@ggui-ai/protocol 0.12.0 → 0.14.0

package/dist/version.d.ts

@@ -1865,8 +1865,11 @@
  *          now `{stackItemId, updated}`.
  *      Pre-launch no-backcompat: consumers that read any of the dropped
  *      fields off the wire response MUST migrate. Internal telemetry
- *      threading via TS-only `HandshakeOutput` / `PushOutput` /
- *      `UpdateOutput` shapes is preserved for handler-side callers.
+ *      threading via the TS-only `HandshakeOutput` / `PushOutput`
+ *      shapes is preserved for handler-side callers. (`ggui_update`'s
+ *      parallel TS shape is gone as of ggui#798 — the handler's return
+ *      type is `GguiUpdateOutput`, `z.infer` of `updateOutputSchema`,
+ *      so there is nothing left for it to carry beyond the wire.)
  *
  *   u2. **`validatePropsData` is closed-shape (strict mode).** Keys
  *      not declared on `propsSpec.properties` are now rejected with
@@ -3072,8 +3075,79 @@
  *      (drift / hash / profile / authority obligations; pins the
  *      2026-08-19 out-of-vocabulary enum incident as a permanent
  *      sample).
+ *
+ * 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`):
+ *
+ *   r1. **`outcome` on every render result** (SPEC §7.1). A REQUIRED
+ *      discriminant, `'rendered' | 'failed' | 'refused'`. Under
+ *      §1.1 of VERSION-POLICY a required-field addition on an
+ *      envelope is a major-class change; §1.4 waives the migration
+ *      obligation while the version carries the `draft-` prefix, and
+ *      the dated doc above is written anyway. `ggui_update` is
+ *      UNCHANGED — it binds no pre-generation gate and consumes no
+ *      handshake, so a mutation arm is a separate slice.
+ *   r2. **Identity present-iff-committed** — `sessionId`, `action`,
+ *      `contractHash`, `blueprintId`, `variantKey` and `cache` are
+ *      OPTIONAL at the schema level and pinned present on the two
+ *      committed outcomes by a presence refinement. A refusal
+ *      commits nothing, so it carries none of them. The same
+ *      refinement pins `resourceUri` present-iff-`'rendered'` — the
+ *      mount affordance, whose iff its docstring already stated and
+ *      nothing enforced: a `failed` result carrying one advertises a
+ *      mount for a render that does not exist.
+ *   r3. **The refusal envelope** — `refusal: {code, message, fix,
+ *      retry, handshake: 'intact', balanceCentsAtCheck?}`, present
+ *      iff `outcome: 'refused'` and then the ONLY field beside
+ *      `outcome`. Enforced ON THE WIRE: a handler now declares
+ *      `outputEnvelopeSchema` (the composed schema) beside
+ *      `outputSchema` (the raw shape the SDK registers), and the
+ *      transport validates against the former — so the presence
+ *      rules a raw-shape rebuild would drop fail loudly instead.
+ *   r4. **`PRE_GENERATION_REFUSAL_CODES`** — a closed registry, one
+ *      `code` namespace across the render-gate, owner-api and
+ *      provisioning-api surfaces, with `retry` on every row and
+ *      `fixBy` on every `after-fix` row. `refusal.code` is the
+ *      render-gate subset; a code outside it fails the wire enum.
+ *   r5. **Hook contract** — `preValidationGate` RETURNS a refusal
+ *      instead of throwing; the handler owns the envelope and
+ *      projects it before the handler's OWN input parse (after the
+ *      SDK's declared-shape validation, so a wire-malformed call
+ *      never reaches a gate). A gate that throws to refuse is a
+ *      conformance failure, observable in the `tool_invoked` line.
+ *   r6. **Conformance:** two catalogs — `refusal-envelope-conformance`
+ *      (the projection obligation, graded against a kit-local
+ *      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
+ *      page / get_session — registered as `.shape`, types derived and
+ *      wearing `DeepReadonly` at the seam; `ggui_get_session`'s wire is the
+ *      projection (`variant` + six base fields, `contextSnapshot` when the
+ *      row has one), never a `GguiSession` — the alias was a lie the
+ *      strip-parse hid. No `.readonly()` in a wire schema (zod 4 projects
+ *      it as `readOnly`).
+ *   r8. **`infra.model` route grammar (ggui#818):** either wire form —
+ *      canonical `provider:model` or LiteLLM `provider/model`, aliases in
+ *      both — or the handler's route guard fails at zod path `infra.model`
+ *      BEFORE the pre-generation gate (`renderInputRouteGuardSchema`, the
+ *      grammar and nothing else, so `{}` still reaches the gate per r5); the
+ *      full envelope (`renderInputEnvelopeSchema`) parses after the gate.
+ *      Bare model ids are out.
  */
-export declare const PROTOCOL_VERSION = "draft-2026-08-19";
+export declare const PROTOCOL_VERSION = "draft-2026-09-04";
 /**
  * The shipped `@ggui-ai/*` WAVE version — bare semver, identical to
  * `package.json#version` on every published package (the lockstep
@@ -3090,7 +3164,7 @@ export declare const PROTOCOL_VERSION = "draft-2026-08-19";
  * `STDLIB_GADGETS_VERSION` and `agent-server`'s `CLIENT_INFO`), and the
  * `/release:cut` straggler list names it so the bump is mechanical.
  */
-export declare const GGUI_WAVE_VERSION = "0.12.0";
+export declare const GGUI_WAVE_VERSION = "0.14.0";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},
@@ -3111,7 +3185,7 @@ export declare const GGUI_WAVE_VERSION = "0.12.0";
  * consumers can reference schema-versioning specifically without
  * coupling to the broader cache-invalidation constant.
  */
-export declare const PROTOCOL_SCHEMA_VERSION = "draft-2026-08-19";
+export declare const PROTOCOL_SCHEMA_VERSION = "draft-2026-09-04";
 /**
  * Canonical live-channel error code emitted when a peer's declared
  * {@link SubscribePayload.supportedVersions} /

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkgGG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,qBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAErD,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4kGG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,qBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAErD,CAAC"}

package/dist/version.js

@@ -1865,8 +1865,11 @@
  *          now `{stackItemId, updated}`.
  *      Pre-launch no-backcompat: consumers that read any of the dropped
  *      fields off the wire response MUST migrate. Internal telemetry
- *      threading via TS-only `HandshakeOutput` / `PushOutput` /
- *      `UpdateOutput` shapes is preserved for handler-side callers.
+ *      threading via the TS-only `HandshakeOutput` / `PushOutput`
+ *      shapes is preserved for handler-side callers. (`ggui_update`'s
+ *      parallel TS shape is gone as of ggui#798 — the handler's return
+ *      type is `GguiUpdateOutput`, `z.infer` of `updateOutputSchema`,
+ *      so there is nothing left for it to carry beyond the wire.)
  *
  *   u2. **`validatePropsData` is closed-shape (strict mode).** Keys
  *      not declared on `propsSpec.properties` are now rejected with
@@ -3072,8 +3075,79 @@
  *      (drift / hash / profile / authority obligations; pins the
  *      2026-08-19 out-of-vocabulary enum incident as a permanent
  *      sample).
+ *
+ * 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`):
+ *
+ *   r1. **`outcome` on every render result** (SPEC §7.1). A REQUIRED
+ *      discriminant, `'rendered' | 'failed' | 'refused'`. Under
+ *      §1.1 of VERSION-POLICY a required-field addition on an
+ *      envelope is a major-class change; §1.4 waives the migration
+ *      obligation while the version carries the `draft-` prefix, and
+ *      the dated doc above is written anyway. `ggui_update` is
+ *      UNCHANGED — it binds no pre-generation gate and consumes no
+ *      handshake, so a mutation arm is a separate slice.
+ *   r2. **Identity present-iff-committed** — `sessionId`, `action`,
+ *      `contractHash`, `blueprintId`, `variantKey` and `cache` are
+ *      OPTIONAL at the schema level and pinned present on the two
+ *      committed outcomes by a presence refinement. A refusal
+ *      commits nothing, so it carries none of them. The same
+ *      refinement pins `resourceUri` present-iff-`'rendered'` — the
+ *      mount affordance, whose iff its docstring already stated and
+ *      nothing enforced: a `failed` result carrying one advertises a
+ *      mount for a render that does not exist.
+ *   r3. **The refusal envelope** — `refusal: {code, message, fix,
+ *      retry, handshake: 'intact', balanceCentsAtCheck?}`, present
+ *      iff `outcome: 'refused'` and then the ONLY field beside
+ *      `outcome`. Enforced ON THE WIRE: a handler now declares
+ *      `outputEnvelopeSchema` (the composed schema) beside
+ *      `outputSchema` (the raw shape the SDK registers), and the
+ *      transport validates against the former — so the presence
+ *      rules a raw-shape rebuild would drop fail loudly instead.
+ *   r4. **`PRE_GENERATION_REFUSAL_CODES`** — a closed registry, one
+ *      `code` namespace across the render-gate, owner-api and
+ *      provisioning-api surfaces, with `retry` on every row and
+ *      `fixBy` on every `after-fix` row. `refusal.code` is the
+ *      render-gate subset; a code outside it fails the wire enum.
+ *   r5. **Hook contract** — `preValidationGate` RETURNS a refusal
+ *      instead of throwing; the handler owns the envelope and
+ *      projects it before the handler's OWN input parse (after the
+ *      SDK's declared-shape validation, so a wire-malformed call
+ *      never reaches a gate). A gate that throws to refuse is a
+ *      conformance failure, observable in the `tool_invoked` line.
+ *   r6. **Conformance:** two catalogs — `refusal-envelope-conformance`
+ *      (the projection obligation, graded against a kit-local
+ *      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
+ *      page / get_session — registered as `.shape`, types derived and
+ *      wearing `DeepReadonly` at the seam; `ggui_get_session`'s wire is the
+ *      projection (`variant` + six base fields, `contextSnapshot` when the
+ *      row has one), never a `GguiSession` — the alias was a lie the
+ *      strip-parse hid. No `.readonly()` in a wire schema (zod 4 projects
+ *      it as `readOnly`).
+ *   r8. **`infra.model` route grammar (ggui#818):** either wire form —
+ *      canonical `provider:model` or LiteLLM `provider/model`, aliases in
+ *      both — or the handler's route guard fails at zod path `infra.model`
+ *      BEFORE the pre-generation gate (`renderInputRouteGuardSchema`, the
+ *      grammar and nothing else, so `{}` still reaches the gate per r5); the
+ *      full envelope (`renderInputEnvelopeSchema`) parses after the gate.
+ *      Bare model ids are out.
  */
-export const PROTOCOL_VERSION = "draft-2026-08-19";
+export const PROTOCOL_VERSION = "draft-2026-09-04";
 /**
  * The shipped `@ggui-ai/*` WAVE version — bare semver, identical to
  * `package.json#version` on every published package (the lockstep
@@ -3090,7 +3164,7 @@ export const PROTOCOL_VERSION = "draft-2026-08-19";
  * `STDLIB_GADGETS_VERSION` and `agent-server`'s `CLIENT_INFO`), and the
  * `/release:cut` straggler list names it so the bump is mechanical.
  */
-export const GGUI_WAVE_VERSION = "0.12.0";
+export const GGUI_WAVE_VERSION = "0.14.0";
 /**
  * Schema version stamped onto wire envelopes that opt into the
  * `schemaVersion` forward-compat field (see {@link ActionEnvelope},

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@ggui-ai/protocol",
-  "version": "0.12.0",
+  "version": "0.14.0",
+  "sideEffects": [
+    "./dist/schemas/sync-check.js",
+    "./dist/validation/ajv-runtime.js"
+  ],
   "description": "ggui protocol types — events, renders, WebSocket, MCP, LLM models",
   "license": "Apache-2.0",
   "keywords": [
@@ -112,11 +116,11 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "rm -rf dist && tsc && node ../scripts/fix-esm-imports.mjs dist",
+    "build": "rm -rf dist.staging-$$ && tsc --outDir dist.staging-$$ && node ../scripts/fix-esm-imports.mjs dist.staging-$$ && node ../scripts/atomic-swap.mjs dist.staging-$$ dist",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "sync-check": "tsx src/schemas/sync-check.ts",