@cleocode/core 2026.6.5 → 2026.6.7

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

@@ -0,0 +1,36 @@
+/**
+ * OUTPUT_CONTRACTS accessor — SSoT lookup for per-operation OUTPUT contracts.
+ *
+ * The OUTPUT-side mirror of {@link getInputContract}. The contract DATA lives
+ * in `@cleocode/contracts` (a leaf, zero-runtime-dep package) as
+ * {@link OUTPUT_CONTRACTS}; this module re-exports it and provides the null-safe
+ * accessor that the SDK `describeOperation` and the `cleo <op> --describe`
+ * 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.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/output-contracts
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+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.
+ *
+ * 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.
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation identifier.
+ * @returns The matching contract, or `null` when none is registered.
+ *
+ * @task T11692
+ */
+export declare function getOutputContract(operation: string): OperationOutputContract | null;
+//# sourceMappingURL=output-contracts.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,38 @@
+/**
+ * OUTPUT_CONTRACTS accessor — SSoT lookup for per-operation OUTPUT contracts.
+ *
+ * The OUTPUT-side mirror of {@link getInputContract}. The contract DATA lives
+ * in `@cleocode/contracts` (a leaf, zero-runtime-dep package) as
+ * {@link OUTPUT_CONTRACTS}; this module re-exports it and provides the null-safe
+ * accessor that the SDK `describeOperation` and the `cleo <op> --describe`
+ * 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.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/output-contracts
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+import { OUTPUT_CONTRACTS } from '@cleocode/contracts';
+export { OUTPUT_CONTRACTS };
+/**
+ * Resolve the {@link OperationOutputContract} for an operation id, or return
+ * `null` when no contract is registered.
+ *
+ * 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.
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation identifier.
+ * @returns The matching contract, or `null` when none is registered.
+ *
+ * @task T11692
+ */
+export function getOutputContract(operation) {
+    return OUTPUT_CONTRACTS[operation] ?? null;
+}
+//# sourceMappingURL=output-contracts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"output-contracts.js","sourceRoot":"","sources":["../../../src/dispatch/contracts/output-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAgC,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAErF,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,gBAAgB,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;AAC7C,CAAC"}

package/dist/dispatch/describe-operation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * describeOperation — SDK introspection of a CLEO operation's I/O contract.
+ *
+ * The programmatic counterpart to `cleo <op> --describe`. Given a canonical
+ * `<domain>.<verb>` operation id (e.g. `'tasks.show'`), composes a single
+ * typed {@link OperationDescriptor} from the three SSoT surfaces:
+ *
+ *   1. {@link OperationDef} (from `@cleocode/contracts`) — gateway, tier,
+ *      idempotency, session requirement, and the declared `params`.
+ *   2. The INPUT contract (`getInputContract`, T9918) — JSON Schema for the
+ *      accepted request payload + worked examples. The schemas set
+ *      `additionalProperties: false`, so unknown keys (e.g. `relates` on
+ *      `tasks.add-batch`) are rejected LOUDLY (DHQ-033).
+ *   3. The OUTPUT contract (`getOutputContract`, T11692) — JSON Schema for the
+ *      LAFS envelope's `data` payload + the curated list of valid `--field`
+ *      JSON pointers (DHQ-057). This is what lets an agent predict the result
+ *      shape instead of guessing (`/data/task/title`, NOT `/data/title`).
+ *
+ * This is the root fix for "agents cannot predict the envelope" (T11692):
+ * `--field` pointers, result parsing, and SDK consumers all resolve against
+ * ONE declared contract rather than hand-sniffing per verb.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/describe-operation
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+import { type OperationInputContract, type OperationOutputContract } from '@cleocode/contracts';
+import { type OperationSchema } from '@cleocode/lafs';
+/**
+ * Fully-resolved I/O contract for a single CLEO operation.
+ *
+ * Returned by {@link describeOperation}. Bundles the operation's identity, its
+ * parameter signature (`params`/`gates` via the LAFS schema), the INPUT
+ * contract, and the OUTPUT contract into one machine- and human-readable
+ * descriptor. `inputContract` / `outputContract` are `null` for operations not
+ * yet migrated to the schema-first surface — callers render the descriptor with
+ * a "no contract yet" note rather than failing.
+ */
+export interface OperationDescriptor {
+    /** Fully-qualified operation key, e.g. `"tasks.show"`. */
+    operation: string;
+    /** CQRS gateway — read-only (`"query"`) or state-modifying (`"mutate"`). */
+    gateway: 'query' | 'mutate';
+    /** One-line description of what the operation does. */
+    description: string;
+    /** Agent progressive-disclosure tier (0=basic, 1=memory/check, 2=full). */
+    tier: number;
+    /** Whether the operation is safe to retry. */
+    idempotent: boolean;
+    /** Whether the operation requires an active session. */
+    sessionRequired: boolean;
+    /**
+     * Parameter signature + declared precondition gates, derived from the LAFS
+     * {@link OperationSchema}. The authoritative human-readable param list.
+     */
+    params: OperationSchema;
+    /**
+     * Schema-first INPUT contract (JSON Schema + examples), or `null` when the
+     * operation has no registered input contract yet.
+     */
+    inputContract: OperationInputContract<unknown> | null;
+    /**
+     * Schema-first OUTPUT contract (envelope `data` JSON Schema + valid `--field`
+     * pointers), or `null` when the operation has no registered output contract
+     * yet.
+     */
+    outputContract: OperationOutputContract | null;
+}
+/**
+ * Describe a CLEO operation's full INPUT + OUTPUT contract.
+ *
+ * The SDK entry point behind `cleo <op> --describe`. Resolves the operation by
+ * its canonical `<domain>.<verb>` id and returns a single typed
+ * {@link OperationDescriptor}, or `null` when the operation id is unknown.
+ *
+ * Contract resolution prefers an inline contract carried on the
+ * {@link OperationDef} (`def.inputSchema` / `def.outputSchema`) and falls back
+ * to the SSoT registries (`getInputContract` / `getOutputContract`). This lets
+ * a definition self-describe while keeping the registries authoritative.
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation id (e.g. `"tasks.show"`).
+ * @returns The resolved descriptor, or `null` when the operation is unknown.
+ *
+ * @example
+ * ```ts
+ * import { describeOperation } from '@cleocode/core';
+ *
+ * const d = describeOperation('tasks.show');
+ * // d.outputContract.fieldPointers includes '/data/task/title'
+ * //   → the correct pointer; '/data/title' would E_FIELD_NOT_FOUND.
+ * ```
+ *
+ * @task T11692
+ */
+export declare function describeOperation(operation: string): OperationDescriptor | null;
+//# sourceMappingURL=describe-operation.d.ts.map

package/dist/dispatch/describe-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-operation.d.ts","sourceRoot":"","sources":["../../src/dispatch/describe-operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAuC,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI3F;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,wDAAwD;IACxD,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,MAAM,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,sBAAsB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACtD;;;;OAIG;IACH,cAAc,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAChD;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAoB/E"}

package/dist/dispatch/describe-operation.js

@@ -0,0 +1,101 @@
+/**
+ * describeOperation — SDK introspection of a CLEO operation's I/O contract.
+ *
+ * The programmatic counterpart to `cleo <op> --describe`. Given a canonical
+ * `<domain>.<verb>` operation id (e.g. `'tasks.show'`), composes a single
+ * typed {@link OperationDescriptor} from the three SSoT surfaces:
+ *
+ *   1. {@link OperationDef} (from `@cleocode/contracts`) — gateway, tier,
+ *      idempotency, session requirement, and the declared `params`.
+ *   2. The INPUT contract (`getInputContract`, T9918) — JSON Schema for the
+ *      accepted request payload + worked examples. The schemas set
+ *      `additionalProperties: false`, so unknown keys (e.g. `relates` on
+ *      `tasks.add-batch`) are rejected LOUDLY (DHQ-033).
+ *   3. The OUTPUT contract (`getOutputContract`, T11692) — JSON Schema for the
+ *      LAFS envelope's `data` payload + the curated list of valid `--field`
+ *      JSON pointers (DHQ-057). This is what lets an agent predict the result
+ *      shape instead of guessing (`/data/task/title`, NOT `/data/title`).
+ *
+ * This is the root fix for "agents cannot predict the envelope" (T11692):
+ * `--field` pointers, result parsing, and SDK consumers all resolve against
+ * ONE declared contract rather than hand-sniffing per verb.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/describe-operation
+ *
+ * @epic T11679
+ * @task T11692 — DHQ-057: per-operation output schema SSoT
+ */
+import { OPERATIONS, } from '@cleocode/contracts';
+import { describeOperation as describeParams } from '@cleocode/lafs';
+import { getInputContract } from './contracts/input-contracts.js';
+import { getOutputContract } from './contracts/output-contracts.js';
+/**
+ * Resolve the {@link OperationDef} for a canonical `<domain>.<verb>` key.
+ *
+ * The first dot separates domain from operation, so dotted operation names like
+ * `"complexity.estimate"` are handled correctly. When the key has no dot, an
+ * unambiguous single-domain match is returned (else `null`).
+ *
+ * @param operation - The operation id (e.g. `"tasks.show"`).
+ * @returns The matching {@link OperationDef}, or `null` if not found / ambiguous.
+ *
+ * @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;
+}
+/**
+ * Describe a CLEO operation's full INPUT + OUTPUT contract.
+ *
+ * The SDK entry point behind `cleo <op> --describe`. Resolves the operation by
+ * its canonical `<domain>.<verb>` id and returns a single typed
+ * {@link OperationDescriptor}, or `null` when the operation id is unknown.
+ *
+ * Contract resolution prefers an inline contract carried on the
+ * {@link OperationDef} (`def.inputSchema` / `def.outputSchema`) and falls back
+ * to the SSoT registries (`getInputContract` / `getOutputContract`). This lets
+ * a definition self-describe while keeping the registries authoritative.
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation id (e.g. `"tasks.show"`).
+ * @returns The resolved descriptor, or `null` when the operation is unknown.
+ *
+ * @example
+ * ```ts
+ * import { describeOperation } from '@cleocode/core';
+ *
+ * const d = describeOperation('tasks.show');
+ * // d.outputContract.fieldPointers includes '/data/task/title'
+ * //   → the correct pointer; '/data/title' would E_FIELD_NOT_FOUND.
+ * ```
+ *
+ * @task T11692
+ */
+export function describeOperation(operation) {
+    const def = resolveOperationDef(operation);
+    if (def === null)
+        return null;
+    const key = `${def.domain}.${def.operation}`;
+    const params = describeParams(def, { includeGates: true, includeExamples: true });
+    const inputContract = def.inputSchema ?? getInputContract(key);
+    const outputContract = def.outputSchema ?? getOutputContract(key);
+    return {
+        operation: key,
+        gateway: def.gateway,
+        description: def.description,
+        tier: def.tier,
+        idempotent: def.idempotent,
+        sessionRequired: def.sessionRequired,
+        params,
+        inputContract,
+        outputContract,
+    };
+}
+//# sourceMappingURL=describe-operation.js.map

package/dist/dispatch/describe-operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-operation.js","sourceRoot":"","sources":["../../src/dispatch/describe-operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,UAAU,GAIX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,iBAAiB,IAAI,cAAc,EAAwB,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AA2CpE;;;;;;;;;;;GAWG;AACH,SAAS,mBAAmB,CAAC,SAAiB;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;QACtE,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,GAAG,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;IAClF,MAAM,aAAa,GAAG,GAAG,CAAC,WAAW,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC/D,MAAM,cAAc,GAAG,GAAG,CAAC,YAAY,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAElE,OAAO;QACL,SAAS,EAAE,GAAG;QACd,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,MAAM;QACN,aAAa;QACb,cAAc;KACf,CAAC;AACJ,CAAC"}