@deepstrike/wasm 0.2.49 → 0.2.51

package/dist/runtime/kernel-journal.js

@@ -0,0 +1,681 @@
+/**
+ * `KernelJournal` — the durable transaction capability of the Canonical Kernel ABI (spec §9.1).
+ *
+ * The interface here is field-for-field the Node SDK's `node/src/runtime/kernel-journal.ts`, which is
+ * the authoritative shape for all four SDKs. Three rules give this file its shape:
+ *
+ * 1. **Records are opaque.** core owns canonical serialization and hashing
+ *    (`KernelRecord::record_bytes()` / `record_digest()` / `expected_head()`). The host stores the
+ *    bytes verbatim and indexes them by the digest core handed it. A journal that re-serializes a
+ *    record to recompute its hash would make "the host recomputed and disagreed" a reachable state;
+ *    it is not one here.
+ * 2. **CAS is a storage-layer primitive, not a read-compare-write sequence.** §9.1 requires a real
+ *    atomic operation (file lock / atomic-publish chained naming / conditional database update).
+ *    `InMemoryKernelJournal` is atomic only within one process and says so in its own type;
+ *    `DriverKernelJournal` is as atomic as the {@link JournalStorageDriver} the host injects.
+ * 3. **The journal's sequence space is `step_seq`** — the operation's record-chain position — and is
+ *    completely independent of `SessionLog`'s business event `seq`. Pruning a journal prefix can
+ *    never punch a hole in business event numbering (spec Task 8b, criterion 4).
+ *
+ * Failures are typed so a caller can tell "retry after rebuild" from "this storage is broken" from
+ * "someone handed me a corrupt chain" — a durable-step wrapper must never publish effects on any of
+ * them, and must never collapse them into one opaque `Error`.
+ *
+ * **Why this SDK has no file backend.** The WASM SDK targets browsers, Cloudflare Workers and Deno
+ * Deploy; it imports no host filesystem anywhere, so Node's `FileKernelJournal` (POSIX `link(2)` as
+ * the atomicity primitive) has nothing to stand on. The durable backend is therefore *injected*:
+ * the host supplies a {@link JournalStorageDriver} over whatever conditional-write primitive its
+ * platform actually has (R2/S3 `If-None-Match`, Durable Object storage, KV compare-and-set, OPFS),
+ * and {@link DriverKernelJournal} supplies the chain, checkpoint and prune protocol on top of it.
+ */
+/** Chain positions at or above this bound are rejected (parity with Node/Python/Rust). */
+export const MAX_CHAIN_POSITION = 1_000_000_000_000;
+/* ------------------------------------------------------------------ *
+ * Errors
+ * ------------------------------------------------------------------ */
+/**
+ * The CAS precondition did not hold: the journal head (or checkpoint pointer) moved.
+ *
+ * Retryable — the protocol response is `abort(token)` → re-read head → rebuild → replay the input
+ * (spec §8.3, row "CAS conflict").
+ */
+export class JournalCasConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JournalCasConflictError";
+    }
+}
+/**
+ * The journal contents contradict themselves or the caller's claim: a broken digest chain, a
+ * `step_seq` that does not follow its predecessor, a checkpoint whose `covered_head` does not match
+ * the record at its `through_step_seq`. Never retryable — retrying replays the same contradiction.
+ */
+export class JournalIntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "JournalIntegrityError";
+    }
+}
+/**
+ * The storage layer failed (quota exceeded, network error, driver rejected the write). Distinct from
+ * both of the above: the journal state is *unknown*, not known-conflicting and not known-corrupt.
+ */
+export class JournalIoError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "JournalIoError";
+    }
+}
+/* ------------------------------------------------------------------ *
+ * Shared validation
+ * ------------------------------------------------------------------ */
+function validateChainPosition(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value >= MAX_CHAIN_POSITION) {
+        throw new JournalIntegrityError(`${label} must be a non-negative integer below ${MAX_CHAIN_POSITION}`);
+    }
+}
+function validateRecord(record) {
+    validateChainPosition(record.step_seq, "journal record step_seq");
+    if (!record.record_digest)
+        throw new JournalIntegrityError("journal record requires a record_digest");
+    if (!(record.record_bytes instanceof Uint8Array)) {
+        throw new JournalIntegrityError("journal record requires opaque record_bytes");
+    }
+}
+function validateCandidate(checkpoint) {
+    if (!checkpoint.checkpoint_id)
+        throw new JournalIntegrityError("checkpoint requires a checkpoint_id");
+    validateChainPosition(checkpoint.through_step_seq, "checkpoint through_step_seq");
+    if (!checkpoint.state_digest)
+        throw new JournalIntegrityError("checkpoint requires a state_digest");
+    if (!(checkpoint.checkpoint_bytes instanceof Uint8Array)) {
+        throw new JournalIntegrityError("checkpoint requires opaque checkpoint_bytes");
+    }
+}
+/**
+ * Check the CAS precondition against the observed head, and the chain position that follows from it.
+ * Shared by both implementations so their conflict/integrity taxonomy cannot drift apart.
+ */
+function checkAppendPrecondition(head, expectedHead, record) {
+    if (expectedHead === undefined) {
+        if (head) {
+            throw new JournalCasConflictError("journal genesis append requires an empty chain, but the operation already has a head");
+        }
+        if (record.step_seq !== 0) {
+            throw new JournalIntegrityError("journal genesis record must have step_seq 0");
+        }
+        return;
+    }
+    if (!head) {
+        throw new JournalCasConflictError("journal compare-and-append expected a head, but the chain is empty");
+    }
+    if (head.record_digest !== expectedHead) {
+        throw new JournalCasConflictError("journal head changed before compare-and-append");
+    }
+    if (record.step_seq !== head.step_seq + 1) {
+        throw new JournalIntegrityError(`journal record step_seq ${record.step_seq} does not follow head step_seq ${head.step_seq}`);
+    }
+}
+/** Verify one contiguous run of entries links head-to-tail. */
+function verifyChain(entries) {
+    for (let i = 1; i < entries.length; i++) {
+        const previous = entries[i - 1];
+        const entry = entries[i];
+        if (entry.step_seq !== previous.step_seq + 1) {
+            throw new JournalIntegrityError(`journal chain has a gap: step_seq ${entry.step_seq} follows ${previous.step_seq}`);
+        }
+        if (entry.previous_record_digest !== previous.record_digest) {
+            throw new JournalIntegrityError("journal chain digest linkage is not continuous");
+        }
+    }
+}
+function checkCheckpointPrecondition(latest, previousCheckpointId, checkpoint) {
+    if (previousCheckpointId === undefined) {
+        if (latest) {
+            throw new JournalCasConflictError("checkpoint install without a predecessor requires an empty checkpoint pointer");
+        }
+        return;
+    }
+    if (!latest) {
+        throw new JournalCasConflictError("checkpoint install named a predecessor, but none is installed");
+    }
+    if (latest.checkpoint_id !== previousCheckpointId) {
+        throw new JournalCasConflictError("checkpoint pointer changed before compare-and-install");
+    }
+    if (checkpoint.through_step_seq < latest.through_step_seq) {
+        throw new JournalIntegrityError("checkpoint pointer must advance monotonically");
+    }
+}
+/**
+ * §9.1: the store verifies that `covered_head` is the record digest at `through_step_seq`. It does
+ * NOT check that this is still the current head — §22.14 rejects that, since it would serialise
+ * checkpointing against ordinary transitions.
+ */
+function verifyCoveredHead(covered, pruned, coveredHead, throughStepSeq) {
+    if (covered) {
+        if (covered.record_digest !== coveredHead) {
+            throw new JournalIntegrityError("checkpoint covered_head does not match the record at its through_step_seq");
+        }
+        return;
+    }
+    if (pruned && pruned.through_step_seq === throughStepSeq && pruned.covered_head === coveredHead)
+        return;
+    throw new JournalIntegrityError("checkpoint through_step_seq names no retained record");
+}
+/**
+ * **Single-process dev/test implementation.**
+ *
+ * CAS is genuinely atomic here — every check-then-mutate below runs to completion without an
+ * intervening `await`, so no other task can interleave on a single-threaded runtime — but that
+ * atomicity ends at the process boundary. Two workers/isolates sharing "the same" journal do not
+ * exist: each has its own `Map`. Production hosts must supply a `KernelJournal` whose CAS is a real
+ * storage-layer primitive (spec §9.1); {@link DriverKernelJournal} over a durable
+ * {@link JournalStorageDriver} is the reference for that.
+ */
+export class InMemoryKernelJournal {
+    operations = new Map();
+    state(operationId) {
+        let state = this.operations.get(operationId);
+        if (!state) {
+            state = { records: [], checkpoints: [] };
+            this.operations.set(operationId, state);
+        }
+        return state;
+    }
+    headOf(state) {
+        const last = state.records.at(-1);
+        if (last)
+            return { step_seq: last.step_seq, record_digest: last.record_digest };
+        if (state.pruned) {
+            return { step_seq: state.pruned.through_step_seq, record_digest: state.pruned.covered_head };
+        }
+        return undefined;
+    }
+    async compareAndAppend(operationId, expectedHead, record) {
+        validateRecord(record);
+        // Atomic region: no `await` from here to the push.
+        const state = this.state(operationId);
+        checkAppendPrecondition(this.headOf(state), expectedHead, record);
+        state.records.push({
+            step_seq: record.step_seq,
+            record_digest: record.record_digest,
+            record_bytes: Uint8Array.from(record.record_bytes),
+            ...(expectedHead === undefined ? {} : { previous_record_digest: expectedHead }),
+        });
+        return { step_seq: record.step_seq, record_digest: record.record_digest };
+    }
+    async head(operationId) {
+        const state = this.operations.get(operationId);
+        return state ? this.headOf(state) : undefined;
+    }
+    async readFrom(operationId, fromStepSeq = 0) {
+        const records = this.operations.get(operationId)?.records ?? [];
+        // Retained records are dense and ordered, so the cursor is an index — not a scan. Callers hit
+        // this once per durable step to fetch the head; a filter here would make a run quadratic.
+        const base = records[0]?.step_seq ?? 0;
+        const entries = records.slice(Math.max(0, fromStepSeq - base));
+        verifyChain(entries);
+        return entries.map(entry => ({ ...entry, record_bytes: Uint8Array.from(entry.record_bytes) }));
+    }
+    async recordsAfter(operationId, afterHead) {
+        if (afterHead === undefined)
+            return this.readFrom(operationId, 0);
+        const state = this.operations.get(operationId);
+        const anchor = state?.records.find(entry => entry.record_digest === afterHead);
+        if (anchor)
+            return this.readFrom(operationId, anchor.step_seq + 1);
+        if (state?.pruned && state.pruned.covered_head === afterHead) {
+            return this.readFrom(operationId, state.pruned.through_step_seq + 1);
+        }
+        throw new JournalIntegrityError("journal cursor digest names no retained record");
+    }
+    async compareAndInstallCheckpoint(operationId, previousCheckpointId, coveredHead, checkpoint) {
+        validateCandidate(checkpoint);
+        // Atomic region: no `await` from here to the push.
+        const state = this.state(operationId);
+        const latest = state.checkpoints.at(-1);
+        checkCheckpointPrecondition(latest, previousCheckpointId, checkpoint);
+        verifyCoveredHead(state.records.find(entry => entry.step_seq === checkpoint.through_step_seq), state.pruned, coveredHead, checkpoint.through_step_seq);
+        const installed = {
+            ...checkpoint,
+            checkpoint_bytes: Uint8Array.from(checkpoint.checkpoint_bytes),
+            ordinal: latest ? latest.ordinal + 1 : 0,
+            covered_head: coveredHead,
+            ...(previousCheckpointId === undefined ? {} : { previous_checkpoint_id: previousCheckpointId }),
+            acknowledged: false,
+        };
+        state.checkpoints.push(installed);
+        return { ...installed, checkpoint_bytes: Uint8Array.from(installed.checkpoint_bytes) };
+    }
+    async latestCheckpoint(operationId) {
+        const latest = this.operations.get(operationId)?.checkpoints.at(-1);
+        return latest ? { ...latest, checkpoint_bytes: Uint8Array.from(latest.checkpoint_bytes) } : undefined;
+    }
+    async ackCheckpoint(operationId, checkpointId) {
+        const installed = this.operations
+            .get(operationId)
+            ?.checkpoints.find(entry => entry.checkpoint_id === checkpointId);
+        if (!installed)
+            throw new JournalIntegrityError("cannot acknowledge an uninstalled checkpoint");
+        installed.acknowledged = true;
+        return { ...installed, checkpoint_bytes: Uint8Array.from(installed.checkpoint_bytes) };
+    }
+    async pruneAckedPrefix(operationId) {
+        const state = this.operations.get(operationId);
+        const acked = [...(state?.checkpoints ?? [])].reverse().find(entry => entry.acknowledged);
+        if (!state || !acked) {
+            return { pruned_through_step_seq: state?.pruned?.through_step_seq ?? -1, pruned_count: 0 };
+        }
+        const before = state.records.length;
+        state.records = state.records.filter(entry => entry.step_seq > acked.through_step_seq);
+        if (!state.pruned || state.pruned.through_step_seq < acked.through_step_seq) {
+            state.pruned = { through_step_seq: acked.through_step_seq, covered_head: acked.covered_head };
+        }
+        return {
+            pruned_through_step_seq: state.pruned.through_step_seq,
+            pruned_count: before - state.records.length,
+        };
+    }
+    async stageOutboundEnvelope(operationId, envelopeJson) {
+        if (!envelopeJson)
+            throw new JournalIntegrityError("outbound envelope must not be empty");
+        this.state(operationId).outboundEnvelope = envelopeJson;
+    }
+    async readOutboundEnvelope(operationId) {
+        return this.operations.get(operationId)?.outboundEnvelope;
+    }
+    async clearOutboundEnvelope(operationId) {
+        const state = this.operations.get(operationId);
+        if (state)
+            delete state.outboundEnvelope;
+    }
+}
+/**
+ * **Single-process reference driver.** Backed by one `Map`, so `createIfAbsent` is atomic in the
+ * only sense a single isolate can offer: the check and the insert run with no `await` between them,
+ * so no other task interleaves. It is a complete, spec-conformant driver *within one isolate* — use
+ * it for dev, tests, and ephemeral Workers; use a durable driver anywhere state must outlive the
+ * isolate or be shared with another one.
+ */
+export class InMemoryJournalDriver {
+    entries = new Map();
+    async createIfAbsent(key, bytes) {
+        // Atomic region: no `await` between the check and the insert.
+        if (this.entries.has(key))
+            return false;
+        this.entries.set(key, Uint8Array.from(bytes));
+        return true;
+    }
+    async read(key) {
+        const value = this.entries.get(key);
+        return value ? Uint8Array.from(value) : undefined;
+    }
+    async list(prefix) {
+        return [...this.entries.keys()].filter(key => key.startsWith(prefix));
+    }
+    async put(key, bytes) {
+        this.entries.set(key, Uint8Array.from(bytes));
+    }
+    async remove(key) {
+        this.entries.delete(key);
+    }
+}
+/* ------------------------------------------------------------------ *
+ * Driver-backed implementation
+ * ------------------------------------------------------------------ */
+const SEQ_DIGITS = 12;
+const RECORD_NAME = /^(\d{12})\.rec$/;
+const CHECKPOINT_NAME = /^(\d{12})\.ckpt$/;
+const ACK_NAME = /^(\d{12})\.ack$/;
+function pad(value) {
+    return String(value).padStart(SEQ_DIGITS, "0");
+}
+/** Injective encoding of an operation id into a key segment safe for path- and URL-shaped stores. */
+function safeSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, char => `~${char.charCodeAt(0).toString(16)}`);
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function toBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * **Durable reference implementation** of `KernelJournal` over a host-injected
+ * {@link JournalStorageDriver} (spec Task 8b) — the WASM SDK's counterpart to Node's
+ * `FileKernelJournal`.
+ *
+ * The atomicity primitive is `driver.createIfAbsent`. Content is published complete, under a name
+ * derived *only* from the CAS precondition, so a crash can never leave a half-written record and
+ * two racing writers can never land on different names.
+ *
+ * **Why a record's key is `<step_seq>.rec` and contains no digest.** The key *is* the collision
+ * domain. Two writers racing on the same head both compute the same next `step_seq`, so they
+ * contend for one key and exactly one wins. Folding a per-writer value (the new record's digest)
+ * into the key would give the racers *different* keys — both claims would succeed and the chain
+ * would fork. Only the predecessor-determined part of the identity may appear in the key.
+ *
+ * The pre-claim head check is not a TOCTOU hole: it can only *reject* an append the driver would
+ * have accepted (a stale `expectedHead` whose `step_seq` slot happens to be free), never accept one
+ * the driver would have rejected. Every acceptance is still decided by the atomic claim.
+ *
+ * Checkpoint installs use the same primitive on a separate ordinal space (`<ordinal>.ckpt`), so two
+ * writers installing on the same predecessor also contend for one key.
+ */
+export class DriverKernelJournal {
+    driver;
+    prefix;
+    constructor(driver, prefix = "kernel-journal") {
+        this.driver = driver;
+        this.prefix = prefix;
+    }
+    operationPrefix(operationId) {
+        return `${this.prefix}/${safeSegment(operationId)}`;
+    }
+    recordsPrefix(operationId) {
+        return `${this.operationPrefix(operationId)}/records/`;
+    }
+    checkpointsPrefix(operationId) {
+        return `${this.operationPrefix(operationId)}/checkpoints/`;
+    }
+    prunedKey(operationId) {
+        return `${this.operationPrefix(operationId)}/pruned`;
+    }
+    outboundKey(operationId) {
+        return `${this.operationPrefix(operationId)}/outbound`;
+    }
+    /** Every driver call funnels through these three so a driver fault is always a `JournalIoError`. */
+    async claim(key, payload) {
+        try {
+            return await this.driver.createIfAbsent(key, encoder.encode(JSON.stringify(payload)));
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not publish a durable record", { cause: err });
+        }
+    }
+    async load(key) {
+        let bytes;
+        try {
+            bytes = await this.driver.read(key);
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not read from its storage driver", { cause: err });
+        }
+        return bytes === undefined ? undefined : decoder.decode(bytes);
+    }
+    async names(prefix) {
+        let keys;
+        try {
+            keys = await this.driver.list(prefix);
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not list its storage driver", { cause: err });
+        }
+        return keys.map(key => key.slice(prefix.length));
+    }
+    /** Sorted `step_seq` values of the retained records. Anything not matching the rule is residue. */
+    async recordSeqs(operationId) {
+        const seqs = [];
+        for (const name of await this.names(this.recordsPrefix(operationId))) {
+            const match = RECORD_NAME.exec(name);
+            if (match)
+                seqs.push(Number(match[1]));
+        }
+        return seqs.sort((a, b) => a - b);
+    }
+    async readRecord(operationId, stepSeq) {
+        const raw = await this.load(`${this.recordsPrefix(operationId)}${pad(stepSeq)}.rec`);
+        if (raw === undefined)
+            return undefined;
+        let persisted;
+        try {
+            persisted = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new JournalIntegrityError(`journal record ${pad(stepSeq)} is not readable: ${String(err)}`);
+        }
+        if (persisted.step_seq !== stepSeq) {
+            throw new JournalIntegrityError(`journal record ${pad(stepSeq)} disagrees with its own step_seq`);
+        }
+        return {
+            step_seq: persisted.step_seq,
+            record_digest: persisted.record_digest,
+            record_bytes: fromBase64(persisted.record_bytes),
+            ...(persisted.previous_record_digest === undefined
+                ? {}
+                : { previous_record_digest: persisted.previous_record_digest }),
+        };
+    }
+    async prunedAnchor(operationId) {
+        const raw = await this.load(this.prunedKey(operationId));
+        if (raw === undefined)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            throw new JournalIntegrityError(`journal pruned anchor is not readable: ${String(err)}`);
+        }
+    }
+    async head(operationId) {
+        const seqs = await this.recordSeqs(operationId);
+        const last = seqs.at(-1);
+        if (last !== undefined) {
+            const entry = await this.readRecord(operationId, last);
+            if (entry)
+                return { step_seq: entry.step_seq, record_digest: entry.record_digest };
+        }
+        const pruned = await this.prunedAnchor(operationId);
+        return pruned ? { step_seq: pruned.through_step_seq, record_digest: pruned.covered_head } : undefined;
+    }
+    async compareAndAppend(operationId, expectedHead, record) {
+        validateRecord(record);
+        checkAppendPrecondition(await this.head(operationId), expectedHead, record);
+        const persisted = {
+            step_seq: record.step_seq,
+            record_digest: record.record_digest,
+            ...(expectedHead === undefined ? {} : { previous_record_digest: expectedHead }),
+            record_bytes: toBase64(record.record_bytes),
+        };
+        const won = await this.claim(`${this.recordsPrefix(operationId)}${pad(record.step_seq)}.rec`, persisted);
+        if (!won) {
+            throw new JournalCasConflictError(`journal step_seq ${record.step_seq} was claimed by a concurrent writer`);
+        }
+        return { step_seq: record.step_seq, record_digest: record.record_digest };
+    }
+    async readFrom(operationId, fromStepSeq = 0) {
+        const entries = [];
+        for (const seq of await this.recordSeqs(operationId)) {
+            if (seq < fromStepSeq)
+                continue;
+            const entry = await this.readRecord(operationId, seq);
+            if (entry)
+                entries.push(entry);
+        }
+        verifyChain(entries);
+        return entries;
+    }
+    async recordsAfter(operationId, afterHead) {
+        if (afterHead === undefined)
+            return this.readFrom(operationId, 0);
+        for (const seq of await this.recordSeqs(operationId)) {
+            const entry = await this.readRecord(operationId, seq);
+            if (entry?.record_digest === afterHead)
+                return this.readFrom(operationId, seq + 1);
+        }
+        const pruned = await this.prunedAnchor(operationId);
+        if (pruned?.covered_head === afterHead)
+            return this.readFrom(operationId, pruned.through_step_seq + 1);
+        throw new JournalIntegrityError("journal cursor digest names no retained record");
+    }
+    /** Sorted ordinals of installed checkpoints. */
+    async checkpointOrdinals(operationId) {
+        const ordinals = [];
+        for (const name of await this.names(this.checkpointsPrefix(operationId))) {
+            const match = CHECKPOINT_NAME.exec(name);
+            if (match)
+                ordinals.push(Number(match[1]));
+        }
+        return ordinals.sort((a, b) => a - b);
+    }
+    async ackedOrdinals(operationId) {
+        const acked = new Set();
+        for (const name of await this.names(this.checkpointsPrefix(operationId))) {
+            const match = ACK_NAME.exec(name);
+            if (match)
+                acked.add(Number(match[1]));
+        }
+        return acked;
+    }
+    async readCheckpoint(operationId, ordinal, acked) {
+        const raw = await this.load(`${this.checkpointsPrefix(operationId)}${pad(ordinal)}.ckpt`);
+        if (raw === undefined)
+            return undefined;
+        let persisted;
+        try {
+            persisted = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new JournalIntegrityError(`checkpoint ${pad(ordinal)} is not readable: ${String(err)}`);
+        }
+        const acknowledged = (acked ?? (await this.ackedOrdinals(operationId))).has(ordinal);
+        return {
+            ordinal: persisted.ordinal,
+            checkpoint_id: persisted.checkpoint_id,
+            ...(persisted.previous_checkpoint_id === undefined
+                ? {}
+                : { previous_checkpoint_id: persisted.previous_checkpoint_id }),
+            covered_head: persisted.covered_head,
+            through_step_seq: persisted.through_step_seq,
+            state_digest: persisted.state_digest,
+            checkpoint_bytes: fromBase64(persisted.checkpoint_bytes),
+            acknowledged,
+        };
+    }
+    async latestCheckpoint(operationId) {
+        const ordinals = await this.checkpointOrdinals(operationId);
+        const last = ordinals.at(-1);
+        return last === undefined ? undefined : this.readCheckpoint(operationId, last);
+    }
+    async compareAndInstallCheckpoint(operationId, previousCheckpointId, coveredHead, checkpoint) {
+        validateCandidate(checkpoint);
+        const latest = await this.latestCheckpoint(operationId);
+        checkCheckpointPrecondition(latest, previousCheckpointId, checkpoint);
+        verifyCoveredHead(await this.readRecord(operationId, checkpoint.through_step_seq), await this.prunedAnchor(operationId), coveredHead, checkpoint.through_step_seq);
+        const ordinal = latest ? latest.ordinal + 1 : 0;
+        const persisted = {
+            ordinal,
+            checkpoint_id: checkpoint.checkpoint_id,
+            ...(previousCheckpointId === undefined ? {} : { previous_checkpoint_id: previousCheckpointId }),
+            covered_head: coveredHead,
+            through_step_seq: checkpoint.through_step_seq,
+            state_digest: checkpoint.state_digest,
+            checkpoint_bytes: toBase64(checkpoint.checkpoint_bytes),
+        };
+        const won = await this.claim(`${this.checkpointsPrefix(operationId)}${pad(ordinal)}.ckpt`, persisted);
+        if (!won) {
+            throw new JournalCasConflictError(`checkpoint ordinal ${ordinal} was claimed by a concurrent installer`);
+        }
+        return {
+            ...checkpoint,
+            checkpoint_bytes: Uint8Array.from(checkpoint.checkpoint_bytes),
+            ordinal,
+            covered_head: coveredHead,
+            ...(previousCheckpointId === undefined ? {} : { previous_checkpoint_id: previousCheckpointId }),
+            acknowledged: false,
+        };
+    }
+    async ackCheckpoint(operationId, checkpointId) {
+        for (const ordinal of (await this.checkpointOrdinals(operationId)).reverse()) {
+            const installed = await this.readCheckpoint(operationId, ordinal);
+            if (!installed || installed.checkpoint_id !== checkpointId)
+                continue;
+            if (!installed.acknowledged) {
+                // A lost claim means another writer already acknowledged it — idempotent either way.
+                await this.claim(`${this.checkpointsPrefix(operationId)}${pad(ordinal)}.ack`, {
+                    ordinal,
+                    checkpoint_id: checkpointId,
+                });
+            }
+            return { ...installed, acknowledged: true };
+        }
+        throw new JournalIntegrityError("cannot acknowledge an uninstalled checkpoint");
+    }
+    async pruneAckedPrefix(operationId) {
+        const acked = await this.ackedOrdinals(operationId);
+        const existing = await this.prunedAnchor(operationId);
+        let boundary;
+        for (const ordinal of (await this.checkpointOrdinals(operationId)).reverse()) {
+            if (!acked.has(ordinal))
+                continue;
+            boundary = await this.readCheckpoint(operationId, ordinal, acked);
+            break;
+        }
+        if (!boundary) {
+            return { pruned_through_step_seq: existing?.through_step_seq ?? -1, pruned_count: 0 };
+        }
+        // Anchor first, delete second: a crash mid-prune leaves a resolvable head either way.
+        if (!existing || existing.through_step_seq < boundary.through_step_seq) {
+            await this.writeAnchor(operationId, {
+                through_step_seq: boundary.through_step_seq,
+                covered_head: boundary.covered_head,
+            });
+        }
+        let pruned = 0;
+        for (const seq of await this.recordSeqs(operationId)) {
+            if (seq > boundary.through_step_seq)
+                break;
+            try {
+                await this.driver.remove(`${this.recordsPrefix(operationId)}${pad(seq)}.rec`);
+            }
+            catch (err) {
+                throw new JournalIoError("journal could not reclaim a pruned record", { cause: err });
+            }
+            pruned++;
+        }
+        return {
+            pruned_through_step_seq: Math.max(boundary.through_step_seq, existing?.through_step_seq ?? -1),
+            pruned_count: pruned,
+        };
+    }
+    /** The anchor only ever moves forward, so an overwriting `put` is the right primitive. */
+    async writeAnchor(operationId, anchor) {
+        try {
+            await this.driver.put(this.prunedKey(operationId), encoder.encode(JSON.stringify(anchor)));
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not record its pruned anchor", { cause: err });
+        }
+    }
+    async stageOutboundEnvelope(operationId, envelopeJson) {
+        if (!envelopeJson)
+            throw new JournalIntegrityError("outbound envelope must not be empty");
+        try {
+            await this.driver.put(this.outboundKey(operationId), encoder.encode(envelopeJson));
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not stage a durable outbound envelope", { cause: err });
+        }
+    }
+    async readOutboundEnvelope(operationId) {
+        return this.load(this.outboundKey(operationId));
+    }
+    async clearOutboundEnvelope(operationId) {
+        try {
+            await this.driver.remove(this.outboundKey(operationId));
+        }
+        catch (err) {
+            throw new JournalIoError("journal could not clear its outbound envelope", { cause: err });
+        }
+    }
+}