@iterativeflow/conformance 2.0.0-alpha.9 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Rowaihi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -82,4 +82,28 @@ declare const engineConformance: (label: string, makeBackend: () => Backend | Pr
  */
 declare const claimFilterConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
 //#endregion
-export { claimFilterConformance, cronConformance, engineConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };
+//#region src/sharded-claim.d.ts
+/**
+ * A horizontally-sharded worker pool where each pod claims only the flow names it registered.
+ * Proves that two pods claiming ONE backend concurrently are SAFE — no run is ever leased by both,
+ * and no pod ever leases a run outside its shard — and LIVE: together they drain both shards. Server
+ * backends only; single-writer backends (sqlite / memory / durable-objects) can't issue concurrent
+ * transactions, so their name-shard claim is covered sequentially by {@link claimFilterConformance}.
+ *
+ * Per-round throughput is backend-specific: Postgres locks only the name-matched rows, so both shards
+ * drain in one round; MySQL's `FOR UPDATE OF j SKIP LOCKED` locks the eligible `job` head before the
+ * `run`-side name filter applies, so the first claimer transiently blocks the other's shard, which
+ * fills on the next round. Both are safe — the loop asserts safety every round and liveness overall.
+ */
+declare const shardedClaimConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
+//#endregion
+//#region src/pending-work.d.ts
+/**
+ * Pins the autoscaling-backlog reads — `Queue.depth(now, names)`, `Timer.dueCount(now, names)`, and
+ * `Store.dueCronCount(now, names)` — that `engine.pendingWork` composes. Every backend must count the
+ * same due work (claimable jobs, due timers, due crons), exclude leased/future work, and filter by
+ * flow name identically.
+ */
+declare const pendingWorkConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
+//#endregion
+export { claimFilterConformance, cronConformance, engineConformance, outboxConformance, pendingWorkConformance, queueConformance, reconcileConformance, shardedClaimConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { builder, cancelRun, defineFlow, reconcile, registry, signalRun, signalType, submit, tickOnce } from "@iterativeflow/core";
+import { builder, cancelRun, defineFlow, reconcile, registry, runTick, serverlessTick, signalRun, signalType, submit, tickOnce } from "@iterativeflow/core";
 import { isTerminal } from "@iterativeflow/core/backend";
 //#region src/store.ts
 /**
@@ -119,15 +119,17 @@ const storeConformance = (label, makeStore) => {
 				input: {},
 				idempotencyKey: "k"
 			});
-			expect((await s.startRun({
+			const b = await s.startRun({
 				name: "f",
 				version: 2,
 				input: {},
 				idempotencyKey: "k"
-			})).runId).not.toBe(a.runId);
+			});
+			expect(b.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();
+			const s = await makeStore();
+			expect(await s.loadRun("00000000-0000-0000-0000-000000000000")).toBeUndefined();
 		});
 		it("loadRunRow returns just the run row (no step/signal maps), undefined if gone", async () => {
 			const s = await makeStore();
@@ -210,7 +212,8 @@ const storeConformance = (label, makeStore) => {
 				result: 42,
 				attempts: 1
 			});
-			expect((await s.loadRun(runId))?.steps.get("a")).toMatchObject({
+			const snap = await s.loadRun(runId);
+			expect(snap?.steps.get("a")).toMatchObject({
 				status: "ok",
 				result: 42,
 				attempts: 1
@@ -390,7 +393,8 @@ const storeConformance = (label, makeStore) => {
 			expect(await s.deleteRunsOlderThan(after, 1)).toBe(0);
 		});
 		it("checkpointStep on an unknown run is rejected (no orphan step)", async () => {
-			await expect((await makeStore()).checkpointStep({
+			const s = await makeStore();
+			await expect(s.checkpointStep({
 				runId: "nope",
 				cursorKey: "a",
 				status: "ok",
@@ -489,9 +493,12 @@ const storeConformance = (label, makeStore) => {
 			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]);
+			const byName = await s.listRuns({ name: "alpha" }, { limit: 10 });
+			expect(byName.runs.map((r) => r.name)).toEqual(["alpha", "alpha"]);
+			const byStatus = await s.listRuns({ status: "done" }, { limit: 10 });
+			expect(byStatus.runs.map((r) => r.id)).toEqual([b.runId]);
+			const byTag = await s.listRuns({ tag: "t2" }, { limit: 10 });
+			expect(byTag.runs.map((r) => r.id)).toEqual([b.runId]);
 		});
 		it("listRuns paginates with a cursor", async () => {
 			const s = await makeStore();
@@ -508,7 +515,8 @@ const storeConformance = (label, makeStore) => {
 				cursor: first.cursor
 			});
 			expect(second.runs).toHaveLength(2);
-			expect(new Set([...first.runs, ...second.runs].map((r) => r.id)).size).toBe(4);
+			const ids = new Set([...first.runs, ...second.runs].map((r) => r.id));
+			expect(ids.size).toBe(4);
 		});
 		it("childrenOf returns the runs spawned under a parent", async () => {
 			const s = await makeStore();
@@ -558,12 +566,14 @@ const storeConformance = (label, makeStore) => {
 					message: "boom"
 				}
 			});
-			expect((await s.retryRun(runId)).retried).toBe(true);
+			const res = await s.retryRun(runId);
+			expect(res.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);
+			const again = await s.retryRun(runId);
+			expect(again.retried).toBe(false);
 		});
 		it("runStats counts runs per status", async () => {
 			const s = await makeStore();
@@ -625,16 +635,18 @@ const queueConformance = (label, makeQueue) => {
 			});
 			await q.enqueue("r1", { runAt: at(0) });
 			await q.enqueue("r2", { runAt: at(5e3) });
-			expect(await q.depth(at(1e3))).toEqual({
+			const backlog = await q.depth(at(1e3));
+			expect(backlog).toEqual({
 				claimable: 1,
 				leased: 0,
 				oldestClaimableAgeMs: 1e3
 			});
-			expect((await q.claim({
+			const leases = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(1e3)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
 			expect(await q.depth(at(1e3))).toEqual({
 				claimable: 0,
 				leased: 1,
@@ -649,25 +661,28 @@ const queueConformance = (label, makeQueue) => {
 				leaseMs: 1e3,
 				now: at(0)
 			})).toEqual([]);
-			expect((await q.claim({
+			const due = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(5e3)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(due.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({
+			const first = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).toHaveLength(1);
-			expect(await q.claim({
+			});
+			expect(first).toHaveLength(1);
+			const second = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(500)
-			})).toEqual([]);
+			});
+			expect(second).toEqual([]);
 		});
 		it("an expired lease is re-claimable (crash recovery), with a fresh token", async () => {
 			const q = await makeQueue();
@@ -702,11 +717,12 @@ const queueConformance = (label, makeQueue) => {
 				leaseMs: 1e3,
 				now: at(1001)
 			})).toEqual([]);
-			expect((await q.claim({
+			const after = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(1501)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(after.map((l) => l.runId)).toEqual(["r1"]);
 		});
 		it("heartbeat on a lost (re-claimed) lease throws", async () => {
 			const q = await makeQueue();
@@ -755,11 +771,12 @@ const queueConformance = (label, makeQueue) => {
 				now: at(1001)
 			});
 			await q.ack(stale, { now: at(1002) });
-			expect((await q.claim({
+			const still = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(2002)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(still.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();
@@ -771,11 +788,12 @@ const queueConformance = (label, makeQueue) => {
 			});
 			await q.enqueue("r1");
 			await q.ack(lease, { now: at(1) });
-			expect((await q.claim({
+			const again = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(2)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(again.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();
@@ -786,11 +804,12 @@ const queueConformance = (label, makeQueue) => {
 				now: at(0)
 			});
 			await q.ack(lease, { now: at(1001) });
-			expect((await q.claim({
+			const still = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(1002)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(still.map((l) => l.runId)).toEqual(["r1"]);
 		});
 		it("heartbeat after expiry throws (lease lost even without a re-claim)", async () => {
 			const q = await makeQueue();
@@ -823,11 +842,12 @@ const queueConformance = (label, makeQueue) => {
 		it("claim honours the batch limit", async () => {
 			const q = await makeQueue();
 			for (let i = 0; i < 5; i++) await q.enqueue(`r${i}`);
-			expect(await q.claim({
+			const leases = await q.claim({
 				limit: 2,
 				leaseMs: 1e3,
 				now: at(0)
-			})).toHaveLength(2);
+			});
+			expect(leases).toHaveLength(2);
 		});
 		it("lower priority is claimed first", async () => {
 			const q = await makeQueue();
@@ -844,11 +864,12 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			await q.enqueue("r1", { priority: 5 });
-			expect((await q.claim({
+			const leases = await q.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toEqual(["r1"]);
+			});
+			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
 		});
 	});
 };
@@ -920,13 +941,15 @@ const timerConformance = (label, makeTimer) => {
 			await tm.schedule("late", at(300));
 			await tm.schedule("early", at(100));
 			await tm.schedule("mid", at(200));
-			expect(await tm.dueBatch({
+			const due = await tm.dueBatch({
 				now: at(1e3),
 				limit: 2
-			})).toEqual(["early", "mid"]);
+			});
+			expect(due).toEqual(["early", "mid"]);
 		});
 		it("nextDueAt is null when nothing is pending", async () => {
-			expect(await (await makeTimer()).nextDueAt(at(0))).toBeNull();
+			const tm = await makeTimer();
+			expect(await tm.nextDueAt(at(0))).toBeNull();
 		});
 		it("nextDueAt returns the earliest timer due strictly after now", async () => {
 			const tm = await makeTimer();
@@ -986,7 +1009,8 @@ const wakeupConformance = (label, makeWakeup) => {
 			expect(resolved).toBe(true);
 		});
 		it("signal is a no-op when there are no waiters", async () => {
-			await expect((await makeWakeup()).signal("nobody")).resolves.toBeUndefined();
+			const w = await makeWakeup();
+			await expect(w.signal("nobody")).resolves.toBeUndefined();
 		});
 		it("is edge-triggered — a signal before any waiter does not latch", async () => {
 			const w = await makeWakeup();
@@ -1032,11 +1056,12 @@ const outboxConformance = (label, makeBackend) => {
 				result: 1,
 				attempts: 1
 			}, { enqueue: [{ runId }] });
-			expect((await queue.claim({
+			const leases = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toEqual([runId]);
+			});
+			expect(leases.map((l) => l.runId)).toEqual([runId]);
 		});
 		it("checkpointStep spawns a child run + enqueues it atomically", async () => {
 			const { store, queue } = await makeBackend();
@@ -1061,11 +1086,12 @@ const outboxConformance = (label, makeBackend) => {
 				}
 			}] });
 			expect((await store.loadRun(childId))?.run.input).toEqual({ n: 1 });
-			expect((await queue.claim({
+			const leases = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toContain(childId);
+			});
+			expect(leases.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();
@@ -1097,11 +1123,12 @@ const outboxConformance = (label, makeBackend) => {
 				result: childId,
 				attempts: 2
 			}, spawn);
-			expect((await queue.claim({
+			const leases = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).filter((l) => l.runId === childId)).toHaveLength(1);
+			});
+			expect(leases.filter((l) => l.runId === childId)).toHaveLength(1);
 		});
 		it("suspendRun(sleeping) sets status + wake timer atomically", async () => {
 			const { store, timer } = await makeBackend();
@@ -1163,11 +1190,12 @@ const outboxConformance = (label, makeBackend) => {
 				status: "done",
 				output: 7
 			}, { enqueue: [{ runId: parent.runId }] });
-			expect((await queue.claim({
+			const leases = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toContain(parent.runId);
+			});
+			expect(leases.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();
@@ -1227,19 +1255,22 @@ const signalConformance = (label, makeBackend) => {
 				version: 1,
 				input: {}
 			});
-			expect((await store.postSignal(runId, "approve", { ok: true })).delivered).toBe(true);
-			expect((await store.loadRun(runId))?.signals.map((s) => ({
+			const res = await store.postSignal(runId, "approve", { ok: true });
+			expect(res.delivered).toBe(true);
+			const snap = await store.loadRun(runId);
+			expect(snap?.signals.map((s) => ({
 				name: s.name,
 				payload: s.payload
 			}))).toEqual([{
 				name: "approve",
 				payload: { ok: true }
 			}]);
-			expect((await queue.claim({
+			const leases = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toEqual([runId]);
+			});
+			expect(leases.map((l) => l.runId)).toEqual([runId]);
 		});
 		it("postSignal is idempotent on its key — a retried delivery lands once", async () => {
 			const { store } = await makeBackend();
@@ -1288,22 +1319,24 @@ const signalConformance = (label, makeBackend) => {
 				leaseMs: 1e3,
 				now: at(0)
 			});
-			expect((await store.checkpointStep({
+			const committed = await store.checkpointStep({
 				runId,
 				cursorKey: "res",
 				status: "ok",
 				result: { received: false },
 				attempts: 1
-			}, { requireVersion: lease.version })).committed).not.toBe(false);
+			}, { requireVersion: lease.version });
+			expect(committed.committed).not.toBe(false);
 			expect((await store.loadRun(runId))?.steps.get("res")?.result).toEqual({ received: false });
 			await store.postSignal(runId, "go", "payload");
-			expect((await store.checkpointStep({
+			const blocked = await store.checkpointStep({
 				runId,
 				cursorKey: "res2",
 				status: "ok",
 				result: { received: false },
 				attempts: 1
-			}, { requireVersion: lease.version })).committed).toBe(false);
+			}, { requireVersion: lease.version });
+			expect(blocked.committed).toBe(false);
 			expect((await store.loadRun(runId))?.steps.get("res2")).toBeUndefined();
 		});
 		it("distinct signals to a run preserve delivery order in the inbox", async () => {
@@ -1538,8 +1571,8 @@ const engineConformance = (label, makeBackend) => {
 			batchMax: 16,
 			leaseMs: 6e5
 		};
-		const drive = async (backend, flows, runId, retry) => {
-			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+		const drive = async (backend, flows, runId, retry, start) => {
+			let clock = start ?? /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
 			const now = () => clock;
 			for (let i = 0; i < 200; i++) {
 				await tickOnce(backend, flows, {
@@ -1564,11 +1597,12 @@ const engineConformance = (label, makeBackend) => {
 				}
 			});
 			const runId = await submit(backend, flow, {});
-			expect(await drive(backend, registry([flow]), runId, {
+			const run = await drive(backend, registry([flow]), runId, {
 				maxAttempts: 3,
 				baseDelayMs: 1,
 				maxDelayMs: 1
-			})).toMatchObject({
+			});
+			expect(run).toMatchObject({
 				status: "done",
 				output: "settled"
 			});
@@ -1583,7 +1617,8 @@ const engineConformance = (label, makeBackend) => {
 				nap: acc.nap
 			}));
 			const runId = await submit(backend, flow, { x: 21 });
-			expect(await drive(backend, registry([flow]), runId)).toMatchObject({
+			const run = await drive(backend, registry([flow]), runId);
+			expect(run).toMatchObject({
 				status: "done",
 				output: {
 					doubled: 42,
@@ -1601,11 +1636,12 @@ const engineConformance = (label, makeBackend) => {
 				})
 			});
 			const runId = await submit(backend, flow, {});
-			expect((await drive(backend, registry([flow]), runId, {
+			const run = await drive(backend, registry([flow]), runId, {
 				maxAttempts: 2,
 				baseDelayMs: 1,
 				maxDelayMs: 1
-			})).status).toBe("failed");
+			});
+			expect(run.status).toBe("failed");
 		});
 		it("dead-letters a poison-pill (uncatchable-crash) run once attempts exceed the cap", async () => {
 			const backend = await makeBackend();
@@ -1647,7 +1683,8 @@ const engineConformance = (label, makeBackend) => {
 			});
 			expect((await backend.store.loadRunRow(runId))?.status).toBe("awaiting_signal");
 			await signalRun(backend, runId, "go", { ok: true });
-			expect(await drive(backend, flows, runId)).toMatchObject({
+			const run = await drive(backend, flows, runId);
+			expect(run).toMatchObject({
 				status: "done",
 				output: "shipped"
 			});
@@ -1800,7 +1837,8 @@ const engineConformance = (label, makeBackend) => {
 				])
 			});
 			const runId = await submit(backend, parent, {});
-			expect(await drive(backend, registry([parent, dbl]), runId)).toMatchObject({
+			const run = await drive(backend, registry([parent, dbl]), runId);
+			expect(run).toMatchObject({
 				status: "done",
 				output: [
 					2,
@@ -1845,11 +1883,12 @@ const engineConformance = (label, makeBackend) => {
 				run: async (ctx, n) => ctx.invoke(recurse, n + 1)
 			});
 			const runId = await submit(backend, recurse, 0);
-			expect((await drive(backend, registry([recurse]), runId, {
+			const top = await drive(backend, registry([recurse]), runId, {
 				maxAttempts: 1,
 				baseDelayMs: 1,
 				maxDelayMs: 1
-			})).status).toBe("failed");
+			});
+			expect(top.status).toBe("failed");
 			let cur = runId;
 			let deepest = await backend.store.loadRunRow(cur);
 			for (;;) {
@@ -1910,7 +1949,7 @@ const engineConformance = (label, makeBackend) => {
 				}])
 			});
 			const runId = await submit(backend, parent, {});
-			expect((await drive(backend, registry([
+			const run = await drive(backend, registry([
 				parent,
 				boom,
 				slow
@@ -1918,12 +1957,316 @@ const engineConformance = (label, makeBackend) => {
 				maxAttempts: 1,
 				baseDelayMs: 1,
 				maxDelayMs: 1
-			})).status).toBe("failed");
+			});
+			expect(run.status).toBe("failed");
 			const kids = await backend.store.childrenOf(runId);
 			expect(kids).toHaveLength(2);
 			expect(kids.every((k) => isTerminal(k.status))).toBe(true);
 			expect(kids.some((k) => k.status === "canceled")).toBe(true);
 		});
+		it("a claimed run for an unregistered flow version parks and resumes once that version deploys", async () => {
+			const backend = await makeBackend();
+			const v1 = defineFlow({
+				name: "wf",
+				version: 1,
+				run: async () => "v1"
+			});
+			const v2 = defineFlow({
+				name: "wf",
+				version: 2,
+				run: async () => "v2"
+			});
+			const fast = {
+				maxAttempts: 3,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			};
+			const runId = await submit(backend, v2, {});
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const now = () => clock;
+			await tickOnce(backend, registry([v1]), {
+				...base,
+				now,
+				retry: fast
+			});
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("retrying");
+			for (let i = 0; i < 4; i++) {
+				clock = new Date(clock.getTime() + 6e4);
+				await tickOnce(backend, registry([v1]), {
+					...base,
+					now,
+					retry: fast
+				});
+				expect((await backend.store.loadRunRow(runId))?.status).toBe("retrying");
+			}
+			const run = await drive(backend, registry([v2]), runId, fast, clock);
+			expect(run).toMatchObject({
+				status: "done",
+				output: "v2"
+			});
+		});
+		it("a signal delivered at the timeout deadline wins the race — never lost to the timeout", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "raced",
+				version: 1,
+				signals: { go: signalType() },
+				run: async (ctx) => {
+					const r = await ctx.signal("go", { timeoutMs: 5e3 });
+					return r.received ? `signal:${r.payload}` : "timeout";
+				}
+			});
+			const flows = registry([flow]);
+			const t0 = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const runId = await submit(backend, flow, {});
+			await tickOnce(backend, flows, {
+				...base,
+				now: () => t0
+			});
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("awaiting_signal");
+			const deadline = new Date(t0.getTime() + 5e3);
+			await signalRun(backend, runId, "go", "ok");
+			const run = await drive(backend, flows, runId, void 0, deadline);
+			expect(run).toMatchObject({
+				status: "done",
+				output: "signal:ok"
+			});
+		});
+		it("a bounded signal wait commits { received: false } when nothing arrives before the deadline", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "waits-out",
+				version: 1,
+				signals: { go: signalType() },
+				run: async (ctx) => {
+					return (await ctx.signal("go", { timeoutMs: 5e3 })).received ? "signal" : "timeout";
+				}
+			});
+			const runId = await submit(backend, flow, {});
+			await tickOnce(backend, registry([flow]), {
+				...base,
+				now: () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z")
+			});
+			const run = await drive(backend, registry([flow]), runId);
+			expect(run).toMatchObject({
+				status: "done",
+				output: "timeout"
+			});
+		});
+		it("memoizes a completed step across a crash-retry — the step fn runs once, the run still completes", async () => {
+			const backend = await makeBackend();
+			let stepCalls = 0;
+			let invocations = 0;
+			const flow = defineFlow({
+				name: "flaky",
+				version: 1,
+				run: async (ctx) => {
+					const v = await ctx.step("charge", () => {
+						stepCalls += 1;
+						return 42;
+					});
+					invocations += 1;
+					if (invocations === 1) throw new Error("crash after the charge committed");
+					return v;
+				}
+			});
+			const runId = await submit(backend, flow, {});
+			const run = await drive(backend, registry([flow]), runId, {
+				maxAttempts: 5,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			});
+			expect(run).toMatchObject({
+				status: "done",
+				output: 42
+			});
+			expect(stepCalls).toBe(1);
+		});
+		it("reconcile re-drives a run stranded off the queue (crash between start and enqueue)", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "stranded",
+				version: 1,
+				run: async () => "recovered"
+			});
+			const flows = registry([flow]);
+			const { runId } = await backend.store.startRun({
+				name: "stranded",
+				version: 1,
+				input: {}
+			});
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const now = () => clock;
+			for (let i = 0; i < 10; i++) {
+				await reconcile(backend, { limit: 16 });
+				await tickOnce(backend, flows, {
+					...base,
+					now
+				});
+				const r = await backend.store.loadRunRow(runId);
+				if (r && isTerminal(r.status)) break;
+				clock = new Date(clock.getTime() + 6e4);
+			}
+			expect(await backend.store.loadRunRow(runId)).toMatchObject({
+				status: "done",
+				output: "recovered"
+			});
+		});
+		it("a reclaimed run fences the crashed worker — its stale ack and duplicate commit don't corrupt the new owner", async () => {
+			const { store, queue } = await makeBackend();
+			const { runId } = await store.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await queue.enqueue(runId);
+			const t0 = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const [a] = await queue.claim({
+				limit: 1,
+				leaseMs: 1e3,
+				now: t0
+			});
+			const t1 = new Date(t0.getTime() + 2e3);
+			const [b] = await queue.claim({
+				limit: 1,
+				leaseMs: 6e5,
+				now: t1
+			});
+			expect(b?.runId).toBe(runId);
+			await store.checkpointStep({
+				runId,
+				cursorKey: "s0",
+				status: "ok",
+				result: "B",
+				attempts: 1
+			});
+			const late = await store.checkpointStep({
+				runId,
+				cursorKey: "s0",
+				status: "ok",
+				result: "A",
+				attempts: 1
+			});
+			expect(late.result).toBe("B");
+			await queue.ack(a, { now: new Date(t1.getTime() + 1e3) });
+			expect((await store.loadRun(runId))?.steps.get("s0")?.result).toBe("B");
+			await expect(queue.heartbeat(b, {
+				leaseMs: 6e5,
+				now: new Date(t1.getTime() + 1e3)
+			})).resolves.toBeDefined();
+		});
+		it("a cancel landing while a worker holds a live lease still cancels — the in-flight tick doesn't resurrect it", async () => {
+			const backend = await makeBackend();
+			let bodyRan = 0;
+			const flow = defineFlow({
+				name: "cancelable",
+				version: 1,
+				run: async (ctx) => {
+					bodyRan += 1;
+					await ctx.sleep(1e4);
+					return "done";
+				}
+			});
+			const flows = registry([flow]);
+			const { store, queue } = backend;
+			const { runId } = await store.startRun({
+				name: "cancelable",
+				version: 1,
+				input: {}
+			});
+			await queue.enqueue(runId);
+			const t0 = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const [lease] = await queue.claim({
+				limit: 1,
+				leaseMs: 6e5,
+				now: t0
+			});
+			await cancelRun(backend, runId);
+			const result = await runTick(backend, flows, lease, {
+				...base,
+				now: () => t0
+			});
+			expect(result.status).toBe("already_terminal");
+			expect((await store.loadRunRow(runId))?.status).toBe("canceled");
+			expect(bodyRan).toBe(0);
+			const after = await queue.claim({
+				limit: 1,
+				leaseMs: 1e3,
+				now: new Date(t0.getTime() + 1e3)
+			});
+			expect(after).toHaveLength(0);
+		});
+		it("two disjoint worker registries drive their own flows to completion against one backend", async () => {
+			const backend = await makeBackend();
+			const a = defineFlow({
+				name: "sa",
+				version: 1,
+				run: async () => "a-done"
+			});
+			const b = defineFlow({
+				name: "sb",
+				version: 1,
+				run: async () => "b-done"
+			});
+			const podA = registry([a]);
+			const podB = registry([b]);
+			const idA = await submit(backend, a, {});
+			const idB = await submit(backend, b, {});
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const now = () => clock;
+			for (let i = 0; i < 10; i++) {
+				await tickOnce(backend, podA, {
+					...base,
+					now
+				});
+				await tickOnce(backend, podB, {
+					...base,
+					now
+				});
+				const ra = await backend.store.loadRunRow(idA);
+				const rb = await backend.store.loadRunRow(idB);
+				if (ra && rb && isTerminal(ra.status) && isTerminal(rb.status)) break;
+				clock = new Date(clock.getTime() + 6e4);
+			}
+			expect(await backend.store.loadRunRow(idA)).toMatchObject({
+				status: "done",
+				output: "a-done"
+			});
+			expect(await backend.store.loadRunRow(idB)).toMatchObject({
+				status: "done",
+				output: "b-done"
+			});
+		});
+		it("serverlessTick advances a durable sleep and reports the next wake horizon (no resident loop)", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "napper",
+				version: 1,
+				run: async (ctx) => {
+					await ctx.sleep(6e4);
+					return "woke";
+				}
+			});
+			const flows = registry([flow]);
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const now = () => clock;
+			const runId = await submit(backend, flow, {});
+			const s1 = await serverlessTick(backend, flows, {
+				...base,
+				now
+			});
+			expect(s1.results.map((r) => r.status)).toContain("sleeping");
+			expect(s1.nextWakeAt?.getTime()).toBe(clock.getTime() + 6e4);
+			clock = new Date(clock.getTime() + 6e4);
+			await serverlessTick(backend, flows, {
+				...base,
+				now
+			});
+			expect(await backend.store.loadRunRow(runId)).toMatchObject({
+				status: "done",
+				output: "woke"
+			});
+		});
 	});
 };
 //#endregion
@@ -1948,18 +2291,20 @@ const claimFilterConformance = (label, makeBackend) => {
 			});
 			await queue.enqueue(a.runId);
 			await queue.enqueue(b.runId);
-			expect((await queue.claim({
+			const onlyA = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				names: ["flow-a"],
 				now: at(0)
-			})).map((l) => l.runId)).toEqual([a.runId]);
-			expect((await queue.claim({
+			});
+			expect(onlyA.map((l) => l.runId)).toEqual([a.runId]);
+			const onlyB = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				names: ["flow-b"],
 				now: at(0)
-			})).map((l) => l.runId)).toEqual([b.runId]);
+			});
+			expect(onlyB.map((l) => l.runId)).toEqual([b.runId]);
 		});
 		it("an empty set leases nothing; an omitted set leases everything", async () => {
 			const { store, queue } = await makeBackend();
@@ -1975,13 +2320,142 @@ const claimFilterConformance = (label, makeBackend) => {
 				names: [],
 				now: at(0)
 			})).toEqual([]);
-			expect((await queue.claim({
+			const all = await queue.claim({
 				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
-			})).map((l) => l.runId)).toEqual([a.runId]);
+			});
+			expect(all.map((l) => l.runId)).toEqual([a.runId]);
+		});
+	});
+};
+//#endregion
+//#region src/sharded-claim.ts
+/**
+* A horizontally-sharded worker pool where each pod claims only the flow names it registered.
+* Proves that two pods claiming ONE backend concurrently are SAFE — no run is ever leased by both,
+* and no pod ever leases a run outside its shard — and LIVE: together they drain both shards. Server
+* backends only; single-writer backends (sqlite / memory / durable-objects) can't issue concurrent
+* transactions, so their name-shard claim is covered sequentially by {@link claimFilterConformance}.
+*
+* Per-round throughput is backend-specific: Postgres locks only the name-matched rows, so both shards
+* drain in one round; MySQL's `FOR UPDATE OF j SKIP LOCKED` locks the eligible `job` head before the
+* `run`-side name filter applies, so the first claimer transiently blocks the other's shard, which
+* fills on the next round. Both are safe — the loop asserts safety every round and liveness overall.
+*/
+const shardedClaimConformance = (label, makeBackend) => {
+	describe(`sharded-claim conformance (${label})`, () => {
+		it("two pods claim disjoint flow-name shards concurrently — no overlap, each drains its own shard", async () => {
+			const backend = await makeBackend();
+			const mk = async (name) => {
+				const { runId } = await backend.store.startRun({
+					name,
+					version: 1,
+					input: {}
+				});
+				await backend.queue.enqueue(runId);
+				return runId;
+			};
+			const aIds = new Set(await Promise.all([
+				mk("a"),
+				mk("a"),
+				mk("a")
+			]));
+			const bIds = new Set(await Promise.all([
+				mk("b"),
+				mk("b"),
+				mk("b")
+			]));
+			const now = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const gotA = /* @__PURE__ */ new Set();
+			const gotB = /* @__PURE__ */ new Set();
+			const claim = async (name, into) => {
+				for (const l of await backend.queue.claim({
+					limit: 10,
+					leaseMs: 6e5,
+					now,
+					names: [name]
+				})) into.add(l.runId);
+			};
+			for (let round = 0; round < 6 && (gotA.size < 3 || gotB.size < 3); round++) {
+				await Promise.all([gotA.size < 3 ? claim("a", gotA) : Promise.resolve(), gotB.size < 3 ? claim("b", gotB) : Promise.resolve()]);
+				expect([...gotA].filter((id) => gotB.has(id))).toEqual([]);
+			}
+			expect([...gotA].every((id) => aIds.has(id))).toBe(true);
+			expect([...gotB].every((id) => bIds.has(id))).toBe(true);
+			expect(gotA.size).toBe(3);
+			expect(gotB.size).toBe(3);
+		});
+	});
+};
+//#endregion
+//#region src/pending-work.ts
+/**
+* Pins the autoscaling-backlog reads — `Queue.depth(now, names)`, `Timer.dueCount(now, names)`, and
+* `Store.dueCronCount(now, names)` — that `engine.pendingWork` composes. Every backend must count the
+* same due work (claimable jobs, due timers, due crons), exclude leased/future work, and filter by
+* flow name identically.
+*/
+const pendingWorkConformance = (label, makeBackend) => {
+	describe(`pending-work conformance (${label})`, () => {
+		const now = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+		const past = /* @__PURE__ */ new Date(now.getTime() - 6e4);
+		const future = new Date(now.getTime() + 36e5);
+		const seed = async () => {
+			const be = await makeBackend();
+			const start = async (name) => (await be.store.startRun({
+				name,
+				version: 1,
+				input: {}
+			})).runId;
+			const leased = await start("a");
+			await be.queue.enqueue(leased);
+			await be.queue.claim({
+				limit: 1,
+				leaseMs: 6e5,
+				now
+			});
+			const a1 = await start("a");
+			await be.queue.enqueue(a1);
+			const b1 = await start("b");
+			await be.queue.enqueue(b1);
+			const sleeping = await start("a");
+			await be.timer.schedule(sleeping, past);
+			const napping = await start("a");
+			await be.timer.schedule(napping, future);
+			await be.timer.schedule("orphan-run", past);
+			const futureJob = await start("a");
+			await be.queue.enqueue(futureJob, { runAt: future });
+			await be.store.upsertCron({
+				name: "cron-a",
+				schedule: "* * * * *",
+				flowName: "a",
+				flowVersion: 1,
+				input: {},
+				nextRunAt: past
+			});
+			return be;
+		};
+		it("depth counts claimable jobs (not leased/future), filtered by flow name", async () => {
+			const be = await seed();
+			expect((await be.queue.depth(now)).claimable).toBe(2);
+			expect((await be.queue.depth(now, ["a"])).claimable).toBe(1);
+			expect((await be.queue.depth(now, ["b"])).claimable).toBe(1);
+			expect((await be.queue.depth(now, [])).claimable).toBe(0);
+		});
+		it("dueCount counts due timers incl. run-less (not future), filtered by flow name", async () => {
+			const be = await seed();
+			expect(await be.timer.dueCount(now)).toBe(2);
+			expect(await be.timer.dueCount(now, ["a"])).toBe(1);
+			expect(await be.timer.dueCount(now, ["b"])).toBe(0);
+		});
+		it("dueCronCount counts due crons, filtered by flow name", async () => {
+			const be = await seed();
+			expect(await be.store.dueCronCount(now)).toBe(1);
+			expect(await be.store.dueCronCount(now, ["a"])).toBe(1);
+			expect(await be.store.dueCronCount(now, ["b"])).toBe(0);
 		});
 	});
 };
 //#endregion
-export { claimFilterConformance, cronConformance, engineConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };
+export { claimFilterConformance, cronConformance, engineConformance, outboxConformance, pendingWorkConformance, queueConformance, reconcileConformance, shardedClaimConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterativeflow/conformance",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,13 +24,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsdown"
-  },
   "dependencies": {
-    "@iterativeflow/core": "2.0.0-alpha.9"
+    "@iterativeflow/core": "2.0.0"
   },
   "peerDependencies": {
     "vitest": ">=3"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}