@iterativeflow/conformance 2.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+import { Backend, Queue, Store, Timer, Wakeup } from "@iterativeflow/core/backend";
+//#region src/store.d.ts
+/**
+ * The Store contract as executable invariants. EVERY backend (in-memory, Postgres,
+ * DynamoDB) is run against this exact suite — a backend is not "done" until green here.
+ * The guarantee is a test, not a comment.
+ */
+declare const storeConformance: (label: string, makeStore: () => Store | Promise<Store>) => void;
+//#endregion
+//#region src/queue.d.ts
+/**
+ * The Queue contract as executable invariants. The universal lease-CAS backend and a
+ * Postgres `SKIP LOCKED` backend must both satisfy exactly these — leasing is exclusive,
+ * leases expire and re-claim (crash recovery), heartbeats extend, and a stale ack is a
+ * no-op. Clock is injected so the suite is deterministic on any backend.
+ */
+declare const queueConformance: (label: string, makeQueue: () => Queue | Promise<Queue>) => void;
+//#endregion
+//#region src/timer.d.ts
+/**
+ * The Timer contract as executable invariants — durable deadlines that fire exactly once,
+ * earliest first, with upsert-reschedule and cancel. Clock injected for determinism.
+ */
+declare const timerConformance: (label: string, makeTimer: () => Timer | Promise<Timer>) => void;
+//#endregion
+//#region src/wakeup.d.ts
+/**
+ * The Wakeup contract as executable invariants: a signal wakes current waiters early, a
+ * missing signal still resolves on timeout (the poll tick), and a signal for another run
+ * doesn't wake unrelated waiters.
+ */
+declare const wakeupConformance: (label: string, makeWakeup: () => Wakeup | Promise<Wakeup>) => void;
+//#endregion
+//#region src/outbox.d.ts
+/**
+ * The transactional-outbox seam as executable invariants: a durable Store write and the
+ * side-effects it carries commit together, and — critically — the outbox fires exactly
+ * ONCE even when the write is replayed. Every backend (memory, Postgres, DynamoDB) must
+ * satisfy this; it is the property that makes crash recovery correct rather than just
+ * plausible.
+ */
+declare const outboxConformance: (label: string, makeBackend: () => Backend | Promise<Backend>) => void;
+//#endregion
+//#region src/signal.d.ts
+/**
+ * The durable signal inbox as executable invariants: a delivered signal lands in `loadRun`,
+ * wakes the run (re-enqueue), is idempotent on its key, and is consumed exactly once by a
+ * checkpoint's `consumeSignals` outbox.
+ */
+declare const signalConformance: (label: string, makeBackend: () => Backend | Promise<Backend>) => void;
+//#endregion
+//#region src/reconcile.d.ts
+/**
+ * `orphanedRuns` as executable invariants — what the reconciler re-drives. A run is an orphan
+ * only when it truly can't make progress on its own: non-terminal but off the queue with no
+ * pending timer, OR an `awaiting_signal` parent whose child already finished (lost wake). A
+ * run that is queued, timing, terminal, or legitimately waiting on an external signal is NOT.
+ */
+declare const reconcileConformance: (label: string, makeBackend: () => Backend | Promise<Backend>) => void;
+//#endregion
+//#region src/cron.d.ts
+/**
+ * The cron store surface as executable invariants: upsert keeps timing on re-register,
+ * `dueCrons` respects `nextRunAt`, and `advanceCron` is a CAS so exactly one worker fires an
+ * occurrence (the double-fire guard on a fleet).
+ */
+declare const cronConformance: (label: string, makeStore: () => Store | Promise<Store>) => void;
+//#endregion
+export { cronConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/dist/index.mjs

@@ -0,0 +1,1303 @@
+import { describe, expect, it } from "vitest";
+//#region src/store.ts
+/**
+* The Store contract as executable invariants. EVERY backend (in-memory, Postgres,
+* DynamoDB) is run against this exact suite — a backend is not "done" until green here.
+* The guarantee is a test, not a comment.
+*/
+const storeConformance = (label, makeStore) => {
+	describe(`Store conformance — ${label}`, () => {
+		it("startRun creates a fresh pending run", async () => {
+			const s = await makeStore();
+			const r = await s.startRun({
+				name: "f",
+				version: 1,
+				input: { a: 1 }
+			});
+			expect(r.created).toBe(true);
+			expect(r.status).toBe("pending");
+			const snap = await s.loadRun(r.runId);
+			expect(snap?.run.status).toBe("pending");
+			expect(snap?.run.input).toEqual({ a: 1 });
+			expect(snap?.run.attempts).toBe(0);
+		});
+		it("startManyRuns creates the whole batch, results aligned with the specs", async () => {
+			const s = await makeStore();
+			const specs = [
+				{
+					name: "f",
+					version: 1,
+					input: { i: 0 }
+				},
+				{
+					name: "g",
+					version: 2,
+					input: { i: 1 }
+				},
+				{
+					name: "h",
+					version: 1,
+					input: { i: 2 }
+				}
+			];
+			const results = await s.startManyRuns(specs);
+			expect(results).toHaveLength(3);
+			expect(results.every((r) => r.created)).toBe(true);
+			for (let i = 0; i < specs.length; i++) {
+				const snap = await s.loadRun(results[i].runId);
+				expect(snap?.run.input).toEqual({ i });
+				expect(snap?.run.name).toBe(specs[i].name);
+			}
+		});
+		it("startManyRuns honours per-spec idempotency — a batch can mix created and existing", async () => {
+			const s = await makeStore();
+			const first = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "dup"
+			});
+			const results = await s.startManyRuns([{
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "dup"
+			}, {
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "new"
+			}]);
+			expect(results[0]).toMatchObject({
+				runId: first.runId,
+				created: false
+			});
+			expect(results[1].created).toBe(true);
+			expect(results[1].runId).not.toBe(first.runId);
+		});
+		it("startRun is idempotent on the idempotency key — no duplicate run", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "k"
+			});
+			const b = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "k"
+			});
+			expect(a.created).toBe(true);
+			expect(b.created).toBe(false);
+			expect(b.runId).toBe(a.runId);
+		});
+		it("idempotency key is scoped by (name, version)", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "k"
+			});
+			expect((await s.startRun({
+				name: "f",
+				version: 2,
+				input: {},
+				idempotencyKey: "k"
+			})).runId).not.toBe(a.runId);
+		});
+		it("loadRun returns undefined for an unknown run", async () => {
+			expect(await (await makeStore()).loadRun("00000000-0000-0000-0000-000000000000")).toBeUndefined();
+		});
+		it("checkpointStep persists a completed step into the memo", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 42,
+				attempts: 1
+			});
+			expect((await s.loadRun(runId))?.steps.get("a")).toMatchObject({
+				status: "ok",
+				result: 42,
+				attempts: 1
+			});
+		});
+		it("checkpointStep is first-writer-wins — a second write does NOT overwrite (exactly-once memo)", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			const first = await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: "first",
+				attempts: 1
+			});
+			const second = await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: "SECOND",
+				attempts: 2
+			});
+			expect(first.result).toBe("first");
+			expect(second.result).toBe("first");
+			expect((await s.loadRun(runId))?.steps.get("a")?.result).toBe("first");
+		});
+		it("markRunning increments attempts (bounded retries survive crashes)", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			expect(await s.markRunning(runId)).toBe(1);
+			expect(await s.markRunning(runId)).toBe(2);
+			expect((await s.loadRun(runId))?.run.attempts).toBe(2);
+		});
+		it("markRunning never resurrects a terminal run (a late re-dispatch can't undo a cancel)", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.markTerminal(runId, { status: "canceled" });
+			await s.markRunning(runId);
+			expect((await s.loadRun(runId))?.run.status).toBe("canceled");
+		});
+		it("markTerminal sets status + output", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.markTerminal(runId, {
+				status: "done",
+				output: "out"
+			});
+			const snap = await s.loadRun(runId);
+			expect(snap?.run.status).toBe("done");
+			expect(snap?.run.output).toBe("out");
+		});
+		it("markTerminal never overrides a canceled run", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "g",
+				version: 1,
+				input: {}
+			});
+			await s.markTerminal(runId, { status: "canceled" });
+			await s.markTerminal(runId, {
+				status: "done",
+				output: "late"
+			});
+			expect((await s.loadRun(runId))?.run.status).toBe("canceled");
+		});
+		it("checkpointStep round-trips a failed_terminal outcome with its error", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "failed_terminal",
+				error: {
+					code: "BOOM",
+					message: "boom"
+				},
+				attempts: 1
+			});
+			expect((await s.loadRun(runId))?.steps.get("a")).toMatchObject({
+				status: "failed_terminal",
+				error: {
+					code: "BOOM",
+					message: "boom"
+				}
+			});
+		});
+		it("first-writer-wins holds across status — a later ok cannot overwrite a failed_terminal", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "failed_terminal",
+				error: {
+					code: "BOOM",
+					message: "boom"
+				},
+				attempts: 1
+			});
+			expect((await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 1,
+				attempts: 2
+			})).status).toBe("failed_terminal");
+			expect((await s.loadRun(runId))?.steps.get("a")?.status).toBe("failed_terminal");
+		});
+		it("checkpointStep on an unknown run is rejected (no orphan step)", async () => {
+			await expect((await makeStore()).checkpointStep({
+				runId: "nope",
+				cursorKey: "a",
+				status: "ok",
+				result: 1,
+				attempts: 1
+			})).rejects.toThrow();
+		});
+		it("startRun on an idempotency hit returns the run's CURRENT status", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "k"
+			});
+			await s.markTerminal(a.runId, {
+				status: "done",
+				output: 1
+			});
+			const b = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "k"
+			});
+			expect(b.created).toBe(false);
+			expect(b.status).toBe("done");
+		});
+		it("tags round-trip", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				tags: ["x", "y"]
+			});
+			expect((await s.loadRun(runId))?.run.tags).toEqual(["x", "y"]);
+		});
+		it("mutating a snapshot's run/step VALUES can't corrupt the store", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: { n: 1 }
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: { v: 1 },
+				attempts: 1
+			});
+			const snap = await s.loadRun(runId);
+			snap.run.input.n = 999;
+			snap.steps.get("a").result.v = 999;
+			snap.steps.clear();
+			const again = await s.loadRun(runId);
+			expect(again.run.input.n).toBe(1);
+			expect(again.steps.get("a").result.v).toBe(1);
+		});
+		it("caller mutating the input after startRun can't reach the stored run", async () => {
+			const s = await makeStore();
+			const input = { n: 1 };
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input
+			});
+			input.n = 999;
+			expect((await s.loadRun(runId))?.run.input).toEqual({ n: 1 });
+		});
+		it("listRuns returns newest-first and filters by status, name, and tag", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "alpha",
+				version: 1,
+				input: {},
+				tags: ["t1"]
+			});
+			const b = await s.startRun({
+				name: "beta",
+				version: 1,
+				input: {},
+				tags: ["t2"]
+			});
+			await s.startRun({
+				name: "alpha",
+				version: 1,
+				input: {},
+				tags: ["t1"]
+			});
+			await s.markTerminal(b.runId, {
+				status: "done",
+				output: 1
+			});
+			const all = await s.listRuns({}, { limit: 10 });
+			expect(all.runs).toHaveLength(3);
+			expect(all.runs[0].id).not.toBe(a.runId);
+			expect((await s.listRuns({ name: "alpha" }, { limit: 10 })).runs.map((r) => r.name)).toEqual(["alpha", "alpha"]);
+			expect((await s.listRuns({ status: "done" }, { limit: 10 })).runs.map((r) => r.id)).toEqual([b.runId]);
+			expect((await s.listRuns({ tag: "t2" }, { limit: 10 })).runs.map((r) => r.id)).toEqual([b.runId]);
+		});
+		it("listRuns paginates with a cursor", async () => {
+			const s = await makeStore();
+			for (let i = 0; i < 5; i++) await s.startRun({
+				name: "f",
+				version: 1,
+				input: { i }
+			});
+			const first = await s.listRuns({}, { limit: 2 });
+			expect(first.runs).toHaveLength(2);
+			expect(first.cursor).toBeDefined();
+			const second = await s.listRuns({}, {
+				limit: 2,
+				cursor: first.cursor
+			});
+			expect(second.runs).toHaveLength(2);
+			expect(new Set([...first.runs, ...second.runs].map((r) => r.id)).size).toBe(4);
+		});
+		it("childrenOf returns the runs spawned under a parent", async () => {
+			const s = await makeStore();
+			const parent = await s.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			const c1 = await s.startRun({
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			});
+			const c2 = await s.startRun({
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			});
+			await s.startRun({
+				name: "unrelated",
+				version: 1,
+				input: {}
+			});
+			const kids = await s.childrenOf(parent.runId);
+			expect(new Set(kids.map((r) => r.id))).toEqual(/* @__PURE__ */ new Set([c1.runId, c2.runId]));
+		});
+		it("retryRun re-drives a failed run and keeps its ok step memos", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 7,
+				attempts: 1
+			});
+			await s.markTerminal(runId, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "boom"
+				}
+			});
+			expect((await s.retryRun(runId)).retried).toBe(true);
+			const snap = await s.loadRun(runId);
+			expect(snap?.run.status).toBe("pending");
+			expect(snap?.run.error).toBeUndefined();
+			expect(snap?.steps.get("a")?.result).toBe(7);
+			expect((await s.retryRun(runId)).retried).toBe(false);
+		});
+		it("runStats counts runs per status", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.markTerminal(a.runId, {
+				status: "done",
+				output: 1
+			});
+			const stats = await s.runStats();
+			expect(stats.pending).toBe(1);
+			expect(stats.done).toBe(1);
+			expect(stats.failed).toBe(0);
+		});
+	});
+};
+//#endregion
+//#region src/clock.ts
+/** @internal */
+const T0 = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+/** @internal */
+const at = (ms) => new Date(T0.getTime() + ms);
+//#endregion
+//#region src/queue.ts
+/**
+* The Queue contract as executable invariants. The universal lease-CAS backend and a
+* Postgres `SKIP LOCKED` backend must both satisfy exactly these — leasing is exclusive,
+* leases expire and re-claim (crash recovery), heartbeats extend, and a stale ack is a
+* no-op. Clock is injected so the suite is deterministic on any backend.
+*/
+const queueConformance = (label, makeQueue) => {
+	describe(`Queue conformance — ${label}`, () => {
+		it("enqueue then claim returns the run with a lease", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const leases = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
+			expect(leases[0].token).toBeTruthy();
+			expect(leases[0].expiresAt.getTime()).toBe(at(1e3).getTime());
+		});
+		it("a future runAt is not claimable until due", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1", { runAt: at(5e3) });
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).toEqual([]);
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(5e3)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("a claimed run is leased exclusively — a second claim before expiry gets nothing", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).toHaveLength(1);
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(500)
+			})).toEqual([]);
+		});
+		it("an expired lease is re-claimable (crash recovery), with a fresh token", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const first = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			const reclaim = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1001)
+			});
+			expect(reclaim.map((l) => l.runId)).toEqual(["r1"]);
+			expect(reclaim[0].token).not.toBe(first[0].token);
+		});
+		it("heartbeat extends the lease so it isn't re-claimed at the original expiry", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.heartbeat(lease, {
+				leaseMs: 1e3,
+				now: at(500)
+			});
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1001)
+			})).toEqual([]);
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1501)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("heartbeat on a lost (re-claimed) lease throws", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [stale] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1001)
+			});
+			await expect(q.heartbeat(stale, {
+				leaseMs: 1e3,
+				now: at(1002)
+			})).rejects.toThrow();
+		});
+		it("ack removes the run so it isn't claimed again", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.ack(lease, { now: at(1) });
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(2e3)
+			})).toEqual([]);
+		});
+		it("a stale ack is a no-op — it does not delete the run the new owner holds", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [stale] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1001)
+			});
+			await q.ack(stale, { now: at(1002) });
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(2002)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("a wake that re-enqueues during a lease survives the ack — the job is released, not deleted", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.enqueue("r1");
+			await q.ack(lease, { now: at(1) });
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(2)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("an expired ack is a no-op — an expired owner can't delete a re-claimable run", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.ack(lease, { now: at(1001) });
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1002)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("heartbeat after expiry throws (lease lost even without a re-claim)", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await expect(q.heartbeat(lease, {
+				leaseMs: 1e3,
+				now: at(1001)
+			})).rejects.toThrow();
+		});
+		it("re-enqueue does not yank an active lease from the current worker", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.enqueue("r1", { priority: 1 });
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(500)
+			})).toEqual([]);
+		});
+		it("release makes the run immediately re-claimable without waiting out the lease", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.release(lease, { now: at(100) });
+			const again = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(200)
+			});
+			expect(again.map((l) => l.runId)).toEqual(["r1"]);
+			expect(again[0].token).not.toBe(lease.token);
+		});
+		it("a stale release is a no-op — it can't unseat the current owner", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [stale] = await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1001)
+			});
+			await q.release(stale, { now: at(1002) });
+			expect(await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(1003)
+			})).toEqual([]);
+		});
+		it("claim honours the batch max", async () => {
+			const q = await makeQueue();
+			for (let i = 0; i < 5; i++) await q.enqueue(`r${i}`);
+			expect(await q.claim({
+				max: 2,
+				leaseMs: 1e3,
+				now: at(0)
+			})).toHaveLength(2);
+		});
+		it("lower priority is claimed first", async () => {
+			const q = await makeQueue();
+			await q.enqueue("low", { priority: 10 });
+			await q.enqueue("high", { priority: 1 });
+			const [first] = await q.claim({
+				max: 1,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(first.runId).toBe("high");
+		});
+		it("re-enqueue is an upsert keyed by runId — claimed once", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			await q.enqueue("r1", { priority: 5 });
+			expect((await q.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+		});
+	});
+};
+//#endregion
+//#region src/timer.ts
+/**
+* The Timer contract as executable invariants — durable deadlines that fire exactly once,
+* earliest first, with upsert-reschedule and cancel. Clock injected for determinism.
+*/
+const timerConformance = (label, makeTimer) => {
+	describe(`Timer conformance — ${label}`, () => {
+		it("a scheduled timer is due once its fireAt has passed", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("r1", at(1e3));
+			expect(await tm.dueBatch({
+				now: at(999),
+				max: 10
+			})).toEqual([]);
+			expect(await tm.dueBatch({
+				now: at(1e3),
+				max: 10
+			})).toEqual(["r1"]);
+		});
+		it("dueBatch fires exactly once — a consumed timer is not returned again", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("r1", at(0));
+			expect(await tm.dueBatch({
+				now: at(1),
+				max: 10
+			})).toEqual(["r1"]);
+			expect(await tm.dueBatch({
+				now: at(2),
+				max: 10
+			})).toEqual([]);
+		});
+		it("reschedule is an upsert — the latest fireAt wins", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("r1", at(1e3));
+			await tm.schedule("r1", at(5e3));
+			expect(await tm.dueBatch({
+				now: at(2e3),
+				max: 10
+			})).toEqual([]);
+			expect(await tm.dueBatch({
+				now: at(5e3),
+				max: 10
+			})).toEqual(["r1"]);
+		});
+		it("reschedule EARLIER also wins — upsert, not a LEAST(fire_at) merge", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("r1", at(5e3));
+			await tm.schedule("r1", at(1e3));
+			expect(await tm.dueBatch({
+				now: at(1e3),
+				max: 10
+			})).toEqual(["r1"]);
+		});
+		it("cancel removes a pending timer", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("r1", at(1e3));
+			await tm.cancel("r1");
+			expect(await tm.dueBatch({
+				now: at(2e3),
+				max: 10
+			})).toEqual([]);
+		});
+		it("dueBatch honours max and returns earliest-first", async () => {
+			const tm = await makeTimer();
+			await tm.schedule("late", at(300));
+			await tm.schedule("early", at(100));
+			await tm.schedule("mid", at(200));
+			expect(await tm.dueBatch({
+				now: at(1e3),
+				max: 2
+			})).toEqual(["early", "mid"]);
+		});
+	});
+};
+//#endregion
+//#region src/wakeup.ts
+/**
+* The Wakeup contract as executable invariants: a signal wakes current waiters early, a
+* missing signal still resolves on timeout (the poll tick), and a signal for another run
+* doesn't wake unrelated waiters.
+*/
+const wakeupConformance = (label, makeWakeup) => {
+	describe(`Wakeup conformance — ${label}`, () => {
+		it("signal wakes a pending waiter early", async () => {
+			const w = await makeWakeup();
+			let resolved = false;
+			const p = w.wait("r1", 5e3).then(() => {
+				resolved = true;
+			});
+			await w.signal("r1");
+			await p;
+			expect(resolved).toBe(true);
+		});
+		it("wait resolves on timeout when no signal arrives (the poll tick)", async () => {
+			const w = await makeWakeup();
+			const start = Date.now();
+			await w.wait("r1", 25);
+			expect(Date.now() - start).toBeGreaterThanOrEqual(20);
+		});
+		it("a signal for another run does not wake the waiter early", async () => {
+			const w = await makeWakeup();
+			let resolved = false;
+			const p = w.wait("r1", 60).then(() => {
+				resolved = true;
+			});
+			await w.signal("r2");
+			await new Promise((r) => setTimeout(r, 15));
+			expect(resolved).toBe(false);
+			await p;
+			expect(resolved).toBe(true);
+		});
+		it("signal is a no-op when there are no waiters", async () => {
+			await expect((await makeWakeup()).signal("nobody")).resolves.toBeUndefined();
+		});
+		it("is edge-triggered — a signal before any waiter does not latch", async () => {
+			const w = await makeWakeup();
+			await w.signal("r1");
+			const start = Date.now();
+			await w.wait("r1", 25);
+			expect(Date.now() - start).toBeGreaterThanOrEqual(20);
+		});
+		it("multiple waiters on the same run all wake on one signal", async () => {
+			const w = await makeWakeup();
+			let woke = 0;
+			const ps = [w.wait("r1", 5e3), w.wait("r1", 5e3)].map((p) => p.then(() => {
+				woke += 1;
+			}));
+			await w.signal("r1");
+			await Promise.all(ps);
+			expect(woke).toBe(2);
+		});
+	});
+};
+//#endregion
+//#region src/outbox.ts
+/**
+* The transactional-outbox seam as executable invariants: a durable Store write and the
+* side-effects it carries commit together, and — critically — the outbox fires exactly
+* ONCE even when the write is replayed. Every backend (memory, Postgres, DynamoDB) must
+* satisfy this; it is the property that makes crash recovery correct rather than just
+* plausible.
+*/
+const outboxConformance = (label, makeBackend) => {
+	describe(`Outbox conformance — ${label}`, () => {
+		it("checkpointStep commits its enqueue atomically — the run is claimable after", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 1,
+				attempts: 1
+			}, { enqueue: [{ runId }] });
+			expect((await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).map((l) => l.runId)).toEqual([runId]);
+		});
+		it("checkpointStep spawns a child run + enqueues it atomically", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "parent",
+				version: 1,
+				input: {}
+			});
+			const childId = "11111111-1111-1111-1111-111111111111";
+			await store.checkpointStep({
+				runId,
+				cursorKey: "spawn",
+				status: "ok",
+				result: childId,
+				attempts: 1
+			}, { spawn: [{
+				runId: childId,
+				spec: {
+					name: "child",
+					version: 1,
+					input: { n: 1 }
+				}
+			}] });
+			expect((await store.loadRun(childId))?.run.input).toEqual({ n: 1 });
+			expect((await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).map((l) => l.runId)).toContain(childId);
+		});
+		it("a replayed checkpoint does NOT re-fire the outbox — the child spawns exactly once", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "parent",
+				version: 1,
+				input: {}
+			});
+			const childId = "22222222-2222-2222-2222-222222222222";
+			const spawn = { spawn: [{
+				runId: childId,
+				spec: {
+					name: "child",
+					version: 1,
+					input: {}
+				}
+			}] };
+			await store.checkpointStep({
+				runId,
+				cursorKey: "spawn",
+				status: "ok",
+				result: childId,
+				attempts: 1
+			}, spawn);
+			await store.checkpointStep({
+				runId,
+				cursorKey: "spawn",
+				status: "ok",
+				result: childId,
+				attempts: 2
+			}, spawn);
+			expect((await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).filter((l) => l.runId === childId)).toHaveLength(1);
+		});
+		it("suspendRun(sleeping) sets status + wake timer atomically", async () => {
+			const { store, timer } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markRunning(runId);
+			await store.suspendRun(runId, "sleeping", { timers: [{
+				runId,
+				fireAt: at(5e3)
+			}] });
+			expect((await store.loadRun(runId))?.run.status).toBe("sleeping");
+			expect(await timer.dueBatch({
+				now: at(4999),
+				max: 10
+			})).toEqual([]);
+			expect(await timer.dueBatch({
+				now: at(5e3),
+				max: 10
+			})).toEqual([runId]);
+		});
+		it("suspendRun is a no-op on a terminal run — no zombie wake timer", async () => {
+			const { store, timer } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markTerminal(runId, {
+				status: "done",
+				output: 1
+			});
+			await store.suspendRun(runId, "sleeping", { timers: [{
+				runId,
+				fireAt: at(5e3)
+			}] });
+			expect((await store.loadRun(runId))?.run.status).toBe("done");
+			expect(await timer.dueBatch({
+				now: at(5e3),
+				max: 10
+			})).toEqual([]);
+		});
+		it("markTerminal wakes a suspended parent atomically (enqueue in the same write)", async () => {
+			const { store, queue } = await makeBackend();
+			const parent = await store.startRun({
+				name: "parent",
+				version: 1,
+				input: {}
+			});
+			const child = await store.startRun({
+				name: "child",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			});
+			await store.markTerminal(child.runId, {
+				status: "done",
+				output: 7
+			}, { enqueue: [{ runId: parent.runId }] });
+			expect((await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).map((l) => l.runId)).toContain(parent.runId);
+		});
+		it("markTerminal cancels a pending timer atomically (no stale wake after completion)", async () => {
+			const { store, timer } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markRunning(runId);
+			await store.suspendRun(runId, "awaiting_signal", { timers: [{
+				runId,
+				fireAt: at(5e3)
+			}] });
+			await store.markTerminal(runId, {
+				status: "done",
+				output: 1
+			}, { cancelTimers: [runId] });
+			expect(await timer.dueBatch({
+				now: at(5e3),
+				max: 10
+			})).toEqual([]);
+		});
+		it("a canceled run's markTerminal is sticky AND skips its outbox", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markTerminal(runId, { status: "canceled" });
+			await store.markTerminal(runId, {
+				status: "done",
+				output: 1
+			}, { enqueue: [{ runId }] });
+			expect((await store.loadRun(runId))?.run.status).toBe("canceled");
+			expect(await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).toEqual([]);
+		});
+	});
+};
+//#endregion
+//#region src/signal.ts
+/**
+* The durable signal inbox as executable invariants: a delivered signal lands in `loadRun`,
+* wakes the run (re-enqueue), is idempotent on its key, and is consumed exactly once by a
+* checkpoint's `consumeSignals` outbox.
+*/
+const signalConformance = (label, makeBackend) => {
+	describe(`Signal conformance — ${label}`, () => {
+		it("postSignal delivers into the inbox and wakes the run (re-enqueue)", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			expect((await store.postSignal(runId, "approve", { ok: true })).delivered).toBe(true);
+			expect((await store.loadRun(runId))?.signals.map((s) => ({
+				name: s.name,
+				payload: s.payload
+			}))).toEqual([{
+				name: "approve",
+				payload: { ok: true }
+			}]);
+			expect((await queue.claim({
+				max: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).map((l) => l.runId)).toEqual([runId]);
+		});
+		it("postSignal is idempotent on its key — a retried delivery lands once", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			const a = await store.postSignal(runId, "x", 1, { idempotencyKey: "k" });
+			const b = await store.postSignal(runId, "x", 1, { idempotencyKey: "k" });
+			expect(a.delivered).toBe(true);
+			expect(b.delivered).toBe(false);
+			expect((await store.loadRun(runId))?.signals).toHaveLength(1);
+		});
+		it("consumeSignals drains exactly the referenced signal, atomically with the checkpoint", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.postSignal(runId, "a", "first");
+			await store.postSignal(runId, "b", "second");
+			const target = (await store.loadRun(runId))?.signals.find((s) => s.name === "a");
+			await store.checkpointStep({
+				runId,
+				cursorKey: "wait",
+				status: "ok",
+				result: "first",
+				attempts: 1
+			}, { consumeSignals: [target.id] });
+			const after = await store.loadRun(runId);
+			expect(after?.signals.map((s) => s.name)).toEqual(["b"]);
+			expect(after?.steps.get("wait")?.result).toBe("first");
+		});
+		it("distinct signals to a run preserve delivery order in the inbox", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.postSignal(runId, "s", 1);
+			await store.postSignal(runId, "s", 2);
+			await store.postSignal(runId, "s", 3);
+			expect((await store.loadRun(runId))?.signals.map((s) => s.payload)).toEqual([
+				1,
+				2,
+				3
+			]);
+		});
+	});
+};
+//#endregion
+//#region src/reconcile.ts
+/**
+* `orphanedRuns` as executable invariants — what the reconciler re-drives. A run is an orphan
+* only when it truly can't make progress on its own: non-terminal but off the queue with no
+* pending timer, OR an `awaiting_signal` parent whose child already finished (lost wake). A
+* run that is queued, timing, terminal, or legitimately waiting on an external signal is NOT.
+*/
+const reconcileConformance = (label, makeBackend) => {
+	describe(`Reconcile conformance — ${label}`, () => {
+		it("a non-terminal run with no job and no timer is an orphan", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			expect(await store.orphanedRuns(10)).toContain(runId);
+		});
+		it("a queued run is not an orphan", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await queue.enqueue(runId);
+			expect(await store.orphanedRuns(10)).not.toContain(runId);
+		});
+		it("a sleeping run with a pending timer is not an orphan", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markRunning(runId);
+			await store.suspendRun(runId, "sleeping", { timers: [{
+				runId,
+				fireAt: at(1e4)
+			}] });
+			expect(await store.orphanedRuns(10)).not.toContain(runId);
+		});
+		it("an awaiting_signal run is not an orphan (legitimately waiting on an external signal)", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markRunning(runId);
+			await store.suspendRun(runId, "awaiting_signal");
+			expect(await store.orphanedRuns(10)).not.toContain(runId);
+		});
+		it("an awaiting_child parent whose child finished IS an orphan (lost parent-wake)", async () => {
+			const { store } = await makeBackend();
+			const parent = await store.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			const child = await store.startRun({
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			});
+			await store.markRunning(parent.runId);
+			await store.suspendRun(parent.runId, "awaiting_child");
+			await store.markTerminal(child.runId, {
+				status: "done",
+				output: 1
+			});
+			expect(await store.orphanedRuns(10)).toContain(parent.runId);
+		});
+		it("a terminal run is never an orphan", async () => {
+			const { store } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await store.markTerminal(runId, {
+				status: "done",
+				output: 1
+			});
+			expect(await store.orphanedRuns(10)).not.toContain(runId);
+		});
+	});
+};
+//#endregion
+//#region src/cron.ts
+/**
+* The cron store surface as executable invariants: upsert keeps timing on re-register,
+* `dueCrons` respects `nextRunAt`, and `advanceCron` is a CAS so exactly one worker fires an
+* occurrence (the double-fire guard on a fleet).
+*/
+const cronConformance = (label, makeStore) => {
+	describe(`Cron conformance — ${label}`, () => {
+		const spec = {
+			name: "nightly",
+			schedule: "0 0 * * *",
+			flowName: "report",
+			flowVersion: 1,
+			input: { kind: "daily" }
+		};
+		it("upsertCron registers a cron that dueCrons returns once due", async () => {
+			const s = await makeStore();
+			await s.upsertCron({
+				...spec,
+				nextRunAt: at(1e3)
+			});
+			expect(await s.dueCrons(at(999), 10)).toEqual([]);
+			const due = await s.dueCrons(at(1e3), 10);
+			expect(due.map((c) => c.name)).toEqual(["nightly"]);
+			expect(due[0].input).toEqual({ kind: "daily" });
+		});
+		it("re-registering keeps the existing nextRunAt (no schedule-timing reset)", async () => {
+			const s = await makeStore();
+			await s.upsertCron({
+				...spec,
+				nextRunAt: at(5e3)
+			});
+			await s.upsertCron({
+				...spec,
+				input: { kind: "changed" },
+				nextRunAt: at(999999)
+			});
+			const due = await s.dueCrons(at(5e3), 10);
+			expect(due.map((c) => c.name)).toEqual(["nightly"]);
+			expect(due[0].input).toEqual({ kind: "changed" });
+		});
+		it("advanceCron is a CAS — only the worker matching the expected time wins", async () => {
+			const s = await makeStore();
+			await s.upsertCron({
+				...spec,
+				nextRunAt: at(1e3)
+			});
+			const first = await s.advanceCron("nightly", at(1e3), at(2e3), at(1e3));
+			const second = await s.advanceCron("nightly", at(1e3), at(2e3), at(1e3));
+			expect(first).toBe(true);
+			expect(second).toBe(false);
+			expect(await s.dueCrons(at(1500), 10)).toEqual([]);
+		});
+	});
+};
+//#endregion
+export { cronConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@iterativeflow/conformance",
+  "version": "2.0.0-alpha.1",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#*": "./src/*.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@iterativeflow/core": "2.0.0-alpha.1"
+  },
+  "peerDependencies": {
+    "vitest": ">=3"
+  }
+}