@cleocode/contracts 2026.5.108 → 2026.5.110

package/dist/db-inventory.d.ts

@@ -0,0 +1,200 @@
+/**
+ * CLEO Database Inventory — SSoT type contract + immutable constant.
+ *
+ * @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/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`
+ *   to enumerate every DB on disk across project + global tiers.
+ * - **T10310 — Pragma drift** validates that every open handle for each role
+ *   applies the pragma SSoT (`specs/sqlite-pragmas.json`).
+ * - **T10311 — Migration coverage** asserts that each entry's
+ *   `migrationsDir` exists and contains a `0000_*` baseline.
+ * - **T10312 — Doctor integrity** runs `PRAGMA integrity_check` against
+ *   every entry whose tier resolves to a present file on disk.
+ * - **T10320 — Cross-DB invariants** uses `ownerPackage` + `tier` to
+ *   classify which DBs must agree on shared identifiers (project_id,
+ *   agent_id, session_id, ...).
+ *
+ * Adding a new entry to the inventory is a charter amendment — update
+ * `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)
+ * @see Epic T10282 — E1-DB-INVENTORY (this artifact)
+ * @see Research note `sg-brain-db-resilience-deep-audit-2026-05-23`
+ *
+ * @task T10305
+ * @epic T10282
+ * @saga T10281
+ */
+/**
+ * Canonical role names for every SQLite database in the CLEO charter.
+ *
+ * @remarks
+ * Mirrors the `openCleoDb('<role>', cwd)` chokepoint (ADR-068 §3) plus the
+ * three audit-discovered roles (`global-brain`, `global-tasks`, `manifest`)
+ * that exist on disk today but do not yet have a registered opener.
+ *
+ * - `tasks`              — project-tier task engine DB
+ * - `brain`              — project-tier memory DB (PII)
+ * - `conduit`            — project-tier agent message transport
+ * - `manifest`           — project-tier derived blob index (rebuildable)
+ * - `llmtxt`             — reserved project-tier llmtxt session store
+ * - `nexus`              — global-tier cross-project knowledge graph (PII)
+ * - `signaldock-project` — historical project-tier signaldock (post-ADR-037, merged into conduit)
+ * - `signaldock-global`  — global-tier canonical agent identity registry
+ * - `telemetry`          — global-tier opt-in command telemetry
+ * - `skills`             — global-tier per-user skill registry
+ * - `global-brain`       — global-tier brain.db observed on disk (audit §1.2 — provenance under investigation)
+ * - `global-tasks`       — global-tier tasks.db observed on disk (audit §1.2 — provenance under investigation)
+ *
+ * @public
+ */
+export type DbRole = 'tasks' | 'brain' | 'conduit' | 'manifest' | 'llmtxt' | 'nexus' | 'signaldock-project' | 'signaldock-global' | 'telemetry' | 'skills' | 'global-brain' | 'global-tasks';
+/**
+ * Lifecycle scope of a CLEO database.
+ *
+ * @remarks
+ * - `project` — file lives under `<projectRoot>/.cleo/`; lifecycle bound to one CLEO project.
+ * - `global`  — file lives under `$XDG_DATA_HOME/cleo/` (env-paths via `getCleoHome()`).
+ * - `derived` — file lives under the project tier but is rebuildable from a
+ *               non-DB source-of-truth (e.g. content-addressable blob store).
+ *               MAY be excluded from backup-pack.
+ *
+ * @public
+ */
+export type DbTier = 'project' | 'global' | 'derived';
+/**
+ * Privacy classification governing backup + cloud-export rules.
+ *
+ * @remarks
+ * - `local-only`               — never cloud-exported.
+ * - `local-only-pii`           — never cloud-exported; PII-class — requires
+ *                                explicit `cleo backup export --include-pii`.
+ * - `cloud-exportable-opt-in`  — may be exported only after explicit opt-in
+ *                                (e.g. `cleo diagnostics enable`).
+ *
+ * @public
+ */
+export type DbPrivacy = 'local-only' | 'local-only-pii' | 'cloud-exportable-opt-in';
+/**
+ * Concurrency model for the database.
+ *
+ * @remarks
+ * Every CLEO database today is `single-writer` (WAL mode with in-process
+ * serialization via the `openCleoDb` singleton). The field is enumerated so
+ * a future read-replica or multi-writer DB MUST be declared explicitly.
+ *
+ * @public
+ */
+export type DbConcurrency = 'single-writer' | 'multi-writer';
+/**
+ * One row in the CLEO database charter.
+ *
+ * @remarks
+ * Every field is required (no `null` placeholders) EXCEPT `drizzleSchemaPath`
+ * and `migrationsDir` — those MAY be `null` for:
+ *
+ * - `derived` databases whose schema is owned by an upstream library (e.g.
+ *   `manifest.db` is owned by `llmtxt/blob`'s `BlobFsAdapter` contract).
+ * - `reserved` roles whose opener throws `not yet implemented` (e.g.
+ *   `llmtxt.db`).
+ *
+ * Path templates use the substitution tokens:
+ *
+ * - `<projectRoot>`   — resolved at runtime from `CLEO_ROOT` env var or
+ *                       `process.cwd()` via `getCleoProjectDir()`.
+ * - `$XDG_DATA_HOME`  — resolved via env-paths through `getCleoHome()`.
+ *                       Linux: `~/.local/share/cleo/`; macOS:
+ *                       `~/Library/Application Support/cleo/`.
+ *
+ * @public
+ */
+export interface DbInventoryEntry {
+    /** Canonical role identifier used by `openCleoDb` and audit tooling. */
+    readonly role: DbRole;
+    /** Lifecycle scope — project, global, or derived. */
+    readonly tier: DbTier;
+    /**
+     * Filesystem path template with `<projectRoot>` / `$XDG_DATA_HOME` tokens.
+     * Substitution convention is documented on {@link DbInventoryEntry}.
+     */
+    readonly filePathTemplate: string;
+    /**
+     * Repo-relative path to the Drizzle schema TypeScript file. `null` when
+     * the schema is owned by an upstream library or the role is reserved.
+     */
+    readonly drizzleSchemaPath: string | null;
+    /**
+     * Repo-relative path to the Drizzle migrations directory (with trailing
+     * slash). `null` for `derived` rows or reserved roles. The path MUST
+     * exist on disk when non-null — enforced by the contracts test suite.
+     */
+    readonly migrationsDir: string | null;
+    /** npm package that owns the open + lifecycle for this database. */
+    readonly ownerPackage: string;
+    /**
+     * Human-readable description of HOW the database is opened. Typically
+     * a code excerpt like `openCleoDb('tasks', cwd)`. For databases without
+     * a registered opener, describes provenance / status.
+     */
+    readonly openedVia: string;
+    /** Concurrency model — see {@link DbConcurrency}. */
+    readonly concurrency: DbConcurrency;
+    /** Privacy classification — see {@link DbPrivacy}. */
+    readonly privacy: DbPrivacy;
+    /**
+     * Canonical backup path template. For `derived` rows this is the
+     * sentinel string `rebuildable-from-blob-store` (or similar) and the
+     * row is excluded from backup-pack staging.
+     */
+    readonly backupPath: string;
+    /**
+     * Provenance pointers — ADR row, related task IDs, audit section
+     * references. Comma-or-semicolon separated string of references.
+     */
+    readonly documentedIn: string;
+}
+/**
+ * Immutable canonical inventory of every CLEO SQLite database.
+ *
+ * @remarks
+ * 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:
+ *
+ * 1. Every `role` is unique across the array.
+ * 2. Every `drizzleSchemaPath` (when non-null) exists on disk.
+ * 3. Every `migrationsDir` (when non-null) exists on disk.
+ * 4. Every `tier` is a member of the {@link DbTier} union.
+ *
+ * @example Iterate every project-tier database
+ * ```typescript
+ * import { DB_INVENTORY } from '@cleocode/contracts';
+ *
+ * const projectDbs = DB_INVENTORY.filter((entry) => entry.tier === 'project');
+ * for (const entry of projectDbs) {
+ *   console.log(entry.role, entry.filePathTemplate);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const DB_INVENTORY: readonly DbInventoryEntry[];
+//# sourceMappingURL=db-inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db-inventory.d.ts","sourceRoot":"","sources":["../src/db-inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,MAAM,GACd,OAAO,GACP,OAAO,GACP,SAAS,GACT,UAAU,GACV,QAAQ,GACR,OAAO,GACP,oBAAoB,GACpB,mBAAmB,GACnB,WAAW,GACX,QAAQ,GACR,cAAc,GACd,cAAc,CAAC;AAEnB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,gBAAgB,GAAG,yBAAyB,CAAC;AAEpF;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,cAAc,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EAAyB,CAAC"}

package/dist/db-inventory.js

@@ -0,0 +1,76 @@
+/**
+ * CLEO Database Inventory — SSoT type contract + immutable constant.
+ *
+ * @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/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`
+ *   to enumerate every DB on disk across project + global tiers.
+ * - **T10310 — Pragma drift** validates that every open handle for each role
+ *   applies the pragma SSoT (`specs/sqlite-pragmas.json`).
+ * - **T10311 — Migration coverage** asserts that each entry's
+ *   `migrationsDir` exists and contains a `0000_*` baseline.
+ * - **T10312 — Doctor integrity** runs `PRAGMA integrity_check` against
+ *   every entry whose tier resolves to a present file on disk.
+ * - **T10320 — Cross-DB invariants** uses `ownerPackage` + `tier` to
+ *   classify which DBs must agree on shared identifiers (project_id,
+ *   agent_id, session_id, ...).
+ *
+ * Adding a new entry to the inventory is a charter amendment — update
+ * `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)
+ * @see Epic T10282 — E1-DB-INVENTORY (this artifact)
+ * @see Research note `sg-brain-db-resilience-deep-audit-2026-05-23`
+ *
+ * @task T10305
+ * @epic T10282
+ * @saga T10281
+ */
+import dbInventoryData from './db-inventory.json' with { type: 'json' };
+// Narrow the raw JSON to the typed shape. The runtime parity test
+// (`db-inventory.test.ts`) asserts every field is valid for every entry.
+const rawInventory = dbInventoryData;
+/**
+ * Immutable canonical inventory of every CLEO SQLite database.
+ *
+ * @remarks
+ * 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:
+ *
+ * 1. Every `role` is unique across the array.
+ * 2. Every `drizzleSchemaPath` (when non-null) exists on disk.
+ * 3. Every `migrationsDir` (when non-null) exists on disk.
+ * 4. Every `tier` is a member of the {@link DbTier} union.
+ *
+ * @example Iterate every project-tier database
+ * ```typescript
+ * import { DB_INVENTORY } from '@cleocode/contracts';
+ *
+ * const projectDbs = DB_INVENTORY.filter((entry) => entry.tier === 'project');
+ * for (const entry of projectDbs) {
+ *   console.log(entry.role, entry.filePathTemplate);
+ * }
+ * ```
+ *
+ * @public
+ */
+export const DB_INVENTORY = rawInventory.entries;
+//# sourceMappingURL=db-inventory.js.map

package/dist/db-inventory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-inventory.js","sourceRoot":"","sources":["../src/db-inventory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,eAAe,MAAM,qBAAqB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AA8JxE,kEAAkE;AAClE,yEAAyE;AACzE,MAAM,YAAY,GAAG,eAAkC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAgC,YAAY,CAAC,OAAO,CAAC"}

package/dist/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/dist/db-recovery.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=db-recovery.d.ts.map

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

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

package/dist/db-recovery.js

@@ -0,0 +1,29 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=db-recovery.js.map

package/dist/db-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-recovery.js","sourceRoot":"","sources":["../src/db-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}