effect-mq 0.5.0 → 0.7.0

package/dist/testing/conformance.js

@@ -14,6 +14,12 @@
  * Effect `Clock` (e.g. pass `now` into queries as a bind parameter) — never
  * from the database server's clock — so this works against real storage too.
  *
+ * Beyond the core queue contract, dedicated sections pin the flow contract:
+ * parent-side ownership (the FanOut ack, dependency rows, batched
+ * `recordChildResults`, every settle decision) and the child-side outbox
+ * (terminal transitions of envelope-carrying jobs staging reports for the
+ * relay to another store).
+ *
  * @since 0.1.0
  */
 import * as JobStore from "../JobStore.js";
@@ -34,6 +40,7 @@ const baseRequest = (overrides) => ({
     timeoutMs: undefined,
     dedupe: undefined,
     trace: undefined,
+    parent: undefined,
     delayMs: 0,
     ...overrides
 });
@@ -353,21 +360,137 @@ export const jobStoreConformance = (name, storeLayer) => {
         })));
         it.effect("list pagination is lossless when enqueue timestamps tie", () => withStore((store) => Effect.gen(function* () {
             // No clock adjustment: every record shares one enqueuedAt, so
-            // ordering and the cursor fall back entirely to the id tie-break.
+            // ordering and the cursor fall back entirely to the id tie-break —
+            // in both directions.
             for (let i = 0; i < 7; i++) {
                 yield* store.enqueue(baseRequest({ payload: { n: i } }));
             }
-            const seen = new Set();
-            let cursor;
-            do {
-                const page = yield* store.list({ limit: 3, cursor });
-                for (const item of page.items) {
-                    expect(seen.has(item.id)).toBe(false);
-                    seen.add(item.id);
+            for (const order of ["desc", "asc"]) {
+                const seen = [];
+                let cursor;
+                do {
+                    const page = yield* store.list({ limit: 3, order, cursor });
+                    for (const item of page.items) {
+                        expect(seen.includes(item.id)).toBe(false);
+                        seen.push(item.id);
+                    }
+                    cursor = page.cursor;
+                } while (cursor !== undefined);
+                expect(seen.length).toBe(7);
+                // Opposite directions walk exact mirror orders.
+                if (order === "asc") {
+                    const descAll = yield* store.list({ limit: 7, order: "desc" });
+                    expect(seen).toEqual(descAll.items.map((item) => item.id).toReversed());
                 }
-                cursor = page.cursor;
-            } while (cursor !== undefined);
-            expect(seen.size).toBe(7);
+            }
+        })));
+        it.effect("list orders by enqueuedAt ascending on request, cursor included", () => withStore((store) => Effect.gen(function* () {
+            const ids = [];
+            for (let i = 0; i < 3; i++) {
+                const { id } = yield* store.enqueue(baseRequest({ payload: { n: i } }));
+                ids.push(id);
+                yield* TestClock.adjust(1_000);
+            }
+            const first = yield* store.list({ orderBy: "enqueuedAt", order: "asc", limit: 2 });
+            expect(first.items.map((job) => job.id)).toEqual([ids[0], ids[1]]);
+            assert(first.cursor !== undefined);
+            const second = yield* store.list({
+                orderBy: "enqueuedAt",
+                order: "asc",
+                limit: 2,
+                cursor: first.cursor
+            });
+            expect(second.items.map((job) => job.id)).toEqual([ids[2]]);
+            expect(second.cursor).toBeUndefined();
+        })));
+        it.effect("list orders delayed jobs by runAt within a queue", () => withStore((store) => Effect.gen(function* () {
+            const late = yield* store.enqueue(baseRequest({ payload: { n: 1 }, delayMs: 30_000 }));
+            const soon = yield* store.enqueue(baseRequest({ payload: { n: 2 }, delayMs: 5_000 }));
+            const middle = yield* store.enqueue(baseRequest({ payload: { n: 3 }, delayMs: 10_000 }));
+            // An immediate job in the same queue must not appear.
+            yield* store.enqueue(baseRequest({ payload: { n: 4 } }));
+            const upcoming = yield* store.list({
+                queue: QueueName("default"),
+                states: ["delayed"],
+                orderBy: "runAt",
+                order: "asc",
+                limit: 2
+            });
+            expect(upcoming.items.map((job) => job.id)).toEqual([soon.id, middle.id]);
+            assert(upcoming.cursor !== undefined);
+            const rest = yield* store.list({
+                queue: QueueName("default"),
+                states: ["delayed"],
+                orderBy: "runAt",
+                order: "asc",
+                limit: 2,
+                cursor: upcoming.cursor
+            });
+            expect(rest.items.map((job) => job.id)).toEqual([late.id]);
+            expect(rest.cursor).toBeUndefined();
+        })));
+        it.effect("list orders terminal jobs by finishedAt, with and without a name", () => withStore((store) => Effect.gen(function* () {
+            // Enqueue in one order, finish in the REVERSE order, so finishedAt
+            // ordering and enqueuedAt ordering disagree — a driver that quietly
+            // ignores orderBy fails here instead of passing by coincidence.
+            const enqueueAs = (name, queue) => {
+                const request = queue === undefined
+                    ? baseRequest({ name })
+                    : baseRequest({ name, queue: QueueName(queue) });
+                return Effect.map(store.enqueue(request), (result) => result.id);
+            };
+            const first = yield* enqueueAs("TestJob");
+            const second = yield* enqueueAs("OtherJob");
+            const third = yield* enqueueAs("TestJob");
+            const elsewhere = yield* enqueueAs("TestJob", "other");
+            const claims = new Map();
+            for (const token of ["t-1", "t-2", "t-3"]) {
+                const claim = yield* store.claim(claimOptions({
+                    names: ["TestJob", "OtherJob"],
+                    token
+                }));
+                assert(claim._tag === "Claimed");
+                claims.set(claim.job.id, token);
+            }
+            const otherClaim = yield* store.claim(claimOptions({
+                queue: QueueName("other"),
+                token: "t-4"
+            }));
+            assert(otherClaim._tag === "Claimed");
+            claims.set(elsewhere, "t-4");
+            for (const id of [elsewhere, third, second, first]) {
+                const token = claims.get(id);
+                assert(token !== undefined);
+                yield* store.ack(id, token, {
+                    _tag: id === second ? "Fail" : "Complete",
+                    exit: undefined
+                });
+                yield* TestClock.adjust(1_000);
+            }
+            // Across terminal states, newest FINISHED first: the reverse of
+            // enqueue order.
+            const recent = yield* store.list({
+                states: ["completed", "failed"],
+                orderBy: "finishedAt",
+                order: "desc"
+            });
+            expect(recent.items.map((job) => job.id)).toEqual([first, second, third, elsewhere]);
+            // Scoped to one name and state.
+            const byName = yield* store.list({
+                name: "TestJob",
+                states: ["completed"],
+                orderBy: "finishedAt",
+                order: "desc"
+            });
+            expect(byName.items.map((job) => job.id)).toEqual([first, third, elsewhere]);
+            // The queue filter applies on top of the finishedAt route.
+            const byQueue = yield* store.list({
+                queue: QueueName("other"),
+                states: ["completed"],
+                orderBy: "finishedAt",
+                order: "desc"
+            });
+            expect(byQueue.items.map((job) => job.id)).toEqual([elsewhere]);
         })));
         it.effect("keep count ties on finishedAt keep the most recently acked records", () => withStore((store) => Effect.gen(function* () {
             // Two jobs acked at the SAME TestClock instant: the tie must break
@@ -429,6 +552,7 @@ export const jobStoreConformance = (name, storeLayer) => {
                 waiting: 1,
                 delayed: 1,
                 active: 1,
+                "waiting-children": 0,
                 completed: 0,
                 failed: 0,
                 cancelled: 0
@@ -792,7 +916,14 @@ export const jobStoreConformance = (name, storeLayer) => {
                 backoff: { _tag: "fixed", delayMs: 2_000 },
                 keep: { completed: { count: 2, ageMs: undefined } },
                 timeoutMs: 9_000,
-                trace: { traceId: "trace-1", spanId: "span-1", sampled: true, delayed: false }
+                trace: { traceId: "trace-1", spanId: "span-1", sampled: true, delayed: false },
+                parent: {
+                    flowName: "rich-flow",
+                    flowId: JobId("rich-parent"),
+                    childKey: "rich-child",
+                    parentStoreKey: "effect-mq/JobStore",
+                    depth: 1
+                }
             });
             yield* store.enqueue(richRequest("rich-single"));
             expect(yield* store.enqueueMany([richRequest("rich-batch")]))
@@ -819,6 +950,8 @@ export const jobStoreConformance = (name, storeLayer) => {
                 timeoutMs: job.timeoutMs,
                 cancelRequested: job.cancelRequested,
                 trace: job.trace,
+                parent: job.parent,
+                flow: job.flow,
                 runAt: job.runAt,
                 enqueuedAt: job.enqueuedAt
             });
@@ -837,11 +970,27 @@ export const jobStoreConformance = (name, storeLayer) => {
                 delayed: false
             });
             expect(expected.payload).toEqual({ big: 1234567890123456, nested: { arr: [1, 2, 3] } });
+            expect(expected.parent).toEqual({
+                flowName: "rich-flow",
+                flowId: "rich-parent",
+                childKey: "rich-child",
+                parentStoreKey: "effect-mq/JobStore",
+                depth: 1
+            });
+            expect(expected.flow).toBeUndefined();
             for (const id of [JobId("rich-batch"), JobId("rich-tick")]) {
                 const job = yield* store.getJob(id);
                 assert(Option.isSome(job));
                 expect(project(job.value)).toEqual(expected);
             }
+            // `list` must return the same complete records as `getJob` —
+            // drivers with hand-written SELECT lists can silently drop fields
+            // there while every getJob-path test stays green.
+            const listed = yield* store.list({ name: "TestJob" });
+            expect(listed.items).toHaveLength(3);
+            for (const job of listed.items) {
+                expect(project(job)).toEqual(expected);
+            }
         })));
         it.effect("enqueueMany wakes parked takers", () => withStore((store) => Effect.gen(function* () {
             const empty = yield* store.claim(claimOptions());
@@ -1008,6 +1157,7 @@ export const jobStoreConformance = (name, storeLayer) => {
                 waiting: 1,
                 delayed: 0,
                 active: 0,
+                "waiting-children": 0,
                 completed: 0,
                 failed: 0,
                 cancelled: 1
@@ -1243,6 +1393,699 @@ export const jobStoreConformance = (name, storeLayer) => {
             assert(Option.isSome(job));
             expect(job.value.state).toBe("waiting");
         })));
+        // ----------------------------------------------------------------------
+        // Flows (parent-child). The parent store owns the flow: the FanOut ack,
+        // dependency rows, pending counter, and every settle decision are pinned
+        // here. `storeKey` strings are opaque to the store.
+        // ----------------------------------------------------------------------
+        const parentEnvelope = (flowId, key) => ({
+            flowName: "test-flow",
+            flowId,
+            childKey: key,
+            parentStoreKey: "main",
+            depth: 1
+        });
+        const childSpec = (flowId, key, overrides) => ({
+            childKey: key,
+            storeKey: "effect-mq/JobStore/children",
+            request: baseRequest({
+                id: JobId(`flow/main/${flowId}/${key}`),
+                name: "ChildJob",
+                parent: parentEnvelope(flowId, key),
+                ...overrides
+            })
+        });
+        const fanOutParent = (store, options) => Effect.gen(function* () {
+            const { id } = yield* store.enqueue(baseRequest({ payload: { parent: true } }));
+            const claim = yield* store.claim(claimOptions({ token: "t-parent" }));
+            assert(claim._tag === "Claimed");
+            expect(claim.job.id).toBe(id);
+            const keys = options?.children ?? ["a", "b"];
+            yield* store.ack(id, "t-parent", {
+                _tag: "FanOut",
+                failFast: options?.failFast ?? false,
+                children: keys.map((key) => childSpec(id, key))
+            });
+            return id;
+        });
+        const report = (flowId, key, outcome, overrides) => ({
+            flowId,
+            childKey: key,
+            outcome,
+            exit: { ok: outcome === "completed" },
+            failedReason: undefined,
+            ...overrides
+        });
+        // Batch-of-one sugar for the single-report pins below; the batch
+        // semantics get their own section.
+        const recordOne = (store, value) => Effect.map(store.recordChildResults([value]), (results) => results[0] ?? { applied: false, parentSettled: false });
+        const flowCounts = (overrides) => ({
+            failFast: false,
+            pending: 0,
+            completed: 0,
+            failed: 0,
+            cancelled: 0,
+            ...overrides
+        });
+        it.effect("FanOut parks the parent with its manifest, rows, and ledger entry", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting-children");
+            expect(parent.value.flow).toEqual(flowCounts({ pending: 2 }));
+            // A fan-out is a phase transition, not a completed run.
+            expect(parent.value.attemptsMade).toBe(0);
+            const attempts = yield* store.getAttempts(flowId);
+            expect(attempts.map((attempt) => attempt.outcome)).toEqual(["fanned-out"]);
+            const rows = yield* store.listChildResults(flowId);
+            expect(rows.cursor).toBeUndefined();
+            expect(rows.items.map((row) => ({
+                childKey: row.childKey,
+                name: row.name,
+                storeKey: row.storeKey,
+                childJobId: row.childJobId,
+                status: row.status,
+                cascaded: row.cascaded
+            }))).toEqual([
+                {
+                    childKey: "a",
+                    name: "ChildJob",
+                    storeKey: "effect-mq/JobStore/children",
+                    childJobId: `flow/main/${flowId}/a`,
+                    status: "pending",
+                    cascaded: false
+                },
+                {
+                    childKey: "b",
+                    name: "ChildJob",
+                    storeKey: "effect-mq/JobStore/children",
+                    childJobId: `flow/main/${flowId}/b`,
+                    status: "pending",
+                    cascaded: false
+                }
+            ]);
+            // Parked parents are never claimable and show in counts.
+            const claim = yield* store.claim(claimOptions({ token: "t-again" }));
+            expect(claim._tag).toBe("Empty");
+            expect((yield* store.counts())["waiting-children"]).toBe(1);
+        })));
+        it.effect("FanOut is lock-token-guarded and validates child ids", () => withStore((store) => Effect.gen(function* () {
+            const { id } = yield* store.enqueue(baseRequest());
+            const claim = yield* store.claim(claimOptions({ token: "t-owner" }));
+            assert(claim._tag === "Claimed");
+            const stale = yield* Effect.exit(store.ack(id, "t-wrong", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(id, "a")]
+            }));
+            assert(Exit.isFailure(stale));
+            // A spec without an explicit id fails loudly and leaves the job
+            // active (the ack can be retried with a fixed spec).
+            const bad = yield* Effect.exit(store.ack(id, "t-owner", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [{ ...childSpec(id, "a"), request: baseRequest({ id: undefined }) }]
+            }));
+            assert(Exit.isFailure(bad));
+            const job = yield* store.getJob(id);
+            assert(Option.isSome(job));
+            expect(job.value.state).toBe("active");
+            yield* store.ack(id, "t-owner", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(id, "a")]
+            });
+        })));
+        it.effect("an empty FanOut settles straight to runnable collect", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: [] });
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting");
+            expect(parent.value.flow).toEqual(flowCounts());
+            const claim = yield* store.claim(claimOptions({ token: "t-resume" }));
+            assert(claim._tag === "Claimed");
+            expect(claim.job.id).toBe(flowId);
+            expect(claim.job.flow).toEqual(flowCounts());
+        })));
+        it.effect("recordChildResults applies once, decrements, and settles on the last report", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            const first = yield* recordOne(store, report(flowId, "a", "completed"));
+            expect(first).toEqual({ applied: true, parentSettled: false });
+            const midway = yield* store.getJob(flowId);
+            assert(Option.isSome(midway));
+            expect(midway.value.state).toBe("waiting-children");
+            expect(midway.value.flow?.pending).toBe(1);
+            // Duplicates and unknowns drop on the dependency row.
+            expect(yield* recordOne(store, report(flowId, "a", "failed")))
+                .toEqual({ applied: false, parentSettled: false });
+            expect(yield* recordOne(store, report(flowId, "ghost", "completed")))
+                .toEqual({ applied: false, parentSettled: false });
+            expect(yield* recordOne(store, report(JobId("no-such-flow"), "a", "completed")))
+                .toEqual({ applied: false, parentSettled: false });
+            const last = yield* recordOne(store, report(flowId, "b", "failed", {
+                exit: { boom: true }
+            }));
+            expect(last).toEqual({ applied: true, parentSettled: true });
+            // Settled: runnable now, phase collect, results recorded exactly.
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting");
+            // The counters mirror the recorded outcomes exactly — via getJob,
+            // via the claimed record (what `collect` reads its counts from),
+            // and via list (what dashboards read). A driver whose claim/list
+            // projections drop the counter columns fails here, not in prod.
+            expect(parent.value.flow).toEqual(flowCounts({ completed: 1, failed: 1 }));
+            const claim = yield* store.claim(claimOptions({ token: "t-resume" }));
+            assert(claim._tag === "Claimed");
+            expect(claim.job.id).toBe(flowId);
+            expect(claim.job.flow).toEqual(flowCounts({ completed: 1, failed: 1 }));
+            const listed = yield* store.list({ name: "TestJob" });
+            expect(listed.items.find((job) => job.id === flowId)?.flow)
+                .toEqual(flowCounts({ completed: 1, failed: 1 }));
+            const rows = yield* store.listChildResults(flowId);
+            const byKey = new Map(rows.items.map((row) => [row.childKey, row]));
+            expect(byKey.get("a")?.status).toBe("completed");
+            expect(byKey.get("a")?.exit).toEqual({ ok: true });
+            // A recorded outcome came FROM the child's store: nothing to cascade.
+            expect(byKey.get("a")?.cascaded).toBe(true);
+            expect(byKey.get("b")?.status).toBe("failed");
+            expect(byKey.get("b")?.exit).toEqual({ boom: true });
+        })));
+        it.effect("recordChildResults wakes a taker parked on the parent's queue", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["only"] });
+            const empty = yield* store.claim(claimOptions({ token: "t-idle" }));
+            assert(empty._tag === "Empty");
+            const waiter = yield* Effect.forkChild(store.awaitWake([QueueName("default")], empty.wakeToken));
+            yield* TestClock.adjust(1);
+            yield* recordOne(store, report(flowId, "only", "completed"));
+            yield* TestClock.adjust(1);
+            expect(yield* Fiber.join(waiter)).toBeUndefined();
+        })));
+        it.effect("concurrent last reports settle the parent exactly once", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            const results = yield* Effect.all([
+                recordOne(store, report(flowId, "a", "completed")),
+                recordOne(store, report(flowId, "b", "completed")),
+                recordOne(store, report(flowId, "a", "completed")),
+                recordOne(store, report(flowId, "b", "completed"))
+            ], { concurrency: 4 });
+            expect(results.filter((result) => result.applied).length).toBe(2);
+            expect(results.filter((result) => result.parentSettled).length).toBe(1);
+        })));
+        it.effect("fail-fast settles the parent terminally and marks remaining rows", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b", "c"], failFast: true });
+            yield* recordOne(store, report(flowId, "a", "completed"));
+            const settle = yield* recordOne(store, report(flowId, "b", "failed"));
+            expect(settle).toEqual({ applied: true, parentSettled: true });
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("failed");
+            expect(parent.value.failedReason).toContain("b");
+            expect(parent.value.exit).toBeUndefined();
+            const rows = yield* store.listChildResults(flowId);
+            const remaining = rows.items.find((row) => row.childKey === "c");
+            expect(remaining?.status).toBe("cancelled");
+            // Marked by the settle — the sweeper still owes a real cancel.
+            expect(remaining?.cascaded).toBe(false);
+            // Settle-time marking lands in the counters too.
+            expect(parent.value.flow).toEqual(flowCounts({ failFast: true, completed: 1, failed: 1, cancelled: 1 }));
+            // A late completion finds its row terminal and drops.
+            expect(yield* recordOne(store, report(flowId, "c", "completed")))
+                .toEqual({ applied: false, parentSettled: false });
+        })));
+        it.effect("cancelling a waiting-children parent settles and marks its pending rows", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            yield* recordOne(store, report(flowId, "a", "completed"));
+            yield* store.cancel(flowId);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("cancelled");
+            // The settle marking moves the counters too.
+            expect(parent.value.flow).toEqual(flowCounts({ completed: 1, cancelled: 1 }));
+            const rows = yield* store.listChildResults(flowId);
+            const byKey = new Map(rows.items.map((row) => [row.childKey, row]));
+            expect(byKey.get("a")?.status).toBe("completed");
+            expect(byKey.get("b")?.status).toBe("cancelled");
+            expect(byKey.get("b")?.cascaded).toBe(false);
+            expect(yield* recordOne(store, report(flowId, "b", "completed")))
+                .toEqual({ applied: false, parentSettled: false });
+        })));
+        it.effect("a cancel that races the fan-out wins and marks the rows", () => withStore((store) => Effect.gen(function* () {
+            const { id } = yield* store.enqueue(baseRequest());
+            const claim = yield* store.claim(claimOptions({ token: "t-parent" }));
+            assert(claim._tag === "Claimed");
+            // Cancel the ACTIVE parent (sets cancelRequested), then the worker
+            // acks its fan-out: cancellation wins over parking.
+            yield* store.cancel(id);
+            yield* store.ack(id, "t-parent", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(id, "a"), childSpec(id, "b")]
+            });
+            const parent = yield* store.getJob(id);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("cancelled");
+            expect(parent.value.flow).toEqual(flowCounts({ cancelled: 2 }));
+            // The manifest landed and every row was marked for cascade, so
+            // the sweeper delivers (mostly no-op) cancels to the child store.
+            const rows = yield* store.listChildResults(id);
+            expect(rows.items.map((row) => row.status)).toEqual(["cancelled", "cancelled"]);
+            expect(rows.items.every((row) => !row.cascaded)).toBe(true);
+            const work = yield* store.flowSweepWork({ pendingAgeMs: 0 });
+            expect(work.cascade[0]?.children.map((child) => child.childKey)).toEqual(["a", "b"]);
+        })));
+        it.effect("promote and retry reject a waiting-children parent", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            const promoted = yield* Effect.exit(store.promote(flowId));
+            assert(Exit.isFailure(promoted));
+            const retried = yield* Effect.exit(store.retry(flowId));
+            assert(Exit.isFailure(retried));
+        })));
+        it.effect("retrying a fail-fast-failed parent re-enters collect with its manifest", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b"], failFast: true });
+            yield* recordOne(store, report(flowId, "a", "failed"));
+            yield* store.retry(flowId);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting");
+            // The manifest survives: a re-claimed parent dispatches collect,
+            // never a second fan-out.
+            expect(parent.value.flow).toBeDefined();
+            expect((yield* store.listChildResults(flowId)).items.length).toBe(2);
+        })));
+        it.effect("a second FanOut converges on the persisted manifest", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a"] });
+            yield* recordOne(store, report(flowId, "a", "completed"));
+            // Parent settled to waiting; claim and (bug-path) fan out again
+            // with DIFFERENT children.
+            const claim = yield* store.claim(claimOptions({ token: "t-double" }));
+            assert(claim._tag === "Claimed");
+            yield* store.ack(flowId, "t-double", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(flowId, "x"), childSpec(flowId, "y")]
+            });
+            // The original manifest is untouched; state follows its pending
+            // count (0 → runnable collect again).
+            const rows = yield* store.listChildResults(flowId);
+            expect(rows.items.map((row) => row.childKey)).toEqual(["a"]);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting");
+        })));
+        it.effect("flowSweepWork scopes reconcile by parent state and pending age", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            // Fresh rows are the push path's business.
+            const fresh = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(fresh.reconcile).toEqual([]);
+            expect(fresh.cascade).toEqual([]);
+            yield* TestClock.adjust(30_000);
+            const due = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(due.reconcile.length).toBe(1);
+            expect(due.reconcile[0]?.flowId).toBe(flowId);
+            expect(due.reconcile[0]?.children.map((child) => child.childKey)).toEqual(["a", "b"]);
+            // The stored spec is the complete original request.
+            expect(due.reconcile[0]?.children[0]?.request).toEqual(childSpec(flowId, "a").request);
+            // Returned rows are re-armed: they leave the page for another full
+            // age, so a sweep page rotates instead of pinning its head.
+            const rearmed = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(rearmed.reconcile).toEqual([]);
+            // A recorded row leaves the reconcile set for good; a settled
+            // parent leaves it entirely.
+            yield* recordOne(store, report(flowId, "a", "completed"));
+            yield* TestClock.adjust(30_000);
+            const partial = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(partial.reconcile[0]?.children.map((child) => child.childKey)).toEqual(["b"]);
+            yield* recordOne(store, report(flowId, "b", "completed"));
+            yield* TestClock.adjust(30_000);
+            const settled = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(settled.reconcile).toEqual([]);
+        })));
+        it.effect("a fail-fast report that is also the last pending row settles as failed", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b"], failFast: true });
+            yield* recordOne(store, report(flowId, "a", "completed"));
+            // This report triggers BOTH settle rules: pending hits zero AND it
+            // is the first failure under fail-fast. Fail-fast wins: terminal
+            // `failed`, never a resume into collect.
+            const last = yield* recordOne(store, report(flowId, "b", "failed"));
+            expect(last).toEqual({ applied: true, parentSettled: true });
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("failed");
+            expect(parent.value.failedReason).toContain("b");
+        })));
+        it.effect("an empty FanOut wakes takers parked on the parent's queue", () => withStore((store) => Effect.gen(function* () {
+            const { id } = yield* store.enqueue(baseRequest());
+            const claim = yield* store.claim(claimOptions({ token: "t-parent" }));
+            assert(claim._tag === "Claimed");
+            const empty = yield* store.claim(claimOptions({ token: "t-idle" }));
+            assert(empty._tag === "Empty");
+            const waiter = yield* Effect.forkChild(store.awaitWake([QueueName("default")], empty.wakeToken));
+            yield* TestClock.adjust(1);
+            yield* store.ack(id, "t-parent", { _tag: "FanOut", failFast: false, children: [] });
+            yield* TestClock.adjust(1);
+            expect(yield* Fiber.join(waiter)).toBeUndefined();
+        })));
+        it.effect("automatic retention spares a settled parent that still owes cascades", () => withStore((store) => Effect.gen(function* () {
+            // A fail-fast settle marks rows for cascade in the same op that
+            // makes the parent prunable — retention must not race the sweeper
+            // out of its only record that cancels are still owed.
+            const keep = { failed: { count: 1, ageMs: undefined } };
+            const { id: flowId } = yield* store.enqueue(baseRequest({ keep }));
+            const claim = yield* store.claim(claimOptions({ token: "t-parent" }));
+            assert(claim._tag === "Claimed");
+            yield* store.ack(flowId, "t-parent", {
+                _tag: "FanOut",
+                failFast: true,
+                children: [childSpec(flowId, "a"), childSpec(flowId, "b")]
+            });
+            yield* recordOne(store, report(flowId, "a", "failed"));
+            // A newer failed peer would evict the flow parent under count: 1 —
+            // but its "b" row is cancelled and not yet cascaded.
+            const { id: peer1 } = yield* store.enqueue(baseRequest({ keep }));
+            const claim1 = yield* store.claim(claimOptions({ token: "t-p1" }));
+            assert(claim1._tag === "Claimed");
+            yield* store.ack(peer1, "t-p1", { _tag: "Fail", exit: undefined });
+            const spared = yield* store.getJob(flowId);
+            assert(Option.isSome(spared));
+            expect(spared.value.state).toBe("failed");
+            expect((yield* store.listChildResults(flowId)).items.length).toBe(2);
+            // Once the cascade is delivered, retention applies normally.
+            yield* store.markChildrenCascaded(flowId, ["b"]);
+            const { id: peer2 } = yield* store.enqueue(baseRequest({ keep }));
+            const claim2 = yield* store.claim(claimOptions({ token: "t-p2" }));
+            assert(claim2._tag === "Claimed");
+            yield* store.ack(peer2, "t-p2", { _tag: "Fail", exit: undefined });
+            expect(Option.isNone(yield* store.getJob(flowId))).toBe(true);
+            expect((yield* store.listChildResults(flowId)).items).toEqual([]);
+        })));
+        it.effect("flowSweepWork yields cascade work until rows are marked cascaded", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b"], failFast: true });
+            yield* recordOne(store, report(flowId, "a", "failed"));
+            const work = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            // Settled flow: nothing to reconcile, but "b" owes a cascade.
+            expect(work.reconcile).toEqual([]);
+            expect(work.cascade.length).toBe(1);
+            expect(work.cascade[0]?.children).toEqual([{
+                    childKey: "b",
+                    storeKey: "effect-mq/JobStore/children",
+                    childJobId: `flow/main/${flowId}/b`
+                }]);
+            yield* store.markChildrenCascaded(flowId, ["b"]);
+            const after = yield* store.flowSweepWork({ pendingAgeMs: 30_000 });
+            expect(after.cascade).toEqual([]);
+            // Idempotent (unknown keys included).
+            yield* store.markChildrenCascaded(flowId, ["b", "ghost"]);
+        })));
+        it.effect("listChildResults paginates in child-key order", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["c", "a", "b"] });
+            const first = yield* store.listChildResults(flowId, { limit: 2 });
+            expect(first.items.map((row) => row.childKey)).toEqual(["a", "b"]);
+            expect(first.cursor).toBeDefined();
+            const second = yield* store.listChildResults(flowId, {
+                cursor: first.cursor,
+                limit: 2
+            });
+            expect(second.items.map((row) => row.childKey)).toEqual(["c"]);
+            expect(second.cursor).toBeUndefined();
+        })));
+        it.effect("remove refuses a waiting-children parent and deletes rows with a settled one", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a"] });
+            expect(yield* store.remove(flowId)).toBe(false);
+            yield* recordOne(store, report(flowId, "a", "failed", { exit: undefined }));
+            // continue-policy: the parent settled to waiting; cancel it so it
+            // is removable, then remove it — the dependency rows go with it.
+            yield* store.cancel(flowId);
+            expect(yield* store.remove(flowId)).toBe(true);
+            expect((yield* store.listChildResults(flowId)).items).toEqual([]);
+        })));
+        it.effect("store-side child failures carry failedReason on the row", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a"] });
+            yield* recordOne(store, report(flowId, "a", "failed", {
+                exit: undefined,
+                failedReason: "job stalled more than allowable limit"
+            }));
+            const rows = yield* store.listChildResults(flowId);
+            expect(rows.items[0]?.exit).toBeUndefined();
+            expect(rows.items[0]?.failedReason).toBe("job stalled more than allowable limit");
+        })));
+        // ----------------------------------------------------------------------
+        // Batched reports + the child-side outbox. The outbox is how a CHILD
+        // store reports terminal transitions to a parent living in another
+        // store: append on the transition, peek/delete from the relay.
+        // ----------------------------------------------------------------------
+        it.effect("recordChildResults applies a batch positionally and keeps counters exact", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b", "c"] });
+            const results = yield* store.recordChildResults([
+                report(flowId, "a", "completed"),
+                report(flowId, "a", "completed"), // duplicate inside the batch
+                report(flowId, "ghost", "completed"),
+                report(flowId, "b", "failed")
+            ]);
+            expect(results).toEqual([
+                { applied: true, parentSettled: false },
+                { applied: false, parentSettled: false },
+                { applied: false, parentSettled: false },
+                { applied: true, parentSettled: false }
+            ]);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting-children");
+            expect(parent.value.flow).toEqual(flowCounts({ pending: 1, completed: 1, failed: 1 }));
+        })));
+        it.effect("a batch that empties pending settles once, on its last applied report", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            const results = yield* store.recordChildResults([
+                report(flowId, "a", "completed"),
+                report(flowId, "b", "completed")
+            ]);
+            expect(results).toEqual([
+                { applied: true, parentSettled: false },
+                { applied: true, parentSettled: true }
+            ]);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("waiting");
+        })));
+        it.effect("fail-fast wins inside a batch, after every batch-mate applied", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store, { children: ["a", "b", "c"], failFast: true });
+            const results = yield* store.recordChildResults([
+                report(flowId, "b", "failed"),
+                report(flowId, "c", "completed")
+            ]);
+            // Row updates apply BEFORE the settle decision: "c" keeps its real
+            // completed outcome even though "b" settles the flow.
+            expect(results).toEqual([
+                { applied: true, parentSettled: true },
+                { applied: true, parentSettled: false }
+            ]);
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("failed");
+            expect(parent.value.failedReason).toContain("b");
+            expect(parent.value.flow).toEqual(flowCounts({ failFast: true, completed: 1, failed: 1, cancelled: 1 }));
+            const rows = yield* store.listChildResults(flowId);
+            const byKey = new Map(rows.items.map((row) => [row.childKey, row.status]));
+            expect(byKey.get("c")).toBe("completed");
+            expect(byKey.get("a")).toBe("cancelled");
+        })));
+        it.effect("a batch may span flows and settles each independently", () => withStore((store) => Effect.gen(function* () {
+            const first = yield* fanOutParent(store, { children: ["a"] });
+            const second = yield* fanOutParent(store, { children: ["b"] });
+            const results = yield* store.recordChildResults([
+                report(first, "a", "completed"),
+                report(second, "b", "completed")
+            ]);
+            expect(results).toEqual([
+                { applied: true, parentSettled: true },
+                { applied: true, parentSettled: true }
+            ]);
+        })));
+        it.effect("a cancelled child report moves the cancelled counter", () => withStore((store) => Effect.gen(function* () {
+            const flowId = yield* fanOutParent(store);
+            yield* recordOne(store, report(flowId, "a", "cancelled", { exit: undefined }));
+            const parent = yield* store.getJob(flowId);
+            assert(Option.isSome(parent));
+            expect(parent.value.flow).toEqual(flowCounts({ pending: 1, cancelled: 1 }));
+        })));
+        it.effect("peekOutbox pages past prior entries with `after`, even deleted ones", () => withStore((store) => Effect.gen(function* () {
+            const enqueueChild = (key) => Effect.gen(function* () {
+                const { id } = yield* store.enqueue(baseRequest({
+                    parent: parentEnvelope(JobId("remote-flow-3"), key)
+                }));
+                const claim = yield* store.claim(claimOptions({ token: `t-${key}` }));
+                assert(claim._tag === "Claimed");
+                yield* store.ack(id, `t-${key}`, { _tag: "Complete", exit: { key } });
+            });
+            yield* enqueueChild("one");
+            yield* enqueueChild("two");
+            yield* enqueueChild("three");
+            const first = yield* store.peekOutbox({ limit: 2 });
+            expect(first.map((entry) => entry.report.childKey)).toEqual(["one", "two"]);
+            const cursor = first[first.length - 1]?.id;
+            assert(cursor !== undefined);
+            const rest = yield* store.peekOutbox({ limit: 2, after: cursor });
+            expect(rest.map((entry) => entry.report.childKey)).toEqual(["three"]);
+            // The cursor keeps working when the entry it names is gone.
+            yield* store.deleteOutbox([cursor]);
+            const restAgain = yield* store.peekOutbox({ limit: 2, after: cursor });
+            expect(restAgain.map((entry) => entry.report.childKey)).toEqual(["three"]);
+        })));
+        it.effect("cancels honoured by retry acks, the stall sweep, and on a parked parent land in the outbox", () => withStore((store) => Effect.gen(function* () {
+            const envelope = (key) => parentEnvelope(JobId("remote-flow-4"), key);
+            // A cancel honoured when a RETRY ack finds the flag set.
+            const retried = yield* store.enqueue(baseRequest({ parent: envelope("retry-cancel") }));
+            const claimA = yield* store.claim(claimOptions({ token: "t-a" }));
+            assert(claimA._tag === "Claimed");
+            yield* store.cancel(retried.id);
+            yield* store.ack(retried.id, "t-a", { _tag: "Retry", delayMs: 0, exit: undefined });
+            // A cancel honoured when the stall sweep recovers a dead worker.
+            const stalled = yield* store.enqueue(baseRequest({ parent: envelope("stall-cancel") }));
+            const claimB = yield* store.claim(claimOptions({ token: "t-b", lockDurationMs: 1_000 }));
+            assert(claimB._tag === "Claimed");
+            yield* store.cancel(stalled.id);
+            yield* TestClock.adjust(2_000);
+            yield* store.recoverStalled({ maxStalledCount: 5 });
+            // A direct cancel of a PARKED nested parent (waiting-children).
+            const parked = yield* store.enqueue(baseRequest({ parent: envelope("parked-cancel") }));
+            const claimC = yield* store.claim(claimOptions({ token: "t-c" }));
+            assert(claimC._tag === "Claimed");
+            yield* store.ack(parked.id, "t-c", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(parked.id, "a")]
+            });
+            yield* store.cancel(parked.id);
+            const entries = yield* store.peekOutbox({ limit: 10 });
+            expect(entries.map((entry) => [entry.report.childKey, entry.report.outcome])).toEqual([
+                ["retry-cancel", "cancelled"],
+                ["stall-cancel", "cancelled"],
+                ["parked-cancel", "cancelled"]
+            ]);
+        })));
+        it.effect("terminal transitions of envelope-carrying jobs land in the outbox", () => withStore((store) => Effect.gen(function* () {
+            const envelope = (key) => parentEnvelope(JobId("remote-flow-1"), key);
+            // A plain job's terminal ack appends nothing.
+            const plain = yield* store.enqueue(baseRequest());
+            const plainClaim = yield* store.claim(claimOptions({ token: "t-plain" }));
+            assert(plainClaim._tag === "Claimed");
+            yield* store.ack(plain.id, "t-plain", { _tag: "Complete", exit: { ok: true } });
+            expect(yield* store.peekOutbox({ limit: 10 })).toEqual([]);
+            // Ack Complete → outbox entry with the exit.
+            const acked = yield* store.enqueue(baseRequest({ parent: envelope("acked") }));
+            const claim = yield* store.claim(claimOptions({ token: "t-child" }));
+            assert(claim._tag === "Claimed");
+            expect(claim.job.id).toBe(acked.id);
+            yield* store.ack(acked.id, "t-child", { _tag: "Complete", exit: { sent: 1 } });
+            // Direct cancel of a delayed child → outbox entry.
+            const cancelled = yield* store.enqueue(baseRequest({ parent: envelope("cancelled"), delayMs: 60_000 }));
+            yield* store.cancel(cancelled.id);
+            // Stall exhaustion → outbox entry carrying the failedReason.
+            yield* store.enqueue(baseRequest({ parent: envelope("stalled") }));
+            const stalledClaim = yield* store.claim(claimOptions({ token: "t-stall", lockDurationMs: 1_000 }));
+            assert(stalledClaim._tag === "Claimed");
+            yield* TestClock.adjust(2_000);
+            const recovered = yield* store.recoverStalled({ maxStalledCount: 0 });
+            expect(recovered).toEqual([{ id: stalledClaim.job.id, failed: true }]);
+            // Oldest first, `limit` respected, full entry shape.
+            const firstPage = yield* store.peekOutbox({ limit: 2 });
+            expect(firstPage.map((entry) => entry.report.childKey)).toEqual(["acked", "cancelled"]);
+            const head = firstPage[0];
+            assert(head !== undefined);
+            expect(head.flowName).toBe("test-flow");
+            expect(head.parentStoreKey).toBe("main");
+            expect(head.report.flowId).toBe("remote-flow-1");
+            expect(head.report.outcome).toBe("completed");
+            expect(head.report.exit).toEqual({ sent: 1 });
+            const all = yield* store.peekOutbox({ limit: 10 });
+            expect(all.map((entry) => entry.report.outcome)).toEqual([
+                "completed",
+                "cancelled",
+                "failed"
+            ]);
+            expect(all[2]?.report.exit).toBeUndefined();
+            expect(all[2]?.report.failedReason).toBe("job stalled more than allowable limit");
+            // Peek does not consume; delete does, idempotently.
+            yield* store.deleteOutbox([head.id, "ghost-id"]);
+            const rest = yield* store.peekOutbox({ limit: 10 });
+            expect(rest.map((entry) => entry.report.childKey)).toEqual(["cancelled", "stalled"]);
+            yield* store.deleteOutbox([head.id]);
+            expect((yield* store.peekOutbox({ limit: 10 })).length).toBe(2);
+        })));
+        it.effect("cancels honoured off the ack path still land in the outbox", () => withStore((store) => Effect.gen(function* () {
+            // A cancel that arrives while the child runs, honoured when the
+            // worker RELEASES the job (shutdown) instead of acking it.
+            const { id } = yield* store.enqueue(baseRequest({
+                parent: parentEnvelope(JobId("remote-flow-2"), "released")
+            }));
+            const claim = yield* store.claim(claimOptions({ token: "t-run" }));
+            assert(claim._tag === "Claimed");
+            yield* store.cancel(id);
+            yield* store.release(id, "t-run");
+            const job = yield* store.getJob(id);
+            assert(Option.isSome(job));
+            expect(job.value.state).toBe("cancelled");
+            const entries = yield* store.peekOutbox({ limit: 10 });
+            expect(entries.map((entry) => entry.report.outcome)).toEqual(["cancelled"]);
+            expect(entries[0]?.report.childKey).toBe("released");
+        })));
+        it.effect("a cancel that races a nested parent's fan-out reports upward through the outbox", () => withStore((store) => Effect.gen(function* () {
+            // The parent being fanned out is itself a flow child; the raced
+            // cancel settles it terminally inside the FanOut ack.
+            const inner = yield* store.enqueue(baseRequest({
+                parent: {
+                    flowName: "outer-flow",
+                    flowId: JobId("outer-2"),
+                    childKey: "inner-raced",
+                    parentStoreKey: "outer-store",
+                    depth: 1
+                }
+            }));
+            const claim = yield* store.claim(claimOptions({ token: "t-race" }));
+            assert(claim._tag === "Claimed");
+            yield* store.cancel(inner.id);
+            yield* store.ack(inner.id, "t-race", {
+                _tag: "FanOut",
+                failFast: false,
+                children: [childSpec(inner.id, "a")]
+            });
+            const parent = yield* store.getJob(inner.id);
+            assert(Option.isSome(parent));
+            expect(parent.value.state).toBe("cancelled");
+            const entries = yield* store.peekOutbox({ limit: 10 });
+            expect(entries.map((entry) => entry.report.outcome)).toEqual(["cancelled"]);
+            expect(entries[0]?.report.childKey).toBe("inner-raced");
+            expect(entries[0]?.flowName).toBe("outer-flow");
+        })));
+        it.effect("a fail-fast settle of a nested parent reports upward through the outbox", () => withStore((store) => Effect.gen(function* () {
+            // The inner parent is itself a flow child; its terminal transition
+            // happens store-side (the settle), with no worker ack to hook.
+            const inner = yield* store.enqueue(baseRequest({
+                parent: {
+                    flowName: "outer-flow",
+                    flowId: JobId("outer-1"),
+                    childKey: "inner",
+                    parentStoreKey: "outer-store",
+                    depth: 1
+                }
+            }));
+            const claim = yield* store.claim(claimOptions({ token: "t-inner" }));
+            assert(claim._tag === "Claimed");
+            yield* store.ack(inner.id, "t-inner", {
+                _tag: "FanOut",
+                failFast: true,
+                children: [childSpec(inner.id, "a")]
+            });
+            // Parking is not terminal: nothing in the outbox yet.
+            expect(yield* store.peekOutbox({ limit: 10 })).toEqual([]);
+            yield* recordOne(store, report(inner.id, "a", "failed"));
+            const entries = yield* store.peekOutbox({ limit: 10 });
+            expect(entries.length).toBe(1);
+            expect(entries[0]?.flowName).toBe("outer-flow");
+            expect(entries[0]?.report.childKey).toBe("inner");
+            expect(entries[0]?.report.outcome).toBe("failed");
+            expect(entries[0]?.report.failedReason).toContain('"a" failed');
+        })));
     });
 };
 //# sourceMappingURL=conformance.js.map