@astrosheep/keiyaku 2.9.9 → 2.9.11

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

@@ -0,0 +1,853 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { runGitProcess } from "../../git/core.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;
+const SCHEMA = `
+  CREATE TABLE snapshot_schema (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    version INTEGER NOT NULL CHECK (version = ${REPOSITORY_CURRENT_STATE_VERSION})
+  ) STRICT;
+  CREATE TABLE snapshot_pin (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    ledger_head TEXT,
+    object_format TEXT CHECK (object_format IS NULL OR object_format IN ('sha1', 'sha256')),
+    empty_tree TEXT
+  ) STRICT;
+  CREATE TABLE snapshot_contracts (
+    contract TEXT PRIMARY KEY CHECK (length(contract) > 0),
+    status TEXT NOT NULL CHECK (status IN ('healthy', 'diseased', 'isolated')),
+    current_json TEXT CHECK (current_json IS NULL OR json_valid(current_json)),
+    fold_json TEXT CHECK (fold_json IS NULL OR json_valid(fold_json)),
+    diagnostics_json TEXT NOT NULL CHECK (json_valid(diagnostics_json))
+  ) STRICT;
+  CREATE TABLE snapshot_history (
+    contract TEXT NOT NULL,
+    position INTEGER NOT NULL CHECK (position >= 0),
+    object_id TEXT NOT NULL,
+    entry_json TEXT NOT NULL CHECK (json_valid(entry_json)),
+    PRIMARY KEY(contract, position),
+    UNIQUE(object_id)
+  ) STRICT;
+  CREATE TABLE snapshot_summaries (
+    contract TEXT PRIMARY KEY,
+    history_json TEXT NOT NULL CHECK (json_valid(history_json))
+  ) STRICT;
+  CREATE TABLE snapshot_repository (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    diagnostics_json TEXT NOT NULL CHECK (json_valid(diagnostics_json))
+  ) STRICT;
+  CREATE TABLE snapshot_topology (
+    object_id TEXT PRIMARY KEY,
+    node_json TEXT NOT NULL CHECK (json_valid(node_json))
+  ) STRICT;
+  CREATE TABLE snapshot_resources (
+    kind TEXT NOT NULL CHECK (kind IN ('worktree', 'task')),
+    resource_key TEXT NOT NULL,
+    contract TEXT NOT NULL,
+    PRIMARY KEY(kind, resource_key, contract)
+  ) STRICT;
+  CREATE TABLE snapshot_integrity (
+    receipt_key TEXT PRIMARY KEY,
+    digest TEXT NOT NULL CHECK (length(digest) = 64)
+  ) STRICT;
+`;
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+function exactRows(database, sql, ...params) {
+    return database.prepare(sql).all(...params);
+}
+function pinDigest(pin) {
+    return digest(["keiyaku-current-state-v3", REPOSITORY_CURRENT_STATE_VERSION, pin.head, pin.objectFormat, pin.emptyTree]);
+}
+function repositoryDigest(database) {
+    return digest(["repository", exactRows(database, "SELECT singleton, diagnostics_json FROM snapshot_repository ORDER BY singleton")]);
+}
+function topologyDigest(database) {
+    return digest(["topology", exactRows(database, "SELECT object_id, node_json FROM snapshot_topology ORDER BY object_id")]);
+}
+function resourcesDigest(database, contract) {
+    return digest(["resources", contract ?? null, contract === undefined
+            ? exactRows(database, "SELECT kind, resource_key, contract FROM snapshot_resources ORDER BY kind, resource_key, contract")
+            : exactRows(database, "SELECT kind, resource_key, contract FROM snapshot_resources WHERE contract = ? ORDER BY kind, resource_key", contract)]);
+}
+function contractDigest(database, contract, summaryOnly) {
+    const contractRows = summaryOnly
+        ? exactRows(database, "SELECT contract, status, current_json, diagnostics_json FROM snapshot_contracts WHERE contract = ?", contract)
+        : exactRows(database, "SELECT contract, status, current_json, fold_json, diagnostics_json FROM snapshot_contracts WHERE contract = ?", contract);
+    const historyRows = summaryOnly
+        ? exactRows(database, "SELECT contract, history_json FROM snapshot_summaries WHERE contract = ?", contract)
+        : exactRows(database, "SELECT contract, position, object_id, entry_json FROM snapshot_history WHERE contract = ? ORDER BY position", contract);
+    return digest([summaryOnly ? "contract-summary" : "contract-full", contract, contractRows, historyRows, resourcesDigest(database, contract)]);
+}
+function receipt(database, key) {
+    return database.prepare("SELECT digest FROM snapshot_integrity WHERE receipt_key = ?").get(key)?.digest ?? null;
+}
+function assertReceipt(database, key, actual) {
+    if (receipt(database, key) !== actual)
+        throw new Error(`snapshot integrity receipt ${key} is missing or mismatched`);
+}
+function writeIntegrityReceipts(database) {
+    database.exec("DELETE FROM snapshot_integrity");
+    const insert = database.prepare("INSERT INTO snapshot_integrity(receipt_key, digest) VALUES (?, ?)");
+    const pin = metadata(database);
+    if (!pin)
+        throw new Error("snapshot pin is missing while signing current state");
+    insert.run("pin", pinDigest(pin));
+    insert.run("repository", repositoryDigest(database));
+    insert.run("topology", topologyDigest(database));
+    insert.run("resources", resourcesDigest(database));
+    const contracts = database.prepare("SELECT contract FROM snapshot_contracts ORDER BY contract").all().map((row) => row.contract);
+    for (const contract of contracts) {
+        insert.run(`contract:${contract}:full`, contractDigest(database, contract, false));
+        insert.run(`contract:${contract}:summary`, contractDigest(database, contract, true));
+    }
+    insert.run("contracts", digest(["contracts", contracts.map((contract) => [contract, receipt(database, `contract:${contract}:full`), receipt(database, `contract:${contract}:summary`)])]));
+}
+function validatePinReceipt(database, pin) {
+    assertReceipt(database, "pin", pinDigest(pin));
+}
+function validateContractReceipt(database, contract, summaryOnly) {
+    assertReceipt(database, `contract:${contract}:${summaryOnly ? "summary" : "full"}`, contractDigest(database, contract, summaryOnly));
+}
+function validateRepositoryReceipts(database, contracts, summaryOnly, includeTopology) {
+    assertReceipt(database, "repository", repositoryDigest(database));
+    assertReceipt(database, "resources", resourcesDigest(database));
+    for (const contract of contracts)
+        validateContractReceipt(database, contract, summaryOnly);
+    const signedContracts = contracts.map((contract) => [contract, receipt(database, `contract:${contract}:full`), receipt(database, `contract:${contract}:summary`)]);
+    assertReceipt(database, "contracts", digest(["contracts", signedContracts]));
+    if (includeTopology)
+        assertReceipt(database, "topology", topologyDigest(database));
+}
+async function snapshotPath(cwd, 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);
+        }
+    }
+    catch {
+        // A subdirectory or linked-worktree .git file still needs Git's common-dir witness.
+    }
+    const result = await runGitProcess(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"], { signal });
+    if (result.error?.name === "AbortError")
+        throw result.error;
+    const commonDir = result.stdout.trim();
+    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);
+}
+function openValidated(databasePath) {
+    let database;
+    try {
+        database = new DatabaseSync(databasePath);
+        database.exec("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 database;
+    }
+    catch {
+        try {
+            database.close();
+        }
+        catch { /* discarded below */ }
+        return null;
+    }
+}
+async function discard(databasePath) {
+    await Promise.all(["", "-wal", "-shm"].map(async (suffix) => {
+        try {
+            await fs.unlink(`${databasePath}${suffix}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }));
+}
+function parseJson(text) {
+    return JSON.parse(text);
+}
+function parseDiagnostics(text, contract) {
+    const value = JSON.parse(text);
+    if (!Array.isArray(value) || value.some((item) => !isRecord(item)
+        || typeof item.objectId !== "string" || typeof item.code !== "string" || typeof item.detail !== "string"
+        || (contract !== undefined && item.contract !== contract))) {
+        throw new Error("snapshot diagnostics are invalid or disagree with their owner");
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertClosedKeys(value, keys, label) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw new Error(`${label} has an unknown or missing field`);
+    }
+}
+function parseCurrent(text, contract) {
+    const value = JSON.parse(text);
+    if (!isRecord(value))
+        throw new Error("snapshot current facts are not an object");
+    assertClosedKeys(value, ["observedLedgerHead", "contract", "phase", "intent", "receiptSegments", "seal", "bootstrapReplay", "petition", "verdict", "pins", "effectiveScope", "causal", "resources"], "snapshot current facts");
+    if (value.contract !== contract || typeof value.observedLedgerHead !== "string" || !isRecord(value.resources)) {
+        throw new Error("snapshot current facts disagree with their row key");
+    }
+    return value;
+}
+function readHistory(database, contract, summaryOnly = false, objectFormat = "sha1") {
+    if (summaryOnly) {
+        const row = database.prepare("SELECT history_json AS historyJson FROM snapshot_summaries WHERE contract = ?").get(contract);
+        if (!row)
+            throw new Error("snapshot current summary is missing");
+        const value = JSON.parse(row.historyJson);
+        if (!Array.isArray(value) || value.some((item) => !isRecord(item) || typeof item.objectId !== "string" || !createLifecycleEntrySchema(objectFormat).safeParse(item.entry).success || item.entry.contract !== contract)) {
+            throw new Error("snapshot current summary is invalid");
+        }
+        return value;
+    }
+    const rows = database.prepare("SELECT position, object_id AS objectId, entry_json AS entryJson FROM snapshot_history WHERE contract = ? ORDER BY position").all(contract);
+    if (!summaryOnly && rows.some((row, index) => row.position !== index))
+        throw new Error("snapshot lifecycle history positions are not contiguous");
+    const history = rows.map((row) => {
+        const parsed = createLifecycleEntrySchema(objectFormat).safeParse(JSON.parse(row.entryJson));
+        if (!parsed.success || parsed.data.contract !== contract)
+            throw new Error("snapshot lifecycle history row is invalid");
+        return { objectId: row.objectId, entry: parsed.data };
+    });
+    return history;
+}
+function summaryHistory(history) {
+    return history.filter(({ entry }, index) => entry.kind === "bind" || entry.kind === "petition" || index === history.length - 1)
+        .filter((row, index, rows) => rows.findIndex((candidate) => candidate.objectId === row.objectId) === index);
+}
+function currentModel(database, contract, currentJson, summaryOnly = false, objectFormat = "sha1") {
+    return { ...parseCurrent(currentJson, contract), history: readHistory(database, contract, summaryOnly, objectFormat) };
+}
+function validateContractConsistency(database, input, pin, summaryOnly = false) {
+    if ((input.currentJson === null) !== (input.foldJson === null))
+        throw new Error("snapshot current/fold presence disagrees");
+    if (input.status !== "isolated" && input.currentJson === null)
+        throw new Error("non-isolated snapshot row has no current facts");
+    if (input.currentJson === null) {
+        if (readHistory(database, input.contract).length !== 0)
+            throw new Error("isolated snapshot row retains lifecycle history");
+        return null;
+    }
+    if (!pin.objectFormat)
+        throw new Error("snapshot contract row has no object format");
+    const model = currentModel(database, input.contract, input.currentJson, summaryOnly, pin.objectFormat);
+    const diagnosticRow = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_contracts WHERE contract = ?").get(input.contract);
+    const diagnostics = parseDiagnostics(diagnosticRow.diagnosticsJson, input.contract);
+    if ((input.status === "healthy") !== (diagnostics.length === 0))
+        throw new Error("snapshot status disagrees with diagnostics");
+    if (summaryOnly) {
+        if (model.observedLedgerHead !== pin.head)
+            throw new Error("snapshot current summary disagrees with pin");
+        return model;
+    }
+    const fold = JSON.parse(input.foldJson);
+    if (!isRecord(fold) || fold.contract !== input.contract || !Array.isArray(fold.entryObjectIds))
+        throw new Error("snapshot fold is invalid");
+    const objectIds = model.history.map((row) => row.objectId);
+    if (fold.entryObjectIds.length !== objectIds.length || fold.entryObjectIds.some((oid, index) => oid !== objectIds[index])) {
+        throw new Error("snapshot fold and lifecycle history disagree");
+    }
+    if (model.observedLedgerHead !== pin.head || model.phase !== fold.phase || model.pins.base !== fold.bind?.data?.base) {
+        throw new Error("snapshot current facts disagree with fold or pin");
+    }
+    const typedFold = fold;
+    const expectedWorktree = typedFold.bind.data.workspace === "worktree"
+        ? { place: typedFold.bind.data.place, state: typedFold.terminalObjectId === null ? "held" : "released" }
+        : null;
+    const expectedTasks = (typedFold.bind.data.taskIds ?? []).map((taskId) => ({ taskId, state: typedFold.terminal?.kind === "forfeit" ? "released" : "held" }));
+    const petitionRow = [...model.history].reverse().find(({ entry }) => entry.kind === "petition");
+    const verdictRow = [...model.history].reverse().find(({ entry }) => entry.kind === "verdict");
+    const arcRow = [...model.history].reverse().find(({ entry }) => entry.kind === "arc");
+    const expectedIntent = arcRow?.entry.kind === "arc"
+        ? { arc: arcRow.entry.data.arc, openedBy: arcRow.objectId, title: arcRow.entry.data.title, objective: arcRow.entry.data.objective, brief: arcRow.entry.data.brief }
+        : { arc: 0, openedBy: typedFold.entryObjectIds[0], title: typedFold.bind.data.title, objective: typedFold.bind.data.objective, brief: null };
+    const expectedPetition = typedFold.terminalObjectId !== null || !typedFold.petition || !petitionRow || petitionRow.entry.kind !== "petition"
+        ? { state: "none" }
+        : {
+            state: typedFold.phase === "approved" && typedFold.verdict ? "approved" : "awaiting-verdict",
+            objectId: petitionRow.objectId,
+            intent: typedFold.petition.data.intent,
+            seat: typedFold.petition.data.seat,
+            target: typedFold.petition.data.target,
+            targetHead: typedFold.petition.data.intent === "claim" ? typedFold.petition.data.targetHead : null,
+            ...(typedFold.phase === "approved" && typedFold.verdict && verdictRow ? { verdictObjectId: verdictRow.objectId, summary: typedFold.verdict.data.summary } : {}),
+        };
+    const expectedVerdict = verdictRow?.entry.kind === "verdict"
+        ? { objectId: verdictRow.objectId, result: verdictRow.entry.data.result, summary: verdictRow.entry.data.summary }
+        : null;
+    if (model.pins.delivery !== typedFold.deliveryHead
+        || model.pins.target.ref !== typedFold.target
+        || model.pins.target.approvedHead !== (typedFold.approvedTargetSnapshot?.targetHead ?? null)
+        || JSON.stringify(model.effectiveScope) !== JSON.stringify(typedFold.effectiveScope)
+        || JSON.stringify(model.receiptSegments) !== JSON.stringify(typedFold.segments)
+        || JSON.stringify(model.seal) !== JSON.stringify(typedFold.segments.at(-1)?.seal ?? null)
+        || JSON.stringify(model.intent) !== JSON.stringify(expectedIntent)
+        || JSON.stringify(model.petition) !== JSON.stringify(expectedPetition)
+        || JSON.stringify(model.verdict) !== JSON.stringify(expectedVerdict)
+        || JSON.stringify(model.causal.after) !== JSON.stringify(typedFold.bind.data.after ?? [])
+        || model.resources.deliveryRef !== repositoryDeliveryRef(input.contract)
+        || JSON.stringify(model.resources.worktree) !== JSON.stringify(expectedWorktree)
+        || JSON.stringify(model.resources.tasks) !== JSON.stringify(expectedTasks)) {
+        throw new Error("snapshot nested current facts disagree with the accepted fold");
+    }
+    const actualResources = database.prepare("SELECT kind, resource_key AS resourceKey FROM snapshot_resources WHERE contract = ? ORDER BY kind, resource_key").all(input.contract);
+    const expectedResources = [
+        ...(model.resources.worktree?.state === "held" ? [{ kind: "worktree", resourceKey: model.resources.worktree.place }] : []),
+        ...model.resources.tasks.filter((task) => task.state === "held").map((task) => ({ kind: "task", resourceKey: task.taskId })),
+    ].sort((left, right) => left.kind.localeCompare(right.kind) || left.resourceKey.localeCompare(right.resourceKey));
+    if (JSON.stringify(actualResources) !== JSON.stringify(expectedResources))
+        throw new Error("snapshot resource rows disagree with current facts");
+    return model;
+}
+function metadata(database) {
+    const rows = database.prepare("SELECT ledger_head AS head, object_format AS objectFormat, empty_tree AS emptyTree FROM snapshot_pin WHERE singleton = 1").all();
+    return rows.length === 1 ? rows[0] : null;
+}
+function storedContract(database, contract) {
+    const row = database.prepare(`
+    SELECT contract, status, current_json AS currentJson, fold_json AS foldJson, diagnostics_json AS diagnosticsJson
+    FROM snapshot_contracts WHERE contract = ?
+  `).get(contract);
+    if (!row)
+        return null;
+    const pin = metadata(database);
+    if (!pin)
+        throw new Error("snapshot pin is missing");
+    return {
+        contract: row.contract,
+        status: row.status,
+        model: validateContractConsistency(database, row, pin),
+        diagnostics: parseDiagnostics(row.diagnosticsJson, contract),
+    };
+}
+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 pin = metadata(database);
+        if (!pin || pin.head !== observedHead)
+            return null;
+        validatePinReceipt(database, pin);
+        const row = storedContract(database, contract);
+        if (row)
+            validateContractReceipt(database, contract, false);
+        if (row?.status === "healthy" && row.model)
+            return { status: "healthy", model: atPin(row.model, observedHead), diagnostics: [] };
+        if (row?.status === "diseased" && row.model)
+            return { status: "diseased", model: atPin(row.model, observedHead), diagnostics: row.diagnostics };
+        if (row?.status === "isolated")
+            return { status: "isolated", contract, diagnostics: row.diagnostics };
+        assertReceipt(database, "repository", repositoryDigest(database));
+        const repository = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_repository WHERE singleton = 1").get();
+        const unattributed = repository ? parseDiagnostics(repository.diagnosticsJson).filter((disease) => disease.contract === undefined) : [];
+        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 */ }
+    }
+}
+export async function readRepositoryCurrentStatePin(cwd, signal) {
+    const databasePath = await snapshotPath(cwd, signal);
+    const database = openValidated(databasePath);
+    if (!database) {
+        await discard(databasePath);
+        return undefined;
+    }
+    try {
+        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 */ }
+    }
+}
+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 pin = metadata(database);
+        if (!pin || pin.head !== observedHead)
+            return null;
+        validatePinReceipt(database, pin);
+        assertReceipt(database, "topology", topologyDigest(database));
+        const rows = database.prepare("SELECT object_id AS objectId, node_json AS nodeJson FROM snapshot_topology").all();
+        const ledgerParents = new Map();
+        const entryIntroductions = new Map();
+        for (const row of rows) {
+            const node = JSON.parse(row.nodeJson);
+            if (node.objectId !== row.objectId || !Array.isArray(node.ledgerParents) || node.ledgerParents.some((parent) => typeof parent !== "string"))
+                throw new Error("snapshot topology row is invalid");
+            ledgerParents.set(row.objectId, node.ledgerParents);
+            if (node.type === "transaction") {
+                if (!Array.isArray(node.entryObjectIds) || node.entryObjectIds.some((entry) => typeof entry !== "string"))
+                    throw new Error("snapshot transaction topology is invalid");
+                for (const entry of node.entryObjectIds) {
+                    if (entryIntroductions.has(entry))
+                        throw new Error("snapshot topology repeats an entry introduction");
+                    entryIntroductions.set(entry, row.objectId);
+                }
+            }
+        }
+        return { ledgerParents, entryIntroductions };
+    }
+    catch {
+        database.close();
+        await discard(databasePath);
+        return null;
+    }
+    finally {
+        try {
+            database.close();
+        }
+        catch { /* corruption path already discarded */ }
+    }
+}
+/** 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 pin = metadata(database);
+        if (!pin || pin.head !== observedHead || !pin.objectFormat || !pin.emptyTree)
+            return null;
+        validatePinReceipt(database, pin);
+        assertReceipt(database, "repository", repositoryDigest(database));
+        assertReceipt(database, "topology", topologyDigest(database));
+        assertReceipt(database, "resources", resourcesDigest(database));
+        const repository = database.prepare("SELECT diagnostics_json AS diagnosticsJson FROM snapshot_repository WHERE singleton = 1").get();
+        const contractRows = database.prepare("SELECT contract, status, diagnostics_json AS diagnosticsJson FROM snapshot_contracts").all();
+        validateRepositoryReceipts(database, contractRows.map((row) => row.contract).sort(), false, true);
+        if (!repository || parseDiagnostics(repository.diagnosticsJson).length > 0 || contractRows.some((row) => row.status !== "healthy" || parseDiagnostics(row.diagnosticsJson, row.contract).length > 0))
+            return null;
+        const historyRows = database.prepare("SELECT object_id AS objectId, entry_json AS entryJson FROM snapshot_history").all();
+        const entries = new Map(historyRows.map((row) => {
+            const parsed = createLifecycleEntrySchema(pin.objectFormat).parse(JSON.parse(row.entryJson));
+            return [row.objectId, parsed];
+        }));
+        const topologyRows = database.prepare("SELECT object_id AS objectId, node_json AS nodeJson FROM snapshot_topology ORDER BY rowid").all();
+        const nodes = new Map();
+        const order = [];
+        for (const row of topologyRows) {
+            const node = JSON.parse(row.nodeJson);
+            if (node.objectId !== row.objectId || !Array.isArray(node.ledgerParents))
+                return null;
+            let typed;
+            if (node.type === "lifecycle") {
+                const entry = entries.get(row.objectId);
+                if (!entry || node.ledgerParents.length > 1)
+                    return null;
+                typed = { type: "lifecycle", objectId: row.objectId, entry, ledgerParents: node.ledgerParents, evidenceParent: evidenceObjectId(entry) };
+            }
+            else if (node.type === "transaction" && node.verb && node.contract && node.entryObjectIds && node.finalEntryObjectId) {
+                typed = { type: "transaction", objectId: row.objectId, transaction: { v: 1, kind: "transaction", verb: node.verb, predecessor: node.ledgerParents.length === 0 ? "none" : "p1" }, ledgerParents: node.ledgerParents, entryObjectIds: node.entryObjectIds, contract: node.contract, finalEntryObjectId: node.finalEntryObjectId, evidenceParent: null };
+            }
+            else if (node.type === "join" && node.ledgerParents.length === 2) {
+                typed = { type: "join", objectId: row.objectId, join: { v: 1, kind: "join", at: "1970-01-01T00:00:00.000Z", actor: "snapshot" }, ledgerParents: node.ledgerParents, evidenceParent: null };
+            }
+            else
+                return null;
+            nodes.set(row.objectId, typed);
+        }
+        const visited = new Set();
+        const visit = (objectId) => {
+            if (visited.has(objectId))
+                return;
+            visited.add(objectId);
+            const node = nodes.get(objectId);
+            if (!node)
+                return;
+            const dependencies = node.type === "transaction" ? [...node.ledgerParents, ...node.entryObjectIds] : [...node.ledgerParents];
+            for (const dependency of dependencies)
+                visit(dependency);
+            order.push(objectId);
+        };
+        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 */ }
+    }
+}
+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 pin = metadata(database);
+        if (!pin || pin.head !== observedHead)
+            return null;
+        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");
+        validatePinReceipt(database, pin);
+        validateRepositoryReceipts(database, rows.map((row) => row.contract), options.summaryOnly === true, options.includeTopology !== false);
+        return {
+            observedLedgerHead: pin.head,
+            objectFormat: pin.objectFormat,
+            emptyTree: pin.emptyTree,
+            contracts: rows.flatMap((row) => {
+                const model = validateContractConsistency(database, row, pin, options.summaryOnly);
+                if (!model)
+                    return [];
+                return [atPin(model, pin.head)];
+            }),
+            isolatedContracts: rows.filter((row) => row.status === "isolated").map((row) => row.contract),
+            diagnostics: [
+                ...parseDiagnostics(repository.diagnosticsJson),
+                ...rows.flatMap((row) => parseDiagnostics(row.diagnosticsJson, row.contract)),
+            ],
+            topology: {
+                head: pin.head,
+                nodes: options.includeTopology === false
+                    ? []
+                    : 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 */ }
+    }
+}
+export async function publishRepositoryCurrentState(cwd, read, options) {
+    const databasePath = await snapshotPath(cwd, 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 */ }
+        try {
+            database.close();
+        }
+        catch { /* database may not have opened */ }
+        throw error;
+    }
+}
+export async function advanceRepositoryCurrentState(cwd, pinnedHead, observedHead, segment, options) {
+    const databasePath = await snapshotPath(cwd, 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 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) {
+                database.exec("ROLLBACK");
+                return false;
+            }
+            if (transaction.entries.some((entry) => database.prepare("SELECT 1 FROM snapshot_history WHERE object_id = ?").get(entry.objectId) !== undefined)) {
+                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);
+            }
+            else {
+                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;
+                        }
+                    }
+                    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);
+                        }
+                    }
+                }
+            }
+            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,
+            }));
+            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");
+        return true;
+    }
+    catch {
+        try {
+            database.exec("ROLLBACK");
+        }
+        catch { /* handled by recovery */ }
+        return false;
+    }
+    finally {
+        database.close();
+    }
+}
+export async function discardRepositoryCurrentState(cwd, signal) {
+    await discard(await snapshotPath(cwd, signal));
+}