effect-mq 0.5.0 → 0.7.0

package/src/redis/RedisJobStore.ts

@@ -12,7 +12,20 @@
  *
  * @since 0.2.0
  */
-import { Clock, type Context, Deferred, Duration, Effect, Exit, Layer, Option, Queue, Schedule, type Scope } from "effect"
+import {
+  Clock,
+  type Context,
+  Data,
+  Deferred,
+  Duration,
+  Effect,
+  Exit,
+  Layer,
+  Option,
+  Queue,
+  Schedule,
+  type Scope
+} from "effect"
 import { Redis } from "effect/unstable/persistence"
 import * as JobStore from "../JobStore.ts"
 import * as scripts from "./scripts.ts"
@@ -37,6 +50,65 @@ export interface RedisJobStoreOptions {
    * Default: `j-<n>` from the store's counter. See `JobStore.IdGenerator`.
    */
   readonly idGenerator?: JobStore.IdGenerator | undefined
+  /**
+   * The optional list indexes: `p:byname:<name>` and `p:byqueue:<queue>`,
+   * both scored by `enqueuedAt`, serving `list({ name })` / `list({ queue })`
+   * without a full scan. Default: all on. `false` disables both; a partial
+   * object disables one (`{ name: false }`). Disable an index only when you
+   * never list that way — a `list` that ROUTES to a disabled index dies with
+   * `ListIndexDisabledError` (a query servable from another structure, e.g.
+   * `name` + terminal `states` ordered by `finishedAt`, never touches it).
+   *
+   * This setting is a PER-PREFIX invariant: every store instance sharing a
+   * key prefix must agree on it. Index writes happen at insert time in the
+   * writing process, so a store with an index off inserts rows that index
+   * never sees — enabled readers on the same prefix silently miss those rows
+   * (the `p:index:<kind>:ready` marker churn between mixed stores is a
+   * symptom of the misconfiguration, not a safety net against it).
+   *
+   * Init reconciles each index one-shot. Enabled with no `ready` marker: a
+   * full driver-paged ZSCAN of `p:all` rebuilds it, then stamps the marker
+   * with the rebuild's start time. Enabled with a marker: rows enqueued since
+   * the marker minus a 60s margin are (re-)indexed — so a rolling deploy
+   * whose old, index-less writers kept inserting after the marker landed is
+   * healed by the last new-code boot — and the marker is re-stamped.
+   * Disabled: only the marker is deleted (a future re-enable then does a full
+   * rebuild instead of trusting stale zsets). The zsets themselves are NEVER
+   * deleted at init — this store cannot know whether an enabled sibling is
+   * serving reads from them. After disabling everywhere, reclaim the memory
+   * manually, e.g.:
+   * `redis-cli --scan --pattern '<prefix>:byname:*' | xargs redis-cli del`.
+   *
+   * @since 0.7.0
+   */
+  readonly indexes?: { readonly name?: boolean | undefined; readonly queue?: boolean | undefined } | false | undefined
+}
+
+/**
+ * A `list` query routed to a list index this store is configured not to
+ * maintain (`RedisJobStoreOptions.indexes`). Delivered as a defect, not a
+ * typed failure: the configuration said "we never list this way", so the
+ * query contradicting it is a programming mistake, matching the library's
+ * die-on-config-mistake idiom.
+ *
+ * @since 0.7.0
+ */
+export class ListIndexDisabledError extends Data.TaggedError("ListIndexDisabledError")<{
+  readonly index: "name" | "queue"
+  readonly message: string
+}> {}
+
+const TERMINAL_STATES: ReadonlySet<JobStore.JobState> = new Set(["completed", "failed", "cancelled"])
+
+/**
+ * The `list` predicates the routed structure does NOT pin, applied per row
+ * inside the list script. Field names are part of the script's contract.
+ */
+interface ResidualFilters {
+  readonly queue?: JobStore.QueueName | undefined
+  readonly name?: string | undefined
+  readonly states?: ReadonlyArray<JobStore.JobState> | undefined
+  readonly metadata?: Readonly<Record<string, string>> | undefined
 }
 
 const storeError = (message: string) => (cause: unknown) => new JobStore.JobStoreError({ message, cause })
@@ -85,6 +157,18 @@ const toRecord = (hash: ReadonlyMap<string, string>): JobStore.JobRecord => ({
   cancelRequested: hash.get("cancelRequested") === "1",
   dedupeKey: optionalString(hash.get("dedupeKey")),
   trace: optionalJson<JobStore.TraceContext>(hash.get("trace")),
+  parent: optionalJson<JobStore.ParentEnvelope>(hash.get("parent")),
+  // Manifest presence IS the phase marker: hashes written before flows (or
+  // parents that never fanned out) simply lack the flow fields.
+  flow: optionalString(hash.get("flowPending")) === undefined
+    ? undefined
+    : {
+      failFast: hash.get("flowFailFast") === "1",
+      pending: Number(hash.get("flowPending")),
+      completed: Number(hash.get("flowCompleted") ?? 0),
+      failed: Number(hash.get("flowFailed") ?? 0),
+      cancelled: Number(hash.get("flowCancelled") ?? 0)
+    },
   runAt: Number(hash.get("runAt") ?? 0),
   enqueuedAt: Number(hash.get("enqueuedAt") ?? 0),
   processedAt: optionalNumber(hash.get("processedAt")),
@@ -115,15 +199,68 @@ const toSchedule = (hash: ReadonlyMap<string, string>): JobStore.ScheduleRecord
 const asArray = <A>(value: ReadonlyArray<A> | Record<string, never>): ReadonlyArray<A> =>
   Array.isArray(value) ? value : []
 
+/**
+ * Decode one outbox zset member: `<seq>\0<json>` where the json carries the
+ * verbatim parent envelope plus the terminal outcome. The full member string
+ * is the opaque entry id (deleteOutbox is then a plain ZREM).
+ */
+const toOutboxEntry = (member: string): JobStore.OutboxEntry => {
+  const sep = member.indexOf("\u0000")
+  const body: {
+    parent: JobStore.ParentEnvelope
+    outcome: JobStore.FlowChildReport["outcome"]
+    exit?: unknown
+    failedReason?: string
+  } = JSON.parse(member.slice(sep + 1))
+  return {
+    id: member,
+    flowName: body.parent.flowName,
+    parentStoreKey: body.parent.parentStoreKey,
+    report: {
+      flowId: body.parent.flowId,
+      childKey: body.parent.childKey,
+      outcome: body.outcome,
+      // The exit key is omitted entirely when absent (ledger convention),
+      // so a legitimate encoded null exit survives the round trip.
+      exit: Object.hasOwn(body, "exit") ? body.exit : undefined,
+      failedReason: body.failedReason
+    }
+  }
+}
+
 const JOB_STATES: ReadonlyArray<JobStore.JobState> = [
   "waiting",
   "delayed",
   "active",
+  "waiting-children",
   "completed",
   "failed",
   "cancelled"
 ]
 
+/**
+ * Fold one positional dependency-row tuple into a `FlowChildRecord`. The
+ * order must stay in lockstep with the HMGET field list in the
+ * `listChildResults` script:
+ * childKey, storeKey, childJobId, name, status, exit, failedReason, cascaded.
+ */
+const toChildRecord = (
+  flowId: JobStore.JobId,
+  row: ReadonlyArray<string>
+): JobStore.FlowChildRecord => ({
+  flowId,
+  childKey: row[0] ?? "",
+  storeKey: row[1] ?? "",
+  childJobId: JobStore.JobId(row[2] ?? ""),
+  name: row[3] ?? "",
+  // SAFETY: the status field is only ever written with FlowChildRecord
+  // status members ("pending" at insert, a report/settle outcome after).
+  status: (row[4] ?? "pending") as JobStore.FlowChildRecord["status"],
+  exit: optionalJson(row[5]),
+  failedReason: optionalString(row[6]),
+  cascaded: row[7] === "1"
+})
+
 /**
  * Build a `RedisJobStore` service. Needs the `Redis` service and a `Scope`
  * (the wake-up subscription and the optional history sweeper live in it).
@@ -137,29 +274,104 @@ export const make = (
     const redis = yield* Redis.Redis
     const prefix = options?.prefix ?? "effect-mq"
     const wakeChannel = `${prefix}:wake`
+    const indexOptions = options?.indexes
+    const indexes: scripts.IndexConfig = indexOptions === false
+      ? { name: false, queue: false }
+      : { name: indexOptions?.name ?? true, queue: indexOptions?.queue ?? true }
+    const HELPERS = scripts.helpers(indexes)
 
-    const evalEnqueue = redis.eval(scripts.enqueue)
-    const evalClaim = redis.eval(scripts.claim)
-    const evalAck = redis.eval(scripts.ack)
-    const evalRelease = redis.eval(scripts.release)
-    const evalExtendLocks = redis.eval(scripts.extendLocks)
-    const evalRecoverStalled = redis.eval(scripts.recoverStalled)
-    const evalGetJob = redis.eval(scripts.getJob)
-    const evalList = redis.eval(scripts.list)
-    const evalCounts = redis.eval(scripts.counts)
-    const evalRemove = redis.eval(scripts.remove)
-    const evalRetry = redis.eval(scripts.retry)
-    const evalCancel = redis.eval(scripts.cancel)
-    const evalPromote = redis.eval(scripts.promote)
-    const evalUpsertSchedule = redis.eval(scripts.upsertSchedule)
-    const evalRemoveSchedule = redis.eval(scripts.removeSchedule)
-    const evalListSchedules = redis.eval(scripts.listSchedules)
-    const evalDueSchedules = redis.eval(scripts.dueSchedules)
-    const evalAdvanceSchedule = redis.eval(scripts.advanceSchedule)
-    const evalTickSchedule = redis.eval(scripts.tickSchedule)
-    const evalEnqueueMany = redis.eval(scripts.enqueueMany)
-    const evalSweepState = redis.eval(scripts.sweepState)
-    const evalSweepDedupes = redis.eval(scripts.sweepDedupes)
+    const evalEnqueue = redis.eval(scripts.enqueue(HELPERS))
+    const evalClaim = redis.eval(scripts.claim(HELPERS))
+    const evalAck = redis.eval(scripts.ack(HELPERS))
+    const evalRelease = redis.eval(scripts.release(HELPERS))
+    const evalExtendLocks = redis.eval(scripts.extendLocks(HELPERS))
+    const evalRecoverStalled = redis.eval(scripts.recoverStalled(HELPERS))
+    const evalGetJob = redis.eval(scripts.getJob(HELPERS))
+    const evalList = redis.eval(scripts.list(HELPERS))
+    const evalIndexMembers = redis.eval(scripts.indexMembers(HELPERS))
+    const evalIndexTailPage = redis.eval(scripts.indexTailPage(HELPERS))
+    const evalCounts = redis.eval(scripts.counts(HELPERS))
+    const evalRemove = redis.eval(scripts.remove(HELPERS))
+    const evalRetry = redis.eval(scripts.retry(HELPERS))
+    const evalCancel = redis.eval(scripts.cancel(HELPERS))
+    const evalPromote = redis.eval(scripts.promote(HELPERS))
+    const evalUpsertSchedule = redis.eval(scripts.upsertSchedule(HELPERS))
+    const evalRemoveSchedule = redis.eval(scripts.removeSchedule(HELPERS))
+    const evalListSchedules = redis.eval(scripts.listSchedules(HELPERS))
+    const evalDueSchedules = redis.eval(scripts.dueSchedules(HELPERS))
+    const evalAdvanceSchedule = redis.eval(scripts.advanceSchedule(HELPERS))
+    const evalTickSchedule = redis.eval(scripts.tickSchedule(HELPERS))
+    const evalEnqueueMany = redis.eval(scripts.enqueueMany(HELPERS))
+    const evalSweepState = redis.eval(scripts.sweepState(HELPERS))
+    const evalSweepDedupes = redis.eval(scripts.sweepDedupes(HELPERS))
+    const evalFanOut = redis.eval(scripts.fanOut(HELPERS))
+    const evalRecordChildResults = redis.eval(scripts.recordChildResults(HELPERS))
+    const evalListChildResults = redis.eval(scripts.listChildResults(HELPERS))
+    const evalFlowSweepWork = redis.eval(scripts.flowSweepWork(HELPERS))
+    const evalMarkChildrenCascaded = redis.eval(scripts.markChildrenCascaded(HELPERS))
+
+    // List-index reconcile, once per boot per index. All work is driver-paged
+    // — never one giant Lua call — so the single-threaded server is never
+    // held. There is no build lock: concurrent boots duplicate idempotent
+    // ZADDs, a crash before the marker stamp makes the next boot redo the
+    // work, and rows inserted meanwhile are indexed live by insertJobRow.
+    //
+    // - enabled, no marker: full rebuild via ZSCAN over `all` (cursor-based
+    //   and linear — immune to score ties and rank shifts; every member
+    //   present for the whole scan is guaranteed returned). Rows deleted
+    //   mid-scan leave at most stale members the read path self-heals.
+    // - enabled, marker present: heal the tail. Index writes are per-process,
+    //   so writers without them (an older version mid-rolling-deploy, or a
+    //   misconfigured indexes-off store) may have inserted unindexed rows
+    //   AFTER the marker landed. Re-indexing everything enqueued since the
+    //   marker minus a 60s margin closes that window: the last enabled boot
+    //   after such writers stop covers everything they wrote before it.
+    // - disabled: delete ONLY the marker (a later re-enable must not trust
+    //   stale zsets). The zsets stay — an enabled sibling may be reading
+    //   them, and this store cannot know.
+    //
+    // Both paths re-stamp the marker with this boot's start time. Init-time
+    // infra failures die — the store never starts half-configured.
+    yield* Effect.gen(function*() {
+      const bootAt = yield* Clock.currentTimeMillis
+      for (const kind of ["name", "queue"] as const) {
+        const marker = `${prefix}:index:${kind}:ready`
+        if (!indexes[kind]) {
+          yield* redis.send("DEL", marker)
+          continue
+        }
+        // SAFETY: GET always replies with a bulk string or null.
+        const stamped = (yield* redis.send("GET", marker)) as string | null
+        const markerAt = stamped === null || stamped === "" ? Number.NaN : Number(stamped)
+        if (Number.isNaN(markerAt)) {
+          let cursor = "0"
+          do {
+            const reply = yield* redis.send("ZSCAN", `${prefix}:all`, cursor, "COUNT", "500")
+            // SAFETY: ZSCAN always replies [nextCursor, member/score pairs].
+            const [next, flat] = reply as [string, ReadonlyArray<string>]
+            cursor = next
+            const ids: Array<string> = []
+            for (let i = 0; i < flat.length; i += 2) {
+              const id = flat[i]
+              if (id !== undefined) ids.push(id)
+            }
+            // COUNT is only a hint — chunk what actually came back.
+            for (let start = 0; start < ids.length; start += 500) {
+              yield* evalIndexMembers(prefix, kind, JSON.stringify(ids.slice(start, start + 500)))
+            }
+          } while (cursor !== "0")
+        } else {
+          const min = String(markerAt - 60_000)
+          let offset = 0
+          while (true) {
+            const scanned = Number(yield* evalIndexTailPage(prefix, kind, min, offset, 500))
+            if (scanned < 500) break
+            offset += scanned
+          }
+        }
+        yield* redis.send("SET", marker, String(bootAt))
+      }
+    }).pipe(Effect.orDie)
 
     // Wake protocol: a queue-filtered waiter registry (same-process wake-ups
     // never depend on the pub/sub round trip), with the channel carrying
@@ -282,9 +494,71 @@ export const make = (
         request.dedupe?.ttlMs === undefined ? "" : String(request.dedupe.ttlMs),
         request.dedupe?.extend === true ? "1" : "0",
         request.dedupe?.replace === true ? "1" : "0",
-        request.trace === undefined ? "" : JSON.stringify(request.trace)
+        request.trace === undefined ? "" : JSON.stringify(request.trace),
+        request.parent === undefined ? "" : JSON.stringify(request.parent)
       )
 
+    // The FanOut ack. Large manifests chunk their dependency rows across
+    // several lock-token-guarded script calls (ARGV strides, like
+    // enqueueMany); only the FINAL chunk writes the manifest and flips the
+    // state, so a crash mid-staging leaves the job active and recoverable —
+    // the next attempt's first chunk clears the orphaned staged rows.
+    const fanOutAck = (
+      id: JobStore.JobId,
+      token: string,
+      failFast: boolean,
+      children: ReadonlyArray<JobStore.FlowChildSpec>
+    ) =>
+      Effect.gen(function*() {
+        if (children.some((child) => child.request.id === undefined)) {
+          // Validate BEFORE any script call, so a bad spec cannot leave the
+          // job half-acked (rows staged, ledger written, still active).
+          return yield* new JobStore.JobStoreError({
+            message: "FanOut child specs require an explicit request.id"
+          })
+        }
+        const now = yield* Clock.currentTimeMillis
+        const chunks: Array<ReadonlyArray<JobStore.FlowChildSpec>> = []
+        for (let start = 0; start < children.length; start += 500) {
+          chunks.push(children.slice(start, start + 500))
+        }
+        // An empty manifest still needs the final (state-flipping) call.
+        if (chunks.length === 0) chunks.push([])
+        for (let i = 0; i < chunks.length; i++) {
+          const chunk = chunks[i]
+          if (chunk === undefined) continue
+          const items: Array<string> = []
+          for (const child of chunk) {
+            items.push(
+              child.childKey,
+              child.storeKey,
+              child.request.id ?? "",
+              child.request.name,
+              JSON.stringify(child.request)
+            )
+          }
+          const reply: { error?: string; wake?: boolean; queue?: string } = JSON.parse(
+            yield* evalFanOut(
+              prefix,
+              id,
+              token,
+              i === chunks.length - 1 ? "1" : "0",
+              i === 0 ? "1" : "0",
+              failFast ? "1" : "0",
+              children.length,
+              now,
+              chunk.length,
+              items
+            ).pipe(Effect.mapError(storeError("ack failed")))
+          )
+          if (reply.error === "notfound") return yield* new JobStore.JobNotFoundError({ jobId: id })
+          if (reply.error === "locklost") return yield* new JobStore.LockLostError({ jobId: id })
+          if (reply.wake === true) {
+            yield* wakeUp(reply.queue !== undefined ? JobStore.QueueName(reply.queue) : undefined)
+          }
+        }
+      })
+
     // Shared by cancel and cancelByDedupe.
     const cancelJob = (id: JobStore.JobId) =>
       Effect.gen(function*() {
@@ -380,6 +654,7 @@ export const make = (
                 request.keep === undefined ? "" : JSON.stringify(request.keep),
                 request.timeoutMs === undefined ? "" : String(request.timeoutMs),
                 request.trace === undefined ? "" : JSON.stringify(request.trace),
+                request.parent === undefined ? "" : JSON.stringify(request.parent),
                 String(Math.max(0, request.delayMs))
               )
             }
@@ -504,15 +779,20 @@ export const make = (
           })
         }).pipe(Effect.mapError(storeError("claim failed"))),
 
-      ack: (id, token, outcome) =>
-        Effect.gen(function*() {
+      ack: (id, token, outcome) => {
+        if (outcome._tag === "FanOut") {
+          return fanOutAck(id, token, outcome.failFast, outcome.children)
+        }
+        // Narrowed binding: the closure below must see the FanOut-free union.
+        const settled = outcome
+        return Effect.gen(function*() {
           const now = yield* Clock.currentTimeMillis
-          const exitJson = outcome._tag === "Cancelled" || outcome.exit === undefined
+          const exitJson = settled._tag === "Cancelled" || settled.exit === undefined
             ? ""
-            : JSON.stringify(outcome.exit)
-          const delayMs = outcome._tag === "Retry" ? Math.max(0, outcome.delayMs) : 0
+            : JSON.stringify(settled.exit)
+          const delayMs = settled._tag === "Retry" ? Math.max(0, settled.delayMs) : 0
           const reply: { error?: string; wake?: boolean; queue?: string } = JSON.parse(
-            yield* evalAck(prefix, id, token, outcome._tag, exitJson, delayMs, now).pipe(
+            yield* evalAck(prefix, id, token, settled._tag, exitJson, delayMs, now).pipe(
               Effect.mapError(storeError("ack failed"))
             )
           )
@@ -521,7 +801,8 @@ export const make = (
           if (reply.wake === true) {
             yield* wakeUp(reply.queue !== undefined ? JobStore.QueueName(reply.queue) : undefined)
           }
-        }),
+        })
+      },
 
       release: (id, token) =>
         Effect.gen(function*() {
@@ -617,24 +898,102 @@ export const make = (
       list: (listOptions) =>
         Effect.gen(function*() {
           const limit = Math.max(1, listOptions.limit ?? 50)
-          const filters = {
-            queue: listOptions.queue,
-            name: listOptions.name,
-            states: listOptions.states,
-            metadata: listOptions.metadata
+          const { metadata, name, queue, states } = listOptions
+          const orderBy = listOptions.orderBy ?? "enqueuedAt"
+          const order = listOptions.order ?? "desc"
+          // Routing: the narrowest structure whose zset score IS the
+          // requested order value; everything it does not pin stays a
+          // residual predicate applied in-script. Routing runs BEFORE the
+          // disabled-index check — a query another structure serves (e.g.
+          // name + terminal states ordered by finishedAt) must never die.
+          let sources: ReadonlyArray<string>
+          let residual: ResidualFilters
+          if (orderBy === "finishedAt") {
+            if (states === undefined || states.some((state) => !TERMINAL_STATES.has(state))) {
+              return yield* Effect.die(
+                new JobStore.ListOrderUnsupportedError({
+                  orderBy,
+                  message: "effect-mq: the Redis store serves orderBy \"finishedAt\" only with " +
+                    "states ⊆ {completed, failed, cancelled} (the finished/terminal zsets carry that order)"
+                })
+              )
+            }
+            // ≤3 per-state sources, merged by (finishedAt, id) in-script.
+            const uniqueStates = [...new Set(states)]
+            sources = name === undefined
+              ? uniqueStates.map((state) => `${prefix}:finished:${state}`)
+              : uniqueStates.map((state) => `${prefix}:terminal:${name}:${state}`)
+            residual = { queue, metadata }
+          } else if (orderBy === "runAt") {
+            const onlyDelayed = states !== undefined && states.length > 0 &&
+              states.every((state) => state === "delayed")
+            if (queue === undefined || !onlyDelayed) {
+              return yield* Effect.die(
+                new JobStore.ListOrderUnsupportedError({
+                  orderBy,
+                  message: "effect-mq: the Redis store serves orderBy \"runAt\" only with " +
+                    "states: [\"delayed\"] and a queue (the delayed:<queue> zset carries that order)"
+                })
+              )
+            }
+            sources = [`${prefix}:delayed:${queue}`]
+            residual = { name, metadata }
+          } else if (name !== undefined) {
+            if (!indexes.name) {
+              return yield* Effect.die(
+                new ListIndexDisabledError({
+                  index: "name",
+                  message: "effect-mq: list({ name }) routes to the byname index, " +
+                    "but RedisJobStoreOptions.indexes.name is disabled for this store"
+                })
+              )
+            }
+            sources = [`${prefix}:byname:${name}`]
+            residual = { queue, states, metadata }
+          } else if (queue !== undefined) {
+            if (!indexes.queue) {
+              return yield* Effect.die(
+                new ListIndexDisabledError({
+                  index: "queue",
+                  message: "effect-mq: list({ queue }) routes to the byqueue index, " +
+                    "but RedisJobStoreOptions.indexes.queue is disabled for this store"
+                })
+              )
+            }
+            sources = [`${prefix}:byqueue:${queue}`]
+            residual = { states, metadata }
+          } else {
+            sources = [`${prefix}:all`]
+            residual = { states, metadata }
           }
           const reply: { items: ReadonlyArray<ReadonlyArray<string>> | Record<string, never>; more: boolean } = JSON
             .parse(
-              yield* evalList(prefix, JSON.stringify(filters), listOptions.cursor ?? "", limit)
+              yield* evalList(
+                prefix,
+                JSON.stringify(sources),
+                order,
+                JSON.stringify(residual),
+                listOptions.cursor ?? "",
+                limit
+              ).pipe(Effect.mapError(storeError("list failed")))
             )
           const items = asArray(reply.items).map((flat) => toRecord(foldPairs(flat)))
           const last = items[items.length - 1]
+          // The cursor value is the order field, which equals the routed
+          // zset's score for every row the script returned.
+          const orderValue = last === undefined
+            ? 0
+            : orderBy === "enqueuedAt"
+            ? last.enqueuedAt
+            : orderBy === "runAt"
+            ? last.runAt
+            : last.finishedAt ?? 0
           const result: JobStore.ListResult = {
             items,
-            cursor: reply.more && last !== undefined ? `${last.enqueuedAt}:${last.id}` : undefined
+            cursor: reply.more && last !== undefined ? `${orderValue}:${last.id}` : undefined
           }
           return result
-        }).pipe(Effect.mapError(storeError("list failed"))),
+        }),
 
       retry: (id) =>
         Effect.gen(function*() {
@@ -800,6 +1159,7 @@ export const make = (
             request.keep === undefined ? "" : JSON.stringify(request.keep),
             request.timeoutMs === undefined ? "" : String(request.timeoutMs),
             request.trace === undefined ? "" : JSON.stringify(request.trace),
+            request.parent === undefined ? "" : JSON.stringify(request.parent),
             Math.max(0, request.delayMs),
             now
           )) === "1"
@@ -817,6 +1177,147 @@ export const make = (
         evalAdvanceSchedule(prefix, key, expectedRunAt, nextRunAt).pipe(
           Effect.mapError(storeError("advanceSchedule failed")),
           Effect.asVoid
+        ),
+
+      recordChildResults: (reports) =>
+        Effect.gen(function*() {
+          if (reports.length === 0) {
+            const none: ReadonlyArray<{ applied: boolean; parentSettled: boolean }> = []
+            return none
+          }
+          const now = yield* Clock.currentTimeMillis
+          const all: Array<{ applied: boolean; parentSettled: boolean }> = []
+          // One atomic batch per chunk of 500 (ARGV headroom); the
+          // contract's per-batch settle semantics then apply per chunk.
+          for (let start = 0; start < reports.length; start += 500) {
+            const chunk = reports.slice(start, start + 500)
+            const items: Array<string> = []
+            for (const report of chunk) {
+              items.push(
+                report.flowId,
+                report.childKey,
+                report.outcome,
+                report.exit === undefined ? "" : JSON.stringify(report.exit),
+                report.failedReason ?? ""
+              )
+            }
+            const reply: {
+              results: ReadonlyArray<{ applied: boolean; parentSettled: boolean }>
+              wakes: ReadonlyArray<string> | Record<string, never>
+            } = JSON.parse(yield* evalRecordChildResults(prefix, now, chunk.length, items))
+            for (const queue of asArray(reply.wakes)) {
+              // A parent settled to runnable collect: wake its queue.
+              yield* wakeUp(JobStore.QueueName(queue))
+            }
+            for (const result of reply.results) {
+              all.push(result)
+            }
+          }
+          return all
+        }).pipe(Effect.mapError(storeError("recordChildResults failed"))),
+
+      peekOutbox: (peekOptions) =>
+        Effect.gen(function*() {
+          const limit = Math.floor(peekOptions.limit)
+          if (limit <= 0) {
+            const none: ReadonlyArray<JobStore.OutboxEntry> = []
+            return none
+          }
+          // The `after` cursor compares by the id's embedded score (the seq
+          // prefix before the NUL), so the walk moves past the named entry
+          // whether or not it still exists. Unparseable input reads as unset.
+          let afterSeq: number | undefined = undefined
+          if (peekOptions.after !== undefined) {
+            const nul = peekOptions.after.indexOf("\u0000")
+            const seq = nul > 0 ? Number(peekOptions.after.slice(0, nul)) : Number.NaN
+            if (Number.isFinite(seq)) afterSeq = seq
+          }
+          const raw = afterSeq === undefined
+            ? yield* redis.send("ZRANGE", `${prefix}:flowoutbox`, "0", String(limit - 1))
+            : yield* redis.send(
+              "ZRANGEBYSCORE",
+              `${prefix}:flowoutbox`,
+              `(${afterSeq}`,
+              "+inf",
+              "LIMIT",
+              "0",
+              String(limit)
+            )
+          // SAFETY: ZRANGE/ZRANGEBYSCORE always reply with arrays of bulk
+          // strings.
+          const members = raw as ReadonlyArray<string>
+          return members.map(toOutboxEntry)
+        }).pipe(Effect.mapError(storeError("peekOutbox failed"))),
+
+      deleteOutbox: (ids) =>
+        Effect.gen(function*() {
+          // Chunked ZREMs keep the variadic argument count bounded; each
+          // chunk is idempotent, so a partial failure just redelivers.
+          for (let start = 0; start < ids.length; start += 500) {
+            yield* redis.send("ZREM", `${prefix}:flowoutbox`, ...ids.slice(start, start + 500))
+          }
+        }).pipe(Effect.mapError(storeError("deleteOutbox failed"))),
+
+      listChildResults: (flowId, listOptions) =>
+        Effect.gen(function*() {
+          const limit = Math.max(1, listOptions?.limit ?? 1000)
+          const reply: { items: ReadonlyArray<ReadonlyArray<string>> | Record<string, never>; more: boolean } = JSON
+            .parse(
+              yield* evalListChildResults(prefix, flowId, listOptions?.cursor ?? "", limit)
+            )
+          const items = asArray(reply.items).map((row) => toChildRecord(flowId, row))
+          const last = items[items.length - 1]
+          return {
+            items,
+            cursor: reply.more && last !== undefined ? last.childKey : undefined
+          }
+        }).pipe(Effect.mapError(storeError("listChildResults failed"))),
+
+      flowSweepWork: (sweepOptions) =>
+        Effect.gen(function*() {
+          const now = yield* Clock.currentTimeMillis
+          const limit = Math.max(1, sweepOptions.limit ?? 1000)
+          const reply: {
+            reconcile:
+              | ReadonlyArray<{
+                flowId: string
+                children: ReadonlyArray<{ childKey: string; storeKey: string; spec: string }>
+              }>
+              | Record<string, never>
+            cascade:
+              | ReadonlyArray<{
+                flowId: string
+                children: ReadonlyArray<{ childKey: string; storeKey: string; childJobId: string }>
+              }>
+              | Record<string, never>
+          } = JSON.parse(yield* evalFlowSweepWork(prefix, sweepOptions.pendingAgeMs, limit, now))
+          const work: JobStore.FlowSweepWork = {
+            reconcile: asArray(reply.reconcile).map((group) => ({
+              flowId: JobStore.JobId(group.flowId),
+              children: group.children.map((child) => {
+                // The stored spec is the verbatim JSON this driver wrote at
+                // fan-out time (never routed through cjson), so it re-parses
+                // to the original EnqueueRequest.
+                const request: JobStore.EnqueueRequest = JSON.parse(child.spec)
+                return { childKey: child.childKey, storeKey: child.storeKey, request }
+              })
+            })),
+            cascade: asArray(reply.cascade).map((group) => ({
+              flowId: JobStore.JobId(group.flowId),
+              children: group.children.map((child) => ({
+                childKey: child.childKey,
+                storeKey: child.storeKey,
+                childJobId: JobStore.JobId(child.childJobId)
+              }))
+            }))
+          }
+          return work
+        }).pipe(Effect.mapError(storeError("flowSweepWork failed"))),
+
+      markChildrenCascaded: (flowId, childKeys) =>
+        evalMarkChildrenCascaded(prefix, flowId, JSON.stringify(childKeys)).pipe(
+          Effect.mapError(storeError("markChildrenCascaded failed")),
+          Effect.asVoid
         )
     }