@cleocode/core 2026.6.11 → 2026.6.13

package/dist/dispatch/contracts/derive-output-contract.js

@@ -0,0 +1,347 @@
+/**
+ * deriveOutputContract — generic per-operation OUTPUT contract producer.
+ *
+ * Closes the COVERAGE half of DHQ-057 / T11692 (the symptom-fix half — the
+ * `--field` remediation loop — is ST-4). The hand-authored {@link OUTPUT_CONTRACTS}
+ * registry covers only the 7 highest-traffic `tasks.*` operations. Every other
+ * operation in the 411-row {@link OPERATIONS} registry has NO machine-readable
+ * description of its result `data` shape, so an agent asking `cleo <op>
+ * --describe` (or hitting `E_FIELD_NOT_FOUND` on a bad `--field` pointer) gets
+ * nothing back for ~404 ops.
+ *
+ * Rather than hand-write 404 more contracts (unmaintainable, drifts instantly),
+ * this module DERIVES an {@link OperationOutputContract} for an operation from
+ * three shape registries that ALREADY exist:
+ *
+ * | Source registry        | Home                     | Derives                                                  |
+ * |------------------------|--------------------------|----------------------------------------------------------|
+ * | {@link OPERATION_RESULT_SCHEMAS} | `@cleocode/contracts`  | precise top-level data keys for the 5 workgraph reads     |
+ * | {@link PROJECTION_PLANS}         | `./mvi-projection.js`  | the data PATH (`tasks.show→task`, `docs.list→attachments`) for projected reads |
+ * | {@link MUTATE_PROJECTION_PLANS}  | `./mutate-projection.js` | the shared `{count, created, updated, deleted}` shape — but ONLY for the 6 ops that actually project it |
+ *
+ * Resolution precedence inside {@link deriveOutputContract} (most-precise first):
+ *
+ *   1. workgraph result schema  → precise key-derived contract
+ *   2. read op with projection plan → path-rooted contract
+ *   3. mutate op WITH a {@link MUTATE_PROJECTION_PLANS} entry → shared
+ *      minimal-mutate contract. An unplanned `gateway==='mutate'` op is NOT
+ *      rewritten by the dispatch middleware (it returns its raw domain payload),
+ *      so it must NOT advertise `/data/created/0` — it falls through to (4).
+ *   4. any other registered op (unplanned mutate or plain query) → a GENERIC
+ *      object contract (data is an object; no specific `--field` pointers, but a
+ *      `shapeNote` telling the agent to `--full`/`--describe`).
+ *
+ * A `null` return means the operation is NOT in {@link OPERATIONS} at all
+ * (genuinely unknown). Per T10400 §6.3 R6.7 a `null` output contract is
+ * "unverified shape", NEVER an error — callers MUST treat it as absent, not
+ * throw.
+ *
+ * ## Boundary
+ *
+ * This producer lives in `core/src/dispatch` (NOT `contracts`) because it reads
+ * `PROJECTION_PLANS` / `MUTATE_PROJECTION_PLANS`, which are core-resident, and
+ * because it is a bodied runtime helper (the contracts-purity Gate 10 forbids
+ * net-new bodied functions in `contracts`). It is import-time side-effect-free:
+ * it builds nothing at module load, only on call.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/derive-output-contract
+ *
+ * @epic T11679
+ * @task T11762 ST-3 — DHQ-057: generic per-op output schema coverage backfill
+ */
+import { OPERATION_RESULT_SCHEMAS, OPERATIONS, } from '@cleocode/contracts';
+import { MUTATE_PROJECTION_PLANS } from '../mutate-projection.js';
+import { PROJECTION_PLANS } from '../mvi-projection.js';
+// ---------------------------------------------------------------------------
+// Operation-def resolution (mirrors describe-operation.ts:resolveOperationDef)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the {@link OperationDef} for a canonical `<domain>.<verb>` key.
+ *
+ * Mirrors `resolveOperationDef` in `describe-operation.ts`: an undotted key is
+ * matched by operation name only (and only when unambiguous); a dotted key is
+ * split at the FIRST dot into `<domain>.<rest>` so multi-segment operation
+ * names like `workgraph.audit` (key `tasks.workgraph.audit`) resolve correctly.
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation identifier.
+ * @returns The matching definition, or `null` when no operation matches.
+ *
+ * @internal
+ */
+function resolveOperationDef(operation) {
+    const dotIdx = operation.indexOf('.');
+    if (dotIdx === -1) {
+        const matches = OPERATIONS.filter((op) => op.operation === operation);
+        return matches.length === 1 ? (matches[0] ?? null) : null;
+    }
+    const domain = operation.slice(0, dotIdx);
+    const op = operation.slice(dotIdx + 1);
+    return OPERATIONS.find((o) => o.domain === domain && o.operation === op) ?? null;
+}
+// ---------------------------------------------------------------------------
+// 1. Workgraph result schemas → precise top-level-key contract
+// ---------------------------------------------------------------------------
+/**
+ * A Zod object schema exposes its top-level field map under `.shape`. The
+ * {@link OPERATION_RESULT_SCHEMAS} values are typed loosely (`safeParse` only),
+ * so this guard recovers the introspectable shape at runtime without coupling
+ * the derive module to a specific Zod typings import.
+ *
+ * @internal
+ */
+function readZodTopLevelKeys(schema) {
+    if (schema === null || typeof schema !== 'object')
+        return null;
+    const shape = schema.shape;
+    if (shape === null || typeof shape !== 'object')
+        return null;
+    const keys = Object.keys(shape);
+    return keys.length > 0 ? keys : null;
+}
+/**
+ * Derive a contract for a workgraph read whose result shape is contracted in
+ * {@link OPERATION_RESULT_SCHEMAS}. The top-level data keys become both the
+ * `dataSchema` properties and the `/data/<key>` field pointers.
+ *
+ * @internal
+ */
+function deriveFromResultSchema(operation) {
+    const schema = OPERATION_RESULT_SCHEMAS.get(operation);
+    if (schema === undefined)
+        return null;
+    const keys = readZodTopLevelKeys(schema);
+    if (keys === null) {
+        // Schema present but not introspectable — fall back to a generic object
+        // contract rather than dropping coverage for a known workgraph op.
+        return genericObjectContract(operation, 'workgraph result');
+    }
+    const properties = {};
+    for (const key of keys)
+        properties[key] = { type: 'object' };
+    return {
+        operation,
+        shapeNote: `Workgraph result — top-level keys: ${keys.join(', ')}. Pointers are rooted at /data/<key>.`,
+        dataSchema: {
+            type: 'object',
+            required: keys,
+            additionalProperties: true,
+            properties,
+        },
+        fieldPointers: keys.map((k) => `/data/${k}`),
+    };
+}
+// ---------------------------------------------------------------------------
+// 2. Projection-plan reads → path-rooted contract
+// ---------------------------------------------------------------------------
+/**
+ * Map a {@link ProjectionKind} to the secondary identity field that pairs with
+ * `id` in the derived field pointers.
+ *
+ * Task-shaped records (`task`/`epic`/`saga`) carry a `title`; doc-shaped records
+ * (`doc`) carry NO `title` — their human-readable handle is `slug` (see
+ * `AttachmentMetadata` and the doc MVI field-set in `mvi-projection.ts`, which
+ * expose `slug`/`description` but never `title`). Hardcoding `/title` for doc
+ * plans produced an invalid `--field /data/.../title` pointer that fails with
+ * `E_FIELD_NOT_FOUND` — the very class of failure this contract exists to
+ * prevent. `'unknown'` falls back to `title` (the generic record convention),
+ * matching the {@link GENERIC_MVI_FIELDS} routing keys.
+ *
+ * @internal
+ */
+function secondaryPointerField(kind) {
+    return kind === 'doc' ? 'slug' : 'title';
+}
+/**
+ * Derive a contract for a read op that has a {@link PROJECTION_PLANS} entry.
+ * The plan tells us WHERE the records live in `data` (`plan.path`) and whether
+ * the payload at that path is a list. We root the field pointers there:
+ *
+ *   - task-kind list plan  → `/data/<path>/0/id`, `/data/<path>/0/title`
+ *   - doc-kind list plan   → `/data/<path>/0/id`, `/data/<path>/0/slug`
+ *   - single plan          → `/data/<path>/id`, `/data/<path>/{title|slug}`
+ *   - `$` path             → records are the data root itself.
+ *
+ * The secondary pointer is chosen per {@link ProjectionKind}
+ * ({@link secondaryPointerField}): task-shaped records expose `title`, doc
+ * records expose `slug` (they have no `title`).
+ *
+ * @internal
+ */
+function deriveFromProjectionPlan(operation, plan) {
+    const atRoot = plan.path === '$';
+    const base = atRoot ? '/data' : `/data/${plan.path}`;
+    const recordPointer = plan.list ? `${base}/0` : base;
+    const secondaryField = secondaryPointerField(plan.kind);
+    const fieldPointers = [`${recordPointer}/id`, `${recordPointer}/${secondaryField}`];
+    const recordSchema = {
+        type: 'object',
+        description: `A ${plan.kind} record.`,
+    };
+    const pathValueSchema = plan.list
+        ? { type: 'array', items: recordSchema, description: `Array of ${plan.kind} records.` }
+        : recordSchema;
+    const dataSchema = atRoot
+        ? pathValueSchema
+        : {
+            type: 'object',
+            required: [plan.path],
+            additionalProperties: true,
+            properties: { [plan.path]: pathValueSchema },
+        };
+    const shapeNote = atRoot
+        ? `Records (${plan.kind}) are the /data ${plan.list ? 'array' : 'object'} itself.`
+        : `Records (${plan.kind}) are under /data/${plan.path}${plan.list ? ' (array)' : ''}. ` +
+            `Use ${recordPointer}/<field>.`;
+    return { operation, shapeNote, dataSchema, fieldPointers };
+}
+// ---------------------------------------------------------------------------
+// 3. Mutate ops → shared MinimalMutateEnvelope contract
+// ---------------------------------------------------------------------------
+/**
+ * The shared `data` schema for the minimal mutate projection envelope
+ * (`MinimalMutateEnvelope` — mutate-projection.ts). `created`/`updated`/
+ * `deleted` are arrays of BARE TASK ID STRINGS (not objects), so
+ * `/data/created/0` resolves to e.g. `"T11692"` directly.
+ *
+ * @internal
+ */
+const MINIMAL_MUTATE_DATA_SCHEMA = {
+    type: 'object',
+    required: ['count', 'created', 'updated', 'deleted'],
+    additionalProperties: true,
+    properties: {
+        count: { type: 'number', description: 'Number of records the mutation affected.' },
+        created: {
+            type: 'array',
+            description: 'Task IDs created (bare strings, e.g. "T11692"). Empty for update/delete-only.',
+            items: { type: 'string' },
+        },
+        updated: {
+            type: 'array',
+            description: 'Task IDs updated (bare strings). Empty for create/delete-only.',
+            items: { type: 'string' },
+        },
+        deleted: {
+            type: 'array',
+            description: 'Task IDs deleted (bare strings). Empty for create/update-only.',
+            items: { type: 'string' },
+        },
+        ids: {
+            type: 'array',
+            description: 'Deprecated alias for the non-empty bucket. Prefer created/updated/deleted.',
+            items: { type: 'string' },
+        },
+    },
+};
+/**
+ * Derive the shared minimal-mutate-envelope contract for a mutate op that
+ * actually projects the `{count, created[], updated[], deleted[]}` shape.
+ *
+ * IMPORTANT: only the 6 ops with a {@link MUTATE_PROJECTION_PLANS} entry
+ * (`tasks.add`, `tasks.add-batch`, `tasks.saga.create`, `tasks.update`,
+ * `tasks.complete`, `tasks.delete`) are rewritten into the minimal envelope by
+ * the dispatch middleware — `applyMutateProjection` / `mutate-minimal-envelope`
+ * return the RAW domain payload untouched for every unplanned mutate op. The
+ * caller ({@link deriveOutputContract}) therefore gates this on plan presence;
+ * the ~169 unplanned mutate ops (`memory.observe`, `session.start`, `docs.add`,
+ * `release.plan`, …) fall through to {@link genericObjectContract} so we never
+ * advertise `/data/created/0` for a result that does not carry it.
+ *
+ * @internal
+ */
+function deriveMutateContract(operation) {
+    return {
+        operation,
+        shapeNote: 'Mutate envelope: affected task IDs are bare strings under /data/created, ' +
+            '/data/updated, or /data/deleted (e.g. /data/created/0 → "T11692"). /data/count is the total. ' +
+            'Pass --full for the verbose post-mutation record.',
+        dataSchema: { ...MINIMAL_MUTATE_DATA_SCHEMA },
+        fieldPointers: ['/data/count', '/data/created/0', '/data/updated/0', '/data/deleted/0'],
+    };
+}
+// ---------------------------------------------------------------------------
+// 4. Generic fallback — any other registered query op
+// ---------------------------------------------------------------------------
+/**
+ * Derive a GENERIC object contract for a registered query op that has neither a
+ * workgraph result schema nor a projection plan. This keeps coverage high (most
+ * read ops return an object `data`) while being honest that the precise shape is
+ * not contracted: no specific `--field` pointers, just a `shapeNote` pointing
+ * the agent at `--describe` / `--full`.
+ *
+ * @internal
+ */
+function genericObjectContract(operation, kindHint = 'query') {
+    return {
+        operation,
+        shapeNote: `Generic ${kindHint} result — the precise /data shape is not individually contracted. ` +
+            'Run with --full to see the verbose record, or --describe for the operation contract.',
+        dataSchema: { type: 'object', additionalProperties: true },
+        fieldPointers: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Public producer
+// ---------------------------------------------------------------------------
+/**
+ * Derive an {@link OperationOutputContract} for an operation from the existing
+ * shape registries, or `null` when the operation is genuinely unknown.
+ *
+ * Used as the SECOND tier of {@link getOutputContract}'s resolution order
+ * (hand-authored {@link OUTPUT_CONTRACTS} → `deriveOutputContract` → `null`).
+ * The hand-authored 7 stay authoritative; this lifts coverage to near-100% for
+ * the remaining ~404 ops without hand-authoring sprawl.
+ *
+ * Resolution precedence (most-precise first): workgraph result schema →
+ * projection-plan read → planned mutate op → generic registered op (unplanned
+ * mutate or plain query) → `null`.
+ *
+ * A `null` return MUST be treated as "no contract / unverified shape", NOT an
+ * error (T10400 §6.3 R6.7).
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation identifier.
+ * @returns A derived contract, or `null` when the operation is not registered.
+ *
+ * @example
+ * ```ts
+ * deriveOutputContract('tasks.tree');        // precise workgraph keys
+ * deriveOutputContract('tasks.show');        // projection-plan path (`task`)
+ * deriveOutputContract('tasks.add');         // shared minimal-mutate envelope (planned)
+ * deriveOutputContract('memory.observe');    // generic object (UNPLANNED mutate)
+ * deriveOutputContract('session.start');     // generic object contract
+ * deriveOutputContract('does.not-exist');    // null
+ * ```
+ *
+ * @task T11762 ST-3
+ */
+export function deriveOutputContract(operation) {
+    const def = resolveOperationDef(operation);
+    if (def === null)
+        return null;
+    // Re-derive the canonical key from the resolved def so a non-canonical input
+    // (e.g. an undotted unambiguous op name) still yields canonical pointers.
+    const key = `${def.domain}.${def.operation}`;
+    // 1. Precise workgraph result schema.
+    const fromSchema = deriveFromResultSchema(key);
+    if (fromSchema !== null)
+        return fromSchema;
+    // 2. Read op with a projection plan.
+    const plan = PROJECTION_PLANS[key];
+    if (plan !== undefined)
+        return deriveFromProjectionPlan(key, plan);
+    // 3. Mutate op that ACTUALLY projects the minimal-mutate envelope. Only the
+    //    ops with a MUTATE_PROJECTION_PLANS entry are rewritten into
+    //    `{count, created[], updated[], deleted[]}` by the dispatch middleware;
+    //    every other `gateway==='mutate'` op returns its own domain-specific
+    //    result shape untouched, so advertising `/data/created/0` for them would
+    //    steer agents at a pointer that resolves nothing (DHQ-057 loop).
+    if (def.gateway === 'mutate' && MUTATE_PROJECTION_PLANS[key] !== undefined) {
+        return deriveMutateContract(key);
+    }
+    // 4. Any other registered op (unplanned mutate or plain query) → generic
+    //    object contract: honest "shape not individually contracted" rather than
+    //    a misleading pointer set.
+    return genericObjectContract(key);
+}
+//# sourceMappingURL=derive-output-contract.js.map

package/dist/dispatch/contracts/derive-output-contract.js.map

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

package/dist/dispatch/contracts/ensures-schema.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Ensures-schema accessors — the bodied lookup layer over the cantbook
+ * `ensures.schema` Zod registry (T11762 ST-1b · Lane A).
+ *
+ * ## Why this lives in `core` (not `contracts`)
+ *
+ * The Zod schemas, the {@link EnsuresSchemaSpec} type, and the registry DATA
+ * ({@link ENSURES_SCHEMA_REGISTRY}) live in the `@cleocode/contracts` leaf
+ * package (ST-1) because those are exactly the Gate-10
+ * (`lint-no-runtime-in-contracts`)-ALLOWED kinds. A `Map.get` accessor, by
+ * contrast, is a net-new bodied runtime helper — NOT a type guard, Zod schema,
+ * or `as const` data — and so MUST NOT live in `contracts` (it would trip the
+ * contracts-purity gate). It is housed here in `core`, mirroring the
+ * `getOutputContract` / `getInputContract` precedent in this same directory.
+ *
+ * The playbook runtime (`packages/playbooks/src/runtime.ts`, ST-2) imports these
+ * accessors from `@cleocode/core` (already a playbooks dependency) to resolve a
+ * declared `ensures.schema` name → its Zod validator, replacing the historical
+ * hardcoded `if (schema === 'task_tree') … else if (=== 'evidence')` block.
+ *
+ * Import-time side-effect-free: this module only constructs a mutable working
+ * copy of the immutable contracts registry at module load. No I/O, no global
+ * state mutation beyond the module-local `REGISTRY` map.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/ensures-schema
+ *
+ * @epic T11762 — E-OUTPUT-SCHEMA-ENFORCEMENT
+ * @task T11901 — ST-1b: ensures-schema accessors in core
+ * @see ENSURES_SCHEMA_REGISTRY — the contracts-resident registry DATA (ST-1)
+ */
+import { type EnsuresSchemaSpec } from '@cleocode/contracts';
+export type { EnsuresSchemaSpec };
+/**
+ * Resolve a registered `ensures.schema` spec by its declared name.
+ *
+ * The playbook runtime calls this with a node's `ensures.schema` value; a
+ * `null` result signals an UNKNOWN schema name, which the runtime treats as a
+ * fail-closed contract violation (it no longer silently skips unknown names —
+ * AC1/AC2).
+ *
+ * @param name - The `ensures.schema:` name declared in a `.cantbook`
+ *   (e.g. `'task_tree'`, `'evidence'`).
+ * @returns The matching {@link EnsuresSchemaSpec}, or `null` when no schema is
+ *   registered under that name.
+ *
+ * @task T11901
+ */
+export declare function getEnsuresSchema(name: string): EnsuresSchemaSpec | null;
+/**
+ * Enumerate every registered `ensures.schema` name.
+ *
+ * Used by the runtime's fail-closed path to list the valid schema set in the
+ * violation message (so a `.cantbook` author sees which names are accepted),
+ * and by the parity tests to assert the registered set.
+ *
+ * @returns A read-only array of all registered schema names.
+ *
+ * @task T11901
+ */
+export declare function listEnsuresSchemaNames(): readonly string[];
+/**
+ * Register (or override) an `ensures.schema` spec by name.
+ *
+ * Genkit-shaped registration alias provided for a future Genkit
+ * `ai.defineSchema(name, zodSchema)` bridge (T11768): that bridge re-registers
+ * the SAME named Zod schemas as a thin adapter over this SSoT, never as a
+ * competing source. Mutates only the module-local working {@link REGISTRY}, not
+ * the immutable contracts data.
+ *
+ * @param spec - The {@link EnsuresSchemaSpec} to register; an existing entry with
+ *   the same {@link EnsuresSchemaSpec.name | name} is replaced.
+ *
+ * @task T11901
+ */
+export declare function defineEnsuresSchema(spec: EnsuresSchemaSpec): void;
+//# sourceMappingURL=ensures-schema.d.ts.map

package/dist/dispatch/contracts/ensures-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensures-schema.d.ts","sourceRoot":"","sources":["../../../src/dispatch/contracts/ensures-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEtF,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAYlC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAEvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAEjE"}

package/dist/dispatch/contracts/ensures-schema.js

@@ -0,0 +1,91 @@
+/**
+ * Ensures-schema accessors — the bodied lookup layer over the cantbook
+ * `ensures.schema` Zod registry (T11762 ST-1b · Lane A).
+ *
+ * ## Why this lives in `core` (not `contracts`)
+ *
+ * The Zod schemas, the {@link EnsuresSchemaSpec} type, and the registry DATA
+ * ({@link ENSURES_SCHEMA_REGISTRY}) live in the `@cleocode/contracts` leaf
+ * package (ST-1) because those are exactly the Gate-10
+ * (`lint-no-runtime-in-contracts`)-ALLOWED kinds. A `Map.get` accessor, by
+ * contrast, is a net-new bodied runtime helper — NOT a type guard, Zod schema,
+ * or `as const` data — and so MUST NOT live in `contracts` (it would trip the
+ * contracts-purity gate). It is housed here in `core`, mirroring the
+ * `getOutputContract` / `getInputContract` precedent in this same directory.
+ *
+ * The playbook runtime (`packages/playbooks/src/runtime.ts`, ST-2) imports these
+ * accessors from `@cleocode/core` (already a playbooks dependency) to resolve a
+ * declared `ensures.schema` name → its Zod validator, replacing the historical
+ * hardcoded `if (schema === 'task_tree') … else if (=== 'evidence')` block.
+ *
+ * Import-time side-effect-free: this module only constructs a mutable working
+ * copy of the immutable contracts registry at module load. No I/O, no global
+ * state mutation beyond the module-local `REGISTRY` map.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/ensures-schema
+ *
+ * @epic T11762 — E-OUTPUT-SCHEMA-ENFORCEMENT
+ * @task T11901 — ST-1b: ensures-schema accessors in core
+ * @see ENSURES_SCHEMA_REGISTRY — the contracts-resident registry DATA (ST-1)
+ */
+import { ENSURES_SCHEMA_REGISTRY } from '@cleocode/contracts';
+/**
+ * Module-local mutable working copy of the immutable contracts registry.
+ *
+ * Seeded from {@link ENSURES_SCHEMA_REGISTRY} (a `ReadonlyMap`). A mutable copy
+ * is held so {@link defineEnsuresSchema} can register additional specs at
+ * runtime (e.g. a future Genkit `ai.defineSchema` bridge — T11768) without
+ * mutating the shared frozen contracts data.
+ */
+const REGISTRY = new Map(ENSURES_SCHEMA_REGISTRY);
+/**
+ * Resolve a registered `ensures.schema` spec by its declared name.
+ *
+ * The playbook runtime calls this with a node's `ensures.schema` value; a
+ * `null` result signals an UNKNOWN schema name, which the runtime treats as a
+ * fail-closed contract violation (it no longer silently skips unknown names —
+ * AC1/AC2).
+ *
+ * @param name - The `ensures.schema:` name declared in a `.cantbook`
+ *   (e.g. `'task_tree'`, `'evidence'`).
+ * @returns The matching {@link EnsuresSchemaSpec}, or `null` when no schema is
+ *   registered under that name.
+ *
+ * @task T11901
+ */
+export function getEnsuresSchema(name) {
+    return REGISTRY.get(name) ?? null;
+}
+/**
+ * Enumerate every registered `ensures.schema` name.
+ *
+ * Used by the runtime's fail-closed path to list the valid schema set in the
+ * violation message (so a `.cantbook` author sees which names are accepted),
+ * and by the parity tests to assert the registered set.
+ *
+ * @returns A read-only array of all registered schema names.
+ *
+ * @task T11901
+ */
+export function listEnsuresSchemaNames() {
+    return [...REGISTRY.keys()];
+}
+/**
+ * Register (or override) an `ensures.schema` spec by name.
+ *
+ * Genkit-shaped registration alias provided for a future Genkit
+ * `ai.defineSchema(name, zodSchema)` bridge (T11768): that bridge re-registers
+ * the SAME named Zod schemas as a thin adapter over this SSoT, never as a
+ * competing source. Mutates only the module-local working {@link REGISTRY}, not
+ * the immutable contracts data.
+ *
+ * @param spec - The {@link EnsuresSchemaSpec} to register; an existing entry with
+ *   the same {@link EnsuresSchemaSpec.name | name} is replaced.
+ *
+ * @task T11901
+ */
+export function defineEnsuresSchema(spec) {
+    REGISTRY.set(spec.name, spec);
+}
+//# sourceMappingURL=ensures-schema.js.map

package/dist/dispatch/contracts/ensures-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensures-schema.js","sourceRoot":"","sources":["../../../src/dispatch/contracts/ensures-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,uBAAuB,EAA0B,MAAM,qBAAqB,CAAC;AAItF;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAA4B,uBAAuB,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/dist/dispatch/contracts/output-contracts.d.ts

@@ -8,29 +8,51 @@
  * surface consult.
  *
  * Keyed by the canonical `<domain>.<verb>` operation identifier (e.g.
- * `'tasks.show'`). A `null` lookup is expected (the registry is populated
- * incrementally, high-traffic ops first) and MUST NOT error.
+ * `'tasks.show'`). A `null` lookup is expected (a genuinely-unregistered op)
+ * and MUST NOT error.
+ *
+ * ## Resolution order (T11762 ST-3)
+ *
+ * The accessor resolves a contract in two tiers, most-authoritative first:
+ *
+ *   1. **Hand-authored** — the 7 high-traffic `tasks.*` entries in
+ *      {@link OUTPUT_CONTRACTS}. These are precise and stay authoritative.
+ *   2. **Derived** — {@link deriveOutputContract} synthesises a contract from
+ *      existing shape registries (`OPERATION_RESULT_SCHEMAS`, `PROJECTION_PLANS`,
+ *      `MinimalMutateEnvelope`) so the remaining ~404 operations resolve a
+ *      contract without hand-authoring sprawl (closes the DHQ-057 coverage gap).
+ *   3. **`null`** — the operation is not registered at all.
  *
  * @packageDocumentation
  * @module @cleocode/core/dispatch/contracts/output-contracts
  *
  * @epic T11679
  * @task T11692 — DHQ-057: per-operation output schema SSoT
+ * @task T11762 ST-3 — generic per-op output schema coverage backfill
  */
 import { type OperationOutputContract, OUTPUT_CONTRACTS } from '@cleocode/contracts';
 export { OUTPUT_CONTRACTS };
 /**
  * Resolve the {@link OperationOutputContract} for an operation id, or return
- * `null` when no contract is registered.
+ * `null` when no contract can be resolved.
  *
  * Used by the SDK `describeOperation` and the `cleo <op> --describe`
  * introspection surface to render the result-shape contract (data schema +
- * valid `--field` pointers). Mirrors {@link getInputContract} exactly.
+ * valid `--field` pointers). Mirrors {@link getInputContract} exactly, with the
+ * addition of the derived tier (T11762 ST-3).
+ *
+ * Resolution order: hand-authored {@link OUTPUT_CONTRACTS}[op] →
+ * {@link deriveOutputContract}(op) → `null`. The hand-authored contracts stay
+ * authoritative; the derived tier lifts coverage to near-100% for ops that lack
+ * a bespoke entry. A `null` result is "no contract / unverified shape", never an
+ * error.
  *
  * @param operation - Canonical `<domain>.<verb>` operation identifier.
- * @returns The matching contract, or `null` when none is registered.
+ * @returns The matching contract (hand-authored or derived), or `null` when the
+ *          operation is not registered.
  *
  * @task T11692
+ * @task T11762 ST-3
  */
 export declare function getOutputContract(operation: string): OperationOutputContract | null;
 //# sourceMappingURL=output-contracts.d.ts.map

package/dist/dispatch/contracts/output-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output-contracts.d.ts","sourceRoot":"","sources":["../../../src/dispatch/contracts/output-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAErF,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAEnF"}
+{"version":3,"file":"output-contracts.d.ts","sourceRoot":"","sources":["../../../src/dispatch/contracts/output-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGrF,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAEnF"}

package/dist/dispatch/contracts/output-contracts.js

@@ -8,31 +8,54 @@
  * surface consult.
  *
  * Keyed by the canonical `<domain>.<verb>` operation identifier (e.g.
- * `'tasks.show'`). A `null` lookup is expected (the registry is populated
- * incrementally, high-traffic ops first) and MUST NOT error.
+ * `'tasks.show'`). A `null` lookup is expected (a genuinely-unregistered op)
+ * and MUST NOT error.
+ *
+ * ## Resolution order (T11762 ST-3)
+ *
+ * The accessor resolves a contract in two tiers, most-authoritative first:
+ *
+ *   1. **Hand-authored** — the 7 high-traffic `tasks.*` entries in
+ *      {@link OUTPUT_CONTRACTS}. These are precise and stay authoritative.
+ *   2. **Derived** — {@link deriveOutputContract} synthesises a contract from
+ *      existing shape registries (`OPERATION_RESULT_SCHEMAS`, `PROJECTION_PLANS`,
+ *      `MinimalMutateEnvelope`) so the remaining ~404 operations resolve a
+ *      contract without hand-authoring sprawl (closes the DHQ-057 coverage gap).
+ *   3. **`null`** — the operation is not registered at all.
  *
  * @packageDocumentation
  * @module @cleocode/core/dispatch/contracts/output-contracts
  *
  * @epic T11679
  * @task T11692 — DHQ-057: per-operation output schema SSoT
+ * @task T11762 ST-3 — generic per-op output schema coverage backfill
  */
 import { OUTPUT_CONTRACTS } from '@cleocode/contracts';
+import { deriveOutputContract } from './derive-output-contract.js';
 export { OUTPUT_CONTRACTS };
 /**
  * Resolve the {@link OperationOutputContract} for an operation id, or return
- * `null` when no contract is registered.
+ * `null` when no contract can be resolved.
  *
  * Used by the SDK `describeOperation` and the `cleo <op> --describe`
  * introspection surface to render the result-shape contract (data schema +
- * valid `--field` pointers). Mirrors {@link getInputContract} exactly.
+ * valid `--field` pointers). Mirrors {@link getInputContract} exactly, with the
+ * addition of the derived tier (T11762 ST-3).
+ *
+ * Resolution order: hand-authored {@link OUTPUT_CONTRACTS}[op] →
+ * {@link deriveOutputContract}(op) → `null`. The hand-authored contracts stay
+ * authoritative; the derived tier lifts coverage to near-100% for ops that lack
+ * a bespoke entry. A `null` result is "no contract / unverified shape", never an
+ * error.
  *
  * @param operation - Canonical `<domain>.<verb>` operation identifier.
- * @returns The matching contract, or `null` when none is registered.
+ * @returns The matching contract (hand-authored or derived), or `null` when the
+ *          operation is not registered.
  *
  * @task T11692
+ * @task T11762 ST-3
  */
 export function getOutputContract(operation) {
-    return OUTPUT_CONTRACTS[operation] ?? null;
+    return OUTPUT_CONTRACTS[operation] ?? deriveOutputContract(operation) ?? null;
 }
 //# sourceMappingURL=output-contracts.js.map