@zq-silk/yui 0.5.3 → 0.6.1

package/dist/storage/upgrade/sqliteStateMigration.js

@@ -0,0 +1,713 @@
+/**
+ * state.json -> SQLite staged migration (task-21 §8, work-item-4).
+ *
+ * This module is the document-to-database population and verification seam for
+ * the layout 6 -> 7 offline migration. It is deliberately side-effect-light:
+ *
+ *  - `populateSqliteFromState` opens a {@link SqliteTaskStore} on the sidecar
+ *    `yui.db.staged` and bulk-loads every record family from the parsed
+ *    `state.json` document, preserving the Home identity, revision, and ID
+ *    high-water marks. The source document is never written.
+ *  - `computeStateFamilyChecksums` / `computeDbFamilyChecksums` compute a
+ *    per-family `{ count, hash }` over the canonical JSON of every record, so
+ *    the staged database can be verified against an independent re-read of
+ *    `state.json` (the Verify phase of §8.2).
+ *  - `verifySqliteMigration` compares the two checksum maps and throws on any
+ *    count or content mismatch, leaving the source untouched.
+ *
+ * The checksum is content-based: each record is canonicalised (sorted keys,
+ * stable array ordering) and hashed individually; the per-family hash is the
+ * sha256 of the sorted record hashes. This is order-independent (a map
+ * serialised in any key order produces the same checksum) and catches any
+ * dropped, duplicated, or mutated record.
+ */
+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. */
+export const COMMITTED_DATABASE_FILENAME = "yui.db";
+// ---------------------------------------------------------------------------
+// Canonical JSON and hashing
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic JSON serialisation: object keys are sorted recursively so that
+ * two semantically-equal objects serialise identically regardless of key
+ * insertion order. Arrays preserve their order.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+/**
+ * Compute a per-family checksum over a set of records. Each record is hashed
+ * individually (over its canonical JSON); the family hash is the sha256 of
+ * the sorted per-record hashes, making the result independent of record
+ * ordering.
+ */
+function hashRecords(records) {
+    const hashes = records
+        .map((record) => createHash("sha256").update(canonicalJson(record)).digest("hex"))
+        .sort();
+    const hash = createHash("sha256").update(hashes.join("\n")).digest("hex");
+    return { count: records.length, hash };
+}
+// ---------------------------------------------------------------------------
+// Document shape helpers
+// ---------------------------------------------------------------------------
+function asObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return value;
+}
+function asObjectMap(value) {
+    const record = asObject(value);
+    const result = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            result[key] = entry;
+        }
+    }
+    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;
+    if (typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function asStoredTask(value) {
+    const record = asObject(value);
+    return {
+        task: asObject(record.task),
+        brief: asNullableObject(record.brief),
+        roles: asObjectMap(record.roles),
+        managedWorkspaces: asObjectMap(record.managedWorkspaces),
+        roleSessionSets: asObjectMap(record.roleSessionSets),
+        workItems: asObjectMap(record.workItems),
+        agentRuns: asObjectMap(record.agentRuns),
+        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),
+        decisions: asObjectMap(record.decisions),
+        milestones: asObjectMap(record.milestones),
+        events: asObjectMap(record.events),
+        leaderFailure: asNullableObject(record.leaderFailure),
+        operatorNotification: asNullableObject(record.operatorNotification),
+        idHighWaterMarks: asObject(record.idHighWaterMarks),
+        capabilityGrants: asObjectMap(record.capabilityGrants),
+        releaseWorkflows: asObjectMap(record.releaseWorkflows)
+    };
+}
+function tasksOf(state) {
+    const result = {};
+    for (const [taskId, raw] of Object.entries(asObject(state.tasks))) {
+        result[taskId] = asStoredTask(raw);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Population (Snapshot -> Stage)
+// ---------------------------------------------------------------------------
+/**
+ * Populate a fresh SQLite database from the parsed `state.json` document.
+ *
+ * The database is opened with the `migration` option (fence bypass) because
+ * the staged load runs while the upgrade fence is active. Every record family
+ * is saved through the canonical {@link SqliteTaskStore} methods so the
+ * typed-column projections and payload contents match what a live store would
+ * produce. The Home identity, revision, and ID high-water marks are preserved
+ * so the opened store continues from the same counters.
+ *
+ * This function NEVER writes `state.json`; it only creates/populates the
+ * sidecar database file.
+ */
+export function populateSqliteFromState(home, state, databaseFilename) {
+    const store = new SqliteTaskStore(home, { databaseFilename, migration: true });
+    try {
+        store.transaction(() => {
+            // Home identity + revision continuity.
+            const identity = asNullableObject(state.homeIdentity);
+            const revision = typeof state.revision === "number" ? state.revision : 0;
+            if (identity !== null) {
+                store.migrationSetHomeMeta(identity, revision);
+            }
+            // Config singleton.
+            const config = asNullableObject(state.config);
+            if (config !== null)
+                store.saveConfig(config);
+            // Global record families.
+            for (const agent of Object.values(asObjectMap(state.configuredAgents))) {
+                store.saveConfiguredAgent(agent);
+            }
+            for (const project of Object.values(asObjectMap(state.projects))) {
+                store.saveProject(project);
+            }
+            for (const profile of Object.values(asObjectMap(state.agentProfiles))) {
+                store.saveAgentProfile(profile);
+            }
+            for (const role of Object.values(asObjectMap(state.globalRoles))) {
+                store.saveGlobalRole(role);
+            }
+            for (const sessions of Object.values(asObjectMap(state.globalRoleSessionSets))) {
+                store.saveGlobalRoleSessionSet(sessions);
+            }
+            // Tasks and their per-task families.
+            const tasks = tasksOf(state);
+            for (const [taskId, stored] of Object.entries(tasks)) {
+                store.saveTask(stored.task);
+                if (stored.brief !== null) {
+                    store.saveTaskBrief(taskId, stored.brief);
+                }
+                for (const role of Object.values(stored.roles)) {
+                    store.saveRole(taskId, role);
+                }
+                for (const workspace of Object.values(stored.managedWorkspaces)) {
+                    store.saveManagedWorkspace(workspace);
+                }
+                for (const sessions of Object.values(stored.roleSessionSets)) {
+                    store.saveRoleSessionSet(sessions);
+                }
+                for (const item of Object.values(stored.workItems)) {
+                    store.saveWorkItem(taskId, item);
+                }
+                for (const run of Object.values(stored.agentRuns)) {
+                    store.saveAgentRun(run);
+                }
+                for (const round of Object.values(stored.reviewRounds)) {
+                    store.saveReviewRound(taskId, round);
+                }
+                for (const changeSet of Object.values(stored.changeSets)) {
+                    store.saveChangeSet(taskId, changeSet);
+                }
+                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)) {
+                    const run = stored.agentRuns[value.runId];
+                    if (run === undefined) {
+                        throw new Error(`Active run pointer ${taskId}/${pointer} references missing agent run ${value.runId}.`);
+                    }
+                    if (pointer.startsWith("/execution-lane/")) {
+                        store.saveActiveExecutionLaneRun(run);
+                    }
+                    else {
+                        store.saveActiveAgentRun(run);
+                    }
+                }
+                for (const message of Object.values(stored.messages)) {
+                    store.saveMessage(taskId, message);
+                }
+                for (const request of Object.values(stored.inputRequests)) {
+                    store.saveInputRequest(taskId, request);
+                }
+                for (const decision of Object.values(stored.decisions)) {
+                    store.saveDecision(taskId, decision);
+                }
+                for (const milestone of Object.values(stored.milestones)) {
+                    store.saveMilestone(taskId, milestone);
+                }
+                for (const event of Object.values(stored.events)) {
+                    store.saveEvent(taskId, event);
+                }
+                if (stored.leaderFailure !== null) {
+                    store.saveLeaderFailure(stored.leaderFailure);
+                }
+                if (stored.operatorNotification !== null) {
+                    store.saveOperatorNotification(stored.operatorNotification);
+                }
+                // Per-task ID high-water marks.
+                for (const [kind, highWater] of Object.entries(stored.idHighWaterMarks)) {
+                    if (typeof highWater === "number" && Number.isFinite(highWater)) {
+                        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))) {
+                store.saveWorkMailbox(mailbox);
+            }
+            // Global ID high-water marks, derived from existing task/project ids.
+            seedGlobalSequences(store, state);
+        });
+    }
+    finally {
+        store.close();
+    }
+}
+/**
+ * Seed `global_sequences` from the numeric suffixes of existing task and
+ * project ids so the next allocated id never collides with a historical one.
+ * Ids that do not match `<kind>-<n>` are ignored (legacy formats).
+ */
+function seedGlobalSequences(store, state) {
+    const taskMax = maxIdSuffix(Object.keys(asObject(state.tasks)), "task");
+    const projectMax = maxIdSuffix(Object.keys(asObject(state.projects)), "project");
+    if (taskMax > 0)
+        store.migrationSeedGlobalSequence("task", taskMax);
+    if (projectMax > 0)
+        store.migrationSeedGlobalSequence("project", projectMax);
+}
+function maxIdSuffix(ids, prefix) {
+    let max = 0;
+    const pattern = new RegExp(`^${prefix}-(\\d+)$`, "u");
+    for (const id of ids) {
+        const match = pattern.exec(id);
+        if (match !== null) {
+            const value = Number.parseInt(match[1], 10);
+            if (Number.isSafeInteger(value))
+                max = Math.max(max, value);
+        }
+    }
+    return max;
+}
+// ---------------------------------------------------------------------------
+// State-side checksums (the source of truth)
+// ---------------------------------------------------------------------------
+/**
+ * Compute per-family checksums from the parsed `state.json` document. This is
+ * the expected checksum set; the staged database is verified against it.
+ */
+export function computeStateFamilyChecksums(state) {
+    const checksums = {};
+    checksums.config = hashRecords(asNullableObject(state.config) === null ? [] : [asObject(state.config)]);
+    checksums.configuredAgent = hashRecords(Object.values(asObjectMap(state.configuredAgents)));
+    checksums.project = hashRecords(Object.values(asObjectMap(state.projects)));
+    checksums.agentProfile = hashRecords(Object.values(asObjectMap(state.agentProfiles)));
+    checksums.globalRole = hashRecords(Object.values(asObjectMap(state.globalRoles)));
+    checksums.globalRoleSessionSet = hashRecords(Object.values(asObjectMap(state.globalRoleSessionSets)));
+    // Flatten the per-task families across all tasks.
+    const tasks = tasksOf(state);
+    const taskRecords = [];
+    const briefs = [];
+    const roles = [];
+    const workspaces = [];
+    const roleSessionSets = [];
+    const workItems = [];
+    const agentRuns = [];
+    const reviewRounds = [];
+    const changeSets = [];
+    const integrationAttempts = [];
+    const integrationQueue = [];
+    const durableJobs = [];
+    const jobCallerKeyHashes = [];
+    const activeRunPointers = [];
+    const messages = [];
+    const inputRequests = [];
+    const decisions = [];
+    const milestones = [];
+    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)
+            briefs.push(stored.brief);
+        roles.push(...Object.values(stored.roles));
+        workspaces.push(...Object.values(stored.managedWorkspaces));
+        roleSessionSets.push(...Object.values(stored.roleSessionSets));
+        workItems.push(...Object.values(stored.workItems));
+        agentRuns.push(...Object.values(stored.agentRuns));
+        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));
+        decisions.push(...Object.values(stored.decisions));
+        milestones.push(...Object.values(stored.milestones));
+        events.push(...Object.values(stored.events));
+        if (stored.leaderFailure !== null)
+            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);
+    checksums.taskRole = hashRecords(roles);
+    checksums.managedWorkspace = hashRecords(workspaces);
+    checksums.taskRoleSessionSet = hashRecords(roleSessionSets);
+    checksums.workItem = hashRecords(workItems);
+    checksums.agentRun = hashRecords(agentRuns);
+    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);
+    checksums.decision = hashRecords(decisions);
+    checksums.milestone = hashRecords(milestones);
+    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;
+}
+function hashPayloadTable(db, sql) {
+    const rows = db.prepare(sql).all();
+    return hashRecords(rows.map((row) => JSON.parse(row.payload)));
+}
+/** Reconstruct a WorkMailbox from the normalised mailboxes table columns. */
+export function rowToMailbox(row) {
+    let target;
+    switch (row.target_kind) {
+        case "operator":
+            target = { kind: "operator" };
+            break;
+        case "task":
+            target = { kind: "task", taskId: row.task_id };
+            break;
+        case "role":
+            target = { kind: "role", taskId: row.task_id, roleName: row.role_name };
+            break;
+        case "role-runtime":
+            target = { kind: "role-runtime", taskId: row.task_id, roleName: row.role_name };
+            break;
+        case "global-role-runtime":
+            target = { kind: "global-role-runtime", roleName: row.role_name };
+            break;
+        default:
+            target = { kind: row.target_kind };
+    }
+    return {
+        schemaVersion: 1,
+        target,
+        nextSequence: row.next_sequence,
+        processing: row.processing === null ? null : JSON.parse(row.processing),
+        pending: row.pending === null ? null : JSON.parse(row.pending)
+    };
+}
+/**
+ * Compute per-family checksums from the SQLite database. The database is
+ * opened read-only; this is the independent verification read.
+ */
+export function computeDbFamilyChecksums(home, databaseFilename) {
+    const dbPath = join(home, databaseFilename);
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const checksums = {};
+        checksums.config = hashPayloadTable(db, "SELECT payload FROM config");
+        checksums.configuredAgent = hashPayloadTable(db, "SELECT payload FROM configured_agents");
+        checksums.project = hashPayloadTable(db, "SELECT payload FROM projects");
+        checksums.agentProfile = hashPayloadTable(db, "SELECT payload FROM agent_profiles");
+        checksums.globalRole = hashPayloadTable(db, "SELECT payload FROM global_roles");
+        checksums.globalRoleSessionSet = hashPayloadTable(db, "SELECT payload FROM global_role_session_sets");
+        checksums.task = hashPayloadTable(db, "SELECT payload FROM task_records");
+        checksums.taskBrief = hashPayloadTable(db, "SELECT brief AS payload FROM task_records WHERE brief IS NOT NULL");
+        checksums.taskRole = hashPayloadTable(db, "SELECT payload FROM task_roles");
+        checksums.managedWorkspace = hashPayloadTable(db, "SELECT payload FROM managed_workspaces");
+        checksums.taskRoleSessionSet = hashPayloadTable(db, "SELECT payload FROM role_session_sets");
+        checksums.workItem = hashPayloadTable(db, "SELECT payload FROM work_items");
+        checksums.agentRun = hashPayloadTable(db, "SELECT payload FROM agent_runs");
+        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");
+        checksums.decision = hashPayloadTable(db, "SELECT payload FROM decisions");
+        checksums.milestone = hashPayloadTable(db, "SELECT payload FROM milestones");
+        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));
+        return checksums;
+    }
+    finally {
+        db.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Verification (Verify phase of §8.2)
+// ---------------------------------------------------------------------------
+/**
+ * Compare the per-family checksums of the source document against those of the
+ * staged database. Throws on any count or content mismatch, naming every
+ * divergent family. The source document is never modified.
+ */
+export function verifySqliteChecksums(state, home, databaseFilename) {
+    const expected = computeStateFamilyChecksums(state);
+    const actual = computeDbFamilyChecksums(home, databaseFilename);
+    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 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;
+}