@zq-silk/yui 0.6.0 → 0.6.2

package/dist/storage/upgrade/sqliteRecordMigrationTarget.js

@@ -0,0 +1,290 @@
+/**
+ * The SQLite-backed {@link MigrationTarget} for record-family migrations on a
+ * layout-7 Home (Issue 01 Phase 2).
+ *
+ * The layout 6 -> 7 target ({@link createSqliteMigrationTarget}) stages a
+ * fresh database from `state.json`. Once a Home is at layout 7 its
+ * authoritative store is `yui.db`; `state.json` may have been archived by the
+ * pseudo-layout-7 repair, so a record-only migration on such a Home cannot
+ * read its source from the document. This target closes that gap:
+ *
+ *  - Snapshot:  `readSource` reads `schema.json` and reconstructs the
+ *               state.json-shaped snapshot from `yui.db` via
+ *               {@link readStateFromSqlite} (raw payloads, so older record
+ *               versions survive with their original `schemaVersion`).
+ *  - Stage:     `writeFreshOutput` populates a sidecar `yui.db.staged` from
+ *               the (possibly transformed) snapshot; refuses to overwrite an
+ *               existing stage.
+ *  - Verify:    `validateCurrentState` independently re-reads `yui.db`,
+ *               re-derives the expected state through the registered
+ *               transforms, and compares per-family checksums against the
+ *               staged database.
+ *  - Commit:    `atomicSwitchWithBackup` swaps the sidecar into `yui.db` (with
+ *               a timestamped backup of the prior database) and advances
+ *               `schema.json`'s record-family versions in the same
+ *               coordination critical section. The layout version is
+ *               unchanged (this target never crosses a layout boundary).
+ *
+ * The source `yui.db` is retained read-only throughout: it is never
+ * overwritten, truncated, or deleted by the migration. This preserves the
+ * rollback path (restore the timestamped backup).
+ */
+import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextFileAtomically } from "../durableFile.js";
+import { STORAGE_SCHEMA_FILE } from "../storageSchema.js";
+import { planMigration } from "../migration/planner.js";
+import { AmbiguousSwitchError } from "../migration/index.js";
+import { describeActiveRuntime, homeRuntimeIsActive, inspectHomeRuntime, inspectSourceVersionState, inspectSnapshotVersionState } from "./homeMigrationTarget.js";
+import { writeSwitchProgress } from "./switchProgress.js";
+import { COMMITTED_DATABASE_FILENAME, STAGED_DATABASE_FILENAME, computeDbFamilyChecksums, computeStateFamilyChecksums, populateSqliteFromState, readStateFromSqlite } from "./sqliteStateMigration.js";
+/** Build the SQLite-backed record-migration target. */
+export function createSqliteRecordMigrationTarget(options) {
+    const home = options.home;
+    const latest = options.latest;
+    const registry = options.registry;
+    const now = options.now ?? (() => new Date());
+    const callerPid = options.callerPid ?? process.pid;
+    const promoteRename = options.renameImpl ?? renameSync;
+    const stagedDbPath = join(home, STAGED_DATABASE_FILENAME);
+    const committedDbPath = join(home, COMMITTED_DATABASE_FILENAME);
+    // The transformed schema manifest is cached during writeFreshOutput so the
+    // switch can advance schema.json without re-reading or re-deriving it.
+    let stagedSchemaManifest = null;
+    return {
+        stagedDbPath,
+        inspectVersions() {
+            const inspected = inspectSourceVersionState(home, latest);
+            if ("corruption" in inspected) {
+                throw new Error(inspected.corruption.detail);
+            }
+            return inspected.source;
+        },
+        detectLiveRuntime() {
+            const signals = inspectHomeRuntime(home, callerPid);
+            if (!homeRuntimeIsActive(signals))
+                return { active: false };
+            return { active: true, detail: describeActiveRuntime(signals) };
+        },
+        readSource() {
+            const manifestRaw = readFileSync(join(home, STORAGE_SCHEMA_FILE), "utf8");
+            const schemaManifest = parseJsonObject(manifestRaw, STORAGE_SCHEMA_FILE);
+            const state = readStateFromSqlite(home);
+            return Object.freeze({ schemaManifest, state });
+        },
+        writeFreshOutput(snapshot) {
+            if (existsSync(stagedDbPath)) {
+                throw new Error(`Refusing to overwrite an existing staged SQLite database: ${stagedDbPath}. ` +
+                    "Discard it and retry.");
+            }
+            // Cache the transformed manifest for the switch's schema.json advancement.
+            // The orchestrator applies the record transforms before calling us, but
+            // direct callers (tests, drills) may pass an untransformed snapshot. The
+            // record-family versions are re-derived from the latest map so the
+            // staged manifest always declares the post-migration versions.
+            const recordVersions = {};
+            for (const [kind, entry] of Object.entries(latest.record)) {
+                recordVersions[kind] = entry.version;
+            }
+            stagedSchemaManifest = {
+                ...snapshot.schemaManifest,
+                recordVersions,
+                updatedAt: now().toISOString()
+            };
+            populateSqliteFromState(home, snapshot.state ?? {}, STAGED_DATABASE_FILENAME);
+        },
+        rebuildDerivedState(effects) {
+            // The SQLite database is fully normalised by populateSqliteFromState;
+            // there is no separate derived index to rebuild. Echo the declared
+            // effects for the report, mirroring the layout 6 -> 7 target.
+            return { rebuiltEffects: [...effects] };
+        },
+        validateCurrentState() {
+            // Independently re-read yui.db from disk (not the in-memory snapshot
+            // used for staging) and re-derive the expected state by applying the
+            // registered transforms. This catches staging corruption, a torn read,
+            // or a concurrent writer that slipped past the quiesce gate.
+            const freshSnapshot = readSourceFresh();
+            const expectedState = deriveExpectedState(freshSnapshot);
+            if (expectedState !== null) {
+                verifyChecksums(expectedState);
+            }
+            const dbChecksums = computeDbFamilyChecksums(home, STAGED_DATABASE_FILENAME);
+            const familyCount = Object.keys(dbChecksums).length;
+            return {
+                checks: [
+                    {
+                        name: "SQLite staged-database checksum verification",
+                        outcome: "passed",
+                        detail: `verified ${familyCount} record families against an independent yui.db re-read`
+                    }
+                ]
+            };
+        },
+        atomicSwitchWithBackup() {
+            if (!existsSync(stagedDbPath)) {
+                throw new Error(`No staged SQLite database to promote: ${stagedDbPath}.`);
+            }
+            const stamp = now().toISOString().replace(/[:.]/g, "-");
+            let backupPath;
+            // Phase 1: back up the existing yui.db, then promote the sidecar.
+            try {
+                if (existsSync(committedDbPath)) {
+                    backupPath = join(home, `${COMMITTED_DATABASE_FILENAME}.backup-${stamp}`);
+                    if (existsSync(backupPath)) {
+                        throw new Error(`Refusing to overwrite an existing database backup: ${backupPath}.`);
+                    }
+                    renameSync(committedDbPath, backupPath);
+                }
+                promoteRename(stagedDbPath, committedDbPath);
+                // The staged connection may leave empty WAL/SHM sidecars behind
+                // even after a clean close; they are dead once promoted.
+                rmSync(`${stagedDbPath}-wal`, { force: true });
+                rmSync(`${stagedDbPath}-shm`, { force: true });
+            }
+            catch (error) {
+                // Pre-promotion failure: restore the original database if we moved it.
+                if (backupPath !== undefined && existsSync(backupPath)) {
+                    try {
+                        promoteRename(backupPath, committedDbPath);
+                    }
+                    catch {
+                        writeInterruptedMarker(home, backupPath, stagedDbPath, now);
+                        throw new AmbiguousSwitchError({
+                            homePath: home,
+                            backupPath,
+                            stagingPath: stagedDbPath,
+                            detail: `SQLite switch failed (${messageOf(error)}) and the automatic rollback also failed. ` +
+                                `The original database is at ${backupPath}; recover manually by renaming it to ${committedDbPath}.`
+                        });
+                    }
+                }
+                throw error;
+            }
+            // Phase 2: advance schema.json record-family versions in the same
+            // critical section. The layout version is unchanged.
+            try {
+                if (stagedSchemaManifest !== null) {
+                    writeTextFileAtomically(join(home, STORAGE_SCHEMA_FILE), `${JSON.stringify(stagedSchemaManifest, null, 2)}\n`);
+                }
+            }
+            catch (error) {
+                // The database is promoted but schema.json could not be advanced.
+                // Attempt to restore the original database; if that fails, the Home
+                // is ambiguous and must be recovered manually.
+                try {
+                    if (backupPath !== undefined && existsSync(backupPath)) {
+                        promoteRename(backupPath, committedDbPath);
+                    }
+                    else {
+                        rmSync(committedDbPath, { force: true });
+                    }
+                }
+                catch {
+                    writeInterruptedMarker(home, backupPath ?? committedDbPath, stagedDbPath, now);
+                    throw new AmbiguousSwitchError({
+                        homePath: home,
+                        backupPath: backupPath ?? committedDbPath,
+                        stagingPath: stagedDbPath,
+                        detail: `SQLite database was promoted but schema.json could not be advanced (${messageOf(error)}), ` +
+                            `and the automatic rollback also failed. The database is at ${committedDbPath}; ` +
+                            `recover by advancing schema.json recordVersions or restoring the backup.`
+                    });
+                }
+                throw error;
+            }
+            return {
+                status: "switched",
+                ...(backupPath === undefined ? {} : { backupPath }),
+                detail: `SQLite database promoted to ${committedDbPath} and schema.json record versions advanced.`
+            };
+        },
+        discardFreshOutput() {
+            rmSync(stagedDbPath, { force: true });
+            // Clean up WAL/SHM sidecars if the connection left them.
+            rmSync(`${stagedDbPath}-wal`, { force: true });
+            rmSync(`${stagedDbPath}-shm`, { force: true });
+            stagedSchemaManifest = null;
+        }
+    };
+    // -- helpers ---------------------------------------------------------------
+    function readSourceFresh() {
+        const manifestRaw = readFileSync(join(home, STORAGE_SCHEMA_FILE), "utf8");
+        const schemaManifest = parseJsonObject(manifestRaw, STORAGE_SCHEMA_FILE);
+        const state = readStateFromSqlite(home);
+        return Object.freeze({ schemaManifest, state });
+    }
+    /**
+     * Re-derive the expected post-migration state by reading the fresh snapshot,
+     * planning from its versions to `latest`, and applying every registered
+     * step transform. This mirrors the engine's apply phase but starts from an
+     * independent disk read.
+     */
+    function deriveExpectedState(snapshot) {
+        const inspected = inspectSnapshotVersionState(snapshot, latest);
+        if ("corruption" in inspected) {
+            throw new Error(inspected.corruption.detail);
+        }
+        const plan = planMigration(registry, inspected.source, latest);
+        if (plan.kind === "blocked") {
+            throw new Error(`SQLite record migration verification cannot derive expected state: ${plan.blocker.message}`);
+        }
+        if (plan.kind === "no-op")
+            return snapshot.state;
+        let current = snapshot;
+        for (const planned of plan.steps) {
+            planned.step.preconditions(current);
+            current = planned.step.transform(current);
+        }
+        return current.state;
+    }
+    function verifyChecksums(expectedState) {
+        const expected = computeStateFamilyChecksums(expectedState);
+        const actual = computeDbFamilyChecksums(home, STAGED_DATABASE_FILENAME);
+        const families = new Set([...Object.keys(expected), ...Object.keys(actual)]);
+        const mismatches = [];
+        for (const family of families) {
+            const e = expected[family];
+            const a = actual[family];
+            if (e === undefined || a === undefined || e.count !== a.count || e.hash !== a.hash) {
+                mismatches.push(`${family} (expected ${e === undefined ? "absent" : `${e.count}/${e.hash.slice(0, 12)}`}, ` +
+                    `found ${a === undefined ? "absent" : `${a.count}/${a.hash.slice(0, 12)}`})`);
+            }
+        }
+        if (mismatches.length > 0) {
+            throw new Error(`SQLite record migration checksum mismatch for ${mismatches.length} family/families: ${mismatches.join("; ")}`);
+        }
+    }
+}
+function parseJsonObject(raw, label) {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object.`);
+    }
+    return value;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Persist the durable `interrupted` switch-progress marker for an ambiguous
+ * SQLite switch (P1-4): the original database was moved to its timestamped
+ * backup and neither the promotion nor its rollback completed. The marker is
+ * the honest durable signal — a completion receipt is never written for a
+ * switch that did not commit. Best-effort: the backup and on-disk state still
+ * recover the Home even if the marker write fails.
+ */
+function writeInterruptedMarker(home, backupPath, stagingPath, now) {
+    try {
+        writeSwitchProgress(home, {
+            phase: "interrupted",
+            homePath: home,
+            backupPath,
+            stagingPath,
+            updatedAt: now().toISOString()
+        });
+    }
+    catch {
+        // Marker best-effort; the backup + on-disk state still recover the Home.
+    }
+}

package/dist/storage/upgrade/sqliteStateMigration.js

@@ -24,7 +24,11 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import Database from "better-sqlite3";
+import { mailboxTargetKey } from "../../coordination/workMailbox.js";
+import { managedWorkspaceKey } from "../../worktree/managedWorkspace.js";
 import { SqliteTaskStore } from "../sqliteStore.js";
+import { readStorageSchemaManifest } from "../storageSchema.js";
+import { CURRENT_STORED_TASK_SCHEMA_VERSION } from "../taskStore.js";
 /** The sidecar database filename used during staging. */
 export const STAGED_DATABASE_FILENAME = "yui.db.staged";
 /** The committed database filename. */
@@ -80,6 +84,19 @@ function asObjectMap(value) {
     }
     return result;
 }
+/** Read a persisted map whose values are opaque strings without silently
+ * dropping malformed entries during an offline migration. */
+function asStringMap(value, label) {
+    const record = asObject(value);
+    const result = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (typeof entry !== "string") {
+            throw new Error(`${label}.${key} must be a string.`);
+        }
+        result[key] = entry;
+    }
+    return result;
+}
 function asNullableObject(value) {
     if (value === null || value === undefined)
         return null;
@@ -100,6 +117,9 @@ function asStoredTask(value) {
         reviewRounds: asObjectMap(record.reviewRounds),
         changeSets: asObjectMap(record.changeSets),
         integrationAttempts: asObjectMap(record.integrationAttempts),
+        integrationQueue: asObjectMap(record.integrationQueue),
+        durableJobs: asObjectMap(record.durableJobs),
+        jobCallerKeyHashes: asStringMap(record.jobCallerKeyHashes, "jobCallerKeyHashes"),
         activeRuns: asObjectMap(record.activeRuns),
         messages: asObjectMap(record.messages),
         inputRequests: asObjectMap(record.inputRequests),
@@ -108,7 +128,9 @@ function asStoredTask(value) {
         events: asObjectMap(record.events),
         leaderFailure: asNullableObject(record.leaderFailure),
         operatorNotification: asNullableObject(record.operatorNotification),
-        idHighWaterMarks: asObject(record.idHighWaterMarks)
+        idHighWaterMarks: asObject(record.idHighWaterMarks),
+        capabilityGrants: asObjectMap(record.capabilityGrants),
+        releaseWorkflows: asObjectMap(record.releaseWorkflows)
     };
 }
 function tasksOf(state) {
@@ -195,6 +217,20 @@ export function populateSqliteFromState(home, state, databaseFilename) {
                 for (const attempt of Object.values(stored.integrationAttempts)) {
                     store.saveIntegrationAttempt(taskId, attempt);
                 }
+                for (const entry of Object.values(stored.integrationQueue)) {
+                    store.saveIntegrationQueueEntry(taskId, entry);
+                }
+                for (const job of Object.values(stored.durableJobs)) {
+                    store.saveDurableJob(taskId, job);
+                }
+                for (const [key, hash] of Object.entries(stored.jobCallerKeyHashes)) {
+                    const separator = key.indexOf("\0");
+                    if (separator <= 0 || separator === key.length - 1
+                        || key.indexOf("\0", separator + 1) !== -1) {
+                        throw new Error(`Job caller key hash identity is invalid: ${taskId}/${key}.`);
+                    }
+                    store.setJobCallerKeyHash(taskId, key.slice(0, separator), key.slice(separator + 1), hash);
+                }
                 // Active-run pointers: the document stores { schemaVersion, runId }
                 // keyed by pointer; the store derives the pointer from the Run.
                 for (const [pointer, value] of Object.entries(stored.activeRuns)) {
@@ -236,6 +272,13 @@ export function populateSqliteFromState(home, state, databaseFilename) {
                         store.migrationSeedIdSequence(taskId, kind, highWater);
                     }
                 }
+                // Capability grants and release workflows (task-15 record families).
+                for (const grant of Object.values(stored.capabilityGrants)) {
+                    store.saveCapabilityGrant(taskId, grant);
+                }
+                for (const workflow of Object.values(stored.releaseWorkflows)) {
+                    store.saveReleaseWorkflow(taskId, workflow);
+                }
             }
             // Work mailboxes.
             for (const mailbox of Object.values(asObjectMap(state.mailboxes))) {
@@ -302,6 +345,9 @@ export function computeStateFamilyChecksums(state) {
     const reviewRounds = [];
     const changeSets = [];
     const integrationAttempts = [];
+    const integrationQueue = [];
+    const durableJobs = [];
+    const jobCallerKeyHashes = [];
     const activeRunPointers = [];
     const messages = [];
     const inputRequests = [];
@@ -310,6 +356,8 @@ export function computeStateFamilyChecksums(state) {
     const events = [];
     const leaderFailures = [];
     const operatorNotifications = [];
+    const capabilityGrants = [];
+    const releaseWorkflows = [];
     for (const stored of Object.values(tasks)) {
         taskRecords.push(stored.task);
         if (stored.brief !== null)
@@ -322,6 +370,20 @@ export function computeStateFamilyChecksums(state) {
         reviewRounds.push(...Object.values(stored.reviewRounds));
         changeSets.push(...Object.values(stored.changeSets));
         integrationAttempts.push(...Object.values(stored.integrationAttempts));
+        integrationQueue.push(...Object.values(stored.integrationQueue));
+        durableJobs.push(...Object.values(stored.durableJobs));
+        for (const [key, hash] of Object.entries(stored.jobCallerKeyHashes)) {
+            const separator = key.indexOf("\0");
+            if (separator <= 0 || separator === key.length - 1
+                || key.indexOf("\0", separator + 1) !== -1) {
+                throw new Error(`Job caller key hash identity is invalid: ${stored.task.id}/${key}.`);
+            }
+            jobCallerKeyHashes.push({
+                taskId: stored.task.id,
+                key,
+                hash
+            });
+        }
         activeRunPointers.push(...Object.values(stored.activeRuns));
         messages.push(...Object.values(stored.messages));
         inputRequests.push(...Object.values(stored.inputRequests));
@@ -332,6 +394,8 @@ export function computeStateFamilyChecksums(state) {
             leaderFailures.push(stored.leaderFailure);
         if (stored.operatorNotification !== null)
             operatorNotifications.push(stored.operatorNotification);
+        capabilityGrants.push(...Object.values(stored.capabilityGrants));
+        releaseWorkflows.push(...Object.values(stored.releaseWorkflows));
     }
     checksums.task = hashRecords(taskRecords);
     checksums.taskBrief = hashRecords(briefs);
@@ -343,6 +407,9 @@ export function computeStateFamilyChecksums(state) {
     checksums.reviewRound = hashRecords(reviewRounds);
     checksums.changeSet = hashRecords(changeSets);
     checksums.integrationAttempt = hashRecords(integrationAttempts);
+    checksums.integrationQueue = hashRecords(integrationQueue);
+    checksums.durableJob = hashRecords(durableJobs);
+    checksums.jobCallerKeyHash = hashRecords(jobCallerKeyHashes);
     checksums.activeRunPointer = hashRecords(activeRunPointers);
     checksums.message = hashRecords(messages);
     checksums.inputRequest = hashRecords(inputRequests);
@@ -351,6 +418,8 @@ export function computeStateFamilyChecksums(state) {
     checksums.event = hashRecords(events);
     checksums.leaderFailure = hashRecords(leaderFailures);
     checksums.operatorNotification = hashRecords(operatorNotifications);
+    checksums.capabilityGrant = hashRecords(capabilityGrants);
+    checksums.releaseWorkflow = hashRecords(releaseWorkflows);
     checksums.workMailbox = hashRecords(Object.values(asObjectMap(state.mailboxes)));
     return checksums;
 }
@@ -359,7 +428,7 @@ function hashPayloadTable(db, sql) {
     return hashRecords(rows.map((row) => JSON.parse(row.payload)));
 }
 /** Reconstruct a WorkMailbox from the normalised mailboxes table columns. */
-function rowToMailbox(row) {
+export function rowToMailbox(row) {
     let target;
     switch (row.target_kind) {
         case "operator":
@@ -413,6 +482,14 @@ export function computeDbFamilyChecksums(home, databaseFilename) {
         checksums.reviewRound = hashPayloadTable(db, "SELECT payload FROM review_rounds");
         checksums.changeSet = hashPayloadTable(db, "SELECT payload FROM change_sets");
         checksums.integrationAttempt = hashPayloadTable(db, "SELECT payload FROM integration_attempts");
+        checksums.integrationQueue = hashPayloadTable(db, "SELECT payload FROM integration_queue");
+        checksums.durableJob = hashPayloadTable(db, "SELECT payload FROM durable_jobs");
+        const callerHashRows = db.prepare("SELECT task_id, role_name, agent_id, hash FROM job_caller_key_hashes").all();
+        checksums.jobCallerKeyHash = hashRecords(callerHashRows.map((row) => ({
+            taskId: row.task_id,
+            key: `${row.role_name}\0${row.agent_id}`,
+            hash: row.hash
+        })));
         checksums.activeRunPointer = hashPayloadTable(db, "SELECT payload FROM active_runs");
         checksums.message = hashPayloadTable(db, "SELECT payload FROM messages");
         checksums.inputRequest = hashPayloadTable(db, "SELECT payload FROM input_requests");
@@ -421,6 +498,8 @@ export function computeDbFamilyChecksums(home, databaseFilename) {
         checksums.event = hashPayloadTable(db, "SELECT payload FROM events");
         checksums.leaderFailure = hashPayloadTable(db, "SELECT payload FROM task_projections WHERE kind = 'leader-failure' AND payload IS NOT NULL");
         checksums.operatorNotification = hashPayloadTable(db, "SELECT payload FROM task_projections WHERE kind = 'operator-notification' AND payload IS NOT NULL");
+        checksums.capabilityGrant = hashPayloadTable(db, "SELECT payload FROM capability_grants");
+        checksums.releaseWorkflow = hashPayloadTable(db, "SELECT payload FROM release_workflows");
         // Mailboxes are reconstructed from typed columns (no payload column).
         const mailboxRows = db.prepare("SELECT target_kind, task_id, role_name, next_sequence, processing, pending FROM mailboxes ORDER BY target_key").all();
         checksums.workMailbox = hashRecords(mailboxRows.map(rowToMailbox));
@@ -455,3 +534,180 @@ export function verifySqliteChecksums(state, home, databaseFilename) {
         throw new Error(`SQLite migration checksum mismatch for ${mismatches.length} family/families: ${mismatches.join("; ")}`);
     }
 }
+// ---------------------------------------------------------------------------
+// SQLite -> Snapshot reconstruction (record-migration source, Issue 01 Phase 2)
+// ---------------------------------------------------------------------------
+/**
+ * Reconstruct the state.json-shaped snapshot from a committed SQLite database.
+ *
+ * This is the reverse of {@link populateSqliteFromState}: it reads every
+ * record family from `yui.db` and rebuilds the nested document shape the
+ * generic migration engine's record transforms operate on. Payloads are read
+ * RAW (`JSON.parse` without the strict current-version parsers) so a record
+ * family at an older persisted version survives the round-trip with its
+ * original `schemaVersion` intact — the strict parsers only understand the
+ * current version and would reject the very records the migration is meant to
+ * transform.
+ *
+ * The database is opened read-only; this function never writes.
+ */
+export function readStateFromSqlite(home) {
+    const dbPath = join(home, COMMITTED_DATABASE_FILENAME);
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const manifest = readStorageSchemaManifest(home);
+        const storedTaskVersion = typeof manifest.recordVersions?.storedTask === "number"
+            ? manifest.recordVersions.storedTask
+            : CURRENT_STORED_TASK_SCHEMA_VERSION;
+        // Home identity + revision continuity.
+        const meta = db.prepare("SELECT home_identity, revision FROM home_meta WHERE id = 1").get();
+        const state = {
+            // The state document's `schemaVersion` is the Yui aggregate version,
+            // sourced from the durable manifest (the version contract). The
+            // `home_meta.aggregate_version` column is the SQLite database's own
+            // schema version (SQLITE_AGGREGATE_VERSION), a different fact.
+            schemaVersion: manifest.aggregateSchemaVersion,
+            revision: meta.revision,
+            homeIdentity: JSON.parse(meta.home_identity),
+            configuredAgents: {},
+            projects: {},
+            agentProfiles: {},
+            globalRoles: {},
+            globalRoleSessionSets: {},
+            tasks: {},
+            mailboxes: {}
+        };
+        // Config singleton (absent on a fresh, never-configured Home).
+        const configRow = db.prepare("SELECT payload FROM config WHERE id = 1").get();
+        if (configRow !== undefined) {
+            state.config = JSON.parse(configRow.payload);
+        }
+        // Global record families.
+        loadGlobalPayloadMap(db, "configured_agents", state, "configuredAgents", (record) => record.id);
+        loadGlobalPayloadMap(db, "projects", state, "projects", (record) => record.id);
+        loadGlobalPayloadMap(db, "agent_profiles", state, "agentProfiles", (record) => record.id);
+        loadGlobalPayloadMap(db, "global_roles", state, "globalRoles", (record) => record.name);
+        loadGlobalPayloadMap(db, "global_role_session_sets", state, "globalRoleSessionSets", (record) => record.owner.roleName);
+        // Tasks: the StoredTask aggregate wrapper. The wrapper `schemaVersion` is
+        // not persisted in the database (records live in flat tables), so it is
+        // taken from the manifest's declared `storedTask` version — the version
+        // the database was created with — so the version scanner and the migration
+        // engine see a consistent source.
+        const tasks = state.tasks;
+        const taskRows = db.prepare("SELECT task_id, payload, brief FROM task_records").all();
+        for (const row of taskRows) {
+            tasks[row.task_id] = {
+                schemaVersion: storedTaskVersion,
+                task: JSON.parse(row.payload),
+                brief: row.brief === null ? null : JSON.parse(row.brief),
+                roles: {},
+                managedWorkspaces: {},
+                roleSessionSets: {},
+                workItems: {},
+                agentRuns: {},
+                reviewRounds: {},
+                changeSets: {},
+                integrationAttempts: {},
+                integrationQueue: {},
+                durableJobs: {},
+                jobCallerKeyHashes: {},
+                activeRuns: {},
+                messages: {},
+                inputRequests: {},
+                decisions: {},
+                milestones: {},
+                events: {},
+                leaderFailure: null,
+                operatorNotification: null,
+                idHighWaterMarks: {},
+                capabilityGrants: {},
+                releaseWorkflows: {}
+            };
+        }
+        // Per-task record families, keyed by their state.json map keys.
+        loadTaskPayloadMap(db, "task_roles", tasks, "roles", (record) => record.name);
+        loadTaskPayloadMap(db, "managed_workspaces", tasks, "managedWorkspaces", (record) => managedWorkspaceKey(record.owner));
+        loadTaskPayloadMap(db, "role_session_sets", tasks, "roleSessionSets", (record) => record.owner.roleName);
+        loadTaskPayloadMap(db, "work_items", tasks, "workItems", (record) => record.id);
+        loadTaskPayloadMap(db, "agent_runs", tasks, "agentRuns", (record) => record.id);
+        loadTaskPayloadMap(db, "review_rounds", tasks, "reviewRounds", (record) => record.id);
+        loadTaskPayloadMap(db, "change_sets", tasks, "changeSets", (record) => record.id);
+        loadTaskPayloadMap(db, "integration_attempts", tasks, "integrationAttempts", (record) => record.id);
+        loadTaskPayloadMap(db, "integration_queue", tasks, "integrationQueue", (record) => record.id);
+        loadTaskPayloadMap(db, "durable_jobs", tasks, "durableJobs", (record) => record.id);
+        loadTaskPayloadMap(db, "messages", tasks, "messages", (record) => record.id);
+        loadTaskPayloadMap(db, "input_requests", tasks, "inputRequests", (record) => record.id);
+        loadTaskPayloadMap(db, "decisions", tasks, "decisions", (record) => record.id);
+        loadTaskPayloadMap(db, "milestones", tasks, "milestones", (record) => record.id);
+        loadTaskPayloadMap(db, "events", tasks, "events", (record) => record.id);
+        loadTaskPayloadMap(db, "capability_grants", tasks, "capabilityGrants", (record) => record.id);
+        loadTaskPayloadMap(db, "release_workflows", tasks, "releaseWorkflows", (record) => record.id);
+        // Job caller key hashes: keyed by `${roleName}\0${agentId}`.
+        const callerHashRows = db.prepare("SELECT task_id, role_name, agent_id, hash FROM job_caller_key_hashes").all();
+        for (const row of callerHashRows) {
+            const stored = requireTaskAggregate(tasks, row.task_id, "jobCallerKeyHashes");
+            stored.jobCallerKeyHashes[`${row.role_name}\0${row.agent_id}`] = row.hash;
+        }
+        // Active-run pointers: keyed by pointer, value is the persisted payload.
+        const activeRunRows = db.prepare("SELECT task_id, pointer, payload FROM active_runs").all();
+        for (const row of activeRunRows) {
+            const stored = requireTaskAggregate(tasks, row.task_id, "activeRuns");
+            stored.activeRuns[row.pointer] = JSON.parse(row.payload);
+        }
+        // Leader failure / operator notification projections.
+        const projectionRows = db.prepare("SELECT task_id, kind, payload FROM task_projections WHERE payload IS NOT NULL").all();
+        for (const row of projectionRows) {
+            const stored = requireTaskAggregate(tasks, row.task_id, row.kind);
+            if (row.kind === "leader-failure") {
+                stored.leaderFailure = JSON.parse(row.payload);
+            }
+            else {
+                stored.operatorNotification = JSON.parse(row.payload);
+            }
+        }
+        // Per-task ID high-water marks.
+        const idSeqRows = db.prepare("SELECT task_id, kind, high_water FROM id_sequences").all();
+        for (const row of idSeqRows) {
+            const stored = requireTaskAggregate(tasks, row.task_id, "idHighWaterMarks");
+            stored.idHighWaterMarks[row.kind] = row.high_water;
+        }
+        // Work mailboxes: reconstructed from typed columns (no payload column).
+        const mailboxRows = db.prepare("SELECT target_kind, task_id, role_name, next_sequence, processing, pending FROM mailboxes ORDER BY target_key").all();
+        const mailboxes = state.mailboxes;
+        for (const row of mailboxRows) {
+            const mailbox = rowToMailbox(row);
+            mailboxes[mailboxTargetKey(mailbox.target)] = mailbox;
+        }
+        return state;
+    }
+    finally {
+        db.close();
+    }
+}
+/** Load a global (non-task-scoped) payload table into a keyed map on `state`. */
+function loadGlobalPayloadMap(db, table, state, stateKey, keyOf) {
+    const rows = db.prepare(`SELECT payload FROM ${table}`).all();
+    const target = state[stateKey];
+    for (const row of rows) {
+        const record = JSON.parse(row.payload);
+        target[keyOf(record)] = record;
+    }
+}
+/** Load a task-scoped payload table into the matching family map of each task. */
+function loadTaskPayloadMap(db, table, tasks, familyKey, keyOf) {
+    const rows = db.prepare(`SELECT task_id, payload FROM ${table}`).all();
+    for (const row of rows) {
+        const stored = requireTaskAggregate(tasks, row.task_id, table);
+        const family = stored[familyKey];
+        const record = JSON.parse(row.payload);
+        family[keyOf(record)] = record;
+    }
+}
+/** Resolve a task's StoredTask aggregate, or throw on an orphaned child row. */
+function requireTaskAggregate(tasks, taskId, context) {
+    const stored = tasks[taskId];
+    if (stored === undefined) {
+        throw new Error(`SQLite reconstruction found ${context} row for unknown task ${taskId}.`);
+    }
+    return stored;
+}