@cleocode/contracts 2026.6.6 → 2026.6.8

package/src/operations/output-contract.ts

@@ -0,0 +1,140 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// OperationOutputContract
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * 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>;

package/src/operations/output-contracts-data.ts

@@ -0,0 +1,356 @@
+/**
+ * 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 {
+  OperationOutputContract,
+  OperationOutputContractRegistry,
+} from './output-contract.js';
+
+// ---------------------------------------------------------------------------
+// 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: OperationOutputContract = {
+  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: OperationOutputContract = {
+  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: OperationOutputContract = {
+  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).' },
+  },
+} as const;
+
+/**
+ * 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: OperationOutputContract = {
+  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: OperationOutputContract = {
+  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: OperationOutputContract = {
+  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: OperationOutputContract = {
+  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: OperationOutputContractRegistry = {
+  'tasks.show': tasksShowOutputContract,
+  'tasks.list': tasksListOutputContract,
+  'tasks.find': tasksFindOutputContract,
+  'tasks.add': tasksAddOutputContract,
+  'tasks.add-batch': tasksAddBatchOutputContract,
+  'tasks.update': tasksUpdateOutputContract,
+  'tasks.complete': tasksCompleteOutputContract,
+};

package/src/operations/tasks.ts

@@ -959,8 +959,18 @@ export interface TasksSyncLinksRemoveResult {
 export interface TasksCancelParams {
   taskId: string;
   reason?: string;
-  /** Explicit child handling mode. Defaults to 'block' so propagation is never implicit. */
-  children?: 'block' | 'cascade' | 'orphan';
+  /**
+   * Explicit child handling mode. Defaults to 'block' so propagation is never
+   * implicit. `reparent` moves the children under {@link reparentTo}; the
+   * legacy `orphan`/detach mode was removed by T11811 (it manufactured the
+   * exact orphan the containment guard rejects).
+   */
+  children?: 'block' | 'cascade' | 'reparent';
+  /**
+   * Target parent ID for the `reparent` strategy (T11811). REQUIRED when
+   * `children='reparent'`.
+   */
+  reparentTo?: string;
   /** Operator waiver for large cascade cancellation. */
   force?: boolean;
   /** Large-subtree cascade guard threshold. Defaults to 10 descendants. */
@@ -992,8 +1002,8 @@ export interface TasksCancelResult {
    */
   alreadyCancelled?: boolean;
   /** Explicit child handling mode applied by the operation. */
-  childStrategy?: 'block' | 'cascade' | 'orphan';
-  /** Child or descendant tasks affected by cascade/orphan handling. */
+  childStrategy?: 'block' | 'cascade' | 'reparent';
+  /** Child or descendant tasks affected by cascade/reparent handling. */
   affectedTasks?: string[];
   /** Count of affected child/descendant tasks. */
   affectedCount?: number;