@ultimat3/notify 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -11,9 +11,9 @@ returns a `job`, which is the whole design.
 
 | Never | Because |
 |---|---|
-| `@ultimat3/mail` | Same tier (4). A `Mailer` is declared **structurally** in `channel-mail.ts` — one method, no dependency — exactly as `@ultimat3/action`'s `PgExecutor` mirrors `@ultimat3/db`. Moving `notify` to tier 5 to legalise the import would put notifications above `render`, `pwa` and `ui` for one channel's transport, and would then need a `cli → notify` edge the way `cli → scraping` does. |
+| `@ultimat3/mail` | Same tier (4). A `Mailer` is declared **structurally** in `channel-mail.ts` — one method, no dependency — exactly as `PgExecutor` (`@ultimat3/core`) mirrors `@ultimat3/db`. Moving `notify` to tier 5 to legalise the import would put notifications above `render`, `pwa` and `ui` for one channel's transport, and would then need a `cli → notify` edge the way `cli → scraping` does. |
 | `@ultimat3/render`, `@ultimat3/ui`, `@ultimat3/ai`, `@ultimat3/mcp`, `@ultimat3/pwa` | Same tier. A notification has no view — the inbox is rendered by the app's page out of `InboxStore.list`, which is data. |
-| `@ultimat3/db`, `@ultimat3/entity` | Legal downward, and deliberately not taken. The two tables this package owns are **DDL constants applied by the boot** (`SQL_NOTIFY_DELIVERIES_TABLE`, `SQL_NOTIFY_INBOX_TABLE`), the way `x_jobs`, `x_idempotency` and `x_audit` are — never `entity()` declarations, which would put framework tables in the app's migration graph and make an app's `x db gen` responsible for them. The Postgres stores take a structural `PgExecutor`, imported as a **type** from `@ultimat3/jobs` rather than re-declared, because a third copy of a one-method interface is a third place to look. |
+| `@ultimat3/db`, `@ultimat3/entity` | Legal downward, and deliberately not taken. The three tables this package owns are **DDL constants applied by the boot** (`SQL_NOTIFY_DELIVERIES_TABLE`, `SQL_NOTIFY_INBOX_TABLE`, `SQL_NOTIFY_DIGESTS_TABLE`), the way `x_jobs`, `x_idempotency` and `x_audit` are — never `entity()` declarations, which would put framework tables in the app's migration graph and make an app's `x db gen` responsible for them. The Postgres stores take a structural `PgExecutor`, imported as a **type** from `@ultimat3/core` (its one declaration; `bun run flight-copies` refuses another, `X_HELPER_COPY`). |
 | `@ultimat3/policy` | A notification is addressed to exactly one person and the audience is `recipients`. There is no row a policy could decide about here. The **inbox read surface** is where authz belongs, and that is the app's query. |
 
 ## What ships, and what must never
@@ -55,7 +55,16 @@ 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, and a durable store can close it.
+rather than hidden. `createPgDigestStore` 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).
+
+**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,
+so an `open` checkpointed with duplicates by an earlier version is repaired on replay too.
 
 ## Files
 
@@ -70,8 +79,9 @@ rather than hidden, and a durable store can close it.
 | `ledger.ts` · `ledger-pg.ts` | the delivery ledger, memory and Postgres |
 | `inbox.ts` · `inbox-pg.ts` | the in-app inbox, memory and Postgres |
 | `preferences.ts` · `digest.ts` | the gate and the window, as seams |
+| `digest-pg.ts` | the digest window in Postgres: one row per window, at most one OPEN per slot |
 | `stores.ts` | the one installer for all four |
-| `retention.ts` | the two sweeps, read off the installed seam |
+| `retention.ts` | the three 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
@@ -108,7 +118,7 @@ it the two would split on exactly the Unicode keys nobody writes a test for.
 
 ## Retention
 
-Both tables are swept by the boot's hourly `x.purge` job, and neither store is handed to it:
+All three tables are swept by the boot's hourly `x.purge` job, and no 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
@@ -117,15 +127,23 @@ 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_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
+(`PgInboxStore`, `PgDeliveryLedger`, `PgDigestStore`), 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.
 
-`packages/cli/src/framework-schema.ts` applies both tables' DDL on every boot, **whether or not that
+`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`,
+`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.
+
+`packages/cli/src/framework-schema.ts` applies every notify table's 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.
 

package/README.md

@@ -98,8 +98,8 @@ One call, at boot. Whole-object replacement, never a merge.
 ```ts
 import type { PgExecutor } from '@ultimat3/jobs';
 import {
-  createMemoryDigestStore,
   createPgDeliveryLedger,
+  createPgDigestStore,
   createPgInboxStore,
   setNotifyStores,
 } from '@ultimat3/notify';
@@ -116,7 +116,8 @@ setNotifyStores({
   // 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(),
+  // `x_notify_digests`: a window survives a restart and every replica joins the same one.
+  digest: createPgDigestStore({ executor }),
   preferences: {
     // The GATE ships; what it reads never does. Your taxonomy, your quiet hours.
     allows: ({ recipient, notifier: name, channel, ctx }) =>
@@ -130,23 +131,25 @@ setNotifyStores({
 | `ledger` | `createMemoryDeliveryLedger()` | one process is genuinely deduped by a heap map, and no ledger at all means a replay sends twice |
 | `preferences` | `allowAllPreferences()` | denying by default is a notifier that silently delivers nothing |
 | `inbox` | **none** — `X_NOTIFY_STORE_MISSING` | a message written to nowhere is worse than a refusal |
-| `digest` | **none** — `X_NOTIFY_STORE_MISSING` | same |
+| `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 |
 
 `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.
+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
+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 |
+| `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 |
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "23.0.0",
+  "version": "24.0.0",
   "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/time": "24.0.0"
   }
 }

package/src/channel-mail.ts

@@ -1,6 +1,6 @@
 // Email as a channel, over a STRUCTURAL mailer rather than an import of @ultimat3/mail.
 //
-// That is the tier argument, and it is the same one `@ultimat3/action`'s `PgExecutor` makes about
+// That is the tier argument, and it is the same one `PgExecutor` (`@ultimat3/core`) makes about
 // `@ultimat3/db`. `@ultimat3/mail` is tier 4 and so is this package, so importing it would be a
 // sideways edge — and moving `notify` to tier 5 to legalise it would put notifications above
 // `render`, `pwa` and `ui` for no reason other than one channel's transport. A mailer is a driver

package/src/digest-pg.ts

@@ -0,0 +1,209 @@
+// 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
+// same queue of windows in one heap; this is what a deployment with more than one process installs.
+
+import type { PgExecutor } from '@ultimat3/core';
+import { finiteCount, UltimateError } from '@ultimat3/core';
+import type { DigestSlot, DigestStore } from './digest';
+import type { NotifyEvent } from './notification';
+
+/**
+ * Applied by the boot beside `SQL_NOTIFY_DELIVERIES_TABLE` and `SQL_NOTIFY_INBOX_TABLE`, never by
+ * an app migration — a new column is `alter table … add column if not exists`, never an edit here.
+ *
+ * The PARTIAL unique index is the whole concurrency story: at most one OPEN window per slot, so two
+ * replicas appending the first event of a window at once collide on it and exactly one of them
+ * opens the window and owns its flush. A window is SEALED once it has elapsed and an append wanted
+ * a new one; sealed windows wait for their flush and are not indexed, so a slot can hold several.
+ */
+export const SQL_NOTIFY_DIGESTS_TABLE = `
+create table if not exists x_notify_digests (
+  seq        bigint      generated always as identity primary key,
+  recipient  text        not null,
+  notifier   text        not null,
+  channel    text        not null,
+  group_key  text        not null,
+  ends_at    timestamptz not null,
+  sealed     boolean     not null default false,
+  events     jsonb       not null
+);
+
+create unique index if not exists x_notify_digests_open_idx
+  on x_notify_digests (recipient, notifier, channel, group_key) where not sealed;
+
+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);
+`;
+
+/**
+ * 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.
+ */
+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
+`;
+
+/** Seal the slot's open window once it has elapsed, so the next append opens a fresh one. */
+export const SQL_NOTIFY_DIGEST_SEAL = `
+update x_notify_digests set sealed = true
+where recipient = $1 and notifier = $2 and channel = $3 and group_key = $4
+  and not sealed and ends_at <= $5
+`;
+
+/**
+ * Take every window closing at or before `$5` — its own and an older one a crashed flush left —
+ * or, with `$5` null, the oldest window alone. Oldest first, by close time and then by the order
+ * the windows were opened in, which is what the memory store's queue answers.
+ */
+export const SQL_NOTIFY_DIGEST_DRAIN = `
+with taken as (
+  delete from x_notify_digests
+  where recipient = $1 and notifier = $2 and channel = $3 and group_key = $4
+    and (
+      ($5::timestamptz is not null and ends_at <= $5)
+      or ($5::timestamptz is null and seq = (
+        select min(seq) from x_notify_digests
+        where recipient = $1 and notifier = $2 and channel = $3 and group_key = $4
+      ))
+    )
+  returning seq, ends_at, events
+)
+select events from taken order by ends_at, seq
+`;
+
+/**
+ * The retention sweep's one statement: windows that CLOSED before `$1`, oldest first, at most `$2`
+ * of them. A window is deleted by its own flush's drain or by the next window's drain of the slot;
+ * this catches the one neither reaches — a flush that dead-lettered on a slot that never digests
+ * again. Bounded per statement, so one pass never holds a lock across the whole table.
+ */
+export const SQL_NOTIFY_DIGESTS_PURGE = `
+delete from x_notify_digests
+where seq in (
+  select seq from x_notify_digests where ends_at < $1 order by ends_at, seq limit $2
+)
+returning seq
+`;
+
+/**
+ * How long a CLOSED window is kept before the sweep may take it: a week. Longer than any retry
+ * schedule a notifier's flush runs on, so the sweep only ever takes a window whose flush is gone.
+ */
+export const DEFAULT_DIGEST_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** Rows per delete statement. */
+export const DIGEST_PURGE_BATCH = 1000;
+/** Statements per pass: the hourly sweep goes on where this one stopped. */
+export const DIGEST_PURGE_MAX_BATCHES = 50;
+
+/** Each seal answers one elapsed window; more than this in one append is clocks that disagree. */
+const MAX_SEALS = 8;
+
+interface AppendRow {
+  readonly ends_at: Date | string;
+  readonly opened: boolean;
+}
+
+/** `at` round-trips through jsonb as an ISO string; the type promises a `Date`, so it is rebuilt. */
+interface StoredEvent extends Omit<NotifyEvent<unknown>, 'at'> {
+  readonly at: string;
+}
+
+interface DrainRow {
+  readonly events: readonly StoredEvent[];
+}
+
+const slotArgs = (slot: DigestSlot): readonly unknown[] => [
+  slot.recipient,
+  slot.notifier,
+  slot.channel,
+  slot.group,
+];
+
+const epochOf = (value: Date | string): number =>
+  (value instanceof Date ? value : new Date(value)).getTime();
+
+export interface PgDigestStoreOptions {
+  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
+ * `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 {
+  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 {
+  const { executor } = options;
+  const retentionMs = finiteCount(
+    'createPgDigestStore',
+    'retentionMs',
+    options.retentionMs ?? DEFAULT_DIGEST_RETENTION_MS,
+    1,
+  );
+  return {
+    retentionMs,
+    async purgeExpired(nowMs) {
+      // The JOB's clock, as the ledger's sweep: `ends_at` was computed from the appender's clock.
+      const before = new Date(finiteCount('purgeExpired', 'nowMs', nowMs, 0) - retentionMs);
+      let removed = 0;
+      for (let batch = 0; batch < DIGEST_PURGE_MAX_BATCHES; batch += 1) {
+        const rows = await executor.query<{ seq: number }>(SQL_NOTIFY_DIGESTS_PURGE, [
+          before,
+          DIGEST_PURGE_BATCH,
+        ]);
+        removed += rows.length;
+        if (rows.length < DIGEST_PURGE_BATCH) break;
+      }
+      return removed;
+    },
+    async append(input) {
+      const slot = slotArgs(input.slot);
+      const now = input.now;
+      const events = JSON.stringify([input.event]);
+      const endsAt = new Date(now.getTime() + input.windowMs);
+      for (let seals = 0; seals <= MAX_SEALS; seals += 1) {
+        const [row] = await executor.query<AppendRow>(SQL_NOTIFY_DIGEST_APPEND, [
+          ...slot,
+          events,
+          endsAt,
+          now,
+        ]);
+        if (row !== undefined) return { opened: row.opened, endsAt: epochOf(row.ends_at) };
+        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
+      // had already elapsed by this process's clock — two replicas a whole window apart in time.
+      throw new UltimateError({
+        code: 'X_INVARIANT',
+        cause: `the digest window for notifier "${input.slot.notifier}" kept closing before this append could join it (${String(MAX_SEALS)} seals): its ${String(input.windowMs)} ms window is shorter than one append's round trip, or two replicas' clocks are a whole window apart`,
+        fix: 'psql "$DATABASE_URL" -c "select notifier, recipient, ends_at, sealed, now() from x_notify_digests order by ends_at desc limit 10"',
+        meta: { notifier: input.slot.notifier, seals: MAX_SEALS },
+      });
+    },
+    async drain(slot, endsAt) {
+      const rows = await executor.query<DrainRow>(SQL_NOTIFY_DIGEST_DRAIN, [
+        ...slotArgs(slot),
+        endsAt === undefined ? null : new Date(endsAt),
+      ]);
+      return rows.flatMap((row) =>
+        row.events.map((event) => ({ ...event, at: new Date(event.at) })),
+      );
+    },
+  };
+}

package/src/fanout.ts

@@ -31,7 +31,9 @@ export async function runFanout<Params>(
     at: ctx.now().getTime(),
     recipients: input.recipients ?? [...(await plan.recipientsFor({ input: input.params, ctx }))],
   }));
-  const audience = open.recipients;
+  // Deduplicated on the way OUT of the step rather than inside it, so an `open` checkpointed by an
+  // earlier version — duplicates and all — is repaired on replay too, not only a fresh resolve.
+  const audience = uniqueById(open.recipients);
   if (audience.length > plan.maxRecipients) {
     throw new NotifyFanoutTooWideError({
       notifier: plan.name,
@@ -62,6 +64,21 @@ export async function runFanout<Params>(
   return { recipients: audience.length, ...tally };
 }
 
+/**
+ * One entry per recipient id, the FIRST kept. Every per-recipient step is named by the id, so a
+ * repeated id was `X_STEP_DUPLICATE` on its second delivery — the fan-out failed part-way, the
+ * recipients after it were never notified, and every retry failed at the same place. One person
+ * named twice by a resolver is still one person, and gets one delivery per channel.
+ */
+function uniqueById(recipients: readonly Recipient[]): Recipient[] {
+  const seen = new Set<string>();
+  return recipients.filter((recipient) => {
+    if (seen.has(recipient.id)) return false;
+    seen.add(recipient.id);
+    return true;
+  });
+}
+
 async function deliverOne<Params>(
   walk: Walk<Params>,
   delivery: ResolvedDelivery<Params>,

package/src/inbox-pg.ts

@@ -1,8 +1,8 @@
 // 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 type { PgExecutor } from '@ultimat3/core';
 import { finiteCount, isUuid, uuid } from '@ultimat3/core';
-import type { PgExecutor } from '@ultimat3/jobs';
 import type { InboxRow, InboxStore, InboxWrite } from './inbox';
 import { DEFAULT_INBOX_PAGE } from './inbox';
 

package/src/index.ts

@@ -29,6 +29,12 @@ export type {
   MemoryDigestStore,
 } from './digest';
 export { createMemoryDigestStore } from './digest';
+export type { PgDigestStore, PgDigestStoreOptions } from './digest-pg';
+export {
+  createPgDigestStore,
+  DEFAULT_DIGEST_RETENTION_MS,
+  SQL_NOTIFY_DIGESTS_TABLE,
+} from './digest-pg';
 export type { NotifyErrorCode } from './errors';
 export {
   NOTIFY_ERROR_CODES,
@@ -88,7 +94,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 { purgeNotifyDeliveries, purgeNotifyDigests, purgeNotifyInbox } from './retention';
 export type { InstalledNotifyStores, NotifyStores } from './stores';
 export {
   notifyStores,

package/src/ledger-pg.ts

@@ -4,8 +4,8 @@
 //
 // 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 } from '@ultimat3/core';
-import type { PgExecutor } from '@ultimat3/jobs';
 import type { DeliveryClaim, DeliveryLedger, DeliveryRecord, DeliveryStatus } from './ledger';
 import { isDeliveryStatus } from './ledger';
 

package/src/retention.ts

@@ -1,8 +1,9 @@
-// The two sweeps over this package's tables, read off the installed seam rather than off a store
+// The three 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 { PgDigestStore } from './digest-pg';
 import type { InboxPurgeBefore, PgInboxStore } from './inbox-pg';
 import type { PgDeliveryLedger } from './ledger-pg';
 import { notifyStores } from './stores';
@@ -48,3 +49,14 @@ export async function purgeNotifyDeliveries(nowMs: number): Promise<number> {
   if (!purgeable<PgDeliveryLedger>(ledger, 'purgeExpired')) return 0;
   return ledger.purgeExpired(nowMs);
 }
+
+/**
+ * Delete digest windows closed longer ago than the store's own `retentionMs`, and answer how many.
+ * A window is normally deleted by a drain; this takes the one whose flush dead-lettered on a slot
+ * that never digests again. Zero for no store or a memory one, for the reason above.
+ */
+export async function purgeNotifyDigests(nowMs: number): Promise<number> {
+  const digest = notifyStores().digest;
+  if (!purgeable<PgDigestStore>(digest, 'purgeExpired')) return 0;
+  return digest.purgeExpired(nowMs);
+}