@ultimat3/notify 12.0.0

package/src/digest.ts

@@ -0,0 +1,100 @@
+// The digest window: N events for one recipient over one channel, coalesced into one delivery.
+//
+// A ROLLING window measured in milliseconds from the first event, and deliberately not a calendar
+// one. "Every day at 09:00" needs an IANA zone per recipient and a cron, which is `task()` plus the
+// app's own schedule — and this repo's rule is that no date is computed without an explicit zone,
+// so a window this package could get wrong is a window it does not offer. `windowMs` needs no zone
+// because it does no calendar arithmetic at all.
+
+import type { NotifyEvent } from './notification';
+
+/** One coalescing bucket's identity. */
+export interface DigestSlot {
+  readonly recipient: string;
+  readonly notifier: string;
+  readonly channel: string;
+  /**
+   * What the window groups BY, within the slot. Defaults to the notifier's name, so every
+   * `post.commented` for one person coalesces; an app that wants one digest per thread returns
+   * the thread id. The taxonomy that names those groups is the app's, exactly as with preferences.
+   */
+  readonly group: string;
+}
+
+export interface DigestAppend {
+  readonly slot: DigestSlot;
+  readonly event: NotifyEvent<unknown>;
+  readonly windowMs: number;
+  readonly now: Date;
+}
+
+export interface DigestBucket {
+  /**
+   * True when THIS append opened the window. Exactly one caller gets it per window, and that
+   * caller owns the flush — which is what stops N concurrent runs each scheduling their own.
+   */
+  readonly opened: boolean;
+  /** Epoch ms the window closes at. */
+  readonly endsAt: number;
+}
+
+export interface DigestStore {
+  append(input: DigestAppend): Promise<DigestBucket>;
+  /**
+   * Everything the window collected, oldest first, and the bucket is closed.
+   *
+   * THE ONE AT-MOST-ONCE SEAM IN THIS PACKAGE, stated rather than hidden: a process killed between
+   * this call and the send loses that batch, because the events are no longer anywhere to replay
+   * from. The fan-out narrows it by checkpointing the drained batch in its own `step.run` before
+   * the send — an ordinary retry replays from that checkpoint — and a durable implementation can
+   * close it entirely by flipping a row's status here and deleting on `settle`. The memory store
+   * below cannot.
+   */
+  drain(slot: DigestSlot): Promise<readonly NotifyEvent<unknown>[]>;
+}
+
+const slotKey = (slot: DigestSlot): string =>
+  JSON.stringify([slot.recipient, slot.notifier, slot.channel, slot.group]);
+
+interface OpenBucket {
+  endsAt: number;
+  readonly events: NotifyEvent<unknown>[];
+}
+
+export interface MemoryDigestStore extends DigestStore {
+  readonly open: number;
+  clear(): void;
+}
+
+export function createMemoryDigestStore(): MemoryDigestStore {
+  const buckets = new Map<string, OpenBucket>();
+  return {
+    get open(): number {
+      return buckets.size;
+    },
+    append(input) {
+      const id = slotKey(input.slot);
+      const at = input.now.getTime();
+      const existing = buckets.get(id);
+      // A bucket whose window has already elapsed is not a bucket to append to: its owner is gone
+      // (a crashed flush) and the event would sit there until an unrelated third event arrived.
+      // Re-opening is the repair, and it costs one extra delivery rather than a lost one.
+      if (existing !== undefined && existing.endsAt > at) {
+        existing.events.push(input.event);
+        return Promise.resolve({ opened: false, endsAt: existing.endsAt });
+      }
+      const endsAt = at + input.windowMs;
+      buckets.set(id, { endsAt, events: [input.event] });
+      return Promise.resolve({ opened: true, endsAt });
+    },
+    drain(slot) {
+      const id = slotKey(slot);
+      const bucket = buckets.get(id);
+      buckets.delete(id);
+      return Promise.resolve(bucket?.events ?? []);
+    },
+    clear() {
+      buckets.clear();
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,183 @@
+// The X_* codes owned by @ultimat3/notify. Each names the exact change that resolves it.
+//
+// No `docs:` line, and that is deliberate: `UltimateError`'s constructor resolves the registered
+// descriptor, whose default is `ERROR_DOCS_URL` in @ultimat3/core. A URL written out here is a
+// second answer to a question core already answers, and the last one went stale host and all.
+import {
+  registerErrorCodes,
+  registerErrorRetry,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
+
+export const NOTIFY_ERROR_CODES = [
+  'X_NOTIFY_CHANNELS_EMPTY',
+  'X_NOTIFY_CHANNEL_DUPLICATE',
+  'X_NOTIFY_FANOUT_TOO_WIDE',
+  'X_NOTIFY_STORE_MISSING',
+  'X_NOTIFY_DELIVERY_FAILED',
+  'X_NOTIFY_DIGEST_UNSUPPORTED',
+] as const;
+
+export type NotifyErrorCode = (typeof NOTIFY_ERROR_CODES)[number];
+
+export const NOTIFY_ERROR_TITLES: Readonly<Record<NotifyErrorCode, string>> = {
+  X_NOTIFY_CHANNELS_EMPTY: 'the notifier declares no channels',
+  X_NOTIFY_CHANNEL_DUPLICATE: 'two deliveries share one channel name',
+  X_NOTIFY_FANOUT_TOO_WIDE: 'the audience is larger than one run may fan out to',
+  X_NOTIFY_STORE_MISSING: 'a channel needs a store nothing installed',
+  X_NOTIFY_DELIVERY_FAILED: 'a channel did not accept the delivery',
+  X_NOTIFY_DIGEST_UNSUPPORTED: 'a digest window is declared on a bulk channel',
+};
+
+// One unconditional call, so a second package claiming one of notify's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(NOTIFY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+/**
+ * The codes of this package's that can be thrown INSIDE a notifier's run, classified.
+ * `executeJob` reads this through `nextRetryForError`, which short-circuits on `terminal` and on
+ * NOTHING else — so an unclassified code falls through to the attempt count and spends the whole
+ * policy re-proving an answer that cannot change. `classifyThrown` reads an unregistered code as
+ * unclassified even when its instance carries `terminal`, which is why this has to be explicit
+ * rather than left to `DEFAULT_ERROR_RETRY`.
+ *
+ * Both terminal ones were live defects until 2026-08-24: an audience of 900 against
+ * `maxRecipients: 500` re-resolved the audience and re-counted it once per attempt, and a missing
+ * inbox store dead-lettered five attempts later than it knew the answer.
+ *
+ * THE THREE DECLARATION-TIME CODES ARE DELIBERATELY ABSENT, and that is the audit rather than an
+ * omission. `X_NOTIFY_CHANNELS_EMPTY`, `X_NOTIFY_CHANNEL_DUPLICATE` and
+ * `X_NOTIFY_DIGEST_UNSUPPORTED` are all thrown by `resolve()` inside `notifier()`, which runs at
+ * module load — the worker is not running, `classifyThrown` is never reached, and a row for them
+ * would be a claim nothing reads. `errors.test.ts` pins the split both ways, so a code that moves
+ * from one side to the other fails a test rather than going quiet.
+ */
+registerErrorRetry({
+  // The audience is what it is. Retrying counts it again and refuses again — and each attempt
+  // re-runs `recipientsFor`, so the policy is spent on repeated work as well as repeated time.
+  X_NOTIFY_FANOUT_TOO_WIDE: 'terminal',
+  // A store is installed at boot or it is not. No attempt of a running worker installs one.
+  X_NOTIFY_STORE_MISSING: 'terminal',
+  // The one a retry can fix: a provider blip, a timeout, a 503. It read correctly before this
+  // block existed only because `unclassified` happens to fall through to the attempt count —
+  // declaring it is what makes that an answer rather than a coincidence, and what stops a later
+  // sweep through this file from making the whole package terminal.
+  X_NOTIFY_DELIVERY_FAILED: 'retryable',
+});
+
+/** Refused where it is written: a notifier with no channel is a job that fans out to nobody. */
+export class NotifyChannelsEmptyError extends UltimateError {
+  constructor(input: { notifier: string }) {
+    super({
+      code: 'X_NOTIFY_CHANNELS_EMPTY',
+      cause: `notifier "${input.notifier}" declares no channels, so every run resolves recipients and delivers nothing`,
+      fix: `add at least one entry to deliver: [] on notifier("${input.notifier}") — inAppChannel() is the one with no external driver`,
+      meta: { notifier: input.notifier },
+    });
+  }
+}
+
+/**
+ * Two deliveries on one notifier naming the same channel. Refused because the ledger's unique key
+ * is `(notifier, key, channel, coalesce(recipient, ''))` (`ledger-pg.ts`, and `SQL_NOTIFY_CLAIM`'s
+ * `on conflict` spells the same expression): the second delivery would claim a row the first
+ * already owns and be dropped as a duplicate, so one of the two would silently never send.
+ *
+ * The `coalesce` is the load-bearing half and is not a detail. A bulk delivery claims with a NULL
+ * recipient, and NULLs are DISTINCT in a plain unique index — so without it a bulk claim would be
+ * claimable without bound and every replay would re-send the whole audience. Stating the key
+ * without it is what invites the "simplification" that puts the bug back.
+ */
+export class NotifyChannelDuplicateError extends UltimateError {
+  constructor(input: { notifier: string; channel: string }) {
+    super({
+      code: 'X_NOTIFY_CHANNEL_DUPLICATE',
+      cause: `notifier "${input.notifier}" declares the channel "${input.channel}" twice, and the delivery ledger keys on it — the second would be deduped away`,
+      fix: `give the second channel its own name on notifier("${input.notifier}") — channel('${input.channel}-digest', …) — or merge the two deliver entries`,
+      meta: { notifier: input.notifier, channel: input.channel },
+    });
+  }
+}
+
+/**
+ * One step per recipient is what makes a provider blip re-send one address rather than all of
+ * them, and a step is a durable row — so the fan-out has a width past which it is the wrong shape
+ * entirely. Refused with a number rather than degraded silently.
+ */
+export class NotifyFanoutTooWideError extends UltimateError {
+  constructor(input: { notifier: string; recipients: number; max: number }) {
+    super({
+      code: 'X_NOTIFY_FANOUT_TOO_WIDE',
+      cause: `notifier "${input.notifier}" resolved ${String(input.recipients)} recipients and the per-run ceiling is ${String(input.max)} — each one is a durable step row`,
+      fix: `deliver through a bulkChannel() on notifier("${input.notifier}"), which sends one payload for every recipient, or page the audience with backfill() from @ultimat3/jobs`,
+      meta: { notifier: input.notifier, recipients: input.recipients, max: input.max },
+    });
+  }
+}
+
+/**
+ * A channel or a window asked for a store nothing installed.
+ *
+ * The delivery ledger is deliberately NOT one of these: it has a correct-for-one-process default
+ * (`createMemoryDeliveryLedger`), the way every other driver seam in this framework does. An inbox
+ * and a digest window have no such default — there is nowhere to put the row — so they refuse.
+ */
+export class NotifyStoreMissingError extends UltimateError {
+  constructor(input: { notifier: string; store: 'inbox' | 'digest' }) {
+    const what =
+      input.store === 'inbox' ? 'a channel that writes the in-app inbox' : 'a digest window';
+    const install =
+      input.store === 'inbox'
+        ? 'createMemoryInboxStore() }) at boot, or createPgInboxStore({ executor }) to share it across replicas'
+        : 'createMemoryDigestStore() }) at boot';
+    super({
+      code: 'X_NOTIFY_STORE_MISSING',
+      cause: `notifier "${input.notifier}" delivers through ${what} and no ${input.store} store is installed, so the rows have nowhere to go`,
+      fix: `call setNotifyStores({ ${input.store}: ${install}`,
+      meta: { notifier: input.notifier, store: input.store },
+    });
+  }
+}
+
+/**
+ * A digest window declared on a bulk channel. Refused where it is written: a bulk send has one
+ * payload for the whole audience and a window coalesces PER RECIPIENT, so the two have no shared
+ * meaning — and inventing one would be this package deciding whose events get grouped.
+ */
+export class NotifyDigestUnsupportedError extends UltimateError {
+  constructor(input: { notifier: string; channel: string }) {
+    super({
+      code: 'X_NOTIFY_DIGEST_UNSUPPORTED',
+      cause: `notifier "${input.notifier}" declares a digest window on the bulk channel "${input.channel}", and a window coalesces per recipient where a bulk send has none`,
+      fix: `drop digest from the "${input.channel}" entry on notifier("${input.notifier}") and give it a wait instead, or deliver it through channel('${input.channel}', …) one recipient at a time`,
+      meta: { notifier: input.notifier, channel: input.channel },
+    });
+  }
+}
+
+/**
+ * A channel's `deliver` threw. Wrapped rather than rethrown so the dead-letter row carries a
+ * stable code and names the channel — a raw provider error names only itself.
+ *
+ * `renderThrowable` and never `${cause}`: a caught value is annotated by nobody, and a provider
+ * rejection is routinely an object whose `toString` throws (`bun run scripts/catch-render.ts`).
+ */
+export class NotifyDeliveryFailedError extends UltimateError {
+  constructor(input: { notifier: string; channel: string; recipients: number; cause: unknown }) {
+    super({
+      code: 'X_NOTIFY_DELIVERY_FAILED',
+      cause: `channel "${input.channel}" of notifier "${input.notifier}" failed for ${String(input.recipients)} recipient(s): ${renderThrowable(input.cause)}`,
+      // `x jobs ls` first, and never `x jobs show` handed a notifier NAME: that command takes a job id
+      // positional and resolves it through `inspectJob`, which answers `X_JOB_UNKNOWN` for
+      // anything else — so a notifier NAME made the one command this refusal printed fail every
+      // time it was run. A `fix:` that fails is worse than none, because the reader spends their
+      // trust on it before finding out. The two-step shape is what `wiki/Error-Codes.md` already
+      // documents for this code.
+      fix: `x jobs ls --json   # find the run, then: x jobs show <id> --json — the failing step is deliver:${input.channel}`,
+      meta: { notifier: input.notifier, channel: input.channel },
+    });
+  }
+}

package/src/fanout-digest.ts

@@ -0,0 +1,113 @@
+// The digest branch of the fan-out: append every allowed recipient's event to its window, and let
+// whichever run OPENED a window own the flush.
+//
+// Exactly one run opens a given window, so exactly one sleeps on it — which is what stops fifty
+// events in one hour from scheduling fifty flushes of the same digest.
+
+import { attemptDelivery } from './attempt';
+import type { NotifyChannel } from './channel';
+import type { DigestSlot } from './digest';
+import type { Walk } from './fanout-walk';
+import type { NotifyEvent, Recipient } from './notification';
+import type { ResolvedDelivery } from './plan';
+import { notifyStores, requireDigest } from './stores';
+
+export interface DigestFlush<Params> {
+  readonly walk: Walk<Params>;
+  readonly channel: NotifyChannel<Params>;
+  readonly delivery: ResolvedDelivery<Params>;
+  readonly allowed: readonly Recipient[];
+}
+
+export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<void> {
+  const { walk, channel, delivery, allowed } = input;
+  const { plan, event, ctx, step, tally } = walk;
+  const windowMs = delivery.digestMs ?? 0;
+  const digest = requireDigest(plan.name);
+  const group = delivery.group?.(event) ?? plan.name;
+  const slotFor = (recipient: string): DigestSlot => ({
+    recipient,
+    notifier: plan.name,
+    channel: channel.name,
+    group,
+  });
+
+  // One step for the whole append pass: appending is what a replayed attempt must NOT redo, or the
+  // same event lands in the digest twice.
+  const opened = await step.run(`digest:${channel.name}`, async () => {
+    const owned: string[] = [];
+    let endsAt = 0;
+    for (const recipient of allowed) {
+      const bucket = await digest.append({
+        slot: slotFor(recipient.id),
+        event,
+        windowMs,
+        now: ctx.now(),
+      });
+      if (!bucket.opened) continue;
+      owned.push(recipient.id);
+      endsAt = Math.max(endsAt, bucket.endsAt);
+    }
+    return { owned, endsAt };
+  });
+
+  tally.digested += allowed.length - opened.owned.length;
+  if (opened.owned.length === 0) return;
+
+  const remaining = opened.endsAt - ctx.now().getTime();
+  if (remaining > 0) await step.sleep(`digest-wait:${channel.name}`, remaining);
+
+  const byId = new Map(allowed.map((recipient) => [recipient.id, recipient]));
+  for (const id of opened.owned) {
+    const recipient = byId.get(id);
+    if (recipient === undefined) continue;
+    // Drain and send are TWO steps on purpose. The drain's result is checkpointed, so an ordinary
+    // retry of the send replays the batch from the step store rather than from a window that is
+    // now empty. What it does not close is a process killed between the drain and its checkpoint;
+    // `DigestStore.drain` says so in its own words, and a durable store can do better.
+    const batch = await step.run(`digest-drain:${channel.name}:${id}`, () =>
+      digest.drain(slotFor(id)),
+    );
+    if (batch.length === 0) continue;
+    const events = rehydrate<Params>(batch);
+    const newest = events[events.length - 1] ?? event;
+    const sent = await step.run(`digest-send:${channel.name}:${id}`, (signal) =>
+      attemptDelivery(
+        {
+          ledger: notifyStores().ledger,
+          // The window, not the event: a digest is one delivery for many events, so its ledger
+          // identity is the slot plus the window it closed. Two different windows for the same
+          // recipient are two deliveries and must not dedupe into one.
+          claim: {
+            notifier: plan.name,
+            key: `digest:${group}:${String(opened.endsAt)}`,
+            recipient: id,
+            channel: channel.name,
+          },
+          notifier: plan.name,
+          channel: channel.name,
+          recipients: 1,
+          ctx,
+          send: (abort) =>
+            channel.deliver({ ctx, recipient, event: newest, batch: events, signal: abort }),
+        },
+        signal,
+      ),
+    );
+    if (sent) tally.delivered += 1;
+    else tally.replayed += 1;
+  }
+}
+
+/**
+ * A step's return value round-trips through JSON, so a replayed batch arrives with `at` as an ISO
+ * string that the type still calls a `Date`. Rebuilt here rather than trusted — a channel that
+ * formats it would throw on `at.getTime` only on the replay path, which is the path nothing tests.
+ *
+ * The cast is the digest store's untyped edge: it holds `NotifyEvent<unknown>` because one store
+ * serves every notifier, and what comes out of a slot is exactly what this notifier put in.
+ */
+const rehydrate = <Params>(
+  batch: readonly NotifyEvent<unknown>[],
+): readonly NotifyEvent<Params>[] =>
+  batch.map((entry) => ({ ...entry, at: new Date(entry.at) })) as readonly NotifyEvent<Params>[];

package/src/fanout-walk.ts

@@ -0,0 +1,33 @@
+// The state one fan-out run carries, in its own module so `fanout.ts` and `fanout-digest.ts` can
+// both name it without importing each other. Nothing here decides anything — it is the shape the
+// two halves of the walk agree on.
+
+import type { Ctx } from '@ultimat3/core';
+import type { StepApi } from '@ultimat3/jobs';
+import type { NotifyEvent, Recipient } from './notification';
+import type { NotifyPlan } from './plan';
+
+/** Mutated in place by every branch, so one run has one set of counters rather than a merge. */
+export interface Tally {
+  delivered: number;
+  suppressed: number;
+  skipped: number;
+  replayed: number;
+  digested: number;
+}
+
+export interface Walk<Params> {
+  readonly plan: NotifyPlan<Params>;
+  readonly event: NotifyEvent<Params>;
+  readonly audience: readonly Recipient[];
+  readonly ctx: Ctx;
+  readonly step: StepApi;
+  readonly tally: Tally;
+}
+
+/** A computed `tally[flag ? 'a' : 'b']` is a dynamic property write on a shipped object, which is
+ * the shape `bun run proto-index` exists to keep out of this tree. Two named fields instead. */
+export const countSend = (tally: Tally, sent: boolean): void => {
+  if (sent) tally.delivered += 1;
+  else tally.replayed += 1;
+};

package/src/fanout.ts

@@ -0,0 +1,173 @@
+// The run body every notifier's job executes: resolve the audience once, then walk the channels in
+// wait order, gating and delivering each.
+//
+// ONE job for the whole fan-out, where `noticed` enqueues a job per (recipient × channel). The
+// reason is `step`: a step IS the retry unit here, so a provider blip on recipient 40 of 50 re-sends
+// recipient 40 and replays the other 39 from the step store in microseconds — the same guarantee a
+// job-per-recipient buys, without N queue rows, N idempotency keys and N manifest entries.
+
+import type { JobRunArgs } from '@ultimat3/jobs';
+import { attemptDelivery } from './attempt';
+import type { NotifyChannel } from './channel';
+import { isBulkChannel } from './channel';
+import { NotifyFanoutTooWideError } from './errors';
+import { flushDigest } from './fanout-digest';
+import type { Tally, Walk } from './fanout-walk';
+import { countSend } from './fanout-walk';
+import type { NotifyEvent, Recipient } from './notification';
+import type { NotifyPayload, NotifyPlan, NotifyReport, ResolvedDelivery } from './plan';
+import { notifyStores } from './stores';
+
+export async function runFanout<Params>(
+  plan: NotifyPlan<Params>,
+  args: JobRunArgs<NotifyPayload<Params>>,
+): Promise<NotifyReport> {
+  const { input, step, ctx } = args;
+  // One step for BOTH facts, because both must survive a replay: a re-resolved audience would
+  // deliver to whoever subscribed during the wait, and a re-read clock would write a different
+  // `at` into the inbox on every attempt. Epoch ms rather than a `Date` — a step's return value
+  // round-trips through JSON, and a `Date` comes back a string.
+  const open = await step.run('open', async () => ({
+    at: ctx.now().getTime(),
+    recipients: input.recipients ?? [...(await plan.recipientsFor({ input: input.params, ctx }))],
+  }));
+  const audience = open.recipients;
+  if (audience.length > plan.maxRecipients) {
+    throw new NotifyFanoutTooWideError({
+      notifier: plan.name,
+      recipients: audience.length,
+      max: plan.maxRecipients,
+    });
+  }
+
+  const event: NotifyEvent<Params> = {
+    notifier: plan.name,
+    key: plan.keyFor(input.params),
+    params: input.params,
+    at: new Date(open.at),
+  };
+  const tally: Tally = { delivered: 0, suppressed: 0, skipped: 0, replayed: 0, digested: 0 };
+  const walk: Walk<Params> = { plan, event, audience, ctx, step, tally };
+
+  // `deliveries` is sorted by `waitMs`, so this sleeps the DELTA and never the sum: an in-app
+  // channel with no wait fires now even when the email beside it waits an hour.
+  let slept = 0;
+  for (const delivery of plan.deliveries) {
+    if (delivery.waitMs > slept) {
+      await step.sleep(`wait:${delivery.channel.name}`, delivery.waitMs - slept);
+      slept = delivery.waitMs;
+    }
+    await deliverOne(walk, delivery);
+  }
+  return { recipients: audience.length, ...tally };
+}
+
+async function deliverOne<Params>(
+  walk: Walk<Params>,
+  delivery: ResolvedDelivery<Params>,
+): Promise<void> {
+  const { event, ctx, tally } = walk;
+  // AFTER the sleep above, which is `noticed`'s documented order and the half most hand-rolled
+  // versions get wrong: a five-minute delay whose condition went false in minute three must send
+  // nothing. Evaluating before the wait would decide on a world that no longer exists.
+  if (delivery.when !== undefined && !(await delivery.when({ event, ctx }))) {
+    tally.skipped += walk.audience.length;
+    return;
+  }
+  if (delivery.unless !== undefined && (await delivery.unless({ event, ctx }))) {
+    tally.skipped += walk.audience.length;
+    return;
+  }
+
+  const allowed = await allowedBy(walk, delivery.channel.name);
+  if (allowed.length === 0) return;
+
+  const channel = delivery.channel;
+  if (delivery.digestMs !== undefined) {
+    // `notifier()` refused a digest on a bulk channel at declaration, so this narrowing cannot
+    // fail at run time — it is here because the type system cannot read that refusal.
+    if (isBulkChannel(channel)) return;
+    await flushDigest({ walk, channel: channel as NotifyChannel<Params>, delivery, allowed });
+    return;
+  }
+  if (isBulkChannel(channel)) {
+    const claim = {
+      notifier: walk.plan.name,
+      key: event.key,
+      // ONE row for the audience: a bulk send is one thing, and half of it is not a state this
+      // package can represent.
+      recipient: null,
+      channel: channel.name,
+    };
+    const sent = await walk.step.run(`deliver:${channel.name}`, (signal) =>
+      attemptDelivery(
+        {
+          ledger: notifyStores().ledger,
+          claim,
+          notifier: walk.plan.name,
+          channel: channel.name,
+          recipients: allowed.length,
+          ctx,
+          send: (abort) =>
+            channel.deliver({ ctx, recipients: allowed, event, batch: [event], signal: abort }),
+        },
+        signal,
+      ),
+    );
+    countSend(tally, sent);
+    return;
+  }
+
+  for (const recipient of allowed) {
+    const claim = {
+      notifier: walk.plan.name,
+      key: event.key,
+      recipient: recipient.id,
+      channel: channel.name,
+    };
+    // The recipient's id names the step because the id survives a replay and a loop index does
+    // not — a step name is the replay key (X_STEP_DUPLICATE).
+    const sent = await walk.step.run(`deliver:${channel.name}:${recipient.id}`, (signal) =>
+      attemptDelivery(
+        {
+          ledger: notifyStores().ledger,
+          claim,
+          notifier: walk.plan.name,
+          channel: channel.name,
+          recipients: 1,
+          ctx,
+          send: (abort) =>
+            channel.deliver({ ctx, recipient, event, batch: [event], signal: abort }),
+        },
+        signal,
+      ),
+    );
+    countSend(tally, sent);
+  }
+}
+
+/**
+ * The preference gate, per recipient and per channel — deliberately NOT inside a durable step. It
+ * is a read, so replaying it costs a query rather than a row, and re-asking on a retry is the more
+ * correct answer anyway: somebody who opted out during a five-minute `wait` should not receive the
+ * mail the first attempt had already decided to send.
+ */
+async function allowedBy<Params>(
+  walk: Walk<Params>,
+  channel: string,
+): Promise<readonly Recipient[]> {
+  const { preferences } = notifyStores();
+  const allowed: Recipient[] = [];
+  for (const recipient of walk.audience) {
+    const ok = await preferences.allows({
+      recipient,
+      notifier: walk.plan.name,
+      channel,
+      event: walk.event,
+      ctx: walk.ctx,
+    });
+    if (ok) allowed.push(recipient);
+    else walk.tally.suppressed += 1;
+  }
+  return allowed;
+}