@cleocode/contracts 2026.6.6 → 2026.6.8

package/dist/__tests__/operation-def.test.js.map

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

package/dist/db-recovery.d.ts

@@ -138,4 +138,67 @@ export interface BackupRecoverResult {
      */
     dryRun: boolean;
 }
+/**
+ * Per-role outcome of a `cleo doctor repair` pass (T11829 · DHQ-060).
+ *
+ * `doctor repair` first PROBES each role's live DB via `PRAGMA quick_check`
+ * (the same probe the recovery pipeline runs on snapshot candidates) and only
+ * invokes the {@link recoverMalformedDb} → quarantine → restore-from-snapshot →
+ * verify pipeline for roles that are actually malformed. This record captures
+ * what was observed and done for one role.
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairRoleResult {
+    /** Canonical role inspected. */
+    role: DbRole;
+    /** Absolute path to the role's live DB file (resolved from `DB_INVENTORY`). */
+    dbPath: string;
+    /** `true` when the live DB file exists on disk. */
+    present: boolean;
+    /**
+     * `true` when the live DB passed `PRAGMA quick_check` (or was absent) — i.e.
+     * NO repair was needed. `false` when corruption was detected.
+     */
+    healthy: boolean;
+    /**
+     * `'skipped'` — healthy or absent, nothing done;
+     * `'would-repair'` — `--dry-run`, corruption detected, repair NOT performed;
+     * `'repaired'` — corruption detected and snapshot restore succeeded;
+     * `'failed'` — corruption detected but recovery could not complete.
+     */
+    action: 'skipped' | 'would-repair' | 'repaired' | 'failed';
+    /** Absolute path to the snapshot restored (or that would be), when applicable. */
+    restoredFrom: string | null;
+    /** Absolute path to the quarantined corrupt DB, when a repair was performed. */
+    quarantinedTo: string | null;
+    /** Approximate data-loss window in hours, when a snapshot timestamp was parsed. */
+    dataLossWindowHours: number | null;
+    /** Human-readable detail (probe outcome, error reason, or restore summary). */
+    detail: string;
+}
+/**
+ * Aggregate result of a `cleo doctor repair` invocation across one or more roles
+ * (T11829 · DHQ-060).
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairResult {
+    /** `true` when the run was a `--dry-run` (no files mutated). */
+    dryRun: boolean;
+    /** Per-role outcomes. */
+    roles: DoctorRepairRoleResult[];
+    /** Count of roles found malformed (`!healthy`). */
+    malformedCount: number;
+    /** Count of roles actually repaired this run. */
+    repairedCount: number;
+    /** Count of roles where a needed repair FAILED. */
+    failedCount: number;
+}
 //# sourceMappingURL=db-recovery.d.ts.map

package/dist/db-recovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-recovery.d.ts","sourceRoot":"","sources":["../src/db-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;OAKG;IACH,SAAS,EAAE,oBAAoB,CAAC;IAChC,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,aAAa,EAAE,oBAAoB,CAAC;IACpC;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB"}
+{"version":3,"file":"db-recovery.d.ts","sourceRoot":"","sources":["../src/db-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;OAKG;IACH,SAAS,EAAE,oBAAoB,CAAC;IAChC,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,aAAa,EAAE,oBAAoB,CAAC;IACpC;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,EAAE,SAAS,GAAG,cAAc,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC3D,kFAAkF;IAClF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gFAAgF;IAChF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mFAAmF;IACnF,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;IAChB,yBAAyB;IACzB,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB"}

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

@@ -27,6 +27,8 @@
  *
  * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
  */
+import type { OperationInputContract } from '../operations/input-contract.js';
+import type { OperationOutputContract } from '../operations/output-contract.js';
 import type { ParamDef } from '../operations/params.js';
 import type { CanonicalDomain, Gateway, Tier } from './identity.js';
 export type { CanonicalDomain, Gateway, ParamDef, Tier };
@@ -84,6 +86,46 @@ export interface OperationDef {
      * @task T11448
      */
     mcpExposed?: boolean;
+    /**
+     * Schema-first INPUT contract for this operation (DHQ-033 / T11692).
+     *
+     * Declares the accepted request payload shape as a JSON Schema draft-07
+     * document with worked examples. When present, the dispatch/CLI layer
+     * validates the incoming payload against `inputSchema.schema` and rejects
+     * unknown keys LOUDLY (the schemas set `additionalProperties: false`), so a
+     * typo'd or unsupported field — e.g. passing `relates` to `tasks.add-batch`,
+     * which only accepts `depends` — fails fast with a typed {@link ValidationError}
+     * instead of being silently dropped.
+     *
+     * **Optional / incremental**: absent means "no declared input contract yet".
+     * The canonical SSoT registry of contracts is keyed by `<domain>.<operation>`
+     * (INPUT_CONTRACTS in core); this inline field lets a definition carry its
+     * own contract and is resolved by the SDK `describeOperation` when set.
+     *
+     * @see OperationInputContract
+     * @task T11692 — DHQ-033 input shape SSoT
+     */
+    inputSchema?: OperationInputContract<unknown>;
+    /**
+     * Schema-first OUTPUT contract for this operation (DHQ-057 / T11692).
+     *
+     * Declares the shape of the LAFS envelope's `data` payload as a JSON Schema
+     * draft-07 document, PLUS the curated list of valid `--field` JSON pointers.
+     * This is the SSoT that lets an agent predict the result shape instead of
+     * hand-sniffing it per verb — e.g. it encodes that `tasks.show` returns the
+     * task under `task`, so the correct pointer is `/data/task/title` and NOT
+     * `/data/title` (the latter is the exact `E_FIELD_NOT_FOUND` failure this
+     * field exists to prevent).
+     *
+     * **Optional / incremental**: absent means "no declared output contract yet".
+     * The canonical SSoT registry is keyed by `<domain>.<operation>`
+     * (OUTPUT_CONTRACTS in contracts); this inline field lets a definition carry
+     * its own contract and is resolved by the SDK `describeOperation` when set.
+     *
+     * @see OperationOutputContract
+     * @task T11692 — DHQ-057 output shape SSoT
+     */
+    outputSchema?: OperationOutputContract;
 }
 /**
  * Resolution output for a dispatch request.

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

@@ -1 +1 @@
-{"version":3,"file":"operation-def.d.ts","sourceRoot":"","sources":["../../src/dispatch/operation-def.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAKpE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAIzD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,MAAM,EAAE,eAAe,CAAC;IACxB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;IACX,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,GAAG,EAAE,YAAY,CAAC;CACnB"}
+{"version":3,"file":"operation-def.d.ts","sourceRoot":"","sources":["../../src/dispatch/operation-def.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAKpE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAIzD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,MAAM,EAAE,eAAe,CAAC;IACxB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,IAAI,CAAC;IACX,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAID;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,GAAG,EAAE,YAAY,CAAC;CACnB"}

package/dist/dispatch/operations-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAMD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EAusRpC,CAAC"}
+{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAMD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EA6sRpC,CAAC"}

package/dist/dispatch/operations-registry.js

@@ -6916,7 +6916,7 @@ export const OPERATIONS = [
         gateway: 'mutate',
         domain: 'docs',
         operation: 'add',
-        description: 'docs.add (mutate) — attach a local file or URL to a CLEO owner entity (task, session, observation)',
+        description: 'docs.add (mutate) — attach a local file, URL, or inline content to a CLEO owner entity (task, session, observation)',
         tier: 1,
         idempotent: false,
         sessionRequired: false,
@@ -6940,6 +6940,12 @@ export const OPERATIONS = [
                 required: false,
                 description: 'Remote URL to attach',
             },
+            {
+                name: 'content',
+                type: 'string',
+                required: false,
+                description: 'Inline document body (T10965); mutually exclusive with file/url',
+            },
             {
                 name: 'desc',
                 type: 'string',