@cleocode/contracts 2026.5.108 → 2026.5.110

package/dist/__tests__/db-inventory.test.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=db-inventory.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db-inventory.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/db-inventory.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/__tests__/db-inventory.test.js

@@ -0,0 +1,148 @@
+/**
+ * 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 } 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 = new Set(['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 = [
+    '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(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 = [
+            '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);
+            }
+        }
+    });
+});
+//# sourceMappingURL=db-inventory.test.js.map

package/dist/__tests__/db-inventory.test.js.map

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

package/dist/__tests__/memory-wire-shapes.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-wire-shapes.test.js","sourceRoot":"","sources":["../../src/__tests__/memory-wire-shapes.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"memory-wire-shapes.test.js","sourceRoot":"","sources":["../../src/__tests__/memory-wire-shapes.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAa9C,OAAO,EACL,8BAA8B,GAI/B,MAAM,sBAAsB,CAAC;AAmO9B,uEAAuE;AAEvE,QAAQ,CAAC,qCAAqC,EAAE,GAAG,EAAE;IACnD,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,GAAG,GAAoB;YAC3B,EAAE,EAAE,UAAU;YACd,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,QAAQ;YACf,IAAI,EAAE,sBAAsB;SAC7B,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,MAAM,GAA6B;YACvC,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;YAC7E,KAAK,EAAE,CAAC;YACR,eAAe,EAAE,EAAE;SACpB,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,MAAM,GAAgB,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpF,MAAM,MAAM,GAAwB;YAClC,MAAM;YACN,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;YACnE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;SACnE,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,MAAM,GAAwB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC5E,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,MAAM,GAA4B;YACtC,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YACzD,QAAQ,EAAE,CAAC,WAAW,CAAC;YACvB,eAAe,EAAE,GAAG;SACrB,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wFAAwF,EAAE,GAAG,EAAE;QAChG,MAAM,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC;YAC7C,OAAO;YACP,iBAAiB;YACjB,YAAY;YACZ,QAAQ;SACT,CAAC,CAAC;QACH,oDAAoD;QACpD,MAAM,MAAM,GAAiC,CAAC,GAAG,8BAA8B,CAAC,CAAC;QACjF,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,MAAM,GAAuB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,MAAM,GAAuB;YACjC,EAAE,EAAE,OAAO;YACX,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,sBAAsB;SAClC,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,IAAI,GAA6B;YACrC,KAAK,EAAE,CAAC,UAAU,EAAE,YAAY,CAAC;YACjC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;YACzB,QAAQ,EAAE,IAAI;SACf,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,MAAM,MAAM,GAAmB;YAC7B,OAAO,EAAE;gBACP;oBACE,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,UAAU;oBAChB,KAAK,EAAE,SAAS;oBAChB,IAAI,EAAE,MAAM;oBACZ,KAAK,EAAE,IAAI;oBACX,eAAe,EAAE,EAAE;iBACpB;aACF;YACD,UAAU,EAAE,EAAE;YACd,eAAe,EAAE,GAAG;YACpB,QAAQ,EAAE,CAAC;SACZ,CAAC;QACF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/task-type-narrowing.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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)
+ */
+export {};
+//# sourceMappingURL=task-type-narrowing.test.d.ts.map

package/dist/__tests__/task-type-narrowing.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-type-narrowing.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/task-type-narrowing.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/task-type-narrowing.test.js

@@ -0,0 +1,51 @@
+/**
+ * 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';
+describe('TaskType discriminator', () => {
+    it('narrows when type === "saga"', () => {
+        const t = {
+            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();
+        }
+    });
+    it('narrows when type === "epic"', () => {
+        const t = {
+            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();
+        }
+    });
+    it('accepts all 4 tier values', () => {
+        const types = ['saga', 'epic', 'task', 'subtask'];
+        expectTypeOf(types).toEqualTypeOf();
+    });
+    it('TaskType is the 4-element union per ADR-083 §2.5', () => {
+        expectTypeOf().toEqualTypeOf();
+    });
+});
+//# sourceMappingURL=task-type-narrowing.test.js.map

package/dist/__tests__/task-type-narrowing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-type-narrowing.test.js","sourceRoot":"","sources":["../../src/__tests__/task-type-narrowing.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAGpD,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAS;YACd,EAAE,EAAE,IAAI;YACR,KAAK,EAAE,MAAM;YACb,WAAW,EAAE,WAAW;YACxB,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,0BAA0B;SACtC,CAAC;QACF,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACtB,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAU,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAS;YACd,EAAE,EAAE,IAAI;YACR,KAAK,EAAE,MAAM;YACb,WAAW,EAAE,WAAW;YACxB,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,0BAA0B;SACtC,CAAC;QACF,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACtB,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,EAAU,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,KAAK,GAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QAC9D,YAAY,CAAC,KAAK,CAAC,CAAC,aAAa,EAAc,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,YAAY,EAAY,CAAC,aAAa,EAAwC,CAAC;IACjF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/backup-verify.d.ts

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

package/dist/backup-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-verify.d.ts","sourceRoot":"","sources":["../src/backup-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC7D,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC"}

package/dist/backup-verify.js

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

package/dist/backup-verify.js.map

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

package/dist/brain.d.ts

@@ -85,4 +85,107 @@ export interface SupersededEntry {
     /** Topic or category grouping these entries together. */
     grouping: string;
 }
+/**
+ * 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;
+}
+/**
+ * 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;
+}
 //# sourceMappingURL=brain.d.ts.map

package/dist/brain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../src/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,cAAc,GAAG,OAAO,GAAG,aAAa,CAAC;AAEvF,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,MAAM,EAAE,aAAa,CAAC;IACtB,8CAA8C;IAC9C,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iDAAiD;IACjD,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../src/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAExE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,cAAc,GAAG,OAAO,GAAG,aAAa,CAAC;AAEvF,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,MAAM,EAAE,aAAa,CAAC;IACtB,8CAA8C;IAC9C,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iDAAiD;IACjD,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;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"}