@cleocode/contracts 2026.5.108 → 2026.5.110

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/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/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.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"
+    }
+  ]
+}