@astrosheep/keiyaku 2.9.11 → 2.9.12

package/build/core/repository-ledger/current-state-store.js

@@ -1,13 +1,16 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
 import { runGitProcess } from "../../git/core.js";
+import { acquireSqliteProcessLifetimeLock } from "../sqlite-process-lifetime-lock.js";
 import { applyFoldEntry } from "./fold.js";
 import { createLifecycleEntrySchema, evidenceObjectId, repositoryDeliveryRef } from "./codec.js";
 export const REPOSITORY_CURRENT_STATE_VERSION = 3;
-export const REPOSITORY_CURRENT_STATE_FILE = "keiyaku-current-state.sqlite";
-const SNAPSHOT_WRITE_BUSY_MS = 5_000;
+export const REPOSITORY_CURRENT_STATE_PREFIX = "keiyaku-current-state-";
+export const REPOSITORY_CURRENT_STATE_SUFFIX = ".sqlite";
+const SNAPSHOT_READER_BUSY_MS = 5_000;
+const SNAPSHOT_WRITER_LOCK_FILE = "keiyaku-current-state-writer-coordination.sqlite";
 const SCHEMA = `
   CREATE TABLE snapshot_schema (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
@@ -126,13 +129,16 @@ function validateRepositoryReceipts(database, contracts, summaryOnly, includeTop
     if (includeTopology)
         assertReceipt(database, "topology", topologyDigest(database));
 }
-async function snapshotPath(cwd, signal) {
+function snapshotFileName(head) {
+    return `${REPOSITORY_CURRENT_STATE_PREFIX}${head ?? "empty"}${REPOSITORY_CURRENT_STATE_SUFFIX}`;
+}
+export async function repositoryCurrentStateSnapshotPath(cwd, head, signal) {
     // Addressing callers already pass the resolved primary worktree root. Reuse
     // that physical coordinate within this request instead of probing Git again.
     const localGitDirectory = path.join(cwd, ".git");
     try {
         if ((await fs.stat(localGitDirectory)).isDirectory()) {
-            return path.join(await fs.realpath(localGitDirectory), REPOSITORY_CURRENT_STATE_FILE);
+            return path.join(await fs.realpath(localGitDirectory), snapshotFileName(head));
         }
     }
     catch {
@@ -145,38 +151,163 @@ async function snapshotPath(cwd, signal) {
     if (result.status !== 0 || result.error || !path.isAbsolute(commonDir)) {
         throw new Error(`cannot resolve repository common directory: ${result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`}`);
     }
-    return path.join(commonDir, REPOSITORY_CURRENT_STATE_FILE);
+    return path.join(commonDir, snapshotFileName(head));
+}
+function classifySnapshotFailure(error) {
+    const code = error.code;
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    if (code === "ENOENT" || message.includes("no such file or directory"))
+        return "missing";
+    if (code === "ERR_SQLITE_BUSY" || code === "ERR_SQLITE_LOCKED" || message.includes("database is locked") || message.includes("database is busy"))
+        return "transient";
+    if (code === "ERR_SQLITE_CORRUPT" || code === "ERR_SQLITE_NOTADB" || message.includes("database disk image is malformed") || message.includes("file is not a database"))
+        return "corrupt";
+    return "validation-failure";
+}
+function isCantOpen(error) {
+    const code = error.code;
+    const message = error instanceof Error ? error.message.toLowerCase() : "";
+    return code === "ERR_SQLITE_CANTOPEN" || message.includes("unable to open database file");
+}
+async function snapshotExists(databasePath) {
+    try {
+        await fs.lstat(databasePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        return undefined;
+    }
 }
-function openValidated(databasePath) {
+async function openValidated(databasePath) {
+    const existedBeforeOpen = await snapshotExists(databasePath);
     let database;
     try {
-        database = new DatabaseSync(databasePath);
-        database.exec("PRAGMA query_only = ON");
+        database = new DatabaseSync(databasePath, { readOnly: true });
+        database.exec(`PRAGMA busy_timeout = ${SNAPSHOT_READER_BUSY_MS}; PRAGMA query_only = ON`);
         const rows = database.prepare("SELECT version FROM snapshot_schema WHERE singleton = 1").all();
         if (rows.length !== 1 || rows[0]?.version !== REPOSITORY_CURRENT_STATE_VERSION) {
             database.close();
-            return null;
+            return { kind: "validation-failure" };
         }
-        return database;
+        return { kind: "opened", database };
     }
-    catch {
+    catch (error) {
         try {
             database.close();
         }
-        catch { /* discarded below */ }
-        return null;
+        catch { /* open did not yield a usable connection */ }
+        if (isCantOpen(error)) {
+            const existsAfterFailure = await snapshotExists(databasePath);
+            if (existedBeforeOpen === false || existsAfterFailure === false)
+                return { kind: "missing", error };
+        }
+        return { kind: classifySnapshotFailure(error), error };
     }
 }
-async function discard(databasePath) {
-    await Promise.all(["", "-wal", "-shm"].map(async (suffix) => {
+async function readSnapshot(databasePath, read) {
+    const opened = await openValidated(databasePath);
+    if (opened.kind !== "opened")
+        return opened;
+    try {
+        return { kind: "read", value: read(opened.database) };
+    }
+    catch (error) {
+        return { kind: classifySnapshotFailure(error), error };
+    }
+    finally {
         try {
-            await fs.unlink(`${databasePath}${suffix}`);
+            opened.database.close();
         }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
+        catch { /* validation failure already has its outcome */ }
+    }
+}
+export function currentStateWriterCoordination(databasePath) {
+    const lockPath = path.join(path.dirname(databasePath), SNAPSHOT_WRITER_LOCK_FILE);
+    return {
+        path: lockPath,
+        async acquire(signal) {
+            const lease = await acquireSqliteProcessLifetimeLock({ path: lockPath, signal });
+            return { release: () => lease.close() };
+        },
+    };
+}
+async function withSnapshotWriter(databasePath, signal, operation) {
+    const lock = await currentStateWriterCoordination(databasePath).acquire(signal);
+    try {
+        return await operation();
+    }
+    finally {
+        lock.release();
+    }
+}
+function temporarySnapshotPath(databasePath) {
+    return `${databasePath}.${process.pid}.${randomUUID()}.tmp`;
+}
+async function discardTemporarySnapshot(databasePath) {
+    await fs.unlink(databasePath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+}
+/** Writers alone publish or retire cache bytes; readers have no filesystem mutation path. */
+async function publishImmutableSnapshot(buildPath, databasePath) {
+    if (await snapshotExists(databasePath))
+        return false;
+    await fs.rename(buildPath, databasePath);
+    return true;
+}
+/**
+ * A filename becomes published only after its complete signed contents validate.
+ * This runs under writer coordination; readers merely report an unusable cache.
+ */
+async function preparePublicationTarget(databasePath, expectedHead) {
+    const snapshot = await readSnapshot(databasePath, (database) => {
+        const pin = metadata(database);
+        if (!pin || pin.head !== expectedHead)
+            throw new Error("snapshot pin does not match its immutable filename");
+        validatePinReceipt(database, pin);
+        const rows = database.prepare(`
+      SELECT contract, status, current_json AS currentJson, fold_json AS foldJson, diagnostics_json AS diagnosticsJson
+      FROM snapshot_contracts ORDER BY contract
+    `).all();
+        const repository = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_repository WHERE singleton = 1").get();
+        if (!repository)
+            throw new Error("snapshot repository row is missing");
+        validateRepositoryReceipts(database, rows.map((row) => row.contract), false, true);
+        parseDiagnostics(repository.diagnosticsJson);
+        for (const row of rows) {
+            parseDiagnostics(row.diagnosticsJson, row.contract);
+            validateContractConsistency(database, row, pin);
         }
-    }));
+    });
+    if (snapshot.kind === "read")
+        return "published";
+    if (snapshot.kind === "missing")
+        return "missing";
+    if (snapshot.kind === "transient")
+        return "transient";
+    await fs.unlink(databasePath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+    return "missing";
+}
+async function garbageCollectSnapshots(databasePath) {
+    const directory = path.dirname(databasePath);
+    const retained = path.basename(databasePath);
+    let entries;
+    try {
+        entries = await fs.readdir(directory);
+    }
+    catch {
+        return;
+    }
+    const cacheFile = /^keiyaku-current-state-(?:[0-9a-f]{40}|[0-9a-f]{64}|empty)\.sqlite(?:\..+\.tmp)?$/;
+    await Promise.all(entries
+        .filter((entry) => entry !== retained && cacheFile.test(entry))
+        .map((entry) => fs.unlink(path.join(directory, entry)).catch(() => undefined)));
 }
 function parseJson(text) {
     return JSON.parse(text);
@@ -345,13 +476,8 @@ function atPin(model, head) {
     return model.observedLedgerHead === head ? model : { ...model, observedLedgerHead: head };
 }
 export async function readPinnedCurrentContract(cwd, observedHead, contract, signal) {
-    const databasePath = await snapshotPath(cwd, signal);
-    const database = openValidated(databasePath);
-    if (!database) {
-        await discard(databasePath);
-        return null;
-    }
-    try {
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, signal);
+    const snapshot = await readSnapshot(databasePath, (database) => {
         const pin = metadata(database);
         if (!pin || pin.head !== observedHead)
             return null;
@@ -371,53 +497,36 @@ export async function readPinnedCurrentContract(cwd, observedHead, contract, sig
         return unattributed.length > 0
             ? { status: "indeterminate", contract, diagnostics: unattributed }
             : { status: "absent", contract, diagnostics: [] };
-    }
-    catch {
-        database.close();
-        await discard(databasePath);
-        return null;
-    }
-    finally {
-        try {
-            database.close();
-        }
-        catch { /* corruption path already discarded */ }
-    }
+    });
+    return snapshot.kind === "read" ? snapshot.value : null;
 }
-export async function readRepositoryCurrentStatePin(cwd, signal) {
-    const databasePath = await snapshotPath(cwd, signal);
-    const database = openValidated(databasePath);
-    if (!database) {
-        await discard(databasePath);
-        return undefined;
-    }
-    try {
+export async function readRepositoryCurrentStatePin(cwd, observedHead, signal) {
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, signal);
+    const snapshot = await readSnapshot(databasePath, (database) => {
         const pin = metadata(database);
         if (!pin)
             return undefined;
         validatePinReceipt(database, pin);
         return pin.head;
-    }
-    catch {
-        database.close();
-        await discard(databasePath);
-        return undefined;
-    }
-    finally {
-        try {
-            database.close();
-        }
-        catch { /* corruption path already discarded */ }
-    }
+    });
+    return snapshot.kind === "read" ? snapshot.value : undefined;
+}
+/**
+ * The first commit parent is the only inexpensive candidate for a linear
+ * incremental predecessor. It is not a current pointer: the caller still
+ * validates the cache addressed by that exact OID before using it.
+ */
+export async function readRepositoryCurrentStatePredecessor(cwd, observedHead, signal) {
+    const result = await runGitProcess(cwd, ["show", "-s", "--format=%P", observedHead], { signal });
+    if (result.error?.name === "AbortError")
+        throw result.error;
+    if (result.status !== 0 || result.error)
+        return null;
+    return result.stdout.trim().split(/\s+/)[0] || null;
 }
 export async function readRepositoryCurrentStateNodeIds(cwd, observedHead, signal) {
-    const databasePath = await snapshotPath(cwd, signal);
-    const database = openValidated(databasePath);
-    if (!database) {
-        await discard(databasePath);
-        return null;
-    }
-    try {
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, signal);
+    const snapshot = await readSnapshot(databasePath, (database) => {
         const pin = metadata(database);
         if (!pin || pin.head !== observedHead)
             return null;
@@ -442,28 +551,13 @@ export async function readRepositoryCurrentStateNodeIds(cwd, observedHead, signa
             }
         }
         return { ledgerParents, entryIntroductions };
-    }
-    catch {
-        database.close();
-        await discard(databasePath);
-        return null;
-    }
-    finally {
-        try {
-            database.close();
-        }
-        catch { /* corruption path already discarded */ }
-    }
+    });
+    return snapshot.kind === "read" ? snapshot.value : null;
 }
 /** Rehydrate the accepted typed topology for publication admission without Git history traversal. */
 export async function readPinnedAcceptedTraversal(cwd, observedHead, signal) {
-    const databasePath = await snapshotPath(cwd, signal);
-    const database = openValidated(databasePath);
-    if (!database) {
-        await discard(databasePath);
-        return null;
-    }
-    try {
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, signal);
+    const snapshot = await readSnapshot(databasePath, (database) => {
         const pin = metadata(database);
         if (!pin || pin.head !== observedHead || !pin.objectFormat || !pin.emptyTree)
             return null;
@@ -520,27 +614,12 @@ export async function readPinnedAcceptedTraversal(cwd, observedHead, signal) {
         };
         visit(observedHead);
         return { head: observedHead, coordinates: { objectFormat: pin.objectFormat, objectIdLength: pin.objectFormat === "sha1" ? 40 : 64, emptyTree: pin.emptyTree }, nodes, order, diseases: [] };
-    }
-    catch {
-        database.close();
-        await discard(databasePath);
-        return null;
-    }
-    finally {
-        try {
-            database.close();
-        }
-        catch { /* corruption path already discarded */ }
-    }
+    });
+    return snapshot.kind === "read" ? snapshot.value : null;
 }
 export async function readPinnedRepositoryLifecycle(cwd, observedHead, signal, options = {}) {
-    const databasePath = await snapshotPath(cwd, signal);
-    const database = openValidated(databasePath);
-    if (!database) {
-        await discard(databasePath);
-        return null;
-    }
-    try {
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, signal);
+    const snapshot = await readSnapshot(databasePath, (database) => {
         const pin = metadata(database);
         if (!pin || pin.head !== observedHead)
             return null;
@@ -575,279 +654,318 @@ export async function readPinnedRepositoryLifecycle(cwd, observedHead, signal, o
                     : database.prepare("SELECT node_json AS nodeJson FROM snapshot_topology ORDER BY rowid").all().map((row) => parseJson(row.nodeJson)),
             },
         };
-    }
-    catch {
-        database.close();
-        await discard(databasePath);
-        return null;
-    }
-    finally {
-        try {
-            database.close();
-        }
-        catch { /* corruption path already discarded */ }
-    }
+    });
+    return snapshot.kind === "read" ? snapshot.value : null;
 }
 export async function publishRepositoryCurrentState(cwd, read, options) {
-    const databasePath = await snapshotPath(cwd, options.signal);
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, read.observedLedgerHead, options.signal);
     await fs.mkdir(path.dirname(databasePath), { recursive: true });
     if (await options.confirmHead() !== read.observedLedgerHead)
         return false;
-    let database;
-    try {
-        database = new DatabaseSync(databasePath);
-        database.exec(`PRAGMA busy_timeout = ${SNAPSHOT_WRITE_BUSY_MS}; PRAGMA synchronous = FULL; PRAGMA journal_mode = DELETE; BEGIN IMMEDIATE`);
-        database.exec("DROP TABLE IF EXISTS snapshot_integrity; DROP TABLE IF EXISTS snapshot_resources; DROP TABLE IF EXISTS snapshot_topology; DROP TABLE IF EXISTS snapshot_summaries; DROP TABLE IF EXISTS snapshot_history; DROP TABLE IF EXISTS snapshot_contracts; DROP TABLE IF EXISTS snapshot_repository; DROP TABLE IF EXISTS snapshot_pin; DROP TABLE IF EXISTS snapshot_schema");
-        database.exec(SCHEMA);
-        database.prepare("INSERT INTO snapshot_schema(singleton, version) VALUES (1, ?)").run(REPOSITORY_CURRENT_STATE_VERSION);
-        database.prepare("INSERT INTO snapshot_pin(singleton, ledger_head, object_format, empty_tree) VALUES (1, ?, ?, ?)").run(read.observedLedgerHead, read.objectFormat, read.emptyTree);
-        const insert = database.prepare("INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json) VALUES (?, ?, ?, ?, ?)");
-        const insertHistory = database.prepare("INSERT INTO snapshot_history(contract, position, object_id, entry_json) VALUES (?, ?, ?, ?)");
-        const insertSummary = database.prepare("INSERT INTO snapshot_summaries(contract, history_json) VALUES (?, ?)");
-        const isolated = new Set(read.isolatedContracts);
-        const models = new Map(read.contracts.map((model) => [model.contract, model]));
-        for (const contract of new Set([...models.keys(), ...isolated])) {
-            const model = models.get(contract) ?? null;
-            const diagnostics = read.diagnostics.filter((disease) => disease.contract === contract);
-            const status = isolated.has(contract) ? "isolated" : diagnostics.length > 0 ? "diseased" : "healthy";
-            const folded = options.fold.contracts.get(contract) ?? null;
-            const current = model === null ? null : Object.fromEntries(Object.entries(model).filter(([key]) => key !== "history"));
-            insert.run(contract, status, current === null ? null : JSON.stringify(current), folded === null ? null : JSON.stringify(folded), JSON.stringify(diagnostics));
-            model?.history.forEach((row, position) => insertHistory.run(contract, position, row.objectId, JSON.stringify(row.entry)));
-            if (model)
-                insertSummary.run(contract, JSON.stringify(summaryHistory(model.history)));
-        }
-        database.prepare("INSERT INTO snapshot_repository(singleton, diagnostics_json) VALUES (1, ?)").run(JSON.stringify(read.diagnostics.filter((disease) => disease.contract === undefined)));
-        const insertTopology = database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)");
-        for (const node of read.topology.nodes)
-            insertTopology.run(node.objectId, JSON.stringify(node));
-        const insertResource = database.prepare("INSERT INTO snapshot_resources(kind, resource_key, contract) VALUES (?, ?, ?)");
-        for (const model of read.contracts) {
-            if (model.resources.worktree?.state === "held")
-                insertResource.run("worktree", model.resources.worktree.place, model.contract);
-            for (const task of model.resources.tasks)
-                if (task.state === "held")
-                    insertResource.run("task", task.taskId, model.contract);
-        }
-        writeIntegrityReceipts(database);
-        options.beforeCommit?.();
-        database.exec("COMMIT");
-        database.close();
-        return true;
-    }
-    catch (error) {
-        try {
-            database.exec("ROLLBACK");
-        }
-        catch { /* database may not have opened */ }
+    return withSnapshotWriter(databasePath, options.signal, async () => {
+        if (await options.confirmHead() !== read.observedLedgerHead)
+            return false;
+        const existing = await preparePublicationTarget(databasePath, read.observedLedgerHead);
+        if (existing === "published")
+            return true;
+        if (existing === "transient")
+            return false;
+        const buildPath = temporarySnapshotPath(databasePath);
+        let database;
         try {
+            await fs.unlink(buildPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+            database = new DatabaseSync(buildPath);
+            database.exec("PRAGMA synchronous = FULL; PRAGMA journal_mode = DELETE; BEGIN IMMEDIATE");
+            database.exec("DROP TABLE IF EXISTS snapshot_integrity; DROP TABLE IF EXISTS snapshot_resources; DROP TABLE IF EXISTS snapshot_topology; DROP TABLE IF EXISTS snapshot_summaries; DROP TABLE IF EXISTS snapshot_history; DROP TABLE IF EXISTS snapshot_contracts; DROP TABLE IF EXISTS snapshot_repository; DROP TABLE IF EXISTS snapshot_pin; DROP TABLE IF EXISTS snapshot_schema");
+            database.exec(SCHEMA);
+            database.prepare("INSERT INTO snapshot_schema(singleton, version) VALUES (1, ?)").run(REPOSITORY_CURRENT_STATE_VERSION);
+            database.prepare("INSERT INTO snapshot_pin(singleton, ledger_head, object_format, empty_tree) VALUES (1, ?, ?, ?)").run(read.observedLedgerHead, read.objectFormat, read.emptyTree);
+            const insert = database.prepare("INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json) VALUES (?, ?, ?, ?, ?)");
+            const insertHistory = database.prepare("INSERT INTO snapshot_history(contract, position, object_id, entry_json) VALUES (?, ?, ?, ?)");
+            const insertSummary = database.prepare("INSERT INTO snapshot_summaries(contract, history_json) VALUES (?, ?)");
+            const isolated = new Set(read.isolatedContracts);
+            const models = new Map(read.contracts.map((model) => [model.contract, model]));
+            for (const contract of new Set([...models.keys(), ...isolated])) {
+                const model = models.get(contract) ?? null;
+                const diagnostics = read.diagnostics.filter((disease) => disease.contract === contract);
+                const status = isolated.has(contract) ? "isolated" : diagnostics.length > 0 ? "diseased" : "healthy";
+                const folded = options.fold.contracts.get(contract) ?? null;
+                const current = model === null ? null : Object.fromEntries(Object.entries(model).filter(([key]) => key !== "history"));
+                insert.run(contract, status, current === null ? null : JSON.stringify(current), folded === null ? null : JSON.stringify(folded), JSON.stringify(diagnostics));
+                model?.history.forEach((row, position) => insertHistory.run(contract, position, row.objectId, JSON.stringify(row.entry)));
+                if (model)
+                    insertSummary.run(contract, JSON.stringify(summaryHistory(model.history)));
+            }
+            database.prepare("INSERT INTO snapshot_repository(singleton, diagnostics_json) VALUES (1, ?)").run(JSON.stringify(read.diagnostics.filter((disease) => disease.contract === undefined)));
+            const insertTopology = database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)");
+            for (const node of read.topology.nodes)
+                insertTopology.run(node.objectId, JSON.stringify(node));
+            const insertResource = database.prepare("INSERT INTO snapshot_resources(kind, resource_key, contract) VALUES (?, ?, ?)");
+            for (const model of read.contracts) {
+                if (model.resources.worktree?.state === "held")
+                    insertResource.run("worktree", model.resources.worktree.place, model.contract);
+                for (const task of model.resources.tasks)
+                    if (task.state === "held")
+                        insertResource.run("task", task.taskId, model.contract);
+            }
+            writeIntegrityReceipts(database);
+            await options.beforeCommit?.();
+            database.exec("COMMIT");
             database.close();
+            // No reader can be holding this new name. An existing same-head file is
+            // convergence, never a target for replacement.
+            await publishImmutableSnapshot(buildPath, databasePath);
+            await garbageCollectSnapshots(databasePath);
+            return true;
         }
-        catch { /* database may not have opened */ }
-        throw error;
-    }
+        catch (error) {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch { /* database may not have opened */ }
+            try {
+                database.close();
+            }
+            catch { /* database may not have opened */ }
+            await discardTemporarySnapshot(buildPath);
+            throw error;
+        }
+    });
 }
 export async function advanceRepositoryCurrentState(cwd, pinnedHead, observedHead, segment, options) {
-    const databasePath = await snapshotPath(cwd, options.signal);
+    const pinnedDatabasePath = await repositoryCurrentStateSnapshotPath(cwd, pinnedHead, options.signal);
+    const databasePath = await repositoryCurrentStateSnapshotPath(cwd, observedHead, options.signal);
     if (await options.confirmHead() !== observedHead)
         return false;
-    const database = openValidated(databasePath);
-    if (!database)
-        return false;
-    try {
-        database.exec(`PRAGMA query_only = OFF; PRAGMA busy_timeout = ${SNAPSHOT_WRITE_BUSY_MS}; PRAGMA synchronous = FULL; BEGIN IMMEDIATE`);
-        const pin = metadata(database);
-        if (!pin || pin.head !== pinnedHead) {
-            database.exec("ROLLBACK");
+    return withSnapshotWriter(databasePath, options.signal, async () => {
+        if (await options.confirmHead() !== observedHead)
             return false;
-        }
-        validatePinReceipt(database, pin);
-        assertReceipt(database, "topology", topologyDigest(database));
-        assertReceipt(database, "resources", resourcesDigest(database));
-        for (const contract of new Set(segment.transactions.map((transaction) => transaction.entries[0]?.entry.contract).filter((contract) => contract !== undefined))) {
-            if (database.prepare("SELECT 1 FROM snapshot_contracts WHERE contract = ?").get(contract))
-                validateContractReceipt(database, contract, false);
-        }
-        const acceptedTopology = new Set(database.prepare("SELECT object_id AS objectId FROM snapshot_topology").all().map((row) => row.objectId));
-        const pendingJoins = new Map(segment.joins.map((join) => [join.objectId, join]));
-        const promoteReadyJoins = () => {
-            let promoted;
-            do {
-                promoted = false;
-                for (const join of pendingJoins.values()) {
-                    if (!join.parents.every((parent) => acceptedTopology.has(parent)))
-                        continue;
-                    database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(join.objectId, JSON.stringify({
-                        objectId: join.objectId,
-                        type: "join",
-                        ledgerParents: join.parents,
-                    }));
-                    acceptedTopology.add(join.objectId);
-                    pendingJoins.delete(join.objectId);
-                    promoted = true;
-                }
-            } while (promoted);
-        };
-        for (const transaction of segment.transactions) {
-            promoteReadyJoins();
-            if ((transaction.predecessor !== null && !acceptedTopology.has(transaction.predecessor)) || transaction.entries.length === 0) {
+        const existing = await preparePublicationTarget(databasePath, observedHead);
+        if (existing === "published")
+            return true;
+        if (existing === "transient")
+            return false;
+        const buildPath = temporarySnapshotPath(databasePath);
+        let database;
+        try {
+            await fs.copyFile(pinnedDatabasePath, buildPath);
+            database = new DatabaseSync(buildPath);
+            database.exec("PRAGMA synchronous = FULL; BEGIN IMMEDIATE");
+            const versions = database.prepare("SELECT version FROM snapshot_schema WHERE singleton = 1").all();
+            if (versions.length !== 1 || versions[0]?.version !== REPOSITORY_CURRENT_STATE_VERSION) {
                 database.exec("ROLLBACK");
+                database.close();
                 return false;
             }
-            if (transaction.entries.some((entry) => database.prepare("SELECT 1 FROM snapshot_history WHERE object_id = ?").get(entry.objectId) !== undefined)) {
+        }
+        catch {
+            try {
+                database.close();
+            }
+            catch { /* replacement recovery owns unusable bytes */ }
+            return false;
+        }
+        try {
+            const pin = metadata(database);
+            if (!pin || pin.head !== pinnedHead) {
                 database.exec("ROLLBACK");
                 return false;
             }
-            const contract = transaction.entries[0].entry.contract;
-            const row = database.prepare("SELECT status, current_json AS currentJson, fold_json AS foldJson, diagnostics_json AS diagnosticsJson FROM snapshot_contracts WHERE contract = ?").get(contract);
-            let state = row?.foldJson ? parseJson(row.foldJson) : undefined;
-            const priorModel = row?.currentJson ? currentModel(database, contract, row.currentJson) : null;
-            const first = transaction.entries[0];
-            if (first.entry.kind === "bind" && (state || row)) {
-                const diagnostics = [...(row ? parseJson(row.diagnosticsJson) : []), {
-                        objectId: first.objectId,
-                        code: "same-contract-divergence",
-                        contract,
-                        detail: "incremental bind diverges from an already admitted contract",
-                    }];
-                database.prepare("UPDATE snapshot_contracts SET status = 'isolated', current_json = NULL, fold_json = NULL, diagnostics_json = ? WHERE contract = ?").run(JSON.stringify(diagnostics), contract);
+            validatePinReceipt(database, pin);
+            assertReceipt(database, "topology", topologyDigest(database));
+            assertReceipt(database, "resources", resourcesDigest(database));
+            for (const contract of new Set(segment.transactions.map((transaction) => transaction.entries[0]?.entry.contract).filter((contract) => contract !== undefined))) {
+                if (database.prepare("SELECT 1 FROM snapshot_contracts WHERE contract = ?").get(contract))
+                    validateContractReceipt(database, contract, false);
             }
-            else {
-                if (first.entry.kind !== "bind" && (!state || first.causalParent !== state.entryObjectIds.at(-1))) {
+            const acceptedTopology = new Set(database.prepare("SELECT object_id AS objectId FROM snapshot_topology").all().map((row) => row.objectId));
+            const pendingJoins = new Map(segment.joins.map((join) => [join.objectId, join]));
+            const promoteReadyJoins = () => {
+                let promoted;
+                do {
+                    promoted = false;
+                    for (const join of pendingJoins.values()) {
+                        if (!join.parents.every((parent) => acceptedTopology.has(parent)))
+                            continue;
+                        database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(join.objectId, JSON.stringify({
+                            objectId: join.objectId,
+                            type: "join",
+                            ledgerParents: join.parents,
+                        }));
+                        acceptedTopology.add(join.objectId);
+                        pendingJoins.delete(join.objectId);
+                        promoted = true;
+                    }
+                } while (promoted);
+            };
+            for (const transaction of segment.transactions) {
+                promoteReadyJoins();
+                if ((transaction.predecessor !== null && !acceptedTopology.has(transaction.predecessor)) || transaction.entries.length === 0) {
                     database.exec("ROLLBACK");
                     return false;
                 }
-                let staged = state === undefined ? undefined : structuredClone(state);
-                let disease;
-                const basePosition = staged?.entryObjectIds.length ?? 0;
-                for (let index = 0; index < transaction.entries.length; index += 1) {
-                    const entry = transaction.entries[index];
-                    const applied = applyFoldEntry(staged, { objectId: entry.objectId, entry: entry.entry, position: basePosition + index });
-                    staged = applied.state;
-                    if (applied.disease) {
-                        disease = { ...applied.disease, transactionObjectId: transaction.objectId };
-                        break;
-                    }
+                if (transaction.entries.some((entry) => database.prepare("SELECT 1 FROM snapshot_history WHERE object_id = ?").get(entry.objectId) !== undefined)) {
+                    database.exec("ROLLBACK");
+                    return false;
                 }
-                if (disease || !staged) {
-                    const diagnostics = [...(row ? parseJson(row.diagnosticsJson) : []), ...(disease ? [disease] : [])];
-                    if (row)
-                        database.prepare("UPDATE snapshot_contracts SET status = 'diseased', diagnostics_json = ? WHERE contract = ?").run(JSON.stringify(diagnostics), contract);
-                    else
-                        database.prepare("INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json) VALUES (?, 'isolated', NULL, NULL, ?)").run(contract, JSON.stringify(diagnostics));
+                const contract = transaction.entries[0].entry.contract;
+                const row = database.prepare("SELECT status, current_json AS currentJson, fold_json AS foldJson, diagnostics_json AS diagnosticsJson FROM snapshot_contracts WHERE contract = ?").get(contract);
+                let state = row?.foldJson ? parseJson(row.foldJson) : undefined;
+                const priorModel = row?.currentJson ? currentModel(database, contract, row.currentJson) : null;
+                const first = transaction.entries[0];
+                if (first.entry.kind === "bind" && (state || row)) {
+                    const diagnostics = [...(row ? parseJson(row.diagnosticsJson) : []), {
+                            objectId: first.objectId,
+                            code: "same-contract-divergence",
+                            contract,
+                            detail: "incremental bind diverges from an already admitted contract",
+                        }];
+                    database.prepare("UPDATE snapshot_contracts SET status = 'isolated', current_json = NULL, fold_json = NULL, diagnostics_json = ? WHERE contract = ?").run(JSON.stringify(diagnostics), contract);
                 }
                 else {
-                    if (first.entry.kind === "bind" && (first.entry.data.after?.length ?? 0) > 0) {
-                        const unavailable = first.entry.data.after.filter((dependency) => {
-                            const prerequisite = database.prepare("SELECT status, fold_json AS foldJson FROM snapshot_contracts WHERE contract = ?").get(dependency);
-                            if (!prerequisite || prerequisite.status !== "healthy" || prerequisite.foldJson === null)
-                                return true;
-                            return parseJson(prerequisite.foldJson).terminalObjectId === null;
-                        });
-                        if (unavailable.length > 0) {
-                            const diagnostic = {
-                                objectId: first.objectId,
-                                code: "causal-prerequisite",
-                                contract,
-                                detail: `after prerequisites are not admitted terminal contracts: ${unavailable.join(", ")}`,
-                            };
-                            database.prepare(`
+                    if (first.entry.kind !== "bind" && (!state || first.causalParent !== state.entryObjectIds.at(-1))) {
+                        database.exec("ROLLBACK");
+                        return false;
+                    }
+                    let staged = state === undefined ? undefined : structuredClone(state);
+                    let disease;
+                    const basePosition = staged?.entryObjectIds.length ?? 0;
+                    for (let index = 0; index < transaction.entries.length; index += 1) {
+                        const entry = transaction.entries[index];
+                        const applied = applyFoldEntry(staged, { objectId: entry.objectId, entry: entry.entry, position: basePosition + index });
+                        staged = applied.state;
+                        if (applied.disease) {
+                            disease = { ...applied.disease, transactionObjectId: transaction.objectId };
+                            break;
+                        }
+                    }
+                    if (disease || !staged) {
+                        const diagnostics = [...(row ? parseJson(row.diagnosticsJson) : []), ...(disease ? [disease] : [])];
+                        if (row)
+                            database.prepare("UPDATE snapshot_contracts SET status = 'diseased', diagnostics_json = ? WHERE contract = ?").run(JSON.stringify(diagnostics), contract);
+                        else
+                            database.prepare("INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json) VALUES (?, 'isolated', NULL, NULL, ?)").run(contract, JSON.stringify(diagnostics));
+                    }
+                    else {
+                        if (first.entry.kind === "bind" && (first.entry.data.after?.length ?? 0) > 0) {
+                            const unavailable = first.entry.data.after.filter((dependency) => {
+                                const prerequisite = database.prepare("SELECT status, fold_json AS foldJson FROM snapshot_contracts WHERE contract = ?").get(dependency);
+                                if (!prerequisite || prerequisite.status !== "healthy" || prerequisite.foldJson === null)
+                                    return true;
+                                return parseJson(prerequisite.foldJson).terminalObjectId === null;
+                            });
+                            if (unavailable.length > 0) {
+                                const diagnostic = {
+                                    objectId: first.objectId,
+                                    code: "causal-prerequisite",
+                                    contract,
+                                    detail: `after prerequisites are not admitted terminal contracts: ${unavailable.join(", ")}`,
+                                };
+                                database.prepare(`
                 INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json)
                 VALUES (?, 'isolated', NULL, NULL, ?)
                 ON CONFLICT(contract) DO UPDATE SET status = 'isolated', current_json = NULL, fold_json = NULL, diagnostics_json = excluded.diagnostics_json
               `).run(contract, JSON.stringify([diagnostic]));
-                            acceptedTopology.add(transaction.objectId);
-                            database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(transaction.objectId, JSON.stringify({
-                                objectId: transaction.objectId,
-                                type: "transaction",
-                                ledgerParents: transaction.predecessor === null ? [] : [transaction.predecessor],
-                                verb: transaction.transaction.verb,
-                                contract,
-                                entryObjectIds: transaction.entries.map((entry) => entry.objectId),
-                                finalEntryObjectId: transaction.entries.at(-1).objectId,
-                            }));
-                            continue;
+                                acceptedTopology.add(transaction.objectId);
+                                database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(transaction.objectId, JSON.stringify({
+                                    objectId: transaction.objectId,
+                                    type: "transaction",
+                                    ledgerParents: transaction.predecessor === null ? [] : [transaction.predecessor],
+                                    verb: transaction.transaction.verb,
+                                    contract,
+                                    entryObjectIds: transaction.entries.map((entry) => entry.objectId),
+                                    finalEntryObjectId: transaction.entries.at(-1).objectId,
+                                }));
+                                continue;
+                            }
                         }
-                    }
-                    const history = [...(priorModel?.history ?? []), ...transaction.entries.map((entry) => ({ objectId: entry.objectId, entry: entry.entry }))];
-                    const model = await options.materialize(staged, history);
-                    database.prepare(`
+                        const history = [...(priorModel?.history ?? []), ...transaction.entries.map((entry) => ({ objectId: entry.objectId, entry: entry.entry }))];
+                        const model = await options.materialize(staged, history);
+                        database.prepare(`
             INSERT INTO snapshot_contracts(contract, status, current_json, fold_json, diagnostics_json)
             VALUES (?, 'healthy', ?, ?, '[]')
             ON CONFLICT(contract) DO UPDATE SET status = 'healthy', current_json = excluded.current_json, fold_json = excluded.fold_json, diagnostics_json = '[]'
           `).run(contract, JSON.stringify(Object.fromEntries(Object.entries(model).filter(([key]) => key !== "history"))), JSON.stringify(staged));
-                    database.prepare("DELETE FROM snapshot_history WHERE contract = ?").run(contract);
-                    const insertHistory = database.prepare("INSERT INTO snapshot_history(contract, position, object_id, entry_json) VALUES (?, ?, ?, ?)");
-                    model.history.forEach((historyRow, position) => insertHistory.run(contract, position, historyRow.objectId, JSON.stringify(historyRow.entry)));
-                    database.prepare("INSERT INTO snapshot_summaries(contract, history_json) VALUES (?, ?) ON CONFLICT(contract) DO UPDATE SET history_json = excluded.history_json").run(contract, JSON.stringify(summaryHistory(model.history)));
-                    database.prepare("DELETE FROM snapshot_resources WHERE contract = ?").run(contract);
-                    const insertResource = database.prepare("INSERT INTO snapshot_resources(kind, resource_key, contract) VALUES (?, ?, ?)");
-                    if (model.resources.worktree?.state === "held")
-                        insertResource.run("worktree", model.resources.worktree.place, contract);
-                    for (const task of model.resources.tasks)
-                        if (task.state === "held")
-                            insertResource.run("task", task.taskId, contract);
-                    const collisions = [
-                        ...(model.resources.worktree?.state === "held" ? [{ kind: "worktree", key: model.resources.worktree.place }] : []),
-                        ...model.resources.tasks.filter((task) => task.state === "held").map((task) => ({ kind: "task", key: task.taskId })),
-                    ];
-                    for (const resource of collisions) {
-                        const owners = database.prepare("SELECT contract FROM snapshot_resources WHERE kind = ? AND resource_key = ?").all(resource.kind, resource.key);
-                        if (owners.length < 2)
-                            continue;
-                        for (const owner of owners) {
-                            const ownerRow = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_contracts WHERE contract = ?").get(owner.contract);
-                            const diagnostic = {
-                                objectId: first.objectId,
-                                code: resource.kind === "worktree" ? "worktree-place-collision" : "task-ownership-collision",
-                                contract: owner.contract,
-                                detail: `${resource.kind} ${resource.key} is held by ${owners.map((candidate) => candidate.contract).sort().join(", ")}`,
-                            };
-                            database.prepare("UPDATE snapshot_contracts SET status = 'isolated', current_json = NULL, fold_json = NULL, diagnostics_json = ? WHERE contract = ?").run(JSON.stringify([...parseJson(ownerRow.diagnosticsJson), diagnostic]), owner.contract);
+                        database.prepare("DELETE FROM snapshot_history WHERE contract = ?").run(contract);
+                        const insertHistory = database.prepare("INSERT INTO snapshot_history(contract, position, object_id, entry_json) VALUES (?, ?, ?, ?)");
+                        model.history.forEach((historyRow, position) => insertHistory.run(contract, position, historyRow.objectId, JSON.stringify(historyRow.entry)));
+                        database.prepare("INSERT INTO snapshot_summaries(contract, history_json) VALUES (?, ?) ON CONFLICT(contract) DO UPDATE SET history_json = excluded.history_json").run(contract, JSON.stringify(summaryHistory(model.history)));
+                        database.prepare("DELETE FROM snapshot_resources WHERE contract = ?").run(contract);
+                        const insertResource = database.prepare("INSERT INTO snapshot_resources(kind, resource_key, contract) VALUES (?, ?, ?)");
+                        if (model.resources.worktree?.state === "held")
+                            insertResource.run("worktree", model.resources.worktree.place, contract);
+                        for (const task of model.resources.tasks)
+                            if (task.state === "held")
+                                insertResource.run("task", task.taskId, contract);
+                        const collisions = [
+                            ...(model.resources.worktree?.state === "held" ? [{ kind: "worktree", key: model.resources.worktree.place }] : []),
+                            ...model.resources.tasks.filter((task) => task.state === "held").map((task) => ({ kind: "task", key: task.taskId })),
+                        ];
+                        for (const resource of collisions) {
+                            const owners = database.prepare("SELECT contract FROM snapshot_resources WHERE kind = ? AND resource_key = ?").all(resource.kind, resource.key);
+                            if (owners.length < 2)
+                                continue;
+                            for (const owner of owners) {
+                                const ownerRow = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_contracts WHERE contract = ?").get(owner.contract);
+                                const diagnostic = {
+                                    objectId: first.objectId,
+                                    code: resource.kind === "worktree" ? "worktree-place-collision" : "task-ownership-collision",
+                                    contract: owner.contract,
+                                    detail: `${resource.kind} ${resource.key} is held by ${owners.map((candidate) => candidate.contract).sort().join(", ")}`,
+                                };
+                                database.prepare("UPDATE snapshot_contracts SET status = 'isolated', current_json = NULL, fold_json = NULL, diagnostics_json = ? WHERE contract = ?").run(JSON.stringify([...parseJson(ownerRow.diagnosticsJson), diagnostic]), owner.contract);
+                            }
                         }
                     }
                 }
-            }
-            const insertLifecycleTopology = database.prepare("INSERT OR IGNORE INTO snapshot_topology(object_id, node_json) VALUES (?, ?)");
-            for (const entry of transaction.entries)
-                insertLifecycleTopology.run(entry.objectId, JSON.stringify({
-                    objectId: entry.objectId,
-                    type: "lifecycle",
-                    ledgerParents: entry.causalParent === null ? [] : [entry.causalParent],
+                const insertLifecycleTopology = database.prepare("INSERT OR IGNORE INTO snapshot_topology(object_id, node_json) VALUES (?, ?)");
+                for (const entry of transaction.entries)
+                    insertLifecycleTopology.run(entry.objectId, JSON.stringify({
+                        objectId: entry.objectId,
+                        type: "lifecycle",
+                        ledgerParents: entry.causalParent === null ? [] : [entry.causalParent],
+                    }));
+                database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(transaction.objectId, JSON.stringify({
+                    objectId: transaction.objectId,
+                    type: "transaction",
+                    ledgerParents: transaction.predecessor === null ? [] : [transaction.predecessor],
+                    verb: transaction.transaction.verb,
+                    contract,
+                    entryObjectIds: transaction.entries.map((entry) => entry.objectId),
+                    finalEntryObjectId: transaction.entries.at(-1).objectId,
                 }));
-            database.prepare("INSERT INTO snapshot_topology(object_id, node_json) VALUES (?, ?)").run(transaction.objectId, JSON.stringify({
-                objectId: transaction.objectId,
-                type: "transaction",
-                ledgerParents: transaction.predecessor === null ? [] : [transaction.predecessor],
-                verb: transaction.transaction.verb,
-                contract,
-                entryObjectIds: transaction.entries.map((entry) => entry.objectId),
-                finalEntryObjectId: transaction.entries.at(-1).objectId,
-            }));
-            acceptedTopology.add(transaction.objectId);
+                acceptedTopology.add(transaction.objectId);
+            }
+            promoteReadyJoins();
+            if (pendingJoins.size > 0 || !acceptedTopology.has(observedHead)) {
+                database.exec("ROLLBACK");
+                return false;
+            }
+            database.prepare("UPDATE snapshot_contracts SET current_json = json_set(current_json, '$.observedLedgerHead', ?) WHERE current_json IS NOT NULL").run(observedHead);
+            database.prepare("UPDATE snapshot_pin SET ledger_head = ? WHERE singleton = 1").run(observedHead);
+            writeIntegrityReceipts(database);
+            database.exec("COMMIT");
+            database.close();
+            await publishImmutableSnapshot(buildPath, databasePath);
+            await garbageCollectSnapshots(databasePath);
+            return true;
         }
-        promoteReadyJoins();
-        if (pendingJoins.size > 0 || !acceptedTopology.has(observedHead)) {
-            database.exec("ROLLBACK");
+        catch {
+            try {
+                database.exec("ROLLBACK");
+            }
+            catch { /* handled by recovery */ }
             return false;
         }
-        database.prepare("UPDATE snapshot_contracts SET current_json = json_set(current_json, '$.observedLedgerHead', ?) WHERE current_json IS NOT NULL").run(observedHead);
-        database.prepare("UPDATE snapshot_pin SET ledger_head = ? WHERE singleton = 1").run(observedHead);
-        writeIntegrityReceipts(database);
-        database.exec("COMMIT");
-        return true;
-    }
-    catch {
-        try {
-            database.exec("ROLLBACK");
+        finally {
+            try {
+                database.close();
+            }
+            catch { /* database may not have opened */ }
+            await discardTemporarySnapshot(buildPath);
         }
-        catch { /* handled by recovery */ }
-        return false;
-    }
-    finally {
-        database.close();
-    }
-}
-export async function discardRepositoryCurrentState(cwd, signal) {
-    await discard(await snapshotPath(cwd, signal));
+    });
 }