@ultimat3/entity 19.2.0 → 19.3.1

package/CLAUDE.md

@@ -67,12 +67,20 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   decimals, so a caller with no kinds — `@ultimat3/query`, whose `OrderKey` is a name and a
   direction — deliberately never calls it: Postgres orders a `text` column of digits lexically, and
   a comparator guessing "both sides look like decimals" would trade this agreement for that
-  disagreement. That residual gap is `@ultimat3/query`'s `shape-order.test.ts` `DECLARED_GAP`. **A `uuid` is a VALUE**: Postgres parses it and
-  prints it lower-cased, so `findById(UPPER)` reads the row there and answered `null` here, and
+  disagreement. That residual gap is `@ultimat3/query`'s `shape-order.test.ts` `DECLARED_GAP`.
+  **A `uuid` is a VALUE, and the value the row HOLDS is lower case**: Postgres parses it and prints
+  it lower-cased, so `findById(UPPER)` reads the row there and answered `null` here, and
   `update(UPPER)` was `X_NOT_FOUND` against a row that exists — `keyOf(kind, value)`
   (`batch-read.ts`), which already carried that rule for a batched read, now spells the memory
-  store's key and its equality too. Text is NOT narrowed: lower-casing it would merge two rows
-  Postgres keeps apart. **A `LIKE` pattern uses Postgres' default escape**: `\` escapes `%`, `_`
+  store's key and its equality too. Equality was only half of it: the STORED value stayed the
+  caller's spelling here while the server's row never carries one, so `countBy('authorId')` keyed
+  its `Map` by `AAAA…` in memory and by `aaaa…` in production — a breakdown one driver's caller
+  cannot look up, out of a call that read the right rows. Narrowed in the two places a value
+  crosses: `parseUuid` on the way back (`decodeRow`, `entity.$parse`) and `narrowUuid` at each
+  write method's entry (`columns.ts`), beside `narrowMoney` and for its reason — `entity.$assert`
+  runs before a statement exists, so an invariant reading an id must see the value the row will
+  hold. Text is NOT narrowed: lower-casing it would merge two rows Postgres keeps apart.
+  **A `LIKE` pattern uses Postgres' default escape**: `\` escapes `%`, `_`
   or itself, so `like 'a\%b'` matches the literal `a%b` in both drivers rather than
   `a\<anything>b` in one — and a pattern ending in the escape character is refused here as
   Postgres refuses it (`22025`). A RUN of `%` is still one `.*`: twenty adjacent `.*` groups in an
@@ -343,10 +351,17 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `cursorFor` runs only when a page found a row past its limit, so `orderBy('publishedAt', 'desc')
   .limit(20)` over a nullable column was green on fifteen seeded rows for as long as the suite
   existed and `X_INVARIANT_VIOLATED` on the first read past twenty in production. That file's own
-  doc comment claimed the opposite for two majors. `assertBatchable` has always judged `inBatches()`
-  this way. This package owns only
-  what a cursor is *bound* to — `planScope(plan)`: the entity, its filters and its sort order,
-  hashed. Not the page size (a bigger next page is the same query) and not `select` (a projection
+  doc comment claimed the opposite for two majors. `assertBatchable` has always judged
+  `inBatches()` this way.
+  **A `timestamptz` sort key is refused when its ALIAS would not fit, `As of 2026-09`.** That key
+  selects a second output — `<column>$US`, the microsecond half `sortPrecision` reads back — and
+  `assertColumnName` admits 63 bytes, which is the server's whole budget: a 61-byte column
+  produced a 64-byte alias, Postgres truncated it and said nothing, the read answered `undefined`,
+  and `cursorFor` fell back to the millisecond `Date` `instant.ts` exists to replace. The page
+  then cuts where no row sits. Bounded against `index-name.ts`'s `MAX_IDENTIFIER_BYTES` and
+  measured on the alias `seekAlias` actually builds, never against a hard-coded suffix length.
+  This package owns only what a cursor is *bound* to — `planScope(plan)`: the entity, its filters
+  and its sort order, hashed. Not the page size (a bigger next page is the same query) and not `select` (a projection
   cannot move a row). A cursor that fails either the signature or the scope is `X_CURSOR_INVALID`;
   it must never decode to "start from the top", which is what the old codec's `null` did.
 - **A NULLABLE sort key orders, `As of 2026-08-24` — `asc nulls last` / `desc nulls first`, and
@@ -414,19 +429,20 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   is recursive structural containment, the second is plain element membership, because an array's
   elements are scalars of one declared type — `arrayOf()` refuses `jsonb`, `bytea`, `money` and a
   nested array, which is what makes that true. A `Date` element compares by its instant, never by
-  reference. **`jsonb_exists(col, $1)`, never the `?` operator**: a literal `?` is a parameter
-  placeholder to more than one client on the way to the server. **No jsonpath expression operator**
-  beside them, deliberately: `contains` already matches nested structure, and a path language
-  inside the query language is a second way to ask one question. `&&` on a `jsonb` column is
-  refused where it was written, since Postgres has no such operator and any answer would be one no
-  statement can make. **`has-key` emits the `?` OPERATOR, schema-qualified
-  (`operator(pg_catalog.?)`), and not `jsonb_exists(col, $1)`** — the two are the same test and only
-  the first is INDEXABLE: measured on Postgres 16 with a GIN index and `enable_seqscan = off`,
-  `data ? 'k'` plans as a Bitmap Index Scan and the function form is a Seq Scan the planner will not
-  convert, because an index is matched against an operator expression and a bare function call is
-  not one. The function form shipped first, on a stated fear of `?` being read as a placeholder;
-  Bun's client passes it through verbatim (measured), and the qualified spelling is immune to a
-  client that does not and to a `search_path` that shadows the operator.
+  reference. **No jsonpath expression operator** beside them, deliberately: `contains` already
+  matches nested structure, and a path language inside the query language is a second way to ask
+  one question. `&&` on a `jsonb` column is refused where it was written, since Postgres has no
+  such operator and any answer would be one no statement can make. **`has-key` emits the `?`
+  OPERATOR, schema-qualified (`operator(pg_catalog.?)`), and not `jsonb_exists(col, $1)`** — the two
+  are the same test and only the first is INDEXABLE: measured on Postgres 16 with a GIN index and
+  `enable_seqscan = off`, `data ? 'k'` plans as a Bitmap Index Scan and the function form is a Seq
+  Scan the planner will not convert, because an index is matched against an operator expression and
+  a bare function call is not one. The function form shipped first, on a stated fear of `?` being
+  read as a placeholder; Bun's client passes it through verbatim (measured), and the qualified
+  spelling is immune to a client that does not and to a `search_path` that shadows the operator. The
+  bullet ABOVE this one said the opposite — "`jsonb_exists(col, $1)`, never the `?` operator" — for
+  two majors after the SQL moved, and `containment.ts`'s own doc comment repeated it; both are gone,
+  and `pg-sql.test.ts` now pins the emitted form so neither can come back as prose.
 - **A GIN index is declarable — `indexes: [{ on: ['tags'], using: 'gin' }]`, `As of 2026-08-24`.**
   Without one every containment operator above is a sequential scan, which is the whole reason they
   needed an index at all: measured over 20,000 rows, array `@>` / `<@` / `&&` and jsonb `@>` and
@@ -677,6 +693,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
     the three callers want three answers and the wrong one is invisible in the result. The soft
     delete inside `removal()` passes `false` too — both its callers read a count through
     `execute()`, so its rows were never readable by anyone.
+    **And the bound is BOTH drivers', `As of 2026-09`.** `memoryRepo.updateWhere` applied no
+    ceiling at all, so a sweep of 50,001 rows answered `50001` here and `X_INVARIANT_VIOLATED`
+    there from one call — a test written against memory proving a call production refuses, which
+    is the drift the two-driver split exists to prevent. Same condition (`hasJsOnlyInvariant`),
+    same constant, same error, and checked before the write loop so a refusal never writes the
+    rows it declined to judge.
 - **Every instant the write path stamps comes from `ctx.clock`, through `entityNow()`**
   (`clock.ts`, `As of 2026-08`). `defaultNow()`, `touch()`'s `onUpdateNow()`, the soft-delete stamp
   in BOTH drivers and a seed's `now` each read `systemClock` directly, so a frozen test clock drove

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "19.2.0",
+  "version": "19.3.1",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.2.0",
-    "@ultimat3/db": "19.2.0",
-    "@ultimat3/schema": "19.2.0",
-    "@ultimat3/time": "19.2.0"
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/db": "19.3.1",
+    "@ultimat3/schema": "19.3.1",
+    "@ultimat3/time": "19.3.1"
   }
 }

package/src/columns.ts

@@ -37,9 +37,18 @@ export const newId = (): string => uuidV7();
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+/**
+ * Lower-cased, because Postgres parses a `uuid` on the way in and prints it lower-cased on the way
+ * out: the row the server stores never carries the caller's spelling, so a row this driver stored
+ * verbatim was a value production does not hold. `keyOf` (`batch-read.ts`) and `sameValueOfKind`
+ * (`memory-match.ts`) already narrow the same way for EQUALITY; this is the value itself, which is
+ * what a caller reads back and what `countBy` keys its `Map` by — an upper-cased insert produced a
+ * breakdown keyed one way in memory and the other in production. `text()` is deliberately NOT
+ * narrowed: lower-casing it would merge two rows Postgres keeps apart.
+ */
 const parseUuid = (value: unknown): string =>
   typeof value === 'string' && UUID.test(value)
-    ? value
+    ? value.toLowerCase()
     : refuseColumn(
         'format',
         `expected a uuid, ${got(value)}`,
@@ -367,11 +376,13 @@ const checkedParts = (columns: MoneyColumnNames): MoneyColumnNames => ({
  * exactly the drift the two-driver split exists to prevent — here it would mean an in-memory row
  * holding a `bigint` that `JSON.stringify` refuses while the Postgres row holds a `number`.
  *
- * Every other kind is returned untouched: writes are asserted, not parsed, and money is the only
- * kind that widens. A value already holding safe-integer minor units is left alone — that is the
- * overwhelmingly common case and it costs one `typeof`-grade check and no allocation (axiom 6);
- * everything else goes through `parseMinor`, so a `bigint` narrows and a float is refused with
- * the same message it would get coming back from the database.
+ * Every other kind is returned untouched HERE: writes are asserted, not parsed, and money is the
+ * only kind whose declared TYPE widens. `uuid` is narrowed too and is narrowed beside this one
+ * (`narrowUuid`), because its width is in the value's spelling rather than in its type. A value
+ * already holding safe-integer minor units is left alone — that is the overwhelmingly common case
+ * and it costs one `typeof`-grade check and no allocation (axiom 6); everything else goes through
+ * `parseMinor`, so a `bigint` narrows and a float is refused with the same message it would get
+ * coming back from the database.
  */
 export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
   let narrowed: Record<string, unknown> | undefined;
@@ -388,6 +399,46 @@ export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
   return (narrowed ?? row) as Row;
 };
 
+/**
+ * The second narrowing, and the same shape as the one above: what the caller spelled in is wider
+ * than what the row holds. Postgres parses a `uuid` on the way IN and prints it lower-cased on the
+ * way OUT, so an upper-cased insert is stored — and read back — lower-cased there whatever the
+ * writer typed, while the in-memory driver kept the spelling verbatim.
+ *
+ * That was one value with two spellings across the two drivers, not a cosmetic difference: `keyOf`
+ * (`batch-read.ts`) and `sameValueOfKind` (`memory-match.ts`) already narrow a `uuid` for
+ * EQUALITY, so the row was found either way, but `countBy` keys its `Map` by the value it read off
+ * the row — so `counts.get(id)` answered the count in production and `undefined` in memory, from
+ * one call. `text()` is deliberately never narrowed: lower-casing it would merge two rows Postgres
+ * keeps apart.
+ *
+ * At the write entry rather than in `bindValues`, for `narrowMoney`'s reason: `entity.$assert`
+ * runs before a statement exists, so an invariant reading an id must see the value the row will
+ * hold. `parseUuid` applies the same rule on the read side (`decodeRow`, `entity.$parse`).
+ */
+const narrowUuid = <Row>(columns: ColumnMap, row: Row): Row => {
+  let narrowed: Record<string, unknown> | undefined;
+  const record = row as Readonly<Record<string, unknown>>;
+  for (const [property, column] of Object.entries(columns)) {
+    if (column.$meta.kind !== 'uuid') continue;
+    const value = record[property];
+    // Untouched unless it is a string that actually carries an upper-case character: a malformed
+    // value is the column parser's to refuse, with its own message, and no allocation is paid by
+    // the overwhelmingly common case (axiom 6).
+    if (typeof value !== 'string') continue;
+    const lower = value.toLowerCase();
+    if (lower === value) continue;
+    // And only a value Postgres would have accepted, which is the whole justification for touching
+    // it: the memory driver stores what `$assert` was shown, so a malformed id lower-cased here is
+    // a spelling NEITHER driver holds — Postgres refuses that insert outright. Asked last, so the
+    // regex is paid only by the rare value that carries an upper-case character at all.
+    if (!UUID.test(value)) continue;
+    narrowed ??= { ...record };
+    narrowed[property] = lower;
+  }
+  return (narrowed ?? row) as Row;
+};
+
 /**
  * The same narrowing at a write METHOD'S entry, typed honestly: what a caller may spell in,
  * the row the entity declares out.
@@ -402,7 +453,7 @@ export const narrowMoney = <Row>(columns: ColumnMap, row: Row): Row => {
  * once `narrowMoney` has returned, and `parseMinor` threw for anything that could not become one.
  */
 export const narrowRow = <Row>(columns: ColumnMap, values: RowWrite<Row>): Row =>
-  narrowMoney(columns, values) as Row;
+  narrowUuid(columns, narrowMoney(columns, values)) as Row;
 
 /**
  * The CHECK that stops a psql session writing a currency the app would refuse — the app's own

package/src/containment.ts

@@ -78,12 +78,16 @@ export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[
   right.some((item) => left.some((candidate) => sameElement(candidate, item)));
 
 /**
- * `jsonb_exists(value, key)` — the function form of the `?` operator, which is what the SQL side
- * emits so a literal `?` can never be read as a parameter placeholder by anything on the way.
+ * The memory half of `col ? key`. The SQL side emits the OPERATOR, schema-qualified —
+ * `col operator(pg_catalog.?) $1` (`pg-sql.ts`) — and not `jsonb_exists(col, $1)`: the two are the
+ * same test and only the operator form is INDEXABLE, because an index is matched against an
+ * operator expression and a bare function call is not one. The function form shipped first, on a
+ * stated fear of `?` being read as a parameter placeholder; the qualification is what answers that
+ * fear, and it is also immune to a `search_path` that shadows the operator.
  *
  * Three shapes, all of them Postgres': a top-level key of an object, a string ELEMENT of an array,
- * and a string value equal to the key. A number never matches — `jsonb_exists('[1]', '1')` is
- * false there, and a `String(item) === key` here would have made it true.
+ * and a string value equal to the key. A number never matches — `'[1]'::jsonb ? '1'` is false
+ * there, and a `String(item) === key` here would have made it true.
  */
 export const jsonHasKey = (value: unknown, key: unknown): boolean => {
   if (typeof key !== 'string' || isNull(value)) return false;

package/src/cursor.ts

@@ -7,10 +7,11 @@
 // to still exist, and a row deleted between two pages would silently restart pagination.
 
 import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
-import { columnFor } from './column';
+import { columnFor, columnName } from './column';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
-import { instantMicros } from './instant';
+import { identifierBytes, MAX_IDENTIFIER_BYTES } from './index-name';
+import { instantMicros, SEEK_ALIAS_SUFFIX, seekAlias } from './instant';
 import type { QueryPlan } from './tenancy';
 import type { AnyColumn, ColumnKind } from './types';
 
@@ -158,6 +159,38 @@ const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
   }
 };
 
+/**
+ * The one sort key that needs a SECOND output column, and therefore a second identifier: a
+ * `timestamptz` carries microseconds the decoded `Date` cannot hold, so the statement selects
+ * `<column>$US` beside it and `sortPrecision` (`pg-row.ts`) reads the exact instant back under
+ * that name.
+ *
+ * `assertColumnName` admits 63 bytes, which is the server's whole budget — so a column of 61 bytes
+ * produced a 64-byte alias, Postgres TRUNCATED it and said nothing, `sortPrecision` looked up a
+ * name the row does not carry, and `cursorFor` silently fell back to the millisecond `Date` this
+ * precision path exists to replace. The page then cuts at a position no row occupies and every row
+ * inside the boundary millisecond is served on no page at all — the exact defect `instant.ts` was
+ * written to close, reintroduced by a long column name.
+ *
+ * Refused where the PLAN is built rather than where the alias is read, for the reason the whole
+ * function exists: the read path has no error to raise, only a quieter answer. The bound is
+ * `index-name.ts`'s, never a second 63 — and the alias is BUILT rather than measured against a
+ * hard-coded suffix length, so changing the suffix cannot leave this arithmetic behind.
+ */
+const assertAliasFits = <Row>(entity: EntityCore<Row>, path: string): void => {
+  const alias = seekAlias(columnName(partsOf(path).property, columnAt(entity, path).$meta));
+  const bytes = identifierBytes(alias);
+  if (bytes <= MAX_IDENTIFIER_BYTES) return;
+  throw invariantViolated(
+    entity.$name,
+    'cursor',
+    `ordering by ${path} needs the output column "${alias}", which is ${bytes} bytes — ` +
+      `Postgres truncates past ${MAX_IDENTIFIER_BYTES} and says nothing, so the page would ` +
+      `silently lose microsecond precision: rename the column with ` +
+      `.column('<at most ${MAX_IDENTIFIER_BYTES - identifierBytes(SEEK_ALIAS_SUFFIX)} bytes>')`,
+  );
+};
+
 /**
  * A keyset seek only has a total order when every sort column is present on every row —
  * `null > 'x'` is unknown in SQL and would drop rows from the middle of a listing.
@@ -176,7 +209,7 @@ export const assertSeekable = <Row>(
   for (const key of orderBy) {
     // Resolving the kind is the other half: it refuses a column the entity never declared and a
     // money property named without its part — both mint a cursor nothing can decode.
-    kindAt(entity, key.column);
+    if (kindAt(entity, key.column) === 'timestamptz') assertAliasFits(entity, key.column);
     if (columnAt(entity, key.column).$meta.notNull) continue;
     // An ORDINARY nullable key is orderable, `As of 2026-08-24`: NULL has a declared place
     // (`asc nulls last` / `desc nulls first`), the cursor carries that place, and the seek reaches

package/src/index-name.ts

@@ -52,9 +52,10 @@ const indexDiscriminator = (
  * DECLARED names because those still differ. Bytes and not characters: 63 is what the server
  * counts, and `.length` would stop seeing the truncation the moment a name is not ASCII.
  */
-const MAX_IDENTIFIER_BYTES = 63;
+export const MAX_IDENTIFIER_BYTES = 63;
 
-const byteLength = (value: string): number => new TextEncoder().encode(value).length;
+/** Bytes, never `.length`: the truncation the server performs is counted in bytes. */
+export const identifierBytes = (value: string): number => new TextEncoder().encode(value).length;
 
 export const indexName = (
   entityName: string,
@@ -71,7 +72,7 @@ export const indexName = (
   const name = plain
     ? `${base}_${suffix}`
     : `${base}_${indexDiscriminator(order, where, using)}_${suffix}`;
-  const bytes = byteLength(name);
+  const bytes = identifierBytes(name);
   if (bytes <= MAX_IDENTIFIER_BYTES) return name;
   throw invariantViolated(
     entityName,

package/src/instant.ts

@@ -90,4 +90,7 @@ export const microsToIso = (micros: bigint): string => {
  * or a `.column()` name `assertColumnName` refuses unless it matches `[a-z_][a-z0-9_$]*` — so an
  * UPPER-CASE suffix is a name no entity can declare and this alias can never shadow a column.
  */
-export const seekAlias = (physicalColumn: string): string => `${physicalColumn}$US`;
+export const SEEK_ALIAS_SUFFIX = '$US';
+
+export const seekAlias = (physicalColumn: string): string =>
+  `${physicalColumn}${SEEK_ALIAS_SUFFIX}`;

package/src/memory-repo.ts

@@ -16,6 +16,7 @@ import { countsFrom, groupColumnOf } from './count-by';
 import { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound } from './errors';
+import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { compareByKind, matchesPredicate } from './memory-match';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions, Transactor, Tx } from './repo';
@@ -306,6 +307,15 @@ export const memoryRepo = <Row>(
       // `addressed()` — patching a row the app has already deleted is not an update, it is a
       // resurrection nobody asked for. `write` re-asserts the invariants on each result.
       const found = rowsOf(plan, {});
+      // The same ceiling `postgresRepo` applies from its own count, and for the same reason: this
+      // is the one write whose result size is the caller's FILTER rather than a page, and a rule
+      // only the app can judge is what forces every matched row through `$assert`. Without it a
+      // sweep of twelve million rows was green here and `X_INVARIANT_VIOLATED` there, from one
+      // call — a test proving a call production refuses. Before the loop, so a refusal never
+      // writes the rows it declined to judge.
+      if (hasJsOnlyInvariant(entity.$invariants) && found.length > MAX_ASSERTED_ROWS) {
+        throw assertedRowsTooMany(entity.$name, 'updateWhere', found.length);
+      }
       for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
       return found.length;
     },