@cleocode/core 2026.5.133 → 2026.6.0

package/dist/store/exodus/plan.js

@@ -0,0 +1,178 @@
+/**
+ * Exodus pre-flight plan builder.
+ *
+ * `buildExodusPlan()` computes the full migration plan — source DB paths,
+ * combined size, free-disk availability, staging directory — BEFORE any
+ * writes occur. A `--dry-run` caller can print the plan and exit early.
+ *
+ * ## Disk pre-flight (AC8)
+ *
+ * `availableBytes >= 3 * totalSourceBytes` must hold before migration begins.
+ * The check uses `statvfs` via `node:fs.statfsSync()` (Node 18+).
+ *
+ * @task T11248 (E5 · SG-DB-SUBSTRATE-V2)
+ * @saga T11242
+ */
+import { existsSync, readdirSync, statfsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCleoHome, resolveCleoDir } from '../../paths.js';
+import { resolveDualScopeDbPath } from '../dual-scope-db.js';
+// ---------------------------------------------------------------------------
+// Legacy DB descriptors (AC2 — 6 per-machine source DBs mapped to 2 targets)
+// ---------------------------------------------------------------------------
+/**
+ * Build the ordered list of legacy source DB descriptors for a given project.
+ *
+ * Project-scoped sources live under `<project>/.cleo/`.
+ * Global-scoped sources live under `getCleoHome()`.
+ */
+function buildSourceDescriptors(cwd) {
+    const cleoDir = resolveCleoDir(cwd);
+    const cleoHome = getCleoHome();
+    return [
+        // Project-tier — go into consolidated project-scope cleo.db
+        {
+            name: 'tasks',
+            path: join(cleoDir, 'tasks.db'),
+            targetScope: 'project',
+        },
+        {
+            name: 'brain (project)',
+            path: join(cleoDir, 'brain.db'),
+            targetScope: 'project',
+        },
+        {
+            name: 'conduit',
+            path: join(cleoDir, 'conduit.db'),
+            targetScope: 'project',
+        },
+        // Global-tier — go into consolidated global-scope cleo.db
+        {
+            name: 'nexus',
+            path: join(cleoHome, 'nexus.db'),
+            targetScope: 'global',
+        },
+        {
+            name: 'signaldock',
+            path: join(cleoHome, 'signaldock.db'),
+            targetScope: 'global',
+        },
+        {
+            name: 'skills',
+            path: join(cleoHome, 'skills.db'),
+            targetScope: 'global',
+        },
+    ];
+}
+/**
+ * Safely stat a file and return its size in bytes, or 0 if it does not exist.
+ */
+function safeFileBytes(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Return available bytes on the filesystem that contains `dir`.
+ *
+ * Uses `statfsSync` (Node 18+). Falls back to 0 if unavailable.
+ */
+function getAvailableBytes(dir) {
+    try {
+        const result = statfsSync(dir);
+        // `bfree` = blocks free for privileged processes; `bavail` = unprivileged.
+        return (result.bavail ?? result.bfree ?? 0) * (result.bsize ?? 4096);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Derive the staging directory name from the current ISO-8601 timestamp.
+ *
+ * Pattern: `.cleo/exodus-staging-<YYYYMMDDTHHMMSSZ>`.
+ * Colons are replaced with empty string (NTFS + shell-safe).
+ */
+export function deriveStagingDirName() {
+    const iso = new Date()
+        .toISOString()
+        .replace(/[:]/g, '')
+        .replace(/\..+Z$/, 'Z');
+    return `exodus-staging-${iso}`;
+}
+/**
+ * Scan for an existing staging directory from a previous (possibly crashed)
+ * run inside the given `.cleo/` directory.
+ *
+ * Returns the absolute path to the most-recent staging dir, or `null` if none
+ * exists.
+ */
+function findExistingStaging(cleoDir) {
+    try {
+        const entries = readdirSync(cleoDir, { withFileTypes: true });
+        const stagingDirs = entries
+            .filter((e) => e.isDirectory() && e.name.startsWith('exodus-staging-'))
+            .map((e) => e.name)
+            .sort()
+            .reverse(); // most recent first
+        if (stagingDirs.length > 0) {
+            return join(cleoDir, stagingDirs[0]);
+        }
+    }
+    catch {
+        // .cleo/ may not exist yet
+    }
+    return null;
+}
+/**
+ * Build the complete exodus plan.
+ *
+ * This is a pure read operation — no files are created or modified.
+ * Pass the result to `runExodusMigrate()` to execute the migration.
+ *
+ * @param cwd - Working directory used to resolve the project root. Defaults to
+ *   `process.cwd()`.
+ * @returns {@link ExodusPlan} describing sources, disk availability, and paths.
+ *
+ * @task T11248 (AC8 — 3× disk pre-flight)
+ */
+export function buildExodusPlan(cwd) {
+    const cleoDir = resolveCleoDir(cwd);
+    const sources = buildSourceDescriptors(cwd);
+    // Compute total source size (only existing files count toward the check)
+    const totalSourceBytes = sources.reduce((sum, s) => sum + safeFileBytes(s.path), 0);
+    // Disk pre-flight: check against the directory that will hold the staging data
+    // (the .cleo/ dir, which is where both the backup and staging live).
+    const availableBytes = getAvailableBytes(cleoDir);
+    const diskPreflight = totalSourceBytes === 0 || availableBytes >= 3 * totalSourceBytes;
+    // Staging directory — resume if a previous one exists
+    const existingStaging = findExistingStaging(cleoDir);
+    const stagingDir = existingStaging ?? join(cleoDir, deriveStagingDirName());
+    const resumeFromStaging = existingStaging !== null;
+    // Target paths (consolidated cleo.db)
+    const projectDbPath = resolveDualScopeDbPath('project', cwd);
+    const globalDbPath = resolveDualScopeDbPath('global');
+    return {
+        sources,
+        totalSourceBytes,
+        availableBytes,
+        diskPreflight,
+        stagingDir,
+        resumeFromStaging,
+        projectDbPath,
+        globalDbPath,
+    };
+}
+/**
+ * Check whether all required source DBs exist.
+ *
+ * Returns `true` if at least one source file is present (partial sets are
+ * acceptable — empty tables simply copy zero rows).
+ */
+export function sourcesPresent(sources) {
+    return sources.some((s) => existsSync(s.path));
+}
+//# sourceMappingURL=plan.js.map

package/dist/store/exodus/plan.js.map

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

package/dist/store/exodus/status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Exodus status reporter.
+ *
+ * `runExodusStatus()` returns a structured view of the current exodus state
+ * without performing any reads or writes beyond stat() calls.
+ *
+ * @task T11248 (E5 · AC3 · SG-DB-SUBSTRATE-V2)
+ * @saga T11242
+ */
+import type { ExodusStatusResult } from './types.js';
+/**
+ * Return a structured status report for the exodus subsystem.
+ *
+ * This is a read-only operation — no mutations occur.
+ *
+ * @param cwd - Working directory used to resolve the project root.
+ * @returns {@link ExodusStatusResult}
+ *
+ * @task T11248 (AC3)
+ */
+export declare function runExodusStatus(cwd?: string): ExodusStatusResult;
+//# sourceMappingURL=status.d.ts.map

package/dist/store/exodus/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAiB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA0CpE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CA4BhE"}

package/dist/store/exodus/status.js

@@ -0,0 +1,88 @@
+/**
+ * Exodus status reporter.
+ *
+ * `runExodusStatus()` returns a structured view of the current exodus state
+ * without performing any reads or writes beyond stat() calls.
+ *
+ * @task T11248 (E5 · AC3 · SG-DB-SUBSTRATE-V2)
+ * @saga T11242
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCleoDir } from '../../paths.js';
+import { resolveDualScopeDbPath } from '../dual-scope-db.js';
+import { buildExodusPlan } from './plan.js';
+// ---------------------------------------------------------------------------
+// Journal reader (mirrors logic in migrate.ts — kept local for zero coupling)
+// ---------------------------------------------------------------------------
+const JOURNAL_FILENAME = 'exodus-journal.json';
+function readJournal(stagingDir) {
+    const p = join(stagingDir, JOURNAL_FILENAME);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function findStagingDirs(cleoDir) {
+    try {
+        return readdirSync(cleoDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name.startsWith('exodus-staging-'))
+            .map((e) => join(cleoDir, e.name))
+            .sort()
+            .reverse(); // most-recent first
+    }
+    catch {
+        return [];
+    }
+}
+function safeBytes(p) {
+    try {
+        return statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Main status runner
+// ---------------------------------------------------------------------------
+/**
+ * Return a structured status report for the exodus subsystem.
+ *
+ * This is a read-only operation — no mutations occur.
+ *
+ * @param cwd - Working directory used to resolve the project root.
+ * @returns {@link ExodusStatusResult}
+ *
+ * @task T11248 (AC3)
+ */
+export function runExodusStatus(cwd) {
+    const plan = buildExodusPlan(cwd);
+    const cleoDir = resolveCleoDir(cwd);
+    // Find staging directories
+    const stagingDirs = findStagingDirs(cleoDir);
+    const latestStaging = stagingDirs[0] ?? null;
+    const journal = latestStaging ? readJournal(latestStaging) : null;
+    const projectDbPath = resolveDualScopeDbPath('project', cwd);
+    const globalDbPath = resolveDualScopeDbPath('global');
+    const sourcesInfo = plan.sources.map((s) => ({
+        name: s.name,
+        path: s.path,
+        exists: existsSync(s.path),
+        bytes: safeBytes(s.path),
+    }));
+    return {
+        hasStaging: latestStaging !== null,
+        stagingDir: latestStaging,
+        journal,
+        projectDbExists: existsSync(projectDbPath),
+        globalDbExists: existsSync(globalDbPath),
+        sourcesPresent: sourcesInfo.some((s) => s.exists),
+        sources: sourcesInfo,
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/store/exodus/status.js.map

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

package/dist/store/exodus/table-name-map.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Deterministic legacy-to-consolidated table-name resolver for exodus migration.
+ *
+ * ## Problem (ROOT CAUSE 1 — T11532)
+ *
+ * Legacy source DBs use UNPREFIXED table names (`tasks`, `messages`, `skills`, …)
+ * while the consolidated dual-scope `cleo.db` uses DOMAIN-PREFIXED names
+ * (`tasks_tasks`, `conduit_messages`, `skills_skills`, …). Without a mapping,
+ * every `INSERT OR IGNORE INTO main."<name>"` silently copies 0 rows because the
+ * target table is absent under the legacy name.
+ *
+ * ## Design
+ *
+ * The mapping is a static lookup table derived from reading every
+ * `cleo-project/` and `cleo-global/` schema file and matching the physical
+ * `sqliteTable('<consolidated-name>', …)` names against each legacy DB's schema.
+ *
+ * Rules:
+ *  - If a legacy table is already domain-prefixed in the consolidated schema
+ *    (e.g. `brain_observations`, `nexus_audit_log`, `tasks_goal`), map identity.
+ *  - If a legacy table has NO consolidated counterpart (virtual tables, orphan
+ *    telemetry tables, …), return `null` so the caller can log + skip explicitly
+ *    rather than silently discarding rows.
+ *
+ * ## Source-DB scope
+ *
+ * The resolver takes a `sourceName` (the `LegacyDbDescriptor.name` value, e.g.
+ * `"tasks"`, `"brain (project)"`, `"conduit"`) to disambiguate tables that
+ * share the same legacy name across multiple DBs (e.g. `"attachments"` lives in
+ * both conduit.db and attachments.ts/tasks.db; `"sessions"` lives in both
+ * tasks.db and signaldock.db).
+ *
+ * ## Nexus code-graph residency move (ADR-090 · T11539)
+ *
+ * The four nexus code-graph tables — `nexus_nodes`, `nexus_relations`,
+ * `nexus_contracts`, `nexus_code_index` (ADR-090 "Category A") — were removed
+ * from the GLOBAL schema (`../schema/cleo-global/nexus.ts`) and now reside in
+ * PROJECT scope (`../schema/cleo-project/nexus-graph.ts`). They are still
+ * extracted from the legacy GLOBAL `nexus.db` source, but exodus MUST route them
+ * into the PROJECT-scope consolidated `cleo.db`, not the global one. The source
+ * descriptor `nexus` carries `targetScope: 'global'`, so a per-table scope
+ * override is required for these four tables — see
+ * {@link NEXUS_GRAPH_PROJECT_TABLES} and {@link resolveTableTargetScope}. The
+ * six registry/identity tables (`nexus_project_registry`,
+ * `nexus_project_id_aliases`, `nexus_audit_log`, `nexus_schema_meta`,
+ * `nexus_user_profile`, `nexus_sigils`) stay GLOBAL.
+ *
+ * @task T11532 (ROOT CAUSE 1 — name-mapping gap)
+ * @task T11533 (ROOT CAUSE 3 — signaldock skills mapping + brain_release_links skip +
+ *               brain_session_narrative mapping)
+ * @task T11546 (no-home-table fixes — schema_meta→tasks_schema_meta, brain_usage_log mapping,
+ *               brain_schema_meta mapping)
+ * @task T11539 (nexus code-graph residency — route the 4 graph tables to PROJECT scope)
+ * @epic T11248
+ * @saga T11242
+ */
+import type { ExodusScope } from './types.js';
+/**
+ * Legacy table names of the four nexus code-graph tables that moved from GLOBAL
+ * to PROJECT scope (ADR-090 · T11538/T11539).
+ *
+ * Keyed by the LEGACY physical name as it appears in `nexus.db`:
+ *   - `nexus_nodes`, `nexus_relations`, `nexus_contracts` — already prefixed.
+ *   - `code_index` — bare in legacy `nexus.db`; → `nexus_code_index` consolidated.
+ *
+ * Membership drives {@link resolveTableTargetScope}: exodus copies/verifies
+ * these against the PROJECT consolidated `cleo.db`, NOT the GLOBAL one, even
+ * though the `nexus` source descriptor's `targetScope` is `'global'`.
+ *
+ * @task T11539
+ * @epic T11248
+ * @saga T11242
+ * @see cleo docs fetch adr-090-nexus-graph-residency-split
+ */
+export declare const NEXUS_GRAPH_PROJECT_TABLES: ReadonlySet<string>;
+/**
+ * Resolve the consolidated TARGET SCOPE for a legacy source table.
+ *
+ * Most tables share the scope of their source DB descriptor (`sourceScope`).
+ * The exception is the four nexus code-graph tables — they are extracted from
+ * the GLOBAL legacy `nexus.db` but land in PROJECT scope per ADR-090 (T11539).
+ *
+ * This is the SSoT consumed by BOTH the exodus migrate runner (insert target DB)
+ * and the exodus verifier (verify target DB) so the two never disagree.
+ *
+ * @param sourceName  - `LegacyDbDescriptor.name` (e.g. `"nexus"`, `"tasks"`).
+ * @param legacyTable - Physical table name in the legacy source DB.
+ * @param sourceScope - The source descriptor's `targetScope`.
+ * @returns The scope of the consolidated `cleo.db` this table copies into.
+ *
+ * @task T11539
+ * @epic T11248
+ * @saga T11242
+ */
+export declare function resolveTableTargetScope(sourceName: string, legacyTable: string, sourceScope: ExodusScope): ExodusScope;
+/**
+ * Return `true` if `tableName` is a DERIVED or INTERNAL table that must be
+ * EXCLUDED from the exodus row-count-parity gate (and from the copy path).
+ *
+ * This is the single, named, documented classification consumed by BOTH the
+ * migrate copy loop and the `verifyMigration` parity check, so the two never
+ * disagree about which tables carry migratable user data. It recognises:
+ *
+ *   1. **FTS5 virtual tables** — a bare `*_fts` name (e.g. `brain_decisions_fts`,
+ *      `messages_fts`). The virtual table itself cannot be `INSERT … SELECT`-ed
+ *      and is rebuilt from its content table after migration.
+ *   2. **FTS5 shadow/backing tables** — `*_fts_data`, `*_fts_idx`,
+ *      `*_fts_docsize`, `*_fts_config`, `*_fts_content` (see
+ *      {@link FTS5_SHADOW_SUFFIXES}). Derived; rebuilt post-migration.
+ *   3. **Internal bookkeeping** — any per-source schema-version / migration
+ *      ledger: `_conduit_meta`, `_conduit_migrations`, `_signaldock_meta`,
+ *      `_signaldock_migrations`, `_skills_meta`, and — generalised via
+ *      {@link INTERNAL_LEDGER_PATTERN} — ANY `_<domain>_meta` /
+ *      `_<domain>_migrations` ledger from a future source DB (see
+ *      {@link INTERNAL_BOOKKEEPING_TABLES}). Schema-version ledgers with no
+ *      consolidated home.
+ *
+ * A migration is "safe" iff every BASE-DATA row survives; these derived/internal
+ * tables are NOT base data, so a 0-row consolidated counterpart for them is
+ * expected and correct — not data loss.
+ *
+ * @param tableName - Physical table name from a legacy source DB.
+ * @returns `true` when the table is derived/internal and must be skipped.
+ *
+ * @task T11572 (exodus parity gate: exclude FTS5 + internal/meta shadow tables)
+ * @task T11577 (generalise internal-ledger skip to signaldock/skills + any per-source ledger)
+ * @epic T11249 (E6)
+ * @saga T11242
+ */
+export declare function isDerivedOrInternalTable(tableName: string): boolean;
+/**
+ * Result of resolving a legacy table name to its consolidated target.
+ *
+ * `kind === 'mapped'`  — `targetName` holds the consolidated physical name.
+ * `kind === 'skip'`    — table is intentionally excluded (virtual, orphan, etc.);
+ *                        `reason` holds a human-readable explanation.
+ * `kind === 'unknown'` — source DB is unrecognized; falls back to identity copy
+ *                        (best-effort for forward-compatibility with future DBs).
+ */
+export type TableNameResolution = {
+    readonly kind: 'mapped';
+    readonly targetName: string;
+} | {
+    readonly kind: 'skip';
+    readonly reason: string;
+} | {
+    readonly kind: 'unknown';
+    readonly targetName: string;
+};
+/**
+ * Resolve the consolidated target table name for a legacy source table.
+ *
+ * @param sourceName  - `LegacyDbDescriptor.name` (e.g. `"tasks"`, `"brain (project)"`).
+ * @param legacyTable - Physical table name from the legacy source DB.
+ * @returns A `TableNameResolution` describing how to copy (or skip) the table.
+ */
+export declare function resolveConsolidatedTableName(sourceName: string, legacyTable: string): TableNameResolution;
+/**
+ * Reverse-lookup: given a consolidated target table name, return the set of
+ * legacy (sourceName, legacyTableName) pairs that map to it.
+ *
+ * Used by `runExodusVerify()` to compare legacy source counts against the
+ * correct consolidated target table rather than the legacy table name.
+ *
+ * Returns an empty array if no legacy table maps to the given consolidated name.
+ */
+export declare function reverseLookup(consolidatedTable: string, sources: ReadonlyArray<{
+    readonly name: string;
+}>): Array<{
+    sourceName: string;
+    legacyTable: string;
+}>;
+//# sourceMappingURL=table-name-map.d.ts.map

package/dist/store/exodus/table-name-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-name-map.d.ts","sourceRoot":"","sources":["../../../src/store/exodus/table-name-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA4O9C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAKzD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,WAAW,GACvB,WAAW,CAKb;AAoKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAUnE;AAMD;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,mBAAmB,CA6DrB;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAChD,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCpD"}