@ultimat3/notify 12.0.0

package/CLAUDE.md

@@ -0,0 +1,93 @@
+# @ultimat3/notify — boundary
+
+Tier 4. May import tiers 0-3. Never sideways, never upward.
+
+**Its real imports are `core`, `schema` (tier 0), `time` (tier 1) and `jobs` (tier 3), so tier 4 is
+its floor** — one above the highest tier it reaches. It sits AT that floor, so it has no
+`FLOOR_ABOVE` row and needs none. The import that fixes it there is `@ultimat3/jobs`: `notifier()`
+returns a `job`, which is the whole design.
+
+## What it may never import, and why
+
+| Never | Because |
+|---|---|
+| `@ultimat3/mail` | Same tier (4). A `Mailer` is declared **structurally** in `channel-mail.ts` — one method, no dependency — exactly as `@ultimat3/action`'s `PgExecutor` mirrors `@ultimat3/db`. Moving `notify` to tier 5 to legalise the import would put notifications above `render`, `pwa` and `ui` for one channel's transport, and would then need a `cli → notify` edge the way `cli → scraping` does. |
+| `@ultimat3/render`, `@ultimat3/ui`, `@ultimat3/ai`, `@ultimat3/mcp`, `@ultimat3/pwa` | Same tier. A notification has no view — the inbox is rendered by the app's page out of `InboxStore.list`, which is data. |
+| `@ultimat3/db`, `@ultimat3/entity` | Legal downward, and deliberately not taken. The two tables this package owns are **DDL constants applied by the boot** (`SQL_NOTIFY_DELIVERIES_TABLE`, `SQL_NOTIFY_INBOX_TABLE`), the way `x_jobs`, `x_idempotency` and `x_audit` are — never `entity()` declarations, which would put framework tables in the app's migration graph and make an app's `x db gen` responsible for them. The Postgres stores take a structural `PgExecutor`, imported as a **type** from `@ultimat3/jobs` rather than re-declared, because a third copy of a one-method interface is a third place to look. |
+| `@ultimat3/policy` | A notification is addressed to exactly one person and the audience is `recipients`. There is no row a policy could decide about here. The **inbox read surface** is where authz belongs, and that is the app's query. |
+
+## What ships, and what must never
+
+`docs/idea/20-large-app-readiness.md` scores this row **Ship, as a job factory** — *"channel fan-out,
+preference gate, digest window, delivery ledger, in-app inbox"* — and is equally explicit about the
+other half: **the notification taxonomy and `quietHours` must never ship.**
+
+So `PreferenceStore` is an interface with two trivial implementations and nothing else. This package
+ships the **gate**; the app ships what the gate reads — which notification types exist, what a
+"marketing" one is, and what hours are quiet in which recipient's zone. `DigestWindow.window` is a
+**rolling duration** and never a calendar time, for the same reason plus one more: no date is
+computed here without an explicit IANA zone, so a window this package could get wrong is a window it
+does not offer. "Every day at 09:00 local" is a `task()` and the app's schedule.
+
+## `notifier()` is a job, not a ninth primitive
+
+A notification is durable background work with an input schema, an idempotency key, a retry policy
+and a queue — the definition of a `job`. `notifier()` therefore *returns* one, and inherits
+`.enqueue()`, `.as()`, the worker's cancellation, the dead-letter path, `x jobs show` and its
+manifest row. Its row is in `PRIMITIVE_FACTORIES` (`packages/core/src/registrar.ts`);
+`scripts/primitive-factories.test.ts` fails if the export and the row disagree.
+
+## At-least-once, in two layers
+
+A job body runs **before** its checkpoint lands, so both layers are load-bearing:
+
+1. `step.run('deliver:<channel>:<recipient>')` — an ordinary retry replays a completed send from the
+   step store and does not call the channel.
+2. `DeliveryLedger.claim` — an atomic claim keyed `(notifier, key, channel, coalesce(recipient, ''))`,
+   taken before the send and settled after it. A claim that already reads `sent` answers `false`, so
+   an attempt that lost its step history entirely still does not send twice. **The `coalesce` is
+   load-bearing, not decoration**: a bulk channel claims one row for the whole audience with a NULL
+   recipient, and NULLs are DISTINCT in a plain unique index — so without it a bulk claim is
+   claimable without bound and every replay re-sends the whole audience. `ledger-pg.ts` spells it in
+   the index and again in `SQL_NOTIFY_CLAIM`'s `on conflict`, and `errors.test.ts` pins all three
+   spellings against each other.
+
+`attempt.ts` is the only place a send happens, so there is exactly one implementation of that order.
+The **one at-most-once seam** is a digest flush: `DigestStore.drain` empties the window, and a
+process killed between the drain and its checkpoint loses that batch. It is stated in `digest.ts`
+rather than hidden, and a durable store can close it.
+
+## Files
+
+| Module | Owns |
+|---|---|
+| `notifier.ts` | the declaration, and the `job()` it builds |
+| `plan.ts` | the declaration types, and the resolved plan every duration is normalised into |
+| `fanout.ts` | the run body: audience, wait order, gates, delivery |
+| `fanout-digest.ts` · `fanout-walk.ts` | the digest branch, and the state both halves share |
+| `attempt.ts` | claim → send → settle, once |
+| `channel.ts` · `channel-in-app.ts` · `channel-mail.ts` | the seam and the two shipped channels |
+| `ledger.ts` · `ledger-pg.ts` | the delivery ledger, memory and Postgres |
+| `inbox.ts` · `inbox-pg.ts` | the in-app inbox, memory and Postgres |
+| `preferences.ts` · `digest.ts` | the gate and the window, as seams |
+| `stores.ts` | the one installer for all four |
+| `errors.ts` | this package's `X_NOTIFY_*` codes and their titles |
+
+One entry point, deliberately: every module runs on the server, so there is no browser half to split
+off.
+
+| Rule | Detail |
+|---|---|
+| Exports | `src/index.ts`, explicit, no `export *` |
+| Errors | `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
+| Files | one responsibility each, < 200 lines, tests beside the source |
+
+## Homeless work this package cannot do
+
+`packages/cli/src/dev-queue.ts`'s `applySchema` installs the jobs, idempotency, rate-limit and
+auth-limit tables. **It does not install `x_notify_deliveries` or `x_notify_inbox`**, so an app using
+the Postgres stores runs that DDL itself until they join the list — the same gap
+`SQL_AUDIT_TABLE` has.
+
+Commands: `bun test packages/notify/src`, `bun run boundaries`,
+`bunx biome check packages/notify`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# @ultimat3/notify
+
+Notifications as one declaration: channel fan-out, a preference gate, a digest window, a delivery
+ledger and an in-app inbox.
+
+`notifier()` is a **job factory** — it returns a `JobHandle`, so a notification inherits retry, the
+dead-letter path, cancellation, `x jobs show` and its manifest row. It is not a ninth primitive.
+
+## The declaration
+
+```ts
+import type { MailDefinition } from '@ultimat3/mail';
+import { send } from '@ultimat3/mail';
+import type { Recipient } from '@ultimat3/notify';
+import { inAppChannel, mailChannel, notifier, t } from '@ultimat3/notify';
+
+interface CommentPosted {
+  readonly postId: string;
+  readonly orgId: string;
+  readonly author: string;
+}
+
+// The app's own template, and the app's own repository — `./mail.ts` and a service its boot
+// installed. Neither ships here: this package knows a mailer and an audience, not your tables.
+declare const postCommented: MailDefinition<CommentPosted>;
+declare const posts: {
+  subscribers(postId: string, signal: AbortSignal): Promise<readonly Recipient[]>;
+};
+
+export const commentPosted = notifier({
+  name: 'post.commented',
+  input: t.object({ postId: t.uuid, orgId: t.uuid, author: t.string }),
+  // Required, exactly as on job(): the org this run acts under.
+  tenant: (params) => params.orgId,
+  // Required, exactly as job().idempotencyKey is — and it is the SAME value: the queue's dedupe
+  // key and the delivery ledger's event column ask one question.
+  key: (params) => `comment:${params.postId}`,
+  // Resolved on the worker, inside a durable step. Omit it and every enqueue names its own.
+  // `ctx.signal` is the run's cancellation — hand it to anything that can block.
+  recipients: ({ input, ctx }) => posts.subscribers(input.postId, ctx.signal),
+  deliver: [
+    // Fires immediately: no wait.
+    { channel: inAppChannel() },
+    // Waits ten minutes, then re-reads the condition. A subscriber who muted the thread in
+    // minute three gets nothing.
+    {
+      // The type argument is what types `mail.batch[n].params`: `NoInfer` on `deliver` stops the
+      // channel from deciding what the params are — the schema above already did.
+      channel: mailChannel<CommentPosted>({
+        mailer: {
+          send: async (mail) => {
+            // `batch` is never empty: one event for an immediate send, the whole window for a
+            // digest. Oldest first, so the newest is the last.
+            for (const event of mail.batch) {
+              await send(postCommented, event.params, { to: mail.to, locale: mail.locale ?? 'en' });
+            }
+          },
+        },
+      }),
+      wait: '10m',
+      unless: ({ event }) => event.params.author === 'system',
+      // Coalesce every comment on this post for one person into one email per hour.
+      digest: { window: '1h', group: (event) => event.params.postId },
+    },
+  ],
+});
+```
+
+Enqueued like any other job:
+
+```ts
+import type { JobHandle } from '@ultimat3/jobs';
+import type { NotifyPayload } from '@ultimat3/notify';
+
+// The declaration above: `notifier()` returns a JobHandle, so this IS the job's own enqueue.
+declare const commentPosted: JobHandle<
+  NotifyPayload<{ postId: string; orgId: string; author: string }>
+>;
+declare const postId: string;
+declare const orgId: string;
+declare const author: string;
+
+await commentPosted.enqueue({ params: { postId, orgId, author } });
+// …or with the audience handed in, `noticed`'s `.deliver(recipients)`:
+await commentPosted.enqueue({
+  params: { postId, orgId, author },
+  recipients: [{ id: 'u_1', to: 'ana@example.com', locale: 'en-GB', tz: 'Europe/London' }],
+});
+```
+
+The payload nests `params` rather than spreading it, so an app whose notification is *about*
+recipients cannot collide with the framework's own key.
+
+## Installing the stores
+
+One call, at boot. Whole-object replacement, never a merge.
+
+```ts
+import type { PgExecutor } from '@ultimat3/jobs';
+import {
+  createMemoryDigestStore,
+  createPgDeliveryLedger,
+  createPgInboxStore,
+  setNotifyStores,
+} from '@ultimat3/notify';
+
+declare const executor: PgExecutor;   // `@ultimat3/cli`'s pgExecutorFor(client)
+// The app's preference table, behind whatever taxonomy it named.
+declare const prefs: {
+  allows(recipient: string, notifier: string, channel: string, at: Date): boolean;
+};
+
+setNotifyStores({
+  ledger: createPgDeliveryLedger({ executor }),
+  inbox: createPgInboxStore({ executor }),
+  digest: createMemoryDigestStore(),
+  preferences: {
+    // The GATE ships; what it reads never does. Your taxonomy, your quiet hours.
+    allows: ({ recipient, notifier: name, channel, ctx }) =>
+      prefs.allows(recipient.id, name, channel, ctx.now()),
+  },
+});
+```
+
+| Store | Default | Why |
+|---|---|---|
+| `ledger` | `createMemoryDeliveryLedger()` | one process is genuinely deduped by a heap map, and no ledger at all means a replay sends twice |
+| `preferences` | `allowAllPreferences()` | denying by default is a notifier that silently delivers nothing |
+| `inbox` | **none** — `X_NOTIFY_STORE_MISSING` | a message written to nowhere is worse than a refusal |
+| `digest` | **none** — `X_NOTIFY_STORE_MISSING` | same |
+
+`executor` is a structural `{ query(sql, params) }` — `@ultimat3/cli`'s `pgExecutorFor(client)` over
+a `DbClient` is the framework's own. `Bun.sql` does **not** satisfy it.
+
+## Channels
+
+```ts
+import { bulkChannel, channel } from '@ultimat3/notify';
+
+// The app's push vendor and its Slack webhook — a channel is where an SDK belongs.
+declare const pushService: {
+  send(token: string, payload: unknown, init: { signal: AbortSignal }): Promise<void>;
+};
+declare const SLACK_URL: string;
+
+// One call per recipient. The retry unit is one address.
+export const push = channel('push', async ({ recipient, event, signal }) => {
+  await pushService.send(recipient.to ?? '', event.params, { signal });
+});
+
+// ONE call for the whole audience — a Slack post, a webhook, a digest to an ops channel.
+export const slack = bulkChannel('slack', async ({ recipients, event, signal }) => {
+  await fetch(SLACK_URL, {
+    method: 'POST',
+    body: JSON.stringify({ text: `${String(recipients.length)} watchers`, event: event.key }),
+    signal,
+  });
+});
+```
+
+`inAppChannel()` and `mailChannel({ mailer })` ship. `mailChannel` takes a **structural** `Mailer` —
+one method, no dependency on `@ultimat3/mail`, which is the same tier.
+
+## The inbox
+
+```ts
+import type { Ctx } from '@ultimat3/core';
+import { requireInbox } from '@ultimat3/notify';
+
+declare const ctx: Ctx;   // the request context; `ctx.actor` is who is reading
+
+const store = requireInbox('post.commented');
+const page = await store.list({ recipient: ctx.actor.id, limit: 50 });
+const badge = await store.unreadCount(ctx.actor.id);
+await store.markSeen({ recipient: ctx.actor.id, at: ctx.now() });
+await store.markRead({ recipient: ctx.actor.id, ids: [page[0]?.id ?? ''], at: ctx.now() });
+```
+
+`seenAt` and `readAt` are two facts — showing the badge does not dismiss the message — and the
+unread count is **derived** from `readAt is null`, never stored, so the badge and the list cannot
+disagree. Every write is scoped by recipient: an id somebody else named is simply absent.
+
+## Delivery order
+
+`deliver` entries are sorted by `wait` ascending and the fan-out sleeps the **delta**, so a channel
+with no wait fires immediately even when a later one waits an hour. `if` and `unless` are evaluated
+**after** the wait, on the attempt that delivers — a condition that goes false during a ten-minute
+delay sends nothing.
+
+## At-least-once
+
+A job body runs before its checkpoint lands. Two layers stop a double send: the step checkpoint
+(`deliver:<channel>:<recipient>`), and the delivery ledger's atomic claim on
+`(notifier, key, channel, coalesce(recipient, ''))` — taken before the send, settled after. A claim
+that already reads `sent` answers `false`.
+
+A bulk channel claims **one** row for the whole audience, with a null recipient: half a bulk POST is
+not a state this package can represent. That null is why the key coalesces rather than naming the
+column: NULLs are distinct in a plain unique index, so a bulk claim would otherwise be claimable
+without bound and every replay would re-send the whole audience.
+
+## Errors
+
+| Code | When |
+|---|---|
+| `X_NOTIFY_CHANNELS_EMPTY` | `deliver: []` — refused at declaration |
+| `X_NOTIFY_CHANNEL_DUPLICATE` | two deliveries name one channel; the ledger keys on it |
+| `X_NOTIFY_DIGEST_UNSUPPORTED` | a digest window on a bulk channel |
+| `X_NOTIFY_FANOUT_TOO_WIDE` | more recipients than `maxRecipients` (default 500) |
+| `X_NOTIFY_STORE_MISSING` | an inbox or digest channel with no store installed |
+| `X_NOTIFY_DELIVERY_FAILED` | a channel's `deliver` threw; the run retries on its policy |
+
+## Boundary
+
+Tier 4. May import tiers 0-3 — enforced by `bun run boundaries`. Its real imports are `core`,
+`schema`, `time` and `jobs`, so tier 4 is its floor. See [`CLAUDE.md`](./CLAUDE.md).

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ultimat3/notify",
+  "version": "12.0.0",
+  "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/notify"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "sideEffects": [
+    "./src/errors.ts"
+  ],
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/jobs": "12.0.0",
+    "@ultimat3/schema": "12.0.0",
+    "@ultimat3/time": "12.0.0"
+  }
+}

package/src/attempt.ts

@@ -0,0 +1,48 @@
+// One delivery attempt, ledger-first. Every send in this package goes through here, so there is
+// exactly one place that decides "has this already gone out" and exactly one that records the
+// answer.
+//
+// The order is claim → send → settle, and it is not interchangeable. Settling first would mark a
+// send that has not happened; claiming after would let two attempts pass the check together.
+
+import type { Ctx } from '@ultimat3/core';
+import { NotifyDeliveryFailedError } from './errors';
+import type { DeliveryClaim, DeliveryLedger } from './ledger';
+
+export interface AttemptInput {
+  readonly ledger: DeliveryLedger;
+  readonly claim: DeliveryClaim;
+  readonly notifier: string;
+  readonly channel: string;
+  /** How many addresses this one attempt covers — 1 for an individual channel, the audience for
+   * a bulk one. Reported in the refusal, because "the Slack post failed" and "one of 400 emails
+   * failed" are different incidents. */
+  readonly recipients: number;
+  readonly ctx: Ctx;
+  send(signal: AbortSignal): Promise<void> | void;
+}
+
+/**
+ * `true` when this attempt sent, `false` when the ledger already held a completed delivery — the
+ * replay case, and the whole reason this function exists.
+ *
+ * A throwing channel settles `failed` and then rethrows as `X_NOTIFY_DELIVERY_FAILED`: the row
+ * stays re-claimable, so the job's own retry policy decides whether it goes out, and the dead
+ * letter names the channel rather than whatever the provider's SDK threw.
+ */
+export async function attemptDelivery(input: AttemptInput, signal: AbortSignal): Promise<boolean> {
+  if (!(await input.ledger.claim(input.claim, input.ctx.now()))) return false;
+  try {
+    await input.send(signal);
+  } catch (error) {
+    await input.ledger.settle(input.claim, 'failed', input.ctx.now());
+    throw new NotifyDeliveryFailedError({
+      notifier: input.notifier,
+      channel: input.channel,
+      recipients: input.recipients,
+      cause: error,
+    });
+  }
+  await input.ledger.settle(input.claim, 'sent', input.ctx.now());
+  return true;
+}

package/src/channel-in-app.ts

@@ -0,0 +1,34 @@
+// The in-app inbox as a channel. `noticed` writes a notification row unconditionally; here it is
+// an opt-in channel, so a notifier that only sends email writes no rows at all — one mechanism,
+// declared where every other delivery is declared, rather than a table that fills itself.
+
+import type { NotifyChannel } from './channel';
+import { channel } from './channel';
+import { requireInbox } from './stores';
+
+export interface InAppChannelOptions {
+  /** The ledger and preference key this delivery is known by. Change it only to run two inbox
+   * channels on one notifier — e.g. a per-org feed beside a personal one. */
+  readonly name?: string | undefined;
+}
+
+export const IN_APP_CHANNEL = 'in-app';
+
+export function inAppChannel<Params = unknown>(
+  options: InAppChannelOptions = {},
+): NotifyChannel<Params> {
+  return channel<Params>(options.name ?? IN_APP_CHANNEL, async ({ recipient, batch }) => {
+    // Every event in the batch, not just the newest: a digest window over an inbox still owes the
+    // reader one row per thing that happened. `add` is idempotent on (recipient, notifier, key),
+    // so a replayed attempt writes nothing new and does not move an existing row's timestamps.
+    for (const entry of batch) {
+      await requireInbox(entry.notifier).add({
+        recipient: recipient.id,
+        notifier: entry.notifier,
+        key: entry.key,
+        params: entry.params,
+        createdAt: entry.at,
+      });
+    }
+  });
+}

package/src/channel-mail.ts

@@ -0,0 +1,75 @@
+// Email as a channel, over a STRUCTURAL mailer rather than an import of @ultimat3/mail.
+//
+// That is the tier argument, and it is the same one `@ultimat3/action`'s `PgExecutor` makes about
+// `@ultimat3/db`. `@ultimat3/mail` is tier 4 and so is this package, so importing it would be a
+// sideways edge — and moving `notify` to tier 5 to legalise it would put notifications above
+// `render`, `pwa` and `ui` for no reason other than one channel's transport. A mailer is a driver
+// seam, so it is declared here as the shape it is: one method, no dependency.
+//
+//   mailChannel({ mailer: { send: (mail) => send(postLiked, mail.batch[0].params, {
+//     to: mail.to, locale: mail.locale ?? 'en',
+//   }) } })
+
+import type { NotifyChannel } from './channel';
+import { channel } from './channel';
+import type { NotifyEvent, Recipient } from './notification';
+
+/** What a mailer is handed. Everything a template needs to render, and nothing about transport. */
+export interface NotifyMail<Params = unknown> {
+  readonly to: string;
+  /** BCP-47, from the recipient. `undefined` when the app did not resolve one — never guessed. */
+  readonly locale: string | undefined;
+  /** IANA zone, from the recipient. A mail that formats a date and reads this `undefined` must
+   * refuse rather than fall back: no ambient time zone, anywhere. */
+  readonly tz: string | undefined;
+  /** Oldest first. One entry for an immediate send; the whole window for a digest. */
+  readonly batch: readonly NotifyEvent<Params>[];
+  readonly signal: AbortSignal;
+}
+
+/**
+ * The seam. `@ultimat3/mail`'s `send(definition, params, { to, locale })` satisfies it in one
+ * line, and so does a transactional-email SDK an app already pays for.
+ */
+export interface Mailer<Params = unknown> {
+  send(mail: NotifyMail<Params>): Promise<void> | void;
+}
+
+export const MAIL_CHANNEL = 'email';
+
+export interface MailChannelOptions<Params> {
+  readonly mailer: Mailer<Params>;
+  readonly name?: string | undefined;
+  /**
+   * Where the address comes from. Defaults to `recipient.to`.
+   *
+   * `undefined` back means this recipient has no address, which is NOT a failure: the delivery is
+   * settled as sent and logged as `notify.address_missing`, because retrying the same event will
+   * find the same missing address and the only outcome of pretending otherwise is a dead letter
+   * per addressless recipient.
+   */
+  readonly addressOf?: ((recipient: Recipient) => string | undefined) | undefined;
+}
+
+export function mailChannel<Params = unknown>(
+  options: MailChannelOptions<Params>,
+): NotifyChannel<Params> {
+  const addressOf = options.addressOf ?? ((recipient: Recipient) => recipient.to);
+  return channel<Params>(
+    options.name ?? MAIL_CHANNEL,
+    async ({ recipient, batch, ctx, signal }) => {
+      const to = addressOf(recipient);
+      if (to === undefined || to === '') {
+        ctx.logger.warn('notify.address_missing', { recipient: recipient.id });
+        return;
+      }
+      await options.mailer.send({
+        to,
+        locale: recipient.locale,
+        tz: recipient.tz,
+        batch,
+        signal,
+      });
+    },
+  );
+}

package/src/channel.ts

@@ -0,0 +1,76 @@
+// What a channel IS: a name plus one `deliver`, in two arities. Individual channels are called
+// once per recipient; bulk channels once for the whole audience.
+//
+// The split is `noticed`'s and it is not cosmetic. An email is instantiated per person and a Slack
+// post is one POST for everybody, so a framework that only knows the first shape makes an app send
+// the same webhook a hundred times.
+
+import type { Ctx } from '@ultimat3/core';
+import type { NotifyEvent, Recipient } from './notification';
+
+/** What every `deliver` gets, whichever arity. */
+interface DeliveryCommon<Params> {
+  readonly ctx: Ctx;
+  /**
+   * The events this delivery covers. One entry for an immediate send; every event the window
+   * coalesced, oldest first, for a digest flush. A channel that ignores it and reads `event`
+   * alone is correct for the immediate case and lossy for the digest one, which is why the field
+   * is not optional.
+   */
+  readonly batch: readonly NotifyEvent<Params>[];
+  /** The newest event in `batch` — the one a single-event channel renders. */
+  readonly event: NotifyEvent<Params>;
+  /** The run's cancellation folded with this step's ceiling. Hand it to `fetch`. */
+  readonly signal: AbortSignal;
+}
+
+export interface DeliveryArgs<Params = unknown> extends DeliveryCommon<Params> {
+  readonly recipient: Recipient;
+}
+
+export interface BulkDeliveryArgs<Params = unknown> extends DeliveryCommon<Params> {
+  /** Everyone the preference gate allowed. Never empty — the fan-out skips an empty audience. */
+  readonly recipients: readonly Recipient[];
+}
+
+export interface NotifyChannel<Params = unknown> {
+  readonly name: string;
+  readonly bulk: false;
+  deliver(args: DeliveryArgs<Params>): Promise<void> | void;
+}
+
+export interface BulkNotifyChannel<Params = unknown> {
+  readonly name: string;
+  readonly bulk: true;
+  deliver(args: BulkDeliveryArgs<Params>): Promise<void> | void;
+}
+
+export type AnyNotifyChannel<Params = unknown> = NotifyChannel<Params> | BulkNotifyChannel<Params>;
+
+/**
+ * One recipient per call. The name is durable — it is a column of the delivery ledger — so it is
+ * given here rather than derived from a variable name that a bundler may rewrite.
+ */
+export function channel<Params = unknown>(
+  name: string,
+  deliver: (args: DeliveryArgs<Params>) => Promise<void> | void,
+): NotifyChannel<Params> {
+  return { name, bulk: false, deliver };
+}
+
+/**
+ * One call for the whole audience. The ledger claims ONE row per (event, channel) rather than one
+ * per recipient, because the send is one thing: half a bulk POST is not a state this package can
+ * represent, and pretending otherwise would let a replay re-post to everybody to repair one
+ * address.
+ */
+export function bulkChannel<Params = unknown>(
+  name: string,
+  deliver: (args: BulkDeliveryArgs<Params>) => Promise<void> | void,
+): BulkNotifyChannel<Params> {
+  return { name, bulk: true, deliver };
+}
+
+export const isBulkChannel = <Params>(
+  value: AnyNotifyChannel<Params>,
+): value is BulkNotifyChannel<Params> => value.bulk;