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

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

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

@@ -0,0 +1,23 @@
+import type { DurableStore, DurableStoreErrorCode, DurableStoreOptions, StoreSnapshot, StoreWritePoint } from "../store.ts";
+/** What a host provides to the STORE and KILL-STORE cases. */
+export interface StoreConformanceAdapter {
+    /** A new, empty durable medium (a Durable Object's storage, an SQLite file); its name opens it again. */
+    createMedium(): Promise<string>;
+    /** A store instance over `medium`. Instances opened on one medium share its durable state. */
+    open(medium: string, options?: DurableStoreOptions): Promise<DurableStore>;
+}
+export interface StoreCaseAdapters {
+    readonly store: StoreConformanceAdapter;
+}
+export declare function cutOnceAt(target: StoreWritePoint): DurableStoreOptions;
+export declare function expectEqual(actual: unknown, expected: unknown, what: string): void;
+export declare function expectStoreError(operation: Promise<unknown>, code: DurableStoreErrorCode, what: string): Promise<void>;
+export declare function expectCut(operation: Promise<unknown>, what: string): Promise<void>;
+export declare function reopenSnapshot(adapter: StoreConformanceAdapter, medium: string): Promise<StoreSnapshot>;
+export declare function adoptLog(): {
+    readonly calls: string[];
+    adopt: (result: {
+        readonly seqs: readonly number[];
+    }) => void;
+};
+//# sourceMappingURL=store-harness.d.ts.map

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

@@ -0,0 +1,64 @@
+import { DurableStoreError } from "../store.js";
+class CutSignal extends Error {
+    constructor(point) {
+        super(`cut at ${JSON.stringify(point)}`);
+        this.name = "CutSignal";
+    }
+}
+const samePoint = (a, b) => a.op === b.op && a.at === b.at && (a.at !== "write" || (b.at === "write" && a.index === b.index));
+export function cutOnceAt(target) {
+    let armed = true;
+    return {
+        onWritePoint: (point) => {
+            if (armed && samePoint(point, target)) {
+                armed = false;
+                throw new CutSignal(point);
+            }
+        },
+    };
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, inner]) => `${JSON.stringify(key)}:${canonical(inner)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+}
+export function expectEqual(actual, expected, what) {
+    const a = canonical(actual);
+    const e = canonical(expected);
+    if (a !== e)
+        throw new Error(`${what}: expected ${e}, got ${a}`);
+}
+export async function expectStoreError(operation, code, what) {
+    try {
+        await operation;
+    }
+    catch (error) {
+        if (error instanceof DurableStoreError && error.code === code)
+            return;
+        throw new Error(`${what}: expected DurableStoreError ${code}, got ${String(error)}`);
+    }
+    throw new Error(`${what}: expected DurableStoreError ${code}, but it resolved`);
+}
+export async function expectCut(operation, what) {
+    try {
+        await operation;
+    }
+    catch (error) {
+        if (error instanceof CutSignal)
+            return;
+        throw new Error(`${what}: expected the cut to surface, got ${String(error)}`);
+    }
+    throw new Error(`${what}: expected the cut to surface, but it resolved`);
+}
+export async function reopenSnapshot(adapter, medium) {
+    return (await adapter.open(medium)).exportSnapshot();
+}
+export function adoptLog() {
+    const calls = [];
+    return { calls, adopt: (result) => void calls.push(`adopt:${result.seqs.join(",")}`) };
+}
+//# sourceMappingURL=store-harness.js.map

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

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

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

@@ -0,0 +1,100 @@
+import { expectEqual } from "./store-harness.js";
+import { createSlot, HEARTBEAT_MS, restartHost } from "./wake-harness.js";
+const TEN_MINUTES = 600_000;
+const preArm = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const session = await slot.instance();
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, "resume", "clear"], "start arms a fallback before it resumes");
+    slot.trace.length = 0;
+    await session.host.admit(async () => {
+        slot.trace.push(`work alarm=+${await slot.alarmAt()}`);
+    });
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, `work alarm=+${HEARTBEAT_MS}`, "clear"], "admit arms durably before work starts, and arms from the idle loop's wake when the work ends");
+    const failing = session.host.admit(async () => {
+        throw new Error("work failed");
+    });
+    await failing.then(() => {
+        throw new Error("a failing admission resolved");
+    }, () => undefined);
+    expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "work that fails leaves the recovery alarm armed");
+    await session.host.admit(() => session.loop.schedule("late", slot.base + TEN_MINUTES));
+    slot.kill();
+    slot.trace.length = 0;
+    await slot.instance();
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, "resume", `set:+${TEN_MINUTES}`], "a new instance lowers a later alarm to the fallback before resuming");
+    await (await slot.instance()).host.update({ active: false, at: slot.base + 30_000 });
+    slot.kill();
+    slot.trace.length = 0;
+    await slot.instance();
+    expectEqual(slot.trace, ["resume", `set:+${TEN_MINUTES}`], "an earlier alarm is kept as the fallback");
+};
+const update = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    const schedule = (id, offset) => host.admit(() => loop.schedule(id, slot.base + offset));
+    slot.trace.length = 0;
+    await schedule("a", TEN_MINUTES);
+    expectEqual(slot.trace, [`set:+${HEARTBEAT_MS}`, `set:+${HEARTBEAT_MS}`, `set:+${TEN_MINUTES}`], "the commit's update keeps the heartbeat while the admission is in flight; after it, the alarm is the wake");
+    await schedule("b", 300_000);
+    expectEqual(await slot.alarmAt(), 300_000, "an earlier wake lowers the alarm");
+    await schedule("c", 900_000);
+    expectEqual(await slot.alarmAt(), 300_000, "a later wake never raises it past the earliest");
+    await host.update({ active: true, at: slot.base + 300_000 });
+    expectEqual(await slot.alarmAt(), HEARTBEAT_MS, "while active, a heartbeat earlier than the wake");
+    await host.update({ active: true, at: slot.base + 30_000 });
+    expectEqual(await slot.alarmAt(), 30_000, "never later than the earliest wake");
+    await host.update({ active: false });
+    expectEqual(await slot.alarmAt(), undefined, "cleared only when the loop is idle");
+    expectEqual(await slot.ran(), [], "updates run nothing");
+};
+const resume = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    for (const [id, offset] of [
+        ["a", 120_000],
+        ["b", 120_000],
+        ["c", TEN_MINUTES],
+    ]) {
+        await host.admit(() => loop.schedule(id, slot.base + offset));
+    }
+    slot.trace.length = 0;
+    await adapters.wake.advanceTo(slot.base + 120_000);
+    expectEqual(slot.fires(), 1, "one fire at the wake");
+    expectEqual(slot.trace.slice(0, 2), [`set:+${120_000 + HEARTBEAT_MS}`, "resume"], "a fire re-arms before resume");
+    expectEqual(await slot.ran(), ["a", "b"], "the due tasks run once, in order");
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "then the alarm is the next wake");
+    await host.update({ active: true });
+    await adapters.wake.advanceTo(slot.base + 120_000 + HEARTBEAT_MS);
+    expectEqual(await slot.ran(), ["a", "b"], "an early alarm runs nothing");
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "and re-arms from the loop's wake");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES);
+    expectEqual(await slot.ran(), ["a", "b", "c"], "the last task runs at its wake");
+    expectEqual(await slot.alarmAt(), undefined, "an idle loop leaves no alarm");
+    expectEqual(slot.fires(), 3, "no fire beyond the alarms armed");
+};
+const retention = async (adapters) => {
+    const slot = await createSlot(adapters);
+    const { host, loop } = await slot.instance();
+    await host.admit(() => loop.schedule("a", slot.base + TEN_MINUTES));
+    await restartHost(adapters, [slot]);
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "the alarm is durable across a host restart");
+    await slot.instance();
+    slot.kill();
+    await slot.instance();
+    expectEqual(await slot.alarmAt(), TEN_MINUTES, "reopened instances keep it");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES - 1);
+    expectEqual(slot.fires(), 0, "nothing fires early, whatever instances came and went");
+    await adapters.wake.advanceTo(slot.base + TEN_MINUTES);
+    expectEqual(slot.fires(), 1, "it fires once");
+    expectEqual(await slot.ran(), ["a"], "the task runs once");
+    expectEqual(await slot.alarmAt(), undefined, "and the alarm is not retained after the work");
+    await adapters.wake.advanceTo(slot.base + 3 * TEN_MINUTES);
+    expectEqual(slot.fires(), 1, "a consumed alarm never fires again");
+};
+export const WAKE_CASES = new Map([
+    ["WAKE-01", preArm],
+    ["WAKE-02", update],
+    ["WAKE-03", resume],
+    ["WAKE-RET-01", retention],
+]);
+//# sourceMappingURL=wake-cases.js.map

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

@@ -0,0 +1,64 @@
+import type { DurableStore, DurableStoreOptions, StoreWritePoint } from "../store.ts";
+import { type WakeAlarm, type WakeAlarmOptions, type WakeAlarmPoint, type WakeHost, type WakePoint } from "../wake-host.ts";
+import type { StoreCaseAdapters } from "./store-harness.ts";
+import { type TestLoop } from "./wake-test-loop.ts";
+/** The session a host's alarm belongs to. Hosts that persist the alarm in the store use `store` under `epoch`. */
+export interface WakeAlarmSession {
+    readonly medium: string;
+    readonly store: DurableStore;
+    readonly epoch: number;
+    readonly onFire: () => Promise<void>;
+    readonly options?: WakeAlarmOptions;
+}
+/** What a host provides to the WAKE, KILL-WAKE and MULTI-HOST cases, next to its store adapter. */
+export interface WakeConformanceAdapter {
+    /** The host clock, epoch milliseconds; only `advanceTo` moves it. */
+    now(): number;
+    /** Move the clock to `at`, delivering every alarm that falls due on the way, in time order, each awaited. */
+    advanceTo(at: number): Promise<void>;
+    /**
+     * The durable alarm of one session. Opening it again (a new instance after a kill) replaces the earlier instance:
+     * fires go to the newest `onFire` only. The armed time outlives instances and host restarts.
+     */
+    openAlarm(session: WakeAlarmSession): Promise<WakeAlarm>;
+    /** The host process restarts: instances and in-memory timers are lost, durable alarms are kept. */
+    restart(): Promise<void>;
+}
+export interface WakeCaseAdapters extends StoreCaseAdapters {
+    readonly wake: WakeConformanceAdapter;
+}
+export declare const HEARTBEAT_MS = 60000;
+export declare const cutStore: (op: StoreWritePoint["op"], at: StoreWritePoint["at"], nth?: number) => DurableStoreOptions;
+export declare const cutAlarm: (op: WakeAlarmPoint["op"], at: WakeAlarmPoint["at"], nth?: number) => WakeAlarmOptions;
+export declare const cutWake: (op: WakePoint["op"], nth?: number) => ((point: WakePoint) => void);
+export declare function expectWakeCut(operation: Promise<unknown>, what: string): Promise<void>;
+export interface SessionInstance {
+    readonly loop: TestLoop;
+    readonly host: WakeHost;
+}
+export interface BootOptions {
+    readonly store?: DurableStoreOptions;
+    readonly alarm?: WakeAlarmOptions;
+    readonly onWakePoint?: (point: WakePoint) => void;
+}
+/** One session on the host: its medium, its live instance (if any), and what the cases observe. */
+export interface SessionSlot {
+    /** The clock time the slot was created at; trace times are relative to it. */
+    readonly base: number;
+    /** Durable alarm writes (`set:+ms` / `clear`) and `resume` calls, in order, across instances. */
+    readonly trace: string[];
+    /** The live instance; with none, boot one (open + `start`) with `options`. */
+    instance(options?: BootOptions): Promise<SessionInstance>;
+    /** Drop the live instance, as an eviction or crash does. */
+    kill(): void;
+    /** Alarm fires delivered to this session. */
+    fires(): number;
+    /** Task IDs the loop committed as run, in commit order. */
+    ran(): Promise<string[]>;
+    /** The durable alarm, relative to `base`; undefined when cleared. */
+    alarmAt(): Promise<number | undefined>;
+}
+export declare function createSlot(adapters: WakeCaseAdapters, epoch?: number): Promise<SessionSlot>;
+/** Restart the host process: every slot loses its live instance; durable state stays. */
+export declare function restartHost(adapters: WakeCaseAdapters, slots: readonly SessionSlot[]): Promise<void>;
+//# sourceMappingURL=wake-harness.d.ts.map

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

@@ -0,0 +1,127 @@
+import { createWakeHost, } from "../wake-host.js";
+import { openTestLoop } from "./wake-test-loop.js";
+export const HEARTBEAT_MS = 60_000;
+/** A simulated kill inside a wake case; every cut in these cases throws it. */
+class WakeCut extends Error {
+    constructor(where) {
+        super(`cut at ${where}`);
+        this.name = "WakeCut";
+    }
+}
+const isCut = (error) => error instanceof WakeCut;
+/** Throw a WakeCut the `nth` time `matches` sees a point (1-based). */
+function cutNth(matches, nth) {
+    let seen = 0;
+    return (point) => {
+        if (matches(point) && ++seen === nth)
+            throw new WakeCut(JSON.stringify(point));
+    };
+}
+export const cutStore = (op, at, nth = 1) => ({
+    onWritePoint: cutNth((point) => point.op === op && point.at === at, nth),
+});
+export const cutAlarm = (op, at, nth = 1) => ({
+    onAlarmPoint: cutNth((point) => point.op === op && point.at === at, nth),
+});
+export const cutWake = (op, nth = 1) => cutNth((point) => point.op === op, nth);
+export async function expectWakeCut(operation, what) {
+    try {
+        await operation;
+    }
+    catch (error) {
+        if (isCut(error))
+            return;
+        throw new Error(`${what}: expected the cut to surface, got ${String(error)}`);
+    }
+    throw new Error(`${what}: expected the cut to surface, but it resolved`);
+}
+export async function createSlot(adapters, epoch = 1) {
+    const { store: storeAdapter, wake } = adapters;
+    const medium = await storeAdapter.createMedium();
+    const reader = await storeAdapter.open(medium);
+    for (let next = 1; next <= epoch; next++)
+        await reader.claim(next - 1, next);
+    const base = wake.now();
+    const trace = [];
+    let live;
+    let alarm;
+    let fires = 0;
+    const record = (options) => ({
+        onAlarmPoint: (point) => {
+            options?.onAlarmPoint?.(point);
+            if (point.at === "durable")
+                trace.push(point.op === "clear" ? "clear" : `set:+${(point.time ?? 0) - base}`);
+        },
+    });
+    async function boot(options = {}) {
+        const store = await storeAdapter.open(medium, options.store);
+        let host;
+        const loop = await openTestLoop(store, epoch, wake.now, async () => host?.update(loop.wake()));
+        alarm = await wake.openAlarm({
+            medium,
+            store: await storeAdapter.open(medium),
+            epoch,
+            onFire: dispatch,
+            options: record(options.alarm),
+        });
+        host = createWakeHost({
+            alarm,
+            now: wake.now,
+            wake: () => loop.wake(),
+            resume: async () => {
+                trace.push("resume");
+                await loop.resume();
+            },
+            heartbeatMs: HEARTBEAT_MS,
+            onWakePoint: options.onWakePoint,
+        });
+        const instance = { loop, host };
+        live = instance;
+        await host.start();
+        return instance;
+    }
+    async function dispatch() {
+        fires++;
+        try {
+            const instance = live ?? (await boot());
+            await instance.host.fire();
+        }
+        catch (error) {
+            if (!isCut(error))
+                throw error;
+            live = undefined;
+        }
+    }
+    return {
+        base,
+        trace,
+        async instance(options) {
+            if (live !== undefined)
+                return live;
+            try {
+                return await boot(options);
+            }
+            catch (error) {
+                if (isCut(error))
+                    live = undefined;
+                throw error;
+            }
+        },
+        kill: () => {
+            live = undefined;
+        },
+        fires: () => fires,
+        ran: async () => (await reader.scanRecords({ kind: "ran" })).map((record) => record.id.slice("ran:".length)),
+        alarmAt: async () => {
+            const at = await alarm?.read();
+            return at === undefined ? undefined : at - base;
+        },
+    };
+}
+/** Restart the host process: every slot loses its live instance; durable state stays. */
+export async function restartHost(adapters, slots) {
+    await adapters.wake.restart();
+    for (const slot of slots)
+        slot.kill();
+}
+//# sourceMappingURL=wake-harness.js.map

package/dist/durable/testing/wake-test-loop.d.ts

@@ -0,0 +1,13 @@
+import type { DurableStore } from "../store.ts";
+import type { Wake } from "../wake-host.ts";
+/** A minimal loop over the store: tasks due at a time, each run in one commit. Enough to observe wake ordering. */
+export interface TestLoop {
+    /** Schedule task `id` at `due`, in one commit. */
+    schedule(id: string, due: number): Promise<void>;
+    /** Run every due task, one commit each: a `ran` record and the task's removal, atomically. */
+    resume(): Promise<void>;
+    /** `active` while a task is due now; `at`, the earliest task due later. */
+    wake(): Wake;
+}
+export declare function openTestLoop(store: DurableStore, epoch: number, now: () => number, committed: () => Promise<void>): Promise<TestLoop>;
+//# sourceMappingURL=wake-test-loop.d.ts.map

package/dist/durable/testing/wake-test-loop.js

@@ -0,0 +1,40 @@
+import { createAdmissionLine } from "../store-admission.js";
+const TASK_PREFIX = "task/";
+export async function openTestLoop(store, epoch, now, committed) {
+    const line = createAdmissionLine();
+    const tasks = new Map();
+    for (const document of await store.scanDocuments(TASK_PREFIX)) {
+        if (typeof document.data === "number")
+            tasks.set(document.key.slice(TASK_PREFIX.length), document.data);
+    }
+    const commit = async (writes, adopt) => {
+        await store.commit(epoch, writes, adopt);
+        await committed();
+    };
+    return {
+        schedule: (id, due) => line.admit(() => commit([{ op: "put", key: TASK_PREFIX + id, data: due }], () => void tasks.set(id, due))),
+        resume: () => line.admit(async () => {
+            const due = [...tasks].filter(([, at]) => at <= now()).sort(([a, x], [b, y]) => x - y || (a < b ? -1 : 1));
+            for (const [id] of due) {
+                const writes = [
+                    { op: "append", id: `ran:${id}`, kind: "ran", data: { id } },
+                    { op: "delete", key: TASK_PREFIX + id },
+                ];
+                await commit(writes, () => void tasks.delete(id));
+            }
+        }),
+        wake: () => {
+            const time = now();
+            let active = false;
+            let at;
+            for (const due of tasks.values()) {
+                if (due <= time)
+                    active = true;
+                else if (at === undefined || due < at)
+                    at = due;
+            }
+            return at === undefined ? { active } : { active, at };
+        },
+    };
+}
+//# sourceMappingURL=wake-test-loop.js.map

package/dist/durable/wake-host-bun-timer.d.ts

@@ -0,0 +1,31 @@
+import type { WakeAlarm, WakeAlarmOptions } from "./wake-host.ts";
+import type { AlarmPersistence } from "./wake-host-store-alarm.ts";
+/** Schedule `callback` after `ms`; returns its cancel. */
+export type SetTimer = (callback: () => unknown, ms: number) => () => void;
+export interface BunTimerHostOptions {
+    readonly now?: () => number;
+    readonly setTimer?: SetTimer;
+    /**
+     * The longest single timer. Monotonic timers stop while a machine sleeps, so a far alarm re-checks the wall clock
+     * at least this often and an alarm that fell due during a sleep fires within this bound of waking. Default 60 s.
+     */
+    readonly maxDelayMs?: number;
+    /** A fire handler rejected. The alarm stays armed and fires again after `maxDelayMs`. */
+    readonly onFireError: (key: string, error: unknown) => void;
+}
+/**
+ * The Bun process timer host: one instance serves every session of the process, each under its own key, with its
+ * alarm persisted (normally `storeAlarmPersistence`). After a process restart the embedding host opens its sessions'
+ * alarms again; an alarm that fell due meanwhile fires at once.
+ */
+export interface BunTimerHost {
+    /**
+     * The alarm of session `key`, read from `persistence`. Opening a key again replaces the earlier instance: fires go
+     * to the newest `onFire`, and the replaced instance's writes are refused.
+     */
+    openAlarm(key: string, persistence: AlarmPersistence, onFire: () => Promise<void>, options?: WakeAlarmOptions): Promise<WakeAlarm>;
+    /** Cancel every timer. Persisted alarms stay. */
+    close(): void;
+}
+export declare function createBunTimerHost(options: BunTimerHostOptions): BunTimerHost;
+//# sourceMappingURL=wake-host-bun-timer.d.ts.map