effect-mq 0.5.0 → 0.7.0

package/dist/redis/RedisJobStore.js

@@ -12,10 +12,22 @@
  *
  * @since 0.2.0
  */
-import { Clock, Deferred, Duration, Effect, Exit, Layer, Option, Queue, Schedule } from "effect";
+import { Clock, Data, Deferred, Duration, Effect, Exit, Layer, Option, Queue, Schedule } from "effect";
 import { Redis } from "effect/unstable/persistence";
 import * as JobStore from "../JobStore.js";
 import * as scripts from "./scripts.js";
+/**
+ * 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") {
+}
+const TERMINAL_STATES = new Set(["completed", "failed", "cancelled"]);
 const storeError = (message) => (cause) => new JobStore.JobStoreError({ message, cause });
 /** Fold a Lua `HGETALL` reply (flat `[field, value, ...]`) into a map. */
 const foldPairs = (flat) => {
@@ -56,6 +68,18 @@ const toRecord = (hash) => ({
     cancelRequested: hash.get("cancelRequested") === "1",
     dedupeKey: optionalString(hash.get("dedupeKey")),
     trace: optionalJson(hash.get("trace")),
+    parent: optionalJson(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")),
@@ -82,14 +106,57 @@ const toSchedule = (hash) => ({
 });
 // cjson encodes an empty Lua table as {}, not [] — normalize.
 const asArray = (value) => 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) => {
+    const sep = member.indexOf("\u0000");
+    const body = 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 = [
     "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, row) => ({
+    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"),
+    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).
@@ -100,28 +167,105 @@ export const make = (options) => Effect.gen(function* () {
     const redis = yield* Redis.Redis;
     const prefix = options?.prefix ?? "effect-mq";
     const wakeChannel = `${prefix}:wake`;
-    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 indexOptions = options?.indexes;
+    const indexes = 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(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"]) {
+            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));
+            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;
+                    cursor = next;
+                    const ids = [];
+                    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
     // cross-process wake-ups — the message names the queue ("*" broadcasts).
@@ -196,7 +340,46 @@ export const make = (options) => Effect.gen(function* () {
         const raw = generate(request);
         return Effect.isEffect(raw) ? raw : Effect.succeed(raw);
     });
-    const enqueueOnce = (request, idMode, id, now) => evalEnqueue(prefix, idMode, id, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), request.priority, request.attemptsMax, request.backoff === undefined ? "" : JSON.stringify(request.backoff), request.keep === undefined ? "" : JSON.stringify(request.keep), request.timeoutMs === undefined ? "" : String(request.timeoutMs), Math.max(0, request.delayMs), now, request.dedupe?.key ?? "", 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));
+    const enqueueOnce = (request, idMode, id, now) => evalEnqueue(prefix, idMode, id, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), request.priority, request.attemptsMax, request.backoff === undefined ? "" : JSON.stringify(request.backoff), request.keep === undefined ? "" : JSON.stringify(request.keep), request.timeoutMs === undefined ? "" : String(request.timeoutMs), Math.max(0, request.delayMs), now, request.dedupe?.key ?? "", 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.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, token, failFast, children) => 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 = [];
+        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 = [];
+            for (const child of chunk) {
+                items.push(child.childKey, child.storeKey, child.request.id ?? "", child.request.name, JSON.stringify(child.request));
+            }
+            const reply = 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) => Effect.gen(function* () {
         const now = yield* Clock.currentTimeMillis;
@@ -263,7 +446,7 @@ export const make = (options) => Effect.gen(function* () {
                         : generate !== undefined
                             ? yield* generateCandidate(request, generate)
                             : "";
-                    itemArgs.push(mode, candidate, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), String(request.priority), String(request.attemptsMax), request.backoff === undefined ? "" : JSON.stringify(request.backoff), request.keep === undefined ? "" : JSON.stringify(request.keep), request.timeoutMs === undefined ? "" : String(request.timeoutMs), request.trace === undefined ? "" : JSON.stringify(request.trace), String(Math.max(0, request.delayMs)));
+                    itemArgs.push(mode, candidate, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), String(request.priority), String(request.attemptsMax), request.backoff === undefined ? "" : JSON.stringify(request.backoff), 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)));
                 }
                 const replies = JSON
                     .parse(yield* evalEnqueueMany(prefix, now, chunk.length, itemArgs));
@@ -370,21 +553,28 @@ export const make = (options) => Effect.gen(function* () {
                 return empty;
             });
         }).pipe(Effect.mapError(storeError("claim failed"))),
-        ack: (id, token, outcome) => Effect.gen(function* () {
-            const now = yield* Clock.currentTimeMillis;
-            const exitJson = outcome._tag === "Cancelled" || outcome.exit === undefined
-                ? ""
-                : JSON.stringify(outcome.exit);
-            const delayMs = outcome._tag === "Retry" ? Math.max(0, outcome.delayMs) : 0;
-            const reply = JSON.parse(yield* evalAck(prefix, id, token, outcome._tag, exitJson, delayMs, now).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);
+        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 = settled._tag === "Cancelled" || settled.exit === undefined
+                    ? ""
+                    : JSON.stringify(settled.exit);
+                const delayMs = settled._tag === "Retry" ? Math.max(0, settled.delayMs) : 0;
+                const reply = JSON.parse(yield* evalAck(prefix, id, token, settled._tag, exitJson, delayMs, now).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);
+                }
+            });
+        },
         release: (id, token) => Effect.gen(function* () {
             const now = yield* Clock.currentTimeMillis;
             const reply = JSON.parse(yield* evalRelease(prefix, id, token, now).pipe(Effect.mapError(storeError("release failed"))));
@@ -448,22 +638,89 @@ export const make = (options) => Effect.gen(function* () {
         })),
         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;
+            let residual;
+            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 = JSON
-                .parse(yield* evalList(prefix, JSON.stringify(filters), listOptions.cursor ?? "", limit));
+                .parse(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 = {
                 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* () {
             const now = yield* Clock.currentTimeMillis;
             const reply = JSON.parse(yield* evalRetry(prefix, id, now).pipe(Effect.mapError(storeError("retry failed"))));
@@ -537,13 +794,108 @@ export const make = (options) => Effect.gen(function* () {
                 });
             }
             const now = yield* Clock.currentTimeMillis;
-            const fired = (yield* evalTickSchedule(prefix, key, expectedRunAt, nextRunAt, request.id, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), request.priority, request.attemptsMax, request.backoff === undefined ? "" : JSON.stringify(request.backoff), request.keep === undefined ? "" : JSON.stringify(request.keep), request.timeoutMs === undefined ? "" : String(request.timeoutMs), request.trace === undefined ? "" : JSON.stringify(request.trace), Math.max(0, request.delayMs), now)) === "1";
+            const fired = (yield* evalTickSchedule(prefix, key, expectedRunAt, nextRunAt, request.id, request.name, request.queue, JSON.stringify(request.payload ?? null), JSON.stringify(request.metadata), request.priority, request.attemptsMax, request.backoff === undefined ? "" : JSON.stringify(request.backoff), 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";
             if (fired) {
                 yield* wakeUp(request.queue);
             }
             return fired;
         }).pipe(Effect.mapError((error) => error instanceof JobStore.JobStoreError ? error : storeError("tickSchedule failed")(error))),
-        advanceSchedule: (key, expectedRunAt, nextRunAt) => evalAdvanceSchedule(prefix, key, expectedRunAt, nextRunAt).pipe(Effect.mapError(storeError("advanceSchedule failed")), Effect.asVoid)
+        advanceSchedule: (key, expectedRunAt, nextRunAt) => evalAdvanceSchedule(prefix, key, expectedRunAt, nextRunAt).pipe(Effect.mapError(storeError("advanceSchedule failed")), Effect.asVoid),
+        recordChildResults: (reports) => Effect.gen(function* () {
+            if (reports.length === 0) {
+                const none = [];
+                return none;
+            }
+            const now = yield* Clock.currentTimeMillis;
+            const all = [];
+            // 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 = [];
+                for (const report of chunk) {
+                    items.push(report.flowId, report.childKey, report.outcome, report.exit === undefined ? "" : JSON.stringify(report.exit), report.failedReason ?? "");
+                }
+                const reply = 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 = [];
+                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 = 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;
+            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 = 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 = JSON.parse(yield* evalFlowSweepWork(prefix, sweepOptions.pendingAgeMs, limit, now));
+            const work = {
+                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 = 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)
     };
     return store;
 });