@code-yeongyu/senpi-agent-core 2026.10.27-1 → 2026.10.30-1

package/dist/durable/store.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The DurableStore contract of the durable core (packages/agent/docs/durable-core-adr.md). Every backend (memory, Bun
+ * SQLite, Durable Object SQLite) implements it and passes the STORE and KILL-STORE conformance cases.
+ *
+ * The store does not serialize concurrent writers: a single admission line above it (store-admission.ts) does.
+ */
+/** A JSON value as the store persists it. */
+export type StoreValue = null | boolean | number | string | readonly StoreValue[] | {
+    readonly [key: string]: StoreValue;
+};
+/** One log record. `seq` is assigned by the store: gapless from 1, in commit order. `id` is unique in the log. */
+export interface StoreRecord {
+    readonly seq: number;
+    readonly id: string;
+    readonly kind: string;
+    readonly data: StoreValue;
+}
+export interface StoreDocument {
+    readonly key: string;
+    readonly data: StoreValue;
+}
+export type StoreWrite = {
+    readonly op: "append";
+    readonly id: string;
+    readonly kind: string;
+    readonly data: StoreValue;
+} | {
+    readonly op: "put";
+    readonly key: string;
+    readonly data: StoreValue;
+} | {
+    readonly op: "delete";
+    readonly key: string;
+};
+export interface CommitResult {
+    /** The sequence numbers of the batch's appends, in write order. */
+    readonly seqs: readonly number[];
+    /** The last committed sequence number after this batch (0 for an empty log). */
+    readonly head: number;
+}
+/** Everything a store holds; the unit of claim + import between hosts. */
+export interface StoreSnapshot {
+    readonly epoch: number;
+    readonly head: number;
+    /** Every record, ascending by `seq`. */
+    readonly records: readonly StoreRecord[];
+    /** Every document, ascending by `key`. */
+    readonly documents: readonly StoreDocument[];
+}
+export interface RecordScan {
+    readonly fromSeq?: number;
+    readonly toSeq?: number;
+    readonly kind?: string;
+    readonly order?: "asc" | "desc";
+    readonly limit?: number;
+}
+export type StoreOperation = "commit" | "claim" | "import";
+/**
+ * A point inside a durable write. `before`: nothing of the operation is durable yet. `write`: inside the atomic unit,
+ * before write `index` is staged. `durable`: the operation is durable, before `adopt` runs and before it resolves.
+ */
+export type StoreWritePoint = {
+    readonly op: StoreOperation;
+    readonly at: "before";
+} | {
+    readonly op: "commit" | "import";
+    readonly at: "write";
+    readonly index: number;
+} | {
+    readonly op: StoreOperation;
+    readonly at: "durable";
+};
+export interface DurableStoreOptions {
+    /**
+     * Test seam for cuts and kills: called at every write point. A throw at `before` or `write` leaves nothing of the
+     * operation durable; a throw at `durable` leaves all of it durable and skips `adopt`.
+     */
+    readonly onWritePoint?: (point: StoreWritePoint) => void;
+}
+export type DurableStoreErrorCode = "unclaimed" | "stale-epoch" | "invalid-claim" | "duplicate-record-id" | "import-conflict";
+export declare class DurableStoreError extends Error {
+    readonly code: DurableStoreErrorCode;
+    constructor(code: DurableStoreErrorCode, message: string);
+}
+export interface DurableStore {
+    /** The current owner epoch; 0 when the store was never claimed. */
+    readEpoch(): Promise<number>;
+    /** The last committed sequence number; 0 for an empty log. */
+    readHead(): Promise<number>;
+    /**
+     * Compare-and-set the owner epoch from `expectedEpoch` to `nextEpoch`, which must be exactly `expectedEpoch + 1`; any
+     * other `nextEpoch` (equal, lower, or skipping an epoch) is refused (`invalid-claim`) and changes nothing. A claimant
+     * whose expected epoch is no longer current is refused (`stale-epoch`), so an old owner can never take the store back.
+     */
+    claim(expectedEpoch: number, nextEpoch: number): Promise<void>;
+    /**
+     * Commit a batch atomically under the owner `epoch`: all of it becomes durable, or none of it. `adopt` runs exactly
+     * once, after the batch is durable and before the commit resolves, and never for a batch that did not become
+     * durable. A commit from any epoch but the current one is refused (`stale-epoch`) and leaves the store unchanged.
+     */
+    commit(epoch: number, writes: readonly StoreWrite[], adopt: (result: CommitResult) => void): Promise<CommitResult>;
+    /** A new ID, unique across instances, reopens and hosts. */
+    mintId(): string;
+    scanRecords(query?: RecordScan): Promise<StoreRecord[]>;
+    getDocument(key: string): Promise<StoreValue | undefined>;
+    /** Documents whose key starts with `prefix`, ascending by key. */
+    scanDocuments(prefix: string): Promise<StoreDocument[]>;
+    exportSnapshot(): Promise<StoreSnapshot>;
+    /**
+     * Import another host's snapshot under this store's current owner `epoch`, which must be above the snapshot's.
+     * Atomic. The store's records must be a prefix of the snapshot's: records past the store's head are imported once,
+     * in order, with their seqs and IDs; documents become the snapshot's. Importing the same snapshot again is a no-op.
+     */
+    importSnapshot(epoch: number, snapshot: StoreSnapshot): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/durable/store.js

@@ -0,0 +1,14 @@
+/**
+ * The DurableStore contract of the durable core (packages/agent/docs/durable-core-adr.md). Every backend (memory, Bun
+ * SQLite, Durable Object SQLite) implements it and passes the STORE and KILL-STORE conformance cases.
+ *
+ * The store does not serialize concurrent writers: a single admission line above it (store-admission.ts) does.
+ */
+export class DurableStoreError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "DurableStoreError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/durable/testing/kill-store.d.ts

@@ -0,0 +1,13 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import type { StoreOperation } from "../store.ts";
+import { type StoreCaseAdapters } from "./store-harness.ts";
+/** Where a KILL case applies; a host report logs it in kill[] with the registry's expected outcome. */
+export interface KillDeclaration {
+    readonly id: string;
+    readonly op: StoreOperation;
+    readonly at: "before" | "durable";
+    readonly placement: "everywhere";
+}
+export declare const KILL_STORE_DECLARATIONS: readonly KillDeclaration[];
+export declare const KILL_STORE_CASES: ReadonlyMap<string, CaseImplementation<StoreCaseAdapters>>;
+//# sourceMappingURL=kill-store.d.ts.map

package/dist/durable/testing/kill-store.js

@@ -0,0 +1,77 @@
+import { append, claimedStore, put, stored } from "./store-cases.js";
+import { adoptLog, cutOnceAt, expectCut, expectEqual, expectStoreError, } from "./store-harness.js";
+const killCase = (id, op, at, body) => ({ id, op, at, placement: "everywhere", run: ({ store }) => body(store, { op, at }) });
+async function seeded(adapter) {
+    const { medium, store } = await claimedStore(adapter);
+    await store.commit(1, [append("r1"), put("doc", 1)], () => { });
+    return { medium, baseline: await store.exportSnapshot() };
+}
+async function killThenReopen(adapter, medium, kill, operation) {
+    await expectCut(operation(await adapter.open(medium, cutOnceAt(kill))), `kill ${kill.at} ${kill.op}`);
+    return adapter.open(medium);
+}
+const content = ({ head, records, documents }) => ({ head, records, documents });
+const SECOND_BATCH = [append("r2"), put("doc", 2)];
+const KILL_CASES = [
+    killCase("KILL-STORE-01", "commit", "before", async (adapter, kill) => {
+        const { medium, baseline } = await seeded(adapter);
+        const log = adoptLog();
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.commit(1, SECOND_BATCH, log.adopt));
+        expectEqual(await restarted.exportSnapshot(), baseline, "nothing of the batch is durable");
+        expectEqual(await restarted.commit(1, SECOND_BATCH, log.adopt), { seqs: [2], head: 2 }, "same IDs, next seq");
+        expectEqual(log.calls, ["adopt:2"], "only the committed batch adopts");
+    }),
+    killCase("KILL-STORE-02", "commit", "durable", async (adapter, kill) => {
+        const { medium, baseline } = await seeded(adapter);
+        const log = adoptLog();
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.commit(1, SECOND_BATCH, log.adopt));
+        const expected = {
+            ...baseline,
+            head: 2,
+            records: [stored(1, "r1"), stored(2, "r2")],
+            documents: [{ key: "doc", data: 2 }],
+        };
+        expectEqual(log.calls, [], "the killed process never adopted");
+        expectEqual(await restarted.exportSnapshot(), expected, "the whole batch is durable with its IDs and seqs");
+        await expectStoreError(restarted.commit(1, SECOND_BATCH, log.adopt), "duplicate-record-id", "a retried batch");
+        expectEqual(await restarted.exportSnapshot(), expected, "the retry applies nothing twice");
+    }),
+    killCase("KILL-STORE-03", "claim", "before", async (adapter, kill) => {
+        const { medium, baseline } = await seeded(adapter);
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.claim(1, 2));
+        expectEqual(await restarted.exportSnapshot(), baseline, "the epoch and log are unchanged");
+        await restarted.claim(1, 2);
+        expectEqual(await restarted.readEpoch(), 2, "the claim succeeds after restart");
+    }),
+    killCase("KILL-STORE-04", "claim", "durable", async (adapter, kill) => {
+        const { medium, baseline } = await seeded(adapter);
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.claim(1, 2));
+        expectEqual(await restarted.exportSnapshot(), { ...baseline, epoch: 2 }, "the claim is durable; the log is intact");
+        await expectStoreError(restarted.claim(1, 2), "stale-epoch", "the claim cannot be taken twice");
+        await expectStoreError(restarted.commit(1, [append("late")], () => { }), "stale-epoch", "the old epoch is fenced");
+    }),
+    killCase("KILL-STORE-05", "import", "before", async (adapter, kill) => {
+        const { baseline } = await seeded(adapter);
+        const { medium } = await claimedStore(adapter, 2);
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.importSnapshot(2, baseline));
+        expectEqual(await restarted.exportSnapshot(), { epoch: 2, head: 0, records: [], documents: [] }, "nothing imported");
+        await restarted.importSnapshot(2, baseline);
+        expectEqual(content(await restarted.exportSnapshot()), content(baseline), "the import succeeds after restart");
+    }),
+    killCase("KILL-STORE-06", "import", "durable", async (adapter, kill) => {
+        const { baseline } = await seeded(adapter);
+        const { medium } = await claimedStore(adapter, 2);
+        const restarted = await killThenReopen(adapter, medium, kill, (s) => s.importSnapshot(2, baseline));
+        expectEqual(content(await restarted.exportSnapshot()), content(baseline), "the whole import is durable");
+        await restarted.importSnapshot(2, baseline);
+        expectEqual(content(await restarted.exportSnapshot()), content(baseline), "re-import adds nothing twice");
+    }),
+];
+export const KILL_STORE_DECLARATIONS = KILL_CASES.map(({ id, op, at, placement }) => ({
+    id,
+    op,
+    at,
+    placement,
+}));
+export const KILL_STORE_CASES = new Map(KILL_CASES.map(({ id, run }) => [id, run]));
+//# sourceMappingURL=kill-store.js.map

package/dist/durable/testing/kill-wake.d.ts

@@ -0,0 +1,12 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import { type WakeCaseAdapters } from "./wake-harness.ts";
+/** Where a KILL-WAKE case applies; a host report logs it in kill[] with the registry's expected outcome. */
+export interface KillWakeDeclaration {
+    readonly id: string;
+    readonly operation: "admit" | "commit" | "update" | "fire";
+    readonly point: string;
+    readonly placement: "everywhere";
+}
+export declare const KILL_WAKE_DECLARATIONS: readonly KillWakeDeclaration[];
+export declare const KILL_WAKE_CASES: ReadonlyMap<string, CaseImplementation<WakeCaseAdapters>>;
+//# sourceMappingURL=kill-wake.d.ts.map

package/dist/durable/testing/kill-wake.js

@@ -0,0 +1,123 @@
+import { expectEqual } from "./store-harness.js";
+import { createSlot, cutAlarm, cutStore, cutWake, expectWakeCut, HEARTBEAT_MS, } from "./wake-harness.js";
+const killCase = (id, operation, point, run) => ({ id, operation, point, placement: "everywhere", run });
+const LATER = 600_000;
+const DUE = 120_000;
+async function killedAdmission(adapters, cut) {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance(cut);
+    await expectWakeCut(host.admit(() => loop.schedule("a", slot.base + LATER)), "the killed admission");
+    slot.kill();
+    return slot;
+}
+/** Recovery with no request from anyone: only the armed alarm brings the session back. */
+async function recoversThroughHeartbeat(adapters, slot) {
+    expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "the pre-armed heartbeat survived the kill");
+    await adapters.wake.advanceTo(slot.base + HEARTBEAT_MS);
+    expectEqual(await slot.alarmAt(), LATER, "the heartbeat's instance armed the committed wake");
+    await adapters.wake.advanceTo(slot.base + LATER);
+    expectEqual(await slot.ran(), ["a"], "the committed task ran exactly once");
+    expectEqual(await slot.alarmAt(), undefined, "and the alarm is cleared");
+}
+async function killedFire(adapters, cut) {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance(cut);
+    await host.admit(() => loop.schedule("a", slot.base + DUE));
+    await adapters.wake.advanceTo(slot.base + DUE);
+    expectEqual(slot.fires(), 1, "the alarm fired into the instance that is killed");
+    return slot;
+}
+async function recoversAfterKilledFire(adapters, slot) {
+    expectEqual(await slot.alarmAt(), DUE + HEARTBEAT_MS, "the fire's re-arm survived the kill");
+    await adapters.wake.advanceTo(slot.base + DUE + HEARTBEAT_MS);
+    expectEqual(await slot.ran(), ["a"], "the task ran exactly once");
+    expectEqual(await slot.alarmAt(), undefined, "and the alarm is cleared");
+    await adapters.wake.advanceTo(slot.base + LATER);
+    expectEqual(slot.fires(), 2, "no fire beyond the recovery");
+}
+/**
+ * An admission B runs while a fire resumes other work on the same instance. The fire's updates see an idle loop (B's
+ * task is not committed yet), so they must not clear the heartbeat B armed; B is killed after its commit is durable,
+ * before its own update. The session runs at epoch 2.
+ */
+async function admissionDuringFire(adapters) {
+    const fireDone = Promise.withResolvers();
+    let admission;
+    let session;
+    const slot = await createSlot(adapters, 2);
+    const first = await slot.instance({
+        store: cutStore("commit", "durable", 3),
+        onWakePoint: (point) => {
+            if (point.op !== "fire" || session === undefined || admission !== undefined)
+                return;
+            const { host, loop } = session;
+            admission = host.admit(async () => {
+                await fireDone.promise;
+                await loop.schedule("b", slot.base + LATER);
+            });
+        },
+    });
+    session = first;
+    await first.host.admit(() => first.loop.schedule("a", slot.base + DUE));
+    await adapters.wake.advanceTo(slot.base + DUE);
+    expectEqual(await slot.ran(), ["a"], "the fire resumed its due task");
+    if (admission === undefined)
+        throw new Error("the admission did not start during the fire");
+    fireDone.resolve();
+    await expectWakeCut(admission, "the admission killed after its commit");
+    slot.kill();
+    return slot;
+}
+const KILL_CASES = [
+    killCase("KILL-WAKE-01", "admit", "alarm write before durable", async (adapters) => {
+        const slot = await killedAdmission(adapters, { alarm: cutAlarm("set", "before", 2) });
+        expectEqual(await slot.alarmAt(), undefined, "nothing of the admission is durable");
+        const { host, loop } = await slot.instance();
+        await host.admit(() => loop.schedule("a", slot.base + LATER));
+        await adapters.wake.advanceTo(slot.base + LATER);
+        expectEqual(await slot.ran(), ["a"], "the retried admission runs once");
+    }),
+    killCase("KILL-WAKE-02", "admit", "after the arm, before work", async (adapters) => {
+        const slot = await killedAdmission(adapters, { onWakePoint: cutWake("admit") });
+        expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "the arm is durable");
+        await adapters.wake.advanceTo(slot.base + HEARTBEAT_MS);
+        expectEqual(await slot.ran(), [], "an alarm without work runs nothing");
+        expectEqual(await slot.alarmAt(), undefined, "and ends cleared");
+        expectEqual(slot.fires(), 1, "one harmless fire");
+    }),
+    killCase("KILL-WAKE-03", "commit", "after the commit is durable, before the alarm update", async (adapters) => {
+        const slot = await killedAdmission(adapters, { store: cutStore("commit", "durable") });
+        await recoversThroughHeartbeat(adapters, slot);
+    }),
+    killCase("KILL-WAKE-04", "update", "eviction during the alarm write", async (adapters) => {
+        const slot = await killedAdmission(adapters, { alarm: cutAlarm("set", "before", 3) });
+        await recoversThroughHeartbeat(adapters, slot);
+    }),
+    killCase("KILL-WAKE-05", "fire", "after the re-arm, before resume", async (adapters) => {
+        const slot = await killedFire(adapters, { onWakePoint: cutWake("fire") });
+        expectEqual(await slot.ran(), [], "nothing ran before the kill");
+        await recoversAfterKilledFire(adapters, slot);
+    }),
+    killCase("KILL-WAKE-06", "fire", "after a resumed task's commit is durable", async (adapters) => {
+        const slot = await killedFire(adapters, { store: cutStore("commit", "durable", 2) });
+        expectEqual(await slot.ran(), ["a"], "the task's commit is durable");
+        await recoversAfterKilledFire(adapters, slot);
+    }),
+    killCase("KILL-WAKE-07", "fire", "eviction during the alarm clear after the work", async (adapters) => {
+        const slot = await killedFire(adapters, { alarm: cutAlarm("clear", "before", 2) });
+        expectEqual(await slot.ran(), ["a"], "the work is durable");
+        await recoversAfterKilledFire(adapters, slot);
+    }),
+    killCase("KILL-WAKE-08", "admit", "a concurrent fire's updates while the admission is uncommitted, then a kill after its commit", async (adapters) => {
+        const slot = await admissionDuringFire(adapters);
+        expectEqual(await slot.alarmAt(), DUE + HEARTBEAT_MS, "the admission's heartbeat outlived the fire's updates");
+        await adapters.wake.advanceTo(slot.base + DUE + HEARTBEAT_MS);
+        expectEqual(await slot.alarmAt(), LATER, "the heartbeat's instance armed the committed wake");
+        await adapters.wake.advanceTo(slot.base + LATER);
+        expectEqual(await slot.ran(), ["a", "b"], "each task ran exactly once");
+        expectEqual(await slot.alarmAt(), undefined, "and the alarm is cleared");
+    }),
+];
+export const KILL_WAKE_DECLARATIONS = KILL_CASES.map(({ id, operation, point, placement }) => ({ id, operation, point, placement }));
+export const KILL_WAKE_CASES = new Map(KILL_CASES.map(({ id, run }) => [id, run]));
+//# sourceMappingURL=kill-wake.js.map

package/dist/durable/testing/manual-timers.d.ts

@@ -0,0 +1,8 @@
+/** Manual timers for a host under test: a clock that moves only through `advanceTo`, which runs due timers in order. */
+export interface ManualTimers {
+    now(): number;
+    setTimer(callback: () => unknown, ms: number): () => void;
+    advanceTo(at: number): Promise<void>;
+}
+export declare function createManualTimers(start: number): ManualTimers;
+//# sourceMappingURL=manual-timers.d.ts.map

package/dist/durable/testing/manual-timers.js

@@ -0,0 +1,31 @@
+export function createManualTimers(start) {
+    let time = start;
+    let nextId = 1;
+    const timers = new Map();
+    return {
+        now: () => time,
+        setTimer: (callback, ms) => {
+            const id = nextId++;
+            timers.set(id, { due: time + Math.max(0, ms), callback });
+            return () => void timers.delete(id);
+        },
+        async advanceTo(at) {
+            for (let step = 0;; step++) {
+                if (step > 10_000)
+                    throw new Error("manual timers: more than 10000 timers fired in one advance");
+                let next;
+                for (const entry of timers) {
+                    if (entry[1].due <= at && (next === undefined || entry[1].due < next[1].due))
+                        next = entry;
+                }
+                if (next === undefined)
+                    break;
+                timers.delete(next[0]);
+                time = Math.max(time, next[1].due);
+                await next[1].callback();
+            }
+            time = Math.max(time, at);
+        },
+    };
+}
+//# sourceMappingURL=manual-timers.js.map

package/dist/durable/testing/multi-host-cases.d.ts

@@ -0,0 +1,6 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import { type WakeCaseAdapters } from "./wake-harness.ts";
+type MultiHostCase = CaseImplementation<WakeCaseAdapters>;
+export declare const MULTI_HOST_CASES: ReadonlyMap<string, MultiHostCase>;
+export {};
+//# sourceMappingURL=multi-host-cases.d.ts.map

package/dist/durable/testing/multi-host-cases.js

@@ -0,0 +1,32 @@
+import { expectEqual } from "./store-harness.js";
+import { createSlot } from "./wake-harness.js";
+async function schedule(slot, id, offset) {
+    const { host, loop } = await slot.instance();
+    await host.admit(() => loop.schedule(id, slot.base + offset));
+}
+const observe = async (slots) => ({
+    fires: slots.map((slot) => slot.fires()),
+    ran: await Promise.all(slots.map((slot) => slot.ran())),
+    alarms: await Promise.all(slots.map((slot) => slot.alarmAt())),
+});
+const manySessionsOnOneHost = async (adapters) => {
+    const slots = [await createSlot(adapters), await createSlot(adapters), await createSlot(adapters)];
+    const [first, second, third] = slots;
+    if (first === undefined || second === undefined || third === undefined)
+        throw new Error("three sessions");
+    await schedule(first, "x", 120_000);
+    await schedule(first, "y", 300_000);
+    await schedule(second, "x", 200_000);
+    await third.instance();
+    expectEqual(await observe(slots), { fires: [0, 0, 0], ran: [[], [], []], alarms: [120_000, 200_000, undefined] }, "armed per session");
+    second.kill();
+    await adapters.wake.advanceTo(first.base + 120_000);
+    expectEqual(await observe(slots), { fires: [1, 0, 0], ran: [["x"], [], []], alarms: [300_000, 200_000, undefined] }, "a fire resumes only its own session; the same task ID elsewhere is untouched");
+    third.kill();
+    await third.instance();
+    expectEqual((await observe(slots)).alarms, [300_000, 200_000, undefined], "restarting one session moves no other session's alarm");
+    await adapters.wake.advanceTo(first.base + 300_000);
+    expectEqual(await observe(slots), { fires: [2, 1, 0], ran: [["x", "y"], ["x"], []], alarms: [undefined, undefined, undefined] }, "an evicted session comes back on its own alarm; records and wakes stay per session");
+};
+export const MULTI_HOST_CASES = new Map([["MULTI-HOST-01", manySessionsOnOneHost]]);
+//# sourceMappingURL=multi-host-cases.js.map

package/dist/durable/testing/store-cases.d.ts

@@ -0,0 +1,21 @@
+import type { CaseImplementation } from "../../conformance/runner.ts";
+import type { StoreValue, StoreWrite } from "../store.ts";
+import { type StoreCaseAdapters, type StoreConformanceAdapter } from "./store-harness.ts";
+type StoreCase = CaseImplementation<StoreCaseAdapters>;
+export declare const append: (id: string, kind?: string) => StoreWrite;
+export declare const put: (key: string, data: StoreValue) => StoreWrite;
+export declare const stored: (seq: number, id: string, kind?: string) => {
+    seq: number;
+    id: string;
+    kind: string;
+    data: {
+        id: string;
+    };
+};
+export declare function claimedStore(adapter: StoreConformanceAdapter, epoch?: number): Promise<{
+    medium: string;
+    store: import("../store.ts").DurableStore;
+}>;
+export declare const STORE_CASES: ReadonlyMap<string, StoreCase>;
+export {};
+//# sourceMappingURL=store-cases.d.ts.map

package/dist/durable/testing/store-cases.js

@@ -0,0 +1,168 @@
+import { createAdmissionLine } from "../store-admission.js";
+import { adoptLog, cutOnceAt, expectCut, expectEqual, expectStoreError, reopenSnapshot, } from "./store-harness.js";
+export const append = (id, kind = "entry") => ({ op: "append", id, kind, data: { id } });
+export const put = (key, data) => ({ op: "put", key, data });
+export const stored = (seq, id, kind = "entry") => ({ seq, id, kind, data: { id } });
+export async function claimedStore(adapter, epoch = 1) {
+    const medium = await adapter.createMedium();
+    const store = await adapter.open(medium);
+    for (let next = 1; next <= epoch; next++)
+        await store.claim(next - 1, next);
+    return { medium, store };
+}
+const commitAdoptsOnDurable = async ({ store: adapter }) => {
+    const medium = await adapter.createMedium();
+    const events = [];
+    const store = await adapter.open(medium, {
+        onWritePoint: (point) => void (point.op === "commit" && point.at === "durable" && events.push("durable")),
+    });
+    await store.claim(0, 1);
+    const adopt = (result) => void events.push(`adopt:${result.seqs.join(",")}`);
+    expectEqual(await store.commit(1, [append("r1"), append("r2"), put("doc", 1)], adopt), { seqs: [1, 2], head: 2 }, "batch");
+    expectEqual(events, ["durable", "adopt:1,2"], "adopt runs once, after the batch is durable");
+    expectEqual(await store.commit(1, [put("doc", 2)], adopt), { seqs: [], head: 2 }, "documents-only batch");
+    expectEqual(await reopenSnapshot(adapter, medium), {
+        epoch: 1,
+        head: 2,
+        records: [stored(1, "r1"), stored(2, "r2")],
+        documents: [{ key: "doc", data: 2 }],
+    }, "another instance on the medium sees every committed batch whole");
+};
+const BATCH = [append("r2"), put("a", 2), { op: "delete", key: "b" }, append("r3"), put("c", 1)];
+const cutAtEveryWritePoint = async ({ store: adapter }) => {
+    const points = [
+        { op: "commit", at: "before" },
+        ...BATCH.map((_, index) => ({ op: "commit", at: "write", index })),
+    ];
+    for (const point of points) {
+        const what = `cut at ${JSON.stringify(point)}`;
+        const { medium, store: setup } = await claimedStore(adapter);
+        await setup.commit(1, [append("r1"), put("a", 1), put("b", 1)], () => { });
+        const baseline = await setup.exportSnapshot();
+        const store = await adapter.open(medium, cutOnceAt(point));
+        const log = adoptLog();
+        await expectCut(store.commit(1, BATCH, log.adopt), what);
+        expectEqual(log.calls, [], `${what}: no adopt`);
+        expectEqual(await reopenSnapshot(adapter, medium), baseline, `${what}: nothing of the batch is durable`);
+        expectEqual(await store.commit(1, BATCH, log.adopt), { seqs: [2, 3], head: 3 }, `${what}: no seq burned`);
+        expectEqual(log.calls, ["adopt:2,3"], `${what}: the retried batch adopts once`);
+    }
+};
+const concurrentAdmissions = async ({ store: adapter }) => {
+    const { store } = await claimedStore(adapter);
+    const line = createAdmissionLine();
+    const events = [];
+    const gate = Promise.withResolvers();
+    const admit = (name, hold) => line.admit(async () => {
+        events.push(`${name}:start`);
+        if (hold !== undefined)
+            await hold;
+        return store.commit(1, [append(name)], (result) => void events.push(`${name}:adopt:${result.seqs.join(",")}`));
+    });
+    const admissions = [
+        admit("a", gate.promise),
+        admit("b"),
+        line.admit(async () => {
+            events.push("c:start");
+            throw new Error("mutation refused");
+        }),
+        admit("d"),
+    ];
+    gate.resolve();
+    const settled = await Promise.allSettled(admissions);
+    expectEqual(settled.map((s) => s.status), ["fulfilled", "fulfilled", "rejected", "fulfilled"], "admission outcomes");
+    expectEqual(events, ["a:start", "a:adopt:1", "b:start", "b:adopt:2", "c:start", "d:start", "d:adopt:3"], "one admission at a time, in admission order; a refused mutation releases the line");
+    expectEqual((await store.scanRecords()).map((r) => `${r.seq}:${r.id}`), ["1:a", "2:b", "3:d"], "records");
+};
+const delayedOldOwner = async ({ store: adapter }) => {
+    const { medium, store: oldOwner } = await claimedStore(adapter);
+    await oldOwner.commit(1, [append("old-1")], () => { });
+    const newOwner = await adapter.open(medium);
+    await newOwner.claim(1, 2);
+    await newOwner.commit(2, [append("new-1")], () => { });
+    const late = adoptLog();
+    await expectStoreError(oldOwner.commit(1, [append("old-2")], late.adopt), "stale-epoch", "old owner's delayed commit");
+    await expectStoreError(oldOwner.claim(1, 2), "stale-epoch", "old owner's delayed claim");
+    await expectStoreError(newOwner.commit(3, [append("x")], late.adopt), "stale-epoch", "a commit from a future epoch");
+    await expectStoreError(newOwner.claim(2, 2), "invalid-claim", "a claim that does not raise the epoch");
+    const fresh = await adapter.open(await adapter.createMedium());
+    await expectStoreError(fresh.commit(0, [append("x")], late.adopt), "unclaimed", "a commit to an unclaimed store");
+    expectEqual(late.calls, [], "no refused commit adopts");
+    expectEqual(await reopenSnapshot(adapter, medium), {
+        epoch: 2,
+        head: 2,
+        records: [stored(1, "old-1"), stored(2, "new-1")],
+        documents: [],
+    }, "the new owner's state");
+};
+const claimAndImport = async ({ store: adapter }) => {
+    const { store: source } = await claimedStore(adapter);
+    await source.commit(1, [append("r1"), append("r2"), put("doc", "v1")], () => { });
+    const first = await source.exportSnapshot();
+    const { medium, store: target } = await claimedStore(adapter, 2);
+    await expectStoreError(target.importSnapshot(1, first), "stale-epoch", "import under a non-current epoch");
+    await target.importSnapshot(2, first);
+    await target.importSnapshot(2, first);
+    expectEqual(await reopenSnapshot(adapter, medium), { ...first, epoch: 2 }, "import is whole and idempotent");
+    await source.commit(1, [append("r3"), put("doc", "v2")], () => { });
+    const tail = await source.exportSnapshot();
+    await target.importSnapshot(2, tail);
+    expectEqual(await reopenSnapshot(adapter, medium), { ...tail, epoch: 2 }, "the tail past the head is imported once");
+    const conflicting = { ...tail, records: [stored(1, "r1"), stored(2, "other"), stored(3, "r3")] };
+    await expectStoreError(target.importSnapshot(2, conflicting), "import-conflict", "a diverged log");
+    await expectStoreError(target.importSnapshot(2, { ...tail, epoch: 2 }), "invalid-claim", "an import not above the source");
+    expectEqual(await reopenSnapshot(adapter, medium), { ...tail, epoch: 2 }, "refused imports change nothing");
+    expectEqual(await target.commit(2, [append("r4")], () => { }), { seqs: [4], head: 4 }, "the new owner continues the log");
+};
+const claimRaisesEpochByOne = async ({ store: adapter }) => {
+    const { medium, store } = await claimedStore(adapter);
+    await store.commit(1, [append("r1")], () => { });
+    const baseline = await store.exportSnapshot();
+    const fresh = await adapter.open(await adapter.createMedium());
+    await expectStoreError(store.claim(1, 3), "invalid-claim", "a claim that skips an epoch");
+    await expectStoreError(fresh.claim(0, 2), "invalid-claim", "a first claim that skips epoch 1");
+    expectEqual(await fresh.readEpoch(), 0, "a refused first claim leaves the store unclaimed");
+    expectEqual(await reopenSnapshot(adapter, medium), baseline, "a refused claim leaves the epoch and log unchanged");
+    await store.claim(1, 2);
+    expectEqual(await store.readEpoch(), 2, "the next epoch is still claimable");
+};
+const idsScansAndDocuments = async ({ store: adapter }) => {
+    const { medium, store } = await claimedStore(adapter);
+    const reopened = await adapter.open(medium);
+    const elsewhere = await adapter.open(await adapter.createMedium());
+    const ids = [store, reopened, elsewhere].flatMap((s) => Array.from({ length: 100 }, () => s.mintId()));
+    expectEqual(new Set(ids).size, ids.length, "minted IDs are unique across instances, reopens and hosts");
+    const kinds = ["a", "b", "a", "b", "a"];
+    await store.commit(1, [...kinds.map((kind, i) => append(`r${i + 1}`, kind)), put("s/2", 2), put("s/1", 1), put("t/1", 3)], () => { });
+    const seqsOf = async (query) => (await store.scanRecords(query)).map((r) => r.seq);
+    expectEqual(await seqsOf(undefined), [1, 2, 3, 4, 5], "full scan");
+    expectEqual(await seqsOf({ fromSeq: 2, toSeq: 4 }), [2, 3, 4], "range scan");
+    expectEqual(await seqsOf({ kind: "b" }), [2, 4], "kind scan");
+    expectEqual(await seqsOf({ order: "desc", limit: 2 }), [5, 4], "descending, limited");
+    expectEqual(await seqsOf({ kind: "a", order: "desc", limit: 1 }), [5], "kind, descending, limited");
+    expectEqual(await store.scanDocuments("s/"), [
+        { key: "s/1", data: 1 },
+        { key: "s/2", data: 2 },
+    ], "prefix scan");
+    await store.commit(1, [{ op: "delete", key: "s/1" }], () => { });
+    expectEqual(await store.getDocument("s/1"), undefined, "a deleted document");
+    expectEqual((await store.scanDocuments("")).map((d) => d.key), ["s/2", "t/1"], "all documents by key");
+    await expectStoreError(store.commit(1, [append("r1")], () => { }), "duplicate-record-id", "an ID already in the log");
+    await expectStoreError(store.commit(1, [append("x"), append("x")], () => { }), "duplicate-record-id", "a repeated ID");
+    expectEqual(await store.readHead(), 5, "refused batches change nothing");
+    const value = { nested: { n: 1 } };
+    await store.commit(1, [put("v", value)], () => { });
+    value.nested.n = 2;
+    const read = await store.getDocument("v");
+    expectEqual(read, { nested: { n: 1 } }, "the store keeps its own copy of written values");
+};
+export const STORE_CASES = new Map([
+    ["STORE-01", commitAdoptsOnDurable],
+    ["STORE-02", cutAtEveryWritePoint],
+    ["STORE-03", concurrentAdmissions],
+    ["STORE-04", delayedOldOwner],
+    ["STORE-05", claimAndImport],
+    ["STORE-06", idsScansAndDocuments],
+    ["STORE-07", claimRaisesEpochByOne],
+]);
+//# sourceMappingURL=store-cases.js.map