@astrosheep/keiyaku 2.9.11 → 2.9.13

package/build/core/lifecycle-runner.js

@@ -5,7 +5,7 @@ import { resolveAcceptedLifecycleTransaction } from "./repository-ledger/accepte
 import { reconcileCommittedMutation, } from "./lifecycle-recovery.js";
 function coordinateObject(pins, target) {
     return {
-        ledgerHead: pins.ledgerHead,
+        ledgerHead: pins.repositoryLedgerHead,
         targetRef: pins.target.ref,
         targetHead: pins.target.head,
         deliveryRef: pins.delivery.ref,
@@ -20,7 +20,7 @@ function sameCoordinates(admission, session) {
 }
 function validateReplayCoordinate(session, coordinate) {
     if (coordinate.state === "bind-aligned") {
-        const currentHead = session.lifecycle.observedLedgerHead;
+        const currentHead = session.pins.repositoryLedgerHead;
         if (coordinate.authoritativeHead !== currentHead) {
             return {
                 code: "LIFECYCLE_REPLAY_COORDINATES_CHANGED",
@@ -55,7 +55,7 @@ function validateReplayCoordinate(session, coordinate) {
         },
         current: {
             status: resolved.status,
-            authoritativeHead: session.lifecycle.observedLedgerHead,
+            authoritativeHead: session.pins.repositoryLedgerHead,
         },
     };
 }
@@ -115,12 +115,12 @@ export async function runLifecycle(plan) {
             };
         }
         const attempt = await withContractCarrierSession({ cwd: plan.cwd, contractId: plan.contractId, mode: "observe-only", signal: plan.signal }, async (session) => {
-            observedHead = session.lifecycle.observedLedgerHead;
+            observedHead = session.pins.repositoryLedgerHead;
             const replayRefusal = validateReplayCoordinate(session, reconciliation.coordinate);
             if (replayRefusal) {
                 return { kind: "refused", outcome: refusedLifecycleFacts({
                         contractId: plan.contractId,
-                        authoritativeHead: session.lifecycle.observedLedgerHead,
+                        authoritativeHead: session.pins.repositoryLedgerHead,
                         ...surfaceCoordinateRefusal(plan.mutation, replayRefusal),
                     }) };
             }
@@ -130,13 +130,13 @@ export async function runLifecycle(plan) {
             }
             catch (error) {
                 if (error instanceof FlowError && !isCancellation(error)) {
-                    return { kind: "refused", outcome: refusedLifecycleFacts({ contractId: plan.contractId, authoritativeHead: session.lifecycle.observedLedgerHead, ...flowRefusal(error) }) };
+                    return { kind: "refused", outcome: refusedLifecycleFacts({ contractId: plan.contractId, authoritativeHead: session.pins.repositoryLedgerHead, ...flowRefusal(error) }) };
                 }
                 throw error;
             }
             return {
                 kind: "admitted",
-                ledgerHead: session.lifecycle.observedLedgerHead,
+                ledgerHead: session.pins.repositoryLedgerHead,
                 lifecycle: session.lifecycle,
                 repository: session.repository,
                 pins: session.pins,
@@ -172,20 +172,20 @@ export async function runLifecycle(plan) {
         throw error;
     }
     try {
-        return await withContractCarrierSession({ cwd: plan.cwd, contractId: plan.contractId, mode: "mutation", signal: plan.signal, ...(plan.renewDeliveryProjector ? { renewDeliveryProjector: plan.renewDeliveryProjector } : {}), ...(plan.terminalWorkspaceCleanup ? { terminalWorkspaceCleanup: plan.terminalWorkspaceCleanup } : {}) }, async (session) => {
-            observedHead = session.lifecycle.observedLedgerHead;
+        return await withContractCarrierSession({ cwd: plan.cwd, contractId: plan.contractId, mode: "mutation", signal: plan.signal, ...(plan.renewDeliveryProjector ? { renewDeliveryProjector: plan.renewDeliveryProjector } : {}), ...(plan.terminalWorkspaceCleanup ? { terminalWorkspaceCleanup: plan.terminalWorkspaceCleanup } : {}), ...(plan.transactionRunner ? { transactionRunner: plan.transactionRunner } : {}) }, async (session) => {
+            observedHead = session.pins.repositoryLedgerHead;
             const replayRefusal = validateReplayCoordinate(session, admission.replay);
             if (replayRefusal) {
                 return { kind: "noncommitted", outcome: refusedLifecycleFacts({
                         contractId: plan.contractId,
-                        authoritativeHead: session.lifecycle.observedLedgerHead,
+                        authoritativeHead: session.pins.repositoryLedgerHead,
                         ...surfaceCoordinateRefusal(plan.mutation, replayRefusal),
                     }) };
             }
             if (!sameCoordinates(admission, session)) {
                 return { kind: "noncommitted", outcome: refusedLifecycleFacts({
                         contractId: plan.contractId,
-                        authoritativeHead: session.lifecycle.observedLedgerHead,
+                        authoritativeHead: session.pins.repositoryLedgerHead,
                         code: "LIFECYCLE_COORDINATES_CHANGED",
                         message: "contract coordinates changed during lifecycle preparation",
                         pinned: coordinateObject(admission.pins, admission.target),
@@ -202,7 +202,7 @@ export async function runLifecycle(plan) {
                 refusal = flowRefusal(error);
             }
             if (refusal) {
-                return { kind: "noncommitted", outcome: refusedLifecycleFacts({ contractId: plan.contractId, authoritativeHead: session.lifecycle.observedLedgerHead, ...refusal }) };
+                return { kind: "noncommitted", outcome: refusedLifecycleFacts({ contractId: plan.contractId, authoritativeHead: session.pins.repositoryLedgerHead, ...refusal }) };
             }
             const effectSession = Object.freeze({
                 stableRoot: session.stableRoot,
@@ -239,7 +239,7 @@ export async function runLifecycle(plan) {
                     if (error instanceof FlowError && !isCancellation(error)) {
                         return { kind: "noncommitted", outcome: refusedLifecycleFacts({
                                 contractId: plan.contractId,
-                                authoritativeHead: session.lifecycle.observedLedgerHead,
+                                authoritativeHead: session.pins.repositoryLedgerHead,
                                 ...flowRefusal(error),
                             }) };
                     }
@@ -274,7 +274,7 @@ export async function runLifecycle(plan) {
                     kind: "noncommitted",
                     outcome: precommitLifecycleFacts({
                         contractId: plan.contractId,
-                        authoritativeHead: session.lifecycle.observedLedgerHead,
+                        authoritativeHead: session.pins.repositoryLedgerHead,
                         journal: session.journal,
                         cancellationObserved: session.cancellationObserved(),
                     }),

package/build/core/log.js

@@ -44,7 +44,7 @@ export async function readContractLog(input) {
             at: entry.at,
             actor: entry.actor,
         })),
-        markdown: renderCurrentContractView(model),
+        markdown: renderCurrentContractView(model, read.observedLedgerHead),
         ...(warning ? { amendmentWarning: warning } : {}),
     };
 }

package/build/core/outcome-base.js

@@ -88,14 +88,14 @@ export class EffectJournal {
     }
 }
 export function carrierLifecycleEffect(carrier) {
-    const idempotencyKey = `carrier:${carrier.ledgerHead}`;
+    const idempotencyKey = `carrier:${carrier.contractHead}`;
     if (carrier.status === "failed") {
         return { effect: "carrier-projection", idempotencyKey, status: "failed", cause: { code: "CARRIER_MATERIALIZATION_FAILED", message: carrier.cause } };
     }
     if (carrier.status === "target-unavailable") {
         return { effect: "carrier-projection", idempotencyKey, status: "failed", cause: { code: "CARRIER_TARGET_UNAVAILABLE", message: carrier.reason } };
     }
-    return { effect: "carrier-projection", idempotencyKey, status: "succeeded", receipt: { ledgerHead: carrier.ledgerHead, status: carrier.status } };
+    return { effect: "carrier-projection", idempotencyKey, status: "succeeded", receipt: { contractHead: carrier.contractHead, status: carrier.status } };
 }
 export function committedLifecycleFacts(input) {
     return {

package/build/core/projection/akuma-name.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const FORBIDDEN_CODE_POINT = /[\u0000-\u001f\u007f-\u009f\uD800-\uDFFF]/u;
+const FORBIDDEN_PORTABLE_PATH_CHARACTER = /[\\/<>:"|?*]/u;
+const MAX_AKUMA_NAME_BYTES = 255;
+export function canonicalizeAkumaName(value) {
+    return value.normalize("NFC");
+}
+export function akumaNameProblem(value) {
+    if (value.length === 0)
+        return "must not be empty.";
+    if (value !== canonicalizeAkumaName(value))
+        return "must use Unicode NFC normalization.";
+    if (value === "." || value === ".." || value.startsWith(".")) {
+        return "must not be a dot path or hidden filesystem name.";
+    }
+    if (FORBIDDEN_CODE_POINT.test(value))
+        return "must not contain control characters or unpaired surrogates.";
+    if (/\p{White_Space}/u.test(value))
+        return "must not contain whitespace.";
+    if (FORBIDDEN_PORTABLE_PATH_CHARACTER.test(value))
+        return "must not contain portable filesystem separators or reserved punctuation.";
+    if (/[. ]$/u.test(value))
+        return "must not end with a dot or space.";
+    if (WINDOWS_RESERVED_NAME.test(value))
+        return "must not be a reserved Windows filename.";
+    if (Buffer.byteLength(value, "utf8") > MAX_AKUMA_NAME_BYTES) {
+        return `must contain at most ${MAX_AKUMA_NAME_BYTES} UTF-8 bytes.`;
+    }
+    return null;
+}
+/**
+ * Akuma identity is exact NFC text. Case, variation selectors, ZWJ sequences,
+ * and visually confusable code points are intentionally not folded.
+ */
+export const akumaNameSchema = z.string().superRefine((value, ctx) => {
+    const problem = akumaNameProblem(value);
+    if (problem !== null)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem });
+});
+export function isAkumaName(value) {
+    return akumaNameProblem(value) === null;
+}

package/build/core/projection/generation/database.js

@@ -1,20 +1,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DatabaseSync } from "node:sqlite";
+import { ProjectionStateError } from "../../atomic-publish.js";
 import { configureHeartBusyTimeout } from "../heart.js";
 import { ProjectionGenerationStoreError, parseStoredRow, validateHistory, } from "./model.js";
+import { ProjectionGenerationLedger } from "./ledger.js";
 export const PROJECTION_GENERATION_STORE_FILE = "heart";
-export const PROJECTION_GENERATION_SCHEMA_VERSION = 4;
-const SCHEMA_TABLE_SQL = `
+export const PROJECTION_GENERATION_SCHEMA_VERSION = 6;
+const GENERATION_SCHEMA_SQL = `
   CREATE TABLE generation_schema (
     singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
     version INTEGER NOT NULL CHECK (version = ${PROJECTION_GENERATION_SCHEMA_VERSION})
   ) STRICT
 `;
-const RECORD_TABLE_SQL = `
+const GENERATION_RECORD_SQL = `
   CREATE TABLE generation_records (
     seq INTEGER PRIMARY KEY CHECK (seq > 0),
-    kind TEXT NOT NULL CHECK (kind IN ('launch', 'adoption', 'kill-intent', 'interrupt-intent', 'verdict')),
+    activity_kind TEXT NOT NULL CHECK (activity_kind IN ('launch', 'adoption', 'kill-intent', 'interrupt-intent', 'verdict')),
     execution_id TEXT NOT NULL CHECK (length(trim(execution_id)) > 0),
     facts_json TEXT NOT NULL CHECK (json_valid(facts_json))
   ) STRICT
@@ -92,6 +94,34 @@ const TELL_LAUNCH_COORDINATE_TABLE_SQL = `
   ) STRICT
 `;
 const closedDatabases = new WeakSet();
+function projectionHeartPath(projectionDirectory) {
+    return path.join(projectionDirectory, PROJECTION_GENERATION_STORE_FILE);
+}
+function openHeartConnection(databasePath, readOnly, foreignKeys = false) {
+    const database = new DatabaseSync(databasePath, {
+        readOnly,
+        ...(foreignKeys ? { enableForeignKeyConstraints: true } : {}),
+        enableDoubleQuotedStringLiterals: false,
+        allowExtension: false,
+    });
+    try {
+        configureHeartBusyTimeout(database);
+        if (!readOnly) {
+            database.exec("PRAGMA journal_mode = DELETE");
+            database.exec("PRAGMA synchronous = FULL");
+            database.exec("PRAGMA foreign_keys = ON");
+            database.exec("PRAGMA trusted_schema = OFF");
+        }
+        return database;
+    }
+    catch (error) {
+        try {
+            database.close();
+        }
+        catch { /* preserve configuration failure */ }
+        throw error;
+    }
+}
 /** Classify only proved missing schema evidence as historical incompatibility. */
 export function projectionGenerationStoreInspectionError(databasePath, error) {
     if (error instanceof ProjectionGenerationStoreError)
@@ -153,14 +183,16 @@ function validateSchemaShape(database) {
         throw new ProjectionGenerationStoreError(`projection generation schema contains unexpected objects: ${signature || "none"}`, { observation: "incompatible" });
     }
     const metadata = database.prepare("SELECT singleton, version FROM generation_schema").all();
-    if (metadata.length !== 1 || Number(metadata[0].singleton) !== 1 || Number(metadata[0].version) !== PROJECTION_GENERATION_SCHEMA_VERSION) {
+    if (metadata.length !== 1
+        || Number(metadata[0].singleton) !== 1
+        || Number(metadata[0].version) !== PROJECTION_GENERATION_SCHEMA_VERSION) {
         throw new ProjectionGenerationStoreError("projection generation schema metadata is malformed", { observation: "incompatible" });
     }
-    const recordColumns = database.prepare("PRAGMA table_info(generation_records)").all();
-    const columnSignature = recordColumns
+    const generationColumns = database.prepare("PRAGMA table_info(generation_records)").all();
+    const generationSignature = generationColumns
         .map((column) => `${column.name}:${column.type}:${Number(column.notnull)}:${Number(column.pk)}`)
         .join(",");
-    if (columnSignature !== "seq:INTEGER:0:1,kind:TEXT:1:0,execution_id:TEXT:1:0,facts_json:TEXT:1:0") {
+    if (generationSignature !== "seq:INTEGER:0:1,activity_kind:TEXT:1:0,execution_id:TEXT:1:0,facts_json:TEXT:1:0") {
         throw new ProjectionGenerationStoreError("projection generation record schema is malformed", { observation: "incompatible" });
     }
     const identityColumns = database.prepare("PRAGMA table_info(projection_identity)").all();
@@ -228,8 +260,10 @@ function initializeOrValidateSchema(database) {
       ORDER BY name
     `).all();
         if (version === 0 && objects.length === 0) {
-            database.exec(SCHEMA_TABLE_SQL);
-            database.exec(RECORD_TABLE_SQL);
+            database.exec(GENERATION_SCHEMA_SQL);
+            database.exec(GENERATION_RECORD_SQL);
+            database.prepare("INSERT INTO generation_schema (singleton, version) VALUES (1, ?)")
+                .run(PROJECTION_GENERATION_SCHEMA_VERSION);
             database.exec(IDENTITY_TABLE_SQL);
             database.exec(TELL_TABLE_SQL);
             database.exec(TELL_RECEIPT_TABLE_SQL);
@@ -237,8 +271,6 @@ function initializeOrValidateSchema(database) {
             database.exec(TELL_LAUNCH_BATCH_TABLE_SQL);
             database.exec(TELL_LAUNCH_ADMISSION_TABLE_SQL);
             database.exec(TELL_LAUNCH_COORDINATE_TABLE_SQL);
-            database.prepare("INSERT INTO generation_schema (singleton, version) VALUES (1, ?)")
-                .run(PROJECTION_GENERATION_SCHEMA_VERSION);
             database.exec(`PRAGMA user_version = ${PROJECTION_GENERATION_SCHEMA_VERSION}`);
         }
         else if (version !== PROJECTION_GENERATION_SCHEMA_VERSION) {
@@ -256,22 +288,10 @@ export function openMutableDatabase(projectionDirectory) {
     const stat = fs.statSync(projectionDirectory);
     if (!stat.isDirectory())
         throw new ProjectionGenerationStoreError("projection generation store parent must be a directory");
-    const databasePath = path.join(projectionDirectory, PROJECTION_GENERATION_STORE_FILE);
+    const databasePath = projectionHeartPath(projectionDirectory);
     let database;
     try {
-        database = new DatabaseSync(databasePath, {
-            enableForeignKeyConstraints: true,
-            enableDoubleQuotedStringLiterals: false,
-            allowExtension: false,
-        });
-        configureHeartBusyTimeout(database);
-        // Rollback journal keeps observers genuinely read-only. A read-only WAL
-        // connection creates/updates -wal and -shm coordination files, while
-        // immutable WAL reads can miss concurrently committed facts.
-        database.exec("PRAGMA journal_mode = DELETE");
-        database.exec("PRAGMA synchronous = FULL");
-        database.exec("PRAGMA foreign_keys = ON");
-        database.exec("PRAGMA trusted_schema = OFF");
+        database = openHeartConnection(databasePath, false, true);
     }
     catch (error) {
         try {
@@ -282,7 +302,7 @@ export function openMutableDatabase(projectionDirectory) {
     }
     try {
         initializeOrValidateSchema(database);
-        readValidatedHistory(database);
+        readValidatedHistory(database, false);
         return { databasePath, database };
     }
     catch (error) {
@@ -296,7 +316,7 @@ export function openReadOnlyDatabase(projectionDirectory) {
     const stat = fs.statSync(projectionDirectory);
     if (!stat.isDirectory())
         throw new ProjectionGenerationStoreError("projection generation store parent must be a directory");
-    const databasePath = path.join(projectionDirectory, PROJECTION_GENERATION_STORE_FILE);
+    const databasePath = projectionHeartPath(projectionDirectory);
     try {
         if (!fs.lstatSync(databasePath).isFile()) {
             throw new ProjectionGenerationStoreError("projection generation store must be a regular file", { observation: "incompatible" });
@@ -307,14 +327,9 @@ export function openReadOnlyDatabase(projectionDirectory) {
     }
     let database;
     try {
-        database = new DatabaseSync(databasePath, {
-            readOnly: true,
-            enableDoubleQuotedStringLiterals: false,
-            allowExtension: false,
-        });
-        configureHeartBusyTimeout(database);
+        database = openHeartConnection(databasePath, true);
         validateSchemaShape(database);
-        readValidatedHistory(database);
+        readValidatedHistory(database, true);
         return { databasePath, database };
     }
     catch (error) {
@@ -325,13 +340,14 @@ export function openReadOnlyDatabase(projectionDirectory) {
         throw projectionGenerationStoreReadError(databasePath, error);
     }
 }
-/** Read the validated heart through one consistent SQLite snapshot. */
-export function withGenerationReadSnapshot(projectionDirectory, read) {
-    const { database } = openReadOnlyDatabase(projectionDirectory);
+function withProjectionHeartOperation(open, mode, operation) {
+    const database = open();
     try {
-        database.exec("BEGIN");
+        if (mode === "read")
+            return operation(database);
+        database.exec(mode === "snapshot" ? "BEGIN" : "BEGIN IMMEDIATE");
         try {
-            const result = read(database);
+            const result = operation(database);
             database.exec("COMMIT");
             return result;
         }
@@ -344,64 +360,110 @@ export function withGenerationReadSnapshot(projectionDirectory, read) {
         closeDatabase(database);
     }
 }
+/** Read the validated heart through one consistent SQLite snapshot. */
+export function withGenerationReadSnapshot(projectionDirectory, read) {
+    return withProjectionHeartOperation(() => openReadOnlyDatabase(projectionDirectory).database, "snapshot", read);
+}
+function openProjectionHeartDatabase(projectionDirectory, readOnly) {
+    const databasePath = projectionHeartPath(projectionDirectory);
+    if (!fs.lstatSync(databasePath).isFile()) {
+        throw new ProjectionStateError("projection heart must be a regular file");
+    }
+    return openHeartConnection(databasePath, readOnly, true);
+}
+export function withProjectionHeartRead(projectionDirectory, read) {
+    return withProjectionHeartOperation(() => openProjectionHeartDatabase(projectionDirectory, true), "read", read);
+}
+export function withProjectionHeartReadSnapshot(projectionDirectory, read) {
+    return withProjectionHeartOperation(() => openProjectionHeartDatabase(projectionDirectory, true), "snapshot", read);
+}
+export function withProjectionHeartWrite(projectionDirectory, write) {
+    return withProjectionHeartOperation(() => openProjectionHeartDatabase(projectionDirectory, false), "write", write);
+}
+export function openProjectionTellObserver(projectionDirectory) {
+    const database = openProjectionHeartDatabase(projectionDirectory, true);
+    let closed = false;
+    let observedDataVersion;
+    const assertOpen = () => {
+        if (closed)
+            throw new ProjectionStateError("projection tell observer is closed");
+    };
+    const readDataVersion = () => {
+        assertOpen();
+        const row = database.prepare("PRAGMA data_version").get();
+        const raw = row?.data_version;
+        const value = typeof raw === "bigint" ? Number(raw) : raw;
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+            throw new ProjectionStateError("PRAGMA data_version returned an invalid value");
+        }
+        return value;
+    };
+    return {
+        hasDataVersionChanged() {
+            const current = readDataVersion();
+            if (current === observedDataVersion)
+                return false;
+            observedDataVersion = current;
+            return true;
+        },
+        hasInbox() {
+            assertOpen();
+            return database.prepare(`
+        SELECT 1
+        FROM projection_tells
+        WHERE state = 'inbox'
+        LIMIT 1
+      `).get() !== undefined;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            closeDatabase(database);
+        },
+    };
+}
 export function assertDatabaseOpen(database) {
     if (closedDatabases.has(database))
         throw new ProjectionGenerationStoreError("projection generation store is closed");
 }
-export function readValidatedHistory(database) {
-    const rows = database.prepare(`
-    SELECT seq, kind, execution_id, facts_json
-    FROM generation_records
-    ORDER BY seq
-  `).all();
-    const records = rows.map(parseStoredRow);
+export function connectionBoundGenerationStore(database, readOnly) {
+    return new ProjectionGenerationLedger(database, readOnly);
+}
+export function readValidatedHistory(database, readOnly) {
+    const records = connectionBoundGenerationStore(database, readOnly).readRecords().map((record) => parseStoredRow({
+        seq: record.seq,
+        kind: record.kind,
+        execution_id: record.executionId,
+        facts_json: JSON.stringify(record.facts),
+    }));
     return { records, current: validateHistory(records) };
 }
 export function appendRecord(database, kind, executionId, facts, seq) {
-    const encoded = JSON.stringify(facts);
-    database.prepare(`
-    INSERT INTO generation_records (seq, kind, execution_id, facts_json)
-    VALUES (?, ?, ?, ?)
-  `).run(seq, kind, executionId, encoded);
-    return { seq, kind, executionId, facts: JSON.parse(encoded) };
+    const record = connectionBoundGenerationStore(database, false)
+        .appendRecord(kind, executionId, facts, seq);
+    return {
+        seq: record.seq,
+        kind: record.kind,
+        executionId: record.executionId,
+        facts: record.facts,
+    };
 }
 export function writeTransition(database, readOnly, run) {
     assertDatabaseOpen(database);
-    if (readOnly) {
-        throw new ProjectionGenerationStoreError("projection generation store is read-only");
-    }
-    if (database.isTransaction)
-        return run();
-    database.exec("BEGIN IMMEDIATE");
-    try {
-        const result = run();
-        database.exec("COMMIT");
-        return result;
-    }
-    catch (error) {
-        rollbackQuietly(database);
-        throw error;
-    }
+    return connectionBoundGenerationStore(database, readOnly).write(run);
 }
 export function beginGenerationWriteTransaction(database, readOnly) {
     assertDatabaseOpen(database);
-    if (readOnly)
-        throw new ProjectionGenerationStoreError("projection generation store is read-only");
-    if (database.isTransaction)
-        throw new ProjectionGenerationStoreError("projection generation write transaction is already open");
-    database.exec("BEGIN IMMEDIATE");
+    connectionBoundGenerationStore(database, readOnly).beginWriteTransaction();
 }
 export function commitGenerationWriteTransaction(database) {
     assertDatabaseOpen(database);
-    if (!database.isTransaction)
-        throw new ProjectionGenerationStoreError("projection generation write transaction is not open");
-    database.exec("COMMIT");
+    connectionBoundGenerationStore(database, false).commitWriteTransaction();
 }
 export function rollbackGenerationWriteTransaction(database) {
     assertDatabaseOpen(database);
-    if (!database.isTransaction)
-        return;
-    rollbackQuietly(database);
+    connectionBoundGenerationStore(database, false).rollbackWriteTransaction();
 }
 export function closeDatabase(database) {
     if (closedDatabases.has(database))

package/build/core/projection/generation/ledger.js

@@ -0,0 +1,91 @@
+import { assertExecutionId, assertPositiveSafeInteger, cloneFacts, ProjectionGenerationStoreError, } from "./model.js";
+const RECORD_KINDS = new Set([
+    "launch", "adoption", "kill-intent", "interrupt-intent", "verdict",
+]);
+/** The projection-owned persistence adapter for generation facts in heart. */
+export class ProjectionGenerationLedger {
+    #database;
+    #readOnly;
+    constructor(database, readOnly) {
+        this.#database = database;
+        this.#readOnly = readOnly;
+    }
+    readRecords() {
+        const rows = this.#database.prepare(`
+      SELECT seq, activity_kind, execution_id, facts_json
+      FROM generation_records
+      ORDER BY seq
+    `).all();
+        return rows.map((row) => {
+            const seq = assertPositiveSafeInteger(Number(row.seq), "generation row seq");
+            if (typeof row.activity_kind !== "string" || !RECORD_KINDS.has(row.activity_kind)) {
+                throw new ProjectionGenerationStoreError(`generation row ${seq} has unknown kind '${String(row.activity_kind)}'`);
+            }
+            if (typeof row.execution_id !== "string")
+                throw new ProjectionGenerationStoreError(`generation row ${seq} has invalid execution_id`);
+            const executionId = assertExecutionId(row.execution_id);
+            if (typeof row.facts_json !== "string")
+                throw new ProjectionGenerationStoreError(`generation row ${seq} facts_json must be text`);
+            let facts;
+            try {
+                facts = cloneFacts(JSON.parse(row.facts_json), `generation row ${seq} facts`);
+            }
+            catch (cause) {
+                if (cause instanceof Error && cause.message.startsWith(`generation row ${seq}`))
+                    throw cause;
+                throw new ProjectionGenerationStoreError(`generation row ${seq} facts_json is invalid JSON`, { cause });
+            }
+            return { seq, kind: row.activity_kind, executionId, facts };
+        });
+    }
+    appendRecord(kind, executionId, facts, seq) {
+        if (this.#readOnly)
+            throw new ProjectionGenerationStoreError("projection generation store is read-only");
+        const encoded = JSON.stringify(facts);
+        this.#database.prepare(`
+      INSERT INTO generation_records (seq, activity_kind, execution_id, facts_json)
+      VALUES (?, ?, ?, ?)
+    `).run(seq, kind, executionId, encoded);
+        return { seq, kind, executionId, facts: JSON.parse(encoded) };
+    }
+    write(run) {
+        if (this.#readOnly)
+            throw new ProjectionGenerationStoreError("projection generation store is read-only");
+        if (this.#database.isTransaction)
+            return run();
+        this.#database.exec("BEGIN IMMEDIATE");
+        try {
+            const result = run();
+            this.#database.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.rollback();
+            throw error;
+        }
+    }
+    beginWriteTransaction() {
+        if (this.#readOnly)
+            throw new ProjectionGenerationStoreError("projection generation store is read-only");
+        if (this.#database.isTransaction)
+            throw new ProjectionGenerationStoreError("projection generation write transaction is already open");
+        this.#database.exec("BEGIN IMMEDIATE");
+    }
+    commitWriteTransaction() {
+        if (!this.#database.isTransaction)
+            throw new ProjectionGenerationStoreError("projection generation write transaction is not open");
+        this.#database.exec("COMMIT");
+    }
+    rollbackWriteTransaction() {
+        if (this.#database.isTransaction)
+            this.rollback();
+    }
+    rollback() {
+        try {
+            this.#database.exec("ROLLBACK");
+        }
+        catch {
+            // Preserve the failure that caused rollback.
+        }
+    }
+}