@amalgm/shell 0.1.164-preview.36072132286 → 0.1.164-preview.36809057014

package/dist/ground-save-ops.d.ts

@@ -0,0 +1,44 @@
+/** Every save a ground file's saver thread runs (ground-saver.ts), by name.
+ * Each is synchronous and runs inside its own savepoint of the batch. */
+import type Database from "better-sqlite3";
+import { acknowledgeCleanup, adoptSnapshotHistory, beginIntent, bindRecovery, relocateRows, renameSignatures, resolveOwnPublication, retire, setIntentPhase } from "./apply-saves.js";
+import { retireProofs } from "./content-clock.js";
+import { rememberConstruct } from "./construct-ledger.js";
+import { clearDeclaration, markDeclarationRejected, markDeclarationSubmitted } from "./declaration-journal.js";
+import { saveDeclaration } from "./declaration-save.js";
+import { saveAdmission } from "./detection/admission-save.js";
+import { pruneDispositions } from "./detection/disposition-rows.js";
+import { appendRecord, receiveRecords, stampAccepted } from "./entity-record-saves.js";
+import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
+import { beginAddIntent, clearAddIntent, clearRoot, installReferences, installRows, refreshRoot } from "./ground-install-saves.js";
+export declare const GROUND_SAVE_OPS: {
+    "add.beginIntent": typeof beginAddIntent;
+    "add.clearIntent": typeof clearAddIntent;
+    "apply.acknowledgeCleanup": typeof acknowledgeCleanup;
+    "apply.adoptSnapshotHistory": typeof adoptSnapshotHistory;
+    "apply.beginIntent": typeof beginIntent;
+    "apply.bindRecovery": typeof bindRecovery;
+    "apply.relocateRows": typeof relocateRows;
+    "apply.renameSignatures": typeof renameSignatures;
+    "apply.resolveOwnPublication": typeof resolveOwnPublication;
+    "apply.retire": typeof retire;
+    "apply.setIntentPhase": typeof setIntentPhase;
+    "constructs.remember": typeof rememberConstruct;
+    "detect.admit": typeof saveAdmission;
+    "detect.dispositions": (database: Database.Database, events: readonly import("@amalgm/live").DetectDispositionEvent[]) => readonly import("./detection/disposition-rows.js").DispositionRow[];
+    "detect.prune": typeof pruneDispositions;
+    "ground.retireProofs": typeof retireProofs;
+    "install.clearRoot": typeof clearRoot;
+    "install.references": typeof installReferences;
+    "install.refreshRoot": typeof refreshRoot;
+    "install.rows": typeof installRows;
+    "record.adoptSnapshotBaseline": typeof adoptSnapshotDeliveryBaseline;
+    "record.append": typeof appendRecord;
+    "record.receive": typeof receiveRecords;
+    "record.stamp": typeof stampAccepted;
+    "register.cleared": typeof clearDeclaration;
+    "register.declare": typeof saveDeclaration;
+    "register.rejected": typeof markDeclarationRejected;
+    "register.submitted": typeof markDeclarationSubmitted;
+};
+export type GroundSaveOps = typeof GROUND_SAVE_OPS;

package/dist/ground-save-ops.js

@@ -0,0 +1,41 @@
+import { acknowledgeCleanup, adoptSnapshotHistory, beginIntent, bindRecovery, relocateRows, renameSignatures, resolveOwnPublication, retire, setIntentPhase, } from "./apply-saves.js";
+import { retireProofs } from "./content-clock.js";
+import { rememberConstruct } from "./construct-ledger.js";
+import { clearDeclaration, markDeclarationRejected, markDeclarationSubmitted } from "./declaration-journal.js";
+import { saveDeclaration } from "./declaration-save.js";
+import { saveAdmission } from "./detection/admission-save.js";
+import { pruneDispositions, saveDispositions } from "./detection/disposition-rows.js";
+import { appendRecord, receiveRecords, stampAccepted } from "./entity-record-saves.js";
+import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
+import { beginAddIntent, clearAddIntent, clearRoot, installReferences, installRows, refreshRoot } from "./ground-install-saves.js";
+export const GROUND_SAVE_OPS = {
+    "add.beginIntent": beginAddIntent,
+    "add.clearIntent": clearAddIntent,
+    "apply.acknowledgeCleanup": acknowledgeCleanup,
+    "apply.adoptSnapshotHistory": adoptSnapshotHistory,
+    "apply.beginIntent": beginIntent,
+    "apply.bindRecovery": bindRecovery,
+    "apply.relocateRows": relocateRows,
+    "apply.renameSignatures": renameSignatures,
+    "apply.resolveOwnPublication": resolveOwnPublication,
+    "apply.retire": retire,
+    "apply.setIntentPhase": setIntentPhase,
+    "constructs.remember": rememberConstruct,
+    "detect.admit": saveAdmission,
+    "detect.dispositions": saveDispositions,
+    "detect.prune": pruneDispositions,
+    "ground.retireProofs": retireProofs,
+    "install.clearRoot": clearRoot,
+    "install.references": installReferences,
+    "install.refreshRoot": refreshRoot,
+    "install.rows": installRows,
+    "record.adoptSnapshotBaseline": adoptSnapshotDeliveryBaseline,
+    "record.append": appendRecord,
+    "record.receive": receiveRecords,
+    "record.stamp": stampAccepted,
+    "register.cleared": clearDeclaration,
+    "register.declare": saveDeclaration,
+    "register.rejected": markDeclarationRejected,
+    "register.submitted": markDeclarationSubmitted,
+};
+//# sourceMappingURL=ground-save-ops.js.map

package/dist/ground-save-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-save-ops.js","sourceRoot":"","sources":["../src/ground-save-ops.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,MAAM,EACN,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC/G,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEnI,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,iBAAiB,EAAE,cAAc;IACjC,iBAAiB,EAAE,cAAc;IACjC,0BAA0B,EAAE,kBAAkB;IAC9C,4BAA4B,EAAE,oBAAoB;IAClD,mBAAmB,EAAE,WAAW;IAChC,oBAAoB,EAAE,YAAY;IAClC,oBAAoB,EAAE,YAAY;IAClC,wBAAwB,EAAE,gBAAgB;IAC1C,6BAA6B,EAAE,qBAAqB;IACpD,cAAc,EAAE,MAAM;IACtB,sBAAsB,EAAE,cAAc;IACtC,qBAAqB,EAAE,iBAAiB;IACxC,cAAc,EAAE,aAAa;IAC7B,qBAAqB,EAAE,gBAAgB;IACvC,cAAc,EAAE,iBAAiB;IACjC,qBAAqB,EAAE,YAAY;IACnC,mBAAmB,EAAE,SAAS;IAC9B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,WAAW;IAClC,cAAc,EAAE,WAAW;IAC3B,8BAA8B,EAAE,6BAA6B;IAC7D,eAAe,EAAE,YAAY;IAC7B,gBAAgB,EAAE,cAAc;IAChC,cAAc,EAAE,aAAa;IAC7B,kBAAkB,EAAE,gBAAgB;IACpC,kBAAkB,EAAE,eAAe;IACnC,mBAAmB,EAAE,uBAAuB;IAC5C,oBAAoB,EAAE,wBAAwB;CACkC,CAAC"}

package/dist/ground-saver-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ground-saver-worker.js

@@ -0,0 +1,156 @@
+/**
+ * A ground file's saver thread (ground-saver.ts). Saves that arrive while it
+ * commits wait, and form the next batch: one IMMEDIATE transaction, each
+ * save in its own savepoint, one commit at synchronous=FULL, so the drive
+ * holds every save in the batch before any is answered. A failed save rolls
+ * back only its own savepoint; a failed commit fails the whole batch.
+ *
+ * A request whose long arrays follow it (ground-saver.ts) waits in its place
+ * until the last item arrives, and every save posted after it waits with it.
+ *
+ * Each ground sequence a save stamps has its receipt, checked inside that
+ * save's savepoint; receipts reach the main thread with the batch's answers,
+ * only after its commit.
+ */
+import { statSync } from "node:fs";
+import { workerData } from "node:worker_threads";
+import { currentSequence, saveGroundReceipts } from "./ground-basis.js";
+import { configureGroundConnection } from "./ground-database.js";
+import { GROUND_SAVE_OPS } from "./ground-save-ops.js";
+import { saveFailure } from "./ground-saver.js";
+import { certifyGroundSaver } from "./ground-store.js";
+import { physicalKey } from "./source-signature.js";
+import { durabilityProfile } from "./sqlite-durability.js";
+import { openFileDatabase } from "./sqlite.js";
+const { file, key, port } = workerData;
+const database = configureGroundConnection(openFileDatabase(file, { fileMustExist: true }));
+if (physicalKey(statSync(file, { bigint: true })) !== key) {
+    database.close();
+    throw new Error(`the ground database ${JSON.stringify(file)} was replaced before its saver thread opened`);
+}
+const receipts = [];
+saveGroundReceipts(database, receipt => receipts.push(receipt));
+certifyGroundSaver(database);
+port.postMessage({ durability: durabilityProfile(database) });
+/** Absolute time, comparable across threads. */
+const now = () => performance.timeOrigin + performance.now();
+/** Inside the batch transaction, a savepoint. */
+const savepoint = database.transaction((run) => run());
+const arriving = new Map();
+const queue = [];
+let scheduled = false;
+let stopping = false;
+port.on("message", (message) => {
+    if (message === "stop")
+        stopping = true;
+    else if ("name" in message) {
+        queue.push(message);
+        if (message.parts.length)
+            arriving.set(message.id, { items: message.parts.map(() => []), failure: null });
+    }
+    else if ("failure" in message)
+        arriving.get(message.id).failure = message.failure;
+    else
+        arriving.get(message.id).items[message.part].push(...message.items);
+    if (!scheduled) {
+        scheduled = true;
+        setImmediate(run);
+    }
+});
+const ready = ({ id, parts }) => {
+    const entry = arriving.get(id);
+    return !entry || entry.failure !== null || parts.every(({ length }, part) => entry.items[part].length === length);
+};
+/** Its whole input, each part back in its place; or why a part never came. */
+function assembled({ id, input, parts }) {
+    const entry = arriving.get(id);
+    if (!entry)
+        return { input };
+    if (entry.failure)
+        return { failure: entry.failure };
+    const root = { input };
+    parts.forEach(({ path }, part) => {
+        const keys = ["input", ...path];
+        let at = root;
+        for (const key of keys.slice(0, -1))
+            at = at[key];
+        at[keys.at(-1)] = entry.items[part];
+    });
+    return { input: root.input };
+}
+function run() {
+    scheduled = false;
+    let complete = 0;
+    while (complete < queue.length && ready(queue[complete]))
+        complete += 1;
+    const batch = queue.splice(0, complete);
+    if (batch.length)
+        commit(batch);
+    for (const { id } of batch)
+        arriving.delete(id);
+    if (stopping && queue.length === 0) {
+        port.close();
+        database.close();
+    }
+}
+function saveOne(request) {
+    const { id, name } = request, began = now(), mark = receipts.length;
+    const whole = assembled(request);
+    if ("failure" in whole)
+        return { id, ok: false, failure: whole.failure, began };
+    const { input } = whole;
+    try {
+        const from = currentSequence(database);
+        let through = from;
+        const value = savepoint(() => {
+            const value = GROUND_SAVE_OPS[name](database, input);
+            if (value && typeof value.then === "function")
+                throw new Error(`ground save ${name} is asynchronous`);
+            through = currentSequence(database);
+            const own = receipts.slice(mark);
+            if (BigInt(own.length) !== through - from || own.some((receipt, at) => receipt.sequence !== from + BigInt(at + 1))) {
+                throw new Error(`ground save ${name} stamped sequences without receipts`);
+            }
+            return value;
+        });
+        return { id, ok: true, value, from, through, began };
+    }
+    catch (error) {
+        receipts.length = mark;
+        return { id, ok: false, failure: saveFailure(error), began };
+    }
+}
+function commit(batch) {
+    const began = now();
+    let replies = [];
+    let lost = false;
+    receipts.length = 0;
+    try {
+        database.exec("BEGIN IMMEDIATE");
+        lost = true;
+        for (const request of batch)
+            replies.push(saveOne(request));
+        database.exec("COMMIT");
+        lost = false;
+    }
+    catch (error) {
+        try {
+            if (database.inTransaction)
+                database.exec("ROLLBACK");
+        }
+        catch { /* the commit's own failure is reported */ }
+        const failed = saveFailure(error);
+        replies = batch.map(({ id }) => ({ id, ok: false, failure: failed, began }));
+        receipts.length = 0;
+    }
+    const answer = { replies, receipts: receipts.splice(0), began, ended: now(), lost };
+    try {
+        port.postMessage(answer);
+    }
+    catch (error) {
+        // A value the port cannot carry fails its saves; the receipts still go.
+        const failed = saveFailure(error);
+        port.postMessage({ ...answer, replies: replies.map(({ id, began }) => ({ id, ok: false, failure: failed, began })) });
+    }
+}
+//# sourceMappingURL=ground-saver-worker.js.map

package/dist/ground-saver-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-saver-worker.js","sourceRoot":"","sources":["../src/ground-saver-worker.ts"],"names":[],"mappings":"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"}

package/dist/ground-saver.d.ts

@@ -0,0 +1,75 @@
+import { type GroundReceipt } from "./ground-basis.js";
+import type { GroundSaveOps } from "./ground-save-ops.js";
+import type { DurabilityProfile } from "./sqlite-durability.js";
+export type GroundSaveName = keyof GroundSaveOps;
+export type GroundSaveInput<N extends GroundSaveName> = Parameters<GroundSaveOps[N]>[1];
+export type GroundSaveValue<N extends GroundSaveName> = ReturnType<GroundSaveOps[N]>;
+/** One committed save. Times are this thread's `performance.now()`. */
+export interface Saved<T> {
+    readonly value: T;
+    /** The ground sequences it stamped: after `from`, through `through`. */
+    readonly from: bigint;
+    readonly through: bigint;
+    readonly posted: number;
+    /** Its savepoint began; its batch committed. */
+    readonly began: number;
+    readonly ended: number;
+}
+/** A long array taken out of a save's input: where it goes, and its length. */
+export interface GroundSavePart {
+    readonly path: readonly string[];
+    readonly length: number;
+}
+export interface GroundSaveRequest {
+    readonly id: number;
+    readonly name: GroundSaveName;
+    readonly input: unknown;
+    readonly parts: readonly GroundSavePart[];
+}
+/** A request's next items for one part, in order; or why the rest never comes. */
+export type GroundSaveItems = {
+    readonly id: number;
+    readonly part: number;
+    readonly items: readonly unknown[];
+} | {
+    readonly id: number;
+    readonly failure: GroundSaveFailure;
+};
+export interface GroundSaveFailure {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly code?: string;
+}
+export type GroundSaveReply = {
+    readonly id: number;
+    readonly began: number;
+} & ({
+    readonly ok: true;
+    readonly value: unknown;
+    readonly from: bigint;
+    readonly through: bigint;
+} | {
+    readonly ok: false;
+    readonly failure: GroundSaveFailure;
+});
+export interface GroundSaveBatch {
+    readonly replies: readonly GroundSaveReply[];
+    readonly receipts: readonly GroundReceipt[];
+    /** Absolute times: the batch began and committed or rolled back. */
+    readonly began: number;
+    readonly ended: number;
+    /** The commit failed after writes began: its receipts may be missing. */
+    readonly lost: boolean;
+}
+export declare const saveFailure: (error: unknown) => GroundSaveFailure;
+/** The first ordinary connection starts it; `stopGroundSaver` ends it. */
+export declare function startGroundSaver(file: string, key: string): void;
+/** After every other owner has closed: the thread finishes its queue, then
+ * closes. Settles once it has exited; it holds the process open until then. */
+export declare function stopGroundSaver(file: string): Promise<void>;
+export declare function save<N extends GroundSaveName>(file: string, name: N, input: GroundSaveInput<N>): Promise<Saved<GroundSaveValue<N>>>;
+/** Settles once every save posted before the call has settled. */
+export declare function saved(file: string): Promise<void>;
+/** The settings the saver's commits run under, read back on its connection. */
+export declare function groundSaveDurability(file: string): Promise<DurabilityProfile>;

package/dist/ground-saver.js

@@ -0,0 +1,216 @@
+/**
+ * Every write to a ground file is a named save, run by that file's one saver
+ * thread (ground-saver-worker.ts); the main thread's connections only read
+ * (ground-database.ts), so it never waits for the drive. A save's promise settles once the drive holds it: its batch
+ * committed at synchronous=FULL. Saves commit in the order they were posted,
+ * so a caller checks its main-side preconditions when it posts. A reader
+ * whose decision must see every earlier save awaits `saved(file)`.
+ *
+ * A batch's receipts carry the main thread's warm territories forward before
+ * any of its saves settles. A read of the ground drains the receipts already
+ * delivered first (ground-basis.ts), so no warm view waits for an event turn.
+ * No save's copy holds the main thread: a long array anywhere in its input's
+ * object spine crosses after the rest, a bounded run of items per message
+ * across turns (turns.ts), and the thread runs the save once every item has
+ * arrived. Its place in the commit order is still the call's.
+ *
+ * The thread never keeps the process alive; a pending save does. A thread
+ * that dies fails its pending saves, and the next save starts another.
+ */
+import { channel } from "node:diagnostics_channel";
+import { MessageChannel, receiveMessageOnPort } from "node:worker_threads";
+import { ITEMS_PER_BOUNDARY } from "@amalgm/live";
+import { carryGroundReceipt, GroundBasisChangedError, registerReceiptSource, retireGroundViews } from "./ground-basis.js";
+import { moduleThread } from "./module-thread.js";
+import { databaseFileName } from "./sqlite.js";
+import { turnBoundary } from "./turns.js";
+const WORKER = new URL("./ground-saver-worker.js", import.meta.url);
+const saves = channel("amalgm:ground-save");
+/** Keyed by databaseFileName, the name every connection reports. */
+const savers = new Map();
+let nextId = 0;
+const local = (absolute) => absolute - performance.timeOrigin;
+export const saveFailure = (error) => error instanceof Error
+    ? { name: error.name, message: error.message, stack: error.stack, code: error.code }
+    : { name: "Error", message: String(error) };
+function restore(failure) {
+    const error = failure.name === GroundBasisChangedError.name ? new GroundBasisChangedError(failure.message) : new Error(failure.message);
+    if (failure.name !== error.name)
+        error.name = failure.name;
+    if (failure.stack)
+        error.stack = failure.stack;
+    if (failure.code)
+        error.code = failure.code;
+    return error;
+}
+/** Receipts first, then each save in order. */
+function answer(name, saver, batch) {
+    for (const receipt of batch.receipts)
+        carryGroundReceipt(name, receipt);
+    if (batch.lost)
+        retireGroundViews(name);
+    const ended = local(batch.ended);
+    for (const reply of batch.replies) {
+        const pending = saver.pending.get(reply.id);
+        if (!pending)
+            continue;
+        saver.pending.delete(reply.id);
+        if (saves.hasSubscribers) {
+            saves.publish({ file: name, save: pending.name, ok: reply.ok, posted: pending.posted, began: local(reply.began), ended,
+                batch: batch.replies.length });
+        }
+        if (reply.ok) {
+            pending.resolve({ value: reply.value, from: reply.from, through: reply.through, posted: pending.posted,
+                began: local(reply.began), ended });
+        }
+        else
+            pending.reject(restore(reply.failure));
+    }
+    if (saver.pending.size === 0)
+        saver.port?.unref();
+}
+/** What the thread already sent, without waiting for its event. */
+function drain(saver) {
+    const port = saver.port;
+    if (!port)
+        return;
+    for (let message = receiveMessageOnPort(port); message; message = receiveMessageOnPort(port))
+        saver.receive(message.message);
+}
+function spawn(name, saver) {
+    const { port1, port2 } = new MessageChannel();
+    const worker = moduleThread(WORKER, { workerData: { file: name, key: saver.key, port: port2 }, transferList: [port2] });
+    saver.worker = worker;
+    saver.port = port1;
+    let durable, failed;
+    saver.durability = new Promise((resolve, reject) => { durable = resolve; failed = reject; });
+    saver.durability.catch(() => { });
+    saver.receive = message => { if ("durability" in message)
+        durable(message.durability);
+    else
+        answer(name, saver, message); };
+    port1.on("message", saver.receive);
+    let fault = new Error(`the ground saver thread for ${JSON.stringify(name)} stopped`);
+    worker.on("error", error => { fault = error; });
+    worker.once("exit", () => {
+        // Answers it sent before it stopped still count; the rest fail, and any
+        // receipt it could not send leaves every warm view unproven.
+        drain(saver);
+        failed(fault);
+        port1.close();
+        if (saver.worker === worker) {
+            saver.worker = null;
+            saver.port = null;
+        }
+        if (saver.pending.size)
+            retireGroundViews(name);
+        for (const [id, pending] of saver.pending) {
+            saver.pending.delete(id);
+            pending.reject(fault);
+        }
+    });
+    // Last: a listener added after unref refs its handle again.
+    worker.unref();
+    port1.unref();
+}
+/** The first ordinary connection starts it; `stopGroundSaver` ends it. */
+export function startGroundSaver(file, key) {
+    const name = databaseFileName(file);
+    if (savers.has(name))
+        return;
+    const saver = { key, worker: null, port: null, receive: () => { }, durability: new Promise(() => { }),
+        pending: new Map(), last: Promise.resolve() };
+    savers.set(name, saver);
+    registerReceiptSource(name, () => drain(saver));
+    spawn(name, saver);
+}
+/** After every other owner has closed: the thread finishes its queue, then
+ * closes. Settles once it has exited; it holds the process open until then. */
+export function stopGroundSaver(file) {
+    const name = databaseFileName(file);
+    const saver = savers.get(name);
+    savers.delete(name);
+    registerReceiptSource(name, null);
+    const worker = saver?.worker;
+    if (!worker)
+        return Promise.resolve();
+    const exited = new Promise(resolve => worker.once("exit", () => resolve()));
+    worker.ref();
+    saver.port.postMessage("stop");
+    return exited;
+}
+/** The input with each long array of its object spine (plain objects, never
+ * an array's items) left empty, and those arrays in the order they were met. */
+function partitioned(input) {
+    const parts = [];
+    const take = (value, path) => {
+        if (Array.isArray(value)) {
+            if (value.length <= ITEMS_PER_BOUNDARY)
+                return value;
+            parts.push({ path, items: value });
+            return [];
+        }
+        if (value === null || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype)
+            return value;
+        const head = {};
+        for (const [key, entry] of Object.entries(value))
+            head[key] = take(entry, [...path, key]);
+        return head;
+    };
+    return { head: take(input, []), parts };
+}
+/** Each part's items, a bounded run per message, until the thread that holds
+ * the request stops, which fails the save; a run it cannot carry fails it too. */
+async function stream(saver, port, id, parts) {
+    try {
+        for (const [part, { items }] of parts.entries()) {
+            for (let at = 0; at < items.length; at += ITEMS_PER_BOUNDARY) {
+                await turnBoundary();
+                if (saver.port !== port)
+                    return;
+                port.postMessage({ id, part, items: items.slice(at, at + ITEMS_PER_BOUNDARY) });
+            }
+        }
+    }
+    catch (error) {
+        if (saver.port === port)
+            port.postMessage({ id, failure: saveFailure(error) });
+    }
+}
+export function save(file, name, input) {
+    const fileKey = databaseFileName(file);
+    const saver = savers.get(fileKey);
+    if (!saver)
+        return Promise.reject(new Error(`the ground database ${JSON.stringify(file)} has no saver`));
+    if (!saver.worker)
+        spawn(fileKey, saver);
+    const id = nextId++;
+    const posted = performance.now();
+    const saved = new Promise((resolve, reject) => {
+        saver.pending.set(id, { name, posted, resolve: resolve, reject });
+    });
+    const port = saver.port, { head, parts } = partitioned(input);
+    try {
+        port.postMessage({ id, name, input: head,
+            parts: parts.map(({ path, items }) => ({ path, length: items.length })) });
+    }
+    catch (error) {
+        saver.pending.delete(id);
+        return Promise.reject(error);
+    }
+    port.ref();
+    saver.last = saved.then(() => { }, () => { });
+    if (parts.length)
+        void stream(saver, port, id, parts);
+    return saved;
+}
+/** Settles once every save posted before the call has settled. */
+export function saved(file) {
+    return savers.get(databaseFileName(file))?.last ?? Promise.resolve();
+}
+/** The settings the saver's commits run under, read back on its connection. */
+export function groundSaveDurability(file) {
+    const saver = savers.get(databaseFileName(file));
+    return saver ? saver.durability : Promise.reject(new Error(`the ground database ${JSON.stringify(file)} has no saver`));
+}
+//# sourceMappingURL=ground-saver.js.map

package/dist/ground-saver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-saver.js","sourceRoot":"","sources":["../src/ground-saver.ts"],"names":[],"mappings":"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"}

package/dist/ground-store.d.ts

@@ -0,0 +1,84 @@
+import type Database from "better-sqlite3";
+import type { RepositoryObservationPair } from "./git-repository-host.js";
+import type { LocalEntityRecord } from "@amalgm/live";
+import { type SharingWrite } from "./sharing-admission.js";
+import { GroundBasis, type GroundInventory, type GroundSnapshotReader, type GroundTransition, type GroundObservation } from "./ground-basis.js";
+import { type GroundRow } from "./ground-row.js";
+export type { GroundInventory } from "./ground-basis.js";
+export type { GroundTransition } from "./ground-basis.js";
+/** A saver thread's connection (ground-saver-worker.ts). */
+export declare function certifyGroundSaver(database: Database.Database): void;
+/** One owner per SQLite connection, including callers sharing Apply's handle. */
+export declare function groundStore(database: Database.Database): GroundStore;
+/** Optional phase evidence; counts describe this batch, not an outer commit. */
+export interface GroundWriteEvidence {
+    readonly nested: boolean;
+    readonly transactionEntryMs: number;
+    readonly callbackMs: number;
+    readonly projectionMs: number;
+    readonly revisionMs: number;
+    readonly transactionFinishMs: number;
+    readonly rowsRead: number;
+    readonly upserts: number;
+    readonly removals: number;
+    readonly revisionWrites: number;
+    readonly verificationOnlyRows: number;
+    readonly physicalRows: number;
+    readonly logicalRows: number;
+}
+export interface GroundWriter {
+    /** Read-only, before acceptance: whether this basis's facts are unchanged
+     * now. It authorizes nothing; an unchanged answer lets this writer's one
+     * acceptance of those facts stand on it instead of reading them again. */
+    compareBasis(basis: GroundBasis): boolean;
+    /** Must precede all projection writes. False means re-observe; it never
+     * grants permission to overwrite a target absent from the original basis. */
+    acceptBasis(basis: GroundBasis): boolean;
+    /** Reads inside a write batch serve that operation, never a Detect read basis. */
+    get(inventory: GroundInventory, uuid: string): GroundRow | undefined;
+    /** Declare the actual repository capture whose existing source closer was
+     * included in this Record admission. A serialized stamp alone grants nothing.
+     * Its proof stays with the caller, who closed it before this write. */
+    observeRepository(pair: Omit<RepositoryObservationPair, "proof">): void;
+    replace(inventory: GroundInventory, rows: readonly GroundRow[], removals?: readonly string[], sharing?: SharingWrite): void;
+    update(inventory: GroundInventory, uuid: string, fields: Partial<Omit<GroundRow, "uuid">>, sharing?: SharingWrite): boolean;
+    remove(inventory: GroundInventory, uuid: string): boolean;
+    /** After all projection writes, insert and attach the exact new Outbox admission to B.
+     * Further sharing writes in this batch are forbidden. */
+    admitSharing(record: LocalEntityRecord): string;
+}
+declare class GroundStore {
+    #private;
+    constructor(database: Database.Database);
+    readSnapshot<T>(operation: (reader: GroundSnapshotReader) => T): {
+        value: T;
+        basis: GroundBasis;
+    };
+    observe(): GroundObservation;
+    /** Exact address subtree for an existing operation, not a retained Detect
+     * proof. Callers needing later admission must capture and validate a basis. */
+    rowsUnder(inventory: GroundInventory, rootUUID: string, relativePath: string): readonly GroundRow[];
+    /** Joins an existing SQLite transaction through a savepoint when necessary.
+     * A failed batch restores all rows; its writer cannot escape its lifetime. */
+    write<T>(operation: (writer: GroundWriter) => T): T;
+    /** Measurement is returned as data. Caller code never runs between the
+     * completed transaction and this owner's report of success. */
+    writeMeasured<T>(operation: (writer: GroundWriter) => T): {
+        value: T;
+        evidence: GroundWriteEvidence;
+    };
+    /** Passive examination evidence for one completed outer commit. Originals
+     * are captured by the writer before mutation; no later read may renew them.
+     * A savepoint cannot supply an honest committed receipt, except a saver's
+     * save: its batch commits all of it or answers none of it. */
+    writeObserved<T>(operation: (writer: GroundWriter) => T): {
+        value: T;
+        changes: readonly GroundTransition[];
+        activated: readonly string[];
+        evidence: GroundWriteEvidence;
+    };
+    /** Its one visible row. A UUID visible in two roots is a fault no write
+     * may build on. */
+    private visibleRow;
+    private performWrite;
+}