@cleocode/contracts 2026.6.5 → 2026.6.7

package/dist/operations/__tests__/output-contracts.test.js

@@ -0,0 +1,103 @@
+/**
+ * Tests for the per-operation OUTPUT contract SSoT (T11692 / DHQ-057).
+ *
+ * Pins the proof-set of OUTPUT contracts and — critically — encodes the exact
+ * shape fact that produced the bug: `tasks.show` returns the task under `task`,
+ * so the canonical pointer is `/data/task/title`, NOT `/data/title`.
+ *
+ * Also validates that mutation contracts reflect the MinimalMutateEnvelope
+ * shape (string[] ids, NOT object arrays) and that tasks.find uses the
+ * { results, total } wrapper (NOT a bare array).
+ *
+ * @task T11692
+ * @epic T11679
+ */
+import { describe, expect, it } from 'vitest';
+import { OUTPUT_CONTRACTS } from '../output-contracts-data.js';
+describe('operations/output-contracts (T11692 · DHQ-057)', () => {
+    it('registers the high-traffic proof-set operations', () => {
+        for (const op of [
+            'tasks.show',
+            'tasks.list',
+            'tasks.find',
+            'tasks.add',
+            'tasks.add-batch',
+            'tasks.update',
+            'tasks.complete',
+        ]) {
+            expect(OUTPUT_CONTRACTS[op], `missing output contract for ${op}`).toBeDefined();
+        }
+    });
+    it('keys every entry by its own operation id', () => {
+        for (const [key, contract] of Object.entries(OUTPUT_CONTRACTS)) {
+            expect(contract.operation).toBe(key);
+        }
+    });
+    describe('tasks.show — the operation that bit us', () => {
+        const show = OUTPUT_CONTRACTS['tasks.show'];
+        it('encodes that the task is nested under `task` (data schema)', () => {
+            const schema = show.dataSchema;
+            expect(schema.required).toContain('task');
+            // The title lives under task.properties.title — NOT at the data root.
+            expect(schema.properties?.task?.properties).toHaveProperty('title');
+            expect(schema.properties).not.toHaveProperty('title');
+        });
+        it('lists /data/task/title as a valid --field pointer and NOT /data/title', () => {
+            expect(show.fieldPointers).toContain('/data/task/title');
+            expect(show.fieldPointers).not.toContain('/data/title');
+        });
+        it('carries a shapeNote steering agents away from /data/<field>', () => {
+            expect(show.shapeNote).toBeTruthy();
+            expect(show.shapeNote).toContain('/data/task/');
+        });
+        it('notes that view may be null', () => {
+            expect(show.shapeNote).toContain('null');
+        });
+    });
+    describe('mutation envelopes — MinimalMutateEnvelope (string[] ids, T9931)', () => {
+        it('tasks.add surfaces the created task ID as a bare string at /data/created/0', () => {
+            const add = OUTPUT_CONTRACTS['tasks.add'];
+            // Correct: /data/created/0 → "T11692" (string), NOT /data/created/0/id
+            expect(add.fieldPointers).toContain('/data/created/0');
+            expect(add.fieldPointers).not.toContain('/data/created/0/id');
+            // Schema must reflect string[] items, not object[]
+            const schema = add.dataSchema;
+            expect(schema.required).toEqual(expect.arrayContaining(['count', 'created', 'updated', 'deleted']));
+            expect(schema.properties?.created?.items?.type).toBe('string');
+            expect(schema.properties?.updated?.items?.type).toBe('string');
+            expect(schema.properties?.deleted?.items?.type).toBe('string');
+        });
+        it('tasks.update / tasks.complete surface the changed task ID at /data/updated/0 (string)', () => {
+            for (const op of ['tasks.update', 'tasks.complete']) {
+                const c = OUTPUT_CONTRACTS[op];
+                // Correct: /data/updated/0 → "T11692" (string), NOT /data/updated/0/id
+                expect(c.fieldPointers).toContain('/data/updated/0');
+                expect(c.fieldPointers).not.toContain('/data/updated/0/id');
+                const schema = c.dataSchema;
+                expect(schema.properties?.updated?.items?.type).toBe('string');
+            }
+        });
+        it('tasks.add-batch dry-run pointers point to root /data/wouldCreate and /data/insertedCount', () => {
+            const batch = OUTPUT_CONTRACTS['tasks.add-batch'];
+            // Correct: root-level, NOT /data/dryRunSummary/wouldCreate
+            expect(batch.fieldPointers).toContain('/data/wouldCreate');
+            expect(batch.fieldPointers).toContain('/data/insertedCount');
+            expect(batch.fieldPointers).not.toContain('/data/dryRunSummary/wouldCreate');
+            expect(batch.fieldPointers).not.toContain('/data/dryRunSummary/insertedCount');
+            // shapeNote should clarify they are NOT under dryRunSummary
+            expect(batch.shapeNote).toContain('/data/wouldCreate');
+        });
+    });
+    it('tasks.find data is a wrapper object with /data/results (array) and /data/total', () => {
+        const find = OUTPUT_CONTRACTS['tasks.find'];
+        // Correct: wrapper object, NOT a bare array
+        expect(find.dataSchema.type).toBe('object');
+        // Correct pointers
+        expect(find.fieldPointers).toContain('/data/results/0/id');
+        expect(find.fieldPointers).toContain('/data/total');
+        // Wrong pointers must NOT appear
+        expect(find.fieldPointers).not.toContain('/data/0/id');
+        expect(find.shapeNote).toContain('/data/results');
+    });
+});
+//# sourceMappingURL=output-contracts.test.js.map

package/dist/operations/__tests__/output-contracts.test.js.map

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

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

@@ -0,0 +1,127 @@
+/**
+ * OperationOutputContract — schema-first OUTPUT contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the per-operation OUTPUT
+ * (result) shape introspection surface (DHQ-057 · T11692 · EP-DHQ-CORE-FIXES
+ * T11679 · SG-CORE-SELF-TOOLING T11480). It is the OUTPUT-side mirror of
+ * {@link OperationInputContract}.
+ *
+ * ## Why this exists
+ *
+ * Before this contract, {@link OperationDef} declared INPUT (`params`) but had
+ * NO machine-readable description of the OUTPUT envelope's `data` payload.
+ * Consequently:
+ *
+ *   - `cleo show T123 --field /data/title` returned `E_FIELD_NOT_FOUND` because
+ *     the real shape is `/data/task/title` — agents had no way to predict the
+ *     envelope `data` shape and `--field` JSON pointers were guesswork.
+ *   - Every consumer (CLI `--field`, REST clients, the SDK) hand-sniffed the
+ *     result per verb instead of resolving against a declared contract.
+ *
+ * An {@link OperationOutputContract} pairs a stable operation identifier with
+ * the JSON Schema (draft-07) document describing the envelope's `data` payload
+ * AND the curated set of valid `--field` JSON pointers (rooted at `/data`) that
+ * an agent can use without trial and error.
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose {@link JsonSchema} alias (re-used from the
+ * input-contract module) so this module does not pull in a JSON Schema typings
+ * package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/output-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ * @see OperationInputContract — the INPUT-side mirror of this contract
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+import type { JsonSchema } from './input-contract.js';
+/**
+ * Schema-first OUTPUT (result) contract for a single CLEO operation.
+ *
+ * Pairs a stable operation identifier with the JSON Schema draft-07 document
+ * that describes the LAFS envelope's `data` payload, plus the curated list of
+ * valid `--field` JSON pointers an agent can rely on.
+ *
+ * The `dataSchema` describes the shape of `envelope.data` — i.e. the value the
+ * dispatch handler returns, BEFORE the LAFS `{ success, data, meta }` wrapper
+ * is applied. For example, `tasks.show` returns
+ * `{ task, view, attachments, acRows?, relations? }`, so its `dataSchema` has
+ * `task` as a required property and `/data/task/title` is the canonical pointer
+ * for the task title — NOT `/data/title`.
+ *
+ * @example
+ * ```ts
+ * const showOutput: OperationOutputContract = {
+ *   operation: 'tasks.show',
+ *   dataSchema: {
+ *     type: 'object',
+ *     required: ['task'],
+ *     properties: {
+ *       task: { type: 'object', description: 'Full task record' },
+ *       view: { type: ['object', 'null'] },
+ *       attachments: { type: 'array' },
+ *     },
+ *   },
+ *   fieldPointers: ['/data/task/id', '/data/task/title', '/data/task/status'],
+ * };
+ * ```
+ */
+export interface OperationOutputContract {
+    /**
+     * Stable, fully-qualified operation identifier in `<domain>.<verb>` form
+     * (e.g. `'tasks.show'`, `'tasks.add-batch'`). Used as the registry key in
+     * {@link OperationOutputContractRegistry}.
+     */
+    operation: string;
+    /**
+     * JSON Schema draft-07 document describing the shape of the LAFS envelope's
+     * `data` payload returned by this operation.
+     *
+     * This is the shape of `envelope.data` — the dispatch handler's return value
+     * BEFORE the `{ success, data, meta }` wrapper. Pointers used by `--field`
+     * are therefore rooted at `/data` (e.g. `/data/task/title` resolves against
+     * `dataSchema.properties.task.properties.title`).
+     */
+    dataSchema: JsonSchema;
+    /**
+     * Curated, copy-pasteable list of valid `--field` JSON pointers an agent can
+     * use without trial and error. Each pointer is rooted at the envelope root
+     * (`/data/...`), matching the resolution semantics of `cleo <op> --field`.
+     *
+     * This is the direct remediation for the `--field /data/title` →
+     * `E_FIELD_NOT_FOUND` class of failures: instead of guessing, an agent runs
+     * `cleo show --describe` and reads the exact pointers that resolve.
+     *
+     * Conventionally lists the high-value scalar/leaf pointers (ids, titles,
+     * statuses, counts) — not every possible deep pointer.
+     */
+    fieldPointers: string[];
+    /**
+     * Optional one-line note clarifying non-obvious shape facts (e.g. "task body
+     * is nested under `task`, not the root"). Surfaced in `--describe` output to
+     * pre-empt the exact mistakes this contract is designed to prevent.
+     */
+    shapeNote?: string;
+}
+/**
+ * Registry of every {@link OperationOutputContract} known to the CLEO runtime,
+ * keyed by the contract's `operation` identifier (e.g. `'tasks.show'`).
+ *
+ * The OUTPUT-side mirror of `OperationInputContractRegistry`. Populated
+ * incrementally — high-traffic operations first. A `null` lookup (operation
+ * absent from the registry) is expected and MUST NOT error: callers render a
+ * structured "no output contract yet" payload instead.
+ *
+ * @example
+ * ```ts
+ * const registry: OperationOutputContractRegistry = {
+ *   'tasks.show': showOutputContract,
+ *   'tasks.list': listOutputContract,
+ * };
+ * ```
+ */
+export type OperationOutputContractRegistry = Record<string, OperationOutputContract>;
+//# sourceMappingURL=output-contract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"output-contract.d.ts","sourceRoot":"","sources":["../../src/operations/output-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;OAQG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC"}

package/dist/operations/output-contract.js

@@ -0,0 +1,41 @@
+/**
+ * OperationOutputContract — schema-first OUTPUT contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the per-operation OUTPUT
+ * (result) shape introspection surface (DHQ-057 · T11692 · EP-DHQ-CORE-FIXES
+ * T11679 · SG-CORE-SELF-TOOLING T11480). It is the OUTPUT-side mirror of
+ * {@link OperationInputContract}.
+ *
+ * ## Why this exists
+ *
+ * Before this contract, {@link OperationDef} declared INPUT (`params`) but had
+ * NO machine-readable description of the OUTPUT envelope's `data` payload.
+ * Consequently:
+ *
+ *   - `cleo show T123 --field /data/title` returned `E_FIELD_NOT_FOUND` because
+ *     the real shape is `/data/task/title` — agents had no way to predict the
+ *     envelope `data` shape and `--field` JSON pointers were guesswork.
+ *   - Every consumer (CLI `--field`, REST clients, the SDK) hand-sniffed the
+ *     result per verb instead of resolving against a declared contract.
+ *
+ * An {@link OperationOutputContract} pairs a stable operation identifier with
+ * the JSON Schema (draft-07) document describing the envelope's `data` payload
+ * AND the curated set of valid `--field` JSON pointers (rooted at `/data`) that
+ * an agent can use without trial and error.
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose {@link JsonSchema} alias (re-used from the
+ * input-contract module) so this module does not pull in a JSON Schema typings
+ * package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/output-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ * @see OperationInputContract — the INPUT-side mirror of this contract
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+export {};
+//# sourceMappingURL=output-contract.js.map

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

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

package/dist/operations/output-contracts-data.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OUTPUT_CONTRACTS data — the proof-set of per-operation OUTPUT contracts.
+ *
+ * SSoT for the OUTPUT (result) shape of CLEO's highest-traffic operations
+ * (DHQ-057 · T11692). Each entry is an {@link OperationOutputContract}: a
+ * JSON Schema draft-07 document for the LAFS envelope's `data` payload plus
+ * the curated list of valid `--field` JSON pointers.
+ *
+ * Populated INCREMENTALLY — high-traffic operations first. This is the OUTPUT
+ * mirror of `INPUT_CONTRACTS` (which lives in core). The data lives here in
+ * `contracts` (a leaf package, zero runtime deps) so every consumer — CLI
+ * `--describe`, the SDK `describeOperation`, REST clients — resolves against
+ * one source of truth.
+ *
+ * Each `dataSchema` is grounded in the concrete result interface declared in
+ * `./tasks.js` (e.g. {@link TasksShowResult}, {@link MinimalMutateEnvelope}) so
+ * the schema can never drift from the typed shape without a compile-time touch
+ * to this file.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/output-contracts-data
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+import type { OperationOutputContractRegistry } from './output-contract.js';
+/**
+ * SSoT registry of per-operation OUTPUT contracts, keyed by the canonical
+ * `<domain>.<verb>` operation id. Extend this map as operations are migrated
+ * to the schema-first OUTPUT surface (high-traffic first).
+ *
+ * @task T11692
+ */
+export declare const OUTPUT_CONTRACTS: OperationOutputContractRegistry;
+//# sourceMappingURL=output-contracts-data.d.ts.map

package/dist/operations/output-contracts-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-contracts-data.d.ts","sourceRoot":"","sources":["../../src/operations/output-contracts-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAEV,+BAA+B,EAChC,MAAM,sBAAsB,CAAC;AAuT9B;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,+BAQ9B,CAAC"}

package/dist/operations/output-contracts-data.js

@@ -0,0 +1,328 @@
+/**
+ * OUTPUT_CONTRACTS data — the proof-set of per-operation OUTPUT contracts.
+ *
+ * SSoT for the OUTPUT (result) shape of CLEO's highest-traffic operations
+ * (DHQ-057 · T11692). Each entry is an {@link OperationOutputContract}: a
+ * JSON Schema draft-07 document for the LAFS envelope's `data` payload plus
+ * the curated list of valid `--field` JSON pointers.
+ *
+ * Populated INCREMENTALLY — high-traffic operations first. This is the OUTPUT
+ * mirror of `INPUT_CONTRACTS` (which lives in core). The data lives here in
+ * `contracts` (a leaf package, zero runtime deps) so every consumer — CLI
+ * `--describe`, the SDK `describeOperation`, REST clients — resolves against
+ * one source of truth.
+ *
+ * Each `dataSchema` is grounded in the concrete result interface declared in
+ * `./tasks.js` (e.g. {@link TasksShowResult}, {@link MinimalMutateEnvelope}) so
+ * the schema can never drift from the typed shape without a compile-time touch
+ * to this file.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/output-contracts-data
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+// ---------------------------------------------------------------------------
+// tasks.show — the operation that bit us (DHQ-057 reproduction)
+// ---------------------------------------------------------------------------
+/**
+ * OUTPUT contract for `tasks.show`.
+ *
+ * Grounded in {@link TasksShowResult}: `{ task, view, attachments, acRows?,
+ * relations? }`. The task body is nested under `task` — so the canonical
+ * pointer for the title is `/data/task/title`, NOT `/data/title`. This is the
+ * exact shape whose absence produced `cleo show --field /data/title` →
+ * `E_FIELD_NOT_FOUND`.
+ */
+const tasksShowOutputContract = {
+    operation: 'tasks.show',
+    shapeNote: 'The task record is nested under `task` — use /data/task/<field>, not /data/<field>. ' +
+        '`view` may be null. `acRows` and `relations` are conditional.',
+    dataSchema: {
+        type: 'object',
+        required: ['task', 'view', 'attachments'],
+        additionalProperties: true,
+        properties: {
+            task: {
+                type: 'object',
+                description: 'Full task record (id, title, status, priority, type, parentId, ...).',
+                required: ['id', 'title', 'status'],
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    status: { type: 'string' },
+                    priority: { type: 'string' },
+                    type: { type: 'string' },
+                    parentId: { type: ['string', 'null'] },
+                },
+            },
+            view: {
+                type: ['object', 'null'],
+                description: 'Canonical task view projection produced by computeTaskView. Null when unavailable.',
+            },
+            attachments: {
+                type: 'array',
+                description: 'Docs attachments linked to this task. Always an array (empty when none).',
+            },
+            acRows: {
+                type: 'array',
+                description: 'Acceptance-criterion rows (id, alias AC<n>, ordinal, text). Optional.',
+            },
+            relations: {
+                type: 'object',
+                description: 'Expanded relation/doc lists. Present only with --relations.',
+            },
+        },
+    },
+    fieldPointers: [
+        '/data/task/id',
+        '/data/task/title',
+        '/data/task/status',
+        '/data/task/priority',
+        '/data/task/type',
+        '/data/task/parentId',
+        '/data/view/id',
+        '/data/view/title',
+    ],
+};
+// ---------------------------------------------------------------------------
+// tasks.list — array-of-tasks plus counts
+// ---------------------------------------------------------------------------
+/**
+ * OUTPUT contract for `tasks.list`.
+ *
+ * Grounded in {@link TasksListResult}: `{ tasks: TaskOp[], total, filtered }`.
+ */
+const tasksListOutputContract = {
+    operation: 'tasks.list',
+    shapeNote: 'Rows are under /data/tasks (an array); counts are /data/total and /data/filtered.',
+    dataSchema: {
+        type: 'object',
+        required: ['tasks', 'total', 'filtered'],
+        additionalProperties: true,
+        properties: {
+            tasks: {
+                type: 'array',
+                description: 'Task rows matching the filters.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        status: { type: 'string' },
+                    },
+                },
+            },
+            total: { type: 'number', description: 'Total tasks before filtering.' },
+            filtered: { type: 'number', description: 'Number of tasks after filters applied.' },
+        },
+    },
+    fieldPointers: [
+        '/data/tasks/0/id',
+        '/data/tasks/0/title',
+        '/data/tasks/0/status',
+        '/data/total',
+        '/data/filtered',
+    ],
+};
+// ---------------------------------------------------------------------------
+// tasks.find — { results: MinimalTask[], total, query, searchType }
+// ---------------------------------------------------------------------------
+/**
+ * OUTPUT contract for `tasks.find`.
+ *
+ * Grounded in the actual return shape from `findTasks()` (find.ts:503-505)
+ * and the MVI projection plan (mvi-projection.ts:330 `path: 'results'`):
+ * `{ results: MinimalTask[], total: number, query: string, searchType: string }`.
+ *
+ * The `data` payload is a **wrapper object** (NOT a bare array). Results live
+ * under `/data/results`; the total count is at `/data/total`.
+ */
+const tasksFindOutputContract = {
+    operation: 'tasks.find',
+    shapeNote: 'Results are wrapped: /data/results (array of matches), /data/total (count). ' +
+        'Use /data/results/0/id — NOT /data/0/id.',
+    dataSchema: {
+        type: 'object',
+        required: ['results', 'total'],
+        additionalProperties: true,
+        properties: {
+            results: {
+                type: 'array',
+                description: 'Array of minimal task matches.',
+                items: {
+                    type: 'object',
+                    required: ['id', 'title'],
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        status: { type: 'string' },
+                    },
+                },
+            },
+            total: { type: 'number', description: 'Total matching tasks.' },
+            query: { type: 'string', description: 'The query string that was searched.' },
+            searchType: { type: 'string', description: 'Kind of search performed (fts, semantic, ...).' },
+        },
+    },
+    fieldPointers: [
+        '/data/results/0/id',
+        '/data/results/0/title',
+        '/data/results/0/status',
+        '/data/total',
+    ],
+};
+// ---------------------------------------------------------------------------
+// Mutation envelope shape (T9931 / T10608) — shared by add / add-batch /
+// update / complete / delete.
+//
+// DEFAULT (minimal) shape — what `--field` resolves against — is
+// `MinimalMutateEnvelope` from `mutate-projection.ts`:
+//   { count, created: string[], updated: string[], deleted: string[], ids: string[], ... }
+//
+// `created`, `updated`, and `deleted` contain BARE TASK ID STRINGS, not
+// objects. `/data/created/0` resolves to a string like "T11692" directly.
+// The object-array shape (`TaskMutationEnvelope`) is the `--full` shape only.
+// ---------------------------------------------------------------------------
+/**
+ * The shared JSON Schema for the minimal mutate projection envelope
+ * (`MinimalMutateEnvelope` — T9931 / mutate-projection.ts). `created`,
+ * `updated`, and `deleted` are always present arrays of **bare task ID strings**
+ * (not objects). The gateway populates only the relevant bucket. Pointers:
+ * - `/data/created/0` → first created task ID string (e.g. "T11692")
+ * - `/data/updated/0` → first updated task ID string
+ * - `/data/deleted/0` → first deleted task ID string
+ *
+ * This is the DEFAULT shape (applies unless caller passes `--full`).
+ */
+const TASK_MUTATION_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 by the mutation (bare strings, e.g. "T11692"). ' +
+                'Empty for update/delete-only mutations.',
+            items: { type: 'string' },
+        },
+        updated: {
+            type: 'array',
+            description: 'Task IDs updated by the mutation (bare strings). ' +
+                'Empty for create/delete-only mutations.',
+            items: { type: 'string' },
+        },
+        deleted: {
+            type: 'array',
+            description: 'Task IDs deleted by the mutation (bare strings). ' +
+                'Empty for create/update-only mutations.',
+            items: { type: 'string' },
+        },
+        ids: {
+            type: 'array',
+            description: 'Deprecated alias for the non-empty bucket. Prefer created/updated/deleted.',
+            items: { type: 'string' },
+        },
+        dryRun: { type: 'boolean', description: 'True when this was a preview-only mutation.' },
+        status: { type: 'string', description: 'Post-mutation task status (add/update/complete).' },
+    },
+};
+/**
+ * OUTPUT contract for `tasks.add`.
+ *
+ * Grounded in `MinimalMutateEnvelope` (mutate-projection.ts) — the created
+ * task ID lands as a bare string in `created[0]`.
+ * Use `/data/created/0` (a string like "T11692"), NOT `/data/created/0/id`.
+ */
+const tasksAddOutputContract = {
+    operation: 'tasks.add',
+    shapeNote: 'The created task ID (bare string) is at /data/created/0 — NOT /data/created/0/id. ' +
+        'Example: /data/created/0 → "T11692".',
+    dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+    fieldPointers: ['/data/created/0', '/data/count'],
+};
+/**
+ * OUTPUT contract for `tasks.add-batch`.
+ *
+ * Grounded in `MinimalMutateEnvelope` (mutate-projection.ts). For dry-run,
+ * `wouldCreate` and `insertedCount` are projected to the **root** of the
+ * envelope data (NOT under `dryRunSummary`) — confirmed in
+ * mutate-projection.ts lines 224/232.
+ */
+const tasksAddBatchOutputContract = {
+    operation: 'tasks.add-batch',
+    shapeNote: 'Atomic batch insert. Each created task ID (bare string) is in /data/created (array). ' +
+        'Dry-run projections are at root: /data/wouldCreate and /data/insertedCount (=0). ' +
+        'NOT under /data/dryRunSummary.',
+    dataSchema: {
+        type: 'object',
+        required: ['count', 'created', 'updated', 'deleted'],
+        additionalProperties: true,
+        properties: {
+            ...TASK_MUTATION_DATA_SCHEMA.properties,
+            wouldCreate: {
+                type: 'number',
+                description: 'Dry-run: predicted write count. Present only when dryRun=true.',
+            },
+            insertedCount: {
+                type: 'number',
+                description: 'Dry-run: always 0 (no DB write). Present only when dryRun=true.',
+            },
+            wouldAffect: {
+                type: 'number',
+                description: 'Dry-run: generic affected count. Present only when dryRun=true.',
+            },
+        },
+    },
+    fieldPointers: ['/data/created/0', '/data/count', '/data/wouldCreate', '/data/insertedCount'],
+};
+/**
+ * OUTPUT contract for `tasks.update` (and the `complete` alias, which is an
+ * update to `status: done`).
+ *
+ * Grounded in `MinimalMutateEnvelope` (mutate-projection.ts) — the changed
+ * task ID lands as a bare string in `updated[0]`.
+ * Use `/data/updated/0` (a string like "T11692"), NOT `/data/updated/0/id`.
+ */
+const tasksUpdateOutputContract = {
+    operation: 'tasks.update',
+    shapeNote: 'The updated task ID (bare string) is at /data/updated/0 — NOT /data/updated/0/id. ' +
+        'Use /data/status for the post-mutation status.',
+    dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+    fieldPointers: ['/data/updated/0', '/data/status', '/data/count'],
+};
+/**
+ * OUTPUT contract for `tasks.complete`.
+ *
+ * Identical envelope to `tasks.update` — completion is a status mutation that
+ * lands the task ID in `updated[0]` as a bare string.
+ */
+const tasksCompleteOutputContract = {
+    operation: 'tasks.complete',
+    shapeNote: 'Completion is a status mutation — the task ID (bare string) is at /data/updated/0 ' +
+        '(status=done). Use /data/status for the post-mutation status.',
+    dataSchema: { ...TASK_MUTATION_DATA_SCHEMA },
+    fieldPointers: ['/data/updated/0', '/data/status', '/data/count'],
+};
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * SSoT registry of per-operation OUTPUT contracts, keyed by the canonical
+ * `<domain>.<verb>` operation id. Extend this map as operations are migrated
+ * to the schema-first OUTPUT surface (high-traffic first).
+ *
+ * @task T11692
+ */
+export const OUTPUT_CONTRACTS = {
+    'tasks.show': tasksShowOutputContract,
+    'tasks.list': tasksListOutputContract,
+    'tasks.find': tasksFindOutputContract,
+    'tasks.add': tasksAddOutputContract,
+    'tasks.add-batch': tasksAddBatchOutputContract,
+    'tasks.update': tasksUpdateOutputContract,
+    'tasks.complete': tasksCompleteOutputContract,
+};
+//# sourceMappingURL=output-contracts-data.js.map