/** * The Plane-2 registry — the ONLY list of domain-error slugs (ggui#880). * * SPEC §7.9 Plane 2: a recoverable, contract-level failure the caller can * fix — a missing session or handshake, props that do not satisfy the * contract, an undeclared channel. The MCP SDK ships a thrown handler error * to the agent as `{content: [{type: 'text', text: error.message}], * isError: true}` and nothing else, so the slug travels as the LEADING * token of that text — `: ` — composed by the `DomainError` * base in `../errors/domain-error` from a code in this registry. A reader * branches on `text.startsWith(code + ': ')` for a registered code and on * nothing else. * * Same posture as the refusal registry in `./refusal-codes`: `code === key` * is forced at the definer, the code type is derived from the keys, and * the two registries are disjoint (pinned) — one code names one plane. */ /** * How a caller recovers from a Plane-2 failure. * * - `retry-same-id` — fix the input and retry on the SAME handshakeId / * sessionId; nothing was consumed. * - `re-mint` — the id itself is gone (unknown, consumed, expired, * another app's); mint a fresh one (`ggui_handshake`, then `ggui_render`). * - `later` — a dependency the server fetches was unavailable; time * restores it, the input was fine. */ export declare const DOMAIN_ERROR_RECOVERIES: readonly ["retry-same-id", "re-mint", "later"]; /** One member of {@link DOMAIN_ERROR_RECOVERIES}. */ export type DomainErrorRecovery = (typeof DOMAIN_ERROR_RECOVERIES)[number]; /** * A data-plane `tools/call` name a Plane-2 slug may be emitted on. The * template admits any `ggui_*` name at the type level; the registry's own * suite narrows every row's `tools` to the data-plane set (no `ggui_ops_*`, * no `ggui_protocol_*`). */ export type DataPlaneToolName = `ggui_${string}`; /** * The registry with its per-key literal types kept (ggui#889): * `DOMAIN_ERROR_ROWS.session_not_found.code` is `'session_not_found'`, * its `recovery` is `'re-mint'`. {@link DOMAIN_ERROR_REGISTRY} is the * same object read through the normalized row type. */ export declare const DOMAIN_ERROR_ROWS: { readonly session_not_found: { readonly code: "session_not_found"; readonly tools: readonly ["ggui_consume", "ggui_get_session", "ggui_get_render_source", "ggui_update", "ggui_amend", "ggui_emit", "ggui_runtime_pull"]; readonly recovery: "re-mint"; readonly emitter: "the session lookup on every session-scoped tool"; readonly description: "The sessionId names no session this caller can reach — never minted, expired, closed, or owned by another app (cross-app access surfaces uniformly). Re-handshake and re-render to mint a fresh one."; }; readonly handshake_not_found: { readonly code: "handshake_not_found"; readonly tools: readonly ["ggui_render"]; readonly recovery: "re-mint"; readonly emitter: "the handshake-record lookup at ggui_render"; readonly description: "The handshakeId is unknown, already consumed by a render, or expired. Call ggui_handshake again for a fresh id, then render with the new pair."; }; readonly contract_violation: { readonly code: "contract_violation"; readonly tools: readonly ["ggui_render", "ggui_update", "ggui_amend", "ggui_emit"]; readonly recovery: "retry-same-id"; readonly emitter: "the props / payload validator against the contract"; readonly description: "Props or a payload do not satisfy the contract's spec — a missing required prop included. Fix the values and retry with the same id; nothing was consumed."; }; readonly schema_mismatch_error: { readonly code: "schema_mismatch_error"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the schema-compatibility check between the contract and the registered tool shapes"; readonly description: "An actionSpec or streamSpec schema is not a subset of the named tool's registered shape. Adjust the contract or the tool, then retry with the same handshakeId."; }; readonly contract_validation_failed: { readonly code: "contract_validation_failed"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the contract lint gate (shape, retired fields, schema metadata, cross-references, schema compatibility)"; readonly description: "The contract failed the lint gate; the detail names the category and the finding. Fix the contract and retry with the same handshakeId."; }; readonly override_contract_invalid: { readonly code: "override_contract_invalid"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the override gate at ggui_render"; readonly description: "override.contract failed validation — an override commits the caller to a conforming contract. Drop the override and render the suggestion, or fix the draft."; }; readonly channel_not_declared: { readonly code: "channel_not_declared"; readonly tools: readonly ["ggui_emit"]; readonly recovery: "retry-same-id"; readonly emitter: "ggui_emit's channel check against the contract's streamSpec"; readonly description: "The channel is not declared by the session's contract. Emit on a declared channel; the detail lists them."; }; readonly invalid_complete: { readonly code: "invalid_complete"; readonly tools: readonly ["ggui_emit"]; readonly recovery: "retry-same-id"; readonly emitter: "ggui_emit's completion check"; readonly description: "A completion was signalled for a channel that cannot complete in its current state. Emit on the channel first, or omit the completion."; }; readonly gadget_not_registered: { readonly code: "gadget_not_registered"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the gadget gate at ggui_render"; readonly description: "A clientCapabilities.gadgets reference names an export the app's gadget registry does not carry. Drop the reference or fix the name; the detail suggests the nearest match."; }; readonly gadget_package_mismatch: { readonly code: "gadget_package_mismatch"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the gadget gate at ggui_render"; readonly description: "A gadget export is registered, but only under a different package than the contract requested. Request the registered package; the detail names it."; }; readonly gadget_public_env_missing: { readonly code: "gadget_public_env_missing"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the gadget gate at ggui_render"; readonly description: "A registered wrapper requires a public-env key the app has not set. Set the key on the app's public env, then retry."; }; readonly duplicate_gadget_hook: { readonly code: "duplicate_gadget_hook"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the gadget gate at ggui_render"; readonly description: "Two gadget packages export the same name; the generated import would collide. Reference one of them."; }; readonly gadget_types_fetch_failed: { readonly code: "gadget_types_fetch_failed"; readonly tools: readonly ["ggui_render"]; readonly recovery: "later"; readonly emitter: "the gadget type fetch before cold generation"; readonly description: "Fetching a gadget package's types failed; the input was fine. Retry after a short delay."; }; readonly gadget_catalog_integrity: { readonly code: "gadget_catalog_integrity"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the app's gadget catalog resolver at ggui_render"; readonly description: "The app's gadget catalog is inconsistent with its registrations. Repair the catalog, then retry with the same handshakeId."; }; readonly blueprint_rejected: { readonly code: "blueprint_rejected"; readonly tools: readonly ["ggui_render"]; readonly recovery: "retry-same-id"; readonly emitter: "the blueprint registry on registration"; readonly description: "The blueprint was rejected by the registry's error-level findings; the detail lists them. Fix the contract and retry with the same handshakeId."; }; }; /** A domain-error code = a registry key. Derived; never a second list. */ export type DomainErrorCode = keyof typeof DOMAIN_ERROR_ROWS; /** A registry row, as consumers read it. */ export interface DomainErrorRow { readonly code: DomainErrorCode; readonly tools: readonly DataPlaneToolName[]; readonly recovery: DomainErrorRecovery; readonly emitter: string; readonly description: string; } /** The registry consumers read. */ export declare const DOMAIN_ERROR_REGISTRY: Readonly>; /** Whether `value` is a registered domain-error code. */ export declare function isDomainErrorCode(value: string): value is DomainErrorCode; /** Every registered code, in registry order. */ export declare const DOMAIN_ERROR_CODES: readonly DomainErrorCode[]; //# sourceMappingURL=domain-error-codes.d.ts.map