@iterativeflow/conformance 2.0.0-alpha.1 → 2.0.0-alpha.2

package/README.md

@@ -0,0 +1,35 @@
+# @iterativeflow/conformance
+
+The backend-authoring kit for [iterativeflow](https://github.com/ahmedrowaihi/iterativeflow)
+v2. To add a substrate, implement the four ports (store/queue/timer/wakeup) from
+`@iterativeflow/core/backend` and prove them against these shared suites — the
+same tests the built-in memory, Postgres, and DynamoDB backends pass. A real
+serialization or consistency regression can't hide behind a backend's own tests.
+
+```bash
+npm install -D @iterativeflow/conformance @iterativeflow/core
+```
+
+```ts
+import { storeConformance, engineConformance } from "@iterativeflow/conformance";
+import { createMyBackend } from "./backend";
+
+storeConformance("my-backend", () => createMyBackend());
+engineConformance("my-backend", () => createMyBackend());
+```
+
+Each suite registers `describe`/`it` blocks (vitest), so call them at the top
+level of a test file.
+
+## Suites
+
+- **Port suites** — `storeConformance`, `queueConformance`, `timerConformance`,
+  `wakeupConformance`: each port's contract in isolation.
+- `outboxConformance` — the atomic multi-port checkpoint write.
+- `signalConformance`, `reconcileConformance`, `cronConformance` — the durable
+  behaviors built on the ports.
+- `engineConformance` — the composed engine (retry/dead-letter, signal resume,
+  cancel cascade, fan-out, drift) end-to-end on your backend.
+
+Every suite takes `(label, makeBackend)` where `makeBackend` returns a fresh
+`Backend` (or a `Promise` of one) per case.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { Backend, Queue, Store, Timer, Wakeup } from "@iterativeflow/core/backend";
+import { Backend } from "@iterativeflow/core";
+import { Backend as Backend$1, Queue, Store, Timer, Wakeup } from "@iterativeflow/core/backend";
 //#region src/store.d.ts
 /**
  * The Store contract as executable invariants. EVERY backend (in-memory, Postgres,
@@ -39,7 +40,7 @@ declare const wakeupConformance: (label: string, makeWakeup: () => Wakeup | Prom
  * 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;
+declare const outboxConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
 //#endregion
 //#region src/signal.d.ts
 /**
@@ -47,7 +48,7 @@ declare const outboxConformance: (label: string, makeBackend: () => Backend | Pr
  * 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;
+declare const signalConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
 //#endregion
 //#region src/reconcile.d.ts
 /**
@@ -56,7 +57,7 @@ declare const signalConformance: (label: string, makeBackend: () => Backend | Pr
  * 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;
+declare const reconcileConformance: (label: string, makeBackend: () => Backend$1 | Promise<Backend$1>) => void;
 //#endregion
 //#region src/cron.d.ts
 /**
@@ -66,4 +67,12 @@ declare const reconcileConformance: (label: string, makeBackend: () => Backend |
  */
 declare const cronConformance: (label: string, makeStore: () => Store | Promise<Store>) => void;
 //#endregion
-export { cronConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };
+//#region src/engine.d.ts
+/**
+ * Engine-behavior conformance: the composed durable behaviors (retry/dead-letter, signal
+ * resume, cancel cascade, drift) run against every backend, not just memory — so a real
+ * serialization/consistency regression can't hide behind the port-conformance suites.
+ */
+declare const engineConformance: (label: string, makeBackend: () => Backend | Promise<Backend>) => void;
+//#endregion
+export { cronConformance, engineConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/dist/index.mjs

@@ -1,4 +1,6 @@
 import { describe, expect, it } from "vitest";
+import { builder, cancelRun, defineFlow, reconcile, registry, signalRun, signalType, submit, tickOnce } from "@iterativeflow/core";
+import { isTerminal } from "@iterativeflow/core/backend";
 //#region src/store.ts
 /**
 * The Store contract as executable invariants. EVERY backend (in-memory, Postgres,
@@ -75,6 +77,22 @@ const storeConformance = (label, makeStore) => {
 			expect(results[1].created).toBe(true);
 			expect(results[1].runId).not.toBe(first.runId);
 		});
+		it("startManyRuns dedups a key that repeats WITHIN the batch — one run, not a throw", async () => {
+			const results = await (await makeStore()).startManyRuns([{
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "same"
+			}, {
+				name: "f",
+				version: 1,
+				input: {},
+				idempotencyKey: "same"
+			}]);
+			expect(results).toHaveLength(2);
+			expect(results[0].runId).toBe(results[1].runId);
+			expect([results[0].created, results[1].created].filter(Boolean)).toHaveLength(1);
+		});
 		it("startRun is idempotent on the idempotency key — no duplicate run", async () => {
 			const s = await makeStore();
 			const a = await s.startRun({
@@ -111,6 +129,73 @@ const storeConformance = (label, makeStore) => {
 		it("loadRun returns undefined for an unknown run", async () => {
 			expect(await (await makeStore()).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();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: { a: 1 }
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 1,
+				attempts: 1
+			});
+			const row = await s.loadRunRow(runId);
+			expect(row).toMatchObject({
+				id: runId,
+				status: "pending"
+			});
+			expect(row).not.toHaveProperty("steps");
+			expect(row).not.toHaveProperty("signals");
+			expect(await s.loadRunRow("00000000-0000-0000-0000-000000000000")).toBeUndefined();
+		});
+		it("loadRunRows returns rows aligned to the input ids, undefined where gone", async () => {
+			const s = await makeStore();
+			const a = await s.startRun({
+				name: "f",
+				version: 1,
+				input: { n: 1 }
+			});
+			const b = await s.startRun({
+				name: "f",
+				version: 1,
+				input: { n: 2 }
+			});
+			const rows = await s.loadRunRows([
+				a.runId,
+				"00000000-0000-0000-0000-000000000000",
+				b.runId
+			]);
+			expect(rows).toHaveLength(3);
+			expect(rows[0]?.id).toBe(a.runId);
+			expect(rows[1]).toBeUndefined();
+			expect(rows[2]?.id).toBe(b.runId);
+			expect(await s.loadRunRows([])).toEqual([]);
+		});
+		it("arriveAtJoin decrements the armed join countdown, and sentinels a gone parent", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "s0",
+				status: "ok",
+				result: [],
+				attempts: 1
+			}, { joinTarget: {
+				runId,
+				count: 2
+			} });
+			expect(await s.arriveAtJoin(runId)).toBe(1);
+			expect(await s.arriveAtJoin(runId)).toBe(0);
+			expect(await s.arriveAtJoin("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({
@@ -131,6 +216,23 @@ const storeConformance = (label, makeStore) => {
 				attempts: 1
 			});
 		});
+		it("checkpointStep round-trips the shape tag (drift-guard evidence)", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.checkpointStep({
+				runId,
+				cursorKey: "a",
+				status: "ok",
+				result: 1,
+				attempts: 1,
+				shape: "step:charge"
+			});
+			expect((await s.loadRun(runId))?.steps.get("a")?.shape).toBe("step:charge");
+		});
 		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({
@@ -167,6 +269,22 @@ const storeConformance = (label, makeStore) => {
 			expect(await s.markRunning(runId)).toBe(2);
 			expect((await s.loadRun(runId))?.run.attempts).toBe(2);
 		});
+		it("a forward-progress suspend zeroes the dispatch counter; retrying keeps it", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			await s.markRunning(runId);
+			await s.markRunning(runId);
+			await s.suspendRun(runId, "retrying");
+			expect((await s.loadRunRow(runId))?.attempts).toBe(2);
+			await s.markRunning(runId);
+			await s.suspendRun(runId, "sleeping");
+			expect((await s.loadRunRow(runId))?.attempts).toBe(0);
+			expect(await s.markRunning(runId)).toBe(1);
+		});
 		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({
@@ -207,56 +325,69 @@ const storeConformance = (label, makeStore) => {
 			});
 			expect((await s.loadRun(runId))?.run.status).toBe("canceled");
 		});
-		it("checkpointStep round-trips a failed_terminal outcome with its error", async () => {
+		it("deleteRunsOlderThan prunes terminal runs (with steps + signals) before the cutoff, spares live ones", async () => {
 			const s = await makeStore();
-			const { runId } = await s.startRun({
+			const old = /* @__PURE__ */ new Date("2020-01-01T00:00:00.000Z");
+			const doomed = await s.startRun({
 				name: "f",
 				version: 1,
-				input: {}
+				input: {},
+				createdAt: old
 			});
 			await s.checkpointStep({
-				runId,
+				runId: doomed.runId,
 				cursorKey: "a",
-				status: "failed_terminal",
-				error: {
-					code: "BOOM",
-					message: "boom"
-				},
+				status: "ok",
+				result: 1,
 				attempts: 1
 			});
-			expect((await s.loadRun(runId))?.steps.get("a")).toMatchObject({
-				status: "failed_terminal",
-				error: {
-					code: "BOOM",
-					message: "boom"
-				}
+			await s.postSignal(doomed.runId, "go", { ok: true });
+			await s.markTerminal(doomed.runId, {
+				status: "done",
+				output: 1
 			});
+			const live = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				createdAt: old
+			});
+			expect((await s.loadRunRow(live.runId))?.createdAt?.getTime()).toBe(old.getTime());
+			expect(await s.deleteRunsOlderThan(/* @__PURE__ */ new Date("2020-06-01T00:00:00Z"), 100)).toBe(1);
+			expect(await s.loadRun(doomed.runId)).toBeUndefined();
+			expect((await s.loadRun(live.runId))?.run.status).toBe("pending");
 		});
-		it("first-writer-wins holds across status — a later ok cannot overwrite a failed_terminal", async () => {
+		it("deleteRunsOlderThan honours the cutoff and the per-sweep limit", async () => {
 			const s = await makeStore();
-			const { runId } = await s.startRun({
+			const old = /* @__PURE__ */ new Date("2020-01-01T00:00:00.000Z");
+			const a = await s.startRun({
 				name: "f",
 				version: 1,
-				input: {}
+				input: {},
+				createdAt: old
 			});
-			await s.checkpointStep({
-				runId,
-				cursorKey: "a",
-				status: "failed_terminal",
+			const b = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				createdAt: old
+			});
+			await s.markTerminal(a.runId, {
+				status: "done",
+				output: 1
+			});
+			await s.markTerminal(b.runId, {
+				status: "failed",
 				error: {
-					code: "BOOM",
-					message: "boom"
-				},
-				attempts: 1
+					code: "X",
+					message: "x"
+				}
 			});
-			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");
+			const after = /* @__PURE__ */ new Date("2020-06-01T00:00:00Z");
+			expect(await s.deleteRunsOlderThan(/* @__PURE__ */ new Date("2019-01-01T00:00:00Z"), 100)).toBe(0);
+			expect(await s.deleteRunsOlderThan(after, 1)).toBe(1);
+			expect(await s.deleteRunsOlderThan(after, 1)).toBe(1);
+			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({
@@ -477,7 +608,7 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const leases = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
@@ -485,16 +616,41 @@ const queueConformance = (label, makeQueue) => {
 			expect(leases[0].token).toBeTruthy();
 			expect(leases[0].expiresAt.getTime()).toBe(at(1e3).getTime());
 		});
+		it("depth reports backlog, in-flight, and the oldest-claimable age", async () => {
+			const q = await makeQueue();
+			expect(await q.depth(at(0))).toEqual({
+				claimable: 0,
+				leased: 0,
+				oldestClaimableAgeMs: null
+			});
+			await q.enqueue("r1", { runAt: at(0) });
+			await q.enqueue("r2", { runAt: at(5e3) });
+			expect(await q.depth(at(1e3))).toEqual({
+				claimable: 1,
+				leased: 0,
+				oldestClaimableAgeMs: 1e3
+			});
+			expect((await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(1e3)
+			})).map((l) => l.runId)).toEqual(["r1"]);
+			expect(await q.depth(at(1e3))).toEqual({
+				claimable: 0,
+				leased: 1,
+				oldestClaimableAgeMs: null
+			});
+		});
 		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,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).toEqual([]);
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(5e3)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -503,12 +659,12 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			expect(await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).toHaveLength(1);
 			expect(await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(500)
 			})).toEqual([]);
@@ -517,12 +673,12 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const first = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			const reclaim = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1001)
 			});
@@ -533,7 +689,7 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [lease] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
@@ -542,12 +698,12 @@ const queueConformance = (label, makeQueue) => {
 				now: at(500)
 			});
 			expect(await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1001)
 			})).toEqual([]);
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1501)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -556,12 +712,12 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [stale] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1001)
 			});
@@ -574,13 +730,13 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [lease] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.ack(lease, { now: at(1) });
 			expect(await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(2e3)
 			})).toEqual([]);
@@ -589,18 +745,18 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [stale] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1001)
 			});
 			await q.ack(stale, { now: at(1002) });
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(2002)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -609,14 +765,14 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [lease] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.enqueue("r1");
 			await q.ack(lease, { now: at(1) });
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(2)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -625,13 +781,13 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [lease] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.ack(lease, { now: at(1001) });
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(1002)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -640,7 +796,7 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			const [lease] = await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
@@ -653,59 +809,22 @@ const queueConformance = (label, makeQueue) => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
 			await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			});
 			await q.enqueue("r1", { priority: 1 });
 			expect(await q.claim({
-				max: 10,
+				limit: 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 () => {
+		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({
-				max: 2,
+				limit: 2,
 				leaseMs: 1e3,
 				now: at(0)
 			})).toHaveLength(2);
@@ -715,7 +834,7 @@ const queueConformance = (label, makeQueue) => {
 			await q.enqueue("low", { priority: 10 });
 			await q.enqueue("high", { priority: 1 });
 			const [first] = await q.claim({
-				max: 1,
+				limit: 1,
 				leaseMs: 1e3,
 				now: at(0)
 			});
@@ -726,7 +845,7 @@ const queueConformance = (label, makeQueue) => {
 			await q.enqueue("r1");
 			await q.enqueue("r1", { priority: 5 });
 			expect((await q.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).map((l) => l.runId)).toEqual(["r1"]);
@@ -746,11 +865,11 @@ const timerConformance = (label, makeTimer) => {
 			await tm.schedule("r1", at(1e3));
 			expect(await tm.dueBatch({
 				now: at(999),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 			expect(await tm.dueBatch({
 				now: at(1e3),
-				max: 10
+				limit: 10
 			})).toEqual(["r1"]);
 		});
 		it("dueBatch fires exactly once — a consumed timer is not returned again", async () => {
@@ -758,11 +877,11 @@ const timerConformance = (label, makeTimer) => {
 			await tm.schedule("r1", at(0));
 			expect(await tm.dueBatch({
 				now: at(1),
-				max: 10
+				limit: 10
 			})).toEqual(["r1"]);
 			expect(await tm.dueBatch({
 				now: at(2),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 		});
 		it("reschedule is an upsert — the latest fireAt wins", async () => {
@@ -771,11 +890,11 @@ const timerConformance = (label, makeTimer) => {
 			await tm.schedule("r1", at(5e3));
 			expect(await tm.dueBatch({
 				now: at(2e3),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 			expect(await tm.dueBatch({
 				now: at(5e3),
-				max: 10
+				limit: 10
 			})).toEqual(["r1"]);
 		});
 		it("reschedule EARLIER also wins — upsert, not a LEAST(fire_at) merge", async () => {
@@ -784,7 +903,7 @@ const timerConformance = (label, makeTimer) => {
 			await tm.schedule("r1", at(1e3));
 			expect(await tm.dueBatch({
 				now: at(1e3),
-				max: 10
+				limit: 10
 			})).toEqual(["r1"]);
 		});
 		it("cancel removes a pending timer", async () => {
@@ -793,17 +912,17 @@ const timerConformance = (label, makeTimer) => {
 			await tm.cancel("r1");
 			expect(await tm.dueBatch({
 				now: at(2e3),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 		});
-		it("dueBatch honours max and returns earliest-first", async () => {
+		it("dueBatch honours limit 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
+				limit: 2
 			})).toEqual(["early", "mid"]);
 		});
 	});
@@ -893,7 +1012,7 @@ const outboxConformance = (label, makeBackend) => {
 				attempts: 1
 			}, { enqueue: [{ runId }] });
 			expect((await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).map((l) => l.runId)).toEqual([runId]);
@@ -922,7 +1041,7 @@ const outboxConformance = (label, makeBackend) => {
 			}] });
 			expect((await store.loadRun(childId))?.run.input).toEqual({ n: 1 });
 			expect((await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).map((l) => l.runId)).toContain(childId);
@@ -958,7 +1077,7 @@ const outboxConformance = (label, makeBackend) => {
 				attempts: 2
 			}, spawn);
 			expect((await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).filter((l) => l.runId === childId)).toHaveLength(1);
@@ -978,11 +1097,11 @@ const outboxConformance = (label, makeBackend) => {
 			expect((await store.loadRun(runId))?.run.status).toBe("sleeping");
 			expect(await timer.dueBatch({
 				now: at(4999),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 			expect(await timer.dueBatch({
 				now: at(5e3),
-				max: 10
+				limit: 10
 			})).toEqual([runId]);
 		});
 		it("suspendRun is a no-op on a terminal run — no zombie wake timer", async () => {
@@ -1003,7 +1122,7 @@ const outboxConformance = (label, makeBackend) => {
 			expect((await store.loadRun(runId))?.run.status).toBe("done");
 			expect(await timer.dueBatch({
 				now: at(5e3),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 		});
 		it("markTerminal wakes a suspended parent atomically (enqueue in the same write)", async () => {
@@ -1024,7 +1143,7 @@ const outboxConformance = (label, makeBackend) => {
 				output: 7
 			}, { enqueue: [{ runId: parent.runId }] });
 			expect((await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).map((l) => l.runId)).toContain(parent.runId);
@@ -1047,7 +1166,7 @@ const outboxConformance = (label, makeBackend) => {
 			}, { cancelTimers: [runId] });
 			expect(await timer.dueBatch({
 				now: at(5e3),
-				max: 10
+				limit: 10
 			})).toEqual([]);
 		});
 		it("a canceled run's markTerminal is sticky AND skips its outbox", async () => {
@@ -1064,7 +1183,7 @@ const outboxConformance = (label, makeBackend) => {
 			}, { enqueue: [{ runId }] });
 			expect((await store.loadRun(runId))?.run.status).toBe("canceled");
 			expect(await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).toEqual([]);
@@ -1096,7 +1215,7 @@ const signalConformance = (label, makeBackend) => {
 				payload: { ok: true }
 			}]);
 			expect((await queue.claim({
-				max: 10,
+				limit: 10,
 				leaseMs: 1e3,
 				now: at(0)
 			})).map((l) => l.runId)).toEqual([runId]);
@@ -1228,6 +1347,61 @@ const reconcileConformance = (label, makeBackend) => {
 			});
 			expect(await store.orphanedRuns(10)).toContain(parent.runId);
 		});
+		it("a fan-out parent with a still-running child is NOT an orphan (join not resolved)", async () => {
+			const { store } = await makeBackend();
+			const parent = await store.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			const kids = await store.startManyRuns([{
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			}, {
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			}]);
+			await store.markRunning(parent.runId);
+			await store.suspendRun(parent.runId, "awaiting_child");
+			await store.markTerminal(kids[0].runId, {
+				status: "done",
+				output: 1
+			});
+			expect(await store.orphanedRuns(10)).not.toContain(parent.runId);
+		});
+		it("a fan-out parent with a FAILED child IS an orphan even while siblings run (fast-fail)", async () => {
+			const { store } = await makeBackend();
+			const parent = await store.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			const kids = await store.startManyRuns([{
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			}, {
+				name: "c",
+				version: 1,
+				input: {},
+				parentRunId: parent.runId
+			}]);
+			await store.markRunning(parent.runId);
+			await store.suspendRun(parent.runId, "awaiting_child");
+			await store.markTerminal(kids[0].runId, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "boom"
+				}
+			});
+			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({
@@ -1300,4 +1474,405 @@ const cronConformance = (label, makeStore) => {
 	});
 };
 //#endregion
-export { cronConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };
+//#region src/engine.ts
+/**
+* Engine-behavior conformance: the composed durable behaviors (retry/dead-letter, signal
+* resume, cancel cascade, drift) run against every backend, not just memory — so a real
+* serialization/consistency regression can't hide behind the port-conformance suites.
+*/
+const engineConformance = (label, makeBackend) => {
+	describe(`engine conformance (${label})`, () => {
+		const base = {
+			batchMax: 16,
+			leaseMs: 6e5
+		};
+		const drive = async (backend, flows, runId, retry) => {
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const now = () => clock;
+			for (let i = 0; i < 200; i++) {
+				await tickOnce(backend, flows, {
+					...base,
+					now,
+					retry
+				});
+				const run = await backend.store.loadRunRow(runId);
+				if (run && isTerminal(run.status)) return run;
+				clock = new Date(clock.getTime() + 6e4);
+			}
+			throw new Error("run did not settle");
+		};
+		it("a run dispatched far more than maxAttempts times (many sleeps) completes", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "poller",
+				version: 1,
+				run: async (ctx) => {
+					for (let i = 0; i < 6; i++) await ctx.sleep(1e3);
+					return "settled";
+				}
+			});
+			const runId = await submit(backend, flow, {});
+			expect(await drive(backend, registry([flow]), runId, {
+				maxAttempts: 3,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			})).toMatchObject({
+				status: "done",
+				output: "settled"
+			});
+		});
+		it("runs a builder flow with a durable sleep to completion", async () => {
+			const backend = await makeBackend();
+			const flow = builder(`${label}-sleep`, 1).step("doubled", (acc) => acc.input.x * 2).step("nap", async (_acc, ctx) => {
+				await ctx.sleep(5e3);
+				return "rested";
+			}).output((acc) => ({
+				doubled: acc.doubled,
+				nap: acc.nap
+			}));
+			const runId = await submit(backend, flow, { x: 21 });
+			expect(await drive(backend, registry([flow]), runId)).toMatchObject({
+				status: "done",
+				output: {
+					doubled: 42,
+					nap: "rested"
+				}
+			});
+		});
+		it("a genuinely failing step still dead-letters after its retry budget", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "always-throws",
+				version: 1,
+				run: async (ctx) => ctx.step("boom", () => {
+					throw new Error("nope");
+				})
+			});
+			const runId = await submit(backend, flow, {});
+			expect((await drive(backend, registry([flow]), runId, {
+				maxAttempts: 2,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			})).status).toBe("failed");
+		});
+		it("dead-letters a poison-pill (uncatchable-crash) run once attempts exceed the cap", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "poison",
+				version: 1,
+				run: async () => 1
+			});
+			const runId = await submit(backend, flow, {});
+			for (let i = 0; i < 5; i++) await backend.store.markRunning(runId);
+			await tickOnce(backend, registry([flow]), {
+				...base,
+				now: () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z"),
+				retry: {
+					maxAttempts: 3,
+					baseDelayMs: 1,
+					maxDelayMs: 1
+				}
+			});
+			const run = await backend.store.loadRunRow(runId);
+			expect(run?.status).toBe("failed");
+			expect(run?.error?.code).toBe("RUN_ATTEMPTS_EXHAUSTED");
+		});
+		it("awaits an external signal, parks, and resumes with its payload", async () => {
+			const backend = await makeBackend();
+			const flow = defineFlow({
+				name: "approve",
+				version: 1,
+				signals: { go: signalType() },
+				run: async (ctx) => {
+					return (await ctx.signal("go")).ok ? "shipped" : "held";
+				}
+			});
+			const flows = registry([flow]);
+			const runId = await submit(backend, flow, {});
+			await tickOnce(backend, flows, {
+				...base,
+				now: () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z")
+			});
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("awaiting_signal");
+			await signalRun(backend, runId, "go", { ok: true });
+			expect(await drive(backend, flows, runId)).toMatchObject({
+				status: "done",
+				output: "shipped"
+			});
+		});
+		it("cancels a run and cascades to grandchildren", async () => {
+			const backend = await makeBackend();
+			const grandchild = defineFlow({
+				name: "gc",
+				version: 1,
+				run: async (ctx) => {
+					await ctx.sleep(1e7);
+					return "gc";
+				}
+			});
+			const child = defineFlow({
+				name: "c",
+				version: 1,
+				run: async (ctx) => ctx.invoke(grandchild, {})
+			});
+			const parent = defineFlow({
+				name: "p",
+				version: 1,
+				run: async (ctx) => ctx.invoke(child, {})
+			});
+			const flows = registry([
+				parent,
+				child,
+				grandchild
+			]);
+			const parentId = await submit(backend, parent, {});
+			let clock = /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			for (let i = 0; i < 10; i++) {
+				await tickOnce(backend, flows, {
+					...base,
+					now: () => clock
+				});
+				clock = new Date(clock.getTime() + 1e3);
+			}
+			await cancelRun(backend, parentId);
+			const kids = await backend.store.childrenOf(parentId);
+			expect(kids.length).toBeGreaterThan(0);
+			const childId = kids[0].id;
+			const grandkids = await backend.store.childrenOf(childId);
+			expect((await backend.store.loadRunRow(parentId))?.status).toBe("canceled");
+			expect((await backend.store.loadRunRow(childId))?.status).toBe("canceled");
+			if (grandkids[0]) expect((await backend.store.loadRunRow(grandkids[0].id))?.status).toBe("canceled");
+		});
+		it("a child of an already-terminated parent cancels itself on dispatch (crash-safe cascade)", async () => {
+			const backend = await makeBackend();
+			const orphan = defineFlow({
+				name: "orphan",
+				version: 1,
+				run: async (ctx) => {
+					await ctx.sleep(1e3);
+					return 1;
+				}
+			});
+			const { runId: parentId } = await backend.store.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			await backend.store.markTerminal(parentId, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "parent died"
+				}
+			});
+			const { runId: childId } = await backend.store.startRun({
+				name: "orphan",
+				version: 1,
+				input: {},
+				parentRunId: parentId,
+				parentCursorKey: "s0"
+			});
+			await backend.queue.enqueue(childId);
+			await tickOnce(backend, registry([orphan]), {
+				...base,
+				now: () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z")
+			});
+			expect((await backend.store.loadRunRow(childId))?.status).toBe("canceled");
+		});
+		it("reconcile cancels a sleeping child left behind by a dead parent", async () => {
+			const backend = await makeBackend();
+			const now = () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			const orphan = defineFlow({
+				name: "orphan2",
+				version: 1,
+				run: async (ctx) => {
+					await ctx.sleep(1e7);
+					return 1;
+				}
+			});
+			const { runId: parentId } = await backend.store.startRun({
+				name: "p",
+				version: 1,
+				input: {}
+			});
+			const { runId: childId } = await backend.store.startRun({
+				name: "orphan2",
+				version: 1,
+				input: {},
+				parentRunId: parentId,
+				parentCursorKey: "s0"
+			});
+			await backend.queue.enqueue(childId);
+			await tickOnce(backend, registry([orphan]), {
+				...base,
+				now
+			});
+			expect((await backend.store.loadRunRow(childId))?.status).toBe("sleeping");
+			await backend.store.markTerminal(parentId, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "died"
+				}
+			});
+			await reconcile(backend, { limit: 16 });
+			await tickOnce(backend, registry([orphan]), {
+				...base,
+				now
+			});
+			expect((await backend.store.loadRunRow(childId))?.status).toBe("canceled");
+		});
+		it("fans out children in parallel and joins their outputs in order", async () => {
+			const backend = await makeBackend();
+			const dbl = defineFlow({
+				name: "dbl",
+				version: 1,
+				run: async (_ctx, n) => n * 2
+			});
+			const parent = defineFlow({
+				name: "fan",
+				version: 1,
+				run: async (ctx) => ctx.invoke([
+					{
+						flow: dbl,
+						input: 1
+					},
+					{
+						flow: dbl,
+						input: 2
+					},
+					{
+						flow: dbl,
+						input: 3
+					}
+				])
+			});
+			const runId = await submit(backend, parent, {});
+			expect(await drive(backend, registry([parent, dbl]), runId)).toMatchObject({
+				status: "done",
+				output: [
+					2,
+					4,
+					6
+				]
+			});
+		});
+		it("rejects a fan-out beyond the cap", async () => {
+			const backend = await makeBackend();
+			const noop = defineFlow({
+				name: "noop",
+				version: 1,
+				run: async () => 1
+			});
+			const parent = defineFlow({
+				name: "toobig",
+				version: 1,
+				run: async (ctx) => ctx.invoke(Array.from({ length: 10001 }, () => ({
+					flow: noop,
+					input: {}
+				})))
+			});
+			const runId = await submit(backend, parent, {});
+			await tickOnce(backend, registry([parent, noop]), {
+				...base,
+				now: () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z"),
+				retry: {
+					maxAttempts: 1,
+					baseDelayMs: 1,
+					maxDelayMs: 1
+				}
+			});
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("failed");
+		});
+		it("caps invoke recursion at the depth limit and persists each run's depth", async () => {
+			const backend = await makeBackend();
+			const recurse = defineFlow({
+				name: "recurse",
+				version: 1,
+				policy: { maxDepth: 3 },
+				run: async (ctx, n) => ctx.invoke(recurse, n + 1)
+			});
+			const runId = await submit(backend, recurse, 0);
+			expect((await drive(backend, registry([recurse]), runId, {
+				maxAttempts: 1,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			})).status).toBe("failed");
+			let cur = runId;
+			let deepest = await backend.store.loadRunRow(cur);
+			for (;;) {
+				const kids = await backend.store.childrenOf(cur);
+				if (kids.length === 0) break;
+				deepest = kids[0];
+				cur = kids[0].id;
+			}
+			expect(deepest?.depth).toBe(3);
+			expect(deepest?.error?.message).toContain("depth");
+		});
+		it("fans out a batch larger than one spawn chunk (crosses chunk boundaries)", async () => {
+			const backend = await makeBackend();
+			const inc = defineFlow({
+				name: "inc",
+				version: 1,
+				run: async (_ctx, n) => n + 1
+			});
+			const parent = defineFlow({
+				name: "wide",
+				version: 1,
+				run: async (ctx) => ctx.invoke(Array.from({ length: 45 }, (_v, n) => ({
+					flow: inc,
+					input: n
+				})))
+			});
+			const runId = await submit(backend, parent, {});
+			const run = await drive(backend, registry([parent, inc]), runId);
+			expect(run.status).toBe("done");
+			expect(run.output).toEqual(Array.from({ length: 45 }, (_v, n) => n + 1));
+		});
+		it("fast-fails a fan-out and cancels the running siblings when one child fails", async () => {
+			const backend = await makeBackend();
+			const boom = defineFlow({
+				name: "boom",
+				version: 1,
+				run: async () => {
+					throw new Error("boom");
+				}
+			});
+			const slow = defineFlow({
+				name: "slow",
+				version: 1,
+				run: async (ctx) => {
+					await ctx.sleep(1e7);
+					return 1;
+				}
+			});
+			const parent = defineFlow({
+				name: "fanfail",
+				version: 1,
+				run: async (ctx) => ctx.invoke([{
+					flow: boom,
+					input: {}
+				}, {
+					flow: slow,
+					input: {}
+				}])
+			});
+			const runId = await submit(backend, parent, {});
+			expect((await drive(backend, registry([
+				parent,
+				boom,
+				slow
+			]), runId, {
+				maxAttempts: 1,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			})).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);
+		});
+	});
+};
+//#endregion
+export { cronConformance, engineConformance, outboxConformance, queueConformance, reconcileConformance, signalConformance, storeConformance, timerConformance, wakeupConformance };

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@iterativeflow/conformance",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahmedrowaihi/iterativeflow.git",
+    "directory": "v2/packages/conformance"
+  },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "type": "module",
   "imports": {
@@ -21,7 +28,7 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "@iterativeflow/core": "2.0.0-alpha.1"
+    "@iterativeflow/core": "2.0.0-alpha.2"
   },
   "peerDependencies": {
     "vitest": ">=3"