effect-mq 0.4.2 → 0.6.0

package/dist/drizzle-postgres/DrizzleJobStore.js

@@ -20,9 +20,49 @@ import * as JobStore from "../JobStore.js";
 import { asc, eq, getTableColumns, sql } from "drizzle-orm";
 import * as PgDrizzle from "drizzle-orm/effect-postgres";
 import { getTableConfig } from "drizzle-orm/pg-core";
-import { Clock, Deferred, Duration, Effect, Layer, Option, Stream } from "effect";
+import { Cause, Clock, Deferred, Duration, Effect, Layer, Option, Predicate, Stream } from "effect";
 const { JobId } = JobStore;
 const storeError = (message) => (cause) => new JobStore.JobStoreError({ message, cause });
+// The exact spellings a bigserial ever produces: no leading zeros, no signs,
+// no whitespace — what outbox ids look like and nothing Postgres would
+// silently normalize into one.
+const CANONICAL_BIGSERIAL = /^[1-9]\d*$/;
+/**
+ * Whether an error surfaced by drizzle's Effect driver is a Postgres
+ * deadlock (40P01), i.e. safe to retry.
+ *
+ * The deadlock travels wrapped: drizzle's session fails with an
+ * `EffectDrizzleQueryError` whose `cause` field is `Cause.fail(SqlError)`
+ * (drizzle-orm `pg-core/effect/session.ts`), and `@effect/sql-pg` classifies
+ * pg code 40P01 into the `SqlError`'s `reason: DeadlockError` (PgClient.ts
+ * `classifyError`). Neither layer's `toString` renders the pg code, so this
+ * unwraps structurally instead of string-matching the rendered error.
+ *
+ * @internal
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- a retry-predicate classifier over whatever the driver threw IS the boundary parser
+export const isDeadlockError = (error) => {
+    // Unwrap drizzle's envelope: its `cause` is an Effect Cause holding the
+    // original failure. A bare SqlError (non-drizzle path) passes through.
+    const unwrapped = Predicate.hasProperty(error, "cause") && Cause.isCause(error.cause)
+        ? Option.getOrUndefined(Cause.findErrorOption(error.cause))
+        : error;
+    if (!Predicate.hasProperty(unwrapped, "_tag") || unwrapped._tag !== "SqlError" ||
+        !Predicate.hasProperty(unwrapped, "reason")) {
+        return false;
+    }
+    const reason = unwrapped.reason;
+    if (Predicate.hasProperty(reason, "_tag") && reason._tag === "DeadlockError") {
+        return true;
+    }
+    // Fallback for classifiers that missed the code: the reason keeps the raw
+    // pg error, whose message for 40P01 is "deadlock detected".
+    if (Predicate.hasProperty(reason, "cause")) {
+        const raw = String(reason.cause);
+        return raw.includes("40P01") || raw.includes("deadlock detected");
+    }
+    return false;
+};
 const rowsOf = (result) => "rows" in result ? result.rows : result;
 const toSchedule = (row) => ({
     key: JobStore.ScheduleKey(row.key),
@@ -38,6 +78,7 @@ const toSchedule = (row) => ({
     backoff: row.backoff ?? undefined,
     keep: row.keep ?? undefined,
     timeoutMs: row.timeoutMs === null ? undefined : Number(row.timeoutMs),
+    group: row.group ?? undefined,
     nextRunAt: row.nextRunAt.getTime()
 });
 const toRecord = (row) => ({
@@ -57,6 +98,17 @@ const toRecord = (row) => ({
     cancelRequested: row.cancelRequested,
     dedupeKey: row.dedupeKey ?? undefined,
     trace: row.trace ?? undefined,
+    parent: row.parent ?? undefined,
+    // The flow columns are NULL together; `flowPending` is the presence marker.
+    flow: row.flowPending === null || row.flowPending === undefined
+        ? undefined
+        : {
+            failFast: row.flowFailFast === true,
+            pending: Number(row.flowPending),
+            completed: Number(row.flowCompleted ?? 0),
+            failed: Number(row.flowFailed ?? 0),
+            cancelled: Number(row.flowCancelled ?? 0)
+        },
     runAt: row.runAt.getTime(),
     enqueuedAt: row.enqueuedAt.getTime(),
     processedAt: row.processedAt?.getTime(),
@@ -64,6 +116,17 @@ const toRecord = (row) => ({
     exit: row.exit ?? undefined,
     failedReason: row.failedReason ?? undefined
 });
+const toFlowChildRecord = (row) => ({
+    flowId: JobId(row.flowId),
+    childKey: row.childKey,
+    name: row.name,
+    storeKey: row.storeKey,
+    childJobId: JobId(row.childJobId),
+    status: row.status,
+    exit: row.exit ?? undefined,
+    failedReason: row.failedReason ?? undefined,
+    cascaded: row.cascaded
+});
 /**
  * Build the store implementation. Requires `PgClient` and a `Scope` (for the
  * LISTEN subscription).
@@ -78,6 +141,8 @@ export const make = (options) => Effect.gen(function* () {
     const schedules = options.schedules;
     const queues = options.queues;
     const dedupe = options.dedupe;
+    const flowChildren = options.flowChildren;
+    const flowOutbox = options.flowOutbox;
     const jobsName = getTableConfig(jobs).name;
     const attemptsName = getTableConfig(attempts).name;
     const wakeChannel = `effect_mq_wake_${jobsName}`;
@@ -102,6 +167,12 @@ export const make = (options) => Effect.gen(function* () {
         "cancelRequested",
         "dedupeKey",
         "trace",
+        "parent",
+        "flowFailFast",
+        "flowPending",
+        "flowCompleted",
+        "flowFailed",
+        "flowCancelled",
         "runAt",
         "enqueuedAt",
         "processedAt",
@@ -135,7 +206,9 @@ export const make = (options) => Effect.gen(function* () {
             db.select({ jobId: attempts.jobId }).from(attempts).limit(0),
             db.select({ key: schedules.key }).from(schedules).limit(0),
             db.select({ queue: queues.queue }).from(queues).limit(0),
-            db.select({ key: dedupe.key }).from(dedupe).limit(0)
+            db.select({ key: dedupe.key }).from(dedupe).limit(0),
+            db.select({ flowId: flowChildren.flowId }).from(flowChildren).limit(0),
+            db.select({ id: flowOutbox.id }).from(flowOutbox).limit(0)
         ]).pipe(Effect.mapError(storeError(`effect-mq: tables "${jobsName}"/"${attemptsName}" are missing or mismatched — ` +
             `re-export the effect-mq/drizzle schema factories from your drizzle schema and run your migrations (drizzle-kit generate)`)));
     }
@@ -175,6 +248,26 @@ export const make = (options) => Effect.gen(function* () {
     // Resubscribe forever: if the LISTEN stream ends or fails, wake-ups
     // degrade to the worker's pollInterval until the next attempt succeeds.
     yield* client.listen(wakeChannel).pipe(Stream.runForEach((payload) => Effect.sync(() => signalWake(payload === "*" ? undefined : JobStore.QueueName(payload)))), Effect.catchCause((cause) => Effect.logWarning("effect-mq: LISTEN subscription failed; wake-ups degraded to polling until resubscribe", cause)), Effect.andThen(Effect.sleep("1 second")), Effect.forever, Effect.forkScoped);
+    // Automatic retention (the store-level sweep and per-job `keep`) never
+    // prunes a flow parent that still owes cascade cancels: its dependency
+    // rows marked `cancelled` and not `cascaded` are the only record that
+    // real cancels are still due in the child stores. The explicit `remove`
+    // verb is not exempted.
+    const owesCascades = sql `EXISTS (
+      SELECT 1 FROM ${flowChildren}
+      WHERE ${flowChildren.flowId} = ${jobs.id}
+        AND ${flowChildren.status} = 'cancelled' AND ${flowChildren.cascaded} = FALSE
+    )`;
+    // A pruned flow parent's dependency rows go with it in the same statement.
+    const purgeJobsWhere = (predicate) => sql `
+        WITH deleted AS (
+          DELETE FROM ${jobs}
+          WHERE ${predicate}
+          RETURNING ${jobs.id} AS id
+        )
+        DELETE FROM ${flowChildren}
+        WHERE ${flowChildren.flowId} IN (SELECT id FROM deleted)
+      `;
     if (options.historyTtl !== undefined) {
         const ttlByState = JobStore.normalizeHistoryTtl(options.historyTtl);
         const sweepMs = Duration.toMillis(options.historySweepInterval ?? "1 minute");
@@ -185,9 +278,8 @@ export const make = (options) => Effect.gen(function* () {
             // job name is pruned on the timer, not only when its group is acked.
             for (const state of ["completed", "failed", "cancelled"]) {
                 const ttl = ttlByState[state];
-                yield* db.execute(sql `
-            DELETE FROM ${jobs}
-            WHERE ${jobs.state} = ${state} AND (
+                yield* db.execute(purgeJobsWhere(sql `
+            ${jobs.state} = ${state} AND NOT ${owesCascades} AND (
               ${ttl !== undefined ? sql `${jobs.finishedAt} <= ${new Date(now.getTime() - ttl)}` : sql `FALSE`}
               OR (
                 COALESCE(
@@ -202,7 +294,7 @@ export const make = (options) => Effect.gen(function* () {
                         ELSE ${jobs.keep}->>'ageMs' END
                     )::double precision) / 1000.0))
             )
-          `);
+          `));
             }
             // Dead dedup rows: expired windows, or pointers at vanished jobs.
             yield* db.execute(sql `
@@ -210,7 +302,7 @@ export const make = (options) => Effect.gen(function* () {
           WHERE (${dedupe.windowExpiresAt} IS NOT NULL AND ${dedupe.windowExpiresAt} <= ${now})
              OR (${dedupe.windowExpiresAt} IS NULL AND NOT EXISTS (
                SELECT 1 FROM ${jobs} WHERE ${jobs.id} = ${dedupe.jobId}
-                 AND ${jobs.state} IN ('waiting', 'delayed', 'active')
+                 AND ${jobs.state} IN ('waiting', 'delayed', 'active', 'waiting-children')
              ))
         `);
         }).pipe(Effect.catchCause((cause) => Effect.logWarning("effect-mq: history sweep failed", cause)), Effect.forever, Effect.forkScoped);
@@ -258,23 +350,23 @@ export const make = (options) => Effect.gen(function* () {
         if (keep === undefined)
             return;
         if (keep.ageMs !== undefined) {
-            yield* tx.execute(sql `
-            DELETE FROM ${jobs}
-            WHERE ${jobs.name} = ${row.name} AND ${jobs.state} = ${row.state}
+            yield* tx.execute(purgeJobsWhere(sql `
+            ${jobs.name} = ${row.name} AND ${jobs.state} = ${row.state}
               AND ${jobs.finishedAt} <= ${new Date(now.getTime() - keep.ageMs)}
-          `);
+              AND NOT ${owesCascades}
+          `));
         }
         if (keep.count !== undefined) {
-            yield* tx.execute(sql `
-            DELETE FROM ${jobs}
-            WHERE ${jobs.name} = ${row.name} AND ${jobs.state} = ${row.state}
+            yield* tx.execute(purgeJobsWhere(sql `
+            ${jobs.name} = ${row.name} AND ${jobs.state} = ${row.state}
               AND ${jobs.id} NOT IN (
                 SELECT ${jobs.id} FROM ${jobs}
                 WHERE ${jobs.name} = ${row.name} AND ${jobs.state} = ${row.state}
                 ORDER BY ${jobs.finishedAt} DESC, ${jobs.seq} DESC
                 LIMIT ${keep.count}
               )
-          `);
+              AND NOT ${owesCascades}
+          `));
         }
     });
     // Distinguish JobNotFound vs LockLost after a guarded UPDATE hit 0 rows.
@@ -303,7 +395,7 @@ export const make = (options) => Effect.gen(function* () {
                     : sql `'j-' || ${seqExpr}::text`;
             const rows = rowsOf(yield* exec.execute(sql `
             INSERT INTO ${jobs} (id, name, queue, state, priority, payload, metadata,
-              attempts_max, backoff, keep, timeout_ms, dedupe_key, trace, run_at, enqueued_at${extraColumnNames})
+              attempts_max, backoff, keep, timeout_ms, dedupe_key, trace, parent, run_at, enqueued_at${extraColumnNames})
             VALUES (${idExpr}, ${request.name}, ${request.queue}, ${state}, ${request.priority},
               ${JSON.stringify(request.payload ?? null)}::jsonb, ${JSON.stringify(request.metadata)}::jsonb,
               ${request.attemptsMax},
@@ -311,6 +403,7 @@ export const make = (options) => Effect.gen(function* () {
               ${request.keep === undefined ? null : JSON.stringify(request.keep)}::jsonb,
               ${request.timeoutMs ?? null}, ${request.dedupe?.key ?? null},
               ${request.trace === undefined ? null : JSON.stringify(request.trace)}::jsonb,
+              ${request.parent === undefined ? null : JSON.stringify(request.parent)}::jsonb,
               ${runAt}, ${now}${extraColumnValues(request)})
             ON CONFLICT (id) DO NOTHING
             RETURNING ${jobs.id} AS id
@@ -437,7 +530,7 @@ export const make = (options) => Effect.gen(function* () {
     // killed and safe to retry.
     Effect.retry({
         times: 3,
-        while: (error) => String(error).includes("40P01") || String(error).includes("deadlock detected")
+        while: isDeadlockError
     }), Effect.mapError((error) => error instanceof JobStore.JobStoreError ? error : storeError("enqueue failed")(error)));
     // A job leaving the pending states frees its pending-mode dedup row; live
     // throttle windows deliberately outlast the job.
@@ -449,26 +542,65 @@ export const make = (options) => Effect.gen(function* () {
             AND ${dedupe.jobId} = ${jobId}
             AND (${dedupe.windowExpiresAt} IS NULL OR ${dedupe.windowExpiresAt} <= ${now})
         `).pipe(Effect.asVoid);
+    // The outbox invariant: every operation that moves a job carrying a
+    // `parent` envelope INTO a terminal state appends its report here in the
+    // same transaction (see `JobStore.OutboxEntry`). `exit`/`failedReason`
+    // mirror the job row AFTER the transition; JSON.stringify drops
+    // undefined fields so absent values read back as undefined.
+    const appendOutbox = (exec, parent, outcome, exit, failedReason) => parent === null || parent === undefined
+        ? Effect.void
+        : exec.execute(sql `
+          INSERT INTO ${flowOutbox} (flow_name, parent_store_key, report)
+          VALUES (${parent.flowName}, ${parent.parentStoreKey}, ${JSON.stringify({
+            flowId: parent.flowId,
+            childKey: parent.childKey,
+            outcome,
+            exit,
+            failedReason: failedReason ?? undefined
+        })}::jsonb)
+        `).pipe(Effect.asVoid);
+    // Flip a flow's still-pending dependency rows to `cancelled` and NOT
+    // `cascaded` (the sweeper still owes the child stores real cancels).
+    // Embedded as a CTE body so the caller can count the marked rows into
+    // the parent's `cancelled` counter in the same statement.
+    const cancelPendingChildren = (flowId) => sql `
+        UPDATE ${flowChildren} SET status = 'cancelled', cascaded = FALSE
+        WHERE ${flowChildren.flowId} = ${flowId} AND ${flowChildren.status} = 'pending'
+        RETURNING 1
+      `;
     // Shared by cancel and cancelByDedupe.
     const cancelJob = (id) => db.transaction((tx) => Effect.gen(function* () {
         const now = yield* nowDate;
-        // One guarded statement: waiting/delayed become terminal, active
-        // gets the cancel-request flag; anything else is reported by state.
+        // Contract lock order (dependency rows first, parent second): mark
+        // a waiting-children parent's remaining pending rows cancelled.
+        // Pending rows exist only while the parent is `waiting-children`,
+        // so this is a no-op for every other state; a non-cancellable
+        // parent rolls the transaction back anyway.
+        const firstPass = rowsOf(yield* tx.execute(sql `
+            WITH marked AS (${cancelPendingChildren(id)})
+            SELECT count(*)::int AS marked FROM marked
+          `));
+        const preMarked = firstPass[0]?.marked ?? 0;
+        // One guarded statement: waiting/delayed/waiting-children become
+        // terminal, active gets the cancel-request flag; anything else is
+        // reported by state.
         const rows = rowsOf(yield* tx.execute(sql `
-              UPDATE ${jobs} SET
-                state = CASE WHEN ${jobs.state} IN ('waiting', 'delayed') THEN 'cancelled' ELSE ${jobs.state} END,
-                finished_at = CASE WHEN ${jobs.state} IN ('waiting', 'delayed') THEN ${now}::timestamptz ELSE ${jobs.finishedAt} END,
-                cancel_requested = CASE WHEN ${jobs.state} = 'active' THEN TRUE ELSE ${jobs.cancelRequested} END
-              WHERE ${jobs.id} = ${id} AND ${jobs.state} IN ('waiting', 'delayed', 'active')
-              RETURNING ${jobs.id} AS id, ${jobs.state} AS state,
-                ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep",
-                ${jobs.dedupeKey} AS "dedupeKey"
-            `));
+            UPDATE ${jobs} SET
+              state = CASE WHEN ${jobs.state} IN ('waiting', 'delayed', 'waiting-children') THEN 'cancelled' ELSE ${jobs.state} END,
+              finished_at = CASE WHEN ${jobs.state} IN ('waiting', 'delayed', 'waiting-children') THEN ${now}::timestamptz ELSE ${jobs.finishedAt} END,
+              flow_pending = CASE WHEN ${jobs.state} = 'waiting-children' THEN 0 ELSE ${jobs.flowPending} END,
+              cancel_requested = CASE WHEN ${jobs.state} = 'active' THEN TRUE ELSE ${jobs.cancelRequested} END
+            WHERE ${jobs.id} = ${id} AND ${jobs.state} IN ('waiting', 'delayed', 'active', 'waiting-children')
+            RETURNING ${jobs.id} AS id, ${jobs.state} AS state,
+              ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep",
+              ${jobs.dedupeKey} AS "dedupeKey", (${jobs.flowPending} IS NOT NULL) AS "hasFlow",
+              ${jobs.parent} AS "parent", ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
+          `));
         const row = rows[0];
         if (row === undefined) {
             const existing = rowsOf(yield* tx.execute(sql `
-                SELECT ${jobs.state} AS state FROM ${jobs} WHERE ${jobs.id} = ${id}
-              `));
+              SELECT ${jobs.state} AS state FROM ${jobs} WHERE ${jobs.id} = ${id}
+            `));
             const found = existing[0];
             if (found === undefined) {
                 return yield* new JobStore.JobNotFoundError({ jobId: id });
@@ -476,11 +608,36 @@ export const make = (options) => Effect.gen(function* () {
             return yield* new JobStore.JobNotCancellableError({ jobId: id, state: found.state });
         }
         if (row.state === "cancelled") {
+            if (row.hasFlow) {
+                // Re-run the marking now that the parent lock is held: the
+                // first UPDATE above races a concurrent FanOut — its
+                // uncommitted dependency-row INSERTs are invisible, while
+                // this UPDATE's own EPQ re-check can still see the parent as
+                // 'waiting-children' after the FanOut commits. Without this
+                // pass those rows would stay 'pending' forever, invisible to
+                // both sweep classes. Every row either pass marked lands in
+                // the `cancelled` counter.
+                yield* tx.execute(sql `
+                WITH marked AS (${cancelPendingChildren(id)})
+                UPDATE ${jobs} SET flow_cancelled = ${jobs.flowCancelled} + ${preMarked}::int
+                  + (SELECT count(*)::int FROM marked)
+                WHERE ${jobs.id} = ${id}
+              `);
+            }
             yield* insertAttempt(tx, id, "cancelled", row.processedAt, now, undefined);
+            // A cancelled child reports upward through the outbox.
+            yield* appendOutbox(tx, row.parent, "cancelled", row.exit ?? undefined, row.failedReason);
             yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now);
             yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now);
         }
-    })).pipe(Effect.mapError((error) => error instanceof JobStore.JobNotFoundError ||
+    })).pipe(
+    // Rare lock-order inversion (this row-then-parent flip vs a
+    // fail-fast settle's parent-then-rows marking) surfaces as a
+    // Postgres deadlock (40P01); one side is killed and safe to retry.
+    Effect.retry({
+        times: 3,
+        while: isDeadlockError
+    }), Effect.mapError((error) => error instanceof JobStore.JobNotFoundError ||
         error instanceof JobStore.JobNotCancellableError ||
         error instanceof JobStore.JobStoreError
         ? error
@@ -565,10 +722,11 @@ export const make = (options) => Effect.gen(function* () {
                 ${request.keep === undefined ? null : JSON.stringify(request.keep)}::jsonb,
                 ${request.timeoutMs ?? null}, ${request.dedupe?.key ?? null},
                 ${request.trace === undefined ? null : JSON.stringify(request.trace)}::jsonb,
+                ${request.parent === undefined ? null : JSON.stringify(request.parent)}::jsonb,
                 ${new Date(now.getTime() + Math.max(0, request.delayMs))}, ${now}${extraColumnValues(request)})`);
                 const rows = rowsOf(yield* db.execute(sql `
               INSERT INTO ${jobs} (id, name, queue, state, priority, payload, metadata,
-                attempts_max, backoff, keep, timeout_ms, dedupe_key, trace, run_at, enqueued_at${extraColumnNames})
+                attempts_max, backoff, keep, timeout_ms, dedupe_key, trace, parent, run_at, enqueued_at${extraColumnNames})
               VALUES ${sql.join(values, sql `, `)}
               ON CONFLICT (id) DO NOTHING
               RETURNING ${jobs.id} AS id
@@ -610,6 +768,97 @@ export const make = (options) => Effect.gen(function* () {
         }
         return resolved;
     });
+    // The FanOut ack: land the manifest (flow columns + dependency rows) and
+    // park the parent, all lock-token-guarded in one transaction. A fan-out
+    // is a phase transition, not a completed run — `attempts_made` is not
+    // incremented; the ledger records `fanned-out` with no exit.
+    const ackFanOut = (id, token, outcome) => Effect.gen(function* () {
+        // Validate BEFORE any mutation, so a bad spec cannot leave the job
+        // half-acked (lock cleared, ledger written, still active).
+        if (outcome.children.some((child) => child.request.id === undefined)) {
+            return yield* new JobStore.JobStoreError({
+                message: "FanOut child specs require an explicit request.id"
+            });
+        }
+        const wakeQueue = yield* db.transaction((tx) => Effect.gen(function* () {
+            const now = yield* nowDate;
+            const rows = rowsOf(yield* tx.execute(sql `
+              UPDATE ${jobs} SET lock_token = NULL, lock_expires_at = NULL
+              WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'active' AND ${jobs.lockToken} = ${token}
+              RETURNING ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name",
+                ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey", ${jobs.queue} AS "queue",
+                ${jobs.cancelRequested} AS "cancelRequested", ${jobs.flowPending} AS "flowPending",
+                ${jobs.parent} AS "parent", ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
+            `));
+            const row = rows[0];
+            if (row === undefined) {
+                return yield* explainMiss(id);
+            }
+            yield* insertAttempt(tx, id, "fanned-out", row.processedAt, now, undefined);
+            let pending;
+            if (row.flowPending === null || row.flowPending === undefined) {
+                pending = outcome.children.length;
+                yield* tx.execute(sql `
+                UPDATE ${jobs} SET flow_fail_fast = ${outcome.failFast}, flow_pending = ${pending},
+                  flow_completed = 0, flow_failed = 0, flow_cancelled = 0
+                WHERE ${jobs.id} = ${id}
+              `);
+                // Chunked multi-row VALUES, like enqueueMany's insertBatch.
+                for (let start = 0; start < outcome.children.length; start += 500) {
+                    const chunk = outcome.children.slice(start, start + 500);
+                    const values = chunk.map((child) => sql `(${id}, ${child.childKey}, ${child.request.name}, ${child.storeKey},
+                    ${JSON.stringify(child.request)}::jsonb, 'pending', NULL, NULL, FALSE, ${now})`);
+                    yield* tx.execute(sql `
+                  INSERT INTO ${flowChildren} (flow_id, child_key, name, store_key, spec,
+                    status, exit, failed_reason, cascaded, pending_since)
+                  VALUES ${sql.join(values, sql `, `)}
+                `);
+                }
+            }
+            else {
+                // A manifest that was already present is kept untouched (double
+                // fan-out converges on the persisted children); the state
+                // transition follows the persisted pending count either way.
+                pending = Number(row.flowPending);
+            }
+            if (row.cancelRequested) {
+                // A cancel raced the fan-out: cancellation wins. The rows exist
+                // and get marked (into the `cancelled` counter), so the sweeper
+                // cascades (mostly no-op cancels for never-enqueued children).
+                yield* tx.execute(sql `
+                WITH marked AS (${cancelPendingChildren(id)})
+                UPDATE ${jobs} SET state = 'cancelled', finished_at = ${now},
+                  cancel_requested = FALSE, flow_pending = 0,
+                  flow_cancelled = ${jobs.flowCancelled} + (SELECT count(*)::int FROM marked)
+                WHERE ${jobs.id} = ${id}
+              `);
+                yield* insertAttempt(tx, id, "cancelled", row.processedAt, now, undefined);
+                // A cancelled NESTED parent reports upward through the outbox.
+                yield* appendOutbox(tx, row.parent, "cancelled", row.exit ?? undefined, row.failedReason);
+                yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now);
+                yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now);
+                return undefined;
+            }
+            if (pending > 0) {
+                yield* tx.execute(sql `
+                UPDATE ${jobs} SET state = 'waiting-children' WHERE ${jobs.id} = ${id}
+              `);
+                return undefined;
+            }
+            // Empty (or fully recorded) manifest: straight to runnable collect.
+            yield* tx.execute(sql `
+              UPDATE ${jobs} SET state = 'waiting', run_at = ${now}, seq = ${seqExpr}
+              WHERE ${jobs.id} = ${id}
+            `);
+            return JobStore.QueueName(row.queue);
+        })).pipe(Effect.mapError((error) => error instanceof JobStore.JobNotFoundError || error instanceof JobStore.LockLostError ||
+            error instanceof JobStore.JobStoreError
+            ? error
+            : storeError("ack failed")(error)));
+        if (wakeQueue !== undefined) {
+            yield* wakeUp(wakeQueue);
+        }
+    });
     const store = {
         enqueue: enqueueOne,
         enqueueMany: (requests) => Effect.gen(function* () {
@@ -680,7 +929,10 @@ export const make = (options) => Effect.gen(function* () {
                 ${jobs.stalledCount} AS "stalledCount", ${jobs.backoff} AS "backoff",
                 ${jobs.keep} AS "keep", ${jobs.timeoutMs} AS "timeoutMs",
                 ${jobs.cancelRequested} AS "cancelRequested", ${jobs.dedupeKey} AS "dedupeKey",
-                ${jobs.trace} AS "trace",
+                ${jobs.trace} AS "trace", ${jobs.parent} AS "parent",
+                ${jobs.flowFailFast} AS "flowFailFast", ${jobs.flowPending} AS "flowPending",
+                ${jobs.flowCompleted} AS "flowCompleted", ${jobs.flowFailed} AS "flowFailed",
+                ${jobs.flowCancelled} AS "flowCancelled",
                 ${jobs.runAt} AS "runAt", ${jobs.enqueuedAt} AS "enqueuedAt",
                 ${jobs.processedAt} AS "processedAt", ${jobs.finishedAt} AS "finishedAt",
                 ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
@@ -703,55 +955,64 @@ export const make = (options) => Effect.gen(function* () {
                 return empty;
             }));
         }).pipe(Effect.mapError((error) => error instanceof JobStore.JobStoreError ? error : storeError("claim failed")(error))),
-        ack: (id, token, outcome) => db.transaction((tx) => Effect.gen(function* () {
-            const now = yield* nowDate;
-            const update = outcome._tag === "Complete"
-                ? sql `state = 'completed', cancel_requested = FALSE, exit = ${JSON.stringify(outcome.exit ?? null)}::jsonb, finished_at = ${now}`
-                : outcome._tag === "Fail"
-                    ? sql `state = 'failed', cancel_requested = FALSE, exit = ${JSON.stringify(outcome.exit ?? null)}::jsonb, finished_at = ${now}`
-                    : outcome._tag === "Cancelled"
-                        ? sql `state = 'cancelled', cancel_requested = FALSE, finished_at = ${now}`
-                        // A cancel that raced this natural failure wins over revival
-                        // (mirrors release/recoverStalled).
-                        : sql `state = CASE WHEN ${jobs.cancelRequested} THEN 'cancelled'
+        ack: (id, token, outcome) => {
+            if (outcome._tag === "FanOut") {
+                return ackFanOut(id, token, outcome);
+            }
+            return db.transaction((tx) => Effect.gen(function* () {
+                const now = yield* nowDate;
+                const update = outcome._tag === "Complete"
+                    ? sql `state = 'completed', cancel_requested = FALSE, exit = ${JSON.stringify(outcome.exit ?? null)}::jsonb, finished_at = ${now}`
+                    : outcome._tag === "Fail"
+                        ? sql `state = 'failed', cancel_requested = FALSE, exit = ${JSON.stringify(outcome.exit ?? null)}::jsonb, finished_at = ${now}`
+                        : outcome._tag === "Cancelled"
+                            ? sql `state = 'cancelled', cancel_requested = FALSE, finished_at = ${now}`
+                            // A cancel that raced this natural failure wins over revival
+                            // (mirrors release/recoverStalled).
+                            : sql `state = CASE WHEN ${jobs.cancelRequested} THEN 'cancelled'
                     ELSE ${outcome.delayMs > 0 ? "delayed" : "waiting"} END,
                   finished_at = CASE WHEN ${jobs.cancelRequested} THEN ${now}::timestamptz ELSE NULL END,
                   run_at = CASE WHEN ${jobs.cancelRequested} THEN ${jobs.runAt}
                     ELSE ${new Date(now.getTime() + Math.max(0, outcome.delayMs))}::timestamptz END,
                   seq = CASE WHEN ${jobs.cancelRequested} THEN ${jobs.seq} ELSE ${seqExpr} END,
                   cancel_requested = FALSE`;
-            const rows = rowsOf(yield* tx.execute(sql `
+                const rows = rowsOf(yield* tx.execute(sql `
               UPDATE ${jobs} SET ${update},
                 attempts_made = ${jobs.attemptsMade} + 1, lock_token = NULL, lock_expires_at = NULL
               WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'active' AND ${jobs.lockToken} = ${token}
               RETURNING ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name",
                 ${jobs.state} AS "state", ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey",
-                ${jobs.queue} AS "queue"
+                ${jobs.queue} AS "queue", ${jobs.parent} AS "parent", ${jobs.exit} AS "exit",
+                ${jobs.failedReason} AS "failedReason"
             `));
-            const row = rows[0];
-            if (row === undefined) {
-                return yield* explainMiss(id);
-            }
-            const cancelledRetry = outcome._tag === "Retry" && row.state === "cancelled";
-            const ledgerOutcome = outcome._tag === "Complete"
-                ? "completed"
-                : outcome._tag === "Fail"
-                    ? "failed"
-                    : outcome._tag === "Cancelled" || cancelledRetry
-                        ? "cancelled"
-                        : "retried";
-            yield* insertAttempt(tx, id, ledgerOutcome, row.processedAt, now, outcome._tag === "Cancelled" || cancelledRetry ? undefined : outcome.exit);
-            if (outcome._tag !== "Retry" || cancelledRetry) {
-                yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now);
-                yield* applyKeep(tx, row, now);
-            }
-            return outcome._tag === "Retry" && !cancelledRetry
-                ? JobStore.QueueName(row.queue)
-                : undefined;
-        })).pipe(Effect.mapError((error) => error instanceof JobStore.JobNotFoundError || error instanceof JobStore.LockLostError ||
-            error instanceof JobStore.JobStoreError
-            ? error
-            : storeError("ack failed")(error)), Effect.tap((queue) => queue !== undefined ? wakeUp(queue) : Effect.void), Effect.asVoid),
+                const row = rows[0];
+                if (row === undefined) {
+                    return yield* explainMiss(id);
+                }
+                const cancelledRetry = outcome._tag === "Retry" && row.state === "cancelled";
+                const ledgerOutcome = outcome._tag === "Complete"
+                    ? "completed"
+                    : outcome._tag === "Fail"
+                        ? "failed"
+                        : outcome._tag === "Cancelled" || cancelledRetry
+                            ? "cancelled"
+                            : "retried";
+                yield* insertAttempt(tx, id, ledgerOutcome, row.processedAt, now, outcome._tag === "Cancelled" || cancelledRetry ? undefined : outcome.exit);
+                if (outcome._tag !== "Retry" || cancelledRetry) {
+                    // A terminal transition of an envelope-carrying child reports
+                    // upward through the outbox (exit/failedReason as persisted).
+                    yield* appendOutbox(tx, row.parent, ledgerOutcome === "retried" ? "cancelled" : ledgerOutcome, row.exit ?? undefined, row.failedReason);
+                    yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now);
+                    yield* applyKeep(tx, row, now);
+                }
+                return outcome._tag === "Retry" && !cancelledRetry
+                    ? JobStore.QueueName(row.queue)
+                    : undefined;
+            })).pipe(Effect.mapError((error) => error instanceof JobStore.JobNotFoundError || error instanceof JobStore.LockLostError ||
+                error instanceof JobStore.JobStoreError
+                ? error
+                : storeError("ack failed")(error)), Effect.tap((queue) => queue !== undefined ? wakeUp(queue) : Effect.void), Effect.asVoid);
+        },
         release: (id, token) => Effect.gen(function* () {
             const released = yield* db.transaction((tx) => Effect.gen(function* () {
                 const now = yield* nowDate;
@@ -766,13 +1027,16 @@ export const make = (options) => Effect.gen(function* () {
                 WHERE ${jobs.id} = ${id} AND ${jobs.state} = 'active' AND ${jobs.lockToken} = ${token}
                 RETURNING ${jobs.id} AS id, (${jobs.state} = 'cancelled') AS cancelled,
                   ${jobs.processedAt} AS "processedAt", ${jobs.name} AS "name", ${jobs.keep} AS "keep",
-                  ${jobs.dedupeKey} AS "dedupeKey", ${jobs.queue} AS "queue"
+                  ${jobs.dedupeKey} AS "dedupeKey", ${jobs.queue} AS "queue",
+                  ${jobs.parent} AS "parent", ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
               `));
                 const row = rows[0];
                 if (row === undefined)
                     return undefined;
                 if (row.cancelled) {
                     yield* insertAttempt(tx, id, "cancelled", row.processedAt, now, undefined);
+                    // A cancel honoured at release is a terminal transition too.
+                    yield* appendOutbox(tx, row.parent, "cancelled", row.exit ?? undefined, row.failedReason);
                     yield* releaseDedupe(tx, row.name, row.dedupeKey, id, now);
                     yield* applyKeep(tx, { name: row.name, state: "cancelled", keep: row.keep }, now);
                 }
@@ -842,12 +1106,16 @@ export const make = (options) => Effect.gen(function* () {
                 cancel_requested = FALSE
               WHERE ${jobs.state} = 'active' AND ${jobs.lockExpiresAt} <= ${now}::timestamptz
               RETURNING ${jobs.id} AS "id", ${jobs.state} AS "state", ${jobs.processedAt} AS "processedAt",
-                ${jobs.name} AS "name", ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey"
+                ${jobs.name} AS "name", ${jobs.keep} AS "keep", ${jobs.dedupeKey} AS "dedupeKey",
+                ${jobs.parent} AS "parent", ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
             `));
             const recovered = [];
             for (const row of rows) {
                 yield* insertAttempt(tx, row.id, row.state === "cancelled" ? "cancelled" : "stalled", row.processedAt, now, undefined);
                 if (row.state === "cancelled" || row.state === "failed") {
+                    // Honoured cancels and stall exhaustion are terminal
+                    // transitions: envelope-carrying children report upward.
+                    yield* appendOutbox(tx, row.parent, row.state === "cancelled" ? "cancelled" : "failed", row.exit ?? undefined, row.failedReason);
                     yield* releaseDedupe(tx, row.name, row.dedupeKey, row.id, now);
                 }
                 if (row.state === "cancelled") {
@@ -905,7 +1173,11 @@ export const make = (options) => Effect.gen(function* () {
               ${jobs.attemptsMax} AS "attemptsMax", ${jobs.attemptsMade} AS "attemptsMade",
               ${jobs.stalledCount} AS "stalledCount", ${jobs.backoff} AS "backoff",
               ${jobs.keep} AS "keep", ${jobs.timeoutMs} AS "timeoutMs",
-              ${jobs.cancelRequested} AS "cancelRequested",
+              ${jobs.cancelRequested} AS "cancelRequested", ${jobs.dedupeKey} AS "dedupeKey",
+              ${jobs.trace} AS "trace", ${jobs.parent} AS "parent",
+              ${jobs.flowFailFast} AS "flowFailFast", ${jobs.flowPending} AS "flowPending",
+              ${jobs.flowCompleted} AS "flowCompleted", ${jobs.flowFailed} AS "flowFailed",
+              ${jobs.flowCancelled} AS "flowCancelled",
               ${jobs.runAt} AS "runAt", ${jobs.enqueuedAt} AS "enqueuedAt",
               ${jobs.processedAt} AS "processedAt", ${jobs.finishedAt} AS "finishedAt",
               ${jobs.exit} AS "exit", ${jobs.failedReason} AS "failedReason"
@@ -990,20 +1262,21 @@ export const make = (options) => Effect.gen(function* () {
         `).pipe(Effect.mapError(storeError("pausedQueues failed")), Effect.map((result) => rowsOf(result).map((row) => JobStore.QueueName(row.queue)))),
         upsertSchedule: (schedule) => db.execute(sql `
           INSERT INTO ${schedules} (key, job_name, queue, cron, tz, every_ms, payload, metadata,
-            priority, attempts_max, backoff, keep, timeout_ms, next_run_at)
+            priority, attempts_max, backoff, keep, timeout_ms, group_name, next_run_at)
           VALUES (${schedule.key}, ${schedule.jobName}, ${schedule.queue},
             ${schedule.cron ?? null}, ${schedule.tz ?? null}, ${schedule.everyMs ?? null},
             ${JSON.stringify(schedule.payload ?? null)}::jsonb, ${JSON.stringify(schedule.metadata)}::jsonb,
             ${schedule.priority}, ${schedule.attemptsMax},
             ${schedule.backoff === undefined ? null : JSON.stringify(schedule.backoff)}::jsonb,
             ${schedule.keep === undefined ? null : JSON.stringify(schedule.keep)}::jsonb,
-            ${schedule.timeoutMs ?? null}, ${new Date(schedule.nextRunAt)})
+            ${schedule.timeoutMs ?? null}, ${schedule.group ?? null}, ${new Date(schedule.nextRunAt)})
           ON CONFLICT (key) DO UPDATE SET
             job_name = EXCLUDED.job_name, queue = EXCLUDED.queue, cron = EXCLUDED.cron,
             tz = EXCLUDED.tz, every_ms = EXCLUDED.every_ms, payload = EXCLUDED.payload,
             metadata = EXCLUDED.metadata, priority = EXCLUDED.priority,
             attempts_max = EXCLUDED.attempts_max, backoff = EXCLUDED.backoff,
             keep = EXCLUDED.keep, timeout_ms = EXCLUDED.timeout_ms,
+            group_name = EXCLUDED.group_name,
             next_run_at = CASE
               WHEN ${schedules.cron} IS NOT DISTINCT FROM EXCLUDED.cron
                 AND ${schedules.tz} IS NOT DISTINCT FROM EXCLUDED.tz
@@ -1023,6 +1296,9 @@ export const make = (options) => Effect.gen(function* () {
             if (listOptions?.queue !== undefined) {
                 conditions.push(sql `${schedules.queue} = ${listOptions.queue}`);
             }
+            if (listOptions?.group !== undefined) {
+                conditions.push(sql `${schedules.group} = ${listOptions.group}`);
+            }
             const rows = rowsOf(yield* db.execute(sql `
             SELECT ${schedules.key} AS "key", ${schedules.jobName} AS "jobName",
               ${schedules.queue} AS "queue", ${schedules.cron} AS "cron", ${schedules.tz} AS "tz",
@@ -1030,7 +1306,7 @@ export const make = (options) => Effect.gen(function* () {
               ${schedules.metadata} AS "metadata", ${schedules.priority} AS "priority",
               ${schedules.attemptsMax} AS "attemptsMax", ${schedules.backoff} AS "backoff",
               ${schedules.keep} AS "keep", ${schedules.timeoutMs} AS "timeoutMs",
-              ${schedules.nextRunAt} AS "nextRunAt"
+              ${schedules.group} AS "group", ${schedules.nextRunAt} AS "nextRunAt"
             FROM ${schedules}
             WHERE ${sql.join(conditions, sql ` AND `)}
             ORDER BY ${schedules.key}
@@ -1046,7 +1322,7 @@ export const make = (options) => Effect.gen(function* () {
               ${schedules.metadata} AS "metadata", ${schedules.priority} AS "priority",
               ${schedules.attemptsMax} AS "attemptsMax", ${schedules.backoff} AS "backoff",
               ${schedules.keep} AS "keep", ${schedules.timeoutMs} AS "timeoutMs",
-              ${schedules.nextRunAt} AS "nextRunAt"
+              ${schedules.group} AS "group", ${schedules.nextRunAt} AS "nextRunAt"
             FROM ${schedules}
             WHERE ${schedules.nextRunAt} <= ${now}
             ORDER BY ${schedules.nextRunAt} ASC
@@ -1085,6 +1361,301 @@ export const make = (options) => Effect.gen(function* () {
             }
             return fired;
         }),
+        recordChildResults: (reports) => Effect.gen(function* () {
+            if (reports.length === 0) {
+                const none = [];
+                return none;
+            }
+            const batch = yield* db.transaction((tx) => Effect.gen(function* () {
+                const now = yield* nowDate;
+                const results = reports.map(() => ({ applied: false, parentSettled: false }));
+                // Phase 1a — apply every row update (contract lock order:
+                // dependency rows FIRST, parents second). Only a (flow, key)'s
+                // first occurrence in the batch can apply — later duplicates
+                // would find the row non-pending anyway, and UPDATE ... FROM
+                // must never see two source rows for one target.
+                const candidates = [];
+                const seen = new Set();
+                for (const [index, report] of reports.entries()) {
+                    const key = `${report.flowId}\u0000${report.childKey}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    candidates.push({ index, report });
+                }
+                for (let start = 0; start < candidates.length; start += 200) {
+                    const chunk = candidates.slice(start, start + 200);
+                    const values = chunk.map(({ index, report }) => sql `(${index}::int, ${report.flowId}::text, ${report.childKey}::text,
+                    ${report.outcome}::text,
+                    ${report.exit === undefined ? null : JSON.stringify(report.exit)}::jsonb,
+                    ${report.failedReason ?? null}::text)`);
+                    const appliedRows = rowsOf(yield* tx.execute(sql `
+                  UPDATE ${flowChildren} SET status = v.outcome, exit = v.exit,
+                    failed_reason = v.failed_reason, cascaded = TRUE
+                  FROM (VALUES ${sql.join(values, sql `, `)})
+                    AS v(ord, flow_id, child_key, outcome, exit, failed_reason)
+                  WHERE ${flowChildren.flowId} = v.flow_id AND ${flowChildren.childKey} = v.child_key
+                    AND ${flowChildren.status} = 'pending'
+                  RETURNING v.ord AS "ord"
+                `));
+                    for (const row of appliedRows) {
+                        const result = results[Number(row.ord)];
+                        if (result !== undefined) {
+                            result.applied = true;
+                        }
+                    }
+                }
+                const touched = new Map();
+                for (const [index, report] of reports.entries()) {
+                    if (results[index]?.applied !== true)
+                        continue;
+                    const touch = touched.get(report.flowId) ?? {
+                        appliedCount: 0,
+                        completed: 0,
+                        failed: 0,
+                        cancelled: 0,
+                        firstAppliedFailed: undefined,
+                        lastApplied: index
+                    };
+                    touch.appliedCount += 1;
+                    touch.lastApplied = index;
+                    if (report.outcome === "completed")
+                        touch.completed += 1;
+                    if (report.outcome === "cancelled")
+                        touch.cancelled += 1;
+                    if (report.outcome === "failed") {
+                        touch.failed += 1;
+                        touch.firstAppliedFailed ??= index;
+                    }
+                    touched.set(report.flowId, touch);
+                }
+                // Phase 1b + 2 — per touched flow (sorted, so concurrent
+                // batches take parent locks in one order): move the applied
+                // children from `pending` to their outcome counters, then make
+                // at most one settle decision. Fail-fast wins the tie.
+                const wakeQueues = [];
+                for (const flowId of [...touched.keys()].toSorted()) {
+                    const touch = touched.get(flowId);
+                    if (touch === undefined)
+                        continue;
+                    const parents = rowsOf(yield* tx.execute(sql `
+                  UPDATE ${jobs} SET
+                    flow_pending = GREATEST(${jobs.flowPending} - ${touch.appliedCount}::int, 0),
+                    flow_completed = ${jobs.flowCompleted} + ${touch.completed}::int,
+                    flow_failed = ${jobs.flowFailed} + ${touch.failed}::int,
+                    flow_cancelled = ${jobs.flowCancelled} + ${touch.cancelled}::int
+                  WHERE ${jobs.id} = ${flowId} AND ${jobs.flowPending} IS NOT NULL
+                  RETURNING ${jobs.state} AS "state", ${jobs.flowPending} AS "flowPending",
+                    ${jobs.flowFailFast} AS "flowFailFast", ${jobs.processedAt} AS "processedAt",
+                    ${jobs.name} AS "name", ${jobs.keep} AS "keep",
+                    ${jobs.dedupeKey} AS "dedupeKey", ${jobs.queue} AS "queue",
+                    ${jobs.parent} AS "parent"
+                `));
+                    const parent = parents[0];
+                    if (parent === undefined || parent.state !== "waiting-children")
+                        continue;
+                    const failedIndex = parent.flowFailFast === true ? touch.firstAppliedFailed : undefined;
+                    const failedReport = failedIndex !== undefined ? reports[failedIndex] : undefined;
+                    if (failedIndex !== undefined && failedReport !== undefined) {
+                        // The first applied failure settles the parent terminally
+                        // (store-side, like stall exhaustion: failedReason, no
+                        // exit) and marks the remaining rows in the same
+                        // transaction. A nested parent's own report goes to the
+                        // outbox here — this settle IS its terminal transition.
+                        const reason = `effect-mq: flow child "${failedReport.childKey}" failed`;
+                        yield* tx.execute(sql `
+                    WITH marked AS (${cancelPendingChildren(flowId)})
+                    UPDATE ${jobs} SET state = 'failed', finished_at = ${now},
+                      failed_reason = ${reason}, cancel_requested = FALSE, flow_pending = 0,
+                      flow_cancelled = ${jobs.flowCancelled} + (SELECT count(*)::int FROM marked)
+                    WHERE ${jobs.id} = ${flowId}
+                  `);
+                        yield* insertAttempt(tx, flowId, "failed", parent.processedAt, now, undefined);
+                        yield* appendOutbox(tx, parent.parent, "failed", undefined, reason);
+                        yield* releaseDedupe(tx, parent.name, parent.dedupeKey, flowId, now);
+                        yield* applyKeep(tx, { name: parent.name, state: "failed", keep: parent.keep }, now);
+                        const decided = results[failedIndex];
+                        if (decided !== undefined) {
+                            decided.parentSettled = true;
+                        }
+                        continue;
+                    }
+                    if (Number(parent.flowPending) === 0) {
+                        // All children settled: the parent resumes runnable, phase
+                        // collect, settled at the flow's last applied report.
+                        yield* tx.execute(sql `
+                    UPDATE ${jobs} SET state = 'waiting', run_at = ${now}, seq = ${seqExpr}
+                    WHERE ${jobs.id} = ${flowId}
+                  `);
+                        wakeQueues.push(JobStore.QueueName(parent.queue));
+                        const decided = results[touch.lastApplied];
+                        if (decided !== undefined) {
+                            decided.parentSettled = true;
+                        }
+                    }
+                }
+                return { results, wakeQueues };
+            })).pipe(
+            // Rare lock-order inversion (a concurrent cancel/settle marking
+            // rows) surfaces as a Postgres deadlock (40P01); the killed side
+            // is safe to retry — the row-state guard keeps it idempotent.
+            Effect.retry({
+                times: 3,
+                while: isDeadlockError
+            }), Effect.mapError((error) => error instanceof JobStore.JobStoreError ? error : storeError("recordChildResults failed")(error)));
+            for (const queue of batch.wakeQueues) {
+                yield* wakeUp(queue);
+            }
+            return batch.results;
+        }),
+        peekOutbox: (peekOptions) => Effect.gen(function* () {
+            const limit = Math.max(0, peekOptions.limit);
+            if (limit === 0) {
+                const none = [];
+                return none;
+            }
+            // `after` pages past a previously returned id (exclusive), whether
+            // or not that entry still exists. Anything that is not a canonical
+            // id this store issued is treated as unset.
+            const after = peekOptions.after !== undefined && CANONICAL_BIGSERIAL.test(peekOptions.after)
+                ? peekOptions.after
+                : undefined;
+            const rows = rowsOf(yield* db.execute(sql `
+            SELECT ${flowOutbox.id}::text AS "id", ${flowOutbox.flowName} AS "flowName",
+              ${flowOutbox.parentStoreKey} AS "parentStoreKey", ${flowOutbox.report} AS "report"
+            FROM ${flowOutbox}
+            ${after === undefined ? sql `` : sql `WHERE ${flowOutbox.id} > ${after}::bigint`}
+            ORDER BY ${flowOutbox.id} ASC
+            LIMIT ${limit}
+          `).pipe(Effect.mapError(storeError("peekOutbox failed"))));
+            return rows.map((row) => ({
+                id: row.id,
+                flowName: row.flowName,
+                parentStoreKey: row.parentStoreKey,
+                report: row.report
+            }));
+        }),
+        deleteOutbox: (ids) => Effect.suspend(() => {
+            // Ids are opaque strings to callers; only CANONICAL ids this store
+            // could have issued can match. The strictness matters twice: a
+            // foreign/garbled id must not blow up the ::bigint cast, and a
+            // non-canonical spelling ("007") must stay an unknown-id no-op
+            // rather than cast to 7 and delete a live entry.
+            const numeric = ids.filter((id) => CANONICAL_BIGSERIAL.test(id));
+            if (numeric.length === 0)
+                return Effect.void;
+            return db.execute(sql `
+            DELETE FROM ${flowOutbox}
+            WHERE ${flowOutbox.id} = ANY(${sql.param(numeric)}::bigint[])
+          `).pipe(Effect.mapError(storeError("deleteOutbox failed")), Effect.asVoid);
+        }),
+        listChildResults: (flowId, listOptions) => Effect.gen(function* () {
+            const limit = Math.max(1, listOptions?.limit ?? 1000);
+            const cursor = listOptions?.cursor;
+            // `spec->>'id'` instead of the whole spec: at 10k children the full
+            // payloads would transfer on every collect.
+            const rows = rowsOf(yield* db.execute(sql `
+            SELECT ${flowChildren.flowId} AS "flowId", ${flowChildren.childKey} AS "childKey",
+              ${flowChildren.name} AS "name", ${flowChildren.storeKey} AS "storeKey",
+              ${flowChildren.spec}->>'id' AS "childJobId", ${flowChildren.status} AS "status",
+              ${flowChildren.exit} AS "exit", ${flowChildren.failedReason} AS "failedReason",
+              ${flowChildren.cascaded} AS "cascaded"
+            FROM ${flowChildren}
+            WHERE ${flowChildren.flowId} = ${flowId}
+              ${cursor === undefined ? sql `` : sql `AND ${flowChildren.childKey} > ${cursor}`}
+            ORDER BY ${flowChildren.childKey} ASC
+            LIMIT ${limit + 1}
+          `).pipe(Effect.mapError(storeError("listChildResults failed"))));
+            const page = rows.slice(0, limit);
+            const items = page.map(toFlowChildRecord);
+            const last = items[items.length - 1];
+            return {
+                items,
+                cursor: rows.length > limit && last !== undefined ? last.childKey : undefined
+            };
+        }),
+        flowSweepWork: (sweepOptions) => Effect.gen(function* () {
+            const now = yield* nowDate;
+            const limit = Math.max(1, sweepOptions.limit ?? 1000);
+            const threshold = new Date(now.getTime() - sweepOptions.pendingAgeMs);
+            // Reconcile: pending rows past the eligibility threshold whose
+            // parent is still parked (a settled flow never re-drives work).
+            // Returning a row re-arms `pending_since` in the same statement, so
+            // a full page rotates across sweeps instead of pinning its head.
+            // SKIP LOCKED: rows a concurrent report/settle holds are its
+            // business, and never waiting means this statement cannot deadlock.
+            // The raw column names are safe: only table names vary across
+            // factory instances. RETURNING order is unspecified — sorted below.
+            const reconcileRows = rowsOf(yield* db.execute(sql `
+            WITH due AS (
+              SELECT c.flow_id, c.child_key
+              FROM ${flowChildren} c
+              JOIN ${jobs} j ON j.id = c.flow_id
+              WHERE c.status = 'pending' AND c.pending_since <= ${threshold}
+                AND j.state = 'waiting-children'
+              ORDER BY c.flow_id, c.child_key
+              LIMIT ${limit}
+              FOR UPDATE OF c SKIP LOCKED
+            )
+            UPDATE ${flowChildren} SET pending_since = ${now}
+            FROM due
+            WHERE ${flowChildren.flowId} = due.flow_id AND ${flowChildren.childKey} = due.child_key
+            RETURNING ${flowChildren.flowId} AS "flowId", ${flowChildren.childKey} AS "childKey",
+              ${flowChildren.storeKey} AS "storeKey", ${flowChildren.spec} AS "spec"
+          `).pipe(Effect.mapError(storeError("flowSweepWork failed"))))
+                .toSorted((a, b) => a.flowId !== b.flowId
+                ? (a.flowId < b.flowId ? -1 : 1)
+                : a.childKey < b.childKey
+                    ? -1
+                    : a.childKey > b.childKey
+                        ? 1
+                        : 0);
+            // Cascade: cancelled rows whose cancel has not been delivered into
+            // the child's store yet (any parent state).
+            const cascadeRows = rowsOf(yield* db.execute(sql `
+            SELECT ${flowChildren.flowId} AS "flowId", ${flowChildren.childKey} AS "childKey",
+              ${flowChildren.storeKey} AS "storeKey", ${flowChildren.spec} AS "spec"
+            FROM ${flowChildren}
+            WHERE ${flowChildren.status} = 'cancelled' AND ${flowChildren.cascaded} = FALSE
+            ORDER BY ${flowChildren.flowId}, ${flowChildren.childKey}
+            LIMIT ${limit}
+          `).pipe(Effect.mapError(storeError("flowSweepWork failed"))));
+            const reconcile = [];
+            for (const row of reconcileRows) {
+                const flowId = JobId(row.flowId);
+                let group = reconcile[reconcile.length - 1];
+                if (group === undefined || group.flowId !== flowId) {
+                    group = { flowId, children: [] };
+                    reconcile.push(group);
+                }
+                group.children.push({ childKey: row.childKey, storeKey: row.storeKey, request: row.spec });
+            }
+            const cascade = [];
+            for (const row of cascadeRows) {
+                const flowId = JobId(row.flowId);
+                let group = cascade[cascade.length - 1];
+                if (group === undefined || group.flowId !== flowId) {
+                    group = { flowId, children: [] };
+                    cascade.push(group);
+                }
+                group.children.push({
+                    childKey: row.childKey,
+                    storeKey: row.storeKey,
+                    // SAFETY: the FanOut ack validated every spec id before
+                    // persisting it.
+                    childJobId: row.spec.id
+                });
+            }
+            const work = { reconcile, cascade };
+            return work;
+        }),
+        markChildrenCascaded: (flowId, childKeys) => childKeys.length === 0
+            ? Effect.void
+            : db.execute(sql `
+            UPDATE ${flowChildren} SET cascaded = TRUE
+            WHERE ${flowChildren.flowId} = ${flowId}
+              AND ${flowChildren.childKey} = ANY(${sql.param([...childKeys])})
+          `).pipe(Effect.mapError(storeError("markChildrenCascaded failed")), Effect.asVoid),
         counts: (queue) => db.execute(sql `
           SELECT ${jobs.state} AS "state", count(*)::int AS "count" FROM ${jobs}
           ${queue === undefined ? sql `` : sql `WHERE ${jobs.queue} = ${queue}`}
@@ -1095,6 +1666,7 @@ export const make = (options) => Effect.gen(function* () {
                 waiting: 0,
                 delayed: 0,
                 active: 0,
+                "waiting-children": 0,
                 completed: 0,
                 failed: 0,
                 cancelled: 0
@@ -1103,10 +1675,19 @@ export const make = (options) => Effect.gen(function* () {
                 counts[row.state] = row.count;
             return counts;
         })),
-        remove: (id) => db.execute(sql `
-          DELETE FROM ${jobs}
-          WHERE ${jobs.id} = ${id} AND ${jobs.state} <> 'active'
-          RETURNING ${jobs.id} AS id
+        remove: (id) => 
+        // The purge CTE takes a removed flow parent's dependency rows with it
+        // in the same statement.
+        db.execute(sql `
+          WITH deleted AS (
+            DELETE FROM ${jobs}
+            WHERE ${jobs.id} = ${id} AND ${jobs.state} NOT IN ('active', 'waiting-children')
+            RETURNING ${jobs.id} AS id
+          ), purged AS (
+            DELETE FROM ${flowChildren}
+            WHERE ${flowChildren.flowId} IN (SELECT id FROM deleted)
+          )
+          SELECT id FROM deleted
         `).pipe(Effect.mapError(storeError("remove failed")), Effect.map((result) => rowsOf(result).length > 0))
     };
     return store;