@openlfcp/client 0.1.0-rc.1

package/dist/checkpoint.d.ts

@@ -0,0 +1,31 @@
+import type { LfcpStorage, ProfileCheckpoint, StorageWrite } from "@openlfcp/storage";
+/**
+ * Persisting a Data Profile's local state (LFCP-036): an explicit,
+ * caller-driven debounce. The sync engine calls noteChange() after merges
+ * and local writes, and maybeFlush(now) on its own schedule; nothing here
+ * keeps timers. A local write can carry the checkpoint in its own atomic
+ * batch instead (write(), e.g. as createQueuedDataUnit's `also`).
+ */
+/** Anything that can describe its persistent state (e.g. SharedObjectsDataProfile). */
+export interface CheckpointSource {
+    checkpoint(): ProfileCheckpoint;
+}
+export declare class ProfileCheckpointer {
+    #private;
+    constructor(storage: Pick<LfcpStorage, "commit">, source: CheckpointSource, options: {
+        readonly minIntervalMs: number;
+    });
+    /** The profile state changed since the last checkpoint. */
+    noteChange(): void;
+    get dirty(): boolean;
+    /** Writes a checkpoint if something changed and `minIntervalMs` passed since the last one. */
+    maybeFlush(nowMs: number): Promise<boolean>;
+    /** Writes a checkpoint now (e.g. before closing). */
+    flush(nowMs: number): Promise<void>;
+    /**
+     * The checkpoint as a write for another atomic batch. The state counts as
+     * persisted once that batch commits; call it as the batch is built.
+     */
+    write(): StorageWrite;
+}
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.js

@@ -0,0 +1,50 @@
+export class ProfileCheckpointer {
+    #storage;
+    #source;
+    #minIntervalMs;
+    #dirty = false;
+    #lastFlushMs = null;
+    constructor(storage, source, options) {
+        this.#storage = storage;
+        this.#source = source;
+        this.#minIntervalMs = options.minIntervalMs;
+    }
+    /** The profile state changed since the last checkpoint. */
+    noteChange() {
+        this.#dirty = true;
+    }
+    get dirty() {
+        return this.#dirty;
+    }
+    /** Writes a checkpoint if something changed and `minIntervalMs` passed since the last one. */
+    async maybeFlush(nowMs) {
+        if (!this.#dirty)
+            return false;
+        if (this.#lastFlushMs !== null && nowMs - this.#lastFlushMs < this.#minIntervalMs)
+            return false;
+        await this.flush(nowMs);
+        return true;
+    }
+    /** Writes a checkpoint now (e.g. before closing). */
+    async flush(nowMs) {
+        try {
+            const r = await this.#storage.commit([this.write()]);
+            if (!r.ok)
+                throw new Error(`the checkpoint was not stored: ${r.reason}`);
+        }
+        catch (e) {
+            this.#dirty = true;
+            throw e;
+        }
+        this.#lastFlushMs = nowMs;
+    }
+    /**
+     * The checkpoint as a write for another atomic batch. The state counts as
+     * persisted once that batch commits; call it as the batch is built.
+     */
+    write() {
+        this.#dirty = false;
+        return { op: "put-profile-checkpoint", checkpoint: this.#source.checkpoint() };
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/connection.d.ts

@@ -0,0 +1,87 @@
+import { type AnyMessage, type ClientConnectionState, type ClientHandshakeConfig, type ReadySession } from "@openlfcp/wire";
+/**
+ * One LFCP connection over a WebSocket (LFCP-WIRE-01 §30, §31, §34-§38,
+ * §63), for the client sync session (LFCP-039a). Portable: it uses the
+ * platform WebSocket (browsers, Electron/Obsidian and Node 24 all have
+ * `globalThis.WebSocket`), injectable for tests; no node:* imports.
+ *
+ * - Requests the `lfcp-1` subprotocol and drops a connection that did not
+ *   get it (§30, G-SM3).
+ * - Binary frames only, one LFCP message per WebSocket message; a text
+ *   frame or a message above the size limit in force is answered with
+ *   ERROR and closes the connection (§31).
+ * - The handshake is the pure one of LFCP-027 (startClientHandshake,
+ *   clientReceive); the §63 state follows clientConnectionTransition.
+ * - Heartbeat (§38): tick(now) sends PING when nothing was sent for the
+ *   READY interval and treats 3 intervals without any LFCP message as a
+ *   dead connection. Time comes from the caller; nothing here sets timers.
+ */
+/** The parts of the WHATWG WebSocket this client uses. */
+export interface WebSocketLike {
+    binaryType: string;
+    readonly protocol: string;
+    send(data: Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        readonly data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        readonly code: number;
+        readonly reason: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+/** Opens a WebSocket: `new WebSocket(url, protocols)` in production. */
+export type WebSocketFactory = (url: string, protocols: readonly string[]) => WebSocketLike;
+/** The platform WebSocket (globalThis.WebSocket); throws if the runtime has none. */
+export declare function platformWebSocket(): WebSocketFactory;
+/** §30: the only LFCP subprotocol. */
+export declare const LFCP_SUBPROTOCOL = "lfcp-1";
+export interface ConnectionEvents {
+    /** The §63 state changed. */
+    state(state: ClientConnectionState): void;
+    /** READY arrived: the session's parameters (§37). */
+    ready(ready: ReadySession): void;
+    /** A message after READY that the handshake does not consume. */
+    message(message: AnyMessage): void;
+    /** The connection is gone (DISCONNECTED); `reason` is for humans and never carries payloads. */
+    closed(reason: string): void;
+}
+export interface ConnectionOptions extends ClientHandshakeConfig {
+    readonly url: string;
+    readonly webSocket?: WebSocketFactory;
+    /** The current time in milliseconds (the caller's clock). */
+    readonly now: () => number;
+    /**
+     * LFCP-WIRE-01 §31: this client's own maximum message size (at least the
+     * 8 MiB default, which is also the default here). A larger value in
+     * READY never raises the receive limit above it.
+     */
+    readonly maxMessageBytes?: number;
+}
+export declare class LfcpConnection {
+    #private;
+    constructor(options: ConnectionOptions, events: ConnectionEvents);
+    get state(): ClientConnectionState;
+    /** The READY parameters while the session is READY. */
+    get ready(): ReadySession | null;
+    /** Opens the WebSocket (DISCONNECTED → CONNECTING). */
+    connect(): void;
+    /**
+     * Sends one message on a READY session. A message above READY's size
+     * limit is refused (MESSAGE_TOO_LARGE) and never sent.
+     */
+    send(message: AnyMessage): void;
+    /** Sends already encoded message bytes (e.g. an OutboundMessage) on a READY session. */
+    sendEncoded(bytes: Uint8Array): void;
+    /**
+     * Heartbeat (§38), driven by the caller's clock: a PING when nothing was
+     * sent for READY's interval, and a close when nothing arrived for three.
+     * Returns false when the connection was declared dead.
+     */
+    tick(now: number): boolean;
+    /** Closes the connection (normal closure). */
+    close(reason?: string): void;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.js

@@ -0,0 +1,210 @@
+import { LfcpError, secureRandom } from "@openlfcp/core";
+import { clientConnectionTransition, clientReceive, createMessage, DEFAULT_MAX_MESSAGE_BYTES, decodeFrame, ERROR_CODE, encodeMessage, startClientHandshake, } from "@openlfcp/wire";
+/** The platform WebSocket (globalThis.WebSocket); throws if the runtime has none. */
+export function platformWebSocket() {
+    const ctor = globalThis.WebSocket;
+    if (ctor === undefined)
+        throw new LfcpError("UNSUPPORTED_VALUE", "this runtime has no global WebSocket; inject a factory");
+    return (url, protocols) => new ctor(url, [...protocols]);
+}
+/** §30: the only LFCP subprotocol. */
+export const LFCP_SUBPROTOCOL = "lfcp-1";
+const BYTES = (data) => {
+    if (typeof data === "string")
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return undefined;
+};
+export class LfcpConnection {
+    #options;
+    #events;
+    #socket = null;
+    #state = "DISCONNECTED";
+    #session = null;
+    #ready = null;
+    #lastSent = 0;
+    #lastReceived = 0;
+    #closedReported = true;
+    constructor(options, events) {
+        this.#options = options;
+        this.#events = events;
+    }
+    get state() {
+        return this.#state;
+    }
+    /** The READY parameters while the session is READY. */
+    get ready() {
+        return this.#ready;
+    }
+    #move(event) {
+        const next = clientConnectionTransition(this.#state, event);
+        if (next === undefined)
+            return;
+        if (next !== this.#state) {
+            this.#state = next;
+            this.#events.state(next);
+        }
+    }
+    /** Opens the WebSocket (DISCONNECTED → CONNECTING). */
+    connect() {
+        if (this.#state !== "DISCONNECTED")
+            return;
+        this.#move("OPEN");
+        this.#closedReported = false;
+        this.#ready = null;
+        const socket = (this.#options.webSocket ?? platformWebSocket())(this.#options.url, [
+            LFCP_SUBPROTOCOL,
+        ]);
+        this.#socket = socket;
+        socket.binaryType = "arraybuffer";
+        socket.onopen = () => {
+            if (socket !== this.#socket)
+                return;
+            if (socket.protocol !== LFCP_SUBPROTOCOL) {
+                this.#drop("CONNECT_FAILED", `the server did not accept ${LFCP_SUBPROTOCOL}`);
+                return;
+            }
+            this.#move("CONNECTED");
+            const now = this.#options.now();
+            this.#lastReceived = now;
+            this.#apply(startClientHandshake(this.#options));
+        };
+        socket.onmessage = (ev) => {
+            if (socket === this.#socket)
+                this.#receive(ev.data);
+        };
+        socket.onclose = (ev) => {
+            if (socket === this.#socket)
+                this.#drop("CONNECTION_LOST", `the WebSocket closed (${ev.code})`, false);
+        };
+        socket.onerror = () => {
+            if (socket === this.#socket)
+                this.#drop("CONNECTION_LOST", "the WebSocket failed");
+        };
+    }
+    #apply(step) {
+        const before = this.#session?.phase;
+        this.#session = step.session;
+        for (const m of step.send)
+            this.#write(m);
+        if (step.close) {
+            this.#drop(before === "AUTHENTICATING" ? "AUTH_FAILURE" : "FATAL_ERROR", step.session.phase === "DISCONNECTED" ? step.session.reason : "handshake failure");
+            return;
+        }
+        if (step.session.phase === "AUTHENTICATING" && before === "NEGOTIATING")
+            this.#move("CHALLENGED");
+        if (step.session.phase === "READY" && before !== "READY") {
+            this.#ready = step.session.ready;
+            this.#move("READY_RECEIVED");
+            this.#events.ready(step.session.ready);
+        }
+        if (step.deliver !== undefined)
+            this.#events.message(step.deliver);
+    }
+    /** §31: the receive limit is the server's advertised maximum, never above this client's own. */
+    #limit() {
+        const local = Math.max(this.#options.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES, DEFAULT_MAX_MESSAGE_BYTES);
+        return this.#ready === null
+            ? DEFAULT_MAX_MESSAGE_BYTES
+            : Math.min(Number(this.#ready.maxMessageBytes), local);
+    }
+    #receive(data) {
+        const frame = BYTES(data);
+        if (frame === undefined)
+            return;
+        const result = decodeFrame(typeof frame === "string" ? { kind: "text", data: frame } : { kind: "binary", data: frame }, { maxMessageBytes: this.#limit() });
+        this.#lastReceived = this.#options.now();
+        if (result.kind === "error") {
+            this.#error(result.wireCode, result.reason);
+            if (result.closesConnection)
+                this.#drop("CONNECTION_LOST", `${result.wireCode}: ${result.reason}`);
+            return;
+        }
+        if (this.#session === null)
+            return;
+        this.#apply(clientReceive(this.#session, result.message, this.#options));
+    }
+    #error(code, diagnostic) {
+        this.#write(createMessage("ERROR", { code: ERROR_CODE[code], diagnostic }));
+    }
+    #write(message) {
+        const socket = this.#socket;
+        if (socket === null)
+            return;
+        socket.send(encodeMessage(message));
+        this.#lastSent = this.#options.now();
+    }
+    /**
+     * Sends one message on a READY session. A message above READY's size
+     * limit is refused (MESSAGE_TOO_LARGE) and never sent.
+     */
+    send(message) {
+        this.sendEncoded(encodeMessage(message));
+    }
+    /** Sends already encoded message bytes (e.g. an OutboundMessage) on a READY session. */
+    sendEncoded(bytes) {
+        if (this.#state !== "READY" || this.#socket === null)
+            throw new LfcpError("UNSUPPORTED_VALUE", "the connection is not READY");
+        if (bytes.length > this.#limit())
+            throw new LfcpError("MESSAGE_TOO_LARGE", `${bytes.length} bytes exceed the session limit ${this.#limit()}`);
+        this.#socket.send(bytes);
+        this.#lastSent = this.#options.now();
+    }
+    /**
+     * Heartbeat (§38), driven by the caller's clock: a PING when nothing was
+     * sent for READY's interval, and a close when nothing arrived for three.
+     * Returns false when the connection was declared dead.
+     */
+    tick(now) {
+        if (this.#state !== "READY" || this.#ready === null) {
+            // A handshake that stalls is as dead as an idle session.
+            if ((this.#state === "NEGOTIATING" || this.#state === "AUTHENTICATING") &&
+                now - this.#lastReceived > 30_000) {
+                this.#drop("CONNECTION_LOST", "the handshake timed out");
+                return false;
+            }
+            return true;
+        }
+        const h = Number(this.#ready.heartbeatMs);
+        if (h <= 0)
+            return true;
+        if (now - this.#lastReceived > 3 * h) {
+            this.#drop("CONNECTION_LOST", "no LFCP message for three heartbeat intervals (§38)");
+            return false;
+        }
+        if (now - this.#lastSent >= h)
+            this.#write(createMessage("PING", { payload: secureRandom(8) }));
+        return true;
+    }
+    /** Closes the connection (normal closure). */
+    close(reason = "closed by the client") {
+        this.#drop("CONNECTION_LOST", reason);
+    }
+    #drop(event, reason, closeSocket = true) {
+        const socket = this.#socket;
+        this.#socket = null;
+        this.#session = null;
+        this.#ready = null;
+        if (socket !== null) {
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            if (closeSocket)
+                try {
+                    socket.close(1000, reason.slice(0, 120));
+                }
+                catch {
+                    // already closing
+                }
+        }
+        this.#move(event);
+        if (this.#state !== "DISCONNECTED")
+            this.#move("CONNECTION_LOST");
+        if (!this.#closedReported) {
+            this.#closedReported = true;
+            this.#events.closed(reason);
+        }
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/data-unit.d.ts

@@ -0,0 +1,50 @@
+import { type ActorSequence, type DataEpoch, type DataUnitId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import type { ActorSequenceReservation, SequenceReuseGuard } from "@openlfcp/storage";
+import { type ControlView, type DataProfileCodec, type Signer } from "@openlfcp/wire";
+/**
+ * Creating a Data Unit (LFCP-WIRE-01 §8, §12, §26). The application value
+ * becomes plaintext through its Data Profile codec, then LFCP encrypts and
+ * signs it; only the resulting opaque bytes are ever sent.
+ */
+export interface CreateDataUnitOptions<T> {
+    /** The writer's validated view of the Resource's Control Chain. */
+    readonly view: ControlView;
+    /** The Control Head the unit is authorized at (usually the latest one). */
+    readonly controlHead: Uint8Array;
+    /** The actor: the writer's signing key and descriptor. */
+    readonly actor: Signer;
+    /** The DEK of the current Data Epoch at `controlHead`. */
+    readonly dek: ResourceDEK;
+    /**
+     * The only source of actor sequences (§8): durable in production
+     * (LFCP-034 to LFCP-036). A sequence is never passed in directly.
+     */
+    readonly sequences: ActorSequenceReservation;
+    /** Optional second line of defence against a sequence used twice in this process. */
+    readonly guard?: SequenceReuseGuard;
+    /**
+     * The actor's unit at the previous sequence (§26.2), or null for its
+     * first unit. A non-null value with sequence 1, or null after 1, is
+     * refused (the reserved sequence is then abandoned, never reused).
+     */
+    readonly previousUnitId: DataUnitId | null;
+    readonly profile: DataProfileCodec<T>;
+    readonly value: T;
+}
+export interface CreatedDataUnit {
+    /** The exact signed bytes: opaque, the only form sent to servers and peers. */
+    readonly bytes: Uint8Array;
+    readonly unitId: DataUnitId;
+    readonly seq: ActorSequence;
+    readonly epoch: DataEpoch;
+}
+/**
+ * Creates an encrypted, signed Data Unit. Before a sequence is reserved,
+ * it checks that the head is on the chain, that the profile is the
+ * Resource's, that the actor holds data/write at the head and that the DEK
+ * is the one committed for the head's current epoch; then it reserves the
+ * next sequence and seals the unit (sealDataUnit).
+ */
+export declare function createDataUnit<T>(options: CreateDataUnitOptions<T>): Promise<CreatedDataUnit>;
+//# sourceMappingURL=data-unit.d.ts.map

package/dist/data-unit.js

@@ -0,0 +1,39 @@
+import { bytesEqual, LfcpError, } from "@openlfcp/core";
+import { dekCommitment } from "@openlfcp/crypto";
+import { ABILITY, hasAbility, sealDataUnit, } from "@openlfcp/wire";
+/**
+ * Creates an encrypted, signed Data Unit. Before a sequence is reserved,
+ * it checks that the head is on the chain, that the profile is the
+ * Resource's, that the actor holds data/write at the head and that the DEK
+ * is the one committed for the head's current epoch; then it reserves the
+ * next sequence and seals the unit (sealDataUnit).
+ */
+export async function createDataUnit(options) {
+    const atHead = options.view.stateAt(options.controlHead);
+    if (atHead === undefined)
+        throw new LfcpError("MISSING_DEPENDENCY", "the Control Head is not on the validated chain");
+    if (options.profile.dataProfile !== atHead.dataProfile)
+        throw new LfcpError("DATA_PROFILE_MISMATCH", `the profile codec is for ${options.profile.dataProfile}, the Resource uses ${atHead.dataProfile}`);
+    const actor = options.actor.descriptor.principalId;
+    if (!hasAbility(atHead, actor, ABILITY.DATA_WRITE))
+        throw new LfcpError("AUTHORIZATION_FAILED", "the actor does not hold data/write at the Control Head (§26.3)");
+    const epoch = atHead.epoch.epoch;
+    if (!bytesEqual(dekCommitment(atHead.resourceId, epoch, options.dek), atHead.epoch.dekCommitment))
+        throw new LfcpError("DEK_COMMITMENT_MISMATCH", `the DEK is not the one committed for epoch ${epoch} at the Control Head`);
+    const plaintext = options.profile.encode(options.value);
+    const seq = await options.sequences.reserveNext(atHead.resourceId, actor);
+    options.guard?.claim(atHead.resourceId, actor, seq);
+    if ((seq === 1n) !== (options.previousUnitId === null))
+        throw new LfcpError("INVALID_STRUCTURE", seq === 1n
+            ? "the actor's first unit (sequence 1) must have a null previous unit (§26.2)"
+            : `sequence ${seq} needs the actor's unit at sequence ${seq - 1n} as its previous unit (§26.2)`);
+    const sealed = sealDataUnit({
+        resourceId: atHead.resourceId,
+        dataEpoch: epoch,
+        actorSeq: seq,
+        prevDataUnitId: options.previousUnitId,
+        controlHead: atHead.head,
+    }, plaintext, options.dek, options.actor);
+    return Object.freeze({ bytes: sealed.bytes, unitId: sealed.unitId, seq, epoch });
+}
+//# sourceMappingURL=data-unit.js.map

package/dist/engine-guard.d.ts

@@ -0,0 +1,58 @@
+import { type ResourceId } from "@openlfcp/core";
+import type { LfcpStorage } from "@openlfcp/storage";
+/**
+ * The crash-loop breaker: received content that traps the profile engine
+ * (e.g. Automerge's wasm module, which then stays terminated for the whole
+ * process) must not crash every restart again.
+ *
+ * Before an engine call on received content (applying Data Units, loading
+ * a Snapshot), the items it covers are recorded durably
+ * (`applying:<scope>:<resource>`, one record per scope: "units" for the
+ * applier, "snapshots" for Snapshot loads); the record is removed when the call returns or
+ * throws an ordinary error. A record found later means the process died
+ * inside the call: a trap, or anything else (killed, power loss, a bug in
+ * our own code).
+ *
+ * Blame needs two such crashes on the item alone:
+ * - after a crash, every item of the leftover record becomes a suspect
+ *   (`suspect:<resource>:<item>` = 1) and is applied alone from then on,
+ *   never in a batch, so an innocent batch member is cleared by its own
+ *   successful apply;
+ * - a suspect that crashes again alone (count 2) is quarantined locally:
+ *   never given to the engine again, here or on later delivery, and
+ *   surfaced. The mark stays, so a re-delivered copy is refused too.
+ *
+ * So a single crash mid-apply (the normal crash-restart path) only costs a
+ * retry; a unit is blamed only when it crashed the engine twice by itself.
+ * A poison unit costs at most three process restarts (batch, alone, then
+ * quarantined at the next start).
+ */
+/** A thrown value that looks like an engine trap (WebAssembly RuntimeError, a terminated module). */
+export declare function isEngineTrap(e: unknown): boolean;
+/** An item the engine processes: a Data Unit or a Snapshot, by ID. */
+export type EngineItem = `unit:${string}` | `snapshot:${string}`;
+export declare const unitItem: (id: Uint8Array) => EngineItem;
+export declare const snapshotItem: (id: Uint8Array) => EngineItem;
+/** How often an item crashed the engine: 1 suspect (applied alone), 2+ quarantined. */
+export type Suspicion = 0 | 1 | 2;
+export declare class EngineGuard {
+    #private;
+    constructor(storage: Pick<LfcpStorage, "localMarks" | "commit">, scope: "units" | "snapshots");
+    /**
+     * Once per Resource and guard: turns a leftover `applying` record into
+     * suspects (counting one more crash for each), and loads the suspects.
+     * Returns the items quarantined by this crash (count reached 2).
+     */
+    recover(resource: ResourceId): Promise<EngineItem[]>;
+    /** How often `item` crashed the engine (after recover()). */
+    suspicion(resource: ResourceId, item: EngineItem): Suspicion;
+    /**
+     * Runs `call` (the engine work on `items`) with the durable record in
+     * place. Returns normally or with an ordinary error: the record is
+     * removed, and suspects of count 1 that went through are cleared. On a
+     * trap the record stays (the module is dead; the process must restart)
+     * and the trap is rethrown.
+     */
+    run<T>(resource: ResourceId, items: readonly EngineItem[], call: () => T | Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=engine-guard.d.ts.map

package/dist/engine-guard.js

@@ -0,0 +1,148 @@
+import { toHex } from "@openlfcp/core";
+/**
+ * The crash-loop breaker: received content that traps the profile engine
+ * (e.g. Automerge's wasm module, which then stays terminated for the whole
+ * process) must not crash every restart again.
+ *
+ * Before an engine call on received content (applying Data Units, loading
+ * a Snapshot), the items it covers are recorded durably
+ * (`applying:<scope>:<resource>`, one record per scope: "units" for the
+ * applier, "snapshots" for Snapshot loads); the record is removed when the call returns or
+ * throws an ordinary error. A record found later means the process died
+ * inside the call: a trap, or anything else (killed, power loss, a bug in
+ * our own code).
+ *
+ * Blame needs two such crashes on the item alone:
+ * - after a crash, every item of the leftover record becomes a suspect
+ *   (`suspect:<resource>:<item>` = 1) and is applied alone from then on,
+ *   never in a batch, so an innocent batch member is cleared by its own
+ *   successful apply;
+ * - a suspect that crashes again alone (count 2) is quarantined locally:
+ *   never given to the engine again, here or on later delivery, and
+ *   surfaced. The mark stays, so a re-delivered copy is refused too.
+ *
+ * So a single crash mid-apply (the normal crash-restart path) only costs a
+ * retry; a unit is blamed only when it crashed the engine twice by itself.
+ * A poison unit costs at most three process restarts (batch, alone, then
+ * quarantined at the next start).
+ */
+/** A thrown value that looks like an engine trap (WebAssembly RuntimeError, a terminated module). */
+export function isEngineTrap(e) {
+    const wasm = globalThis
+        .WebAssembly?.RuntimeError;
+    if (wasm !== undefined && e instanceof wasm)
+        return true;
+    if (!(e instanceof Error))
+        return false;
+    return (e.name === "RuntimeError" ||
+        /\b(module|instance)\b.*\bterminated\b|\bunreachable\b executed|\bwasm trap\b/i.test(e.message));
+}
+export const unitItem = (id) => `unit:${toHex(id)}`;
+export const snapshotItem = (id) => `snapshot:${toHex(id)}`;
+export class EngineGuard {
+    #storage;
+    #scope;
+    #suspects = new Map();
+    #recovering = new Map();
+    constructor(storage, scope) {
+        this.#storage = storage;
+        this.#scope = scope;
+    }
+    #applying(R) {
+        return `applying:${this.#scope}:${R}`;
+    }
+    /**
+     * Once per Resource and guard: turns a leftover `applying` record into
+     * suspects (counting one more crash for each), and loads the suspects.
+     * Returns the items quarantined by this crash (count reached 2).
+     */
+    recover(resource) {
+        const key = toHex(resource);
+        let running = this.#recovering.get(key);
+        if (running === undefined) {
+            running = this.#recover(key);
+            this.#recovering.set(key, running);
+        }
+        return running;
+    }
+    async #recover(R) {
+        const counts = new Map();
+        for (const m of await this.#storage.localMarks.list(`suspect:${R}:`))
+            counts.set(m.key.slice(`suspect:${R}:`.length), Number(m.value));
+        const leftover = await this.#storage.localMarks.get(this.#applying(R));
+        const quarantined = [];
+        if (leftover !== undefined) {
+            const items = JSON.parse(leftover);
+            for (const item of items) {
+                const n = (counts.get(item) ?? 0) + 1;
+                counts.set(item, n);
+                if (n === 2)
+                    quarantined.push(item);
+            }
+            const r = await this.#storage.commit([
+                ...items.map((item) => ({
+                    op: "put-local-mark",
+                    key: `suspect:${R}:${item}`,
+                    value: String(counts.get(item)),
+                })),
+                { op: "put-local-mark", key: this.#applying(R), value: null },
+            ]);
+            if (!r.ok)
+                throw new Error(`the crash record was not stored: ${r.reason}`);
+        }
+        this.#suspects.set(R, counts);
+        return quarantined;
+    }
+    /** How often `item` crashed the engine (after recover()). */
+    suspicion(resource, item) {
+        const n = this.#suspects.get(toHex(resource))?.get(item) ?? 0;
+        return n >= 2 ? 2 : n === 1 ? 1 : 0;
+    }
+    /**
+     * Runs `call` (the engine work on `items`) with the durable record in
+     * place. Returns normally or with an ordinary error: the record is
+     * removed, and suspects of count 1 that went through are cleared. On a
+     * trap the record stays (the module is dead; the process must restart)
+     * and the trap is rethrown.
+     */
+    async run(resource, items, call) {
+        const R = toHex(resource);
+        if (items.length === 0)
+            return call();
+        await this.#mark([
+            { op: "put-local-mark", key: this.#applying(R), value: JSON.stringify(items) },
+        ]);
+        let result;
+        try {
+            result = await call();
+        }
+        catch (e) {
+            if (isEngineTrap(e))
+                throw e;
+            await this.#settled(R, items, false);
+            throw e;
+        }
+        await this.#settled(R, items, true);
+        return result;
+    }
+    async #settled(R, items, passed) {
+        const counts = this.#suspects.get(R);
+        const cleared = passed ? items.filter((item) => counts?.get(item) === 1) : [];
+        for (const item of cleared)
+            counts?.delete(item);
+        await this.#mark([
+            { op: "put-local-mark", key: this.#applying(R), value: null },
+            ...cleared.map((item) => ({
+                op: "put-local-mark",
+                key: `suspect:${R}:${item}`,
+                value: null,
+            })),
+        ]);
+    }
+    async #mark(writes) {
+        const r = await this.#storage.commit(writes);
+        if (!r.ok)
+            throw new Error(`the apply record was not stored: ${r.reason}`);
+    }
+}
+//# sourceMappingURL=engine-guard.js.map