@iterativeflow/conformance 2.7.0 → 3.0.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { builder, cancelRun, defineFlow, reconcile, registry, runTick, serverlessTick, signalRun, signalType, submit, tickOnce } from "@iterativeflow/core";
+import { assert, describe, expect, it } from "vitest";
+import { cancelRun, defineFlow, reconcile, registry, runTick, serverlessTick, signalRun, submit, tickOnce } from "@iterativeflow/core";
 import { isTerminal } from "@iterativeflow/core/backend";
 //#region src/store.ts
 /**
@@ -234,10 +234,23 @@ const storeConformance = (label, makeStore) => {
 				result: { at },
 				attempts: 1
 			});
-			const memo = (await s.loadRun(runId))?.steps.get("a")?.result;
-			expect(memo.at).toBe("2030-01-01T00:00:00.000Z");
+			expect((await s.loadRun(runId))?.steps.get("a")?.result).toEqual({ at: "2030-01-01T00:00:00.000Z" });
 		});
-		it("checkpointStep round-trips the shape tag (drift-guard evidence)", async () => {
+		it("a run's output round-trips through JSON — a Date comes back as a string on every backend", async () => {
+			const s = await makeStore();
+			const { runId } = await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			});
+			const at = /* @__PURE__ */ new Date("2030-01-01T00:00:00.000Z");
+			await s.markTerminal(runId, {
+				status: "done",
+				output: { at }
+			});
+			expect((await s.loadRunRow(runId))?.output).toEqual({ at: "2030-01-01T00:00:00.000Z" });
+		});
+		it("checkpointStep round-trips the call that wrote it (drift-guard evidence)", async () => {
 			const s = await makeStore();
 			const { runId } = await s.startRun({
 				name: "f",
@@ -250,9 +263,9 @@ const storeConformance = (label, makeStore) => {
 				status: "ok",
 				result: 1,
 				attempts: 1,
-				shape: "step:charge"
+				call: "step:charge"
 			});
-			expect((await s.loadRun(runId))?.steps.get("a")?.shape).toBe("step:charge");
+			expect((await s.loadRun(runId))?.steps.get("a")?.call).toBe("step:charge");
 		});
 		it("checkpointStep is first-writer-wins — a second write does NOT overwrite (exactly-once memo)", async () => {
 			const s = await makeStore();
@@ -443,8 +456,9 @@ const storeConformance = (label, makeStore) => {
 				otherName,
 				live
 			]) expect(await s.loadRunRow(spared)).toBeDefined();
+			const fromTheWire = JSON.parse(`{"status":"pending"}`);
 			expect(await s.deleteRuns({
-				status: "pending",
+				...fromTheWire,
 				before: /* @__PURE__ */ new Date()
 			}, 100)).toBe(0);
 			expect((await s.loadRunRow(live))?.status).toBe("pending");
@@ -506,12 +520,17 @@ const storeConformance = (label, makeStore) => {
 				attempts: 1
 			});
 			const snap = await s.loadRun(runId);
-			snap.run.input.n = 999;
-			snap.steps.get("a").result.v = 999;
+			const input = snap?.run.input;
+			const result = snap?.steps.get("a")?.result;
+			assert(input instanceof Object && "n" in input);
+			assert(result instanceof Object && "v" in result);
+			assert(snap?.steps instanceof Map);
+			input.n = 999;
+			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);
+			expect(again?.run.input).toEqual({ n: 1 });
+			expect(again?.steps.get("a")?.result).toEqual({ v: 1 });
 		});
 		it("caller mutating the input after startRun can't reach the stored run", async () => {
 			const s = await makeStore();
@@ -654,6 +673,44 @@ const storeConformance = (label, makeStore) => {
 			expect((await s.loadRunRow(runId))?.attempts).toBe(0);
 			expect(await s.markRunning(runId)).toBe(1);
 		});
+		it("markTerminal never overwrites a terminal run — a late cancel keeps the outcome", async () => {
+			const s = await makeStore();
+			const done = (await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			})).runId;
+			const failed = (await s.startRun({
+				name: "f",
+				version: 1,
+				input: {}
+			})).runId;
+			await s.markTerminal(done, {
+				status: "done",
+				output: { total: 42 }
+			});
+			await s.markTerminal(failed, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "boom"
+				}
+			});
+			await s.markTerminal(done, { status: "canceled" });
+			await s.markTerminal(failed, { status: "canceled" });
+			expect(await s.loadRunRow(done)).toMatchObject({
+				status: "done",
+				output: { total: 42 }
+			});
+			expect(await s.loadRunRow(failed)).toMatchObject({
+				status: "failed",
+				error: {
+					code: "X",
+					message: "boom"
+				}
+			});
+			expect((await s.retryRun(failed)).retried).toBe(true);
+		});
 		it("cancelRuns cancels the live matched set and never a terminal run", async () => {
 			const s = await makeStore();
 			const mk = async (name) => (await s.startRun({
@@ -677,6 +734,34 @@ const storeConformance = (label, makeStore) => {
 			expect(await s.cancelRuns({ name: "f" }, 100)).toBe(0);
 			await expect(s.cancelRuns({}, 100)).rejects.toThrow();
 		});
+		it("cancelRuns and retryRuns narrow by tag, never widening to untagged runs", async () => {
+			const s = await makeStore();
+			const mk = async (tags) => (await s.startRun({
+				name: "f",
+				version: 1,
+				input: {},
+				tags
+			})).runId;
+			const tenant = await mk(["tenant:42"]);
+			const neighbour = await mk(["tenant:7"]);
+			const untagged = await mk();
+			expect(await s.cancelRuns({ tag: "tenant:42" }, 100)).toBe(1);
+			expect((await s.loadRunRow(tenant))?.status).toBe("canceled");
+			expect((await s.loadRunRow(neighbour))?.status).toBe("pending");
+			expect((await s.loadRunRow(untagged))?.status).toBe("pending");
+			const failedTenant = await mk(["tenant:42"]);
+			const failedNeighbour = await mk(["tenant:7"]);
+			for (const id of [failedTenant, failedNeighbour]) await s.markTerminal(id, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "x"
+				}
+			});
+			expect(await s.retryRuns({ tag: "tenant:42" }, 100)).toBe(1);
+			expect((await s.loadRunRow(failedTenant))?.status).toBe("pending");
+			expect((await s.loadRunRow(failedNeighbour))?.status).toBe("failed");
+		});
 		it("retryRuns re-drives the failed matched set, clearing the spent attempt budget", async () => {
 			const s = await makeStore();
 			const mk = async (name) => (await s.startRun({
@@ -1021,6 +1106,26 @@ const queueConformance = (label, makeQueue) => {
 			});
 			expect(first.runId).toBe("high");
 		});
+		it("negative priorities order numerically, before zero", async () => {
+			const q = await makeQueue();
+			await q.enqueue("zero", { priority: 0 });
+			await q.enqueue("minus3", { priority: -3 });
+			await q.enqueue("minus5", { priority: -5 });
+			const order = [];
+			for (let i = 0; i < 3; i++) {
+				const [l] = await q.claim({
+					limit: 1,
+					leaseMs: 6e4,
+					now: at(0)
+				});
+				order.push(l.runId);
+			}
+			expect(order).toEqual([
+				"minus5",
+				"minus3",
+				"zero"
+			]);
+		});
 		it("re-enqueue is an upsert keyed by runId — claimed once", async () => {
 			const q = await makeQueue();
 			await q.enqueue("r1");
@@ -1032,6 +1137,98 @@ const queueConformance = (label, makeQueue) => {
 			});
 			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
 		});
+		it("enqueueMany enqueues every run, honouring per-request runAt and priority", async () => {
+			const q = await makeQueue();
+			await q.enqueueMany([
+				{
+					runId: "low",
+					opts: { priority: 10 }
+				},
+				{
+					runId: "high",
+					opts: { priority: 1 }
+				},
+				{
+					runId: "later",
+					opts: { runAt: at(5e3) }
+				}
+			]);
+			expect(await q.depth(at(0))).toMatchObject({
+				claimable: 2,
+				leased: 0
+			});
+			const [first] = await q.claim({
+				limit: 1,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(first.runId).toBe("high");
+			const rest = await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(rest.map((l) => l.runId)).toEqual(["low"]);
+		});
+		it("enqueueMany on an empty list is a no-op", async () => {
+			const q = await makeQueue();
+			await q.enqueueMany([]);
+			expect(await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			})).toEqual([]);
+		});
+		it("enqueueMany collapses duplicate runIds into one upsert, bumping version once", async () => {
+			const q = await makeQueue();
+			await q.enqueueMany([{
+				runId: "r1",
+				opts: { priority: 9 }
+			}, {
+				runId: "r1",
+				opts: { priority: 2 }
+			}]);
+			const leases = await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
+			expect(leases[0].version).toBe(1);
+		});
+		it("enqueueMany does not yank an active lease, and its wake survives the ack", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1");
+			const [lease] = await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			await q.enqueueMany([{ runId: "r1" }]);
+			expect(await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(500)
+			})).toEqual([]);
+			await q.ack(lease, { now: at(600) });
+			const again = await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(601)
+			});
+			expect(again.map((l) => l.runId)).toEqual(["r1"]);
+		});
+		it("enqueueMany re-enqueues an existing job rather than duplicating it", async () => {
+			const q = await makeQueue();
+			await q.enqueue("r1", { runAt: at(9e3) });
+			await q.enqueueMany([{ runId: "r1" }]);
+			const leases = await q.claim({
+				limit: 10,
+				leaseMs: 1e3,
+				now: at(0)
+			});
+			expect(leases.map((l) => l.runId)).toEqual(["r1"]);
+		});
 	});
 };
 //#endregion
@@ -1805,6 +2002,16 @@ const cronConformance = (label, makeStore) => {
 };
 //#endregion
 //#region src/engine.ts
+const okSchema = { "~standard": {
+	version: 1,
+	vendor: "conformance",
+	validate: (v) => v instanceof Object && "ok" in v ? { value: { ok: v.ok === true } } : { issues: [{ message: "ok is required" }] }
+} };
+const textSchema = { "~standard": {
+	version: 1,
+	vendor: "conformance",
+	validate: (v) => v === String(v) ? { value: String(v) } : { issues: [{ message: "not text" }] }
+} };
 /**
 * 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
@@ -1852,15 +2059,20 @@ const engineConformance = (label, makeBackend) => {
 				output: "settled"
 			});
 		});
-		it("runs a builder flow with a durable sleep to completion", async () => {
+		it("a flow with a durable sleep between steps resumes 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 flow = defineFlow({
+				name: `${label}-sleep`,
+				version: 1,
+				run: async (ctx, input) => {
+					const doubled = await ctx.step("doubled", () => input.x * 2);
+					await ctx.sleep(5e3);
+					return {
+						doubled,
+						nap: await ctx.step("nap", () => "rested")
+					};
+				}
+			});
 			const runId = await submit(backend, flow, { x: 21 });
 			const run = await drive(backend, registry([flow]), runId);
 			expect(run).toMatchObject({
@@ -1915,7 +2127,7 @@ const engineConformance = (label, makeBackend) => {
 			const flow = defineFlow({
 				name: "approve",
 				version: 1,
-				signals: { go: signalType() },
+				signals: { go: okSchema },
 				run: async (ctx) => {
 					return (await ctx.signal("go")).ok ? "shipped" : "held";
 				}
@@ -2209,6 +2421,310 @@ const engineConformance = (label, makeBackend) => {
 			expect(kids.every((k) => isTerminal(k.status))).toBe(true);
 			expect(kids.some((k) => k.status === "canceled")).toBe(true);
 		});
+		it("a settled fan-out returns every child's result and cancels no sibling", async () => {
+			const backend = await makeBackend();
+			const ok = defineFlow({
+				name: "settle-ok",
+				version: 1,
+				run: async (_ctx, n) => n
+			});
+			const boom = defineFlow({
+				name: "settle-boom",
+				version: 1,
+				run: async () => {
+					throw new Error("boom");
+				}
+			});
+			const parent = defineFlow({
+				name: "settle-fan",
+				version: 1,
+				run: async (ctx) => ctx.invoke([
+					{
+						flow: ok,
+						input: 1
+					},
+					{
+						flow: boom,
+						input: {}
+					},
+					{
+						flow: ok,
+						input: 2
+					}
+				], { onChildFailure: "settle" })
+			});
+			const runId = await submit(backend, parent, {});
+			const run = await drive(backend, registry([
+				parent,
+				ok,
+				boom
+			]), runId, {
+				maxAttempts: 1,
+				baseDelayMs: 1,
+				maxDelayMs: 1
+			});
+			expect(run).toMatchObject({
+				status: "done",
+				output: [
+					{
+						status: "done",
+						output: 1
+					},
+					{
+						status: "failed",
+						error: { message: "boom" }
+					},
+					{
+						status: "done",
+						output: 2
+					}
+				]
+			});
+			const kids = await backend.store.childrenOf(runId);
+			expect(kids.filter((k) => k.status === "canceled")).toHaveLength(0);
+		});
+		const waiter = defineFlow({
+			name: "waits-forever",
+			version: 1,
+			run: async (ctx) => {
+				await ctx.signal("never");
+				return 1;
+			}
+		});
+		const parkOnChild = async (backend, parent) => {
+			const flows = registry([parent, waiter]);
+			const runId = await submit(backend, parent, {});
+			const now = () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			await tickOnce(backend, flows, {
+				...base,
+				now
+			});
+			await tickOnce(backend, flows, {
+				...base,
+				now
+			});
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("awaiting_child");
+			const [child] = await backend.store.childrenOf(runId);
+			return {
+				runId,
+				childId: child.id,
+				tick: () => tickOnce(backend, flows, {
+					...base,
+					now
+				})
+			};
+		};
+		it("canceling a child wakes its fail-fast parent without waiting for reconcile", async () => {
+			const backend = await makeBackend();
+			const parent = defineFlow({
+				name: "waits-on-child",
+				version: 1,
+				run: async (ctx) => ctx.invoke(waiter, {})
+			});
+			const { runId, childId, tick } = await parkOnChild(backend, parent);
+			await cancelRun(backend, childId);
+			await tick();
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("failed");
+		});
+		it("a settled parent reports a canceled child as canceled and completes", async () => {
+			const backend = await makeBackend();
+			const parent = defineFlow({
+				name: "settles-on-child",
+				version: 1,
+				run: async (ctx) => ctx.invoke(waiter, {}, { onChildFailure: "settle" })
+			});
+			const { runId, childId, tick } = await parkOnChild(backend, parent);
+			await cancelRun(backend, childId);
+			await tick();
+			expect(await backend.store.loadRunRow(runId)).toMatchObject({
+				status: "done",
+				output: { status: "canceled" }
+			});
+		});
+		const wide = (inc) => defineFlow({
+			name: "wide-chunks",
+			version: 1,
+			run: async (ctx) => ctx.invoke(Array.from({ length: 45 }, (_v, n) => ({
+				flow: inc,
+				input: n
+			})))
+		});
+		const inc = defineFlow({
+			name: "inc-chunk",
+			version: 1,
+			run: async (_ctx, n) => n + 1
+		});
+		const secondChunk = (call) => call?.startsWith("invokeAll:1:") ?? false;
+		it("a crash right after a spawn chunk commits spawns no child twice", async () => {
+			const real = await makeBackend();
+			let crashed = false;
+			const backend = {
+				...real,
+				store: {
+					...real.store,
+					checkpointStep: async (c, fx) => {
+						const stored = await real.store.checkpointStep(c, fx);
+						if (!crashed && secondChunk(c.call)) {
+							crashed = true;
+							throw new Error("worker died after the commit");
+						}
+						return stored;
+					}
+				}
+			};
+			const parent = wide(inc);
+			const runId = await submit(backend, parent, {});
+			const run = await drive(backend, registry([parent, inc]), runId);
+			expect(crashed).toBe(true);
+			expect(run.output).toEqual(Array.from({ length: 45 }, (_v, n) => n + 1));
+			expect(await backend.store.childrenOf(runId)).toHaveLength(45);
+		});
+		it("a parent canceled between spawn chunks leaves no child running", async () => {
+			const real = await makeBackend();
+			const parent = wide(inc);
+			const runId = await submit(real, parent, {});
+			let canceled = false;
+			const backend = {
+				...real,
+				store: {
+					...real.store,
+					checkpointStep: async (c, fx) => {
+						if (!canceled && secondChunk(c.call)) {
+							canceled = true;
+							await cancelRun(real, runId);
+						}
+						return real.store.checkpointStep(c, fx);
+					}
+				}
+			};
+			const flows = registry([parent, inc]);
+			const now = () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			for (let i = 0; i < 10; i++) await tickOnce(backend, flows, {
+				...base,
+				now
+			});
+			expect(canceled).toBe(true);
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("canceled");
+			const kids = await backend.store.childrenOf(runId);
+			expect(kids.length).toBeGreaterThan(0);
+			expect(kids.every((k) => k.status === "canceled")).toBe(true);
+		});
+		it("a child that finishes while its parent is mid-replay still wakes the parent", async () => {
+			const real = await makeBackend();
+			const quick = defineFlow({
+				name: "quick-child",
+				version: 1,
+				run: async () => 7
+			});
+			const parent = defineFlow({
+				name: "replaying-parent",
+				version: 1,
+				run: async (ctx) => ctx.invoke(quick, {})
+			});
+			const flows = registry([parent, quick]);
+			const now = () => /* @__PURE__ */ new Date("2030-01-01T00:00:00Z");
+			let raced = false;
+			const backend = {
+				...real,
+				store: {
+					...real.store,
+					loadRunRow: async (id) => {
+						const row = await real.store.loadRunRow(id);
+						if (!raced && row?.name === "quick-child") {
+							raced = true;
+							await tickOnce(real, flows, {
+								...base,
+								now,
+								names: ["quick-child"]
+							});
+						}
+						return row;
+					}
+				}
+			};
+			const runId = await submit(backend, parent, {});
+			await tickOnce(backend, flows, {
+				...base,
+				now,
+				names: ["replaying-parent"]
+			});
+			expect(raced).toBe(true);
+			expect((await real.store.loadRunRow(runId))?.status).toBe("awaiting_child");
+			const run = await drive(real, flows, runId);
+			expect(run).toMatchObject({
+				status: "done",
+				output: 7
+			});
+		});
+		it("a re-enqueue with no priority keeps the run's own priority", async () => {
+			const backend = await makeBackend();
+			const at = (ms) => new Date(Date.UTC(2030, 0, 1) + ms);
+			const low = (await backend.store.startRun({
+				name: "p",
+				version: 1,
+				input: {},
+				priority: 10
+			})).runId;
+			const urgent = (await backend.store.startRun({
+				name: "p",
+				version: 1,
+				input: {},
+				priority: -10
+			})).runId;
+			await backend.queue.enqueueMany([{
+				runId: low,
+				opts: { runAt: at(0) }
+			}, {
+				runId: urgent,
+				opts: { runAt: at(1e3) }
+			}]);
+			const [first] = await backend.queue.claim({
+				limit: 1,
+				leaseMs: 6e4,
+				now: at(2e3)
+			});
+			expect(first.runId).toBe(urgent);
+		});
+		it("a signal delivery, a retry and a bulk retry keep the run's own priority", async () => {
+			const backend = await makeBackend();
+			const start = async (priority) => (await backend.store.startRun({
+				name: "p",
+				version: 1,
+				input: {},
+				priority
+			})).runId;
+			const claimFirst = async () => (await backend.queue.claim({
+				limit: 1,
+				leaseMs: 6e4
+			}))[0]?.runId;
+			const rival = async () => backend.queue.enqueue(await start(), { priority: -5 });
+			const signalled = await start(-10);
+			await rival();
+			await backend.store.postSignal(signalled, "go", {});
+			expect(await claimFirst()).toBe(signalled);
+			const retried = await start(-10);
+			await backend.store.markTerminal(retried, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "x"
+				}
+			});
+			await rival();
+			await backend.store.retryRun(retried);
+			expect(await claimFirst()).toBe(retried);
+			const bulk = await start(-10);
+			await backend.store.markTerminal(bulk, {
+				status: "failed",
+				error: {
+					code: "X",
+					message: "x"
+				}
+			});
+			await rival();
+			await backend.store.retryRuns({ status: "failed" }, 100);
+			expect(await claimFirst()).toBe(bulk);
+		});
 		it("a claimed run for an unregistered flow version parks and resumes once that version deploys", async () => {
 			const backend = await makeBackend();
 			const v1 = defineFlow({
@@ -2234,7 +2750,7 @@ const engineConformance = (label, makeBackend) => {
 				now,
 				retry: fast
 			});
-			expect((await backend.store.loadRunRow(runId))?.status).toBe("retrying");
+			expect((await backend.store.loadRunRow(runId))?.status).toBe("parked");
 			for (let i = 0; i < 4; i++) {
 				clock = new Date(clock.getTime() + 6e4);
 				await tickOnce(backend, registry([v1]), {
@@ -2242,7 +2758,7 @@ const engineConformance = (label, makeBackend) => {
 					now,
 					retry: fast
 				});
-				expect((await backend.store.loadRunRow(runId))?.status).toBe("retrying");
+				expect((await backend.store.loadRunRow(runId))?.status).toBe("parked");
 			}
 			const run = await drive(backend, registry([v2]), runId, fast, clock);
 			expect(run).toMatchObject({
@@ -2255,7 +2771,7 @@ const engineConformance = (label, makeBackend) => {
 			const flow = defineFlow({
 				name: "raced",
 				version: 1,
-				signals: { go: signalType() },
+				signals: { go: textSchema },
 				run: async (ctx) => {
 					const r = await ctx.signal("go", { timeoutMs: 5e3 });
 					return r.received ? `signal:${r.payload}` : "timeout";
@@ -2282,7 +2798,7 @@ const engineConformance = (label, makeBackend) => {
 			const flow = defineFlow({
 				name: "waits-out",
 				version: 1,
-				signals: { go: signalType() },
+				signals: { go: textSchema },
 				run: async (ctx) => {
 					return (await ctx.signal("go", { timeoutMs: 5e3 })).received ? "signal" : "timeout";
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterativeflow/conformance",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@iterativeflow/core": "2.7.0"
+    "@iterativeflow/core": "3.0.0"
   },
   "peerDependencies": {
     "vitest": ">=3"