@deksden-com/dd-flow-cli 0.9.0-beta.103 → 0.9.0-beta.105

package/dist/storage/database.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
+import { channel } from "node:diagnostics_channel";
 import { createRequire } from "node:module";
 import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
 import { executeStoreSchema, readStoreWriterContract, registerStoreWriter } from "./writer-contract.js";
+import { assertImportAdmission } from "./import-guard.js";
+import { withStoreCleanup, rollbackStoreTransaction } from "./native-cleanup.js";
 const workContinuationStorageSql = `
   CREATE TABLE IF NOT EXISTS stage_work_memberships (
     project_id TEXT NOT NULL, run_id TEXT NOT NULL, work_id TEXT NOT NULL REFERENCES works(work_id),
@@ -17,9 +20,73 @@ const workContinuationStorageSql = `
     payload_json TEXT NOT NULL, work_id TEXT NOT NULL REFERENCES works(work_id), created_at TEXT NOT NULL
   );
 `;
+function closeAfterOpenFailure(db, error) {
+    return withStoreCleanup(() => { throw error; }, () => { if (db.isOpen)
+        db.close(); });
+}
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
 const resourceDatabases = new Map();
+const publicationScopes = [];
+/** Defer committed cross-store projections until the surrounding writer exits. */
+export function withDeferredPublications(operation) {
+    const pending = [];
+    publicationScopes.push(pending);
+    let value;
+    let primary;
+    let failed = false;
+    try {
+        value = operation();
+        if (value && typeof value.then === "function")
+            throw new AppError("write_transaction_async", "Deferred publication scope must be synchronous", 1);
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    publicationScopes.pop();
+    const parent = publicationScopes.at(-1);
+    if (parent)
+        parent.push(...pending);
+    else {
+        try {
+            executePublications(pending);
+        }
+        catch (publicationError) {
+            if (failed && primary instanceof AppError)
+                throw new AppError(primary.code, primary.message, primary.exitCode, { ...primary.details, effect: "partial", committed_publications: pending.length, publication_pending: true, publication_error: errorDetails(publicationError) });
+            if (failed)
+                throw new AppError("cross_store_failed", "Cross-store mutation failed and committed projections need reconciliation", 1, { effect: "partial", cause: errorDetails(primary), committed_publications: pending.length, publication_pending: true, publication_error: errorDetails(publicationError) });
+            throw publicationError;
+        }
+    }
+    if (failed && pending.length && primary instanceof AppError)
+        throw new AppError(primary.code, primary.message, primary.exitCode, { ...primary.details, effect: "partial", committed_publications: pending.length });
+    if (failed && pending.length)
+        throw new AppError("cross_store_failed", "Cross-store mutation failed after a committed inner write", 1, { effect: "partial", cause: errorDetails(primary), committed_publications: pending.length });
+    if (failed)
+        throw primary;
+    return value;
+}
+function executePublications(pending) {
+    let firstError;
+    let failed = false;
+    for (const operation of pending) {
+        try {
+            operation();
+        }
+        catch (error) {
+            if (!failed)
+                firstError = error;
+            failed = true;
+        }
+    }
+    if (failed) {
+        if (firstError instanceof AppError && firstError.details.effect === "committed")
+            throw firstError;
+        throw new AppError("publication_pending", "SQL committed but a required projection needs reconciliation", 1, { effect: "committed", publication_pending: true, cause: errorDetails(firstError) });
+    }
+}
 /** Invocation authority is prepared once with the runtime schema. Native
  * hooks must only verify this table; they never create it on the hot path. */
 export function ensureLifecycleInvocationStorage(db) {
@@ -32,6 +99,11 @@ export function ensureLifecycleInvocationStorage(db) {
     );
     CREATE INDEX IF NOT EXISTS idx_lifecycle_invocations_scope
       ON lifecycle_invocations(scope_json, fingerprint, created_at);
+    CREATE TABLE IF NOT EXISTS lifecycle_packet_assignments (
+      packet_sha256 TEXT NOT NULL,
+      invocation_id TEXT NOT NULL REFERENCES lifecycle_invocations(id),
+      PRIMARY KEY(packet_sha256, invocation_id)
+    );
   `);
 }
 /** RUN authority stays in its existing store; process leases stay in runtime.sqlite. */
@@ -174,6 +246,8 @@ export function ensureVnextWorkStorage(db) {
       prompt_path TEXT NOT NULL,
       result_path TEXT,
       start_receipt_json TEXT,
+      start_publication_status TEXT,
+      result_receipt_json TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
       completed_at TEXT,
@@ -230,6 +304,10 @@ export function ensureVnextWorkStorage(db) {
         const columns = db.all("PRAGMA table_info(work_sessions)");
         if (!columns.some((column) => column.name === "start_receipt_json"))
             db.execSchema("ALTER TABLE work_sessions ADD COLUMN start_receipt_json TEXT");
+        if (!columns.some((column) => column.name === "start_publication_status"))
+            db.execSchema("ALTER TABLE work_sessions ADD COLUMN start_publication_status TEXT");
+        if (!columns.some((column) => column.name === "result_receipt_json"))
+            db.execSchema("ALTER TABLE work_sessions ADD COLUMN result_receipt_json TEXT");
     });
 }
 /** Durable intent for a provider-root external Work.  It is deliberately
@@ -253,7 +331,9 @@ export function ensureWorkLaunchStorage(db) {
     CREATE INDEX IF NOT EXISTS idx_work_launches_status ON work_launches(status, updated_at DESC);
   `);
 }
-export function getDatabase(ddFlowHome, mode = "initialize") {
+export function getDatabase(ddFlowHome, mode = "initialize", importPermitId) {
+    if (mode !== "read_existing")
+        assertImportAdmission(ddFlowHome, importPermitId);
     const dbPath = path.join(ddFlowHome, "db.sqlite");
     const exists = fs.existsSync(dbPath);
     if (mode === "read_existing" && !exists) {
@@ -270,16 +350,14 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
             registerStoreWriter(db);
         }
         catch (error) {
-            db.close();
-            throw error;
+            return closeAfterOpenFailure(db, error);
         }
     }
     try {
         configureDatabase(db, mode);
     }
     catch (error) {
-        db.close();
-        throw error;
+        return closeAfterOpenFailure(db, error);
     }
     // Internal additive schema changes must be available to every write command.
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
@@ -300,8 +378,7 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
             }
         }
         catch (error) {
-            db.close();
-            throw error;
+            return closeAfterOpenFailure(db, error);
         }
     }
     if (mode === "read_existing")
@@ -316,7 +393,7 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
  * preparation error instead of an implicit migration race.
  */
 function assertHookStoreReady(db) {
-    const required = ["projects", "hook_events", "codex_session_bindings", "sessions", "flow_session_segments", "lifecycle_invocations"];
+    const required = ["projects", "hook_events", "codex_session_bindings", "sessions", "flow_session_segments", "lifecycle_invocations", "lifecycle_packet_assignments"];
     const missing = required.filter((table) => !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table));
     if (missing.length)
         throw new AppError("hook_storage_unprepared", "Managed store is not prepared for synchronous hook admission", 1, { missing_tables: missing, next_action: "Open the runtime with a normal dd-flow command and complete migration before starting the native Session." });
@@ -346,7 +423,7 @@ export function withResourceReadSnapshot(resourceHome, read) {
     if (!cached && !fs.existsSync(dbPath))
         return read(emptyReadOnlyDatabase(dbPath));
     const db = cached ?? new DatabaseSync(dbPath, { readOnly: true });
-    try {
+    const operation = () => {
         if (!cached)
             db.exec("PRAGMA busy_timeout = 4000; PRAGMA query_only = ON");
         // A second process can observe SQLite's file before the initializing
@@ -359,31 +436,22 @@ export function withResourceReadSnapshot(resourceHome, read) {
         const reader = cached
             ? { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all }
             : databaseFacade(dbPath, false, db);
-        // SAVEPOINT also composes with an existing owner's transaction. The
-        // callback sees its uncommitted state but never receives write capability.
-        db.exec("SAVEPOINT resource_read_snapshot");
-        try {
-            const result = read(reader);
-            db.exec("RELEASE resource_read_snapshot");
-            return result;
-        }
-        catch (error) {
-            db.exec("ROLLBACK TO resource_read_snapshot");
-            db.exec("RELEASE resource_read_snapshot");
-            throw error;
-        }
-    }
-    finally {
-        if (!cached)
-            db.close?.();
-    }
+        // The facade owns savepoint cleanup and poisons a connection when rollback
+        // fails; the callback only receives the read-only view.
+        return (cached ?? reader).readSnapshot(() => read(reader));
+    };
+    if (cached)
+        return operation();
+    const native = db;
+    return withStoreCleanup(operation, () => { if (native.isOpen)
+        native.close(); });
 }
 export function getResourceDatabase(resourceHome, mode = "initialize") {
     const dbPath = path.join(resourceHome, "runtime.sqlite");
     const cached = resourceDatabases.get(dbPath);
-    if (mode === "read_existing") {
+    if (mode === "read_existing" || mode === "read_isolated") {
         // Reuse a current transaction's view without exposing its write capability.
-        if (cached)
+        if (cached && mode === "read_existing")
             return { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all };
         if (!fs.existsSync(dbPath))
             return emptyReadOnlyDatabase(dbPath);
@@ -396,8 +464,7 @@ export function getResourceDatabase(resourceHome, mode = "initialize") {
             }
         }
         catch (error) {
-            db.close();
-            throw error;
+            return closeAfterOpenFailure(db, error);
         }
         return databaseFacade(dbPath, false, db);
     }
@@ -410,15 +477,13 @@ export function getResourceDatabase(resourceHome, mode = "initialize") {
         registerStoreWriter(db);
     }
     catch (error) {
-        db.close();
-        throw error;
+        return closeAfterOpenFailure(db, error);
     }
     try {
         configureDatabase(db, "initialize");
     }
     catch (error) {
-        db.close();
-        throw error;
+        return closeAfterOpenFailure(db, error);
     }
     db.exec("PRAGMA foreign_keys = ON");
     const fresh = !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
@@ -465,8 +530,7 @@ export function getResourceDatabase(resourceHome, mode = "initialize") {
   `, fresh);
     }
     catch (error) {
-        db.close();
-        throw error;
+        return closeAfterOpenFailure(db, error);
     }
     const database = databaseFacade(dbPath, true, db, () => {
         resourceDatabases.delete(dbPath);
@@ -483,6 +547,8 @@ function emptyReadOnlyDatabase(dbPath) {
         execSchema: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
         beginWriteTransaction: () => { throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath }); },
         writeTransaction: () => { throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath }); },
+        readSnapshot: (operation) => operation(),
+        afterCommit: () => { throw new AppError("read_only_storage", "Read-only access cannot publish absent dd-flow storage", 1, { path: dbPath }); },
         run: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
         get: () => undefined,
         all: () => []
@@ -491,11 +557,31 @@ function emptyReadOnlyDatabase(dbPath) {
 function databaseFacade(dbPath, writable, db, close = () => db.close?.()) {
     let reserved = false;
     let poisoned = false;
+    let closed = false;
+    const closeOnce = () => { if (closed || !db.isOpen) {
+        closed = true;
+        return;
+    } closed = true; close(); };
     let savepoint = 0;
-    const assertUsable = () => { if (poisoned)
-        throw new AppError("write_transaction_unresolved", "Transaction cleanup failed; reopen the connection before continuing", 1); };
+    let afterCommit = [];
+    let manualFrames = [];
+    let readDepth = 0;
+    const writerTiming = channel("dd-flow.sqlite.writer");
+    const publishCommitted = () => {
+        const pending = afterCommit;
+        afterCommit = [];
+        const scope = publicationScopes.at(-1);
+        if (scope)
+            scope.push(...pending);
+        else
+            executePublications(pending);
+    };
+    const assertUsable = () => { if (poisoned || closed || !db.isOpen)
+        throw new AppError("write_transaction_unresolved", "Transaction cleanup failed or the connection is closed; reopen the connection before continuing", 1); };
     const beginWriteTransaction = () => {
         assertUsable();
+        if (readDepth)
+            throw new AppError("read_snapshot_write", "Cannot reserve a writer inside a read snapshot", 1);
         if (!writable)
             throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath });
         db.exec("BEGIN IMMEDIATE");
@@ -507,20 +593,32 @@ function databaseFacade(dbPath, writable, db, close = () => db.close?.()) {
         }
         catch (cleanup) {
             poisoned = true;
+            let closeError;
+            try {
+                closeOnce();
+            }
+            catch (error) {
+                closeError = errorDetails(error);
+            }
+            const secondary = { transaction_cleanup_error: errorDetails(cleanup), ...(closeError ? { transaction_close_error: closeError } : {}) };
             if (original instanceof AppError)
-                throw new AppError(original.code, original.message, original.exitCode, { ...original.details, transaction_cleanup_error: errorDetails(cleanup) });
-            throw new AppError("write_transaction_failed", "Write transaction failed and SQLite cleanup also failed", 1, { cause: errorDetails(original), transaction_cleanup_error: errorDetails(cleanup) });
+                throw new AppError(original.code, original.message, original.exitCode, { ...original.details, ...secondary });
+            throw new AppError("write_transaction_failed", "Write transaction failed and SQLite cleanup also failed", 1, { cause: errorDetails(original), ...secondary });
         }
         throw original;
     };
-    const writeTransaction = (operation) => {
+    const writeTransaction = (operation, operationName = "writeTransaction") => {
         assertUsable();
+        if (readDepth)
+            throw new AppError("read_snapshot_write", "Cannot reserve a writer inside a read snapshot", 1);
         if (!writable)
             throw new AppError("read_only_storage", "Read-only access cannot start a write transaction", 1, { path: dbPath });
         if (db.isTransaction && !reserved)
             throw new AppError("write_transaction_unowned", "Cannot write inside an unowned transaction or read snapshot", 1);
         const nested = db.isTransaction;
+        const callbackLength = afterCommit.length;
         const marker = `dd_flow_write_${++savepoint}`;
+        const startedAt = performance.now();
         try {
             if (nested)
                 db.exec(`SAVEPOINT ${marker}`);
@@ -542,9 +640,17 @@ function databaseFacade(dbPath, writable, db, close = () => db.close?.()) {
                 db.exec(`RELEASE ${marker}`);
             else
                 db.exec("COMMIT");
+            phase = "committed";
+            if (!nested && writerTiming.hasSubscribers)
+                writerTiming.publish({ operation: operationName, wall_time_ms: performance.now() - startedAt, path: dbPath });
+            if (!nested)
+                publishCommitted();
             return value;
         }
         catch (error) {
+            if (phase === "committed")
+                throw error;
+            afterCommit.length = callbackLength;
             try {
                 return rollback(nested ? `ROLLBACK TO ${marker}; RELEASE ${marker}` : "ROLLBACK", error);
             }
@@ -555,28 +661,134 @@ function databaseFacade(dbPath, writable, db, close = () => db.close?.()) {
             }
         }
         finally {
-            if (!db.isTransaction)
+            if (closed || !db.isOpen || !db.isTransaction) {
                 reserved = false;
+                if (phase !== "committed") {
+                    afterCommit = [];
+                    manualFrames = [];
+                }
+            }
+        }
+    };
+    const readSnapshot = (operation) => {
+        assertUsable();
+        const nested = db.isTransaction;
+        const marker = `dd_flow_read_${++savepoint}`;
+        const callbackLength = afterCommit.length;
+        try {
+            db.exec(nested ? `SAVEPOINT ${marker}` : "BEGIN");
+        }
+        catch (error) {
+            throw new AppError("read_snapshot_failed", "Cannot start SQLite read snapshot", 1, { cause: errorDetails(error) });
+        }
+        readDepth += 1;
+        let phase = "body";
+        try {
+            const value = operation();
+            if (value && typeof value.then === "function") {
+                void Promise.resolve(value).catch(() => { });
+                throw new AppError("read_snapshot_async", "Read snapshot callback must be synchronous", 1);
+            }
+            phase = "commit";
+            db.exec(nested ? `RELEASE ${marker}` : "COMMIT");
+            phase = "committed";
+            return value;
+        }
+        catch (error) {
+            if (phase === "committed")
+                throw error;
+            afterCommit.length = callbackLength;
+            return rollback(nested ? `ROLLBACK TO ${marker}; RELEASE ${marker}` : "ROLLBACK", error);
+        }
+        finally {
+            readDepth -= 1;
+        }
+    };
+    const applyManualBoundary = (sql) => {
+        for (const statement of sql.split(";")) {
+            const save = /^\s*SAVEPOINT\s+([\w-]+)/i.exec(statement);
+            if (save) {
+                manualFrames.push({ name: save[1], length: afterCommit.length });
+                continue;
+            }
+            const rollbackTo = /^\s*ROLLBACK\s+TO(?:\s+SAVEPOINT)?\s+([\w-]+)/i.exec(statement);
+            if (rollbackTo) {
+                const frame = manualFrames.findLastIndex((item) => item.name === rollbackTo[1]);
+                if (frame >= 0) {
+                    afterCommit.length = manualFrames[frame].length;
+                    manualFrames.length = frame + 1;
+                }
+                continue;
+            }
+            const release = /^\s*RELEASE(?:\s+SAVEPOINT)?\s+([\w-]+)/i.exec(statement);
+            if (release) {
+                const frame = manualFrames.findLastIndex((item) => item.name === release[1]);
+                if (frame >= 0)
+                    manualFrames.length = frame;
+                continue;
+            }
+            if (/^\s*ROLLBACK\b/i.test(statement)) {
+                afterCommit = [];
+                manualFrames = [];
+                continue;
+            }
+            if (/^\s*COMMIT\b/i.test(statement)) {
+                manualFrames = [];
+                publishCommitted();
+            }
         }
     };
     return {
         path: dbPath,
         writable,
-        close,
-        exec: (sql) => { assertUsable(); try {
-            db.exec(sql);
-        }
-        finally {
-            if (!db.isTransaction)
-                reserved = false;
-        } },
+        close: closeOnce,
+        exec: (sql) => {
+            assertUsable();
+            if (readDepth)
+                throw new AppError("read_snapshot_write", "Cannot execute SQL inside a read snapshot", 1);
+            try {
+                db.exec(sql);
+                applyManualBoundary(sql);
+            }
+            catch (error) {
+                if (/^\s*ROLLBACK\b/i.test(sql)) {
+                    poisoned = true;
+                    try {
+                        closeOnce();
+                    }
+                    catch { /* Keep the primary SQLite failure. */ }
+                }
+                throw error;
+            }
+            finally {
+                if (closed || !db.isOpen || !db.isTransaction) {
+                    reserved = false;
+                    if (!/^\s*COMMIT\b/i.test(sql)) {
+                        afterCommit = [];
+                        manualFrames = [];
+                    }
+                }
+            }
+        },
         execSchema: (sql) => { assertUsable(); if (db.isTransaction && !reserved)
             throw new AppError("write_transaction_unowned", "Cannot change schema inside an unowned transaction", 1); executeStoreSchema(db, sql); },
         beginWriteTransaction,
         writeTransaction,
-        run: (sql, params = []) => { assertUsable(); return db.prepare(sql).run(...params); },
-        get: (sql, params = []) => db.prepare(sql).get(...params),
-        all: (sql, params = []) => db.prepare(sql).all(...params)
+        readSnapshot,
+        afterCommit: (operation) => { assertUsable(); if (readDepth)
+            throw new AppError("read_snapshot_write", "Cannot queue publication inside a read snapshot", 1); if (db.isTransaction)
+            afterCommit.push(operation);
+        else {
+            const scope = publicationScopes.at(-1);
+            if (scope)
+                scope.push(operation);
+            else
+                executePublications([operation]);
+        } },
+        run: (sql, params = []) => { assertUsable(); if (readDepth)
+            throw new AppError("read_snapshot_write", "Cannot write inside a read snapshot", 1); return db.prepare(sql).run(...params); },
+        get: (sql, params = []) => { assertUsable(); return db.prepare(sql).get(...params); },
+        all: (sql, params = []) => { assertUsable(); return db.prepare(sql).all(...params); }
     };
 }
 function errorDetails(error) {
@@ -640,6 +852,7 @@ function migrate(db) {
     CREATE TABLE IF NOT EXISTS plan_bindings (
       project_id TEXT NOT NULL,
       protocol_id TEXT NOT NULL,
+      plan_id TEXT,
       plan_revision INTEGER NOT NULL,
       plan_sha256 TEXT NOT NULL,
       plan_path TEXT NOT NULL,
@@ -1221,6 +1434,22 @@ function migrate(db) {
     ensureColumn(db, "usage", "source_mtime_ms", "ALTER TABLE usage ADD COLUMN source_mtime_ms INTEGER");
     db.prepare("UPDATE usage SET cache_read_input_tokens = cached_input_tokens WHERE cache_read_input_tokens IS NULL AND cached_input_tokens IS NOT NULL").run();
     ensureColumn(db, "runs", "run_home_path", "ALTER TABLE runs ADD COLUMN run_home_path TEXT");
+    ensureColumn(db, "plan_bindings", "plan_id", "ALTER TABLE plan_bindings ADD COLUMN plan_id TEXT");
+    // Historical RUN projections already retain the canonical identifier. Use
+    // those SQL bytes to backfill without opening plan files under the writer.
+    for (const row of db.prepare("SELECT project_id, protocol_id FROM plan_bindings WHERE plan_id IS NULL").all()) {
+        const runs = db.prepare("SELECT index_json FROM runs WHERE project_id = ? AND subject_type = 'protocol' AND subject_id = ? ORDER BY updated_at DESC").all(row.project_id, row.protocol_id);
+        for (const run of runs) {
+            try {
+                const planId = JSON.parse(run.index_json).plan_ref?.plan_id;
+                if (typeof planId !== "string" || !planId || planId === "unknown-plan")
+                    continue;
+                db.prepare("UPDATE plan_bindings SET plan_id = ? WHERE project_id = ? AND protocol_id = ? AND plan_id IS NULL").run(planId, row.project_id, row.protocol_id);
+                break;
+            }
+            catch { /* A malformed historical RUN cannot establish plan identity. */ }
+        }
+    }
     ensureColumn(db, "runs", "run_root", "ALTER TABLE runs ADD COLUMN run_root TEXT");
     db.prepare("UPDATE runs SET run_root = COALESCE(run_root, run_home_path, run_dir) WHERE run_root IS NULL OR run_root = ''").run();
     ensureColumn(db, "merge_requests", "accepted_tree", "ALTER TABLE merge_requests ADD COLUMN accepted_tree TEXT");
@@ -1237,6 +1466,8 @@ function migrate(db) {
     ensureColumn(db, "runs", "artifact_root_kind", "ALTER TABLE runs ADD COLUMN artifact_root_kind TEXT");
     ensureColumn(db, "works", "payload_json", "ALTER TABLE works ADD COLUMN payload_json TEXT");
     ensureColumn(db, "work_sessions", "start_receipt_json", "ALTER TABLE work_sessions ADD COLUMN start_receipt_json TEXT");
+    ensureColumn(db, "work_sessions", "start_publication_status", "ALTER TABLE work_sessions ADD COLUMN start_publication_status TEXT");
+    ensureColumn(db, "work_sessions", "result_receipt_json", "ALTER TABLE work_sessions ADD COLUMN result_receipt_json TEXT");
     ensureColumn(db, "check_receipts", "declaration_id", "ALTER TABLE check_receipts ADD COLUMN declaration_id TEXT NOT NULL DEFAULT 'CHK-LEGACY'");
     ensureColumn(db, "check_receipts", "workspace_fingerprint", "ALTER TABLE check_receipts ADD COLUMN workspace_fingerprint TEXT NOT NULL DEFAULT ''");
     ensureColumn(db, "check_receipts", "artifacts_json", "ALTER TABLE check_receipts ADD COLUMN artifacts_json TEXT NOT NULL DEFAULT '[]'");
@@ -1329,8 +1560,7 @@ function migrateSessionStorageKeys(db, dbPath) {
         db.exec("COMMIT");
     }
     catch (error) {
-        db.exec("ROLLBACK");
-        throw error;
+        return rollbackStoreTransaction(db, "ROLLBACK", error);
     }
 }
 function storageSessionKey(harness, native) {

package/dist/storage/foreign-key-transaction.js

@@ -0,0 +1,39 @@
+import { AppError } from "../shared/errors.js";
+/** Relocation changes related keys together; restore connection policy even
+ * when BEGIN or rollback fails, and never reuse a connection with unknown FK mode. */
+export function foreignKeyTransaction(db, operation) {
+    const foreignKeys = db.get("PRAGMA foreign_keys").foreign_keys;
+    let value, primary, failed = false, committed = false;
+    try {
+        db.exec("PRAGMA foreign_keys = OFF");
+        if (db.get("PRAGMA foreign_keys")?.foreign_keys !== 0)
+            throw new AppError("foreign_key_transaction_active", "Key relocation requires its own connection transaction", 1);
+        value = db.writeTransaction(() => { db.afterCommit(() => { committed = true; }); return operation(); });
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    try {
+        db.exec(`PRAGMA foreign_keys = ${foreignKeys ? "ON" : "OFF"}`);
+        if (db.get("PRAGMA foreign_keys")?.foreign_keys !== foreignKeys)
+            throw new Error("Foreign-key enforcement was not restored");
+    }
+    catch (restore) {
+        const details = { foreign_keys_restore_error: String(restore), effect: committed ? "committed" : "unknown" };
+        try {
+            db.close?.();
+        }
+        catch (close) {
+            details.connection_close_error = String(close);
+        }
+        if (primary instanceof AppError)
+            Object.assign(primary.details, details);
+        else
+            primary = new AppError("foreign_key_restoration_failed", primary instanceof Error ? primary.message : "Cannot restore foreign-key enforcement", 1, { ...details, ...(failed ? { cause: String(primary) } : {}) });
+        failed = true;
+    }
+    if (failed)
+        throw primary;
+    return value;
+}

package/dist/storage/immutable-input.js

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+/** Durable immutable candidate; only a later SQL receipt grants it authority. */
+export function publishImmutableInput(file, bytes, conflictCode) {
+    const expected = crypto.createHash("sha256").update(bytes).digest("hex");
+    const verify = () => {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") !== expected)
+            throw new AppError(conflictCode, "Immutable input differs from the accepted bytes", 1, { path: file, expected_sha256: expected });
+    };
+    const temporary = `${file}.tmp-${crypto.randomUUID()}`;
+    try {
+        fs.writeFileSync(temporary, bytes, { flag: "wx", mode: 0o600 });
+        const descriptor = fs.openSync(temporary, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        try {
+            fs.linkSync(temporary, file);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            verify();
+        }
+        const directory = fs.openSync(path.dirname(file), "r");
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    finally {
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch { /* Unreferenced staging garbage must not mask the accepted input or primary error. */ }
+    }
+}