@cleocode/contracts 2026.5.111 → 2026.5.113

package/dist/invariants/index.js

@@ -0,0 +1,118 @@
+/**
+ * Central invariants registry — SSoT for system-wide invariants surfaced via
+ * the SaGa T10326 SG-SUBSTRATE-RECONCILIATION programme (Epic T10327
+ * E-INVARIANT-REGISTRY-SSOT, Task T10335 R1).
+ *
+ * Every registered invariant carries the metadata needed to:
+ * 1. Reference its source ADR (e.g. `ADR-073` §1.2 for I1-I8).
+ * 2. Locate the runtime guard that enforces it (when one exists).
+ * 3. Bind the CI lint rule that protects it (when one exists).
+ * 4. Cross-reference test files that exercise it.
+ * 5. Render documentation via the downstream R8 auto-render pipeline.
+ *
+ * Downstream consumers:
+ * - R2 (T10336, SHIPPED): registers ADR-070 ORC-001..ORC-014 codes into
+ *   this same registry via `./adr-070-orchestration.ts`.
+ * - R4 (T10338): CI gate validates that every `severity:'error'` entry has
+ *   a non-null `runtimeGate` AND a matching error-code in `errors.ts`.
+ * - R5 (T10339): refactor `packages/core/src/release/invariants/registry.ts`
+ *   to consume the central registry instead of carrying its own list.
+ * - R6 (T10340): `cleo doctor --audit-invariants` walks the registry to
+ *   produce a per-invariant audit report.
+ * - R8 (T10342): auto-render docs page from the registry.
+ *
+ * @epic T10327 — E-INVARIANT-REGISTRY-SSOT
+ * @saga T10326 — SG-SUBSTRATE-RECONCILIATION
+ * @task T10335 — R1: registry + ADR-073 I1-I8
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+import { ADR_056_INVARIANTS } from './adr-056-release.js';
+import { ADR_070_INVARIANTS } from './adr-070-orchestration.js';
+import { ADR_073_INVARIANTS } from './adr-073-saga.js';
+// Re-exported so consumers can import either the per-ADR list or the merged
+// registry from one place.
+export { ADR_056_INVARIANTS } from './adr-056-release.js';
+export { ADR_070_INVARIANTS } from './adr-070-orchestration.js';
+export { ADR_073_INVARIANTS } from './adr-073-saga.js';
+/**
+ * Compute the canonical registry key for an invariant.
+ *
+ * @internal
+ */
+function buildKey(invariant) {
+    return `${invariant.adr}.${invariant.code}`;
+}
+/**
+ * Build the merged registry record from all per-ADR invariant modules.
+ *
+ * Future ADR modules (ADR-070 ORC codes via R2 T10336, etc.) append to
+ * the spread list below. Each module exports a `readonly RegisteredInvariant[]`
+ * — this index assembles them into a keyed record at module load time.
+ *
+ * @internal
+ */
+function buildRegistry() {
+    const entries = [
+        ...ADR_073_INVARIANTS,
+        ...ADR_056_INVARIANTS,
+        ...ADR_070_INVARIANTS,
+    ];
+    const record = {};
+    for (const entry of entries) {
+        const key = buildKey(entry);
+        if (record[key] !== undefined) {
+            throw new Error(`Duplicate invariant key registered: ${key}`);
+        }
+        record[key] = entry;
+    }
+    return Object.freeze(record);
+}
+/**
+ * Central invariants registry — keyed by `${adr}.${code}`.
+ *
+ * Treat as read-only at runtime. Mutating this record is a contract
+ * violation; downstream consumers (R5 release-registry refactor, R6
+ * doctor audit, R8 docs renderer) assume immutability.
+ *
+ * @example
+ * ```ts
+ * import { INVARIANTS_REGISTRY } from '@cleocode/contracts';
+ * const i3 = INVARIANTS_REGISTRY['ADR-073.I3'];
+ * if (i3?.runtimeGate) {
+ *   console.log(`Guard: ${i3.runtimeGate.functionName}`);
+ * }
+ * ```
+ */
+export const INVARIANTS_REGISTRY = buildRegistry();
+/**
+ * Look up a single invariant by its `${adr}.${code}` key.
+ *
+ * @example
+ * ```ts
+ * const i3 = getInvariant('ADR-073.I3');
+ * // → RegisteredInvariant for ADR-073 invariant I3
+ * ```
+ */
+export function getInvariant(adrCode) {
+    return INVARIANTS_REGISTRY[adrCode];
+}
+/**
+ * Return every invariant registered against a given ADR, in declaration order.
+ *
+ * @example
+ * ```ts
+ * const adr073 = getInvariantsByAdr('ADR-073');
+ * // → array of I1..I8 entries
+ * ```
+ */
+export function getInvariantsByAdr(adr) {
+    const result = [];
+    for (const key of Object.keys(INVARIANTS_REGISTRY)) {
+        const entry = INVARIANTS_REGISTRY[key];
+        if (entry !== undefined && entry.adr === adr) {
+            result.push(entry);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/invariants/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/invariants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,4EAA4E;AAC5E,2BAA2B;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAoGvD;;;;GAIG;AACH,SAAS,QAAQ,CAAC,SAA8B;IAC9C,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,aAAa;IACpB,MAAM,OAAO,GAA0B;QACrC,GAAG,kBAAkB;QACrB,GAAG,kBAAkB;QACrB,GAAG,kBAAkB;KACtB,CAAC;IACF,MAAM,MAAM,GAAwC,EAAE,CAAC;IACvD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkD,aAAa,EAAE,CAAC;AAElG;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/operations/__tests__/input-contract.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Type + construction tests for OperationInputContract, ValidationResult,
+ * and ValidationError.
+ *
+ * These tests are intentionally minimal — the contracts package is a leaf
+ * with zero runtime dependencies, so there is no validator to exercise
+ * here. Instead, we assert:
+ *
+ *   1. ValidationResult narrows correctly via the `ok` discriminator.
+ *   2. A typed OperationInputContract<T> can be constructed and its
+ *      examples[0].value satisfies the generic.
+ *   3. ValidationError can be constructed with all 6 required fields.
+ *
+ * The runtime validator that consumes these types ships under T9915.
+ *
+ * @epic T9855
+ * @task T9914
+ */
+export {};
+//# sourceMappingURL=input-contract.test.d.ts.map

package/dist/operations/__tests__/input-contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.test.d.ts","sourceRoot":"","sources":["../../../src/operations/__tests__/input-contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/operations/__tests__/input-contract.test.js

@@ -0,0 +1,158 @@
+/**
+ * Type + construction tests for OperationInputContract, ValidationResult,
+ * and ValidationError.
+ *
+ * These tests are intentionally minimal — the contracts package is a leaf
+ * with zero runtime dependencies, so there is no validator to exercise
+ * here. Instead, we assert:
+ *
+ *   1. ValidationResult narrows correctly via the `ok` discriminator.
+ *   2. A typed OperationInputContract<T> can be constructed and its
+ *      examples[0].value satisfies the generic.
+ *   3. ValidationError can be constructed with all 6 required fields.
+ *
+ * The runtime validator that consumes these types ships under T9915.
+ *
+ * @epic T9855
+ * @task T9914
+ */
+import { describe, expect, it } from 'vitest';
+// ---------------------------------------------------------------------------
+// ValidationResult discriminated-union narrowing
+// ---------------------------------------------------------------------------
+describe('ValidationResult<T>', () => {
+    it('narrows to the success branch when ok is true', () => {
+        // Constructor return type is widened so TS keeps both branches reachable
+        // at the call site — that's the whole point of the discriminated union.
+        const makeResult = () => ({
+            ok: true,
+            value: { title: 'Ship E7' },
+        });
+        const result = makeResult();
+        if (result.ok) {
+            // Type-level: TypeScript narrows result.value to { title: string }.
+            // Runtime: the value is exactly what we constructed.
+            expect(result.value.title).toBe('Ship E7');
+        }
+        else {
+            // Type-level: result.errors is ValidationError[].
+            expect(result.errors).toEqual([]);
+        }
+    });
+    it('narrows to the failure branch when ok is false', () => {
+        const makeResult = () => ({
+            ok: false,
+            errors: [
+                {
+                    path: '/title',
+                    expected: 'string with minLength 1',
+                    received: 'empty string',
+                    fix: 'Provide a non-empty title.',
+                    errorCode: 'E_INPUT_MIN_LENGTH',
+                    schemaPath: '#/properties/title/minLength',
+                },
+            ],
+        });
+        const result = makeResult();
+        if (result.ok) {
+            expect(result.value).toBeDefined();
+        }
+        else {
+            expect(result.errors).toHaveLength(1);
+            expect(result.errors[0]?.errorCode).toBe('E_INPUT_MIN_LENGTH');
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// OperationInputContract<T> construction
+// ---------------------------------------------------------------------------
+describe('OperationInputContract<T>', () => {
+    it('builds a typed contract whose examples match the generic', () => {
+        const schema = {
+            type: 'object',
+            required: ['title', 'acceptance'],
+            properties: {
+                title: { type: 'string', minLength: 1, maxLength: 200 },
+                acceptance: { type: 'string', minLength: 1 },
+            },
+            additionalProperties: false,
+        };
+        const contract = {
+            operation: 'tasks.create',
+            schema,
+            examples: [
+                {
+                    name: 'minimal',
+                    value: { title: 'Ship E7', acceptance: 'PR merged' },
+                    description: 'Smallest valid payload.',
+                },
+            ],
+        };
+        expect(contract.operation).toBe('tasks.create');
+        expect(contract.schema).toBe(schema);
+        expect(contract.examples).toHaveLength(1);
+        const first = contract.examples[0];
+        expect(first).toBeDefined();
+        // Type-level: first.value is CreateTaskInput. Runtime sanity:
+        expect(first?.value.title).toBe('Ship E7');
+        expect(first?.value.acceptance).toBe('PR merged');
+        expect(first?.name).toBe('minimal');
+        expect(first?.description).toBe('Smallest valid payload.');
+    });
+    it('accepts a contract with an example that omits the optional description', () => {
+        const contract = {
+            operation: 'docs.fetch',
+            schema: { type: 'object', required: ['id'], properties: { id: { type: 'string' } } },
+            examples: [{ name: 'minimal', value: { id: 'adr-076' } }],
+        };
+        expect(contract.examples[0]?.description).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// ValidationError shape
+// ---------------------------------------------------------------------------
+describe('ValidationError', () => {
+    it('constructs with all 6 required fields', () => {
+        const err = {
+            path: '/owners/0/email',
+            expected: 'string matching email format',
+            received: 'string',
+            fix: 'Use a valid email address (e.g. user@example.com).',
+            errorCode: 'E_INPUT_FORMAT_EMAIL',
+            schemaPath: '#/properties/owners/items/properties/email/format',
+        };
+        expect(err.path).toBe('/owners/0/email');
+        expect(err.expected).toBe('string matching email format');
+        expect(err.received).toBe('string');
+        expect(err.fix).toBe('Use a valid email address (e.g. user@example.com).');
+        expect(err.errorCode).toBe('E_INPUT_FORMAT_EMAIL');
+        expect(err.schemaPath).toBe('#/properties/owners/items/properties/email/format');
+        // All 6 fields present — no extras.
+        expect(Object.keys(err).sort()).toEqual([
+            'errorCode',
+            'expected',
+            'fix',
+            'path',
+            'received',
+            'schemaPath',
+        ]);
+    });
+});
+// ---------------------------------------------------------------------------
+// Registry shape
+// ---------------------------------------------------------------------------
+describe('OperationInputContractRegistry', () => {
+    it('keys contracts by their operation identifier', () => {
+        const createTask = {
+            operation: 'tasks.create',
+            schema: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } },
+            examples: [{ name: 'minimal', value: { title: 'a' } }],
+        };
+        const registry = {
+            'tasks.create': createTask,
+        };
+        expect(registry['tasks.create']?.operation).toBe('tasks.create');
+        expect(registry['unknown.op']).toBeUndefined();
+    });
+});
+//# sourceMappingURL=input-contract.test.js.map

package/dist/operations/__tests__/input-contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.test.js","sourceRoot":"","sources":["../../../src/operations/__tests__/input-contract.test.ts"],"names":[],"mappings":"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"}

package/dist/operations/docs.d.ts

@@ -351,6 +351,22 @@ export interface DocsAddParams {
      * @task T9637 (T-DOCS-SLUG-2)
      */
     type?: DocsType;
+    /**
+     * When `true`, body-schema validation against
+     * {@link DocKindMetadata.requiredSections} is enforced — a missing
+     * required H2 section returns `E_DOC_SCHEMA_MISMATCH` with the
+     * missing-sections list in `details.missing`. When omitted or `false`,
+     * the validator runs in advisory mode: the write proceeds and any
+     * missing sections surface as a warning in the envelope's `meta`.
+     *
+     * Only meaningful when `file` is set; URL attachments skip body
+     * validation (no local bytes to scan).
+     *
+     * @task T10160 (E12.C3 · absorbs T10154)
+     * @epic T10157
+     * @saga T9855
+     */
+    strict?: boolean;
 }
 /**
  * Result of `docs.add`.

package/dist/operations/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/operations/docs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/operations/docs.ts"],"names":[],"mappings":"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"}

package/dist/operations/input-contract.d.ts

@@ -0,0 +1,267 @@
+/**
+ * OperationInputContract — schema-first input contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the schema-first input
+ * validation surface that powers the `mutate(operation, input)` DX
+ * (Saga T9855 / E7). Every CLEO operation that accepts structured input
+ * MUST be describable as an {@link OperationInputContract}: a JSON Schema
+ * draft-07 document, a stable operation identifier, and at least one
+ * worked example payload.
+ *
+ * Validators consume an {@link OperationInputContract} and produce a
+ * {@link ValidationResult} discriminated union — either the typed value
+ * (`ok: true`) or an array of {@link ValidationError} entries with
+ * actionable, JSON-Pointer-anchored remediation hints (`ok: false`).
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose alias {@link JsonSchema} so this
+ * module does not pull in a JSON Schema typings package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/input-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ *
+ * @epic T9855
+ * @task T9914
+ */
+/**
+ * Loose alias for a JSON Schema draft-07 document.
+ *
+ * Intentionally typed as `Record<string, unknown>` to keep the contracts
+ * package free of any JSON Schema typings runtime/type dependency. The
+ * actual draft-07 shape is enforced by the validator implementation
+ * (T9915) at the point of use, not by the type system here.
+ *
+ * @example
+ * ```ts
+ * const titleSchema: JsonSchema = {
+ *   type: 'object',
+ *   required: ['title'],
+ *   properties: {
+ *     title: { type: 'string', minLength: 1 },
+ *   },
+ * };
+ * ```
+ */
+export type JsonSchema = Record<string, unknown>;
+/**
+ * A single worked example payload for an {@link OperationInputContract}.
+ *
+ * Examples are MANDATORY (the contract requires at least one) — they
+ * double as documentation for human readers AND as conformance fixtures
+ * for the validator self-test that ships with every CLEO release.
+ *
+ * @typeParam T - The validated, typed input shape produced by the contract.
+ *
+ * @example
+ * ```ts
+ * const example: OperationInputExample<{ title: string }> = {
+ *   name: 'minimal',
+ *   value: { title: 'Ship saga T9855' },
+ *   description: 'Smallest valid input — title is the only required field.',
+ * };
+ * ```
+ */
+export interface OperationInputExample<T> {
+    /**
+     * Short, human-readable identifier for the example. Conventionally
+     * kebab-case (`'minimal'`, `'with-all-fields'`, `'edge-empty-array'`).
+     */
+    name: string;
+    /**
+     * A concrete value that validates successfully against the contract's
+     * {@link OperationInputContract.schema | schema}. Strongly typed via
+     * the `T` generic so example tables stay in sync with the operation
+     * payload shape at compile time.
+     */
+    value: T;
+    /**
+     * Optional prose explaining why this example matters — what edge case
+     * it covers, what default it exercises, etc. Surfaced in generated docs.
+     */
+    description?: string;
+}
+/**
+ * Schema-first input contract for a single CLEO operation.
+ *
+ * Pairs a stable operation identifier with the JSON Schema draft-07
+ * document that describes the operation's accepted input shape, plus a
+ * non-empty (by convention) catalogue of worked examples. The validator
+ * implementation (T9915) ingests an {@link OperationInputContract} and a
+ * raw payload, returning a {@link ValidationResult}.
+ *
+ * Together with the {@link OperationInputContractRegistry}, this type is
+ * the foundation of the schema-first `mutate(operation, input)` DX
+ * surface (Saga T9855 / E7).
+ *
+ * @typeParam T - The validated, typed input shape produced when the
+ * raw payload passes validation. The generic propagates through
+ * {@link ValidationResult} so callers receive a strongly-typed `value`
+ * in the success branch.
+ *
+ * @example
+ * ```ts
+ * interface CreateTaskInput {
+ *   title: string;
+ *   acceptance: string;
+ * }
+ *
+ * const createTaskContract: OperationInputContract<CreateTaskInput> = {
+ *   operation: 'tasks.create',
+ *   schema: {
+ *     type: 'object',
+ *     required: ['title', 'acceptance'],
+ *     properties: {
+ *       title: { type: 'string', minLength: 1, maxLength: 200 },
+ *       acceptance: { type: 'string', minLength: 1 },
+ *     },
+ *     additionalProperties: false,
+ *   },
+ *   examples: [
+ *     {
+ *       name: 'minimal',
+ *       value: { title: 'Ship E7', acceptance: 'PR merged' },
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export interface OperationInputContract<T> {
+    /**
+     * Stable, fully-qualified operation identifier in
+     * `<domain>.<verb>` form (e.g. `'tasks.create'`, `'docs.publish'`).
+     * Used as the registry key in {@link OperationInputContractRegistry}.
+     */
+    operation: string;
+    /**
+     * JSON Schema draft-07 document describing the accepted input shape.
+     * The validator MUST treat absent properties as not-present (it does
+     * NOT inject `default` values) so callers can distinguish "user
+     * omitted" from "user supplied default".
+     */
+    schema: JsonSchema;
+    /**
+     * Catalogue of worked example payloads. Conventionally non-empty so
+     * generated docs always have at least one runnable sample. Each
+     * example's {@link OperationInputExample.value | value} is statically
+     * typed to the contract's `T` parameter.
+     */
+    examples: ReadonlyArray<OperationInputExample<T>>;
+}
+/**
+ * A single validation failure produced by the input validator.
+ *
+ * Every field is REQUIRED — there are no optional remediation hints.
+ * This shape is the wire format the `mutate` DX surface returns to
+ * callers, so it MUST be stable, machine-parseable, AND human-readable.
+ *
+ * @example
+ * ```ts
+ * const err: ValidationError = {
+ *   path: '/title',
+ *   expected: 'string with minLength 1',
+ *   received: 'empty string',
+ *   fix: 'Provide a non-empty title (1-200 chars).',
+ *   errorCode: 'E_INPUT_MIN_LENGTH',
+ *   schemaPath: '#/properties/title/minLength',
+ * };
+ * ```
+ */
+export interface ValidationError {
+    /**
+     * RFC 6901 JSON Pointer to the failing input location, anchored at
+     * the root of the payload (e.g. `'/title'`, `'/owners/0/email'`).
+     * An empty string `''` denotes the root document itself.
+     */
+    path: string;
+    /**
+     * Human-readable description of what the validator expected at
+     * {@link ValidationError.path | path} (e.g. `'string'`,
+     * `'integer >= 0'`, `'one of: pending | active | done'`).
+     */
+    expected: string;
+    /**
+     * Human-readable description of what was actually received at
+     * {@link ValidationError.path | path}. NEVER includes the raw value
+     * itself — describes type/cardinality only — so logs of errors do
+     * not accidentally leak user payloads.
+     */
+    received: string;
+    /**
+     * Actionable, imperative remediation hint targeted at the caller
+     * (e.g. `'Provide a non-empty title (1-200 chars).'`). Surfaced
+     * directly in CLI output and validator return envelopes.
+     */
+    fix: string;
+    /**
+     * Stable, screaming-snake-case error code (e.g.
+     * `'E_INPUT_MIN_LENGTH'`, `'E_INPUT_REQUIRED'`). Stable across
+     * releases so callers can branch on it programmatically.
+     */
+    errorCode: string;
+    /**
+     * RFC 6901 JSON Pointer into the contract's
+     * {@link OperationInputContract.schema | schema} that produced the
+     * failure (e.g. `'#/properties/title/minLength'`). Lets tooling jump
+     * straight to the offending schema clause.
+     */
+    schemaPath: string;
+}
+/**
+ * Discriminated union returned by the input validator.
+ *
+ * Narrows on the `ok` boolean: when `ok === true`, the strongly-typed
+ * `value` is present; when `ok === false`, a non-empty `errors` array
+ * lists every failure (validators are encouraged to surface ALL errors
+ * in one pass, not bail on the first).
+ *
+ * @typeParam T - The validated, typed input shape produced on success.
+ *
+ * @example
+ * ```ts
+ * function handle(result: ValidationResult<{ title: string }>) {
+ *   if (result.ok) {
+ *     // result.value is { title: string }
+ *     return createTask(result.value);
+ *   }
+ *   // result.errors is ValidationError[]
+ *   for (const e of result.errors) {
+ *     console.error(`${e.path}: ${e.fix}`);
+ *   }
+ * }
+ * ```
+ */
+export type ValidationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly errors: ValidationError[];
+};
+/**
+ * Registry of every {@link OperationInputContract} known to the CLEO
+ * runtime, keyed by the contract's `operation` identifier (e.g.
+ * `'tasks.create'`).
+ *
+ * The value type uses `unknown` for the contract's generic so registry
+ * lookups stay assignable across operations with different input
+ * shapes. Callers that need the concrete `T` MUST narrow via an
+ * operation-specific accessor — direct `registry[op]` reads are
+ * intentionally not type-narrowed by operation name.
+ *
+ * @example
+ * ```ts
+ * const registry: OperationInputContractRegistry = {
+ *   'tasks.create': createTaskContract,
+ *   'docs.publish': publishDocsContract,
+ * };
+ *
+ * const contract = registry['tasks.create'];
+ * if (contract) {
+ *   // validate(contract, payload) → ValidationResult<unknown>
+ * }
+ * ```
+ */
+export type OperationInputContractRegistry = Record<string, OperationInputContract<unknown>>;
+//# sourceMappingURL=input-contract.d.ts.map

package/dist/operations/input-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.d.ts","sourceRoot":"","sources":["../../src/operations/input-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAC;IAET;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;CACnD;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAM/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC"}

package/dist/operations/input-contract.js

@@ -0,0 +1,29 @@
+/**
+ * OperationInputContract — schema-first input contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the schema-first input
+ * validation surface that powers the `mutate(operation, input)` DX
+ * (Saga T9855 / E7). Every CLEO operation that accepts structured input
+ * MUST be describable as an {@link OperationInputContract}: a JSON Schema
+ * draft-07 document, a stable operation identifier, and at least one
+ * worked example payload.
+ *
+ * Validators consume an {@link OperationInputContract} and produce a
+ * {@link ValidationResult} discriminated union — either the typed value
+ * (`ok: true`) or an array of {@link ValidationError} entries with
+ * actionable, JSON-Pointer-anchored remediation hints (`ok: false`).
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose alias {@link JsonSchema} so this
+ * module does not pull in a JSON Schema typings package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/input-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ *
+ * @epic T9855
+ * @task T9914
+ */
+export {};
+//# sourceMappingURL=input-contract.js.map

package/dist/operations/input-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.js","sourceRoot":"","sources":["../../src/operations/input-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}