@cleocode/core 2026.5.134 → 2026.6.0

package/dist/store/exodus/on-open.js

@@ -0,0 +1,464 @@
+/**
+ * Exodus-on-open — lazy, idempotent, parity-gated auto-migration of the legacy
+ * multi-DB fleet into the consolidated dual-scope `cleo.db` on first open.
+ *
+ * ## Why this exists (data-continuity safety net · T11553)
+ *
+ * E6 routes every `getDb`/`getBrainDb`/etc read at the consolidated `cleo.db`.
+ * On an *existing* install the consolidated DB is freshly migrated but **empty**
+ * (0 base-table rows), while the user's real data still lives in the legacy
+ * `tasks.db` / `brain.db` / `conduit.db` / `signaldock.db` fleet (e.g. 4465
+ * tasks). Without an auto-migration the E8/T11251 cutover would make every
+ * user's data **invisible**. This module wires the existing `runExodusMigrate`
+ * engine to run **once, automatically, on first open** — gated by the
+ * `verifyMigration` (T11551) parity check so a partial or lossy migration NEVER
+ * becomes the live source of truth.
+ *
+ * ## Trigger condition (AC1)
+ *
+ * On first `openDualScopeDb(scope)` the hook runs iff **both**:
+ *   1. the consolidated `cleo.db` for that scope is EMPTY (the canonical first
+ *      base table has zero rows), AND
+ *   2. at least one legacy source DB for that scope has rows.
+ *
+ * ## Idempotency (AC1)
+ *
+ * After a successful migration the consolidated DB is non-empty, so the
+ * emptiness check short-circuits on every subsequent open — a second open is a
+ * no-op. The check is also re-evaluated *inside* the single-flight lock
+ * (double-checked locking) so the process that loses a concurrency race never
+ * re-migrates.
+ *
+ * ## Parity gate + clean abort (AC2)
+ *
+ * After the copy, `verifyMigration` (T11551) compares row counts + canonical
+ * digests + FK integrity + enum drift legacy↔consolidated. The data-continuity
+ * gate is **row-count parity + zero migration-INTRODUCED FK orphans** (hash/enum
+ * drift are the expected normalisation diagnostics, and pre-existing SOURCE FK
+ * orphans are tolerated as zero-loss — see {@link isDataContinuityOk}). If a
+ * genuine deficit/introduced-orphan is detected the hook **aborts the cutover**:
+ * it rolls the half-migrated consolidated tables back to EMPTY (`DELETE FROM`
+ * every user table — see {@link rollbackConsolidatedToEmpty}) so the legacy DBs
+ * remain the source of truth, no half-migrated `cleo.db` is exposed, and there
+ * are no silent `INSERT OR IGNORE` row drops. The file is never unlinked; the
+ * chokepoint re-opens a fresh handle afterwards (the migrate engine closes the
+ * handles it opened, so the rollback re-opens the scope before truncating it).
+ *
+ * ## Retry correctness — journal invalidation on abort (T11572)
+ *
+ * `runExodusMigrate` is resumable: it journals each table `done` and SKIPS
+ * already-`done` tables on a re-run. On abort we truncate the consolidated rows
+ * back to empty, so a stale `done` journal would make the next open re-trigger
+ * (target empty), copy NOTHING (journal says done), re-verify the still-empty
+ * target, and re-abort — a permanent loop. The abort path therefore also calls
+ * `clearExodusJournal(plan.stagingDir)` so a post-abort retry RE-COPIES from
+ * scratch.
+ *
+ * ## Concurrency safety (AC6 · reconcile with T11554 / R13-T11278)
+ *
+ * Two processes opening a brand-new empty `cleo.db` simultaneously must not both
+ * migrate. A `proper-lockfile` single-flight lock on
+ * `<cleo.db>.exodus-on-open.lock` serialises the attempt; the loser re-checks
+ * emptiness under the lock and bails. This is the same first-run-race concern
+ * T11554 raises for schema bootstrap — both are solved by serialising the
+ * first-open mutation.
+ *
+ * @module
+ * @task T11553 (E6 · exodus-on-open)
+ * @epic T11249 (E6)
+ * @saga T11242 (SG-DB-SUBSTRATE-V2)
+ * @see packages/core/src/store/exodus/migrate.ts — runExodusMigrate engine
+ * @see packages/core/src/store/exodus/verify-migration.ts — verifyMigration parity gate (T11551)
+ * @see packages/core/src/store/dual-scope-db.ts — the open chokepoint that calls this
+ */
+import { existsSync } from 'node:fs';
+import { getLogger } from '../../logger.js';
+import { withLock } from '../lock.js';
+const log = getLogger('exodus-on-open');
+/**
+ * Re-entrancy guard. `runExodusMigrate` itself calls `openDualScopeDb` for both
+ * scopes to create + populate the consolidated schema. Those nested opens MUST
+ * NOT recursively trigger another exodus-on-open. This flag is set for the
+ * duration of an auto-migration so the chokepoint skips the hook while a
+ * migration is already in flight.
+ */
+let _exodusInProgress = false;
+/**
+ * Opt-out env flag. Set `CLEO_DISABLE_EXODUS_ON_OPEN=1` to skip the lazy
+ * auto-migration entirely (e.g. for tooling that intentionally inspects an
+ * empty consolidated DB). The manual `cleo exodus migrate` path is unaffected.
+ */
+function isDisabledByEnv() {
+    const v = process.env.CLEO_DISABLE_EXODUS_ON_OPEN;
+    return v === '1' || v === 'true';
+}
+/**
+ * The canonical "first base table" for each scope — the same existence anchor
+ * used by the migration journal reconciliation. If this table has zero rows the
+ * consolidated DB is considered empty for the purposes of the trigger.
+ *
+ * - project → `tasks_tasks`
+ * - global  → `nexus_project_registry`
+ */
+function baseTableForScope(scope) {
+    return scope === 'project' ? 'tasks_tasks' : 'nexus_project_registry';
+}
+/**
+ * Count rows in `table` on `nativeDb`, returning `0` if the table does not yet
+ * exist or the query fails. Used to decide whether the consolidated DB is empty.
+ */
+function safeRowCount(nativeDb, table) {
+    try {
+        const row = nativeDb.prepare(`SELECT COUNT(*) AS n FROM "${table}"`).get();
+        return row?.n ?? 0;
+    }
+    catch {
+        // Table missing (pre-migration) or other read error → treat as empty.
+        return 0;
+    }
+}
+/**
+ * Return `true` if the consolidated `cleo.db` for `scope` is empty — i.e. the
+ * canonical base table for that scope has zero rows.
+ */
+function consolidatedIsEmpty(nativeDb, scope) {
+    return safeRowCount(nativeDb, baseTableForScope(scope)) === 0;
+}
+/**
+ * Roll a half-migrated consolidated `cleo.db` back to EMPTY **in place**, on the
+ * caller's live handle — without closing the handle or deleting the file.
+ *
+ * Called on a parity-failure abort. `runExodusMigrate` writes into the SAME
+ * cached native handle the chokepoint caller is using (the cache is keyed by
+ * path), so we must NOT close it or unlink the file out from under the caller
+ * (`getBrainDb`/`ensureConduitDb` would then hit "database is not open"). Instead
+ * we `DELETE FROM` every user table inside a single transaction with foreign
+ * keys OFF, restoring the post-migration *empty* schema. The caller then
+ * proceeds with an empty `cleo.db` and the legacy DBs remain the source of
+ * truth — exactly the AC2 "no half-migrated cleo.db" contract, achieved without
+ * destroying the open handle.
+ *
+ * The schema (tables, indexes, drizzle journal) is preserved; only data rows are
+ * removed. Idempotent and best-effort: a failure to clear one table is logged
+ * but does not throw (the next open's emptiness check still sees a populated
+ * base table and could re-attempt, which is acceptable — it will re-abort).
+ *
+ * @param nativeDb - The live consolidated handle to truncate.
+ * @param scope    - Scope label for logging.
+ */
+function rollbackConsolidatedToEmpty(nativeDb, scope) {
+    let userTables = [];
+    try {
+        userTables = nativeDb
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__drizzle_%'")
+            .all().map((r) => r.name);
+    }
+    catch (err) {
+        log.error({ err, scope }, 'exodus-on-open: failed to enumerate tables for rollback');
+        return;
+    }
+    try {
+        nativeDb.exec('PRAGMA foreign_keys = OFF');
+        nativeDb.exec('BEGIN');
+        for (const table of userTables) {
+            try {
+                nativeDb.exec(`DELETE FROM "${table}"`);
+            }
+            catch (err) {
+                log.warn({ err, table, scope }, 'exodus-on-open: failed to clear table during rollback');
+            }
+        }
+        nativeDb.exec('COMMIT');
+    }
+    catch (err) {
+        try {
+            nativeDb.exec('ROLLBACK');
+        }
+        catch {
+            // ignore — nothing to roll back
+        }
+        log.error({ err, scope }, 'exodus-on-open: rollback transaction failed');
+    }
+    finally {
+        try {
+            nativeDb.exec('PRAGMA foreign_keys = ON');
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/**
+ * Roll BOTH consolidated scopes back to empty after a failed auto-migration.
+ *
+ * IMPORTANT: `runExodusMigrate` closes the dual-scope handles it opened (and
+ * evicts them from the chokepoint cache) when it finishes — including on
+ * failure. Any `nativeDb` reference captured before the migrate ran is therefore
+ * already CLOSED, so we must NOT operate on it. Instead we re-open each scope
+ * fresh from the chokepoint (a cache-miss → a new live handle on the same
+ * on-disk file, which still holds the half-migrated rows) and truncate THAT.
+ * `_exodusInProgress` is still `true`, so the re-opens do not recurse into the
+ * hook.
+ *
+ * @param scope - The scope being opened (logging context only; both scopes are
+ *   cleared because `runExodusMigrate` populates both).
+ */
+async function rollbackBothScopes(scope) {
+    const { openDualScopeDb } = await import('../dual-scope-db.js');
+    for (const s of ['project', 'global']) {
+        try {
+            const handle = s === 'project' ? await openDualScopeDb('project') : await openDualScopeDb('global');
+            const native = handle.db.$client;
+            if (native) {
+                rollbackConsolidatedToEmpty(native, s);
+            }
+        }
+        catch (err) {
+            log.warn({ err, scope: s, openingScope: scope }, 'exodus-on-open: could not roll back scope (best-effort)');
+        }
+    }
+}
+/**
+ * Decide whether a {@link verifyMigration} result clears the **data-continuity**
+ * gate — the campaign-aligned zero-loss invariant (DHQ-045 · T11551).
+ *
+ * `verifyMigration().ok` is intentionally STRICTER than data-continuity: it also
+ * requires `hashMatch` and zero enum-drift findings. After a CORRECT migration
+ * those two will legitimately be `false`, because the migration NORMALISES the
+ * data (legacy enum aliases like `'ACCEPTED'`→`'accepted'`, epoch→ISO
+ * timestamps) — so the consolidated content digest differs from the un-normalised
+ * source, and the source still reports its raw drift as a diagnostic. Treating
+ * that as a parity failure would abort EVERY real migration.
+ *
+ * The zero-loss invariant the exodus campaign actually proves (and the one the
+ * representative real-data parity test asserts) is:
+ *
+ *   1. every data-bearing base table copied with NO ROW DEFICIT
+ *      (`targetCount >= sourceCount` — you cannot LOSE a row you have MORE of),
+ *      AND
+ *   2. NO referential orphans the migration INTRODUCED on the consolidated
+ *      target (`introducedForeignKeyViolations` empty).
+ *
+ * ## A row SURPLUS is NOT data loss (T11577)
+ *
+ * Data loss means rows are MISSING: `targetCount < sourceCount` (a DEFICIT).
+ * A SURPLUS (`targetCount > sourceCount`) cannot be loss — every source row is
+ * still present, plus extra. The canonical benign surplus is the migration's
+ * OWN audit trail: `runExodusMigrate` opens the nexus registry, whose
+ * `writeNexusAudit` (`nexus/registry.ts`) appends rows to `nexus_audit_log`
+ * DURING the migrating open, so the consolidated `nexus_audit_log` legitimately
+ * has a few MORE rows than the legacy source (e.g. 161923 → 161926). Gating on
+ * exact `countMatch` (`source === target`) wrongly aborts the cutover on that
+ * append. The gate therefore fails ONLY on a genuine DEFICIT; a surplus is
+ * tolerated and logged as a WARN (with the table + delta) so it stays visible
+ * and a double-copy on a non-append table could still be spotted by an operator.
+ * Deficits are NEVER tolerated — that is the real data-loss class.
+ *
+ * ## Pre-existing source orphans are tolerated (T11572)
+ *
+ * A legacy source DB can already contain referential orphans (e.g. a
+ * `tasks_task_relations` row pointing at a task that was deleted long before the
+ * migration). Those rows copy through faithfully — that is ZERO loss, not a
+ * migration defect — so they appear on BOTH sides and `verifyMigration`
+ * classifies them as `preExistingForeignKeyViolations`. Gating on the *total*
+ * orphan set (`foreignKeyViolations`) would permanently abort every real cutover
+ * over a defect the data already had. The gate therefore fails ONLY on
+ * `introducedForeignKeyViolations` — orphans present on the target that the
+ * source did not have (i.e. the migration dropped a parent row). Pre-existing
+ * orphans are logged as a WARN for a data-hygiene follow-up.
+ *
+ * Hash mismatch + source enum-drift are surfaced as WARN diagnostics (a true
+ * content corruption would normally also show up as an introduced FK orphan or a
+ * count deficit), but they do NOT, on their own, indicate data loss.
+ *
+ * @param result - The {@link VerifyMigrationResult} from `verifyMigration`.
+ * @returns `true` when NO base table has a row DEFICIT (`targetCount <
+ *   sourceCount`) and the migration introduced no new FK orphans — i.e. the
+ *   cutover is safe. A surplus (`targetCount > sourceCount`) is tolerated.
+ *
+ * @task T11577 (deficit-only gate — tolerate benign migration-time surplus)
+ */
+export function isDataContinuityOk(result) {
+    // A DEFICIT (target has FEWER rows than source) is the genuine data-loss
+    // class — abort. A SURPLUS (target has MORE, e.g. nexus_audit_log gaining the
+    // migration's own audit writes) is NOT loss; tolerate it but log a WARN so the
+    // table + delta stay visible (a surplus on a non-append table could hint at a
+    // double-copy worth an operator's attention).
+    const deficits = result.tables.filter((t) => t.targetCount < t.sourceCount);
+    const surpluses = result.tables.filter((t) => t.targetCount > t.sourceCount);
+    if (surpluses.length > 0) {
+        log.warn({
+            surpluses: surpluses.map((t) => ({
+                table: t.targetTable,
+                scope: t.scope,
+                source: t.sourceCount,
+                target: t.targetCount,
+                delta: t.targetCount - t.sourceCount,
+            })),
+        }, `exodus-on-open: ${surpluses.length} table(s) have MORE rows in target than source ` +
+            `(row surplus — NOT data loss, tolerated; e.g. migration-time nexus_audit_log writes). ` +
+            `Verify none is an unexpected double-copy on a non-append table.`);
+    }
+    return deficits.length === 0 && result.introducedForeignKeyViolations.length === 0;
+}
+/**
+ * Lazily migrate the legacy fleet into the consolidated `cleo.db` on first open.
+ *
+ * This is the thin guard wired into {@link openDualScopeDb}. It is invoked AFTER
+ * the consolidated schema migrations have run (so the base tables exist) but
+ * BEFORE the handle is returned to the caller. It is a no-op unless the trigger
+ * condition (AC1) holds.
+ *
+ * Re-entrancy, concurrency, parity gating, and clean abort are all handled here
+ * — see the module docs. The heavy lifting (copy, journal, backup, attach-leak
+ * safety) is delegated to the existing {@link runExodusMigrate} engine; this
+ * function adds only the *when* (lazy trigger) and the *safety envelope*
+ * (single-flight + verify-or-rollback).
+ *
+ * On a parity-failure abort the migration's writes are rolled back IN PLACE on
+ * the caller's live handle (see {@link rollbackConsolidatedToEmpty}) — the
+ * handle is never closed and the file is never deleted, so the chokepoint caller
+ * (`getBrainDb`/`ensureConduitDb`/…) keeps a valid, empty `cleo.db` and the
+ * legacy DBs remain the source of truth.
+ *
+ * @param scope       - The scope being opened (`'project'` | `'global'`).
+ * @param dbPath      - Absolute path to the consolidated `cleo.db` for `scope`.
+ * @param nativeDb    - The freshly-opened native handle (post-migration). This is
+ *                      the SAME cached handle `runExodusMigrate` writes through,
+ *                      so the rollback truncates it in place rather than deleting.
+ * @param cwd         - Working directory used to resolve the project root.
+ * @returns The {@link ExodusOnOpenResult} describing what happened.
+ *
+ * @task T11553 (AC1, AC2, AC6)
+ * @epic T11249 (E6)
+ * @saga T11242
+ */
+export async function maybeRunExodusOnOpen(scope, dbPath, nativeDb, cwd) {
+    // Re-entrancy: the nested opens from runExodusMigrate must never recurse.
+    if (_exodusInProgress) {
+        return { outcome: 'skipped', reason: 're-entrant open during active migration' };
+    }
+    if (isDisabledByEnv()) {
+        return { outcome: 'skipped', reason: 'CLEO_DISABLE_EXODUS_ON_OPEN set' };
+    }
+    // Fast path (unlocked): if the consolidated DB already has data, nothing to do.
+    // This makes the second-open case a cheap COUNT(*) with no lock acquisition.
+    if (!consolidatedIsEmpty(nativeDb, scope)) {
+        return { outcome: 'skipped', reason: 'consolidated cleo.db already populated' };
+    }
+    // Lazy-load the exodus engine via dynamic import to break the import cycle
+    // (exodus/migrate.ts imports openDualScopeDb from dual-scope-db.ts).
+    const { buildExodusPlan, runExodusMigrate, verifyMigration, clearExodusJournal } = await import('./index.js');
+    const plan = buildExodusPlan(cwd);
+    // Trigger ONLY on sources that belong to the SCOPE being opened. A
+    // project-scope open must not fire because a GLOBAL legacy DB (e.g.
+    // signaldock.db) happens to exist — that would (a) wrongly migrate global
+    // data on a project read and (b) collide with the legacy signaldock→conduit
+    // migration, which legitimately opens an empty project `cleo.db` while a
+    // global signaldock.db is present. The migration engine still consolidates
+    // BOTH scopes once triggered; this gate only decides WHEN to fire.
+    const scopeSources = plan.sources.filter((s) => s.targetScope === scope);
+    if (!scopeSources.some((s) => existsSync(s.path))) {
+        return {
+            outcome: 'skipped',
+            reason: `no legacy ${scope}-scope source DBs present (fresh install or cross-scope-only)`,
+        };
+    }
+    // Single-flight: serialise the first-open migration across processes so two
+    // concurrent opens never both migrate (AC6 · T11554 first-run race).
+    const lockPath = `${dbPath}.exodus-on-open.lock`;
+    return withLock(lockPath, async () => {
+        // Double-checked locking: a process that lost the race will find the DB
+        // already populated (by the winner) and bail without re-migrating.
+        if (!consolidatedIsEmpty(nativeDb, scope)) {
+            return { outcome: 'skipped', reason: 'migrated by a concurrent process (lock winner)' };
+        }
+        log.info({
+            scope,
+            dbPath,
+            sources: plan.sources.filter((s) => existsSync(s.path)).map((s) => s.name),
+        }, 'exodus-on-open: consolidated cleo.db is empty and legacy data present — auto-migrating');
+        _exodusInProgress = true;
+        try {
+            // 1. Run the migration engine (copies BOTH scopes; idempotent + journaled).
+            const migrateResult = await runExodusMigrate(plan, false, (msg) => log.debug({ scope }, `exodus-on-open: ${msg}`));
+            if (!migrateResult.ok) {
+                // Migration itself failed mid-copy — abort the cutover cleanly by
+                // rolling the consolidated tables back to empty IN PLACE (handle stays
+                // open; legacy DBs remain the source of truth).
+                await rollbackBothScopes(scope);
+                // T11572: invalidate the journal so the NEXT open re-copies instead of
+                // resuming a half-done journal against the now-empty target (abort loop).
+                clearExodusJournal(migrateResult.stagingDir);
+                const reason = `migration failed: ${migrateResult.error ?? 'unknown error'} — legacy DBs kept as source`;
+                log.error({ scope, error: migrateResult.error }, `exodus-on-open: ${reason}`);
+                return { outcome: 'aborted', reason };
+            }
+            // 2. PARITY GATE (AC2): verifyMigration (T11551) — row-count + content
+            //    digest + FK integrity + enum-drift equivalence legacy↔consolidated.
+            const verifyResult = verifyMigration(plan.sources, plan.projectDbPath, plan.globalDbPath, (msg) => log.debug({ scope }, `exodus-on-open verify: ${msg}`));
+            // Surface diagnostics (hash mismatch / source enum-drift) but do NOT
+            // abort on them — see isDataContinuityOk(). A correct normalising
+            // migration legitimately produces both; only a row-count deficit or an
+            // FK orphan means actual data loss.
+            if (!verifyResult.ok) {
+                log.warn({
+                    scope,
+                    enumDrift: verifyResult.enumDrift.length,
+                    hashMismatches: verifyResult.tables.filter((t) => !t.hashMatch).length,
+                }, 'exodus-on-open: verifyMigration reported non-fatal drift (normalisation expected); checking data-continuity gate');
+            }
+            if (!isDataContinuityOk(verifyResult)) {
+                // DATA LOSS (count deficit or FK orphan) → abort. Roll the half-migrated
+                // consolidated tables back to EMPTY in place so legacy remains the
+                // source of truth. Never expose a lossy consolidated DB; never close the
+                // caller's handle.
+                await rollbackBothScopes(scope);
+                // T11572: invalidate the journal so a retry re-copies (see above).
+                clearExodusJournal(plan.stagingDir);
+                // T11577: report only genuine DEFICITS (target < source) — a surplus
+                // is tolerated by isDataContinuityOk() and must not appear as a cause.
+                const deficits = verifyResult.tables
+                    .filter((t) => t.targetCount < t.sourceCount)
+                    .map((t) => `${t.targetTable}(${t.sourceCount}→${t.targetCount})`);
+                const reason = `parity verification failed — cutover aborted, legacy DBs kept as source. ` +
+                    `count deficits: [${deficits.join(', ')}]; ` +
+                    `INTRODUCED fk orphans: ${verifyResult.introducedForeignKeyViolations.length} ` +
+                    `(pre-existing source orphans tolerated: ${verifyResult.preExistingForeignKeyViolations.length}). ` +
+                    `${verifyResult.error ?? ''}`.trim();
+                log.error({
+                    scope,
+                    countDeficits: deficits,
+                    introducedFkViolations: verifyResult.introducedForeignKeyViolations.length,
+                    preExistingFkViolations: verifyResult.preExistingForeignKeyViolations.length,
+                }, 'exodus-on-open: data-continuity FAILED — consolidated cleo.db rolled back to empty, legacy kept');
+                return { outcome: 'aborted', reason };
+            }
+            const rowsCopied = migrateResult.tables
+                .filter((t) => !t.skipped)
+                .reduce((n, t) => n + t.rowsCopied, 0);
+            log.info({ scope, rowsCopied, tables: migrateResult.tables.length }, 'exodus-on-open: parity verified — legacy data migrated into consolidated cleo.db');
+            return {
+                outcome: 'migrated',
+                reason: `migrated ${rowsCopied} rows across ${migrateResult.tables.length} tables; parity verified`,
+                rowsCopied,
+            };
+        }
+        finally {
+            _exodusInProgress = false;
+        }
+    }, 
+    // Tolerate a slow migration: a large fleet copy can take a while, so allow a
+    // generous stale window and a few retries while the winner holds the lock.
+    { stale: 600_000, retries: 30 });
+}
+/**
+ * Test-only accessor: whether an exodus migration is currently in flight. Used
+ * to assert the re-entrancy guard does not recurse.
+ *
+ * @internal
+ */
+export function _isExodusInProgress() {
+    return _exodusInProgress;
+}
+//# sourceMappingURL=on-open.js.map

package/dist/store/exodus/on-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-open.js","sourceRoot":"","sources":["../../../src/store/exodus/on-open.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,GAAG,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC;AAExC;;;;;;GAMG;AACH,IAAI,iBAAiB,GAAG,KAAK,CAAC;AAE9B;;;;GAIG;AACH,SAAS,eAAe;IACtB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC;IAClD,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,KAAgB;IACzC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,wBAAwB,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,QAAsB,EAAE,KAAa;IACzD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,8BAA8B,KAAK,GAAG,CAAC,CAAC,GAAG,EAE3D,CAAC;QACd,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,QAAsB,EAAE,KAAgB;IACnE,OAAO,YAAY,CAAC,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,2BAA2B,CAAC,QAAsB,EAAE,KAAgB;IAC3E,IAAI,UAAU,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC;QACH,UAAU,GACR,QAAQ;aACL,OAAO,CACN,gHAAgH,CACjH;aACA,GAAG,EACP,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,yDAAyD,CAAC,CAAC;QACrF,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QAC3C,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,QAAQ,CAAC,IAAI,CAAC,gBAAgB,KAAK,GAAG,CAAC,CAAC;YAC1C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,uDAAuD,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,gCAAgC;QAClC,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,6CAA6C,CAAC,CAAC;IAC3E,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,kBAAkB,CAAC,KAAgB;IAChD,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAChE,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAU,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,MAAM,MAAM,GACV,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;YACvF,MAAM,MAAM,GAAI,MAAM,CAAC,EAAiC,CAAC,OAAO,CAAC;YACjE,IAAI,MAAM,EAAE,CAAC;gBACX,2BAA2B,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CACN,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,EACtC,yDAAyD,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA6B;IAC9D,yEAAyE;IACzE,8EAA8E;IAC9E,+EAA+E;IAC/E,8EAA8E;IAC9E,8CAA8C;IAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAC5E,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAC7E,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,IAAI,CACN;YACE,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,KAAK,EAAE,CAAC,CAAC,WAAW;gBACpB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,MAAM,EAAE,CAAC,CAAC,WAAW;gBACrB,MAAM,EAAE,CAAC,CAAC,WAAW;gBACrB,KAAK,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW;aACrC,CAAC,CAAC;SACJ,EACD,mBAAmB,SAAS,CAAC,MAAM,iDAAiD;YAClF,wFAAwF;YACxF,iEAAiE,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,8BAA8B,CAAC,MAAM,KAAK,CAAC,CAAC;AACrF,CAAC;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAgB,EAChB,MAAc,EACd,QAAsB,EACtB,GAAuB;IAEvB,0EAA0E;IAC1E,IAAI,iBAAiB,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,eAAe,EAAE,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,iCAAiC,EAAE,CAAC;IAC3E,CAAC;IAED,gFAAgF;IAChF,6EAA6E;IAC7E,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IAClF,CAAC;IAED,2EAA2E;IAC3E,qEAAqE;IACrE,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAC7F,YAAY,CACb,CAAC;IAEF,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAElC,mEAAmE;IACnE,oEAAoE;IACpE,0EAA0E;IAC1E,4EAA4E;IAC5E,yEAAyE;IACzE,2EAA2E;IAC3E,mEAAmE;IACnE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC;IACzE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAClD,OAAO;YACL,OAAO,EAAE,SAAS;YAClB,MAAM,EAAE,aAAa,KAAK,+DAA+D;SAC1F,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,qEAAqE;IACrE,MAAM,QAAQ,GAAG,GAAG,MAAM,sBAAsB,CAAC;IAEjD,OAAO,QAAQ,CACb,QAAQ,EACR,KAAK,IAAiC,EAAE;QACtC,wEAAwE;QACxE,mEAAmE;QACnE,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YAC1C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,gDAAgD,EAAE,CAAC;QAC1F,CAAC;QAED,GAAG,CAAC,IAAI,CACN;YACE,KAAK;YACL,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAC3E,EACD,wFAAwF,CACzF,CAAC;QAEF,iBAAiB,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,4EAA4E;YAC5E,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAChE,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,mBAAmB,GAAG,EAAE,CAAC,CAC/C,CAAC;YAEF,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC;gBACtB,kEAAkE;gBAClE,uEAAuE;gBACvE,gDAAgD;gBAChD,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAC;gBAChC,uEAAuE;gBACvE,0EAA0E;gBAC1E,kBAAkB,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;gBAC7C,MAAM,MAAM,GAAG,qBAAqB,aAAa,CAAC,KAAK,IAAI,eAAe,8BAA8B,CAAC;gBACzG,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,EAAE,mBAAmB,MAAM,EAAE,CAAC,CAAC;gBAC9E,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;YACxC,CAAC;YAED,uEAAuE;YACvE,yEAAyE;YACzE,MAAM,YAAY,GAAG,eAAe,CAClC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,YAAY,EACjB,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,0BAA0B,GAAG,EAAE,CAAC,CAC/D,CAAC;YAEF,qEAAqE;YACrE,kEAAkE;YAClE,uEAAuE;YACvE,oCAAoC;YACpC,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;gBACrB,GAAG,CAAC,IAAI,CACN;oBACE,KAAK;oBACL,SAAS,EAAE,YAAY,CAAC,SAAS,CAAC,MAAM;oBACxC,cAAc,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM;iBACvE,EACD,kHAAkH,CACnH,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAAC;gBACtC,yEAAyE;gBACzE,mEAAmE;gBACnE,yEAAyE;gBACzE,mBAAmB;gBACnB,MAAM,kBAAkB,CAAC,KAAK,CAAC,CAAC;gBAChC,mEAAmE;gBACnE,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBACpC,qEAAqE;gBACrE,uEAAuE;gBACvE,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM;qBACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;qBAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC;gBACrE,MAAM,MAAM,GACV,2EAA2E;oBAC3E,oBAAoB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBAC5C,0BAA0B,YAAY,CAAC,8BAA8B,CAAC,MAAM,GAAG;oBAC/E,2CAA2C,YAAY,CAAC,+BAA+B,CAAC,MAAM,KAAK;oBACnG,GAAG,YAAY,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;gBACvC,GAAG,CAAC,KAAK,CACP;oBACE,KAAK;oBACL,aAAa,EAAE,QAAQ;oBACvB,sBAAsB,EAAE,YAAY,CAAC,8BAA8B,CAAC,MAAM;oBAC1E,uBAAuB,EAAE,YAAY,CAAC,+BAA+B,CAAC,MAAM;iBAC7E,EACD,iGAAiG,CAClG,CAAC;gBACF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;YACxC,CAAC;YAED,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM;iBACpC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;iBACzB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;YAEzC,GAAG,CAAC,IAAI,CACN,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,EAC1D,kFAAkF,CACnF,CAAC;YAEF,OAAO;gBACL,OAAO,EAAE,UAAU;gBACnB,MAAM,EAAE,YAAY,UAAU,gBAAgB,aAAa,CAAC,MAAM,CAAC,MAAM,0BAA0B;gBACnG,UAAU;aACX,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,iBAAiB,GAAG,KAAK,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,6EAA6E;IAC7E,2EAA2E;IAC3E,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAChC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,iBAAiB,CAAC;AAC3B,CAAC"}

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"}