@ggui-ai/protocol 0.1.0-rc.1

package/dist/validation/sanitize-error.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Patterns stripped from stringified errors before emission on
+ * `_ggui:contract-error`. The default set covers the common credential
+ * shapes that show up in stack traces by accident (URLs with token query
+ * params, Bearer headers captured by retry libraries, env-var dumps).
+ *
+ * Each regex replaces the matched span with `[REDACTED]`. Replacement is
+ * conservative — we'd rather over-redact than leak. Operators who need
+ * finer control inject a custom sanitizer via
+ * `createSessionChannelServer({ sanitizeCausedBy })`.
+ */
+export declare const DEFAULT_CREDENTIAL_PATTERNS: readonly RegExp[];
+/** Default max length for a sanitized `causedBy` string. */
+export declare const DEFAULT_CAUSED_BY_MAX_LENGTH = 2048;
+/** Truncation marker appended when `causedBy` exceeds the max length. */
+export declare const TRUNCATION_MARKER = "\n\u2026[truncated]";
+/**
+ * Sanitize a stringified error (typically `err.stack`) before it's
+ * written to `ContractErrorPayload.error.causedBy`.
+ *
+ * Applies every pattern in {@link DEFAULT_CREDENTIAL_PATTERNS} in order,
+ * replacing matches with `[REDACTED]`. If the result exceeds `maxLength`,
+ * the tail is replaced with {@link TRUNCATION_MARKER}.
+ *
+ * The function is pure and deterministic — the same `raw` produces the
+ * same output across runs. Safe to call in hot paths; patterns are
+ * pre-compiled module-level regexes.
+ *
+ * @param raw - The stringified error (usually `err.stack`).
+ * @param maxLength - Maximum length of returned string. Default 2048.
+ * @param patterns - Override the default credential-pattern set. Useful
+ *   for tests or operators who want stricter behavior. Passing an empty
+ *   array disables pattern replacement (truncation still applies).
+ */
+export declare function sanitizeCausedBy(raw: string, maxLength?: number, patterns?: readonly RegExp[]): string;
+/**
+ * Signature of the sanitizer hook operators can inject into
+ * `createSessionChannelServer`. Receives the raw stringified error
+ * (typically `err.stack`) and MUST return a safe-to-emit string.
+ *
+ * Defaults to {@link sanitizeCausedBy} when no override is supplied. A
+ * pass-through function that returns `raw` unchanged is valid but
+ * discouraged — it re-enables the leak this module was added to close.
+ */
+export type SanitizeCausedBy = (raw: string) => string;
+//# sourceMappingURL=sanitize-error.d.ts.map

package/dist/validation/sanitize-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize-error.d.ts","sourceRoot":"","sources":["../../src/validation/sanitize-error.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAWxD,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,wBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAqC,EAChD,QAAQ,GAAE,SAAS,MAAM,EAAgC,GACxD,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC"}

package/dist/validation/sanitize-error.js

@@ -0,0 +1,88 @@
+// packages/protocol/src/validation/sanitize-error.ts
+//
+// Credential-leak sanitizer for `ContractErrorPayload.error.causedBy`.
+//
+// The `causedBy` field on a contract-error envelope carries the
+// stringified original error — typically `Error.stack`. Stacks frequently
+// contain URLs with query-param tokens (`?token=...`, `?api_key=...`),
+// Authorization header values captured by over-eager logging libraries,
+// and env-var dumps. The envelope flows on the reserved
+// `_ggui:contract-error` channel with `replay: 'all'`, so anything that
+// lands in `causedBy` persists in the session ring buffer and is visible
+// in operator tools (SessionInspector activity panels). If an operator
+// shares a bug report with that data, the credential leaks externally.
+//
+// This module's default posture is "sanitize before emission": the
+// session-channel router pipes every `err.stack` through
+// {@link sanitizeCausedBy} before populating `causedBy`. Operators who
+// need stricter sanitization can inject their own function via
+// `createSessionChannelServer({ sanitizeCausedBy })`.
+//
+// Scope: this is a DEFENSE-IN-DEPTH belt, not the sole line. Libraries
+// that handle secrets should already avoid embedding them in error
+// messages. This sanitizer exists because stack traces are produced
+// opportunistically by code that didn't think about leaking and we'd
+// rather redact conservatively than ship raw stacks.
+/**
+ * Patterns stripped from stringified errors before emission on
+ * `_ggui:contract-error`. The default set covers the common credential
+ * shapes that show up in stack traces by accident (URLs with token query
+ * params, Bearer headers captured by retry libraries, env-var dumps).
+ *
+ * Each regex replaces the matched span with `[REDACTED]`. Replacement is
+ * conservative — we'd rather over-redact than leak. Operators who need
+ * finer control inject a custom sanitizer via
+ * `createSessionChannelServer({ sanitizeCausedBy })`.
+ */
+export const DEFAULT_CREDENTIAL_PATTERNS = [
+    // Bearer / Basic header values. `Bearer <token>` / `Authorization: Basic <base64>`.
+    /Bearer\s+[A-Za-z0-9._\-~+/]+=*/gi,
+    /Basic\s+[A-Za-z0-9+/]+=*/gi,
+    /Authorization:\s*\S+/gi,
+    // Query-param-style secrets — matches `?token=...` / `&api_key=...` etc.
+    // Up to the next `&`, space, quote, or end-of-string.
+    /([?&](?:token|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret|session[_-]?id)=)[^&\s"']+/gi,
+    // Env-var-style `KEY=value` where KEY is obviously secret-ish and value
+    // is non-empty. Bounds the value to the next whitespace/quote.
+    /\b(AWS_[A-Z_]+|ANTHROPIC_API_KEY|OPENAI_API_KEY|GOOGLE_API_KEY|OPENROUTER_API_KEY|COGNITO_[A-Z_]+|DATABASE_URL|DB_PASSWORD|REDIS_URL)=\S+/gi,
+];
+/** Default max length for a sanitized `causedBy` string. */
+export const DEFAULT_CAUSED_BY_MAX_LENGTH = 2048;
+/** Truncation marker appended when `causedBy` exceeds the max length. */
+export const TRUNCATION_MARKER = '\n…[truncated]';
+/**
+ * Sanitize a stringified error (typically `err.stack`) before it's
+ * written to `ContractErrorPayload.error.causedBy`.
+ *
+ * Applies every pattern in {@link DEFAULT_CREDENTIAL_PATTERNS} in order,
+ * replacing matches with `[REDACTED]`. If the result exceeds `maxLength`,
+ * the tail is replaced with {@link TRUNCATION_MARKER}.
+ *
+ * The function is pure and deterministic — the same `raw` produces the
+ * same output across runs. Safe to call in hot paths; patterns are
+ * pre-compiled module-level regexes.
+ *
+ * @param raw - The stringified error (usually `err.stack`).
+ * @param maxLength - Maximum length of returned string. Default 2048.
+ * @param patterns - Override the default credential-pattern set. Useful
+ *   for tests or operators who want stricter behavior. Passing an empty
+ *   array disables pattern replacement (truncation still applies).
+ */
+export function sanitizeCausedBy(raw, maxLength = DEFAULT_CAUSED_BY_MAX_LENGTH, patterns = DEFAULT_CREDENTIAL_PATTERNS) {
+    let out = raw;
+    for (const p of patterns) {
+        // Special-case the query-param pattern: we want to keep the key name
+        // so callers can still see WHERE the secret was, just not what it
+        // was. Every other pattern is replaced whole.
+        if (p.source.includes('token|api')) {
+            out = out.replace(p, '$1[REDACTED]');
+        }
+        else {
+            out = out.replace(p, '[REDACTED]');
+        }
+    }
+    if (out.length > maxLength) {
+        out = out.slice(0, maxLength) + TRUNCATION_MARKER;
+    }
+    return out;
+}

package/dist/validation/schema-compat-invariants.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Protocol-level schema-compatibility invariants for `DataContract`.
+ *
+ * Ships one stable error code:
+ *
+ *   - `CTR_SCHEMA_INCOMPAT` — an `actionSpec[*].schema` is not a
+ *     subset of the referenced `agentCapabilities.tools[*].inputSchema`,
+ *     OR a `streamSpec[*].schema` is not a superset of the
+ *     referenced `agentCapabilities.tools[*].outputSchema`. Direction is
+ *     fixed by the data flow: action payloads travel UI → tool, so
+ *     the action's accepted values must fit the tool's accepted
+ *     inputs; stream payloads travel tool → channel, so the
+ *     channel's accepted values must cover the tool's possible
+ *     outputs.
+ *
+ * **Scope vs server-level F4.** This invariant runs PURELY against
+ * the contract's own catalog — `actionSpec[*].schema` /
+ * `streamSpec[*].schema` vs `agentCapabilities.tools[*].inputSchema` /
+ * `outputSchema`, all of which are author-declared JSON Schemas
+ * already on the contract. No tool registry, no zod conversion, no
+ * server state. The server-level F4 check (`checkStackItemSchemaCompat`
+ * in `@ggui-ai/mcp-server`) compares the same `actionSpec` /
+ * `streamSpec` schemas against the SERVER-REGISTERED tools' actual
+ * zod schemas; it covers the operator-side "did the deployed tool
+ * change schema since the contract was authored?" failure mode. Both
+ * checks compose:
+ *
+ *   - Protocol-level CTR_SCHEMA_INCOMPAT: author-visible bug.
+ *     "Your contract's action.schema doesn't fit the inputSchema
+ *     you yourself declared on this tool entry."
+ *   - Server-level SchemaCompatError: operator-visible bug. "The
+ *     deployed tool's actual inputSchema doesn't match what the
+ *     contract declares."
+ *
+ * Skipped silently when the referenced agentTool has no declared
+ * `inputSchema`/`outputSchema` (the catalog entry is incomplete; the
+ * check has no anchor and degrades to "no opinion"). Skipped when
+ * the action/channel has no `schema` (void-payload entries — nothing
+ * to compare).
+ *
+ * Companion to `cross-references` and `name-invariants` — together
+ * they ship companion rule registries to cross-references and
+ * name-invariants under the unified `lintContract` API.
+ */
+import type { AgentCapabilitiesSpec, DataContract } from '../types/data-contract';
+import type { ContractViolation } from './contract-validator';
+/**
+ * Stable error code for protocol-level schema-compatibility
+ * violations on action ⊆ inputSchema or channel ⊇ outputSchema.
+ */
+export declare const CTR_SCHEMA_INCOMPAT = "CTR_SCHEMA_INCOMPAT";
+/**
+ * Discriminator on the side of the contract the violation came
+ * from. Surfaced on the violation so consumers can render the
+ * action vs. stream cases differently without parsing the field
+ * path.
+ */
+export type SchemaCompatSide = 'action' | 'stream';
+/**
+ * Schema-compat invariant violation. Carries the stable error code
+ * plus side / specName / toolName so consumers can pivot rendering
+ * on the action vs stream case without parsing the field path.
+ *
+ * The granular `isSchemaSubset` violation list is NOT carried on the
+ * violation (the rich `SubsetViolation` shape doesn't fit the
+ * `ContractViolation extends JsonObject` constraint). The message
+ * includes the first mismatch's reason + path; callers needing the
+ * full list can re-run {@link checkSchemaCompat} subcomponents
+ * directly.
+ */
+export interface SchemaCompatViolation extends ContractViolation {
+    code: typeof CTR_SCHEMA_INCOMPAT;
+    /** Which side of the contract was checked. */
+    side: SchemaCompatSide;
+    /** The action / channel name on the contract. */
+    specName: string;
+    /** The agentCapabilities.tools key resolved to perform the check. */
+    toolName: string;
+}
+/**
+ * Validate every `actionSpec[*].schema` is a subset of the
+ * referenced `agentCapabilities.tools[nextStep].inputSchema`.
+ *
+ * Skips entries where:
+ *   - no `nextStep` is declared (pure event signal — the agent owns
+ *     dispatch; nothing to compare),
+ *   - the referenced agentTool has no declared `inputSchema` (the
+ *     catalog entry is incomplete; the check has no anchor),
+ *   - the referenced agentTool is missing entirely (a separate
+ *     invariant `CTR_REF_NEXT_STEP` covers that).
+ *
+ * When the action has no `schema`, the wire shape is modeled as
+ * `{type: 'object', properties: {}, additionalProperties: false}` —
+ * "void payload." This matches the F4 convention so the protocol-
+ * level check stays compatible with the server-level posture.
+ */
+export declare function checkActionSchemaCompat(actionSpec: DataContract['actionSpec'] | undefined, agentCapabilities: AgentCapabilitiesSpec | undefined): SchemaCompatViolation[];
+/**
+ * Validate every `streamSpec[*].schema` is a SUPERSET of the
+ * referenced `agentCapabilities.tools[source.tool].outputSchema`. Direction
+ * inverts: streams travel tool → channel, so the channel schema
+ * must accept everything the tool can return.
+ *
+ * Skips entries where:
+ *   - no `source` is declared,
+ *   - the referenced agentTool has no declared `outputSchema`,
+ *   - the referenced agentTool is missing entirely
+ *     (`CTR_REF_STREAM_SOURCE` covers that),
+ *   - the channel has no `schema` (declarative validation is
+ *     impossible without the channel's accepted shape).
+ */
+export declare function checkStreamSchemaCompat(streamSpec: DataContract['streamSpec'] | undefined, agentCapabilities: AgentCapabilitiesSpec | undefined): SchemaCompatViolation[];
+/**
+ * Run every protocol-level schema-compat invariant. Aggregates action
+ * + stream violations; order is stable (action checks first).
+ */
+export declare function checkSchemaCompat(contract: DataContract): SchemaCompatViolation[];
+/**
+ * Throwable form of {@link checkSchemaCompat}. Use at protocol
+ * boundaries where a schema-compat violation is a contract bug the
+ * author must fix.
+ */
+export declare class SchemaCompatInvariantError extends Error {
+    readonly code: "schema_compat_incompat";
+    readonly violations: readonly SchemaCompatViolation[];
+    constructor(violations: readonly SchemaCompatViolation[]);
+}
+/**
+ * Throw-on-violation wrapper around {@link checkSchemaCompat}.
+ * No-op when the contract's schemas align with its own
+ * agentCapabilities catalog.
+ *
+ * Slots alongside `assertCrossReferences` + `assertNameInvariants`
+ * at push time. Different scope from the server-level
+ * `SchemaCompatError` thrown by `checkStackItemSchemaCompat` in
+ * `@ggui-ai/mcp-server`: this check uses ONLY the contract's own
+ * catalog; the server-level check uses the runtime tool registry.
+ */
+export declare function assertSchemaCompat(contract: DataContract): void;
+//# sourceMappingURL=schema-compat-invariants.d.ts.map

package/dist/validation/schema-compat-invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compat-invariants.d.ts","sourceRoot":"","sources":["../../src/validation/schema-compat-invariants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAGV,qBAAqB,EACrB,YAAY,EAGb,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAQ9D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,IAAI,EAAE,OAAO,mBAAmB,CAAC;IACjC,8CAA8C;IAC9C,IAAI,EAAE,gBAAgB,CAAC;IACvB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,SAAS,EAClD,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,GACnD,qBAAqB,EAAE,CAqCzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,SAAS,EAClD,iBAAiB,EAAE,qBAAqB,GAAG,SAAS,GACnD,qBAAqB,EAAE,CAuCzB;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,GACrB,qBAAqB,EAAE,CAKzB;AAED;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAG,wBAAwB,CAAU;IAClD,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;gBAE1C,UAAU,EAAE,SAAS,qBAAqB,EAAE;CAQzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAK/D"}

package/dist/validation/schema-compat-invariants.js

@@ -0,0 +1,220 @@
+/**
+ * Protocol-level schema-compatibility invariants for `DataContract`.
+ *
+ * Ships one stable error code:
+ *
+ *   - `CTR_SCHEMA_INCOMPAT` — an `actionSpec[*].schema` is not a
+ *     subset of the referenced `agentCapabilities.tools[*].inputSchema`,
+ *     OR a `streamSpec[*].schema` is not a superset of the
+ *     referenced `agentCapabilities.tools[*].outputSchema`. Direction is
+ *     fixed by the data flow: action payloads travel UI → tool, so
+ *     the action's accepted values must fit the tool's accepted
+ *     inputs; stream payloads travel tool → channel, so the
+ *     channel's accepted values must cover the tool's possible
+ *     outputs.
+ *
+ * **Scope vs server-level F4.** This invariant runs PURELY against
+ * the contract's own catalog — `actionSpec[*].schema` /
+ * `streamSpec[*].schema` vs `agentCapabilities.tools[*].inputSchema` /
+ * `outputSchema`, all of which are author-declared JSON Schemas
+ * already on the contract. No tool registry, no zod conversion, no
+ * server state. The server-level F4 check (`checkStackItemSchemaCompat`
+ * in `@ggui-ai/mcp-server`) compares the same `actionSpec` /
+ * `streamSpec` schemas against the SERVER-REGISTERED tools' actual
+ * zod schemas; it covers the operator-side "did the deployed tool
+ * change schema since the contract was authored?" failure mode. Both
+ * checks compose:
+ *
+ *   - Protocol-level CTR_SCHEMA_INCOMPAT: author-visible bug.
+ *     "Your contract's action.schema doesn't fit the inputSchema
+ *     you yourself declared on this tool entry."
+ *   - Server-level SchemaCompatError: operator-visible bug. "The
+ *     deployed tool's actual inputSchema doesn't match what the
+ *     contract declares."
+ *
+ * Skipped silently when the referenced agentTool has no declared
+ * `inputSchema`/`outputSchema` (the catalog entry is incomplete; the
+ * check has no anchor and degrades to "no opinion"). Skipped when
+ * the action/channel has no `schema` (void-payload entries — nothing
+ * to compare).
+ *
+ * Companion to `cross-references` and `name-invariants` — together
+ * they ship companion rule registries to cross-references and
+ * name-invariants under the unified `lintContract` API.
+ */
+import { isSchemaSubset } from './schema-subset.js';
+// `SubsetViolation` is used as the parameter type for the local
+// `describe` helper below; it is intentionally NOT carried on the
+// public `SchemaCompatViolation` (the rich shape doesn't fit
+// `ContractViolation extends JsonObject`).
+/**
+ * Stable error code for protocol-level schema-compatibility
+ * violations on action ⊆ inputSchema or channel ⊇ outputSchema.
+ */
+export const CTR_SCHEMA_INCOMPAT = 'CTR_SCHEMA_INCOMPAT';
+function buildToolMap(agentCapabilities) {
+    if (!agentCapabilities)
+        return new Map();
+    return new Map(Object.entries(agentCapabilities.tools));
+}
+/**
+ * Validate every `actionSpec[*].schema` is a subset of the
+ * referenced `agentCapabilities.tools[nextStep].inputSchema`.
+ *
+ * Skips entries where:
+ *   - no `nextStep` is declared (pure event signal — the agent owns
+ *     dispatch; nothing to compare),
+ *   - the referenced agentTool has no declared `inputSchema` (the
+ *     catalog entry is incomplete; the check has no anchor),
+ *   - the referenced agentTool is missing entirely (a separate
+ *     invariant `CTR_REF_NEXT_STEP` covers that).
+ *
+ * When the action has no `schema`, the wire shape is modeled as
+ * `{type: 'object', properties: {}, additionalProperties: false}` —
+ * "void payload." This matches the F4 convention so the protocol-
+ * level check stays compatible with the server-level posture.
+ */
+export function checkActionSchemaCompat(actionSpec, agentCapabilities) {
+    if (!actionSpec)
+        return [];
+    const tools = buildToolMap(agentCapabilities);
+    const violations = [];
+    for (const [actionName, entry] of Object.entries(actionSpec)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const toolName = entry.nextStep;
+        if (typeof toolName !== 'string' || toolName.length === 0)
+            continue;
+        const tool = tools.get(toolName);
+        if (!tool)
+            continue; // CTR_REF_NEXT_STEP covers this
+        const toolInput = tool.inputSchema;
+        if (!toolInput)
+            continue; // catalog entry incomplete — no anchor
+        const actionSchema = entry.schema ?? {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        };
+        const result = isSchemaSubset(toolInput, actionSchema);
+        if (result.compatible)
+            continue;
+        violations.push({
+            code: CTR_SCHEMA_INCOMPAT,
+            side: 'action',
+            specName: actionName,
+            toolName,
+            field: `actionSpec.${actionName}.schema`,
+            message: `actionSpec.${actionName}.schema is not a subset of agentCapabilities.tools.${toolName}.inputSchema — values the action accepts would be rejected by the tool. ${describe(result.violations)}`,
+            expected: `subset of agentCapabilities.tools.${toolName}.inputSchema`,
+            received: 'incompatible',
+        });
+    }
+    return violations;
+}
+/**
+ * Validate every `streamSpec[*].schema` is a SUPERSET of the
+ * referenced `agentCapabilities.tools[source.tool].outputSchema`. Direction
+ * inverts: streams travel tool → channel, so the channel schema
+ * must accept everything the tool can return.
+ *
+ * Skips entries where:
+ *   - no `source` is declared,
+ *   - the referenced agentTool has no declared `outputSchema`,
+ *   - the referenced agentTool is missing entirely
+ *     (`CTR_REF_STREAM_SOURCE` covers that),
+ *   - the channel has no `schema` (declarative validation is
+ *     impossible without the channel's accepted shape).
+ */
+export function checkStreamSchemaCompat(streamSpec, agentCapabilities) {
+    if (!streamSpec)
+        return [];
+    const tools = buildToolMap(agentCapabilities);
+    const violations = [];
+    for (const [channelName, entry] of Object.entries(streamSpec)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const source = entry.source;
+        if (!source)
+            continue;
+        const toolName = source.tool;
+        if (typeof toolName !== 'string' || toolName.length === 0)
+            continue;
+        const tool = tools.get(toolName);
+        if (!tool)
+            continue; // CTR_REF_STREAM_SOURCE covers this
+        const toolOutput = tool.outputSchema;
+        if (!toolOutput)
+            continue;
+        const channelSchema = entry.schema;
+        if (!channelSchema)
+            continue;
+        // Direction: every tool-returned value must be accepted by the
+        // channel schema. Channel is the superset / permissive side,
+        // tool-return is the restricted side.
+        const result = isSchemaSubset(channelSchema, toolOutput);
+        if (result.compatible)
+            continue;
+        violations.push({
+            code: CTR_SCHEMA_INCOMPAT,
+            side: 'stream',
+            specName: channelName,
+            toolName,
+            field: `streamSpec.${channelName}.schema`,
+            message: `streamSpec.${channelName}.schema does not accept all values agentCapabilities.tools.${toolName}.outputSchema produces — some tool outputs would fail channel validation. ${describe(result.violations)}`,
+            expected: `superset of agentCapabilities.tools.${toolName}.outputSchema`,
+            received: 'incompatible',
+        });
+    }
+    return violations;
+}
+function describe(violations) {
+    if (violations.length === 0)
+        return '';
+    const first = violations[0];
+    return `First mismatch: ${first.reason} at ${first.path || '<root>'}.`;
+}
+/**
+ * Run every protocol-level schema-compat invariant. Aggregates action
+ * + stream violations; order is stable (action checks first).
+ */
+export function checkSchemaCompat(contract) {
+    return [
+        ...checkActionSchemaCompat(contract.actionSpec, contract.agentCapabilities),
+        ...checkStreamSchemaCompat(contract.streamSpec, contract.agentCapabilities),
+    ];
+}
+/**
+ * Throwable form of {@link checkSchemaCompat}. Use at protocol
+ * boundaries where a schema-compat violation is a contract bug the
+ * author must fix.
+ */
+export class SchemaCompatInvariantError extends Error {
+    code = 'schema_compat_incompat';
+    violations;
+    constructor(violations) {
+        const summary = violations
+            .map((v) => `[${v.code}] ${v.message}`)
+            .join(' | ');
+        super(`Contract schema-compat invariants failed: ${summary}`);
+        this.name = 'SchemaCompatInvariantError';
+        this.violations = violations;
+    }
+}
+/**
+ * Throw-on-violation wrapper around {@link checkSchemaCompat}.
+ * No-op when the contract's schemas align with its own
+ * agentCapabilities catalog.
+ *
+ * Slots alongside `assertCrossReferences` + `assertNameInvariants`
+ * at push time. Different scope from the server-level
+ * `SchemaCompatError` thrown by `checkStackItemSchemaCompat` in
+ * `@ggui-ai/mcp-server`: this check uses ONLY the contract's own
+ * catalog; the server-level check uses the runtime tool registry.
+ */
+export function assertSchemaCompat(contract) {
+    const violations = checkSchemaCompat(contract);
+    if (violations.length > 0) {
+        throw new SchemaCompatInvariantError(violations);
+    }
+}

package/dist/validation/schema-meta-validation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Layer B (inner JSON Schema meta-validation) for a `DataContract`.
+ *
+ * Walks the six inner JSON Schema fields the agent authors:
+ *   1. `propsSpec.properties[*].schema`
+ *   2. `actionSpec[*].schema` (optional per entry)
+ *   3. `streamSpec[*].schema`
+ *   4. `contextSpec[*].schema`
+ *   5. `agentCapabilities.tools[*].inputSchema` (optional per entry)
+ *   6. `agentCapabilities.tools[*].outputSchema` (optional per entry)
+ *
+ * For each present schema, runs `compileForValidation()` from
+ * `ajv-runtime`. Ajv's `strict: true` mode throws on malformed JSON
+ * Schemas at compile-time — unknown keywords, missing `items` on
+ * array nodes, properties values that are not schemas, etc. This is
+ * the meta-validation pass: it asserts the contract's own type
+ * descriptions are well-formed BEFORE any runtime data flows.
+ *
+ * Failures collect into a single throw with every malformed field
+ * named — agents fix all of them in one round rather than retry-
+ * per-field.
+ *
+ * Designed to slot at:
+ *   - `ggui_handshake` entry — validates `blueprintDraft.contract`
+ *     before the negotiator runs.
+ *   - `ggui_push` entry — validates the `effectiveContract` (either
+ *     synth-amended or override) before any state mutation.
+ *
+ * Both call sites already run cross-reference and name-invariant
+ * assertions for the same author-recoverable failure class; this
+ * sits alongside them.
+ */
+import type { DataContract } from '../types/data-contract';
+export interface SchemaMetaViolation {
+    /** Path to the malformed schema field (e.g., `propsSpec.properties.todos.schema`). */
+    field: string;
+    /** Ajv's compile-error message (truncated to fit the wire). */
+    message: string;
+}
+/**
+ * Typed error for contract schema meta-validation failures. Mirrors
+ * the shape of `CrossReferenceError` / `ContractViolationError` for
+ * symmetry — push/handshake catch and surface a structured
+ * `contract_schema_invalid` error to the agent.
+ */
+export declare class ContractSchemaMetaError extends Error {
+    readonly code: "contract_schema_invalid";
+    readonly violations: readonly SchemaMetaViolation[];
+    readonly hint: string;
+    constructor(violations: readonly SchemaMetaViolation[]);
+}
+/**
+ * Walks the contract's six inner JSON Schema fields and asserts
+ * each compiles cleanly under Ajv's strict mode. Throws
+ * {@link ContractSchemaMetaError} on the first push attempt that
+ * smuggles a malformed schema; collects every offender in one pass
+ * before throwing so the agent sees the full list.
+ */
+export declare function assertContractSchemasValid(contract: DataContract): void;
+//# sourceMappingURL=schema-meta-validation.d.ts.map

package/dist/validation/schema-meta-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-meta-validation.d.ts","sourceRoot":"","sources":["../../src/validation/schema-meta-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAG,yBAAyB,CAAU;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,UAAU,EAAE,SAAS,mBAAmB,EAAE;CAWvD;AAmCD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAuDvE"}