@ggui-ai/protocol 0.1.0-rc.1

package/dist/validation/lint-contract.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Unified protocol-linter entry points for `DataContract`.
+ *
+ * Two reporting modes share one rule registry:
+ *
+ *   - {@link validateContract} — strict; runs phased validation and
+ *     throws {@link ContractValidationError} on the FIRST phase that
+ *     produces errors. Used at every protocol boundary (push handler,
+ *     blueprint registration, future synth output gate).
+ *
+ *   - {@link lintContract} — graded; runs ALL phases unconditionally
+ *     and returns errors + warnings together. Used by authoring
+ *     tools (synth's self-correction loop, blueprint registration's
+ *     warning surfaces, future contract-author tooling).
+ *
+ * **Phased execution** (stop-at-first-error-class for `validateContract`):
+ *
+ *   ```
+ *   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)
+ *   ```
+ *
+ * Errors are reported one phase at a time during strict validation so
+ * the LLM gets a clean signal during iterative authoring — fixing a
+ * shape bug first, then references, then schemas, then hygiene. The
+ * graded mode emits every issue at once so authoring tools can
+ * present a complete checklist.
+ */
+import type { DataContract } from '../types/data-contract';
+/**
+ * Severity classification for a {@link ContractIssue}. Strict
+ * `validateContract` throws on `'error'`; graded `lintContract`
+ * surfaces both, partitioned by severity.
+ */
+export type ContractIssueSeverity = 'error' | 'warn';
+/**
+ * Phase classification for a {@link ContractIssue}. Surfaced so
+ * authoring tools can render issues grouped by phase + drive the
+ * "fix one phase at a time" UX.
+ */
+export type ContractLintPhase = 'shape' | 'references' | 'schema-compat' | 'hygiene';
+/**
+ * One observation about a contract from the linter's perspective.
+ *
+ * Stable-code-keyed (vs. the existing per-module `ContractViolation`
+ * shape) so authoring tools can pattern-match on `code` and drive
+ * fix workflows. The pre-existing per-module violation types
+ * (`CrossReferenceViolation`, `NameInvariantViolation`,
+ * `SchemaCompatViolation`) map into this shape via the internal
+ * conversion helpers in this file; consumers of `lintContract` /
+ * `validateContract` see only `ContractIssue`.
+ */
+export interface ContractIssue {
+    /** Stable error code (e.g., 'CTR_REF_NEXT_STEP', 'CTR_DUP_NAME'). */
+    readonly code: string;
+    readonly severity: ContractIssueSeverity;
+    readonly phase: ContractLintPhase;
+    /**
+     * Field path into the contract identifying the offending entry.
+     * Uses dotted JS-style notation matching the per-module
+     * `ContractViolation.field` convention
+     * (`actionSpec.archive.nextStep`).
+     */
+    readonly path: string;
+    /** Human-readable violation prose. */
+    readonly message: string;
+    /**
+     * Optional remediation hint. Future hygiene-phase rules emit a
+     * fix recipe here ("declare `usage` on this entry"); invariant
+     * rules embed the recipe directly in `message` today.
+     */
+    readonly fixHint?: string;
+}
+/**
+ * Aggregate result of {@link lintContract}. Errors and warnings are
+ * partitioned at construction; consumers that want a flat list can
+ * concatenate.
+ */
+export interface ContractLintResult {
+    readonly errors: readonly ContractIssue[];
+    readonly warnings: readonly ContractIssue[];
+}
+/**
+ * Strict-mode failure. Carries the offending phase + every issue
+ * the failing phase produced so error renderers can show every fix
+ * in one pass without re-running the linter.
+ *
+ * The `phase` field discriminates the error class: shape errors
+ * surface as a single rolled-up zod failure; reference / schema-compat
+ * errors carry one issue per violation.
+ */
+export declare class ContractValidationError extends Error {
+    readonly code: "contract_validation_failed";
+    readonly phase: ContractLintPhase;
+    readonly issues: readonly ContractIssue[];
+    constructor(phase: ContractLintPhase, issues: readonly ContractIssue[]);
+}
+/**
+ * Strict-mode validator. Runs the four phases in order; throws
+ * {@link ContractValidationError} on the FIRST phase that produces
+ * errors. Used at every protocol boundary where a malformed
+ * contract is a fatal author bug.
+ *
+ * Phases run in dependency order:
+ *
+ *   1. shape — zod parse fails ⇒ nothing else makes sense
+ *   2. references — refs must resolve before schema-compat can read
+ *      the referenced tool's schemas
+ *   3. schema-compat — checks rely on resolved references
+ *   4. hygiene — warnings only; never throws (handled by lintContract)
+ *
+ * Hygiene-only contracts (warnings without errors) pass the strict
+ * gate. Use {@link lintContract} when warnings matter.
+ */
+export declare function validateContract(contract: DataContract): void;
+/**
+ * Graded-mode linter. Runs ALL phases unconditionally and returns
+ * errors + warnings partitioned. Suitable for authoring tools that
+ * want a complete checklist of issues + suggestions rather than the
+ * fail-fast posture of {@link validateContract}.
+ *
+ * Phase ordering still matters for diagnostics (issues are returned
+ * in phase order); but graded mode never short-circuits, so an
+ * author seeing a phase-2 reference error also sees the phase-4
+ * hygiene warnings on the same contract.
+ */
+export declare function lintContract(contract: DataContract): ContractLintResult;
+//# sourceMappingURL=lint-contract.d.ts.map

package/dist/validation/lint-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint-contract.d.ts","sourceRoot":"","sources":["../../src/validation/lint-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAgB3D;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,YAAY,GACZ,eAAe,GACf,SAAS,CAAC;AAEd;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;IACtD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;gBAE9B,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,SAAS,aAAa,EAAE;CAOvE;AAwHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAiB7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,CAsBvE"}

package/dist/validation/lint-contract.js

@@ -0,0 +1,225 @@
+/**
+ * Unified protocol-linter entry points for `DataContract`.
+ *
+ * Two reporting modes share one rule registry:
+ *
+ *   - {@link validateContract} — strict; runs phased validation and
+ *     throws {@link ContractValidationError} on the FIRST phase that
+ *     produces errors. Used at every protocol boundary (push handler,
+ *     blueprint registration, future synth output gate).
+ *
+ *   - {@link lintContract} — graded; runs ALL phases unconditionally
+ *     and returns errors + warnings together. Used by authoring
+ *     tools (synth's self-correction loop, blueprint registration's
+ *     warning surfaces, future contract-author tooling).
+ *
+ * **Phased execution** (stop-at-first-error-class for `validateContract`):
+ *
+ *   ```
+ *   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)
+ *   ```
+ *
+ * Errors are reported one phase at a time during strict validation so
+ * the LLM gets a clean signal during iterative authoring — fixing a
+ * shape bug first, then references, then schemas, then hygiene. The
+ * graded mode emits every issue at once so authoring tools can
+ * present a complete checklist.
+ */
+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';
+/**
+ * Strict-mode failure. Carries the offending phase + every issue
+ * the failing phase produced so error renderers can show every fix
+ * in one pass without re-running the linter.
+ *
+ * The `phase` field discriminates the error class: shape errors
+ * surface as a single rolled-up zod failure; reference / schema-compat
+ * errors carry one issue per violation.
+ */
+export class ContractValidationError extends Error {
+    code = 'contract_validation_failed';
+    phase;
+    issues;
+    constructor(phase, issues) {
+        const summary = issues.map((i) => `[${i.code}] ${i.message}`).join(' | ');
+        super(`Contract validation failed at phase '${phase}': ${summary}`);
+        this.name = 'ContractValidationError';
+        this.phase = phase;
+        this.issues = issues;
+    }
+}
+// =============================================================================
+// Phase 1 — shape (zod wire-shape validation)
+// =============================================================================
+function phaseShape(contract) {
+    const parsed = dataContractSchema.safeParse(contract);
+    if (parsed.success)
+        return [];
+    return zodErrorToIssues(parsed.error);
+}
+function zodErrorToIssues(error) {
+    return error.issues.map((issue) => ({
+        code: zodIssueCode(issue.code),
+        severity: 'error',
+        phase: 'shape',
+        path: issue.path.join('.') || '<root>',
+        message: issue.message,
+    }));
+}
+/**
+ * Map a zod issue code to the linter's stable code namespace. The
+ * mapping is intentionally narrow — every unknown zod code rolls up
+ * to `CTR_SHAPE_INVALID`; consumers that want zod-level granularity
+ * can re-parse with `dataContractSchema.safeParse` themselves.
+ */
+function zodIssueCode(zodCode) {
+    switch (zodCode) {
+        case 'invalid_type':
+            return 'CTR_SHAPE_INVALID_TYPE';
+        case 'unrecognized_keys':
+            return 'CTR_SHAPE_UNRECOGNIZED_KEYS';
+        default:
+            return 'CTR_SHAPE_INVALID';
+    }
+}
+// =============================================================================
+// Phase 2 — references (CTR_REF_*, CTR_DUP_NAME, CTR_RESERVED_NAME)
+// =============================================================================
+function phaseReferences(contract) {
+    const issues = [];
+    for (const v of checkCrossReferences(contract)) {
+        issues.push(crossRefViolationToIssue(v));
+    }
+    for (const v of checkNameInvariants(contract)) {
+        issues.push(nameInvariantViolationToIssue(v));
+    }
+    return issues;
+}
+function crossRefViolationToIssue(v) {
+    return {
+        code: v.code,
+        severity: 'error',
+        phase: 'references',
+        path: v.field,
+        message: v.message,
+    };
+}
+function nameInvariantViolationToIssue(v) {
+    return {
+        code: v.code,
+        severity: 'error',
+        phase: 'references',
+        path: v.field,
+        message: v.message,
+    };
+}
+// =============================================================================
+// Phase 3 — schema compat (CTR_SCHEMA_INCOMPAT)
+// =============================================================================
+function phaseSchemaCompat(contract) {
+    return checkSchemaCompat(contract).map(schemaCompatViolationToIssue);
+}
+function schemaCompatViolationToIssue(v) {
+    return {
+        code: v.code,
+        severity: 'error',
+        phase: 'schema-compat',
+        path: v.field,
+        message: v.message,
+    };
+}
+// =============================================================================
+// Phase 4 — hygiene (LINT_*)
+// =============================================================================
+function phaseHygiene(contract) {
+    return checkHygiene(contract).map(hygieneWarningToIssue);
+}
+function hygieneWarningToIssue(w) {
+    return {
+        code: w.code,
+        severity: 'warn',
+        phase: 'hygiene',
+        path: w.path,
+        message: w.message,
+        ...(w.fixHint !== undefined ? { fixHint: w.fixHint } : {}),
+    };
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Strict-mode validator. Runs the four phases in order; throws
+ * {@link ContractValidationError} on the FIRST phase that produces
+ * errors. Used at every protocol boundary where a malformed
+ * contract is a fatal author bug.
+ *
+ * Phases run in dependency order:
+ *
+ *   1. shape — zod parse fails ⇒ nothing else makes sense
+ *   2. references — refs must resolve before schema-compat can read
+ *      the referenced tool's schemas
+ *   3. schema-compat — checks rely on resolved references
+ *   4. hygiene — warnings only; never throws (handled by lintContract)
+ *
+ * Hygiene-only contracts (warnings without errors) pass the strict
+ * gate. Use {@link lintContract} when warnings matter.
+ */
+export function validateContract(contract) {
+    const shapeIssues = phaseShape(contract);
+    if (shapeIssues.length > 0) {
+        throw new ContractValidationError('shape', shapeIssues);
+    }
+    // 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);
+    if (refIssues.length > 0) {
+        throw new ContractValidationError('references', refIssues);
+    }
+    const compatIssues = phaseSchemaCompat(contract);
+    if (compatIssues.length > 0) {
+        throw new ContractValidationError('schema-compat', compatIssues);
+    }
+    // Hygiene is graded-only; not thrown by strict validator.
+}
+/**
+ * Graded-mode linter. Runs ALL phases unconditionally and returns
+ * errors + warnings partitioned. Suitable for authoring tools that
+ * want a complete checklist of issues + suggestions rather than the
+ * fail-fast posture of {@link validateContract}.
+ *
+ * Phase ordering still matters for diagnostics (issues are returned
+ * in phase order); but graded mode never short-circuits, so an
+ * author seeing a phase-2 reference error also sees the phase-4
+ * hygiene warnings on the same 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));
+    }
+    issues.push(...phaseHygiene(contract));
+    const errors = [];
+    const warnings = [];
+    for (const issue of issues) {
+        if (issue.severity === 'error')
+            errors.push(issue);
+        else
+            warnings.push(issue);
+    }
+    return { errors, warnings };
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Name-uniqueness and reserved-namespace invariants for `DataContract`.
+ *
+ * Two stable error codes:
+ *
+ *   - `CTR_DUP_NAME`     — the same key appears in two or more of
+ *                          `actionSpec`, `streamSpec`, `contextSpec`.
+ *                          Collisions are author bugs: the boilerplate
+ *                          generator emits identifiers from these keys
+ *                          (action handlers, channel subscribers, slot
+ *                          state hooks), and a collision either shadows
+ *                          or compiles to ambiguous source. The agent's
+ *                          downstream reasoning also fragments —
+ *                          "submit" can't be both a discrete event AND
+ *                          observable state without confusing the
+ *                          actions-vs-context placement rule.
+ *
+ *   - `CTR_RESERVED_NAME` — a key on `actionSpec` or `contextSpec`
+ *                          starts with the `_ggui:` reserved prefix.
+ *                          `streamSpec` already enforces this in
+ *                          `validateContractStructure` (server-owned
+ *                          reserved channels can't be agent-declared);
+ *                          this invariant extends the rule to the other
+ *                          two inbound specs so the reserved namespace
+ *                          is uniformly off-limits to authors. Today no
+ *                          reserved actions or context slots exist, but
+ *                          the protocol reserves the namespace forward
+ *                          for runtime-owned signals.
+ *
+ * Pure checks; return violations rather than throwing. Callers that
+ * want fail-fast semantics use {@link assertNameInvariants}. Folded
+ * into `validateContractStructure` so the structural-validator surface
+ * picks up these rules without per-caller wiring.
+ *
+ * Companion to {@link CrossReferenceError} in `./cross-references` —
+ * the two modules ship the "phase 2: references" rule registry.
+ */
+import type { DataContract } from '../types/data-contract';
+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.
+ */
+export declare const CTR_DUP_NAME = "CTR_DUP_NAME";
+/**
+ * Stable error code for keys in the `_ggui:` reserved namespace on
+ * `actionSpec` or `contextSpec`. `streamSpec` already enforces the
+ * same rule in `validateContractStructure`.
+ */
+export declare const CTR_RESERVED_NAME = "CTR_RESERVED_NAME";
+/**
+ * Name-invariant violation. Adds a stable `code` field on top of
+ * `ContractViolation` so consumers can switch on the code rather than
+ * pattern-matching message strings.
+ */
+export interface NameInvariantViolation extends ContractViolation {
+    code: typeof CTR_DUP_NAME | typeof CTR_RESERVED_NAME;
+}
+/**
+ * Validate that no name appears in more than one of `actionSpec`,
+ * `streamSpec`, `contextSpec`. Emits one violation per colliding name
+ * (not one per spec the name appears in) so the agent sees a single
+ * actionable line per collision.
+ *
+ * Order is stable: collisions are reported in the order names first
+ * appear when scanning `actionSpec` → `streamSpec` → `contextSpec`.
+ */
+export declare function checkNameCollisions(contract: DataContract): NameInvariantViolation[];
+/**
+ * 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`
+ * channel); this invariant extends the rule uniformly across the
+ * other two inbound spec maps.
+ *
+ * Future runtime-owned action or context signals would carry the
+ * `_ggui:` prefix and would be emitted by the runtime, not declared
+ * by authors. Today no such signals exist, but the prefix is reserved
+ * forward.
+ */
+export declare function checkReservedNames(contract: DataContract): NameInvariantViolation[];
+/**
+ * Run every name-invariant check. Returns the aggregated violation
+ * list — order is stable: collisions first, reserved names second.
+ *
+ * Pure check; doesn't throw. Callers that want fail-fast semantics
+ * use {@link assertNameInvariants}.
+ */
+export declare function checkNameInvariants(contract: DataContract): NameInvariantViolation[];
+/**
+ * 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
+ * registration).
+ *
+ * Carries the full violation list so error renderers can show every
+ * offending name in one pass instead of fix-and-retry per-field.
+ */
+export declare class NameInvariantError extends Error {
+    readonly code: "name_invariant_violation";
+    readonly violations: readonly NameInvariantViolation[];
+    constructor(violations: readonly NameInvariantViolation[]);
+}
+/**
+ * Throw-on-violation wrapper around {@link checkNameInvariants}.
+ * No-op when the contract's names are consistent.
+ *
+ * Designed to slot alongside `assertCrossReferences` at push 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.
+ */
+export declare function assertNameInvariants(contract: DataContract): void;
+//# sourceMappingURL=name-invariants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"name-invariants.d.ts","sourceRoot":"","sources":["../../src/validation/name-invariants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,IAAI,EAAE,OAAO,YAAY,GAAG,OAAO,iBAAiB,CAAC;CACtD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,sBAAsB,EAAE,CA6B1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,GACrB,sBAAsB,EAAE,CAmB1B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GACrB,sBAAsB,EAAE,CAE1B;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAC;gBAE3C,UAAU,EAAE,SAAS,sBAAsB,EAAE;CAQ1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAKjE"}

package/dist/validation/name-invariants.js

@@ -0,0 +1,172 @@
+/**
+ * Name-uniqueness and reserved-namespace invariants for `DataContract`.
+ *
+ * Two stable error codes:
+ *
+ *   - `CTR_DUP_NAME`     — the same key appears in two or more of
+ *                          `actionSpec`, `streamSpec`, `contextSpec`.
+ *                          Collisions are author bugs: the boilerplate
+ *                          generator emits identifiers from these keys
+ *                          (action handlers, channel subscribers, slot
+ *                          state hooks), and a collision either shadows
+ *                          or compiles to ambiguous source. The agent's
+ *                          downstream reasoning also fragments —
+ *                          "submit" can't be both a discrete event AND
+ *                          observable state without confusing the
+ *                          actions-vs-context placement rule.
+ *
+ *   - `CTR_RESERVED_NAME` — a key on `actionSpec` or `contextSpec`
+ *                          starts with the `_ggui:` reserved prefix.
+ *                          `streamSpec` already enforces this in
+ *                          `validateContractStructure` (server-owned
+ *                          reserved channels can't be agent-declared);
+ *                          this invariant extends the rule to the other
+ *                          two inbound specs so the reserved namespace
+ *                          is uniformly off-limits to authors. Today no
+ *                          reserved actions or context slots exist, but
+ *                          the protocol reserves the namespace forward
+ *                          for runtime-owned signals.
+ *
+ * Pure checks; return violations rather than throwing. Callers that
+ * want fail-fast semantics use {@link assertNameInvariants}. Folded
+ * into `validateContractStructure` so the structural-validator surface
+ * picks up these rules without per-caller wiring.
+ *
+ * Companion to {@link CrossReferenceError} in `./cross-references` —
+ * the two modules ship the "phase 2: references" rule registry.
+ */
+import { RESERVED_CHANNEL_PREFIX, isReservedChannelName, } from './reserved-channels.js';
+/**
+ * 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.
+ */
+export const CTR_DUP_NAME = 'CTR_DUP_NAME';
+/**
+ * Stable error code for keys in the `_ggui:` reserved namespace on
+ * `actionSpec` or `contextSpec`. `streamSpec` already enforces the
+ * same rule in `validateContractStructure`.
+ */
+export const CTR_RESERVED_NAME = 'CTR_RESERVED_NAME';
+/** Spec maps that share the inbound name namespace. */
+const SPEC_FIELDS = ['actionSpec', 'streamSpec', 'contextSpec'];
+/**
+ * Validate that no name appears in more than one of `actionSpec`,
+ * `streamSpec`, `contextSpec`. Emits one violation per colliding name
+ * (not one per spec the name appears in) so the agent sees a single
+ * actionable line per collision.
+ *
+ * Order is stable: collisions are reported in the order names first
+ * appear when scanning `actionSpec` → `streamSpec` → `contextSpec`.
+ */
+export function checkNameCollisions(contract) {
+    // Build name → list of spec fields where it appears
+    const byName = new Map();
+    for (const field of SPEC_FIELDS) {
+        const spec = contract[field];
+        if (!spec || typeof spec !== 'object')
+            continue;
+        for (const name of Object.keys(spec)) {
+            const existing = byName.get(name);
+            if (existing) {
+                existing.push(field);
+            }
+            else {
+                byName.set(name, [field]);
+            }
+        }
+    }
+    const violations = [];
+    for (const [name, fields] of byName) {
+        if (fields.length < 2)
+            continue;
+        violations.push({
+            code: CTR_DUP_NAME,
+            field: `${fields[0]}.${name}`,
+            message: `Name '${name}' is declared in multiple specs: ${fields.join(', ')}. Each name MUST appear in exactly one of actionSpec / streamSpec / contextSpec — the boilerplate generator emits identifiers from these keys and collisions produce shadowed or ambiguous source.`,
+            expected: 'unique name across inbound specs',
+            received: fields.join(' + '),
+        });
+    }
+    return violations;
+}
+/**
+ * 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`
+ * channel); this invariant extends the rule uniformly across the
+ * other two inbound spec maps.
+ *
+ * Future runtime-owned action or context signals would carry the
+ * `_ggui:` prefix and would be emitted by the runtime, not declared
+ * by authors. Today no such signals exist, but the prefix is reserved
+ * forward.
+ */
+export function checkReservedNames(contract) {
+    const violations = [];
+    for (const field of ['actionSpec', 'contextSpec']) {
+        const spec = contract[field];
+        if (!spec || typeof spec !== 'object')
+            continue;
+        for (const name of Object.keys(spec)) {
+            if (!isReservedChannelName(name))
+                continue;
+            violations.push({
+                code: CTR_RESERVED_NAME,
+                field: `${field}.${name}`,
+                message: `${field}.${name} is in the reserved '${RESERVED_CHANNEL_PREFIX}' namespace — names starting with that prefix are reserved for runtime-owned signals and cannot be agent-declared.`,
+                expected: `name not starting with '${RESERVED_CHANNEL_PREFIX}'`,
+                received: name,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * Run every name-invariant check. Returns the aggregated violation
+ * list — order is stable: collisions first, reserved names second.
+ *
+ * Pure check; doesn't throw. Callers that want fail-fast semantics
+ * use {@link assertNameInvariants}.
+ */
+export function checkNameInvariants(contract) {
+    return [...checkNameCollisions(contract), ...checkReservedNames(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
+ * registration).
+ *
+ * Carries the full violation list so error renderers can show every
+ * offending name in one pass instead of fix-and-retry per-field.
+ */
+export class NameInvariantError extends Error {
+    code = 'name_invariant_violation';
+    violations;
+    constructor(violations) {
+        const summary = violations
+            .map((v) => `[${v.code}] ${v.message}`)
+            .join(' | ');
+        super(`Contract name-invariant check failed: ${summary}`);
+        this.name = 'NameInvariantError';
+        this.violations = violations;
+    }
+}
+/**
+ * Throw-on-violation wrapper around {@link checkNameInvariants}.
+ * No-op when the contract's names are consistent.
+ *
+ * Designed to slot alongside `assertCrossReferences` at push 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.
+ */
+export function assertNameInvariants(contract) {
+    const violations = checkNameInvariants(contract);
+    if (violations.length > 0) {
+        throw new NameInvariantError(violations);
+    }
+}