@cleocode/contracts 2026.5.109 → 2026.5.111

package/dist/index.js.map

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

package/dist/memory/observe.d.ts

@@ -109,6 +109,14 @@ export interface ObserveBrainParams {
      * External callers MUST NOT set this flag.
      */
     _skipGate?: boolean;
+    /**
+     * T10351: Internal flag — when true, bypasses the brain writer-thread
+     * chokepoint and writes directly. Set ONLY by the writer-thread handler
+     * (`brain-writer-handlers.ts`) when re-entering observeBrain from inside
+     * the worker, so the routing doesn't recurse forever. External callers
+     * MUST NOT set this flag.
+     */
+    _skipQueue?: boolean;
 }
 /**
  * Result envelope returned by `observeBrain`.

package/dist/memory/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,+DAKjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;CACxB"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,+DAKjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;CACxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.109",
+  "version": "2026.5.111",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -138,12 +138,13 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.109"
+    "@cleocode/lafs": "2026.5.111"
   },
   "scripts": {
-    "build": "tsc -b --force && node scripts/emit-schemas.mjs",
-    "build:ts": "tsc -b --force",
+    "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",
+    "build:ts": "tsc -b --force && node scripts/copy-assets.mjs",
     "build:schemas": "node scripts/emit-schemas.mjs",
+    "build:assets": "node scripts/copy-assets.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }

package/src/__tests__/memory-wire-shapes.test.ts

@@ -204,6 +204,7 @@ type _ObserveBrainParamsShape = {
   origin?: string | null;
   provenanceChain?: string[] | null;
   _skipGate?: boolean;
+  _skipQueue?: boolean;
 };
 
 type _AssertObserveParamsPinned = AssertEquals1<

package/src/backup-verify.ts

@@ -0,0 +1,140 @@
+/**
+ * Type contract for `cleo backup verify` — per-DB freshness + integrity walker.
+ *
+ * `cleo backup verify` walks every entry in `DB_INVENTORY` and reports, for
+ * each role, the freshest snapshot in BOTH the canonical backup directory
+ * (`.cleo/backups/sqlite/` per T10315) and the legacy backup directory
+ * (`.cleo/backups/snapshot/`, kept read-only for one deprecation window).
+ * Each snapshot is opened via the canonical chokepoint, verified with
+ * `PRAGMA integrity_check`, and surfaced as a structured envelope. Operators
+ * use the envelope to detect stale and corrupt backups before they're needed
+ * for recovery.
+ *
+ * Verdict semantics (see {@link BackupVerifyVerdict}):
+ *
+ *  - `healthy` — a fresh snapshot exists (≤ 24h old) AND `integrity_check`
+ *    returned `ok`.
+ *  - `stale` — a snapshot exists but its mtime is > 24h old. Integrity may
+ *    still be OK; the operator should run `cleo backup add` to refresh.
+ *  - `corrupt` — at least one snapshot exists but the FRESH snapshot failed
+ *    `integrity_check`. The legacy snapshot may still be usable as a fallback.
+ *  - `missing` — no snapshot was found in EITHER the canonical or legacy
+ *    directory. Recovery from snapshot is impossible.
+ *
+ * @task T10319
+ * @epic T10284
+ * @saga T10281
+ */
+
+/**
+ * Verdict roll-up for a single role.
+ *
+ * @public
+ */
+export type BackupVerifyVerdict = 'healthy' | 'stale' | 'corrupt' | 'missing';
+
+/**
+ * Per-snapshot freshness + integrity record.
+ *
+ * @remarks
+ * Returned for both the canonical (`.cleo/backups/sqlite/`) and legacy
+ * (`.cleo/backups/snapshot/`) snapshot directories. When no snapshot exists
+ * in the corresponding directory the field on the parent
+ * {@link BackupVerifyDbReport} is `null` rather than this shape with empty
+ * fields — that lets consumers distinguish "no snapshot ever taken" from
+ * "snapshot exists but is unhealthy".
+ *
+ * @public
+ */
+export interface BackupVerifySnapshot {
+  /** Absolute path to the snapshot file. */
+  readonly path: string;
+  /** Snapshot mtime in epoch ms (the freshness signal). */
+  readonly mtime: number;
+  /**
+   * `true` when the snapshot file opened cleanly AND `PRAGMA integrity_check`
+   * returned the single row `ok`. `false` otherwise — see {@link error} for
+   * details.
+   */
+  readonly integrityOK: boolean;
+  /**
+   * Snapshot file size in bytes when `stat()` succeeded; `null` when the
+   * file vanished between discovery and stat.
+   */
+  readonly sizeBytes: number | null;
+  /**
+   * Human-readable error message when the snapshot could not be opened or
+   * its integrity check threw. `null` on success.
+   */
+  readonly error: string | null;
+}
+
+/**
+ * Per-DB report — one entry per role in `DB_INVENTORY`.
+ *
+ * @public
+ */
+export interface BackupVerifyDbReport {
+  /** Canonical role identifier (matches `DB_INVENTORY[i].role`). */
+  readonly role: string;
+  /** Lifecycle tier copied through from the inventory for downstream UI. */
+  readonly tier: 'project' | 'global' | 'derived';
+  /**
+   * Freshest snapshot found under `.cleo/backups/sqlite/` (canonical per
+   * T10315) — or `null` when the canonical directory has no snapshot for
+   * this role.
+   */
+  readonly freshSnapshot: BackupVerifySnapshot | null;
+  /**
+   * Freshest snapshot found under `.cleo/backups/snapshot/` (legacy, kept
+   * read-only during the deprecation window) — or `null` when the legacy
+   * directory has no snapshot for this role.
+   */
+  readonly legacySnapshot: BackupVerifySnapshot | null;
+  /**
+   * Hours between `Date.now()` and the freshest available snapshot's mtime
+   * (whichever of {@link freshSnapshot} / {@link legacySnapshot} is newer).
+   * `null` when {@link verdict} is `missing` — no snapshot to measure from.
+   */
+  readonly dataLossEstimateHours: number | null;
+  /**
+   * Roll-up verdict for this role — see {@link BackupVerifyVerdict}.
+   */
+  readonly verdict: BackupVerifyVerdict;
+}
+
+/**
+ * Aggregated counters across every role in the survey. Used by the CLI verb
+ * to drive its non-zero exit decision (`stale > 0 || corrupt > 0`).
+ *
+ * @public
+ */
+export interface BackupVerifySummary {
+  /** Number of roles whose verdict is `healthy`. */
+  readonly healthy: number;
+  /** Number of roles whose verdict is `stale`. */
+  readonly stale: number;
+  /** Number of roles whose verdict is `corrupt`. */
+  readonly corrupt: number;
+  /** Number of roles whose verdict is `missing`. */
+  readonly missing: number;
+}
+
+/**
+ * Envelope payload returned by `cleo backup verify` (and the underlying
+ * {@link runBackupVerify} core helper).
+ *
+ * @remarks
+ * The shape is keyed by role rather than indexed by array position so
+ * consumers can `.dbs['brain']` without scanning. The summary is provided
+ * pre-computed because the CLI exit code is driven from it — recomputing it
+ * downstream would invite drift.
+ *
+ * @public
+ */
+export interface BackupVerifyResult {
+  /** Per-role reports keyed by `DB_INVENTORY[i].role`. */
+  readonly dbs: Readonly<Record<string, BackupVerifyDbReport>>;
+  /** Aggregated counters used to drive the CLI exit code. */
+  readonly summary: BackupVerifySummary;
+}

package/src/db-inventory.json

@@ -0,0 +1,165 @@
+{
+  "$schemaNote": "SSoT machine-readable inventory of every CLEO SQLite database. Consumed by T10307 fleet survey, T10310 pragma drift, T10311 migration coverage, T10312 doctor integrity, T10320 cross-DB invariants. Owned by Saga T10281 SG-BRAIN-DB-RESILIENCE / Epic T10282 E1-DB-INVENTORY (task T10305). Amend together with ADR-068 charter; the CI drift gate (forthcoming under E1) compares entries to disk reality.",
+  "$pathTokens": {
+    "<projectRoot>": "Resolved at runtime from CLEO_ROOT env var or process.cwd(). Substituted by SSoT helpers `getCleoProjectDir()` in packages/brain/src/cleo-home.ts.",
+    "$XDG_DATA_HOME": "Resolved via env-paths through `getCleoHome()` in @cleocode/paths. Linux: ~/.local/share/cleo/, macOS: ~/Library/Application Support/cleo/."
+  },
+  "entries": [
+    {
+      "role": "tasks",
+      "tier": "project",
+      "filePathTemplate": "<projectRoot>/.cleo/tasks.db",
+      "drizzleSchemaPath": "packages/core/src/store/tasks-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-tasks/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "openCleoDb('tasks', cwd)",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": ".cleo/backups/sqlite/tasks-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 1; ADR-013 §9"
+    },
+    {
+      "role": "brain",
+      "tier": "project",
+      "filePathTemplate": "<projectRoot>/.cleo/brain.db",
+      "drizzleSchemaPath": "packages/core/src/store/memory-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-brain/",
+      "ownerPackage": "@cleocode/brain",
+      "openedVia": "openCleoDb('brain', cwd)",
+      "concurrency": "single-writer",
+      "privacy": "local-only-pii",
+      "backupPath": ".cleo/backups/sqlite/brain-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 2; ADR-013 §9; audit §2 (P0 malformed 2026-05-23)"
+    },
+    {
+      "role": "conduit",
+      "tier": "project",
+      "filePathTemplate": "<projectRoot>/.cleo/conduit.db",
+      "drizzleSchemaPath": "packages/core/src/store/conduit-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-conduit/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "openCleoDb('conduit', cwd)",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": ".cleo/backups/sqlite/conduit-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 3; ADR-037 (signaldock→conduit split)"
+    },
+    {
+      "role": "manifest",
+      "tier": "derived",
+      "filePathTemplate": "<projectRoot>/.cleo/blobs/manifest.db",
+      "drizzleSchemaPath": "packages/core/src/store/llmtxt-blob-adapter.ts",
+      "migrationsDir": null,
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "CleoBlobStore via llmtxt/blob BlobFsAdapter (no openCleoDb role registered)",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": "rebuildable-from-blob-store",
+      "documentedIn": "ADR-068 row 7 (derived); schema owned by llmtxt/blob BlobFsAdapter contract"
+    },
+    {
+      "role": "llmtxt",
+      "tier": "project",
+      "filePathTemplate": "<projectRoot>/.cleo/llmtxt/llmtxt.db",
+      "drizzleSchemaPath": null,
+      "migrationsDir": null,
+      "ownerPackage": "@cleocode/llmtxt-core",
+      "openedVia": "openCleoDb('llmtxt', cwd) — RESERVED; opener throws 'not yet implemented' (see open-cleo-db.ts L138)",
+      "concurrency": "single-writer",
+      "privacy": "local-only-pii",
+      "backupPath": ".cleo/backups/sqlite/llmtxt-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 8 (reserved); audit §1.1 row 4 (live at .cleo/llmtxt/llmtxt.db)"
+    },
+    {
+      "role": "nexus",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/nexus.db",
+      "drizzleSchemaPath": "packages/core/src/store/nexus-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-nexus/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "openCleoDb('nexus')",
+      "concurrency": "single-writer",
+      "privacy": "local-only-pii",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/nexus-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 5"
+    },
+    {
+      "role": "signaldock-project",
+      "tier": "project",
+      "filePathTemplate": "<projectRoot>/.cleo/signaldock.db",
+      "drizzleSchemaPath": "packages/core/src/store/signaldock-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-signaldock/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "HISTORICAL — project-tier signaldock.db was migrated into conduit.db post-T310/ADR-037. No live opener; charter row retained for migration provenance and legacy backup detection.",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": ".cleo/backups/sqlite/signaldock-project-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 4 (stale — superseded by ADR-037); audit §1.1 (not in live project DB list)"
+    },
+    {
+      "role": "signaldock-global",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/signaldock.db",
+      "drizzleSchemaPath": "packages/core/src/store/signaldock-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-signaldock/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "openCleoDb('signaldock')",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/signaldock-global-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 9; ADR-037 (post-split global identity registry)"
+    },
+    {
+      "role": "telemetry",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/telemetry.db",
+      "drizzleSchemaPath": "packages/core/src/telemetry/schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-telemetry/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "@cleocode/core telemetry/sqlite.ts — lazy open on first event when opted-in; not yet registered as openCleoDb role",
+      "concurrency": "single-writer",
+      "privacy": "cloud-exportable-opt-in",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/telemetry-YYYYMMDD-HHmmss.db",
+      "documentedIn": "ADR-068 row 6; T624"
+    },
+    {
+      "role": "skills",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/skills.db",
+      "drizzleSchemaPath": "packages/core/src/store/skills-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-skills/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "openCleoDb('skills')",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/skills-YYYYMMDD-HHmmss.db",
+      "documentedIn": "T9651 (initial skills.db migration); audit §1.2 row 4 — NOT yet in ADR-068 table"
+    },
+    {
+      "role": "global-brain",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/brain.db",
+      "drizzleSchemaPath": "packages/core/src/store/memory-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-brain/",
+      "ownerPackage": "@cleocode/brain",
+      "openedVia": "UNREGISTERED — file exists on disk (audit §1.2 row 3) but no live opener. Provenance unclear; likely orphan from a getCleoHome()-vs-project-resolution path bug. Tracked for cleanup decision under T10282/T10307.",
+      "concurrency": "single-writer",
+      "privacy": "local-only-pii",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/global-brain-YYYYMMDD-HHmmss.db",
+      "documentedIn": "audit §1.2 row 3 — NEW per saga T10281; not in ADR-068"
+    },
+    {
+      "role": "global-tasks",
+      "tier": "global",
+      "filePathTemplate": "$XDG_DATA_HOME/cleo/tasks.db",
+      "drizzleSchemaPath": "packages/core/src/store/tasks-schema.ts",
+      "migrationsDir": "packages/core/migrations/drizzle-tasks/",
+      "ownerPackage": "@cleocode/core",
+      "openedVia": "UNREGISTERED — file exists on disk (audit §1.2 row 5, 4 KB) but no live opener. Provenance unclear; likely orphan from a cwd-cascade bug (T9550 class). Tracked for cleanup decision under T10282/T10307.",
+      "concurrency": "single-writer",
+      "privacy": "local-only",
+      "backupPath": "$XDG_DATA_HOME/cleo/backups/sqlite/global-tasks-YYYYMMDD-HHmmss.db",
+      "documentedIn": "audit §1.2 row 5 — NEW per saga T10281; not in ADR-068"
+    }
+  ]
+}

package/src/db-inventory.ts

@@ -4,10 +4,16 @@
  * @remarks
  * This module exports the typed shape and the runtime constant for every
  * SQLite database that CLEO manages. The runtime data is sourced from the
- * canonical JSON inventory at `packages/core/src/store/db-inventory.json`
+ * canonical JSON inventory at `packages/contracts/src/db-inventory.json`
  * via ESM JSON import (`with { type: 'json' }`). The JSON file is the
  * single source of truth; this module re-exposes it with a typed contract.
  *
+ * The JSON file is co-located in this package (rather than referencing a
+ * sibling-package `src/` path) so that the built `dist/db-inventory.js`
+ * resolves the JSON via a relative `./db-inventory.json` import that
+ * works inside the published `@cleocode/contracts` npm tarball — sibling
+ * package `src/` directories are not shipped to consumers.
+ *
  * Downstream consumers:
  *
  * - **T10307 — Fleet survey** (`cleo doctor db-substrate`) iterates `DB_INVENTORY`
@@ -23,9 +29,10 @@
  *   agent_id, session_id, ...).
  *
  * Adding a new entry to the inventory is a charter amendment — update
- * `db-inventory.json` AND `.cleo/adrs/ADR-068-cleo-database-charter.md`
- * in the same PR (gated by `cleo check arch` Gate-4 SSoT-EXEMPT lint
- * once T10282 ships its drift check).
+ * `packages/contracts/src/db-inventory.json` AND
+ * `.cleo/adrs/ADR-068-cleo-database-charter.md` in the same PR (gated by
+ * `cleo check arch` Gate-4 SSoT-EXEMPT lint once T10282 ships its drift
+ * check).
  *
  * @see ADR-068 — CLEO Database Charter (canonical narrative)
  * @see Saga T10281 — SG-BRAIN-DB-RESILIENCE (provenance)
@@ -37,7 +44,7 @@
  * @saga T10281
  */
 
-import dbInventoryData from '../../core/src/store/db-inventory.json' with { type: 'json' };
+import dbInventoryData from './db-inventory.json' with { type: 'json' };
 
 /**
  * Canonical role names for every SQLite database in the CLEO charter.
@@ -203,7 +210,7 @@ const rawInventory = dbInventoryData as DbInventoryFile;
  * Immutable canonical inventory of every CLEO SQLite database.
  *
  * @remarks
- * Sourced from `packages/core/src/store/db-inventory.json` — the SSoT.
+ * Sourced from `packages/contracts/src/db-inventory.json` — the SSoT.
  * Adding a new entry is a charter amendment per ADR-068 §"How to add a
  * new database". The {@link db-inventory.test.ts} suite asserts:
  *

package/src/db-recovery.ts

@@ -0,0 +1,144 @@
+/**
+ * Generic CLEO database recovery contracts — generalised from the brain-only
+ * T10303/T10304 shapes so the same envelope works for every role declared in
+ * {@link DB_INVENTORY}.
+ *
+ * These types mirror {@link BrainRecoveryResult} + {@link BackupRecoverBrainResult}
+ * almost verbatim, with two adjustments:
+ *
+ * 1. `observationsRecovered: number | null` is generalised to
+ *    `rowCounts: DbRecoveredRowCounts` — a `Record<tableName, number | null>`
+ *    keyed by the user tables discovered in the restored DB via
+ *    `sqlite_master`. Tables that fail to count surface as `null`.
+ * 2. Every envelope carries the `role: DbRole` it pertains to so envelopes from
+ *    `cleo backup recover <role>` are self-describing across tools that may
+ *    fan recovery out across multiple DBs.
+ *
+ * The brain-specific shapes ({@link BrainRecoveryResult},
+ * {@link BackupRecoverBrainResult}, {@link BrainRecoveredRowCounts}) remain in
+ * {@link brain.ts} as the backward-compatible surface — the brain CLI verb
+ * (`cleo backup recover brain`) still emits the same envelope it did before
+ * T10318 generalised the pipeline.
+ *
+ * @task T10318
+ * @epic T10284
+ * @saga T10281
+ * @adr ADR-068
+ */
+
+import type { DbRole } from './db-inventory.js';
+
+/**
+ * Best-effort per-table row counts probed from a recovered CLEO database.
+ *
+ * @remarks
+ * The recovery pipeline enumerates user tables in the restored DB via
+ * `sqlite_master` (excluding internal `sqlite_*` and Drizzle journal tables)
+ * and runs `SELECT COUNT(*)` on each. Tables that fail to count — for
+ * example, a missing table in a very old snapshot, or a schema/version
+ * mismatch — surface as `null` instead of throwing so the envelope always
+ * serialises cleanly.
+ *
+ * Keys are exact SQLite table names (case-sensitive). Values are non-negative
+ * integers or `null`.
+ *
+ * @public
+ */
+export type DbRecoveredRowCounts = Readonly<Record<string, number | null>>;
+
+/**
+ * Result of a generic CLEO DB auto-recovery attempt.
+ *
+ * @remarks
+ * Returned by `recoverMalformedDb({ role, ... })` (T10318) when the chokepoint
+ * (or an operator invoking `cleo backup recover <role>`) detects malformation
+ * via `ERR_SQLITE_ERROR errcode=11` or a failing `PRAGMA integrity_check` /
+ * `PRAGMA quick_check`. The corrupt DB has been moved to a quarantine
+ * directory and the freshest validated snapshot has been copied to the
+ * canonical role path.
+ *
+ * Consumers read this structure to decide whether to re-attempt the open and
+ * to emit user-facing diagnostics with the data-loss window.
+ *
+ * @public
+ */
+export interface DbRecoveryResult {
+  /** Canonical role of the database that was recovered. */
+  role: DbRole;
+  /** Absolute path to the snapshot that was restored, or `null` if recovery failed. */
+  restoredFrom: string | null;
+  /**
+   * Approximate hours between the snapshot's timestamp and the recovery
+   * event. `null` when the snapshot timestamp could not be parsed.
+   * Used in the recovery warning to make the data-loss window legible.
+   */
+  dataLossWindowHours: number | null;
+  /**
+   * Per-table row counts probed from the restored DB. Each key is a user
+   * table name; each value is the row count, or `null` on count failure.
+   * Empty record `{}` when the restored DB has no user tables (or when
+   * the probe itself failed to open the DB).
+   */
+  rowCounts: DbRecoveredRowCounts;
+  /** `true` if the restored DB passes `PRAGMA quick_check`. */
+  integrityOK: boolean;
+  /**
+   * Absolute path to the quarantine directory where the corrupt DB plus
+   * its `-wal`/`-shm` sidecars were moved before restore. `null` when no
+   * corrupt DB existed at the canonical path (recovery into an empty slot).
+   */
+  quarantineDir: string | null;
+}
+
+/**
+ * Envelope payload returned by `cleo backup recover <role>`.
+ *
+ * @remarks
+ * Wraps {@link DbRecoveryResult} with three CLI-only additions:
+ *
+ * - `rowsRecovered` aliases `rowCounts` to keep the envelope shape compatible
+ *   with the brain-specific {@link BackupRecoverBrainResult}.
+ * - `quarantinedTo: string` is the non-nullable string form (empty string in
+ *   `--dry-run` mode where no files were touched) — easier for shell scripts
+ *   that pipe the envelope into `jq` and then path operations.
+ * - `dryRun: boolean` records whether the envelope is a *plan* (would-do)
+ *   versus a *record* (already-done). Consumers MUST check this before
+ *   treating `restoredFrom` as a post-condition.
+ *
+ * @task T10318
+ * @epic T10284
+ * @saga T10281
+ * @public
+ */
+export interface BackupRecoverResult {
+  /** Canonical role of the database that was (or would be) recovered. */
+  role: DbRole;
+  /**
+   * Absolute path to the snapshot that was (or would be) restored. Empty
+   * string when no snapshot was available — the envelope's caller surfaces
+   * that as a failure mode via a structured error.
+   */
+  restoredFrom: string;
+  /** Per-table row counts probed from the restored DB (or the plan target). */
+  rowsRecovered: DbRecoveredRowCounts;
+  /**
+   * Approximate hours between the snapshot's timestamp and the recovery
+   * event. `null` when the snapshot timestamp could not be parsed (e.g.
+   * legacy `<role>.db.PRE-DUP-FIX-*` fallback artifact).
+   */
+  dataLossWindowHours: number | null;
+  /** `true` when the restored DB passes `PRAGMA quick_check`. */
+  integrityOK: boolean;
+  /**
+   * Absolute path to the quarantine directory where the corrupt DB plus
+   * its `-wal`/`-shm` sidecars were moved. Empty string in `--dry-run`
+   * mode where no files were touched.
+   */
+  quarantinedTo: string;
+  /**
+   * `true` when invoked with `--dry-run` — indicates the envelope is a
+   * plan, NOT a record of mutations performed. Consumers MUST check this
+   * before treating `restoredFrom` as a post-condition.
+   */
+  dryRun: boolean;
+}