@ultimat3/notify 25.0.0 → 25.2.0

package/README.md

@@ -104,7 +104,7 @@ import {
   setNotifyStores,
 } from '@ultimat3/notify';
 
-declare const executor: PgExecutor;   // `@ultimat3/cli`'s pgExecutorFor(client)
+declare const executor: PgExecutor;   // `@ultimat3/db`'s dbExecutor()
 declare const idempotency: { readonly windowMs: number };   // the boot's own store
 // The app's preference table, behind whatever taxonomy it named.
 declare const prefs: {
@@ -133,8 +133,8 @@ setNotifyStores({
 | `inbox` | **none** — `X_NOTIFY_STORE_MISSING` | a message written to nowhere is worse than a refusal |
 | `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.
+`executor` is a structural `{ query(sql, params) }` — `@ultimat3/db`'s `dbExecutor()` is the
+framework's own. `Bun.sql` does **not** satisfy it.
 
 ## Retention
 
@@ -225,7 +225,9 @@ delay sends nothing.
 A job body runs before its checkpoint lands. Two layers stop a double send: the step checkpoint
 (`deliver:<channel>:<recipient>`), and the delivery ledger's atomic claim on
 `(notifier, key, channel, coalesce(recipient, ''))` — taken before the send, settled after. A claim
-that already reads `sent` answers `false`.
+that already reads `sent` answers `false`. `memoryDeliveryLedger` keys and settles exactly as the
+Postgres ledger does — a null and an empty recipient are one row, and a `settle` with no claim
+records nothing (`ledger-parity.live.test.ts` runs one script against both).
 
 A bulk channel claims **one** row for the whole audience, with a null recipient: half a bulk POST is
 not a state this package can represent. That null is why the key coalesces rather than naming the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "25.0.0",
+  "version": "25.2.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": "25.0.0",
-    "@ultimat3/jobs": "25.0.0",
-    "@ultimat3/schema": "25.0.0",
-    "@ultimat3/time": "25.0.0"
+    "@ultimat3/core": "25.2.0",
+    "@ultimat3/jobs": "25.2.0",
+    "@ultimat3/schema": "25.2.0",
+    "@ultimat3/time": "25.2.0"
   }
 }

package/src/ledger.ts

@@ -58,9 +58,10 @@ export interface DeliveryLedger {
  * 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.
+ * `recipient ?? ''` is the Postgres ledger's `coalesce(recipient, '')`: one identity, both stores.
  */
 const keyOf = (claim: DeliveryClaim): string =>
-  JSON.stringify([claim.notifier, claim.key, claim.recipient, claim.channel]);
+  JSON.stringify([claim.notifier, claim.key, claim.recipient ?? '', claim.channel]);
 
 export interface MemoryDeliveryLedgerOptions {
   /**
@@ -122,8 +123,9 @@ export function memoryDeliveryLedger(
       const id = keyOf(claim);
       const existing = rows.get(id);
       if (existing?.status === 'sent') return Promise.resolve(false);
+      // The row it found keeps its own identity, as the pg `on conflict do update` does.
       rows.set(id, {
-        ...claim,
+        ...(existing ?? claim),
         status: 'sending',
         attempts: (existing?.attempts ?? 0) + 1,
         at,
@@ -134,7 +136,9 @@ export function memoryDeliveryLedger(
     settle(claim, status, at) {
       const id = keyOf(claim);
       const existing = rows.get(id);
-      rows.set(id, { ...claim, status, attempts: existing?.attempts ?? 1, at });
+      // No claim, no row: the pg `update` matches nothing, and a row written here would refuse
+      // the claim after it — a notification dev never sends and production does.
+      if (existing !== undefined) rows.set(id, { ...existing, status, at });
       return Promise.resolve();
     },
     find(claim) {