@cleocode/contracts 2026.5.107 → 2026.5.109

package/src/__tests__/db-inventory.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Contract tests for the CLEO database inventory SSoT.
+ *
+ * Asserts the structural invariants the inventory MUST hold:
+ *
+ * 1. Every {@link DbInventoryEntry.role} is unique across the array.
+ * 2. Every {@link DbInventoryEntry.tier} is a valid member of the
+ *    {@link DbTier} union.
+ * 3. Every non-null {@link DbInventoryEntry.drizzleSchemaPath} resolves
+ *    to a real file on disk relative to the monorepo root.
+ * 4. Every non-null {@link DbInventoryEntry.migrationsDir} resolves to a
+ *    real directory on disk relative to the monorepo root.
+ * 5. The list is non-empty and covers the AC1-mandated role set.
+ *
+ * These invariants are the gating contract for downstream saga tasks
+ * (T10307 fleet survey, T10310 pragma drift, T10311 migration coverage,
+ * T10312 doctor integrity, T10320 cross-DB invariants). If this suite
+ * fails, the inventory has drifted from disk reality and CI MUST block.
+ *
+ * @task T10305
+ * @epic T10282
+ * @saga T10281
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { DB_INVENTORY, type DbInventoryEntry, type DbTier } from '../db-inventory.js';
+
+/**
+ * Resolve the monorepo root from this test file.
+ *
+ * `__tests__/db-inventory.test.ts` lives at
+ * `packages/contracts/src/__tests__/` — four levels above the repo root.
+ */
+const THIS_FILE = fileURLToPath(import.meta.url);
+const REPO_ROOT = resolve(dirname(THIS_FILE), '..', '..', '..', '..');
+
+const VALID_TIERS: ReadonlySet<DbTier> = new Set<DbTier>(['project', 'global', 'derived']);
+
+/**
+ * Roles AC1 of T10305 explicitly requires the inventory to enumerate.
+ * The set must be covered exactly; extras are acceptable when documented.
+ */
+const REQUIRED_ROLES: readonly string[] = [
+  'tasks',
+  'brain',
+  'conduit',
+  'manifest',
+  'llmtxt',
+  'nexus',
+  'signaldock-project',
+  'signaldock-global',
+  'telemetry',
+  'skills',
+  'global-brain',
+  'global-tasks',
+];
+
+describe('CLEO database inventory (T10305 SSoT)', () => {
+  it('is non-empty', () => {
+    expect(DB_INVENTORY.length).toBeGreaterThan(0);
+  });
+
+  it('covers every role required by T10305 AC1', () => {
+    const seen = new Set<string>(DB_INVENTORY.map((e) => e.role));
+    for (const role of REQUIRED_ROLES) {
+      expect(seen.has(role), `inventory missing role '${role}'`).toBe(true);
+    }
+  });
+
+  it('has unique role IDs across all entries', () => {
+    const roles = DB_INVENTORY.map((e) => e.role);
+    const unique = new Set(roles);
+    expect(unique.size).toBe(roles.length);
+  });
+
+  it('uses only valid tier literals', () => {
+    for (const entry of DB_INVENTORY) {
+      expect(
+        VALID_TIERS.has(entry.tier),
+        `role '${entry.role}' has invalid tier '${entry.tier}'`,
+      ).toBe(true);
+    }
+  });
+
+  it('uses valid path tokens in filePathTemplate', () => {
+    // Project tier MUST use <projectRoot>/ prefix; global tier MUST use
+    // $XDG_DATA_HOME/cleo/ prefix. Derived tier may use either.
+    for (const entry of DB_INVENTORY) {
+      const t = entry.filePathTemplate;
+      if (entry.tier === 'project') {
+        expect(
+          t.startsWith('<projectRoot>/'),
+          `project-tier entry '${entry.role}' uses non-canonical path '${t}'`,
+        ).toBe(true);
+      } else if (entry.tier === 'global') {
+        expect(
+          t.startsWith('$XDG_DATA_HOME/cleo/'),
+          `global-tier entry '${entry.role}' uses non-canonical path '${t}'`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it('resolves every non-null drizzleSchemaPath to a real file', () => {
+    for (const entry of DB_INVENTORY) {
+      if (entry.drizzleSchemaPath === null) continue;
+      const absolutePath = resolve(REPO_ROOT, entry.drizzleSchemaPath);
+      expect(
+        existsSync(absolutePath),
+        `role '${entry.role}' schema path missing: ${entry.drizzleSchemaPath}`,
+      ).toBe(true);
+      expect(
+        statSync(absolutePath).isFile(),
+        `role '${entry.role}' schema path is not a file: ${entry.drizzleSchemaPath}`,
+      ).toBe(true);
+    }
+  });
+
+  it('resolves every non-null migrationsDir to a real directory', () => {
+    for (const entry of DB_INVENTORY) {
+      if (entry.migrationsDir === null) continue;
+      const absolutePath = resolve(REPO_ROOT, entry.migrationsDir);
+      expect(
+        existsSync(absolutePath),
+        `role '${entry.role}' migrations dir missing: ${entry.migrationsDir}`,
+      ).toBe(true);
+      expect(
+        statSync(absolutePath).isDirectory(),
+        `role '${entry.role}' migrations path is not a directory: ${entry.migrationsDir}`,
+      ).toBe(true);
+    }
+  });
+
+  it('omits migrationsDir only for derived or reserved roles', () => {
+    // A null migrationsDir is only valid for:
+    //  - derived tier (schema owned by upstream lib — e.g. manifest)
+    //  - reserved roles whose opener throws not-yet-implemented (e.g. llmtxt)
+    for (const entry of DB_INVENTORY) {
+      if (entry.migrationsDir !== null) continue;
+      const isDerived = entry.tier === 'derived';
+      const isReserved = /reserved|not yet implemented/i.test(entry.openedVia);
+      expect(
+        isDerived || isReserved,
+        `role '${entry.role}' has null migrationsDir but is neither derived nor reserved`,
+      ).toBe(true);
+    }
+  });
+
+  it('exposes a readonly array type at compile time', () => {
+    // Compile-time check: assigning to an index must be rejected.
+    // Runtime check: Object.isFrozen is not guaranteed by `readonly` but the
+    // type-system reject is the primary defence. We only assert the runtime
+    // shape is array-like here.
+    expect(Array.isArray(DB_INVENTORY)).toBe(true);
+  });
+
+  it('keeps each entry self-consistent (sample-fields populated)', () => {
+    // Sanity: every entry must populate the structural fields. The contract
+    // forbids `null` placeholders on non-optional fields.
+    const sampleRequiredKeys: ReadonlyArray<keyof DbInventoryEntry> = [
+      'role',
+      'tier',
+      'filePathTemplate',
+      'ownerPackage',
+      'openedVia',
+      'concurrency',
+      'privacy',
+      'backupPath',
+      'documentedIn',
+    ];
+    for (const entry of DB_INVENTORY) {
+      for (const key of sampleRequiredKeys) {
+        const value = entry[key];
+        expect(
+          typeof value === 'string' && value.length > 0,
+          `role '${entry.role}' field '${String(key)}' is empty or non-string`,
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/__tests__/task-type-narrowing.test.ts

@@ -0,0 +1,56 @@
+/**
+ * TaskType discriminator narrowing tests.
+ *
+ * Pins the post-ADR-083 §2.5 union shape (`'saga' | 'epic' | 'task' |
+ * 'subtask'`) so that:
+ *   - Adding/removing a tier in the canonical {@link TaskType} union breaks
+ *     this test loudly (caught at compile time AND runtime).
+ *   - Discriminated-union narrowing on `task.type === 'saga'` keeps working
+ *     for downstream consumers.
+ *
+ * @since SAGA T10326 · Epic T10277 · Task T10328 (W1.A)
+ */
+
+import { describe, expectTypeOf, it } from 'vitest';
+import type { Task, TaskType } from '../task.js';
+
+describe('TaskType discriminator', () => {
+  it('narrows when type === "saga"', () => {
+    const t: Task = {
+      id: 'T1',
+      title: 'demo',
+      description: 'demo task',
+      status: 'pending',
+      priority: 'medium',
+      type: 'saga',
+      createdAt: '2026-01-01T00:00:00.000Z',
+    };
+    if (t.type === 'saga') {
+      expectTypeOf(t.type).toEqualTypeOf<'saga'>();
+    }
+  });
+
+  it('narrows when type === "epic"', () => {
+    const t: Task = {
+      id: 'T2',
+      title: 'demo',
+      description: 'demo task',
+      status: 'pending',
+      priority: 'medium',
+      type: 'epic',
+      createdAt: '2026-01-01T00:00:00.000Z',
+    };
+    if (t.type === 'epic') {
+      expectTypeOf(t.type).toEqualTypeOf<'epic'>();
+    }
+  });
+
+  it('accepts all 4 tier values', () => {
+    const types: TaskType[] = ['saga', 'epic', 'task', 'subtask'];
+    expectTypeOf(types).toEqualTypeOf<TaskType[]>();
+  });
+
+  it('TaskType is the 4-element union per ADR-083 §2.5', () => {
+    expectTypeOf<TaskType>().toEqualTypeOf<'saga' | 'epic' | 'task' | 'subtask'>();
+  });
+});

package/src/brain.ts

@@ -96,3 +96,117 @@ export interface SupersededEntry {
   /** Topic or category grouping these entries together. */
   grouping: string;
 }
+
+// ============================================================
+// T10303 — Brain.db auto-recovery (Saga T10281 / Epic T10286)
+// ============================================================
+
+/**
+ * Result of a brain.db auto-recovery attempt.
+ *
+ * Returned by `recoverMalformedBrainDb()` (T10303) when the chokepoint
+ * 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 `.cleo/brain.db`.
+ *
+ * Consumers (the brain.db open chokepoint, telemetry, the upcoming T10302
+ * regression test) read this structure to decide whether to re-attempt the
+ * open and to emit user-facing diagnostics with the data-loss window.
+ */
+export interface BrainRecoveryResult {
+  /** 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;
+  /**
+   * Number of `brain_observations` rows in the restored DB. Best-effort —
+   * `null` when the count query failed (table missing, FK violation, …).
+   */
+  observationsRecovered: number | null;
+  /** `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.
+   */
+  quarantineDir: string | null;
+}
+
+// ============================================================
+// T10304 — `cleo backup recover brain` CLI verb (Saga T10281 / Epic T10286)
+// ============================================================
+
+/**
+ * Per-table row counts probed from the restored brain.db.
+ *
+ * Best-effort — any individual count may be `null` when the table is
+ * missing (very old snapshot predating that schema rev) or when the count
+ * query throws. The values feed both the `cleo backup recover brain`
+ * envelope and the recovery runbook's user-facing diagnostics.
+ *
+ * @task T10304
+ * @epic T10286
+ * @saga T10281
+ */
+export interface BrainRecoveredRowCounts {
+  /** `brain_observations` row count, or `null` when the count failed. */
+  observations: number | null;
+  /** `brain_decisions` row count, or `null` when the count failed. */
+  decisions: number | null;
+  /** `brain_learnings` row count, or `null` when the count failed. */
+  learnings: number | null;
+}
+
+/**
+ * Envelope payload returned by `cleo backup recover brain`.
+ *
+ * The CLI verb (T10304) wraps {@link BrainRecoveryResult} from
+ * {@link recoverMalformedBrainDb} (T10303) and enriches it with per-table
+ * row counts plus the operator-friendly snapshot/quarantine paths required
+ * by the AC envelope shape.
+ *
+ * Surfaces:
+ * - `--dry-run` plan envelopes (with `restoredFrom` being the snapshot that
+ *   *would* be restored and `quarantinedTo` being the directory the corrupt
+ *   DB *would* be moved to).
+ * - Real-recovery envelopes after the pipeline has executed.
+ *
+ * @task T10304
+ * @epic T10286
+ * @saga T10281
+ */
+export interface BackupRecoverBrainResult {
+  /**
+   * 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.
+   */
+  restoredFrom: string;
+  /** Per-table row counts probed from the restored DB. */
+  rowsRecovered: BrainRecoveredRowCounts;
+  /**
+   * Approximate hours between the snapshot's timestamp and the recovery
+   * event. `null` when the snapshot timestamp could not be parsed (e.g.
+   * legacy `brain.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;
+}

package/src/db-inventory.ts

@@ -0,0 +1,227 @@
+/**
+ * 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/core/src/store/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.
+ *
+ * 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
+ * `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 '../../core/src/store/db-inventory.json' with { type: 'json' };
+
+/**
+ * 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;
+}
+
+/**
+ * Shape of the raw JSON SSoT — a header plus the typed entry array.
+ *
+ * @internal
+ */
+interface DbInventoryFile {
+  readonly $schemaNote: string;
+  readonly $pathTokens: Readonly<Record<string, string>>;
+  readonly entries: readonly DbInventoryEntry[];
+}
+
+// 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 as DbInventoryFile;
+
+/**
+ * Immutable canonical inventory of every CLEO SQLite database.
+ *
+ * @remarks
+ * Sourced from `packages/core/src/store/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: readonly DbInventoryEntry[] = rawInventory.entries;