@ultimat3/notify 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -55,12 +55,24 @@ A job body runs **before** its checkpoint lands, so both layers are load-bearing
 `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. `createPgDigestStore` makes the window itself durable and shared — the
+rather than hidden. `postgresDigestStore` makes the window itself durable and shared — the
 partial unique index `x_notify_digests_open_idx` lets two replicas' first appends collide so ONE
 opens the window and owns the flush; an elapsed open window is sealed and the append retried — but
 its `drain` is still a delete, so the seam is unchanged (`digest-parity.live.test.ts` runs one
 suite against both stores).
 
+**A digest append is ONE STEP PER RECIPIENT, and idempotent per appender** (`As of 2026-10-05`).
+The append pass was one `step.run`, and a step that fails part-way re-runs WHOLE: recipients already
+appended read `opened: false` from the window they had opened and it was never drained, and a window
+they had JOINED could have been drained and deleted by its owner meanwhile, so their event went out
+in a second digest. Now `digest:<channel>:<recipient>` is a step each (the step store is the
+durable fence; one row per recipient, as `deliver:` already writes), and behind it
+`DigestAppend.appender` (`${runId}:${recipient}`) is stored per window — `appended_by text[]`,
+opener first — so an append whose answer was lost, or a run whose step history is gone, gets back
+the window it landed in while that window exists. Two executions of one appender at once (a lapsed
+lease) cannot both join: the `do update` refuses an appender already in the row. Pinned by
+`fanout-digest.test.ts` and `digest-parity.live.test.ts`.
+
 **The audience is deduplicated by `id` once, as it leaves the `open` step** (`As of 2026-10-02`).
 Every per-recipient step is named by the id, so a resolver that named one person twice failed
 `X_STEP_DUPLICATE` part-way through the fan-out, on every retry. Outside the step rather than in it,
@@ -91,7 +103,7 @@ off.
 `list`/`markRead`** (`As of 2026-09`). `markRead`'s contract is that an id belonging to nobody is
 *simply absent* — the memory store skips it — while the Postgres one bound the caller's ids into
 `any($2::uuid[])`, so one malformed id raised 22P02 out of the store and the nineteen good ids in
-the batch went unmarked. `createPgInboxStore` screens with `isUuid` before binding and answers `0`
+the batch went unmarked. `postgresInboxStore` screens with `isUuid` before binding and answers `0`
 with no round trip when nothing survives; the statement keeps its `::uuid[]` cast and its primary
 key index, which `id::text = any($2)` would have given up. And the memory `list` now sorts
 `(createdAt desc, notifier, key)` — the total order `SQL_NOTIFY_INBOX_PAGE` takes — because
@@ -99,8 +111,8 @@ key index, which `id::text = any($2)` would have given up. And the memory `list`
 can drop one and repeat the other.
 
 **The tail is `(notifier, key)` and never `id`, `As of 2026-09-06`.** Both stores had a tail and
-they were two different total orders: `createPgInboxStore` mints a UUIDv7 that Postgres compares by
-its 16 BYTES, while `createMemoryInboxStore` derives its id from
+they were two different total orders: `postgresInboxStore` mints a UUIDv7 that Postgres compares by
+its 16 BYTES, while `memoryInboxStore` derives its id from
 `JSON.stringify([recipient, notifier, key])` and compares by code point — so equal-`createdAt` rows
 came back one way in dev and the other in production, which is the drop-and-repeat the tail exists
 to prevent, on whichever driver nobody tested against. `(notifier, key)` is unique within a
@@ -126,19 +138,19 @@ decision rather than a failure.
 
 | Table | Window | Named where |
 |---|---|---|
-| `x_notify_deliveries` | `PgDeliveryLedgerOptions.windowMs`, default 24 h | beside the statement that reads it. **Never shorter than the app's idempotency window** — a job replayed inside that window against a purged claim claims cleanly and sends twice. Pass `idempotency.windowMs` |
-| `x_notify_digests` | `PgDigestStoreOptions.retentionMs`, default 7 days after the window closed | beside the statement that reads it, like the ledger's |
+| `x_notify_deliveries` | `PostgresDeliveryLedgerOptions.windowMs`, default 24 h | beside the statement that reads it. **Never shorter than the app's idempotency window** — a job replayed inside that window against a purged claim claims cleanly and sends twice. Pass `idempotency.windowMs` |
+| `x_notify_digests` | `PostgresDigestStoreOptions.retentionMs`, default 7 days after the window closed | beside the statement that reads it, like the ledger's |
 | `x_notify_inbox` | `notify.inboxReadRetentionMs` / `notify.inboxUnreadRetentionMs` in `AppConfig`, **both absent by default** | the app's `app.config.ts`, because an inbox row is a message a person has not read yet and when it disappears is a product decision (axiom 8) |
 
 `purgeBefore` and `purgeExpired` live on the **Postgres stores' own wider types**
-(`PgInboxStore`, `PgDeliveryLedger`, `PgDigestStore`), never on the seams: adding a method to
+(`PostgresInboxStore`, `PostgresDeliveryLedger`, `PostgresDigestStore`), never on the seams: adding a method to
 the seam every implementation must satisfy is a breaking change for an app that wrote its own, and a
 heap map bounded by process life has nothing to delete. Exactly the shape `PostgresIdempotencyStore`
 already has.
 
 `x_notify_digests`: every window is deleted by its own flush's `drain`, or by the next window's
 drain of the same slot (`ends_at <=`). The one neither reaches — a flush that dead-lettered, on a
-slot that never digests again — is the sweep's (`purgeNotifyDigests` → `PgDigestStore.purgeExpired`,
+slot that never digests again — is the sweep's (`purgeNotifyDigests` → `PostgresDigestStore.purgeExpired`,
 `As of 2026-10-02`): windows CLOSED more than `retentionMs` before the job's clock, default
 `DEFAULT_DIGEST_RETENTION_MS` (7 days, longer than any flush's retries), deleted in batches of
 `DIGEST_PURGE_BATCH` and at most `DIGEST_PURGE_MAX_BATCHES` statements per pass.

package/README.md

@@ -98,9 +98,9 @@ One call, at boot. Whole-object replacement, never a merge.
 ```ts
 import type { PgExecutor } from '@ultimat3/jobs';
 import {
-  createPgDeliveryLedger,
-  createPgDigestStore,
-  createPgInboxStore,
+  postgresDeliveryLedger,
+  postgresDigestStore,
+  postgresInboxStore,
   setNotifyStores,
 } from '@ultimat3/notify';
 
@@ -114,10 +114,10 @@ declare const prefs: {
 setNotifyStores({
   // `windowMs` is how long a settled claim is kept. NEVER SHORTER than your idempotency window —
   // a job replayed inside that window against a purged claim claims cleanly and sends twice.
-  ledger: createPgDeliveryLedger({ executor, windowMs: idempotency.windowMs }),
-  inbox: createPgInboxStore({ executor }),
+  ledger: postgresDeliveryLedger({ executor, windowMs: idempotency.windowMs }),
+  inbox: postgresInboxStore({ executor }),
   // `x_notify_digests`: a window survives a restart and every replica joins the same one.
-  digest: createPgDigestStore({ executor }),
+  digest: postgresDigestStore({ executor }),
   preferences: {
     // The GATE ships; what it reads never does. Your taxonomy, your quiet hours.
     allows: ({ recipient, notifier: name, channel, ctx }) =>
@@ -128,10 +128,10 @@ setNotifyStores({
 
 | Store | Default | Why |
 |---|---|---|
-| `ledger` | `createMemoryDeliveryLedger()` | one process is genuinely deduped by a heap map, and no ledger at all means a replay sends twice |
+| `ledger` | `memoryDeliveryLedger()` | 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. `createMemoryDigestStore()` for one process; `createPgDigestStore({ executor })` keeps a window across a restart and gives two replicas ONE window (a partial unique index on the open one), so exactly one run owns its flush |
+| `digest` | **none** — `X_NOTIFY_STORE_MISSING` | same. `memoryDigestStore()` for one process; `postgresDigestStore({ executor })` keeps a window across a restart and gives two replicas ONE window (a partial unique index on the open one), so exactly one run owns its flush |
 
 `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.
@@ -139,17 +139,17 @@ a `DbClient` is the framework's own. `Bun.sql` does **not** satisfy it.
 ## Retention
 
 All three tables grow with traffic, and the boot's hourly `x.purge` job sweeps them — but only
-against the **Postgres** stores. `createPgInboxStore` carries `purgeBefore`, `createPgDeliveryLedger`
-and `createPgDigestStore` carry `purgeExpired`; the memory ones do not, and a boot that installed a
-memory store sweeps nothing. The methods are on those stores' own wider types (`PgInboxStore`,
-`PgDeliveryLedger`, `PgDigestStore`), not on the seams, so an app that wrote its own implementation
+against the **Postgres** stores. `postgresInboxStore` carries `purgeBefore`, `postgresDeliveryLedger`
+and `postgresDigestStore` carry `purgeExpired`; the memory ones do not, and a boot that installed a
+memory store sweeps nothing. The methods are on those stores' own wider types (`PostgresInboxStore`,
+`PostgresDeliveryLedger`, `PostgresDigestStore`), not on the seams, so an app that wrote its own implementation
 is unaffected.
 
 | Table | Window | Default |
 |---|---|---|
-| `x_notify_deliveries` | `createPgDeliveryLedger({ windowMs })` | 24 h. A settled claim ages from its **last** attempt — `settle` moves `at` |
+| `x_notify_deliveries` | `postgresDeliveryLedger({ windowMs })` | 24 h. A settled claim ages from its **last** attempt — `settle` moves `at` |
 | `x_notify_inbox` | `notify.inboxReadRetentionMs` / `notify.inboxUnreadRetentionMs` in `app.config.ts` | **neither** — never swept |
-| `x_notify_digests` | `createPgDigestStore({ retentionMs })` | 7 days after a window CLOSED. A drained window is already gone; this takes one whose flush dead-lettered. Batched: 1,000 rows per statement, at most 50 per pass |
+| `x_notify_digests` | `postgresDigestStore({ retentionMs })` | 7 days after a window CLOSED. A drained window is already gone; this takes one whose flush dead-lettered. Batched: 1,000 rows per statement, at most 50 per pass |
 
 The inbox default is deliberate and is not a missing number. An inbox row is a message a person has
 not read yet, so when it disappears is your decision, not the framework's — which is why the key
@@ -168,7 +168,7 @@ A read row ages from `read_at` and an unread one from `created_at` — ageing a
 ## Channels
 
 ```ts
-import { bulkChannel, channel } from '@ultimat3/notify';
+import { bulkChannel, deliveryChannel } from '@ultimat3/notify';
 
 // The app's push vendor and its Slack webhook — a channel is where an SDK belongs.
 declare const pushService: {
@@ -177,7 +177,7 @@ declare const pushService: {
 declare const SLACK_URL: string;
 
 // One call per recipient. The retry unit is one address.
-export const push = channel('push', async ({ recipient, event, signal }) => {
+export const push = deliveryChannel('push', async ({ recipient, event, signal }) => {
   await pushService.send(recipient.to ?? '', event.params, { signal });
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
   "license": "MIT",
   "type": "module",
@@ -28,16 +28,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/time": "24.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/jobs": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/channel-in-app.ts

@@ -3,7 +3,7 @@
 // declared where every other delivery is declared, rather than a table that fills itself.
 
 import type { NotifyChannel } from './channel';
-import { channel } from './channel';
+import { deliveryChannel } from './channel';
 import { requireInbox } from './stores';
 
 export interface InAppChannelOptions {
@@ -17,7 +17,7 @@ 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 }) => {
+  return deliveryChannel<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.

package/src/channel-mail.ts

@@ -11,7 +11,7 @@
 //   }) } })
 
 import type { NotifyChannel } from './channel';
-import { channel } from './channel';
+import { deliveryChannel } from './channel';
 import type { NotifyEvent, Recipient } from './notification';
 
 /** What a mailer is handed. Everything a template needs to render, and nothing about transport. */
@@ -55,7 +55,7 @@ export function mailChannel<Params = unknown>(
   options: MailChannelOptions<Params>,
 ): NotifyChannel<Params> {
   const addressOf = options.addressOf ?? ((recipient: Recipient) => recipient.to);
-  return channel<Params>(
+  return deliveryChannel<Params>(
     options.name ?? MAIL_CHANNEL,
     async ({ recipient, batch, ctx, signal }) => {
       const to = addressOf(recipient);

package/src/channel.ts

@@ -51,7 +51,7 @@ export type AnyNotifyChannel<Params = unknown> = NotifyChannel<Params> | BulkNot
  * 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>(
+export function deliveryChannel<Params = unknown>(
   name: string,
   deliver: (args: DeliveryArgs<Params>) => Promise<void> | void,
 ): NotifyChannel<Params> {

package/src/digest-pg.ts

@@ -1,5 +1,5 @@
 // The Postgres digest store: one row per window, so a `digested` event outlives the process that
-// appended it and every replica coalesces into the same window. `createMemoryDigestStore` is the
+// appended it and every replica coalesces into the same window. `memoryDigestStore` is the
 // same queue of windows in one heap; this is what a deployment with more than one process installs.
 
 import type { PgExecutor } from '@ultimat3/core';
@@ -35,21 +35,46 @@ create index if not exists x_notify_digests_slot_idx
   on x_notify_digests (recipient, notifier, channel, group_key, ends_at);
 
 create index if not exists x_notify_digests_ends_idx on x_notify_digests (ends_at);
+
+alter table x_notify_digests add column if not exists appended_by text[] not null default '{}';
 `;
 
 /**
- * Join the open window, or open one. `(xmax = 0)` is true for the row this statement INSERTED and
- * false for one it updated, which is `DigestBucket.opened`. An open window that has already
- * elapsed is not joined: the `where` on the `do update` refuses it and no row comes back, which is
- * the store's cue to seal it and try again.
+ * Join the open window, or open one — unless this appender (`$8`) already landed in a window of the
+ * slot, which is a replayed step: then that window's answer comes back and nothing is written.
+ * `appended_by[1]` is the opener, so a replay by the opener still reads `opened`, and owns the
+ * flush it owned the first time. `(xmax = 0)` is true for the row this statement INSERTED and false
+ * for one it updated. An open window that has already elapsed is not joined: the `where` on the
+ * `do update` refuses it and no row comes back, which is the store's cue to seal it and try again.
+ * A row written before `appended_by` existed holds `'{}'`, matches no appender, and opens nothing.
+ *
+ * The `any` on the `do update` is for two executions of ONE appender at once (a lapsed lease): both
+ * pass `prior` in their own snapshots, and the loser's conflict re-reads the winner's COMMITTED row.
+ * It refuses to join it twice and no row comes back — the store's next pass then finds it in
+ * `prior`, exactly as it finds an elapsed window sealed.
  */
 export const SQL_NOTIFY_DIGEST_APPEND = `
-insert into x_notify_digests (recipient, notifier, channel, group_key, ends_at, events)
-values ($1, $2, $3, $4, $6, $5::jsonb)
-on conflict (recipient, notifier, channel, group_key) where not sealed
-do update set events = x_notify_digests.events || excluded.events
-where x_notify_digests.ends_at > $7
-returning ends_at, (xmax = 0) as opened
+with prior as (
+  select ends_at, coalesce(appended_by[1] = $8::text, false) as opened
+  from x_notify_digests
+  where recipient = $1 and notifier = $2 and channel = $3 and group_key = $4
+    and $8::text = any(appended_by)
+  order by seq
+  limit 1
+), joined as (
+  insert into x_notify_digests (recipient, notifier, channel, group_key, ends_at, events, appended_by)
+  select $1, $2, $3, $4, $6::timestamptz, $5::jsonb, array[$8::text]
+  where not exists (select 1 from prior)
+  on conflict (recipient, notifier, channel, group_key) where not sealed
+  do update set events = x_notify_digests.events || excluded.events,
+    appended_by = x_notify_digests.appended_by || excluded.appended_by
+  where x_notify_digests.ends_at > $7::timestamptz
+    and not ($8::text = any(x_notify_digests.appended_by))
+  returning ends_at, (xmax = 0) as opened
+)
+select ends_at, opened from prior
+union all
+select ends_at, opened from joined
 `;
 
 /** Seal the slot's open window once it has elapsed, so the next append opens a fresh one. */
@@ -131,27 +156,27 @@ const slotArgs = (slot: DigestSlot): readonly unknown[] => [
 const epochOf = (value: Date | string): number =>
   (value instanceof Date ? value : new Date(value)).getTime();
 
-export interface PgDigestStoreOptions {
+export interface PostgresDigestStoreOptions {
   readonly executor: PgExecutor;
   /** How long a closed window is kept. Defaults to `DEFAULT_DIGEST_RETENTION_MS`. */
   readonly retentionMs?: number | undefined;
 }
 
 /**
- * The Postgres store's own wider type, exactly as `PgDeliveryLedger` is: `purgeExpired` is not on
+ * The Postgres store's own wider type, exactly as `PostgresDeliveryLedger` is: `purgeExpired` is not on
  * `DigestStore`, because a heap map bounded by process life has nothing to delete and a new
  * method on the seam breaks every app that wrote its own store.
  */
-export interface PgDigestStore extends DigestStore {
+export interface PostgresDigestStore extends DigestStore {
   readonly retentionMs: number;
   /** Delete windows closed more than `retentionMs` before `nowMs` (the job's clock); answer how many. */
   purgeExpired(nowMs: number): Promise<number>;
 }
 
-export function createPgDigestStore(options: PgDigestStoreOptions): PgDigestStore {
+export function postgresDigestStore(options: PostgresDigestStoreOptions): PostgresDigestStore {
   const { executor } = options;
   const retentionMs = finiteCount(
-    'createPgDigestStore',
+    'postgresDigestStore',
     'retentionMs',
     options.retentionMs ?? DEFAULT_DIGEST_RETENTION_MS,
     1,
@@ -183,8 +208,11 @@ export function createPgDigestStore(options: PgDigestStoreOptions): PgDigestStor
           events,
           endsAt,
           now,
+          input.appender,
         ]);
         if (row !== undefined) return { opened: row.opened, endsAt: epochOf(row.ends_at) };
+        // No row: the open window elapsed, or this appender's own twin committed it first. The seal
+        // is a no-op on a window still open, and either way the next pass answers from `prior`.
         await executor.query(SQL_NOTIFY_DIGEST_SEAL, [...slot, now]);
       }
       // Reached only when every retry met a window that ANOTHER appender had just opened and that

package/src/digest.ts

@@ -26,6 +26,13 @@ export interface DigestAppend {
   readonly event: NotifyEvent<unknown>;
   readonly windowMs: number;
   readonly now: Date;
+  /**
+   * Who is appending: the fan-out passes its job's `runId` and the recipient, which a retry keeps.
+   * The append runs inside a step that re-runs WHOLE when any append in it fails, so an appender
+   * that already landed must get the SAME answer back and add nothing — a replay that read
+   * `opened: false` left a window nobody owned, and so nobody ever drained.
+   */
+  readonly appender: string;
 }
 
 export interface DigestBucket {
@@ -65,6 +72,8 @@ const slotKey = (slot: DigestSlot): string =>
 interface OpenBucket {
   endsAt: number;
   readonly events: NotifyEvent<unknown>[];
+  /** Every appender this window took, opener first — what makes a replayed append a no-op. */
+  readonly appenders: string[];
 }
 
 export interface MemoryDigestStore extends DigestStore {
@@ -78,7 +87,7 @@ export interface MemoryDigestStore extends DigestStore {
  * event the earlier window held. A closed window is now sealed under its `endsAt`, and a later
  * append opens the next one beside it.
  */
-export function createMemoryDigestStore(): MemoryDigestStore {
+export function memoryDigestStore(): MemoryDigestStore {
   const slots = new Map<string, OpenBucket[]>();
   return {
     get open(): number {
@@ -90,15 +99,24 @@ export function createMemoryDigestStore(): MemoryDigestStore {
       const id = slotKey(input.slot);
       const at = input.now.getTime();
       const windows = slots.get(id) ?? [];
+      // A replay answers the window it already landed in, sealed or not, and adds nothing.
+      const prior = windows.find((window) => window.appenders.includes(input.appender));
+      if (prior !== undefined) {
+        return Promise.resolve({
+          opened: prior.appenders[0] === input.appender,
+          endsAt: prior.endsAt,
+        });
+      }
       const newest = windows.at(-1);
       // An elapsed window is SEALED — its flush drains it — and never appended to: the event
       // opens the next window, which is one extra delivery rather than a lost one.
       if (newest !== undefined && newest.endsAt > at) {
         newest.events.push(input.event);
+        newest.appenders.push(input.appender);
         return Promise.resolve({ opened: false, endsAt: newest.endsAt });
       }
       const endsAt = at + input.windowMs;
-      windows.push({ endsAt, events: [input.event] });
+      windows.push({ endsAt, events: [input.event], appenders: [input.appender] });
       slots.set(id, windows);
       return Promise.resolve({ opened: true, endsAt });
     },

package/src/errors.ts

@@ -96,7 +96,7 @@ export class NotifyChannelDuplicateError extends UltimateError {
     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`,
+      fix: `give the second channel its own name on notifier("${input.notifier}") — deliveryChannel('${input.channel}-digest', …) — or merge the two deliver entries`,
       meta: { notifier: input.notifier, channel: input.channel },
     });
   }
@@ -122,7 +122,7 @@ export class NotifyFanoutTooWideError extends UltimateError {
  * 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
+ * (`memoryDeliveryLedger`), 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 {
@@ -131,8 +131,8 @@ export class NotifyStoreMissingError extends UltimateError {
       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';
+        ? 'memoryInboxStore() }) at boot, or postgresInboxStore({ executor }) to share it across replicas'
+        : 'memoryDigestStore() }) 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`,
@@ -152,7 +152,7 @@ export class NotifyDigestUnsupportedError extends UltimateError {
     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`,
+      fix: `drop digest from the "${input.channel}" entry on notifier("${input.notifier}") and give it a wait instead, or deliver it through deliveryChannel('${input.channel}', …) one recipient at a time`,
       meta: { notifier: input.notifier, channel: input.channel },
     });
   }

package/src/fanout-digest.ts

@@ -21,7 +21,7 @@ export interface DigestFlush<Params> {
 
 export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<void> {
   const { walk, channel, delivery, allowed } = input;
-  const { plan, event, ctx, step, tally } = walk;
+  const { plan, event, ctx, runId, step, tally } = walk;
   const windowMs = delivery.digestMs ?? 0;
   const digest = requireDigest(plan.name);
   const group = delivery.group?.(event) ?? plan.name;
@@ -32,26 +32,33 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
     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 () => {
-    // Each owner's OWN window end: two recipients' windows need not close together, and the
-    // drain takes the window it names.
-    const owned: { readonly id: string; readonly endsAt: number }[] = [];
-    let endsAt = 0;
-    for (const recipient of allowed) {
-      const bucket = await digest.append({
+  // ONE STEP PER APPEND, and the step store is the fence: a completed append is never redone, so
+  // the same event never lands in a digest twice. One step for the whole pass re-ran every append
+  // when any one failed, and the window a re-run append had joined may already have been drained
+  // and deleted by its owner — nothing in the store remembered it, so the event went out again in
+  // a second digest. The appender id is the store's own defence behind the step: an append whose
+  // write committed but whose answer was lost, or a run whose step history is gone, gets back the
+  // window it already landed in — `opened` included — for as long as that window exists.
+  // Each owner's OWN window end: two recipients' windows need not close together, and the drain
+  // takes the window it names.
+  const opened: { owned: { readonly id: string; readonly endsAt: number }[]; endsAt: number } = {
+    owned: [],
+    endsAt: 0,
+  };
+  for (const recipient of allowed) {
+    const bucket = await step.run(`digest:${channel.name}:${recipient.id}`, () =>
+      digest.append({
         slot: slotFor(recipient.id),
         event,
         windowMs,
         now: ctx.now(),
-      });
-      if (!bucket.opened) continue;
-      owned.push({ id: recipient.id, endsAt: bucket.endsAt });
-      endsAt = Math.max(endsAt, bucket.endsAt);
-    }
-    return { owned, endsAt };
-  });
+        appender: `${runId}:${recipient.id}`,
+      }),
+    );
+    if (!bucket.opened) continue;
+    opened.owned.push({ id: recipient.id, endsAt: bucket.endsAt });
+    opened.endsAt = Math.max(opened.endsAt, bucket.endsAt);
+  }
 
   tally.digested += allowed.length - opened.owned.length;
   if (opened.owned.length === 0) return;

package/src/fanout-walk.ts

@@ -21,6 +21,8 @@ export interface Walk<Params> {
   readonly event: NotifyEvent<Params>;
   readonly audience: readonly Recipient[];
   readonly ctx: Ctx;
+  /** The job run's id, which every retry of it keeps — what names this run's digest appends. */
+  readonly runId: string;
   readonly step: StepApi;
   readonly tally: Tally;
 }

package/src/fanout.ts

@@ -22,7 +22,7 @@ export async function runFanout<Params>(
   plan: NotifyPlan<Params>,
   args: JobRunArgs<NotifyPayload<Params>>,
 ): Promise<NotifyReport> {
-  const { input, step, ctx } = args;
+  const { input, step, ctx, runId } = 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
@@ -49,7 +49,7 @@ export async function runFanout<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 };
+  const walk: Walk<Params> = { plan, event, audience, ctx, runId, 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.

package/src/inbox-pg.ts

@@ -2,7 +2,7 @@
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
 import type { PgExecutor } from '@ultimat3/core';
-import { finiteCount, isUuid, uuid } from '@ultimat3/core';
+import { finiteCount, isUuid, uuidV7 } from '@ultimat3/core';
 import type { InboxRow, InboxStore, InboxWrite } from './inbox';
 import { DEFAULT_INBOX_PAGE } from './inbox';
 
@@ -59,7 +59,7 @@ where recipient = $2 and notifier = $3 and key = $4
  * `unique (recipient, notifier, key)`, so the order is total and a bounded page cannot drop or
  * repeat a row when two notifications land in the same millisecond.
  *
- * `collate "C"` and not the column's collation: `createMemoryInboxStore` compares the same two
+ * `collate "C"` and not the column's collation: `memoryInboxStore` compares the same two
  * columns by CODE POINT, and a database initialised under an ICU or a `en_US.UTF-8` collation
  * orders text by locale rules — case-insensitively, ignoring punctuation at the first level — so
  * the two stores would disagree on exactly the Unicode keys nobody writes a test for. `id` was the
@@ -130,7 +130,7 @@ const toRow = (row: InboxDbRow): InboxRow => ({
   readAt: row.read_at === null ? null : asDate(row.read_at),
 });
 
-export interface PgInboxStoreOptions {
+export interface PostgresInboxStoreOptions {
   readonly executor: PgExecutor;
   /**
    * Ids for new rows. A `random = Math.random` default parameter is this repo's injectable seam
@@ -153,16 +153,16 @@ export interface InboxPurgeBefore {
 
 /**
  * The Postgres inbox's own wider type. `purgeBefore` is HERE and not on `InboxStore` for the
- * reason `PgDeliveryLedger.purgeExpired` is not on `DeliveryLedger`: adding a method to the seam
+ * reason `PostgresDeliveryLedger.purgeExpired` is not on `DeliveryLedger`: adding a method to the seam
  * every implementation must satisfy is a breaking change for an app that wrote its own.
  */
-export interface PgInboxStore extends InboxStore {
+export interface PostgresInboxStore extends InboxStore {
   purgeBefore(before: InboxPurgeBefore): Promise<number>;
 }
 
-export function createPgInboxStore(options: PgInboxStoreOptions): PgInboxStore {
+export function postgresInboxStore(options: PostgresInboxStoreOptions): PostgresInboxStore {
   const { executor } = options;
-  const newId = options.newId ?? uuid;
+  const newId = options.newId ?? uuidV7;
   return {
     async add(write: InboxWrite) {
       const rows = await executor.query<InboxDbRow>(SQL_NOTIFY_INBOX_ADD, [
@@ -184,7 +184,7 @@ export function createPgInboxStore(options: PgInboxStoreOptions): PgInboxStore {
       // what a driver does with a `NaN` parameter is the driver's business — the memory store beside
       // it answered `[]` for the same input. `??` cannot see it, because `NaN` is not nullish.
       const limit = finiteCount(
-        'createPgInboxStore',
+        'postgresInboxStore',
         'limit',
         query.limit ?? DEFAULT_INBOX_PAGE,
         0,

package/src/inbox.ts

@@ -69,8 +69,8 @@ const compareText = (a: string, b: string): number => {
  * The tail key both stores order on: `(notifier, key)`, which is unique within a recipient because
  * `add` is idempotent on `(recipient, notifier, key)` and the Postgres table declares that UNIQUE.
  *
- * `id` cannot be it, and that is the whole reason this exists. `createPgInboxStore` mints a UUIDv7
- * and Postgres orders `uuid` by its 16 BYTES; `createMemoryInboxStore` derives its id from
+ * `id` cannot be it, and that is the whole reason this exists. `postgresInboxStore` mints a UUIDv7
+ * and Postgres orders `uuid` by its 16 BYTES; `memoryInboxStore` derives its id from
  * `JSON.stringify([recipient, notifier, key])` and orders it by code point. Two total orders that
  * agree on nothing — so two notifications written in one millisecond came back in one order in dev
  * and the other in production, and a bounded page dropped one and repeated the other on exactly the
@@ -88,7 +88,7 @@ const idOf = (write: { recipient: string; notifier: string; key: string }): stri
  * memory ledger — a ledger that forgets a row starts sending duplicates, where an inbox that
  * forgets one just loses a message nobody was going to read after the restart anyway.
  */
-export function createMemoryInboxStore(): MemoryInboxStore {
+export function memoryInboxStore(): MemoryInboxStore {
   const rows = new Map<string, InboxRow>();
 
   // `(createdAt desc, notifier, key)` — the same TOTAL order `SQL_NOTIFY_INBOX_PAGE` takes, and
@@ -122,18 +122,13 @@ export function createMemoryInboxStore(): MemoryInboxStore {
       return Promise.resolve(row);
     },
     // `async` and not `Promise.resolve`, so a refused `limit` REJECTS here exactly as it does in
-    // `createPgInboxStore`: two drivers behind one interface must not answer one question two ways,
+    // `postgresInboxStore`: two drivers behind one interface must not answer one question two ways,
     // and a sync throw against a rejected promise is a difference a caller can see.
     async list(query) {
       // `slice(0, NaN)` is `[]` — an empty inbox reported as the whole of it — and
       // `slice(0, Infinity)` is every row the recipient ever received, which is the unbounded read
       // `limit`'s own doc forbids. `??` reaches neither: `NaN` is not nullish.
-      const limit = finiteCount(
-        'createMemoryInboxStore',
-        'limit',
-        query.limit ?? DEFAULT_INBOX_PAGE,
-        0,
-      );
+      const limit = finiteCount('memoryInboxStore', 'limit', query.limit ?? DEFAULT_INBOX_PAGE, 0);
       return own(query.recipient)
         .filter((row) => query.unreadOnly !== true || row.readAt === null)
         .slice(0, limit);

package/src/index.ts

@@ -16,7 +16,7 @@ export type {
   DeliveryArgs,
   NotifyChannel,
 } from './channel';
-export { bulkChannel, channel, isBulkChannel } from './channel';
+export { bulkChannel, deliveryChannel, isBulkChannel } from './channel';
 export type { InAppChannelOptions } from './channel-in-app';
 export { IN_APP_CHANNEL, inAppChannel } from './channel-in-app';
 export type { MailChannelOptions, Mailer, NotifyMail } from './channel-mail';
@@ -28,11 +28,11 @@ export type {
   DigestStore,
   MemoryDigestStore,
 } from './digest';
-export { createMemoryDigestStore } from './digest';
-export type { PgDigestStore, PgDigestStoreOptions } from './digest-pg';
+export { memoryDigestStore } from './digest';
+export type { PostgresDigestStore, PostgresDigestStoreOptions } from './digest-pg';
 export {
-  createPgDigestStore,
   DEFAULT_DIGEST_RETENTION_MS,
+  postgresDigestStore,
   SQL_NOTIFY_DIGESTS_TABLE,
 } from './digest-pg';
 export type { NotifyErrorCode } from './errors';
@@ -49,12 +49,10 @@ export {
 // @ultimat3/jobs: a second way to execute a fan-out would bypass the job the factory built, and
 // with it the retry policy, the cancellation and the manifest row.
 export type { InboxQuery, InboxRow, InboxStore, InboxWrite, MemoryInboxStore } from './inbox';
-export { createMemoryInboxStore, DEFAULT_INBOX_PAGE } from './inbox';
-export type { InboxPurgeBefore, PgInboxStore, PgInboxStoreOptions } from './inbox-pg';
+export { DEFAULT_INBOX_PAGE, memoryInboxStore } from './inbox';
+export type { InboxPurgeBefore, PostgresInboxStore, PostgresInboxStoreOptions } from './inbox-pg';
 export {
-  createPgInboxStore,
-  SQL_NOTIFY_INBOX_MARK_READ,
-  SQL_NOTIFY_INBOX_PAGE,
+  postgresInboxStore,
   SQL_NOTIFY_INBOX_TABLE,
 } from './inbox-pg';
 export type {
@@ -63,17 +61,16 @@ export type {
   DeliveryRecord,
   DeliveryStatus,
   MemoryDeliveryLedger,
-  MemoryLedgerOptions,
+  MemoryDeliveryLedgerOptions,
 } from './ledger';
 export {
-  createMemoryDeliveryLedger,
   DELIVERY_STATUSES,
   isDeliveryStatus,
+  memoryDeliveryLedger,
 } from './ledger';
-export type { PgDeliveryLedger, PgDeliveryLedgerOptions } from './ledger-pg';
+export type { PostgresDeliveryLedger, PostgresDeliveryLedgerOptions } from './ledger-pg';
 export {
-  createPgDeliveryLedger,
-  SQL_NOTIFY_CLAIM,
+  postgresDeliveryLedger,
   SQL_NOTIFY_DELIVERIES_TABLE,
 } from './ledger-pg';
 export type { NotifyEvent, Recipient } from './notification';
@@ -93,7 +90,7 @@ export type {
 } from './plan';
 export { toDurationMs } from './plan';
 export type { MemoryPreferenceStore, PreferenceQuery, PreferenceStore } from './preferences';
-export { allowAllPreferences, createMemoryPreferenceStore } from './preferences';
+export { allowAllPreferences, memoryPreferenceStore } from './preferences';
 export { purgeNotifyDeliveries, purgeNotifyDigests, purgeNotifyInbox } from './retention';
 export type { InstalledNotifyStores, NotifyStores } from './stores';
 export {

package/src/ledger-pg.ts

@@ -102,14 +102,14 @@ delete from x_notify_deliveries where at < $1
  */
 const SQL_NOTIFY_DELIVERIES_PURGE_COUNTED = `${SQL_NOTIFY_DELIVERIES_PURGE} returning key`;
 
-export interface PgDeliveryLedgerOptions {
+export interface PostgresDeliveryLedgerOptions {
   readonly executor: PgExecutor;
   /**
    * How long a settled claim is kept. Defaults to `DEFAULT_DELIVERY_WINDOW_MS`.
    *
    * NEVER SHORTER THAN YOUR IDEMPOTENCY WINDOW, and this is the one dangerous direction: a job
    * replayed inside the idempotency window, against a delivery claim that has already been
-   * purged, claims cleanly and sends the notification a second time. `createPgDeliveryLedger({
+   * purged, claims cleanly and sends the notification a second time. `postgresDeliveryLedger({
    * executor, windowMs: idempotency.windowMs })` makes that impossible by construction rather
    * than by two defaults that happen to agree.
    */
@@ -125,15 +125,17 @@ export const DEFAULT_DELIVERY_WINDOW_MS = 24 * 60 * 60 * 1000;
  * seam every implementation must satisfy is a breaking change for an app that wrote its own.
  * Exactly the shape `PostgresIdempotencyStore` already has.
  */
-export interface PgDeliveryLedger extends DeliveryLedger {
+export interface PostgresDeliveryLedger extends DeliveryLedger {
   readonly windowMs: number;
   purgeExpired(nowMs: number): Promise<number>;
 }
 
-export function createPgDeliveryLedger(options: PgDeliveryLedgerOptions): PgDeliveryLedger {
+export function postgresDeliveryLedger(
+  options: PostgresDeliveryLedgerOptions,
+): PostgresDeliveryLedger {
   const { executor } = options;
   const windowMs = finiteCount(
-    'createPgDeliveryLedger',
+    'postgresDeliveryLedger',
     'windowMs',
     options.windowMs ?? DEFAULT_DELIVERY_WINDOW_MS,
     1,

package/src/ledger.ts

@@ -62,7 +62,7 @@ export interface DeliveryLedger {
 const keyOf = (claim: DeliveryClaim): string =>
   JSON.stringify([claim.notifier, claim.key, claim.recipient, claim.channel]);
 
-export interface MemoryLedgerOptions {
+export interface MemoryDeliveryLedgerOptions {
   /**
    * Rows kept before the oldest is evicted. A process-local ledger is a DEV ledger — it forgets
    * on restart and it is private to one replica — so it is bounded rather than allowed to grow
@@ -82,11 +82,11 @@ export interface MemoryDeliveryLedger extends DeliveryLedger {
 
 /**
  * The default, and honest about what it is: one process, no durability. Installed by a test and by
- * `x dev`; a deployment with more than one replica needs `createPgDeliveryLedger`, because a claim
+ * `x dev`; a deployment with more than one replica needs `postgresDeliveryLedger`, because a claim
  * this replica took is invisible to the one that replays the job.
  */
-export function createMemoryDeliveryLedger(
-  options: MemoryLedgerOptions = {},
+export function memoryDeliveryLedger(
+  options: MemoryDeliveryLedgerOptions = {},
 ): MemoryDeliveryLedger {
   // `while (rows.size > max)` is the eviction, so a `max` that is not a number is not a large cap
   // — it is no cap, and this ledger grows into the heap of a process that was told it was bounded.
@@ -94,7 +94,7 @@ export function createMemoryDeliveryLedger(
   // here intact. A floor of 1 because a ledger that keeps zero rows cannot refuse a replay, which
   // is its one job, and it fails at it silently.
   const max = finiteCount(
-    'createMemoryDeliveryLedger',
+    'memoryDeliveryLedger',
     'max',
     options.max ?? DEFAULT_MAX_DELIVERY_RECORDS,
     1,

package/src/preferences.ts

@@ -52,7 +52,7 @@ const optOutKey = (recipient: string, notifier: string, channel: string): string
  * A test double and a dev store, not a product. Real preferences live in the app's own table
  * beside the taxonomy that names them; this exists so the gate can be exercised without one.
  */
-export function createMemoryPreferenceStore(): MemoryPreferenceStore {
+export function memoryPreferenceStore(): MemoryPreferenceStore {
   const denied = new Set<string>();
   return {
     allows(query) {

package/src/retention.ts

@@ -3,15 +3,15 @@
 // owns the hourly sweep, so the sweep cannot hold the stores — it can only ask, per attempt, what
 // is installed now. Same shape and the same reason as `purgeAuthLimits()`.
 
-import type { PgDigestStore } from './digest-pg';
-import type { InboxPurgeBefore, PgInboxStore } from './inbox-pg';
-import type { PgDeliveryLedger } from './ledger-pg';
+import type { PostgresDigestStore } from './digest-pg';
+import type { InboxPurgeBefore, PostgresInboxStore } from './inbox-pg';
+import type { PostgresDeliveryLedger } from './ledger-pg';
 import { notifyStores } from './stores';
 
 /**
  * Whether the installed store can delete by age at all.
  *
- * A DECLARED capability check, never duck typing: `PgInboxStore` and `PgDeliveryLedger` widen the
+ * A DECLARED capability check, never duck typing: `PostgresInboxStore` and `PostgresDeliveryLedger` widen the
  * seam their memory siblings satisfy, so "has this method" is exactly "is this the Postgres one".
  * The memory stores deliberately have none — a heap map is bounded by process life, and adding the
  * method to `InboxStore`/`DeliveryLedger` would break every app that wrote its own implementation.
@@ -31,13 +31,13 @@ const purgeable = <T>(store: unknown, method: string): store is T =>
  */
 export async function purgeNotifyInbox(before: InboxPurgeBefore): Promise<number> {
   const store = notifyStores().inbox;
-  if (!purgeable<PgInboxStore>(store, 'purgeBefore')) return 0;
+  if (!purgeable<PostgresInboxStore>(store, 'purgeBefore')) return 0;
   return store.purgeBefore(before);
 }
 
 /**
  * Delete delivery claims past the ledger's own window, and answer how many. The window is the
- * LEDGER's, never this caller's: `createPgDeliveryLedger({ windowMs })` is where an app states it,
+ * LEDGER's, never this caller's: `postgresDeliveryLedger({ windowMs })` is where an app states it,
  * beside the statement that reads it, so there is one number rather than two that can disagree.
  *
  * `nowMs` is the job's clock for the reason `x_rate_limit`'s target states — `at` is written by
@@ -46,7 +46,7 @@ export async function purgeNotifyInbox(before: InboxPurgeBefore): Promise<number
  */
 export async function purgeNotifyDeliveries(nowMs: number): Promise<number> {
   const ledger = notifyStores().ledger;
-  if (!purgeable<PgDeliveryLedger>(ledger, 'purgeExpired')) return 0;
+  if (!purgeable<PostgresDeliveryLedger>(ledger, 'purgeExpired')) return 0;
   return ledger.purgeExpired(nowMs);
 }
 
@@ -57,6 +57,6 @@ export async function purgeNotifyDeliveries(nowMs: number): Promise<number> {
  */
 export async function purgeNotifyDigests(nowMs: number): Promise<number> {
   const digest = notifyStores().digest;
-  if (!purgeable<PgDigestStore>(digest, 'purgeExpired')) return 0;
+  if (!purgeable<PostgresDigestStore>(digest, 'purgeExpired')) return 0;
   return digest.purgeExpired(nowMs);
 }

package/src/stores.ts

@@ -9,13 +9,13 @@ import type { DigestStore } from './digest';
 import { NotifyStoreMissingError } from './errors';
 import type { InboxStore } from './inbox';
 import type { DeliveryLedger } from './ledger';
-import { createMemoryDeliveryLedger } from './ledger';
+import { memoryDeliveryLedger } from './ledger';
 import type { PreferenceStore } from './preferences';
 import { allowAllPreferences } from './preferences';
 
 export interface NotifyStores {
   /**
-   * Defaults to `createMemoryDeliveryLedger()`. A default is correct here and nowhere else in this
+   * Defaults to `memoryDeliveryLedger()`. A default is correct here and nowhere else in this
    * interface: one process with one replica is genuinely deduped by a heap map, and the failure
    * mode of having none at all — a replayed attempt sending twice — is worse than the failure mode
    * of a dev default, which is a second send only after a restart.
@@ -39,7 +39,7 @@ export interface InstalledNotifyStores {
 }
 
 const defaults = (): InstalledNotifyStores => ({
-  ledger: createMemoryDeliveryLedger(),
+  ledger: memoryDeliveryLedger(),
   inbox: undefined,
   preferences: allowAllPreferences(),
   digest: undefined,
@@ -51,7 +51,7 @@ let installed: InstalledNotifyStores = defaults();
  * `RuntimeOverrides` exists to refuse, and a merge would hide the second call's omissions. */
 export function setNotifyStores(stores: NotifyStores): void {
   installed = {
-    ledger: stores.ledger ?? createMemoryDeliveryLedger(),
+    ledger: stores.ledger ?? memoryDeliveryLedger(),
     inbox: stores.inbox,
     preferences: stores.preferences ?? allowAllPreferences(),
     digest: stores.digest,