@ultimat3/notify 12.0.0

package/src/inbox-pg.ts

@@ -0,0 +1,162 @@
+// The shared in-app inbox: one Postgres table, applied by the boot the way `x_jobs` is.
+// Statements are spelled out so an agent can run the exact one it saw in a log.
+
+import { uuid } from '@ultimat3/core';
+import type { PgExecutor } from '@ultimat3/jobs';
+import type { InboxRow, InboxStore, InboxWrite } from './inbox';
+import { DEFAULT_INBOX_PAGE } from './inbox';
+
+/**
+ * `unique (recipient, notifier, key)` is what makes `add` idempotent, and it is the same identity
+ * the delivery ledger claims on — one notification, one row, however many times the job replays.
+ *
+ * The unread badge wants a PARTIAL index on `read_at is null`, which is the query that runs on
+ * every page load. It is spelled out here because this table is DDL rather than an `entity()`
+ * declaration, so nothing has to work around the invariant DSL's missing null predicate.
+ */
+export const SQL_NOTIFY_INBOX_TABLE = `
+create table if not exists x_notify_inbox (
+  id         uuid        primary key,
+  recipient  text        not null,
+  notifier   text        not null,
+  key        text        not null,
+  params     jsonb       not null,
+  created_at timestamptz not null default now(),
+  seen_at    timestamptz,
+  read_at    timestamptz,
+  unique (recipient, notifier, key)
+);
+
+create index if not exists x_notify_inbox_page_idx
+  on x_notify_inbox (recipient, created_at desc, id);
+
+create index if not exists x_notify_inbox_unread_idx
+  on x_notify_inbox (recipient) where read_at is null;
+`;
+
+const COLUMNS = 'id, recipient, notifier, key, params, created_at, seen_at, read_at';
+
+/**
+ * Convergent: a second write of the same notification returns the FIRST row rather than moving
+ * its timestamps, so replaying the job leaves a message the user already read still read.
+ */
+export const SQL_NOTIFY_INBOX_ADD = `
+with inserted as (
+  insert into x_notify_inbox (id, recipient, notifier, key, params, created_at)
+  values ($1, $2, $3, $4, $5, $6)
+  on conflict (recipient, notifier, key) do nothing
+  returning ${COLUMNS}
+)
+select ${COLUMNS} from inserted
+union all
+select ${COLUMNS} from x_notify_inbox
+where recipient = $2 and notifier = $3 and key = $4
+  and not exists (select 1 from inserted)
+`;
+
+/** Newest first, `(created_at desc, id)` — the tail key is unique, so the order is total and a
+ * bounded page cannot drop or repeat a row when two notifications land in the same millisecond. */
+export const SQL_NOTIFY_INBOX_PAGE = `
+select ${COLUMNS} from x_notify_inbox
+where recipient = $1 and ($2::boolean is not true or read_at is null)
+order by created_at desc, id
+limit $3
+`;
+
+export const SQL_NOTIFY_INBOX_UNREAD = `
+select count(*)::int as unread from x_notify_inbox where recipient = $1 and read_at is null
+`;
+
+/** Scoped by recipient, so an id somebody else named is not found and not written. */
+export const SQL_NOTIFY_INBOX_MARK_READ = `
+update x_notify_inbox set read_at = $3
+where recipient = $1 and id = any($2::uuid[]) and read_at is null
+returning id
+`;
+
+export const SQL_NOTIFY_INBOX_MARK_SEEN = `
+update x_notify_inbox set seen_at = $2 where recipient = $1 and seen_at is null returning id
+`;
+
+interface InboxDbRow {
+  readonly id: string;
+  readonly recipient: string;
+  readonly notifier: string;
+  readonly key: string;
+  readonly params: unknown;
+  readonly created_at: Date | string;
+  readonly seen_at: Date | string | null;
+  readonly read_at: Date | string | null;
+}
+
+const asDate = (value: Date | string): Date => (value instanceof Date ? value : new Date(value));
+
+const toRow = (row: InboxDbRow): InboxRow => ({
+  id: row.id,
+  recipient: row.recipient,
+  notifier: row.notifier,
+  key: row.key,
+  params: row.params,
+  createdAt: asDate(row.created_at),
+  seenAt: row.seen_at === null ? null : asDate(row.seen_at),
+  readAt: row.read_at === null ? null : asDate(row.read_at),
+});
+
+export interface PgInboxStoreOptions {
+  readonly executor: PgExecutor;
+  /**
+   * Ids for new rows. A `random = Math.random` default parameter is this repo's injectable seam
+   * and this is the same shape: a test that needs a fixed id passes one, and shipped source never
+   * calls a die it cannot control.
+   */
+  readonly newId?: () => string;
+}
+
+export function createPgInboxStore(options: PgInboxStoreOptions): InboxStore {
+  const { executor } = options;
+  const newId = options.newId ?? uuid;
+  return {
+    async add(write: InboxWrite) {
+      const rows = await executor.query<InboxDbRow>(SQL_NOTIFY_INBOX_ADD, [
+        newId(),
+        write.recipient,
+        write.notifier,
+        write.key,
+        JSON.stringify(write.params),
+        write.createdAt,
+      ]);
+      const row = rows[0];
+      // The statement's `union all` always answers exactly one row — the inserted one, or the
+      // existing one it conflicted with. Nothing back means the row was deleted between the two
+      // halves, which is a race no caller can repair, so it reads as the write that just happened.
+      return row === undefined ? { id: newId(), ...write, seenAt: null, readAt: null } : toRow(row);
+    },
+    async list(query) {
+      const rows = await executor.query<InboxDbRow>(SQL_NOTIFY_INBOX_PAGE, [
+        query.recipient,
+        query.unreadOnly === true,
+        query.limit ?? DEFAULT_INBOX_PAGE,
+      ]);
+      return rows.map(toRow);
+    },
+    async unreadCount(recipient) {
+      const rows = await executor.query<{ unread: number }>(SQL_NOTIFY_INBOX_UNREAD, [recipient]);
+      return rows[0]?.unread ?? 0;
+    },
+    async markRead(input) {
+      const rows = await executor.query<{ id: string }>(SQL_NOTIFY_INBOX_MARK_READ, [
+        input.recipient,
+        [...input.ids],
+        input.at,
+      ]);
+      return rows.length;
+    },
+    async markSeen(input) {
+      const rows = await executor.query<{ id: string }>(SQL_NOTIFY_INBOX_MARK_SEEN, [
+        input.recipient,
+        input.at,
+      ]);
+      return rows.length;
+    },
+  };
+}

package/src/inbox.ts

@@ -0,0 +1,131 @@
+// The in-app inbox: one row per (recipient, notification), with `seenAt` and `readAt`.
+//
+// SEEN and READ are two facts, exactly as `noticed` has them: seen is "the badge showed it", read
+// is "they opened it". Collapsing them loses the only thing a badge can be derived from — and the
+// count is DERIVED from `readAt is null`, never stored, because a stored counter and a row set
+// drift the first time a write half-lands.
+
+export interface InboxRow {
+  /** Stable within a store. `(recipient, notifier, key)` is what makes it unique. */
+  readonly id: string;
+  readonly recipient: string;
+  readonly notifier: string;
+  readonly key: string;
+  /** The notifier's validated params, as written. Denormalised on purpose: an inbox row records
+   * what it said at the time, so deleting the thing it points at leaves the row readable. */
+  readonly params: unknown;
+  readonly createdAt: Date;
+  readonly seenAt: Date | null;
+  readonly readAt: Date | null;
+}
+
+export interface InboxQuery {
+  readonly recipient: string;
+  /** Bounded everywhere: an inbox is a page, never "everything since you signed up". */
+  readonly limit?: number | undefined;
+  /** `noticed`'s `unread` scope. Omitted reads the whole page. */
+  readonly unreadOnly?: boolean | undefined;
+}
+
+export interface InboxWrite {
+  readonly recipient: string;
+  readonly notifier: string;
+  readonly key: string;
+  readonly params: unknown;
+  readonly createdAt: Date;
+}
+
+export interface InboxStore {
+  /**
+   * Idempotent on `(recipient, notifier, key)`. Answers the row as it now stands, so a replay
+   * gets the FIRST write's timestamps back rather than moving them — the same convergence rule
+   * `markRead` follows, and what makes an at-least-once job safe to point at this store.
+   */
+  add(write: InboxWrite): Promise<InboxRow>;
+  list(query: InboxQuery): Promise<readonly InboxRow[]>;
+  unreadCount(recipient: string): Promise<number>;
+  /** `noticed`'s `mark_as_read`, scoped: an id belonging to somebody else is simply absent. */
+  markRead(input: { recipient: string; ids: readonly string[]; at: Date }): Promise<number>;
+  /** Every unseen row for this recipient — what a rendered badge asserts. */
+  markSeen(input: { recipient: string; at: Date }): Promise<number>;
+}
+
+export const DEFAULT_INBOX_PAGE = 50;
+
+export interface MemoryInboxStore extends InboxStore {
+  readonly size: number;
+  clear(): void;
+}
+
+const idOf = (write: { recipient: string; notifier: string; key: string }): string =>
+  JSON.stringify([write.recipient, write.notifier, write.key]);
+
+/**
+ * The dev inbox: one process, no durability, unbounded. Unbounded deliberately and unlike the
+ * 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 {
+  const rows = new Map<string, InboxRow>();
+
+  const own = (recipient: string): InboxRow[] =>
+    [...rows.values()]
+      .filter((row) => row.recipient === recipient)
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+
+  return {
+    get size(): number {
+      return rows.size;
+    },
+    add(write) {
+      const id = idOf(write);
+      const existing = rows.get(id);
+      if (existing !== undefined) return Promise.resolve(existing);
+      const row: InboxRow = {
+        id,
+        recipient: write.recipient,
+        notifier: write.notifier,
+        key: write.key,
+        params: write.params,
+        createdAt: write.createdAt,
+        seenAt: null,
+        readAt: null,
+      };
+      rows.set(id, row);
+      return Promise.resolve(row);
+    },
+    list(query) {
+      const page = own(query.recipient)
+        .filter((row) => query.unreadOnly !== true || row.readAt === null)
+        .slice(0, query.limit ?? DEFAULT_INBOX_PAGE);
+      return Promise.resolve(page);
+    },
+    unreadCount(recipient) {
+      return Promise.resolve(own(recipient).filter((row) => row.readAt === null).length);
+    },
+    markRead(input) {
+      let marked = 0;
+      for (const id of input.ids) {
+        const row = rows.get(id);
+        // The recipient check is the SCOPE, not an optimisation: it is what makes an id somebody
+        // else named simply absent, so no write can reach a row that is not the caller's own.
+        if (row === undefined || row.recipient !== input.recipient || row.readAt !== null) continue;
+        rows.set(id, { ...row, readAt: input.at });
+        marked += 1;
+      }
+      return Promise.resolve(marked);
+    },
+    markSeen(input) {
+      let marked = 0;
+      for (const row of own(input.recipient)) {
+        if (row.seenAt !== null) continue;
+        rows.set(row.id, { ...row, seenAt: input.at });
+        marked += 1;
+      }
+      return Promise.resolve(marked);
+    },
+    clear() {
+      rows.clear();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+// Public API of @ultimat3/notify. Explicit re-exports only — no `export *`.
+//
+// ONE entry point, deliberately: every module here runs on the server. There is no browser half to
+// split off, because the only client-side surface a notification has is the inbox rendered by a
+// page and the socket `@ultimat3/realtime` already owns.
+
+/** Re-exported so a `notifier` file needs one import, not two. Same object as schema's. */
+export type { Infer } from '@ultimat3/schema';
+export { t } from '@ultimat3/schema';
+export type { AttemptInput } from './attempt';
+export { attemptDelivery } from './attempt';
+export type {
+  AnyNotifyChannel,
+  BulkDeliveryArgs,
+  BulkNotifyChannel,
+  DeliveryArgs,
+  NotifyChannel,
+} from './channel';
+export { bulkChannel, channel, 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';
+export { MAIL_CHANNEL, mailChannel } from './channel-mail';
+export type {
+  DigestAppend,
+  DigestBucket,
+  DigestSlot,
+  DigestStore,
+  MemoryDigestStore,
+} from './digest';
+export { createMemoryDigestStore } from './digest';
+export type { NotifyErrorCode } from './errors';
+export {
+  NOTIFY_ERROR_CODES,
+  NotifyChannelDuplicateError,
+  NotifyChannelsEmptyError,
+  NotifyDeliveryFailedError,
+  NotifyDigestUnsupportedError,
+  NotifyFanoutTooWideError,
+  NotifyStoreMissingError,
+} from './errors';
+// `runFanout` is deliberately absent, for the reason `registerJob` is absent from
+// @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 { PgInboxStoreOptions } from './inbox-pg';
+export {
+  createPgInboxStore,
+  SQL_NOTIFY_INBOX_ADD,
+  SQL_NOTIFY_INBOX_MARK_READ,
+  SQL_NOTIFY_INBOX_MARK_SEEN,
+  SQL_NOTIFY_INBOX_PAGE,
+  SQL_NOTIFY_INBOX_TABLE,
+  SQL_NOTIFY_INBOX_UNREAD,
+} from './inbox-pg';
+export type {
+  DeliveryClaim,
+  DeliveryLedger,
+  DeliveryRecord,
+  DeliveryStatus,
+  MemoryDeliveryLedger,
+  MemoryLedgerOptions,
+} from './ledger';
+export {
+  createMemoryDeliveryLedger,
+  DEFAULT_MAX_DELIVERY_RECORDS,
+  DELIVERY_STATUSES,
+  isDeliveryStatus,
+} from './ledger';
+export type { PgDeliveryLedgerOptions } from './ledger-pg';
+export {
+  createPgDeliveryLedger,
+  SQL_NOTIFY_CLAIM,
+  SQL_NOTIFY_DELIVERIES_TABLE,
+  SQL_NOTIFY_FIND,
+  SQL_NOTIFY_SETTLE,
+} from './ledger-pg';
+export type { NotifyEvent, Recipient } from './notification';
+export { recipientSchema } from './notification';
+export type { NotifierDefinition } from './notifier';
+export { DEFAULT_MAX_RECIPIENTS, notifier } from './notifier';
+export type {
+  ChannelDelivery,
+  DeliveryGate,
+  DigestWindow,
+  NotifyDuration,
+  NotifyPayload,
+  NotifyPlan,
+  NotifyReport,
+  RecipientArgs,
+  ResolvedDelivery,
+} from './plan';
+export { toDurationMs } from './plan';
+export type { MemoryPreferenceStore, PreferenceQuery, PreferenceStore } from './preferences';
+export { allowAllPreferences, createMemoryPreferenceStore } from './preferences';
+export type { InstalledNotifyStores, NotifyStores } from './stores';
+export {
+  notifyStores,
+  requireDigest,
+  requireInbox,
+  resetNotifyStores,
+  setNotifyStores,
+} from './stores';

package/src/ledger-pg.ts

@@ -0,0 +1,122 @@
+// The shared delivery ledger: one Postgres table, `insert … on conflict` for the atomicity.
+// Without it `replicas: 3` means a job replayed on another node sends a second copy of the same
+// notification — the claim this replica took lives in its own heap and nowhere else.
+//
+// Statements are spelled out so an agent can run the exact one it saw in a log.
+
+import type { PgExecutor } from '@ultimat3/jobs';
+import type { DeliveryClaim, DeliveryLedger, DeliveryRecord, DeliveryStatus } from './ledger';
+import { isDeliveryStatus } from './ledger';
+
+/**
+ * Applied the way `SQL_JOBS_TABLE` and `SQL_IDEMPOTENCY_TABLE` are — by the boot, not by an app
+ * migration. `create table if not exists` is a no-op against a database that already has it, so a
+ * new column is added by `alter table … add column if not exists` and never by editing the
+ * `create`.
+ *
+ * The unique key is an EXPRESSION index over `coalesce(recipient, '')` rather than a plain
+ * four-column one. A bulk channel's claim covers the whole audience and so stores a NULL
+ * recipient; NULLs are distinct in a unique index on every Postgres before 15, which would let
+ * one bulk send be claimed an unbounded number of times. The stored value stays a true NULL —
+ * only the index reads it as `''`.
+ */
+export const SQL_NOTIFY_DELIVERIES_TABLE = `
+create table if not exists x_notify_deliveries (
+  notifier   text        not null,
+  key        text        not null,
+  recipient  text,
+  channel    text        not null,
+  status     text        not null default 'sending',
+  attempts   integer     not null default 1,
+  at         timestamptz not null default now()
+);
+
+create unique index if not exists x_notify_deliveries_claim_idx
+  on x_notify_deliveries (notifier, key, channel, coalesce(recipient, ''));
+
+create index if not exists x_notify_deliveries_at_idx on x_notify_deliveries (at);
+`;
+
+/**
+ * The claim, atomic in one statement. The `do update` fires ONLY for a row that is not already
+ * `sent`, so a returned row always means this caller owns the delivery and must send. No row back
+ * means the notification already went out and this attempt is a replay.
+ */
+export const SQL_NOTIFY_CLAIM = `
+insert into x_notify_deliveries (notifier, key, recipient, channel, status, attempts, at)
+values ($1, $2, $3, $4, 'sending', 1, $5)
+on conflict (notifier, key, channel, coalesce(recipient, ''))
+do update set attempts = x_notify_deliveries.attempts + 1, status = 'sending', at = excluded.at
+where x_notify_deliveries.status <> 'sent'
+returning attempts
+`;
+
+export const SQL_NOTIFY_SETTLE = `
+update x_notify_deliveries set status = $5, at = $6
+where notifier = $1 and key = $2 and channel = $4 and coalesce(recipient, '') = coalesce($3, '')
+`;
+
+export const SQL_NOTIFY_FIND = `
+select notifier, key, recipient, channel, status, attempts, at
+from x_notify_deliveries
+where notifier = $1 and key = $2 and channel = $4 and coalesce(recipient, '') = coalesce($3, '')
+`;
+
+interface DeliveryRow {
+  readonly notifier: string;
+  readonly key: string;
+  readonly recipient: string | null;
+  readonly channel: string;
+  readonly status: string;
+  readonly attempts: number;
+  readonly at: Date | string;
+}
+
+/** Positional in the order every statement above declares, so the four share one builder. */
+const argsOf = (claim: DeliveryClaim): readonly unknown[] => [
+  claim.notifier,
+  claim.key,
+  claim.recipient,
+  claim.channel,
+];
+
+export interface PgDeliveryLedgerOptions {
+  readonly executor: PgExecutor;
+}
+
+export function createPgDeliveryLedger(options: PgDeliveryLedgerOptions): DeliveryLedger {
+  const { executor } = options;
+  return {
+    async claim(claim, at) {
+      const rows = await executor.query<{ attempts: number }>(SQL_NOTIFY_CLAIM, [
+        ...argsOf(claim),
+        at,
+      ]);
+      return rows.length > 0;
+    },
+    async settle(claim, status, at) {
+      await executor.query(SQL_NOTIFY_SETTLE, [...argsOf(claim), status, at]);
+    },
+    async find(claim) {
+      const rows = await executor.query<DeliveryRow>(SQL_NOTIFY_FIND, argsOf(claim));
+      const row = rows[0];
+      return row === undefined ? undefined : toRecord(row);
+    },
+  };
+}
+
+/**
+ * A status column this package did not write — a hand-edited row, or a column an older version
+ * wrote — reads as `failed` rather than being cast through. Casting would let an unknown string
+ * flow out as a `DeliveryStatus` the type says it cannot be; `failed` is the safe reading, because
+ * only `sent` suppresses a resend and nothing else may be allowed to imply it.
+ */
+const toRecord = (row: DeliveryRow): DeliveryRecord => ({
+  notifier: row.notifier,
+  key: row.key,
+  recipient: row.recipient,
+  channel: row.channel,
+  status: (isDeliveryStatus(row.status) ? row.status : 'failed') satisfies DeliveryStatus,
+  attempts: row.attempts,
+  at: row.at instanceof Date ? row.at : new Date(row.at),
+});

package/src/ledger.ts

@@ -0,0 +1,136 @@
+// The delivery ledger: the row that makes a replayed attempt stop short of a second send.
+//
+// A `step.run` checkpoint is the FIRST layer and it is not enough on its own — a job body runs
+// before its checkpoint lands, so an attempt killed between the provider's 200 and the step write
+// replays the send. This is the second layer: the claim is taken atomically before the send, and a
+// claim that already reads `sent` answers `false` and the fan-out skips.
+
+export const DELIVERY_STATUSES = ['sending', 'sent', 'failed'] as const;
+
+export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
+
+/** A status column this package did not write is not a `DeliveryStatus`; the pg store reads one
+ * back on every `find` and must not cast an unknown string through the type that decides whether a
+ * notification is resent. */
+export const isDeliveryStatus = (value: unknown): value is DeliveryStatus =>
+  typeof value === 'string' && (DELIVERY_STATUSES as readonly string[]).includes(value);
+
+/**
+ * One delivery's identity: which notification, to whom, over which channel.
+ *
+ * `recipient` is `null` for a bulk channel and that is the whole difference between the two
+ * arities at this layer — one row for the audience rather than one per address.
+ */
+export interface DeliveryClaim {
+  readonly notifier: string;
+  /** The notifier's `key` for this run — what makes two invocations the same notification. */
+  readonly key: string;
+  readonly recipient: string | null;
+  readonly channel: string;
+}
+
+export interface DeliveryRecord extends DeliveryClaim {
+  readonly status: DeliveryStatus;
+  /** How many attempts have taken this claim. A `sent` row is never re-claimed, so this counts
+   * crashes and provider failures, which is exactly what makes a flapping channel visible. */
+  readonly attempts: number;
+  readonly at: Date;
+}
+
+export interface DeliveryLedger {
+  /**
+   * Take ownership of this delivery. `true` means send; `false` means a completed row already
+   * exists and this attempt must not send.
+   *
+   * A row left `sending` by a killed process IS re-claimable, deliberately: the alternative is a
+   * notification that silently never arrives because the process that owned it died. At-least-once
+   * is the guarantee this package offers and the honest one — `settle` is what closes the window.
+   */
+  claim(claim: DeliveryClaim, at: Date): Promise<boolean>;
+  /** Record the outcome. Only `sent` blocks a future claim. */
+  settle(claim: DeliveryClaim, status: DeliveryStatus, at: Date): Promise<void>;
+  find(claim: DeliveryClaim): Promise<DeliveryRecord | undefined>;
+}
+
+/**
+ * The tuple as one string. `JSON.stringify` of an ARRAY rather than a joined separator: a
+ * recipient id or a channel name containing the separator would otherwise collide two distinct
+ * deliveries into one ledger row, and the failure mode is a notification nobody ever receives.
+ */
+const keyOf = (claim: DeliveryClaim): string =>
+  JSON.stringify([claim.notifier, claim.key, claim.recipient, claim.channel]);
+
+export interface MemoryLedgerOptions {
+  /**
+   * 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
+   * into the heap, and it says so by publishing `size`.
+   */
+  readonly max?: number;
+}
+
+export const DEFAULT_MAX_DELIVERY_RECORDS = 10_000;
+
+export interface MemoryDeliveryLedger extends DeliveryLedger {
+  readonly size: number;
+  /** Rows evicted for the cap. Non-zero means this ledger can no longer refuse a replay. */
+  readonly dropped: number;
+  clear(): void;
+}
+
+/**
+ * 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
+ * this replica took is invisible to the one that replays the job.
+ */
+export function createMemoryDeliveryLedger(
+  options: MemoryLedgerOptions = {},
+): MemoryDeliveryLedger {
+  const max = options.max ?? DEFAULT_MAX_DELIVERY_RECORDS;
+  const rows = new Map<string, DeliveryRecord>();
+  let dropped = 0;
+
+  const evict = (): void => {
+    while (rows.size > max) {
+      const oldest = rows.keys().next();
+      if (oldest.done === true) return;
+      rows.delete(oldest.value);
+      dropped += 1;
+    }
+  };
+
+  return {
+    get size(): number {
+      return rows.size;
+    },
+    get dropped(): number {
+      return dropped;
+    },
+    claim(claim, at) {
+      const id = keyOf(claim);
+      const existing = rows.get(id);
+      if (existing?.status === 'sent') return Promise.resolve(false);
+      rows.set(id, {
+        ...claim,
+        status: 'sending',
+        attempts: (existing?.attempts ?? 0) + 1,
+        at,
+      });
+      evict();
+      return Promise.resolve(true);
+    },
+    settle(claim, status, at) {
+      const id = keyOf(claim);
+      const existing = rows.get(id);
+      rows.set(id, { ...claim, status, attempts: existing?.attempts ?? 1, at });
+      return Promise.resolve();
+    },
+    find(claim) {
+      return Promise.resolve(rows.get(keyOf(claim)));
+    },
+    clear() {
+      rows.clear();
+      dropped = 0;
+    },
+  };
+}