@ultimat3/notify 19.2.0 → 19.3.1

package/CLAUDE.md

@@ -77,6 +77,28 @@ rather than hidden, and a durable store can close it.
 One entry point, deliberately: every module runs on the server, so there is no browser half to split
 off.
 
+**The two inbox stores answer one question one way, and the two places they did not were both in
+`list`/`markRead`** (`As of 2026-09`). `markRead`'s contract is that an id belonging to nobody is
+*simply absent* — the memory store skips it — while the Postgres one bound the caller's ids into
+`any($2::uuid[])`, so one malformed id raised 22P02 out of the store and the nineteen good ids in
+the batch went unmarked. `createPgInboxStore` screens with `isUuid` before binding and answers `0`
+with no round trip when nothing survives; the statement keeps its `::uuid[]` cast and its primary
+key index, which `id::text = any($2)` would have given up. And the memory `list` now sorts
+`(createdAt desc, notifier, key)` — the total order `SQL_NOTIFY_INBOX_PAGE` takes — because
+`createdAt` alone is partial and a bounded page over two notifications written in one millisecond
+can drop one and repeat the other.
+
+**The tail is `(notifier, key)` and never `id`, `As of 2026-09-06`.** Both stores had a tail and
+they were two different total orders: `createPgInboxStore` mints a UUIDv7 that Postgres compares by
+its 16 BYTES, while `createMemoryInboxStore` derives its id from
+`JSON.stringify([recipient, notifier, key])` and compares by code point — so equal-`createdAt` rows
+came back one way in dev and the other in production, which is the drop-and-repeat the tail exists
+to prevent, on whichever driver nobody tested against. `(notifier, key)` is unique within a
+recipient by the table's own `unique (recipient, notifier, key)`, which is also what makes `add`
+idempotent. The statement spells `collate "C"` on both columns: the memory store compares by code
+point and a database initialised under ICU or `en_US.UTF-8` orders text by locale rules, so without
+it the two would split on exactly the Unicode keys nobody writes a test for.
+
 | Rule | Detail |
 |---|---|
 | Exports | `src/index.ts`, explicit, no `export *` |

package/package.json

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

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 { finiteCount, uuid } 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';
@@ -54,12 +54,23 @@ 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. */
+/**
+ * Newest first, `(created_at desc, notifier, key)` — unique within a recipient by the table's own
+ * `unique (recipient, notifier, key)`, so the order is total and a bounded page cannot drop or
+ * repeat a row when two notifications land in the same millisecond.
+ *
+ * `collate "C"` and not the column's collation: `createMemoryInboxStore` compares the same two
+ * columns by CODE POINT, and a database initialised under an ICU or a `en_US.UTF-8` collation
+ * orders text by locale rules — case-insensitively, ignoring punctuation at the first level — so
+ * the two stores would disagree on exactly the Unicode keys nobody writes a test for. `id` was the
+ * tail until 2026-09-06 and could not be: a UUIDv7 ordered by its 16 bytes here and a
+ * `JSON.stringify([recipient, notifier, key])` ordered by code point there is two total orders that
+ * agree on nothing.
+ */
 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
+order by created_at desc, notifier collate "C", key collate "C"
 limit $3
 `;
 
@@ -190,9 +201,18 @@ export function createPgInboxStore(options: PgInboxStoreOptions): PgInboxStore {
       return rows[0]?.unread ?? 0;
     },
     async markRead(input) {
+      // The ids are NAMED by the caller and bound into `any($2::uuid[])`, so one that is not a
+      // uuid is Postgres 22P02 out of a method whose contract says an id belonging to nobody is
+      // simply absent — the memory store skips it. Raising would lose the whole batch: nineteen
+      // good ids marked by nobody because a twentieth was a typo. Screened, never cast: a
+      // `id::text = any($2)` would answer the same and give up the primary key index.
+      const ids = [...input.ids].filter(isUuid);
+      // No round trip for a batch that can match nothing — `any('{}')` costs a statement to
+      // answer what this line already knows.
+      if (ids.length === 0) return 0;
       const rows = await executor.query<{ id: string }>(SQL_NOTIFY_INBOX_MARK_READ, [
         input.recipient,
-        [...input.ids],
+        ids,
         input.at,
       ]);
       return rows.length;

package/src/inbox.ts

@@ -59,6 +59,27 @@ export interface MemoryInboxStore extends InboxStore {
   clear(): void;
 }
 
+/** Codepoint order, never `localeCompare`: Postgres compares the tail key by bytes, not by locale. */
+const compareText = (a: string, b: string): number => {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+};
+
+/**
+ * The tail key both stores order on: `(notifier, key)`, which is unique within a recipient because
+ * `add` is idempotent on `(recipient, notifier, key)` and the Postgres table declares that UNIQUE.
+ *
+ * `id` cannot be it, and that is the whole reason this exists. `createPgInboxStore` mints a UUIDv7
+ * and Postgres orders `uuid` by its 16 BYTES; `createMemoryInboxStore` derives its id from
+ * `JSON.stringify([recipient, notifier, key])` and orders it by code point. Two total orders that
+ * agree on nothing — so two notifications written in one millisecond came back in one order in dev
+ * and the other in production, and a bounded page dropped one and repeated the other on exactly the
+ * driver nobody was testing against. Two drivers behind one interface must not answer one question
+ * two ways.
+ */
+const compareTail = (a: InboxRow, b: InboxRow): number =>
+  compareText(a.notifier, b.notifier) || compareText(a.key, b.key);
+
 const idOf = (write: { recipient: string; notifier: string; key: string }): string =>
   JSON.stringify([write.recipient, write.notifier, write.key]);
 
@@ -70,10 +91,14 @@ const idOf = (write: { recipient: string; notifier: string; key: string }): stri
 export function createMemoryInboxStore(): MemoryInboxStore {
   const rows = new Map<string, InboxRow>();
 
+  // `(createdAt desc, notifier, key)` — the same TOTAL order `SQL_NOTIFY_INBOX_PAGE` takes, and
+  // for the same reason: `createdAt` alone is partial, so two notifications written in one
+  // millisecond can swap places between two reads and a bounded page then drops one and repeats
+  // the other.
   const own = (recipient: string): InboxRow[] =>
     [...rows.values()]
       .filter((row) => row.recipient === recipient)
-      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || compareTail(a, b));
 
   return {
     get size(): number {