@ggui-ai/protocol 0.14.0 → 0.16.0

package/dist/version.js

@@ -6,6 +6,412 @@
  * schema change; the most recent change anchors {@link PROTOCOL_VERSION}.
  *
  * --------------------------------------------------------------------
+ * Theming revision — the overlay is the projection, the host owns runtime
+ * mode (2026-09-10, ggui#987 — **BREAKING on the draft wave**, named by the
+ * conformance kit: `protocol-conformance/src/theme-binding-conformance`
+ * promoted today's pins in the prior commit, and this change fails them —
+ * VERSION-POLICY §1.1; shipped under §1.4's `draft-` clause, §3.5's window
+ * waived pre-v1.0). Founder rulings D1–D7 (2026-09-09/10), joint spec
+ * `docs/superpowers/specs/2026-09-09-theming-revision-protocol-half.md`.
+ * `appThemeSchema` v2: `overlays: { light, dark }` REQUIRED (the derived
+ * projection for both modes — one producer, `@ggui-ai/design`'s
+ * `deriveThemeVariables`), `overlayHash` REQUIRED (`canonicalOverlayHash`,
+ * recomputed at every write door), `mode` optional and a DEFAULT only,
+ * `name` a label; `base` DELETED with the registration tier (D2 = B). The
+ * client projection of `themeMode` flips — `hostAnnounced ?? stamped ??
+ * sessionSidecar` (D4 = A: M1 + M2, "follow the widget") — the server stamp
+ * is unchanged; `themeId` loses its `sidecarName` leg. `AppThemeRefusalBody`
+ * is the one write-door refusal shape. `parseMcpAppAiGguiRenderMeta` gains
+ * `onInvalidTheme` so the read door is never silent. The render shell paints
+ * `--ggui-color-ground` (the surface-layering roles of §2.1).
+ * --------------------------------------------------------------------
+ * Model registry: `openai/gpt-6-astra` (2026-09-09, additive, ggui#977 —
+ * MINOR; Exp 008's founder-ruled second arm, ggui#972). One new `ModelId`
+ * union member and one `MODELS.openai` allowlist entry; premium, active,
+ * not in the lineup; costs 10 / 50 / 12.5 / 1.0 per 1M (input / output /
+ * cache write / cache read), `maxTokens` 922000, tools — every field a
+ * receipt on the issue; `retireNotBefore` unset (none published).
+ * --------------------------------------------------------------------
+ * Refusal registry v11 — the retail plan model retired (2026-09-08,
+ * wire-code, pre-launch, ggui#960 — MINOR on the 0.16.0 draft wave; the
+ * protocol half of the pricing publication ggui#949, WITH cloud's arm
+ * deletion). Founder's ruling: one product, prepaid pay-as-you-go at flat
+ * rates, trial and tiers retired, the welcome credit as the free entry.
+ * Eleven codes lose their emitting arms and retire in the same slice —
+ * render-gate `trial_exhausted`, `trial_expired`, `app_canceled`
+ * (`RENDER_GATE_REFUSAL_CODES` 14 → 11); owner-api `subscription_exists`,
+ * `no_subscription`, `subscription_unchanged`, `portal_unavailable`,
+ * `card_update_unavailable`, `managed_app_no_portal`,
+ * `managed_app_no_card_update`, `managed_app_no_checkout` (9 → 1: the
+ * prepaid wallet's one Stripe surface is the top-up, user-scoped). Four
+ * rows re-described in the new model's words: `billing_path_missing`,
+ * `model_not_allowed` (per-account grant), `checkout_unavailable`
+ * (top-ups), `insufficient_credit` (pool or BYOK). New typed exports
+ * `OWNER_API_REFUSAL_CODES` + `OwnerApiRefusalCode`. Not breaking under
+ * §2: pre-launch draft wave, every retired code had lost its emitter in
+ * the same publication; the kit's non-render-surface case re-aims to the
+ * surviving owner-api code. `managed_default_cap_exceeded` stays (ggui#965).
+ * --------------------------------------------------------------------
+ * Blueprint provenance de-modeled (2026-09-06, wire-tightening, pre-launch,
+ * ggui#924 — MINOR; half of ggui#923, one WITH publication across six
+ * lanes). `LlmBlueprintSource.generator` is the identity `ui-gen-<tier>`
+ * (one tier token — `ui-gen-default` / `ui-gen-advanced` / an operator
+ * tier; `GENERATOR_ID_PATTERN`, `isGeneratorId`) and `model` is the run's route
+ * in the registry's spelling (`ModelRef` = `<prefix>/<model>`, composed only
+ * by `modelRefOfRoute`, recovered by `parseModelRef`; registry `ModelId`s
+ * are the subset — a self-hoster's bedrock/OpenRouter route is a ref the
+ * registry does not list; `MODEL_IDS`, `isModelId` narrow to the subset).
+ * Before: both were `string`, and the identity embedded the model
+ * (`ui-gen-default-haiku-4-5`) — a model retirement (Haiku 4.5,
+ * 2026-10-15) would rename the identity against every stored record.
+ * `parseBlueprintSource` and `llmBlueprintSourceSchema` refuse a modeled
+ * identity and a bare model name; the handshake draft's `generator` hint
+ * and the operator tools' `generator` inputs take the same grammar. No
+ * alias, no dual-read (pre-launch): a row written before the rename reads
+ * as no provenance; stores reseed. Not breaking under VERSION-POLICY §2
+ * (no kit fixture asserts a modeled id or a bare model); MINOR under §1.2
+ * as a schema tightening on the 0.16.0 draft wave. Post-launch this would
+ * be a MAJOR with a migration doc and a dual-read shim — the reason it
+ * ships now.
+ * --------------------------------------------------------------------
+ * Five phantom numeric codes retired-reserved + the emitter census
+ * (2026-09-06, wire-code, pre-launch, ggui#910 — PATCH). `CAPABILITY_DENIED`
+ * (-32005), `GENERATION_QUOTA_EXCEEDED` (-32010), `APP_LIMIT_EXCEEDED`
+ * (-32011), `CONCURRENT_SESSION_LIMIT` (-32012) and the numeric
+ * `CONTRACT_VIOLATION` (-32020 — the census found it once the gate
+ * existed; the live `CONTRACT_VIOLATION` is a string on the channel and
+ * the Plane-3 render error, and tools/call has Plane-2
+ * `contract_violation`) were declared,
+ * SPEC-fenced and mirrored into four tables, and emitted by nothing
+ * first-party — a census by constant and by number over oss/packages,
+ * cloud and backend. The constants leave; the numbers stay reserved
+ * (SPEC §7.9); an unauthorised key is a bare 403 carrying -32007; quota,
+ * app-limit and concurrency states are refusals or implementation-range
+ * codes. Cheap only before launch: after the `draft-` rule flips each
+ * removal would be a MAJOR with a migration doc. The mirrors gate now
+ * also asserts the inverse — every declared non-standard code has a
+ * first-party emitter (one `git grep` per code; seeded self-test) — so a
+ * phantom cannot be declared again silently. Pinned by
+ * `types/__tests__/retired-error-codes.test.ts` (eight retired numbers).
+ * Not breaking under VERSION-POLICY §2; PATCH under §1.3.
+ * --------------------------------------------------------------------
+ *
+ * --------------------------------------------------------------------
+ * `-32013 RATE_LIMIT_EXCEEDED` retired-reserved (2026-09-06, wire-code,
+ * pre-launch, ggui#890 — PATCH). After ggui#886 (the per-app cap denies as
+ * the registry's `app_rate_limited` refusal) and the `RateLimitedError`
+ * deletion, no first-party implementation emits the number: the reference
+ * server refuses in-band, the hosted transport's only 429 is a per-IP
+ * backstop with no JSON-RPC body. The constant leaves
+ * `PLATFORM_ERROR_CODES` and SPEC §7.9's platform fence; the number stays
+ * reserved (the `-32001` / `-32004` convention) so no future canonical code
+ * reuses it. Not breaking under VERSION-POLICY §2 — no kit fixture asserts
+ * it; PATCH under §1.3. Pinned by `types/__tests__/retired-error-codes.test.ts`
+ * (no constant declares a retired number; no tracked source emits one) and
+ * by the mirrors gate, which reds the docs tables' rows until they leave
+ * in the same publication.
+ *
+ * --------------------------------------------------------------------
+ * The registries export their literal-typed rows (2026-09-06, types-only,
+ * pre-launch, ggui#889 — PATCH). `PRE_GENERATION_REFUSAL_CODES` and
+ * `DOMAIN_ERROR_REGISTRY` are the normalized views (`Record<Code, Row>`),
+ * which erase the per-key literal the `const` definers preserve — so a
+ * producer that must satisfy a wire enum from a row had to parse it
+ * through the enum (ggui#886). `PRE_GENERATION_REFUSAL_ROWS` and
+ * `DOMAIN_ERROR_ROWS` are the SAME objects with the literal types kept:
+ * each row's `code` is typed as its own key. No wire change;
+ * the kit's registry-completeness catalog reads the normalized view as
+ * before. Not breaking under VERSION-POLICY §2; PATCH under §1.3.
+ *
+ * --------------------------------------------------------------------
+ * Plane-2 slugs lead the wire text (2026-09-06, wire-text, pre-launch,
+ * ggui#880 — MINOR). SPEC
+ * §7.9 promised "the `code` field on each class is the wire literal"
+ * while the MCP SDK ships every thrown handler error to the agent as
+ * `{content: [{type: 'text', text: error.message}], isError: true}` and
+ * nothing else — executed against the built server: `session_not_found`
+ * and `handshake_not_found` reached neither a field nor the text, and
+ * descriptions, presets and the SPEC taught agents to branch on them.
+ *
+ *   de1. **`DomainError` base** (`errors/domain-error.ts`) — the ONLY
+ *      composer of a Plane-2 error's `message`: `${code}: ${detail}`.
+ *      Refuses an empty detail and a detail that begins with any
+ *      registered domain OR refusal code + `': '`
+ *      (`DomainErrorDetailCollisionError`, a `TypeError` the emitter's
+ *      own suite sees — never the wire); a tool-name prefix is prose.
+ *      `isDomainError` detects by `Symbol.for('ai.ggui.domainError')`
+ *      marker + shape, never `instanceof`; `parseDomainErrorText` is
+ *      the reader side.
+ *   de2. **`DOMAIN_ERROR_CODES` registry** (`types/domain-error-codes.ts`)
+ *      — the CLOSED Plane-2 set, fifteen rows from the executed census,
+ *      each with the data-plane `tools` that emit it, a `recovery` class
+ *      (`retry-same-id` | `re-mint` | `later`), an `emitter` and a
+ *      self-hoster `description`. Pinned disjoint from
+ *      `PRE_GENERATION_REFUSAL_CODES` (one code, one plane). SPEC §7.9's
+ *      Plane-2 table is its mirror (pinned from the registry's own suite):
+ *      the four phantom classes the table listed (`ContractRequiredError`,
+ *      `ContractHashMismatchError`, `UnknownActionToolError`,
+ *      `EventNotAllowedError`) are gone; `cross_reference_unresolved` /
+ *      `contract_schema_invalid` are not wire codes (no caller throws
+ *      them — the lint gate throws `contract_validation_failed`).
+ *   de3. **The two protocol-owned emitters extend the base** —
+ *      `ContractViolationError` (`contract_violation`; `toErrorData()`
+ *      keeps its `{error, tool, violations, hint, propsSchemaHash?}`
+ *      shape) and `ContractValidationError` (`contract_validation_failed`,
+ *      phase + issues kept). Consumers detecting them by `instanceof`
+ *      are unchanged; their message now leads with the slug.
+ *   de4. **The wire plane is the MCP spec's** — a Plane-2 failure is a
+ *      tool RESULT with `isError: true`, never a JSON-RPC error frame;
+ *      no `structuredContent` (the SDK client validates it against the
+ *      tool's `outputSchema` whenever present, so a typed envelope would
+ *      demote every success field to optional — refused). SPEC §7.9.1:
+ *      `SESSION_NOT_FOUND` (-32002) is the live-channel / runtime Plane-1
+ *      code; on `tools/call` the same state is `session_not_found`.
+ *   de5. **The conformance kit's first `tools/call` driver** — catalog
+ *      `domain-error`: six no-setup scenarios (unknown `handshakeId` on
+ *      `ggui_render`; unknown `sessionId` on `ggui_consume` /
+ *      `ggui_get_session` / `ggui_update` / `ggui_amend` / `ggui_emit`)
+ *      graded on the raw result via `runConformance({ toolCallDriver })`
+ *      / `--tool-call-driver <module>`. Before this wave every first-party
+ *      server failed all six on `slug-leads`.
+ *
+ * Conformance-kit verdict: not breaking under VERSION-POLICY §2 — no
+ * prior fixture asserts Plane-2 text; the leading slug is additive to
+ * prose and the new catalog is an addition. MINOR under §1.2 (new
+ * exported base, registry and kit catalog); rides the 0.16.0 wave. The
+ * adoption of the base by the handler / core / mcp-server classes lands
+ * WITH this entry (oss's half of ggui#880); until both are on a server,
+ * that server fails the catalog — which is the point.
+ *
+ * --------------------------------------------------------------------
+ * The pending-event row is a schema (2026-09-06, store-boundary, pre-launch,
+ * ggui#839 — the #817 C2 follower; cite `3f3d86b86`). The consume pipe's
+ * stored row — what `submit_action` / the WS ingress append and
+ * `PendingEventConsumer.consumeAndClear` drains — was a hand-written
+ * interface the adapters typed as `Record<string, unknown>` and the consume
+ * handler coerced with defaults; nothing validated it. A store-boundary
+ * contract (producers ↔ adapters ↔ the consume handler), never wire:
+ * `ggui_consume` returns the entries, never the wrapper.
+ *
+ *   pe1. **`pendingEventSchema` + `PendingEvent` derived** —
+ *      `{ id: string.min(1), envelope: consumeEventEntrySchema, createdAt:
+ *      string }`; `createdAt` stays a string (the relay copies a client
+ *      `firedAt` the ingress accepts as a diagnostic).
+ *   pe2. **`sequence` deleted** — zero writers (both producers append
+ *      `{id, envelope, createdAt}`; sqlite's `seq` never joined the row;
+ *      the pod stores the literal), zero readers (the only read was the
+ *      handler's own default-to-0), named in neither SPEC nor the kit.
+ *   pe3. **`id` required and non-empty** — the drain_ack key and the
+ *      idempotency key per `(sessionId, id)`; the id-less append branches
+ *      (core docstring, in-memory, sqlite, the pod's `ddb.ts`) deleted in
+ *      the same publication.
+ *   pe4. **No string envelope arm** — every writer passes the object; a
+ *      store that serializes the whole row. `parsePendingEnvelope`
+ *      collapsed into the row parse (`envelope-adapters.ts` deleted).
+ *   pe5. **`PendingEventMalformedError` + the per-adapter failure mode** —
+ *      `consumeAndClear` MUST NOT return a row that fails the schema and
+ *      MUST NOT drop a well-formed row because a sibling failed: a
+ *      transactional drain (sqlite) refuses whole and rolls back; a
+ *      destructive drain (DynamoDB) quarantines per row with a
+ *      `pending_event_malformed` structured log; in-memory holds the typed
+ *      struct it validated on append. `append` refuses a malformed row
+ *      before storing it. The consume handler maps the error to a
+ *      `HandlerFailure` carrying `{ events: [], status }`, never a JSON-RPC
+ *      error, and the parse runs before any `drain_ack` fires.
+ *
+ * Conformance-kit verdict: not breaking under VERSION-POLICY §2 — the kit
+ * never names the wrapper (`git grep PendingEvent -- oss/packages/protocol-conformance`
+ * = 0); its only `sequence` is the `action-ack-sequence` fixture's WS ack
+ * `payload.sequence`, the ledger's `appendEvent` seq, never the pipe row's
+ * deleted field. The observable
+ * violation is `@ggui-ai/mcp-server-core`'s published contract-tests suite
+ * (a seeded malformed row is refused or quarantined per form). PATCH-class
+ * under §1.3 for `@ggui-ai/protocol`; rides the 0.16.0 wave.
+ *
+ * --------------------------------------------------------------------
+ * The endpoint-level refusal carries the app as DATA (2026-09-05, wire
+ * field, pre-launch, ggui#870 — the ggui#782 ↔ guuey#708 re-sitting's
+ * D6, guuey#836's blocker). `transportRefusalSchema` — what rides
+ * `error.data.refusal` on a per-app endpoint's typed 403 (ggui#825/#836)
+ * — was strict `{ code, message, fix, retry }` with the app named only
+ * in `message`; a tenant's repair loop cannot parse prose safely.
+ *
+ *   ai1. **`data.refusal.appId: string` — REQUIRED** — the app id the
+ *      refused endpoint serves, equal to the endpoint path's `{appId}`.
+ *      The ggui id the bound caller already holds, never the tenant's
+ *      own `ownerRef`; the tenant maps it to its own id from the
+ *      `gguiAppId` it stored at create. Required, not optional: a field
+ *      a repair loop cannot rely on is a hope, not a contract.
+ *
+ *   ai2. **Who receives the typed face** (the fact from the pod's code,
+ *      ggui#812 identity-first): a correctly bound federated identity
+ *      only — an anonymous request is refused by the auth adapter as
+ *      401 before this arm and learns nothing about the app; a native
+ *      key mismatch gets the bare default-deny 403. SPEC §7.1's
+ *      endpoint paragraph says so now; the anonymous typed face is
+ *      deliberately not a contract (it would trade disclosure).
+ *
+ * Conformance-kit verdict: BREAKING by the letter of VERSION-POLICY §2 —
+ * the kit's `transport-refusal` cases now carry `appId` and the strict
+ * schema refuses a projection without it, so an emitter built against
+ * 0.15.0 fails the 0.16.0 kit — and, the wire being `z.strictObject`, a
+ * 0.15.0 STRICT reader of the body is failed by a 0.16.0 emitter too
+ * (zero such readers exist today; guuey's is step 3, not started). Shipped under §1.4's `draft-` clause in
+ * the 0.16.0 wave; the pod's emitter (cloud, ggui#870's other half)
+ * lands WITH this change, after the tombstone fix for ggui#785/G26.
+ *
+ * Package version — classification MADE here: MAJOR-class change carried
+ * by a MINOR wave under `draft-` (§1.4) for `@ggui-ai/protocol` and
+ * `@ggui-ai/protocol-conformance`. PROTOCOL_VERSION unchanged — no WS
+ * envelope moved.
+ *
+ * --------------------------------------------------------------------
+ * Two refusal codes lose the word "tier" (2026-09-05, rename, pre-launch,
+ * ggui#802 — #786 review finding F6). A code name ships to npm and, for a
+ * render-gate code, reaches every self-hoster's LLM as JSON-Schema enum
+ * metadata on `tools/list`; "tier" names a plan ladder a self-hoster does
+ * not have (docs/principles/oss-purity.md, the type-literal class). Ruled
+ * by a three-lens judge panel under the registry's naming rules:
+ *
+ *   rt1. **`model_not_in_tier` → `model_not_allowed`** (render-gate,
+ *      after-fix, fixBy caller) — the state the row's own description,
+ *      the kit case's `fix` and SPEC §7.9 already name ("not among those
+ *      the app is allowed to use"); subject-first like the rest of the
+ *      registry; true on a deployment with one allow-list per app and no
+ *      prices. Not `model_not_available`: `*_unavailable` is this
+ *      registry's `later` / operator class, the wrong retry class for the
+ *      one code an agent may act on itself.
+ *
+ *   rt2. **`already_on_tier` → `subscription_unchanged`** (owner-api,
+ *      after-fix, fixBy owner) — the owner-api noun the registry already
+ *      uses (`subscription_exists`, `no_subscription`); the state is
+ *      "requested == held", no ladder word.
+ *
+ *   rt3. `tier_unrecognized` is NOT a registry code (deleted from the
+ *      wire at registry v9): a backend allowance state read by the
+ *      console, whose column is literally `tier`. Unchanged.
+ *
+ * Conformance-kit verdict: BREAKING by the letter of VERSION-POLICY §2 —
+ * the kit's `refuse-after-fix-caller` case pinned the old name, so an
+ * emitter built against 0.15.0 fails the 0.16.0 kit's `renderRefusalSchema`
+ * enum. Shipped under §1.4's `draft-` clause (semver describes intent
+ * pre-v1) in the 0.16.0 wave, with the changelog's Unreleased section
+ * naming the move; every mirror moves in one change (the kit case, SPEC,
+ * the docs, the console's copy, the backend's owner-api refusals, the pod's
+ * emitter, cs macros). The registry's purity pin now allows NO code name to
+ * carry plan-tier vocabulary — the grandfather list is gone.
+ *
+ * Package version — classification MADE here: MAJOR-class change carried
+ * by a MINOR wave under `draft-` (§1.4) for `@ggui-ai/protocol` and
+ * `@ggui-ai/protocol-conformance`, pre-1.0 and pre-launch.
+ * PROTOCOL_VERSION unchanged — no WS envelope moved.
+ *
+ * --------------------------------------------------------------------
+ * `UNAUTHORIZED` moves from `-32001` to `-32007` (2026-09-05, renumber,
+ * pre-launch, ggui#853; found by ggui-main in the prod skew-gate log).
+ * `-32001` is the MCP SDK client's own `ErrorCode.RequestTimeout`
+ * (`@modelcontextprotocol/sdk` types.js, beside `ConnectionClosed`
+ * -32000) — minted LOCALLY, never sent by a server — so a client reading
+ * the number could not tell a server's UNAUTHORIZED from its own
+ * timeout: the class ggui#836 closed for -32000, on a number ggui had
+ * chosen long before #836 (0.14.0 and earlier).
+ *
+ *   uc1. **`MCP_ERROR_CODES.UNAUTHORIZED = -32007`** — the next free
+ *      canonical slot per this table's own note; `-32001` joins
+ *      `-32004` as retired-reserved. Every mirror moves in this one
+ *      change (SPEC §7.9 + its table, the gated doc mirrors, the
+ *      endpoint routes' tests, the kit's transport-refusal wording, the
+ *      pod's auth arm, the live journeys). HTTP status and message are
+ *      unchanged: 401/403 + the same text.
+ *
+ *   uc2. **The guard #836 lacked** — `types/error-codes-vs-sdk.test.ts`
+ *      pins every ggui-chosen code (`MCP_ERROR_CODES` minus the five
+ *      JSON-RPC standard codes, plus `PLATFORM_ERROR_CODES`) disjoint
+ *      from every code the SDK's `ErrorCode` enum owns, and ggui's
+ *      copies of the standard five equal to the SDK's. It was RED on
+ *      -32001 before uc1 and is what reds the next collision.
+ *
+ * Conformance-kit verdict: no fixture on 0.15.0 pinned `-32001` (the
+ * transport-refusal catalog grades `-32003 + data.refusal` and `null`;
+ * its prose named -32001 and now names -32007) — a renumbered
+ * canonical code with no kit regression; guuey's clients branch on
+ * -32002/-32006 only (ggui#836 record). Bytes on the wire: one number.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/protocol` and `@ggui-ai/mcp-server` (a canonical code
+ * renumbered, `draft-` intent per VERSION-POLICY §1.4), pre-1.0 and
+ * pre-launch. PROTOCOL_VERSION unchanged — no WS envelope moved.
+ *
+ * --------------------------------------------------------------------
+ * SPEC §7.1's refused arm is ONE primitive (2026-09-05, additive,
+ * pre-launch, ggui#803 leg 9). The tool result a render gate answers a
+ * pre-generation refusal with was built by hand in
+ * `@ggui-ai/mcp-server-handlers` (`buildRenderRefusalText` + an inline
+ * `{ outcome: 'refused', refusal }`), the conformance kit carried its
+ * own reference, and the reference server could not project it at all
+ * — so the reference server was not a reference for the refused
+ * envelope, and a third hand-built copy there would only have re-graded
+ * the kit's reference.
+ *
+ *   rr1. **`projectRenderRefusal(refusal): RenderRefusalResult`** (new
+ *      export, `envelopes/render-refusal.ts`) — `isError: true`,
+ *      `content[0].text` = `<code>: <message> <fix>`, `structuredContent`
+ *      = `{ outcome: 'refused', refusal }` typed as **`RefusedRenderOutput`**
+ *      (`z.infer<typeof refusedOutputSchema>`, new export), no `_meta`.
+ *      Pure and synchronous. The four facts have one source.
+ *
+ *   rr2. **Consumers**: `mcp-server-handlers`' `ggui_render` builds the
+ *      refused result here (its local builder, inline object and
+ *      `RenderRefusedOutput` alias are deleted — no shim); the
+ *      reference server supplies the kit's `refusalProjector` from the
+ *      same primitive at the kit's stringly boundary (a code off
+ *      `RENDER_GATE_REFUSAL_CODES` → `null`; anything else parsed by
+ *      `renderRefusalSchema`), so its six `refusal-envelope/*` rows are
+ *      GRADED, not skipped. The kit's own hand-built reference stays as
+ *      the second source that catches the primitive drifting.
+ *
+ * Conformance-kit verdict: no new kit entry — the six `refusal-envelope`
+ * cases already grade exactly these four facts; what changed is that
+ * two implementations now answer them through one function, and the
+ * reference server's exact-set assertion moved the rows from SKIPPED to
+ * PASSING. Bytes on the wire: unchanged.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/protocol` (two new exports, additive) and for
+ * `@ggui-ai/mcp-server-handlers` (same result, one source), pre-1.0 and
+ * pre-launch. PROTOCOL_VERSION unchanged — no WS envelope moved.
+ *
+ * --------------------------------------------------------------------
+ * Authorization refusals carry JSON-RPC `data` (2026-09-05, additive,
+ * pre-launch, ggui#825). `@ggui-ai/mcp-server`'s per-app `authorize`
+ * hook refuses by throwing, and the route answered every throw with a
+ * bare `403 {code: -32000, message: "Forbidden"}` — correct in effect,
+ * illegible to a client that needs to tell "this app is no longer served" from
+ * "your credential is wrong".
+ *
+ *   ar1. **`ErrorMapperResult.data?: JsonValue`** — a deployment's
+ *      `errorMapper` may attach JSON-RPC 2.0 error `data` (any JSON
+ *      value) to a mapped result; serialized verbatim on `error.data`,
+ *      omitted when absent. Applies to every mapped error, not only
+ *      authorization refusals.
+ *
+ *   ar2. **The per-app authorization refusal consults the mapper**,
+ *      bounded to 401 / 403: a mapper answering any other status, or
+ *      throwing, is ignored and logged (`per_app_authorize_mapper_out_
+ *      of_bounds` / `error_mapper_failed` on the route logger) and the
+ *      default-deny 403 stands byte-identical to a deployment with no
+ *      mapper. The allow path never consults the mapper.
+ *
+ * Conformance-kit verdict: no kit entry required — an optional field on
+ * an operator-side hook result, no MCP tool name/shape touched; the
+ * shape of any `data.refusal` a deployment chooses to attach is that
+ * deployment's declaration, not this package's.
+ *
+ * Package version — classification MADE here: MINOR for
+ * `@ggui-ai/mcp-server` (new optional field on `ErrorMapperResult` +
+ * the authorization refusal path consults `errorMapper`), pre-1.0 and
+ * pre-launch. PROTOCOL_VERSION unchanged — no WS envelope moved.
+ * --------------------------------------------------------------------
  * Authored source rides blueprint reuse (2026-08-14, additive,
  * pre-launch). Cache-reuse renders (a repeated prompt semantic-matches
  * a cached blueprint) previously committed without authored
@@ -3076,6 +3482,19 @@
  *      2026-08-19 out-of-vocabulary enum incident as a permanent
  *      sample).
  *
+ * draft-2026-09-10 — THEMING REVISION (ggui#987 protocol half, ggui#989
+ *      OSS half, ggui#985 cloud half; BREAKING on the draft wave under
+ *      VERSION-POLICY §1.1, shipped under §1.4's `draft-` clause — the
+ *      substantive entry is the "Theming revision" block at the top of
+ *      this changelog). The wire: `appThemeSchema` v2 (`overlays` +
+ *      `overlayHash` required, `base` deleted), the client mode
+ *      projection `hostAnnounced ?? stamped ?? sessionSidecar`, `themeId`
+ *      without its sidecar-name leg, `AppThemeRefusalBody` at every write
+ *      door, `parseMcpAppAiGguiRenderMeta`'s `onInvalidTheme`, the render
+ *      shell on `--ggui-color-ground`. The 0.16.0 lockstep wave carries
+ *      it; the samples, the e2e fixtures and the docs' draft strings move
+ *      in this same commit.
+ *
  * draft-2026-09-04 — PRE-GENERATION REFUSAL ENVELOPE (ggui#786;
  *      BREAKING IN INTENT, pre-launch so no shim and no `@deprecated`
  *      — see `docs/protocol/migrations/2026-09-04-pre-generation-refusal-envelope.md`):
@@ -3121,15 +3540,6 @@
  *      reference and against the shipping projector in
  *      `@ggui-ai/mcp-server-handlers`) and `registry-completeness`
  *      (the registry's structural pins, bound to the LIVE registry).
- *
- * FOLLOWER — moves in the SAME commit as this constant, pinned by a
- * gate that fails loud when it lags: the `protocol` field of every
- * shipped `samples/gguis/<name>/ggui.json` (the `@ggui-ai/project-config`
- * samples test). That pin is a HOUSE rule — shipped samples declare the
- * CURRENT stamp, because a new project starts from them. The CONTRACT
- * for any `ggui.json#protocol` is membership in
- * `CLIENT_SUPPORTED_VERSIONS`, enforced by the loader (`UPGRADE_REQUIRED`
- * on a non-member); the two coincide only while the set is a singleton.
  *   r7. **Tool output shapes are protocol-owned (ggui#817 part C):**
  *      seven schemas — search / featured / validate / consume's
  *      host-context projection / list_sessions' summary / runtime_pull's
@@ -3146,8 +3556,47 @@
  *      grammar and nothing else, so `{}` still reaches the gate per r5); the
  *      full envelope (`renderInputEnvelopeSchema`) parses after the gate.
  *      Bare model ids are out.
+ *   r9. **Endpoint-level refusal (ggui#825):** registry surface
+ *      `mcp-endpoint` (v11) and the transport envelope — a per-app MCP
+ *      endpoint that refuses a request for a registry state answers HTTP
+ *      403 with `{ code: -32000, message: 'Forbidden', data: { refusal } }`
+ *      (`transportRefusalErrorSchema`; `refusal` = the projection without
+ *      the render-only fields, `MCP_ENDPOINT_REFUSAL_CODES` derived — today
+ *      `app_deprovisioned`). Untyped authorization failures keep the bare
+ *      403 by contract. Additive.
+ *   r10. **Consume / list_sessions / emit own their wire shapes (ggui#817
+ *      part C2):** `consumeEventEntrySchema` (the drained row, closed),
+ *      `gguiSessionStatusSchema` (`active` | `expired`), `gguiConsumeOutputSchema`,
+ *      `gguiListSessionsOutputSchema`, `gguiEmitOutputSchema`; the types
+ *      derive (`ConsumeEventEntry`, `GguiConsumeOutput`, `GguiEmitOutput`,
+ *      `GguiListSessionsOutput`, `GguiSessionStatus`). `tools/list` now
+ *      advertises the entry vocabulary and the status enum for
+ *      `ggui_consume`; `parsePendingEnvelope` parsed a drained row instead
+ *      of casting it, so a malformed pipe entry refused at the seam
+ *      (follower: collapsed into `pendingEventSchema`'s row parse, pe4
+ *      above). The wire bytes of a well-formed row are unchanged. Additive.
+ *   r11. **Endpoint refusal codes (ggui#836):** the per-app endpoint speaks
+ *      §7.9 Plane-1 rows — the typed deprovisioned arm is `-32003`
+ *      (`APP_NOT_FOUND`, `App not found`) with `data.refusal`; untyped
+ *      authorization failures are `-32001` (`UNAUTHORIZED`) with no
+ *      `data`; HTTP 403 on both. `-32000` (the SDK client's
+ *      `ConnectionClosed`) is never a code a first-party server chooses.
+ *      Supersedes r9's literals; pre-launch, no compatibility arm.
+ *   r12. **`GENERATION_OVERLOADED: -32014`** joins `PLATFORM_ERROR_CODES` —
+ *      the generation queue is saturated (HTTP 503 + `Retry-After`; the
+ *      server is the limit, unlike `-32013`). Additive; the four complete
+ *      mirrors carry it under `check-error-code-mirrors`.
+ *
+ * FOLLOWER — moves in the SAME commit as this constant, pinned by a
+ * gate that fails loud when it lags: the `protocol` field of every
+ * shipped `samples/gguis/<name>/ggui.json` (the `@ggui-ai/project-config`
+ * samples test). That pin is a HOUSE rule — shipped samples declare the
+ * CURRENT stamp, because a new project starts from them. The CONTRACT
+ * for any `ggui.json#protocol` is membership in
+ * `CLIENT_SUPPORTED_VERSIONS`, enforced by the loader (`UPGRADE_REQUIRED`
+ * on a non-member); the two coincide only while the set is a singleton.
  */
-export const PROTOCOL_VERSION = "draft-2026-09-04";
+export const PROTOCOL_VERSION = "draft-2026-09-10";
 /**
  * The shipped `@ggui-ai/*` WAVE version — bare semver, identical to
  * `package.json#version` on every published package (the lockstep
@@ -3163,8 +3612,32 @@ export const PROTOCOL_VERSION = "draft-2026-09-04";
  * `package.json#version` (the same parity pattern as
  * `STDLIB_GADGETS_VERSION` and `agent-server`'s `CLIENT_INFO`), and the
  * `/release:cut` straggler list names it so the bump is mechanical.
+ *
+ * Wave classifications (protocol seat; the kit is the arbiter,
+ * docs/protocol/VERSION-POLICY.md §1–2):
+ *
+ *   - **0.15.0 — MINOR** (ruled 2026-09-05). Every `@ggui-ai/protocol`
+ *     landing since the 0.14.0 cut (`f3cf6c906`) is additive under
+ *     §1.2: the `@ggui-ai/protocol/wire` browser entry (ggui#819), the
+ *     `GENERATION_OVERLOADED: -32014` canonical code and SPEC §7.9's
+ *     Plane 0 (ggui#840), `ErrorMapperResult.data` (ggui#825), the
+ *     endpoint-level refusal — `403 {code: -32003, data.refusal}` for
+ *     `app_deprovisioned` (ggui#836), the `ggui_consume` /
+ *     `ggui_list_sessions` / `ggui_emit` output schemas (ggui#817 C2),
+ *     and the `.readonly()` removal from the gadget wire schema
+ *     (ggui#824). The one non-additive-looking line — the untyped
+ *     authorization refusal moving from `-32000` to `-32001
+ *     UNAUTHORIZED` (ggui#836) — is not a fixture regression: no
+ *     fixture on 0.14.0 pinned `-32000` (it was the SDK's default
+ *     courtesy code, never a first-party choice; ggui#840's Plane-0
+ *     ruling), and the transport-refusal catalog now states `-32001`.
+ *     §1.4 (`draft-`: semver describes intent) applies on top. A
+ *     0.14.1 is legitimate ONLY as a founder-ruled hotfix branch off
+ *     `f3cf6c906` carrying ggui#846 alone (a declaration-emit fix —
+ *     PATCH under §1.3); it cannot be cut from main, whose delta since
+ *     0.14.0 is minor-class.
  */
-export const GGUI_WAVE_VERSION = "0.14.0";
+export const GGUI_WAVE_VERSION = "0.16.0";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},

package/dist/wire.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@ggui-ai/protocol/wire` — the browser entry (ggui#819).
+ *
+ * What a renderer running inside an iframe validates and types against:
+ * the contract's shapes and their inference, the live-channel frames, the
+ * action envelope, the host-context projection, the reserved-channel
+ * guard, the interface-context snapshot, the invoke event, the permission
+ * grammar and the two limits the runtime shares with the server. Nothing
+ * a SERVER registers or validates — no tool input/output schema, no ops
+ * tool, no LLM route table, no contract zod schema — is reachable from
+ * here at runtime: a bundler cannot drop a module whose top level builds
+ * zod schemas, so the iframe pays for every module its entry reaches
+ * (`wire.test.ts` walks the graph and pins that). The root barrel keeps
+ * every name; this entry is the same names, fewer modules.
+ */
+export * from './types/contract-inference.js';
+export * from './types/data-contract.js';
+export * from './types/live-channel.js';
+export * from './types/render.js';
+export * from './types/invoke.js';
+export * from './types/events.js';
+export * from './types/ggui-session-event.js';
+export * from './types/host-context.js';
+export * from './types/interface-context.js';
+export * from './validation/contract-validator.js';
+export * from './validation/reserved-channels.js';
+export * from './validation/hygiene-rules.js';
+export * from './errors/unknown-permission-name.js';
+export * from './envelopes/builders.js';
+export * from './schemas/invoke.js';
+export * from './schemas/interface-context.js';
+export * from './schemas/runtime-telemetry-limits.js';
+export * from './schemas/public-env-key.js';
+export * from './version.js';
+export * from './schemas/data-contract.js';
+export * from './types/gadget.js';
+export * from './gadgets/stdlib-gadgets.js';
+export * from './gadgets/resolve-contract-gadgets.js';
+export * from './iframe-bridge.js';
+export type { ValidateFunction } from './validation/ajv-runtime.js';
+export type { AppTheme } from './schemas/app-theme.js';
+export type { AppDisplayConfig } from './types/app-config.js';
+export type { EndUserIdentity } from './types/auth.js';
+export type { GguiRuntimePullInput, GguiConsumeOutput, ConsumeEventEntry, GguiEmitOutput, GguiSessionStatus, } from './types/mcp.js';
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,WAAW,CAAC;AAI1B,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AAGnD,cAAc,iBAAiB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/wire.js

@@ -0,0 +1,44 @@
+/**
+ * `@ggui-ai/protocol/wire` — the browser entry (ggui#819).
+ *
+ * What a renderer running inside an iframe validates and types against:
+ * the contract's shapes and their inference, the live-channel frames, the
+ * action envelope, the host-context projection, the reserved-channel
+ * guard, the interface-context snapshot, the invoke event, the permission
+ * grammar and the two limits the runtime shares with the server. Nothing
+ * a SERVER registers or validates — no tool input/output schema, no ops
+ * tool, no LLM route table, no contract zod schema — is reachable from
+ * here at runtime: a bundler cannot drop a module whose top level builds
+ * zod schemas, so the iframe pays for every module its entry reaches
+ * (`wire.test.ts` walks the graph and pins that). The root barrel keeps
+ * every name; this entry is the same names, fewer modules.
+ */
+export * from './types/contract-inference.js';
+export * from './types/data-contract.js';
+export * from './types/live-channel.js';
+export * from './types/render.js';
+export * from './types/invoke.js';
+export * from './types/events.js';
+export * from './types/ggui-session-event.js';
+export * from './types/host-context.js';
+export * from './types/interface-context.js';
+export * from './validation/contract-validator.js';
+export * from './validation/reserved-channels.js';
+export * from './validation/hygiene-rules.js';
+export * from './errors/unknown-permission-name.js';
+export * from './envelopes/builders.js';
+export * from './schemas/invoke.js';
+export * from './schemas/interface-context.js';
+export * from './schemas/runtime-telemetry-limits.js';
+export * from './schemas/public-env-key.js';
+export * from './version.js';
+// The gadget family: the stdlib hooks bundled into the iframe validate a
+// descriptor draft at runtime (`createGguiGadget`), so the contract-schema
+// module comes along — it is what the browser validates there.
+export * from './schemas/data-contract.js';
+export * from './types/gadget.js';
+export * from './gadgets/stdlib-gadgets.js';
+export * from './gadgets/resolve-contract-gadgets.js';
+// The iframe bridge vocabulary (`BRIDGE_EVENTS`) — what the RN WebView bridge
+// and the web runtime agree on; browser data, not a tool schema.
+export * from './iframe-bridge.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "sideEffects": [
     "./dist/schemas/sync-check.js",
     "./dist/validation/ajv-runtime.js"
@@ -78,6 +78,12 @@
       "require": "./dist/integrations/theme-binding.js",
       "default": "./dist/integrations/theme-binding.js"
     },
+    "./wire": {
+      "types": "./dist/wire.d.ts",
+      "import": "./dist/wire.js",
+      "require": "./dist/wire.js",
+      "default": "./dist/wire.js"
+    },
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js",