@ggui-ai/protocol 0.1.0-rc.1

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

@@ -0,0 +1,156 @@
+import type { ValidationResult } from './contract-validator';
+/** Prefix that marks a channel as server-owned (reserved from agents). */
+export declare const RESERVED_CHANNEL_PREFIX = "_ggui:";
+/**
+ * Reserved channel for provisional A2UI assembly streams emitted by
+ * the server during fresh-gen `ggui_push` flows. The agent never
+ * authors messages on this channel; the renderer subscribes implicitly
+ * and dispatches the A2UI payload through its preview surface.
+ */
+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.
+ *
+ * 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.
+ *
+ * Agent-authored `streamSpec` MUST NOT declare this channel; the
+ * structural validator rejects it alongside every other reserved-
+ * prefix name.
+ */
+export declare const LIFECYCLE_CHANNEL = "_ggui:lifecycle";
+/**
+ * Closed set of RECOGNIZED reserved channel names. Emissions and
+ * delivery validation consult this set — NOT the broader prefix
+ * predicate — so a typo inside the reserved namespace
+ * (`_ggui:preveiw`) cannot silently pass validation the way the
+ * unbounded prefix check did. A typo now falls through to the normal
+ * "unknown channel" rejection, surfacing the bug at its source instead
+ * of turning it into a silent no-op delivery.
+ *
+ * Adding a new reserved channel requires two edits: add the constant
+ * above, and add it to this set. The audit rule for future reviewers
+ * is "if a constant in this file is not in {@link KNOWN_RESERVED_CHANNELS},
+ * it is not a recognized delivery target".
+ */
+export declare const KNOWN_RESERVED_CHANNELS: ReadonlySet<string>;
+/**
+ * Returns `true` when `name` falls inside the server-owned reserved
+ * NAMESPACE (prefix `_ggui:`). Used exclusively by
+ * {@link validateContractStructure} to reject agent-authored
+ * `streamSpec` entries that try to declare ANY channel in the reserved
+ * namespace — regardless of whether the server currently recognizes
+ * the specific name. Broader than {@link isKnownReservedChannel} by
+ * design.
+ */
+export declare function isReservedChannelName(name: string): boolean;
+/**
+ * Returns `true` when `name` is a RECOGNIZED reserved channel the
+ * server-side runtime emits on today (see
+ * {@link KNOWN_RESERVED_CHANNELS}). Narrower than
+ * {@link isReservedChannelName} by design — a typo inside the reserved
+ * prefix (`_ggui:preveiw`) returns `false` here, which is the whole
+ * point: delivery validators and reserved-channel storage policies
+ * consult THIS predicate so typos surface as normal "unknown channel"
+ * rejections instead of silent no-op passes.
+ */
+export declare function isKnownReservedChannel(name: string): boolean;
+/**
+ * Validator signature for reserved-channel payload shape checks.
+ *
+ * Reserved-channel payload validation is split into TWO pools, joined
+ * at delivery time by {@link validateStreamData}:
+ *
+ *   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
+ *      belongs here too). Always active, no composition needed.
+ *   2. `extraReservedValidators` — INJECTION POINT for payloads whose
+ *      shape the protocol does NOT own. Primary consumer today:
+ *      `_ggui:preview` carries an A2UI-shaped `ServerMessage` from
+ *      `@ggui-ai/preview-a2ui`. The A2UI boundary package exports the
+ *      schema; hosting implementations compose a
+ *      {@link ReservedChannelValidator} adapter and pass it in.
+ *
+ * This split is the Protocol #6 (vendor-neutral separation)
+ * preservation: `@ggui-ai/protocol` ships zero imports of
+ * `@ggui-ai/preview-a2ui`, so third-party implementations that don't
+ * adopt A2UI can still build on the protocol without pulling in a
+ * preview-specific dep graph. Servers that DO use A2UI (the ggui
+ * first-party `@ggui-ai/mcp-server`) inject the validator at
+ * 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.
+ *
+ * Only channels whose payload shape is authored inside
+ * `@ggui-ai/protocol` appear here. `_ggui:preview` is intentionally
+ * ABSENT — its payload is A2UI-shaped (authored in
+ * `@ggui-ai/preview-a2ui`), and shipping a validator for it in this
+ * package would couple the protocol to a preview-specific dep graph,
+ * breaking Protocol #6 (vendor-neutral separation).
+ *
+ * Hosting implementations that compose preview support inject their
+ * own `_ggui:preview` validator via
+ * `validateStreamData(..., extraReservedValidators)` — lookup order:
+ * extras first, then this built-in map, then fall-through to valid.
+ *
+ * Readonly `ReadonlyMap` so consumers can't mutate the global registry.
+ */
+export declare const BUILTIN_RESERVED_VALIDATORS: ReadonlyMap<string, ReservedChannelValidator>;
+/**
+ * Structural validator for {@link LIFECYCLE_CHANNEL} payloads. The
+ * wire shape is the closed discriminated union
+ * {@link CanvasLifecyclePayload}; we narrow on `kind` and check the
+ * required fields per variant. Defines the failure mode the protocol
+ * bar requires for reserved channels.
+ *
+ * Rejects:
+ *   - non-object / null / array payloads
+ *   - missing or non-string `kind`
+ *   - unknown `kind` values (closed union — new kinds bump protocol)
+ *   - missing or wrong-typed variant-specific fields
+ */
+export declare function validateCanvasLifecyclePayload(payload: unknown): ValidationResult;
+//# sourceMappingURL=reserved-channels.d.ts.map

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

@@ -0,0 +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"}

package/dist/validation/reserved-channels.js

@@ -0,0 +1,356 @@
+/** Prefix that marks a channel as server-owned (reserved from agents). */
+export const RESERVED_CHANNEL_PREFIX = '_ggui:';
+/**
+ * Reserved channel for provisional A2UI assembly streams emitted by
+ * the server during fresh-gen `ggui_push` flows. The agent never
+ * authors messages on this channel; the renderer subscribes implicitly
+ * and dispatches the A2UI payload through its preview surface.
+ */
+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.
+ *
+ * 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.
+ *
+ * Agent-authored `streamSpec` MUST NOT declare this channel; the
+ * structural validator rejects it alongside every other reserved-
+ * prefix name.
+ */
+export const LIFECYCLE_CHANNEL = '_ggui:lifecycle';
+/**
+ * Closed set of RECOGNIZED reserved channel names. Emissions and
+ * delivery validation consult this set — NOT the broader prefix
+ * predicate — so a typo inside the reserved namespace
+ * (`_ggui:preveiw`) cannot silently pass validation the way the
+ * unbounded prefix check did. A typo now falls through to the normal
+ * "unknown channel" rejection, surfacing the bug at its source instead
+ * of turning it into a silent no-op delivery.
+ *
+ * Adding a new reserved channel requires two edits: add the constant
+ * above, and add it to this set. The audit rule for future reviewers
+ * is "if a constant in this file is not in {@link KNOWN_RESERVED_CHANNELS},
+ * it is not a recognized delivery target".
+ */
+export const KNOWN_RESERVED_CHANNELS = new Set([
+    PREVIEW_CHANNEL,
+    CONTRACT_ERROR_CHANNEL,
+    LIFECYCLE_CHANNEL,
+]);
+/**
+ * Returns `true` when `name` falls inside the server-owned reserved
+ * NAMESPACE (prefix `_ggui:`). Used exclusively by
+ * {@link validateContractStructure} to reject agent-authored
+ * `streamSpec` entries that try to declare ANY channel in the reserved
+ * namespace — regardless of whether the server currently recognizes
+ * the specific name. Broader than {@link isKnownReservedChannel} by
+ * design.
+ */
+export function isReservedChannelName(name) {
+    return name.startsWith(RESERVED_CHANNEL_PREFIX);
+}
+/**
+ * Returns `true` when `name` is a RECOGNIZED reserved channel the
+ * server-side runtime emits on today (see
+ * {@link KNOWN_RESERVED_CHANNELS}). Narrower than
+ * {@link isReservedChannelName} by design — a typo inside the reserved
+ * prefix (`_ggui:preveiw`) returns `false` here, which is the whole
+ * point: delivery validators and reserved-channel storage policies
+ * consult THIS predicate so typos surface as normal "unknown channel"
+ * rejections instead of silent no-op passes.
+ */
+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.
+ *
+ * Only channels whose payload shape is authored inside
+ * `@ggui-ai/protocol` appear here. `_ggui:preview` is intentionally
+ * ABSENT — its payload is A2UI-shaped (authored in
+ * `@ggui-ai/preview-a2ui`), and shipping a validator for it in this
+ * package would couple the protocol to a preview-specific dep graph,
+ * breaking Protocol #6 (vendor-neutral separation).
+ *
+ * Hosting implementations that compose preview support inject their
+ * own `_ggui:preview` validator via
+ * `validateStreamData(..., extraReservedValidators)` — lookup order:
+ * extras first, then this built-in map, then fall-through to valid.
+ *
+ * Readonly `ReadonlyMap` so consumers can't mutate the global registry.
+ */
+export const BUILTIN_RESERVED_VALIDATORS = new Map([
+    [CONTRACT_ERROR_CHANNEL, validateContractErrorPayload],
+    [LIFECYCLE_CHANNEL, validateCanvasLifecyclePayload],
+    // 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
+ * required fields per variant. Defines the failure mode the protocol
+ * bar requires for reserved channels.
+ *
+ * Rejects:
+ *   - non-object / null / array payloads
+ *   - missing or non-string `kind`
+ *   - unknown `kind` values (closed union — new kinds bump protocol)
+ *   - missing or wrong-typed variant-specific fields
+ */
+export function validateCanvasLifecyclePayload(payload) {
+    const violations = [];
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return {
+            valid: false,
+            violations: [
+                {
+                    field: 'payload',
+                    message: `${LIFECYCLE_CHANNEL} payload must be a non-null object`,
+                    expected: 'object',
+                    received: payload === null ? 'null' : Array.isArray(payload) ? 'array' : typeof payload,
+                },
+            ],
+        };
+    }
+    const p = payload;
+    if (typeof p.kind !== 'string') {
+        return {
+            valid: false,
+            violations: [
+                {
+                    field: 'kind',
+                    message: "Required field 'kind' must be a string",
+                    expected: 'string',
+                    received: p.kind === undefined ? 'undefined' : typeof p.kind,
+                },
+            ],
+        };
+    }
+    const requireString = (field) => {
+        if (typeof p[field] !== 'string') {
+            violations.push({
+                field,
+                message: `Required field '${field}' must be a string`,
+                expected: 'string',
+                received: p[field] === undefined ? 'undefined' : typeof p[field],
+            });
+        }
+    };
+    switch (p.kind) {
+        case 'handshake_started':
+            requireString('handshakeId');
+            requireString('intent');
+            break;
+        case 'handshake_completed':
+            requireString('handshakeId');
+            if (p.outcome !== 'accepted' &&
+                p.outcome !== 'amended' &&
+                p.outcome !== 'declined' &&
+                p.outcome !== 'cached') {
+                violations.push({
+                    field: 'outcome',
+                    message: "Required field 'outcome' must be 'accepted' | 'amended' | 'declined' | 'cached'",
+                    expected: "'accepted' | 'amended' | 'declined' | 'cached'",
+                    received: p.outcome === undefined ? 'undefined' : String(p.outcome),
+                });
+            }
+            if (typeof p.genExpected !== 'boolean') {
+                violations.push({
+                    field: 'genExpected',
+                    message: "Required field 'genExpected' must be a boolean",
+                    expected: 'boolean',
+                    received: p.genExpected === undefined ? 'undefined' : typeof p.genExpected,
+                });
+            }
+            break;
+        case 'push_started':
+            requireString('stackItemId');
+            requireString('intent');
+            break;
+        case 'consume_polling':
+            requireString('stackItemId');
+            if (p.state !== 'open') {
+                violations.push({
+                    field: 'state',
+                    message: "Required field 'state' must be 'open'",
+                    expected: "'open'",
+                    received: p.state === undefined ? 'undefined' : String(p.state),
+                });
+            }
+            break;
+        default:
+            violations.push({
+                field: 'kind',
+                message: `Unknown lifecycle kind '${p.kind}'. Closed union; new kinds bump protocol version.`,
+                expected: "'handshake_started' | 'handshake_completed' | 'push_started' | 'consume_polling'",
+                received: p.kind,
+            });
+    }
+    return { valid: violations.length === 0, violations };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * `resolveStreamChannel` — the single source of truth for applying
+ * per-channel defaults to a {@link StreamSpec} entry.
+ *
+ * Four runtime roles reason about stream channels today (hosted
+ * Lambda fan-out, OSS `/ws` fan-out, `@ggui-ai/react` data receipt,
+ * `@ggui-ai/react-native` data receipt). Each of them needs the same
+ * question answered: "what are the effective semantics of channel X
+ * on this spec?" Without a shared helper, each role applies the
+ * `DEFAULT_STREAM_*` constants inline and those defaults drift.
+ *
+ * This helper is a THIN lookup + default-application pass. It is
+ * explicitly NOT:
+ *
+ *   - a payload validator (that remains `validateStreamData` — the
+ *     shape check is orthogonal to the semantics lookup).
+ *   - a permission/authorization gate (channels are declared, not
+ *     granted).
+ *   - a replay-buffer read (no server-side buffer infrastructure
+ *     exists yet; `replay` comes back as a DECLARATION, not a
+ *     guarantee — see streamSpec design-lock for the honest stop).
+ *
+ * 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.channels[channelName]` is missing — the channel isn't
+ *     declared. Callers MUST NOT assume this means "permissive";
+ *     rejection is the downstream responsibility of
+ *     `validateStreamData` (which reports the undeclared-channel
+ *     violation), not this helper.
+ */
+import { type JsonSchema, type JsonValue, type StreamChannelMode, type StreamReplayPolicy, type StreamSpec } from '../types/data-contract.js';
+/**
+ * A channel's fully-resolved runtime semantics. Every optional field
+ * on the raw {@link import('../types/data-contract.js').StreamChannelEntry}
+ * has been defaulted per the locked `DEFAULT_STREAM_*` constants, so
+ * consumers that honor channel semantics never need to re-check for
+ * `undefined` on `mode` / `replay` / `complete`.
+ */
+export interface ResolvedStreamChannel {
+    /** Channel name (the lookup key used against `spec.channels`). */
+    readonly name: string;
+    /** Payload schema — the authoritative contract for deliveries. */
+    readonly schema: JsonSchema;
+    /** State-folding mode (defaulted). */
+    readonly mode: StreamChannelMode;
+    /** Replay policy (defaulted; advisory until replay infra ships). */
+    readonly replay: StreamReplayPolicy;
+    /** Whether this channel has a terminal completion marker (defaulted). */
+    readonly complete: boolean;
+    /** Optional passthrough — channel's human-readable description. */
+    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
+ * return the fully-resolved view. Optional fields on the raw entry
+ * (`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 channelName The channel name to resolve — typically read
+ *                    from the outbound envelope's `channel` field.
+ * @returns `ResolvedStreamChannel` when the channel is declared;
+ *          `undefined` otherwise (either the spec is absent or the
+ *          channel isn't in `spec.channels`).
+ */
+export declare function resolveStreamChannel(spec: StreamSpec | undefined, channelName: string): ResolvedStreamChannel | undefined;
+//# sourceMappingURL=resolve-stream-channel.d.ts.map

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

@@ -0,0 +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"}

package/dist/validation/resolve-stream-channel.js

@@ -0,0 +1,64 @@
+/**
+ * `resolveStreamChannel` — the single source of truth for applying
+ * per-channel defaults to a {@link StreamSpec} entry.
+ *
+ * Four runtime roles reason about stream channels today (hosted
+ * Lambda fan-out, OSS `/ws` fan-out, `@ggui-ai/react` data receipt,
+ * `@ggui-ai/react-native` data receipt). Each of them needs the same
+ * question answered: "what are the effective semantics of channel X
+ * on this spec?" Without a shared helper, each role applies the
+ * `DEFAULT_STREAM_*` constants inline and those defaults drift.
+ *
+ * This helper is a THIN lookup + default-application pass. It is
+ * explicitly NOT:
+ *
+ *   - a payload validator (that remains `validateStreamData` — the
+ *     shape check is orthogonal to the semantics lookup).
+ *   - a permission/authorization gate (channels are declared, not
+ *     granted).
+ *   - a replay-buffer read (no server-side buffer infrastructure
+ *     exists yet; `replay` comes back as a DECLARATION, not a
+ *     guarantee — see streamSpec design-lock for the honest stop).
+ *
+ * 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.channels[channelName]` is missing — the channel isn't
+ *     declared. Callers MUST NOT assume this means "permissive";
+ *     rejection is the downstream responsibility of
+ *     `validateStreamData` (which reports the undeclared-channel
+ *     violation), not this helper.
+ */
+import { DEFAULT_STREAM_CHANNEL_COMPLETE, DEFAULT_STREAM_CHANNEL_MODE, DEFAULT_STREAM_REPLAY_POLICY, } from '../types/data-contract.js';
+/**
+ * Look up a channel's declared semantics in a {@link StreamSpec} and
+ * return the fully-resolved view. Optional fields on the raw entry
+ * (`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 channelName The channel name to resolve — typically read
+ *                    from the outbound envelope's `channel` field.
+ * @returns `ResolvedStreamChannel` when the channel is declared;
+ *          `undefined` otherwise (either the spec is absent or the
+ *          channel isn't in `spec.channels`).
+ */
+export function resolveStreamChannel(spec, channelName) {
+    if (!spec)
+        return undefined;
+    const entry = spec[channelName];
+    if (!entry)
+        return undefined;
+    return {
+        name: channelName,
+        schema: entry.schema,
+        mode: entry.mode ?? DEFAULT_STREAM_CHANNEL_MODE,
+        replay: entry.replay ?? DEFAULT_STREAM_REPLAY_POLICY,
+        complete: entry.complete ?? DEFAULT_STREAM_CHANNEL_COMPLETE,
+        ...(entry.description !== undefined ? { description: entry.description } : {}),
+        ...(entry.example !== undefined ? { example: entry.example } : {}),
+        ...(entry.tool !== undefined ? { tool: entry.tool } : {}),
+    };
+}