@ggui-ai/protocol 0.2.0-alpha.3 → 0.3.0-rc.0

package/dist/validation/lint-contract.js

@@ -5,7 +5,7 @@
  *
  *   - {@link validateContract} — strict; runs phased validation and
  *     throws {@link ContractValidationError} on the FIRST phase that
- *     produces errors. Used at every protocol boundary (push handler,
+ *     produces errors. Used at every protocol boundary (render handler,
  *     blueprint registration, future synth output gate).
  *
  *   - {@link lintContract} — graded; runs ALL phases unconditionally
@@ -17,9 +17,11 @@
  *
  *   ```
  *   phase 1: shape          (zod wire-shape validation)
- *   phase 2: references     (CTR_REF_*, CTR_DUP_NAME, CTR_RESERVED_NAME)
- *   phase 3: schema compat  (CTR_SCHEMA_INCOMPAT)
- *   phase 4: hygiene        (LINT_*  — graded, warnings only today)
+ *   phase 2: retired        (CTR_RETIRED_FIELD — dead top-level fields)
+ *   phase 3: schema-meta    (CTR_SCHEMA_META_INVALID — Ajv strict on inner schemas)
+ *   phase 4: references     (CTR_REF_*, CTR_DUP_NAME, CTR_RESERVED_NAME)
+ *   phase 5: schema compat  (CTR_SCHEMA_INCOMPAT)
+ *   phase 6: hygiene        (LINT_*  — graded, warnings only)
  *   ```
  *
  * Errors are reported one phase at a time during strict validation so
@@ -32,7 +34,8 @@ import { dataContractSchema } from '../schemas/data-contract.js';
 import { checkCrossReferences, } from './cross-references.js';
 import { checkNameInvariants, } from './name-invariants.js';
 import { checkSchemaCompat, } from './schema-compat-invariants.js';
-import { checkHygiene } from './hygiene-rules.js';
+import { checkContractSchemasValid } from './schema-meta-validation.js';
+import { checkHygiene, checkRetiredContractFields, } from './hygiene-rules.js';
 /**
  * Strict-mode failure. Carries the offending phase + every issue
  * the failing phase produced so error renderers can show every fix
@@ -60,8 +63,8 @@ export class ContractValidationError extends Error {
 function phaseShape(contract) {
     const parsed = dataContractSchema.safeParse(contract);
     if (parsed.success)
-        return [];
-    return zodErrorToIssues(parsed.error);
+        return { issues: [], parsed: parsed.data };
+    return { issues: zodErrorToIssues(parsed.error), parsed: null };
 }
 function zodErrorToIssues(error) {
     return error.issues.map((issue) => ({
@@ -89,6 +92,52 @@ function zodIssueCode(zodCode) {
     }
 }
 // =============================================================================
+// Phase — retired fields (CTR_RETIRED_FIELD)
+// =============================================================================
+/**
+ * Retired top-level field carriers (`wiredTools`, `libraries`,
+ * `dispatch`, …) are a fatal contract bug: the field rides through the
+ * `.passthrough()` schema but names dead protocol surface. Promoted
+ * from a hygiene WARNING to an ERROR so it routes through the same gate
+ * as every other contract error — the handshake repair loop remaps it
+ * (an LLM correctly re-nests `wiredTools` → `agentCapabilities.tools`),
+ * and `ggui_render`'s override path rejects it. Shares the one detector
+ * (`checkRetiredContractFields`) with the author-time surface + the
+ * render-gate assert, so the retired vocabulary can't drift across sites.
+ */
+function phaseRetired(contract) {
+    return checkRetiredContractFields(contract).map((w) => ({
+        code: 'CTR_RETIRED_FIELD',
+        severity: 'error',
+        phase: 'retired',
+        path: w.path,
+        message: w.message,
+        ...(w.fixHint !== undefined ? { fixHint: w.fixHint } : {}),
+    }));
+}
+// =============================================================================
+// Phase — schema-meta (CTR_SCHEMA_META_INVALID, Ajv strict meta-validation)
+// =============================================================================
+/**
+ * Inner JSON Schema meta-validation — each `schema:` field must compile
+ * under Ajv strict mode. Distinct from phase-1 shape: zod validates the
+ * WRAPPER shape, but the wrapped JSON Schema rides through
+ * `.passthrough()` unvalidated. Runs before references / schema-compat,
+ * which read these schemas. This is the check the render/handshake assert
+ * set had that `validateContract` was previously missing — folding it in
+ * here is what makes the strict gate complete (and therefore safe to use
+ * as the single boundary gate).
+ */
+function phaseSchemaMeta(contract) {
+    return checkContractSchemasValid(contract).map((v) => ({
+        code: 'CTR_SCHEMA_META_INVALID',
+        severity: 'error',
+        phase: 'schema-meta',
+        path: v.field,
+        message: v.message,
+    }));
+}
+// =============================================================================
 // Phase 2 — references (CTR_REF_*, CTR_DUP_NAME, CTR_RESERVED_NAME)
 // =============================================================================
 function phaseReferences(contract) {
@@ -171,18 +220,29 @@ function hygieneWarningToIssue(w) {
  * gate. Use {@link lintContract} when warnings matter.
  */
 export function validateContract(contract) {
-    const shapeIssues = phaseShape(contract);
-    if (shapeIssues.length > 0) {
-        throw new ContractValidationError('shape', shapeIssues);
+    const shape = phaseShape(contract);
+    if (shape.issues.length > 0) {
+        throw new ContractValidationError('shape', shape.issues);
+    }
+    // Shape passed ⇒ a parsed DataContract is available for the deeper,
+    // type-dependent phases. The null check narrows `c` to DataContract
+    // without a cast (unreachable: no shape issues ⇒ parsed present).
+    const c = shape.parsed;
+    if (c === null)
+        return;
+    const retiredIssues = phaseRetired(c);
+    if (retiredIssues.length > 0) {
+        throw new ContractValidationError('retired', retiredIssues);
+    }
+    const schemaMetaIssues = phaseSchemaMeta(c);
+    if (schemaMetaIssues.length > 0) {
+        throw new ContractValidationError('schema-meta', schemaMetaIssues);
     }
-    // After phase 1 we know the contract structurally parses; safe to
-    // cast through into the phase-2 / phase-3 helpers (they accept
-    // `DataContract` directly).
-    const refIssues = phaseReferences(contract);
+    const refIssues = phaseReferences(c);
     if (refIssues.length > 0) {
         throw new ContractValidationError('references', refIssues);
     }
-    const compatIssues = phaseSchemaCompat(contract);
+    const compatIssues = phaseSchemaCompat(c);
     if (compatIssues.length > 0) {
         throw new ContractValidationError('schema-compat', compatIssues);
     }
@@ -201,18 +261,21 @@ export function validateContract(contract) {
  */
 export function lintContract(contract) {
     const issues = [];
-    issues.push(...phaseShape(contract));
-    // Phase 2 + 3 produce shape-dependent errors. When the shape
-    // phase already failed, the contract may not match the type
-    // signatures these phases assume — skip downstream phases in that
-    // case to avoid throwing during the lint run. Authoring tools see
-    // "fix shape first" via the shape issues; once those are clean
-    // the next `lintContract` run reaches the deeper phases.
-    if (issues.length === 0) {
-        issues.push(...phaseReferences(contract));
-        issues.push(...phaseSchemaCompat(contract));
+    const shape = phaseShape(contract);
+    issues.push(...shape.issues);
+    // Phases beyond shape are shape-dependent and need a parsed
+    // DataContract. When shape failed, skip them (the contract may not
+    // match the type signatures these phases assume); authoring tools see
+    // "fix shape first" via the shape issues, and the next run reaches the
+    // deeper phases once shape is clean.
+    if (shape.issues.length === 0 && shape.parsed !== null) {
+        const c = shape.parsed;
+        issues.push(...phaseRetired(c));
+        issues.push(...phaseSchemaMeta(c));
+        issues.push(...phaseReferences(c));
+        issues.push(...phaseSchemaCompat(c));
+        issues.push(...phaseHygiene(c));
     }
-    issues.push(...phaseHygiene(contract));
     const errors = [];
     const warnings = [];
     for (const issue of issues) {

package/dist/validation/name-invariants.d.ts

@@ -41,7 +41,7 @@ import type { ContractViolation } from './contract-validator';
  * Stable error code for collisions across the three inbound spec maps
  * (`actionSpec` / `streamSpec` / `contextSpec`). The boilerplate
  * generator emits identifiers from these keys; a collision is an
- * author bug that the protocol catches at push.
+ * author bug that the protocol catches at render.
  */
 export declare const CTR_DUP_NAME = "CTR_DUP_NAME";
 /**
@@ -72,7 +72,7 @@ export declare function checkNameCollisions(contract: DataContract): NameInvaria
  * Validate that no `actionSpec` or `contextSpec` key uses the
  * `_ggui:` reserved namespace. `streamSpec` reserved-channel rejection
  * lives in `validateContractStructure` (the reserved namespace there
- * carries server-side semantics like the `_ggui:contract-error`
+ * carries server-side semantics like the `_ggui:lifecycle`
  * channel); this invariant extends the rule uniformly across the
  * other two inbound spec maps.
  *
@@ -93,7 +93,7 @@ export declare function checkNameInvariants(contract: DataContract): NameInvaria
 /**
  * Throwable form of {@link checkNameInvariants}. Use at protocol
  * boundaries where a name collision or reserved-namespace use is a
- * contract bug the caller must fix (push handler, blueprint
+ * contract bug the caller must fix (render handler, blueprint
  * registration).
  *
  * Carries the full violation list so error renderers can show every
@@ -108,7 +108,7 @@ export declare class NameInvariantError extends Error {
  * Throw-on-violation wrapper around {@link checkNameInvariants}.
  * No-op when the contract's names are consistent.
  *
- * Designed to slot alongside `assertCrossReferences` at push time:
+ * Designed to slot alongside `assertCrossReferences` at render time:
  * cross-reference invariants catch dangling pointers between specs;
  * name invariants catch malformed name spaces within specs. Both
  * surface author-recoverable failures before any state mutation.

package/dist/validation/name-invariants.js

@@ -40,7 +40,7 @@ import { RESERVED_CHANNEL_PREFIX, isReservedChannelName, } from './reserved-chan
  * Stable error code for collisions across the three inbound spec maps
  * (`actionSpec` / `streamSpec` / `contextSpec`). The boilerplate
  * generator emits identifiers from these keys; a collision is an
- * author bug that the protocol catches at push.
+ * author bug that the protocol catches at render.
  */
 export const CTR_DUP_NAME = 'CTR_DUP_NAME';
 /**
@@ -95,7 +95,7 @@ export function checkNameCollisions(contract) {
  * Validate that no `actionSpec` or `contextSpec` key uses the
  * `_ggui:` reserved namespace. `streamSpec` reserved-channel rejection
  * lives in `validateContractStructure` (the reserved namespace there
- * carries server-side semantics like the `_ggui:contract-error`
+ * carries server-side semantics like the `_ggui:lifecycle`
  * channel); this invariant extends the rule uniformly across the
  * other two inbound spec maps.
  *
@@ -137,7 +137,7 @@ export function checkNameInvariants(contract) {
 /**
  * Throwable form of {@link checkNameInvariants}. Use at protocol
  * boundaries where a name collision or reserved-namespace use is a
- * contract bug the caller must fix (push handler, blueprint
+ * contract bug the caller must fix (render handler, blueprint
  * registration).
  *
  * Carries the full violation list so error renderers can show every
@@ -159,7 +159,7 @@ export class NameInvariantError extends Error {
  * Throw-on-violation wrapper around {@link checkNameInvariants}.
  * No-op when the contract's names are consistent.
  *
- * Designed to slot alongside `assertCrossReferences` at push time:
+ * Designed to slot alongside `assertCrossReferences` at render time:
  * cross-reference invariants catch dangling pointers between specs;
  * name invariants catch malformed name spaces within specs. Both
  * surface author-recoverable failures before any state mutation.

package/dist/validation/reserved-channels.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Reserved channel namespace for server-emitted streams on the live channel.
+ *
+ * Agents may NOT declare channels whose names start with `_ggui:` in
+ * their `streamSpec`. The namespace is reserved for system
+ * channels the server emits directly — bypassing the agent's declared
+ * streamSpec because these channels are not part of the agent-authored
+ * contract.
+ *
+ * Concrete reservations today:
+ *
+ *   - {@link PREVIEW_CHANNEL} — provisional A2UI assembly stream
+ *     emitted during fresh-gen `ggui_render` flows. The integration
+ *     surface (A2UI message types, catalog, validators) lives in the
+ *     dedicated boundary package `@ggui-ai/preview-a2ui`; this module
+ *     owns only the protocol-level naming rule so `@ggui-ai/protocol`
+ *     stays free of A2UI-shaped types. Payload validation for this
+ *     channel is delivered via the INJECTION pattern documented on
+ *     {@link BUILTIN_RESERVED_VALIDATORS} — the server composes the
+ *     A2UI validator into `validateStreamData`'s
+ *     `extraReservedValidators` parameter.
+ *   - {@link LIFECYCLE_CHANNEL} — generation-progress lifecycle
+ *     envelopes the server emits for session-wide subscribers.
+ *     Payload is a PROTOCOL-OWNED shape, so the structural validator
+ *     ships inside this module as a built-in (see
+ *     {@link validateGguiLifecyclePayload} +
+ *     {@link BUILTIN_RESERVED_VALIDATORS}).
+ *
+ * Why here and not in `types/live-channel.ts`: `live-channel.ts` describes
+ * WIRE envelope shapes (`StreamEnvelope`, `SubscribePayload`). This
+ * file describes a NAMING POLICY that the contract-structure validator
+ * enforces. Separate concerns — easier to audit the boundary.
+ */
 import type { ValidationResult } from './contract-validator';
 /** Prefix that marks a channel as server-owned (reserved from agents). */
 export declare const RESERVED_CHANNEL_PREFIX = "_ggui:";
@@ -9,27 +42,14 @@ export declare const RESERVED_CHANNEL_PREFIX = "_ggui:";
  */
 export declare const PREVIEW_CHANNEL = "_ggui:preview";
 /**
- * Reserved channel for canonical contract-error envelopes emitted by
- * the wiredActionRouter. Body shape is `ContractErrorPayload` (see
- * `types/data-contract.ts`). Agent-authored `streamSpec`
- * MUST NOT declare this channel — structural validation rejects it
- * alongside every other reserved-prefix name.
+ * Reserved channel for generation-progress lifecycle envelopes —
+ * handshake / render / consume lifecycle signals that drive
+ * client-side progress indicators.
  *
- * If future work adds richer contract observability (e.g., separate
- * `_ggui:wired-tool-invoked` success trace), each new name joins this
- * module with its own constant and the {@link KNOWN_RESERVED_CHANNELS}
- * set below.
- */
-export declare const CONTRACT_ERROR_CHANNEL = "_ggui:contract-error";
-/**
- * Reserved channel for canvas-mode session
- * lifecycle envelopes — handshake / push / consume lifecycle signals
- * that drive the ggui-animator's state machine.
- *
- * Body shape: `CanvasLifecyclePayload` (discriminated on `kind`). The
- * server emits; canvas iframes (subscribed session-wide) consume.
- * Inline iframes (pinned to a single stack item) do not receive
- * envelopes on this channel — delivery is gated by subscription scope.
+ * Body shape: `GguiLifecyclePayload` (discriminated on `kind`). The
+ * server emits; session-wide subscribers consume. Iframes pinned to a
+ * single GguiSession do not receive envelopes on this channel —
+ * delivery is gated by subscription scope.
  *
  * Agent-authored `streamSpec` MUST NOT declare this channel; the
  * structural validator rejects it alongside every other reserved-
@@ -80,7 +100,7 @@ export declare function isKnownReservedChannel(name: string): boolean;
  *
  *   1. `BUILTIN_RESERVED_VALIDATORS` — the PROTOCOL-OWNED payloads.
  *      Shipped in `@ggui-ai/protocol` because the protocol defines the
- *      shape (`ContractErrorPayload` is authored here; the validator
+ *      shape (`GguiLifecyclePayload` is authored here; the validator
  *      belongs here too). Always active, no composition needed.
  *   2. `extraReservedValidators` — INJECTION POINT for payloads whose
  *      shape the protocol does NOT own. Primary consumer today:
@@ -98,29 +118,6 @@ export declare function isKnownReservedChannel(name: string): boolean;
  * composition time.
  */
 export type ReservedChannelValidator = (payload: unknown) => ValidationResult;
-/**
- * Structural validator for {@link ContractErrorPayload} — the body the
- * server emits on `_ggui:contract-error`. PROTOCOL-OWNED shape; ships
- * as a built-in (see {@link BUILTIN_RESERVED_VALIDATORS}).
- *
- * Semantics:
- *   - Payload MUST be a non-null object (arrays rejected).
- *   - Required fields: `toolName: string`, `error.code: string`,
- *     `error.message: string`, `timestamp: string`.
- *   - Optional fields: `actionName: string`, `sourceAction: {type:
- *     string, dispatchedAt: string}`, `error.causedBy: string`,
- *     `schemaVersion: string`.
- *   - `error.code` accepts ANY string — the {@link ContractErrorCode}
- *     type is extensibly-closed per Item 2 (`(string & {})` branch),
- *     so forward-compat codes like `BOOTSTRAP_FAILED` /
- *     `RATE_LIMIT_EXCEEDED` MUST NOT be rejected at this layer.
- *   - `sourceAction.type` accepts ANY string — per F6 extensibility
- *     (`'wired-action' | 'refresh-stream' | (string & {})`).
- *
- * Returns `{valid: true, violations: []}` on conformance. Reject sets
- * `valid: false` with one violation per missing-or-mistyped field.
- */
-export declare function validateContractErrorPayload(payload: unknown): ValidationResult;
 /**
  * The PROTOCOL-OWNED reserved-channel validator registry.
  *
@@ -142,7 +139,7 @@ export declare const BUILTIN_RESERVED_VALIDATORS: ReadonlyMap<string, ReservedCh
 /**
  * Structural validator for {@link LIFECYCLE_CHANNEL} payloads. The
  * wire shape is the closed discriminated union
- * {@link CanvasLifecyclePayload}; we narrow on `kind` and check the
+ * {@link GguiLifecyclePayload}; we narrow on `kind` and check the
  * required fields per variant. Defines the failure mode the protocol
  * bar requires for reserved channels.
  *
@@ -152,5 +149,5 @@ export declare const BUILTIN_RESERVED_VALIDATORS: ReadonlyMap<string, ReservedCh
  *   - unknown `kind` values (closed union — new kinds bump protocol)
  *   - missing or wrong-typed variant-specific fields
  */
-export declare function validateCanvasLifecyclePayload(payload: unknown): ValidationResult;
+export declare function validateGguiLifecyclePayload(payload: unknown): ValidationResult;
 //# sourceMappingURL=reserved-channels.d.ts.map

package/dist/validation/reserved-channels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reserved-channels.d.ts","sourceRoot":"","sources":["../../src/validation/reserved-channels.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAItD,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,gBAAgB,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,gBAAgB,CAuIlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,MAAM,EACN,wBAAwB,CAKxB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,OAAO,GACf,gBAAgB,CA4FlB"}
+{"version":3,"file":"reserved-channels.d.ts","sourceRoot":"","sources":["../../src/validation/reserved-channels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAGtD,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,OAAO,KACb,gBAAgB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,MAAM,EACN,wBAAwB,CAIxB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,GACf,gBAAgB,CA4FlB"}

package/dist/validation/reserved-channels.js

@@ -1,3 +1,4 @@
+import { isRecord } from './is-record.js';
 /** Prefix that marks a channel as server-owned (reserved from agents). */
 export const RESERVED_CHANNEL_PREFIX = '_ggui:';
 /**
@@ -8,27 +9,14 @@ export const RESERVED_CHANNEL_PREFIX = '_ggui:';
  */
 export const PREVIEW_CHANNEL = '_ggui:preview';
 /**
- * Reserved channel for canonical contract-error envelopes emitted by
- * the wiredActionRouter. Body shape is `ContractErrorPayload` (see
- * `types/data-contract.ts`). Agent-authored `streamSpec`
- * MUST NOT declare this channel — structural validation rejects it
- * alongside every other reserved-prefix name.
+ * Reserved channel for generation-progress lifecycle envelopes —
+ * handshake / render / consume lifecycle signals that drive
+ * client-side progress indicators.
  *
- * If future work adds richer contract observability (e.g., separate
- * `_ggui:wired-tool-invoked` success trace), each new name joins this
- * module with its own constant and the {@link KNOWN_RESERVED_CHANNELS}
- * set below.
- */
-export const CONTRACT_ERROR_CHANNEL = '_ggui:contract-error';
-/**
- * Reserved channel for canvas-mode session
- * lifecycle envelopes — handshake / push / consume lifecycle signals
- * that drive the ggui-animator's state machine.
- *
- * Body shape: `CanvasLifecyclePayload` (discriminated on `kind`). The
- * server emits; canvas iframes (subscribed session-wide) consume.
- * Inline iframes (pinned to a single stack item) do not receive
- * envelopes on this channel — delivery is gated by subscription scope.
+ * Body shape: `GguiLifecyclePayload` (discriminated on `kind`). The
+ * server emits; session-wide subscribers consume. Iframes pinned to a
+ * single GguiSession do not receive envelopes on this channel —
+ * delivery is gated by subscription scope.
  *
  * Agent-authored `streamSpec` MUST NOT declare this channel; the
  * structural validator rejects it alongside every other reserved-
@@ -51,7 +39,6 @@ export const LIFECYCLE_CHANNEL = '_ggui:lifecycle';
  */
 export const KNOWN_RESERVED_CHANNELS = new Set([
     PREVIEW_CHANNEL,
-    CONTRACT_ERROR_CHANNEL,
     LIFECYCLE_CHANNEL,
 ]);
 /**
@@ -79,155 +66,6 @@ export function isReservedChannelName(name) {
 export function isKnownReservedChannel(name) {
     return KNOWN_RESERVED_CHANNELS.has(name);
 }
-/**
- * Structural validator for {@link ContractErrorPayload} — the body the
- * server emits on `_ggui:contract-error`. PROTOCOL-OWNED shape; ships
- * as a built-in (see {@link BUILTIN_RESERVED_VALIDATORS}).
- *
- * Semantics:
- *   - Payload MUST be a non-null object (arrays rejected).
- *   - Required fields: `toolName: string`, `error.code: string`,
- *     `error.message: string`, `timestamp: string`.
- *   - Optional fields: `actionName: string`, `sourceAction: {type:
- *     string, dispatchedAt: string}`, `error.causedBy: string`,
- *     `schemaVersion: string`.
- *   - `error.code` accepts ANY string — the {@link ContractErrorCode}
- *     type is extensibly-closed per Item 2 (`(string & {})` branch),
- *     so forward-compat codes like `BOOTSTRAP_FAILED` /
- *     `RATE_LIMIT_EXCEEDED` MUST NOT be rejected at this layer.
- *   - `sourceAction.type` accepts ANY string — per F6 extensibility
- *     (`'wired-action' | 'refresh-stream' | (string & {})`).
- *
- * Returns `{valid: true, violations: []}` on conformance. Reject sets
- * `valid: false` with one violation per missing-or-mistyped field.
- */
-export function validateContractErrorPayload(payload) {
-    const violations = [];
-    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
-        return {
-            valid: false,
-            violations: [
-                {
-                    field: 'payload',
-                    message: `${CONTRACT_ERROR_CHANNEL} payload must be a non-null object`,
-                    expected: 'object',
-                    received: payload === null ? 'null' : Array.isArray(payload) ? 'array' : typeof payload,
-                },
-            ],
-        };
-    }
-    const p = payload;
-    // ── Required: toolName ──
-    if (typeof p.toolName !== 'string') {
-        violations.push({
-            field: 'toolName',
-            message: "Required field 'toolName' must be a string",
-            expected: 'string',
-            received: p.toolName === undefined ? 'undefined' : typeof p.toolName,
-        });
-    }
-    // ── Optional: actionName ──
-    if (p.actionName !== undefined && typeof p.actionName !== 'string') {
-        violations.push({
-            field: 'actionName',
-            message: "Optional field 'actionName' must be a string when present",
-            expected: 'string',
-            received: typeof p.actionName,
-        });
-    }
-    // ── Optional: sourceAction ──
-    if (p.sourceAction !== undefined) {
-        if (typeof p.sourceAction !== 'object' ||
-            p.sourceAction === null ||
-            Array.isArray(p.sourceAction)) {
-            violations.push({
-                field: 'sourceAction',
-                message: "Optional field 'sourceAction' must be an object when present",
-                expected: 'object',
-                received: p.sourceAction === null ? 'null' : Array.isArray(p.sourceAction) ? 'array' : typeof p.sourceAction,
-            });
-        }
-        else {
-            const sa = p.sourceAction;
-            if (typeof sa.type !== 'string') {
-                // Accepts any string — extensibility per F6. Type presence is
-                // required, VALUE is open.
-                violations.push({
-                    field: 'sourceAction.type',
-                    message: "Field 'sourceAction.type' must be a string",
-                    expected: 'string',
-                    received: sa.type === undefined ? 'undefined' : typeof sa.type,
-                });
-            }
-            if (typeof sa.dispatchedAt !== 'string') {
-                violations.push({
-                    field: 'sourceAction.dispatchedAt',
-                    message: "Field 'sourceAction.dispatchedAt' must be a string (ISO 8601)",
-                    expected: 'string',
-                    received: sa.dispatchedAt === undefined ? 'undefined' : typeof sa.dispatchedAt,
-                });
-            }
-        }
-    }
-    // ── Required: error.code + error.message ──
-    if (typeof p.error !== 'object' || p.error === null || Array.isArray(p.error)) {
-        violations.push({
-            field: 'error',
-            message: "Required field 'error' must be a non-null object",
-            expected: 'object',
-            received: p.error === undefined ? 'undefined' : p.error === null ? 'null' : Array.isArray(p.error) ? 'array' : typeof p.error,
-        });
-    }
-    else {
-        const err = p.error;
-        if (typeof err.code !== 'string') {
-            // Accepts any string — ContractErrorCode is extensibly-closed per
-            // Item 2. Rejecting by name-set here would force a version bump
-            // every time a new code ships.
-            violations.push({
-                field: 'error.code',
-                message: "Required field 'error.code' must be a string",
-                expected: 'string',
-                received: err.code === undefined ? 'undefined' : typeof err.code,
-            });
-        }
-        if (typeof err.message !== 'string') {
-            violations.push({
-                field: 'error.message',
-                message: "Required field 'error.message' must be a string",
-                expected: 'string',
-                received: err.message === undefined ? 'undefined' : typeof err.message,
-            });
-        }
-        if (err.causedBy !== undefined && typeof err.causedBy !== 'string') {
-            violations.push({
-                field: 'error.causedBy',
-                message: "Optional field 'error.causedBy' must be a string when present",
-                expected: 'string',
-                received: typeof err.causedBy,
-            });
-        }
-    }
-    // ── Required: timestamp ──
-    if (typeof p.timestamp !== 'string') {
-        violations.push({
-            field: 'timestamp',
-            message: "Required field 'timestamp' must be a string (ISO 8601)",
-            expected: 'string',
-            received: p.timestamp === undefined ? 'undefined' : typeof p.timestamp,
-        });
-    }
-    // ── Optional: schemaVersion ──
-    if (p.schemaVersion !== undefined && typeof p.schemaVersion !== 'string') {
-        violations.push({
-            field: 'schemaVersion',
-            message: "Optional field 'schemaVersion' must be a string when present",
-            expected: 'string',
-            received: typeof p.schemaVersion,
-        });
-    }
-    return { valid: violations.length === 0, violations };
-}
 /**
  * The PROTOCOL-OWNED reserved-channel validator registry.
  *
@@ -246,14 +84,13 @@ export function validateContractErrorPayload(payload) {
  * Readonly `ReadonlyMap` so consumers can't mutate the global registry.
  */
 export const BUILTIN_RESERVED_VALIDATORS = new Map([
-    [CONTRACT_ERROR_CHANNEL, validateContractErrorPayload],
-    [LIFECYCLE_CHANNEL, validateCanvasLifecyclePayload],
+    [LIFECYCLE_CHANNEL, validateGguiLifecyclePayload],
     // PREVIEW_CHANNEL intentionally absent — injected at composition time.
 ]);
 /**
  * Structural validator for {@link LIFECYCLE_CHANNEL} payloads. The
  * wire shape is the closed discriminated union
- * {@link CanvasLifecyclePayload}; we narrow on `kind` and check the
+ * {@link GguiLifecyclePayload}; we narrow on `kind` and check the
  * required fields per variant. Defines the failure mode the protocol
  * bar requires for reserved channels.
  *
@@ -263,9 +100,9 @@ export const BUILTIN_RESERVED_VALIDATORS = new Map([
  *   - unknown `kind` values (closed union — new kinds bump protocol)
  *   - missing or wrong-typed variant-specific fields
  */
-export function validateCanvasLifecyclePayload(payload) {
+export function validateGguiLifecyclePayload(payload) {
     const violations = [];
-    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+    if (!isRecord(payload)) {
         return {
             valid: false,
             violations: [
@@ -330,11 +167,11 @@ export function validateCanvasLifecyclePayload(payload) {
             }
             break;
         case 'render_started':
-            requireString('renderId');
+            requireString('sessionId');
             requireString('intent');
             break;
         case 'consume_polling':
-            requireString('renderId');
+            requireString('sessionId');
             if (p.state !== 'open') {
                 violations.push({
                     field: 'state',

package/dist/validation/resolve-stream-channel.d.ts

@@ -23,7 +23,7 @@
  * Returns `undefined` for two distinct cases, both of which are
  * "nothing to enforce" at call sites:
  *
- *   - `spec === undefined` — the stack item has no stream contract.
+ *   - `spec === undefined` — the render has no stream contract.
  *   - `spec.channels[channelName]` is missing — the channel isn't
  *     declared. Callers MUST NOT assume this means "permissive";
  *     rejection is the downstream responsibility of
@@ -53,12 +53,6 @@ export interface ResolvedStreamChannel {
     readonly description?: string;
     /** Optional passthrough — channel's example payload. */
     readonly example?: JsonValue;
-    /** Optional passthrough — refresh tool declared for this channel.
-     * Server-side action dispatch (WS-direct agent-less deployments)
-     * fires this after a wired action succeeds; absence means "no
-     * refresh fires." Distinct from the `source` poll/push feed on
-     * `StreamChannelEntry`. See `StreamChannelEntry.tool`. */
-    readonly tool?: string;
 }
 /**
  * Look up a channel's declared semantics in a {@link StreamSpec} and
@@ -66,8 +60,8 @@ export interface ResolvedStreamChannel {
  * (`mode` / `replay` / `complete`) are filled with their locked
  * defaults.
  *
- * @param spec        The active stack item's stream contract, or undefined
- *                    when the item has no `streamSpec` at all.
+ * @param spec        The active render's stream contract, or undefined
+ *                    when the render has no `streamSpec` at all.
  * @param channelName The channel name to resolve — typically read
  *                    from the outbound envelope's `channel` field.
  * @returns `ResolvedStreamChannel` when the channel is declared;

package/dist/validation/resolve-stream-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-stream-channel.d.ts","sourceRoot":"","sources":["../../src/validation/resolve-stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;8DAI0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAClB,qBAAqB,GAAG,SAAS,CAcnC"}
+{"version":3,"file":"resolve-stream-channel.d.ts","sourceRoot":"","sources":["../../src/validation/resolve-stream-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,WAAW,EAAE,MAAM,GAClB,qBAAqB,GAAG,SAAS,CAanC"}