@ultimat3/notify 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -71,6 +71,7 @@ rather than hidden, and a durable store can close it.
 | `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 |
+| `retention.ts` | the two sweeps, read off the installed seam |
 | `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
@@ -81,13 +82,30 @@ off.
 | 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.
+| Durations | one vocabulary — `@ultimat3/time`'s. `toDurationMs` is a **narrowing** of `toMs`, never a copy of it: `toMs` screens finiteness and stops, because a negative or fractional duration is real there (`toSeconds(-3000)` is a tested `-3`); a `wait` and a digest `window` are counts of whole FORWARD milliseconds, and the refusal names which declaration was wrong since one notifier holds several. `plan-bounds.test.ts` calls BOTH on the same inputs — the two disagreed once (#372), when only this side was screened, and only a test that calls both can see it come back |
+
+## Retention
+
+Both tables are swept by the boot's hourly `x.purge` job, and neither store is handed to it:
+`setNotifyStores` is an APP's boot line that runs when the app's modules import, after the boot that
+installs the sweep. So `retention.ts` reads the seam **per attempt** — the same shape as
+`purgeAuthLimits()` — and answers `0` for a memory store or none at all, which is a boot that made a
+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_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`), never on `InboxStore`/`DeliveryLedger`: 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.
+
+`packages/cli/src/framework-schema.ts` applies both tables' DDL on every boot, **whether or not that
+boot calls `setNotifyStores`** — this file said it did not until 2026-08-27, which is a sentence that
+outlived its fact.
 
 Commands: `bun test packages/notify/src`, `bun run boundaries`,
 `bunx biome check packages/notify`.

package/README.md

@@ -105,13 +105,16 @@ import {
 } from '@ultimat3/notify';
 
 declare const executor: PgExecutor;   // `@ultimat3/cli`'s pgExecutorFor(client)
+declare const idempotency: { readonly windowMs: number };   // the boot's own store
 // 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 }),
+  // `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 }),
   digest: createMemoryDigestStore(),
   preferences: {
@@ -132,6 +135,33 @@ setNotifyStores({
 `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.
 
+## Retention
+
+Both tables grow with traffic, and the boot's hourly `x.purge` job sweeps both — but only against
+the **Postgres** stores. `createPgInboxStore` carries `purgeBefore` and `createPgDeliveryLedger`
+carries `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`), not
+on `InboxStore`/`DeliveryLedger`, 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_inbox` | `notify.inboxReadRetentionMs` / `notify.inboxUnreadRetentionMs` in `app.config.ts` | **neither** — never swept |
+
+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
+lives in **your** config and why there are two of them: read notices gone in a month with unread
+ones kept forever is the shape most apps want, and it is only expressible if the two windows are
+separate.
+
+```ts
+// app.config.ts
+notify: { inboxReadRetentionMs: 30 * 24 * 60 * 60 * 1000 }
+```
+
+A read row ages from `read_at` and an unread one from `created_at` — ageing a read row from
+`created_at` would delete a notification the moment the recipient opened an old one.
+
 ## Channels
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "16.0.0",
+  "version": "18.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.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/jobs": "16.0.0",
-    "@ultimat3/schema": "16.0.0",
-    "@ultimat3/time": "16.0.0"
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/schema": "18.0.0",
+    "@ultimat3/time": "18.0.0"
   }
 }

package/src/inbox-pg.ts

@@ -1,7 +1,7 @@
 // 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 { finiteCount, uuid } from '@ultimat3/core';
 import type { PgExecutor } from '@ultimat3/jobs';
 import type { InboxRow, InboxStore, InboxWrite } from './inbox';
 import { DEFAULT_INBOX_PAGE } from './inbox';
@@ -74,6 +74,23 @@ where recipient = $1 and id = any($2::uuid[]) and read_at is null
 returning id
 `;
 
+/**
+ * Both windows in ONE statement, and each half is inert when its window is absent: a `null`
+ * cutoff makes its `is not null` guard false, so the other half runs alone. One round trip, and
+ * — more importantly — no way to express "purge read rows" and "purge unread rows" as two
+ * statements that could disagree about which rows are which.
+ *
+ * A READ row ages from `read_at` and an UNREAD one from `created_at`. Ageing a read row from
+ * `created_at` would delete a notification the moment the recipient opened it, if it happened to
+ * be old — which is the opposite of what a read window means.
+ */
+export const SQL_NOTIFY_INBOX_PURGE = `
+delete from x_notify_inbox
+where ($1::timestamptz is not null and read_at is not null and read_at < $1)
+   or ($2::timestamptz is not null and read_at is null and created_at < $2)
+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
 `;
@@ -112,7 +129,27 @@ export interface PgInboxStoreOptions {
   readonly newId?: () => string;
 }
 
-export function createPgInboxStore(options: PgInboxStoreOptions): InboxStore {
+/**
+ * The two cutoffs, each `undefined` where its window is unset. Never a single window: the axiom-8
+ * objection to sweeping an inbox is only about UNREAD messages, so the two have to be separately
+ * expressible or an app that wants read notices gone in a month is forced to choose between
+ * deleting unread ones too and sweeping nothing.
+ */
+export interface InboxPurgeBefore {
+  readonly read?: Date | undefined;
+  readonly unread?: Date | undefined;
+}
+
+/**
+ * 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
+ * every implementation must satisfy is a breaking change for an app that wrote its own.
+ */
+export interface PgInboxStore extends InboxStore {
+  purgeBefore(before: InboxPurgeBefore): Promise<number>;
+}
+
+export function createPgInboxStore(options: PgInboxStoreOptions): PgInboxStore {
   const { executor } = options;
   const newId = options.newId ?? uuid;
   return {
@@ -132,10 +169,19 @@ export function createPgInboxStore(options: PgInboxStoreOptions): InboxStore {
       return row === undefined ? { id: newId(), ...write, seenAt: null, readAt: null } : toRow(row);
     },
     async list(query) {
+      // Screened here and not left to Postgres: this number is bound straight into `limit $3`, and
+      // 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',
+        'limit',
+        query.limit ?? DEFAULT_INBOX_PAGE,
+        0,
+      );
       const rows = await executor.query<InboxDbRow>(SQL_NOTIFY_INBOX_PAGE, [
         query.recipient,
         query.unreadOnly === true,
-        query.limit ?? DEFAULT_INBOX_PAGE,
+        limit,
       ]);
       return rows.map(toRow);
     },
@@ -151,6 +197,17 @@ export function createPgInboxStore(options: PgInboxStoreOptions): InboxStore {
       ]);
       return rows.length;
     },
+    async purgeBefore(before) {
+      // Neither window set is not an error and not a no-op to leave to Postgres: the statement
+      // would run, match nothing and cost a scan on every hourly sweep of every app that never
+      // configured retention, which is every app by default.
+      if (before.read === undefined && before.unread === undefined) return 0;
+      const rows = await executor.query<{ id: string }>(SQL_NOTIFY_INBOX_PURGE, [
+        before.read ?? null,
+        before.unread ?? null,
+      ]);
+      return rows.length;
+    },
     async markSeen(input) {
       const rows = await executor.query<{ id: string }>(SQL_NOTIFY_INBOX_MARK_SEEN, [
         input.recipient,

package/src/inbox.ts

@@ -5,6 +5,8 @@
 // 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.
 
+import { finiteCount } from '@ultimat3/core';
+
 export interface InboxRow {
   /** Stable within a store. `(recipient, notifier, key)` is what makes it unique. */
   readonly id: string;
@@ -94,11 +96,22 @@ export function createMemoryInboxStore(): MemoryInboxStore {
       rows.set(id, row);
       return Promise.resolve(row);
     },
-    list(query) {
-      const page = own(query.recipient)
+    // `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,
+    // 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,
+      );
+      return own(query.recipient)
         .filter((row) => query.unreadOnly !== true || row.readAt === null)
-        .slice(0, query.limit ?? DEFAULT_INBOX_PAGE);
-      return Promise.resolve(page);
+        .slice(0, limit);
     },
     unreadCount(recipient) {
       return Promise.resolve(own(recipient).filter((row) => row.readAt === null).length);

package/src/index.ts

@@ -44,13 +44,14 @@ export {
 // 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 type { InboxPurgeBefore, PgInboxStore, 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_PURGE,
   SQL_NOTIFY_INBOX_TABLE,
   SQL_NOTIFY_INBOX_UNREAD,
 } from './inbox-pg';
@@ -68,10 +69,12 @@ export {
   DELIVERY_STATUSES,
   isDeliveryStatus,
 } from './ledger';
-export type { PgDeliveryLedgerOptions } from './ledger-pg';
+export type { PgDeliveryLedger, PgDeliveryLedgerOptions } from './ledger-pg';
 export {
   createPgDeliveryLedger,
+  DEFAULT_DELIVERY_WINDOW_MS,
   SQL_NOTIFY_CLAIM,
+  SQL_NOTIFY_DELIVERIES_PURGE,
   SQL_NOTIFY_DELIVERIES_TABLE,
   SQL_NOTIFY_FIND,
   SQL_NOTIFY_SETTLE,
@@ -94,6 +97,7 @@ export type {
 export { toDurationMs } from './plan';
 export type { MemoryPreferenceStore, PreferenceQuery, PreferenceStore } from './preferences';
 export { allowAllPreferences, createMemoryPreferenceStore } from './preferences';
+export { purgeNotifyDeliveries, purgeNotifyInbox } from './retention';
 export type { InstalledNotifyStores, NotifyStores } from './stores';
 export {
   notifyStores,

package/src/ledger-pg.ts

@@ -4,6 +4,7 @@
 //
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
+import { finiteCount } from '@ultimat3/core';
 import type { PgExecutor } from '@ultimat3/jobs';
 import type { DeliveryClaim, DeliveryLedger, DeliveryRecord, DeliveryStatus } from './ledger';
 import { isDeliveryStatus } from './ledger';
@@ -80,13 +81,75 @@ const argsOf = (claim: DeliveryClaim): readonly unknown[] => [
   claim.channel,
 ];
 
+/**
+ * Delete every claim older than the window, and answer how many. `at` is the claim's own
+ * timestamp and `SQL_NOTIFY_SETTLE` moves it, so a row ages from its LAST attempt rather than its
+ * first — a delivery still being retried is never swept out from under the retry.
+ *
+ * Unconditional on status, deliberately. A `sending` row past the window belonged to a process
+ * that died and never came back; keeping it forever protects nothing, because a re-claim is
+ * already allowed on it (see `DeliveryLedger.claim`).
+ */
+export const SQL_NOTIFY_DELIVERIES_PURGE = `
+delete from x_notify_deliveries where at < $1
+`;
+
+/**
+ * The statement the store actually runs. A bare `delete` answers NO ROWS through `PgExecutor`, so
+ * a count read off it is zero forever — a sweep that reports it deleted nothing while deleting
+ * everything, which is indistinguishable in a log from a sweep that is not wired at all.
+ * `SQL_IDEMPOTENCY_PURGE` is spliced the same way for the same reason.
+ */
+const SQL_NOTIFY_DELIVERIES_PURGE_COUNTED = `${SQL_NOTIFY_DELIVERIES_PURGE} returning key`;
+
 export interface PgDeliveryLedgerOptions {
   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({
+   * executor, windowMs: idempotency.windowMs })` makes that impossible by construction rather
+   * than by two defaults that happen to agree.
+   */
+  readonly windowMs?: number | undefined;
 }
 
-export function createPgDeliveryLedger(options: PgDeliveryLedgerOptions): DeliveryLedger {
+/** 24 hours — the same default `postgresIdempotencyStore` carries, for the reason above. */
+export const DEFAULT_DELIVERY_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The Postgres ledger's own wider type. `purgeExpired` is HERE and not on `DeliveryLedger`
+ * because a heap map bounded by process life has nothing to delete, and adding a method to the
+ * 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 {
+  readonly windowMs: number;
+  purgeExpired(nowMs: number): Promise<number>;
+}
+
+export function createPgDeliveryLedger(options: PgDeliveryLedgerOptions): PgDeliveryLedger {
   const { executor } = options;
+  const windowMs = finiteCount(
+    'createPgDeliveryLedger',
+    'windowMs',
+    options.windowMs ?? DEFAULT_DELIVERY_WINDOW_MS,
+    1,
+  );
   return {
+    windowMs,
+    async purgeExpired(nowMs) {
+      // The JOB's clock, not the server's, and the same rule `x_rate_limit`'s target states: `at`
+      // is written by whichever process took the delivery, so a cutoff computed from `now()` in
+      // Postgres measures the offset between two clocks instead of the age of the row.
+      const before = new Date(finiteCount('purgeExpired', 'nowMs', nowMs, 0) - windowMs);
+      const rows = await executor.query<{ key: string }>(SQL_NOTIFY_DELIVERIES_PURGE_COUNTED, [
+        before,
+      ]);
+      return rows.length;
+    },
     async claim(claim, at) {
       const rows = await executor.query<{ attempts: number }>(SQL_NOTIFY_CLAIM, [
         ...argsOf(claim),

package/src/ledger.ts

@@ -5,6 +5,8 @@
 // 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.
 
+import { finiteCount } from '@ultimat3/core';
+
 export const DELIVERY_STATUSES = ['sending', 'sent', 'failed'] as const;
 
 export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
@@ -86,7 +88,17 @@ export interface MemoryDeliveryLedger extends DeliveryLedger {
 export function createMemoryDeliveryLedger(
   options: MemoryLedgerOptions = {},
 ): MemoryDeliveryLedger {
-  const max = options.max ?? DEFAULT_MAX_DELIVERY_RECORDS;
+  // `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.
+  // `??` guards nullish and `NaN` is not, so `Number(process.env.…)` on an unset variable arrives
+  // 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',
+    'max',
+    options.max ?? DEFAULT_MAX_DELIVERY_RECORDS,
+    1,
+  );
   const rows = new Map<string, DeliveryRecord>();
   let dropped = 0;
 

package/src/notifier.ts

@@ -9,6 +9,7 @@
 // The declaration lives here and the fan-out lives in `fanout.ts` — the same split `backfill.ts`
 // and `backfill-pass.ts` already have.
 
+import { finiteCount } from '@ultimat3/core';
 import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
 import { DEFAULT_RETRY, job } from '@ultimat3/jobs';
 import type { Schema } from '@ultimat3/schema';
@@ -101,10 +102,16 @@ function resolve<Params>(
     }
     return {
       channel,
-      waitMs: delivery.wait === undefined ? 0 : toDurationMs(delivery.wait),
+      waitMs:
+        delivery.wait === undefined
+          ? 0
+          : toDurationMs(delivery.wait, `deliver[${channel.name}].wait`),
       when: delivery.if,
       unless: delivery.unless,
-      digestMs: delivery.digest === undefined ? undefined : toDurationMs(delivery.digest.window),
+      digestMs:
+        delivery.digest === undefined
+          ? undefined
+          : toDurationMs(delivery.digest.window, `deliver[${channel.name}].digest.window`),
       group: delivery.digest?.group,
     };
   });
@@ -121,7 +128,18 @@ export function notifier<Params>(
   const declared = definition.recipients;
   const plan: NotifyPlan<Params> = {
     name: definition.name,
-    maxRecipients: definition.maxRecipients ?? DEFAULT_MAX_RECIPIENTS,
+    // `audience.length > maxRecipients` is the ONLY thing between a notifier and an unbounded
+    // fan-out, and `NaN` makes it false for every audience — the ceiling stops existing rather than
+    // being enforced wrongly. Refused where the notifier is declared, which is where an author can
+    // act on it. Floor of 0: a notifier whose audience must be empty is loud (every non-empty run
+    // is `X_NOTIFY_FANOUT_TOO_WIDE`), so it is a declaration and not the silent failure this
+    // screen exists for.
+    maxRecipients: finiteCount(
+      `notifier ${definition.name}`,
+      'maxRecipients',
+      definition.maxRecipients ?? DEFAULT_MAX_RECIPIENTS,
+      0,
+    ),
     deliveries,
     keyFor: (params) => definition.key(params),
     // Bound to the definition rather than torn off it, so an author who writes `recipients` as a

package/src/plan.ts

@@ -3,6 +3,7 @@
 // declaration, so the run body never re-parses a duration or re-decides a default per recipient.
 
 import type { Ctx } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 import { parseDuration } from '@ultimat3/time';
 import type { AnyNotifyChannel } from './channel';
 import type { NotifyEvent, Recipient } from './notification';
@@ -10,8 +11,28 @@ import type { NotifyEvent, Recipient } from './notification';
 /** `'5m'` | `300_000`. Numbers pass through so a caller may stay explicit, exactly as jobs does. */
 export type NotifyDuration = string | number;
 
-export const toDurationMs = (duration: NotifyDuration): number =>
-  typeof duration === 'number' ? duration : parseDuration(duration);
+/**
+ * `parseDuration` refuses every string it cannot read, so the STRING arm is already total. The
+ * number arm was the hole: it passed straight through, and a `NaN` there makes `waitMs > slept`
+ * false for every delivery (a declared delay that silently does not happen) and `at + windowMs`
+ * `NaN` (a digest bucket whose `endsAt > at` never holds, so every event opens its own window and
+ * the coalescer coalesces nothing). `option` names which declaration was wrong, since one notifier
+ * may hold several.
+ *
+ * NOT A COPY OF `@ultimat3/time`'s `toMs`, and the difference is the whole reason both exist:
+ * `toMs` is the framework's duration vocabulary and a negative or fractional duration is REAL
+ * there — `toSeconds(-3000)` is a tested `-3` — so it screens finiteness and stops. A notifier's
+ * `wait` and digest `window` are counts of whole forward milliseconds, and the refusal has to name
+ * the declaration. `plan-bounds.test.ts` calls BOTH on the same inputs, which is what keeps the
+ * two from drifting apart again the way they did when only this one was screened.
+ */
+export const toDurationMs = (duration: NotifyDuration, option = 'duration'): number =>
+  finiteCount(
+    'notifier',
+    option,
+    typeof duration === 'number' ? duration : parseDuration(duration),
+    0,
+  );
 
 /**
  * What a notifier is enqueued with.

package/src/retention.ts

@@ -0,0 +1,50 @@
+// The two sweeps over this package's tables, read off the installed seam rather than off a store
+// somebody handed the caller. `setNotifyStores` is an APP's boot line and runs after the boot that
+// 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 { InboxPurgeBefore, PgInboxStore } from './inbox-pg';
+import type { PgDeliveryLedger } 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
+ * 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.
+ */
+const purgeable = <T>(store: unknown, method: string): store is T =>
+  typeof store === 'object' &&
+  store !== null &&
+  typeof (store as Record<string, unknown>)[method] === 'function';
+
+/**
+ * Delete inbox rows past whichever windows the app named, and answer how many.
+ *
+ * ZERO IS THE ANSWER FOR "nothing to do", and there are three ways to reach it — no inbox
+ * installed, a memory inbox, or both windows unset. None of them is an error: an app that never
+ * configured retention has made a decision, and a sweep that threw would take the other framework
+ * tables' sweep down with it.
+ */
+export async function purgeNotifyInbox(before: InboxPurgeBefore): Promise<number> {
+  const store = notifyStores().inbox;
+  if (!purgeable<PgInboxStore>(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,
+ * 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
+ * whichever process took the delivery, so a cutoff computed inside Postgres measures the offset
+ * between two clocks rather than the age of the row.
+ */
+export async function purgeNotifyDeliveries(nowMs: number): Promise<number> {
+  const ledger = notifyStores().ledger;
+  if (!purgeable<PgDeliveryLedger>(ledger, 'purgeExpired')) return 0;
+  return ledger.purgeExpired(nowMs);
+}