@ultimat3/notify 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -81,6 +81,7 @@ 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 |
+| 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 |
 
 ## Homeless work this package cannot do
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "15.0.0",
+  "version": "17.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": "15.0.0",
-    "@ultimat3/jobs": "15.0.0",
-    "@ultimat3/schema": "15.0.0",
-    "@ultimat3/time": "15.0.0"
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/jobs": "17.0.0",
+    "@ultimat3/schema": "17.0.0",
+    "@ultimat3/time": "17.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';
@@ -132,10 +132,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);
     },

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/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.