@ultimat3/entity 9.0.0 → 11.0.0

package/CLAUDE.md

@@ -60,7 +60,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   wrapped into a one-element list for the SQL and refused in memory — 0 rows against one driver, 1
   against the other, from a call `andWhere(column, op, value: unknown)` compiles), and a list
   carrying a NULL emits `(col in (…) or col is null)` — `col = null` is UNKNOWN, so the null row
-  the caller listed was the one row Postgres left out while memory included it.
+  the caller listed was the one row Postgres left out while memory included it. **A column the row
+  never NAMED is NULL**, `As of 2026-08-23`: the table holds NULL whether a row spelled it out or
+  omitted it, so `eq`, `neq` and `in` read the row side through `isNull` exactly as `is-null` and
+  the ordering guard already did — `===` made the two rows different, and `eq null` skipped the
+  absent one, `in [null]` missed it and `neq null` answered it, each the opposite of the same
+  predicate in production. A `money()` column holding NULL reaches this with no hand-built row at
+  all: `valueAt(row, 'price.minor')` has nothing to read, whatever `$parse` produced.
 - **The Postgres driver is proved against a real Postgres, not only against a recording client.**
   `pg-driver.live.test.ts` runs the whole chain — `entity()` -> `$describe()` ->
   `generateMigration()` -> a live server -> `postgresDriver()` -> decoded row — and skips when no
@@ -354,9 +360,14 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   or a filter alone never addresses a row on a tenant-scoped entity — another tenant's id reads as
   `X_NOT_FOUND`, never as their row. That bounds WHICH rows a write touches; it cannot bound what
   they become, and `insert`/`insertAll`/`upsertAll` build no plan at all. So the VALUE is judged as
-  well, by `assertRowTenant` (`tenancy.ts`) at the four seams every write passes: `memoryRepo`'s
-  `write()` plus its `insertAll`/`upsertAll` batch loops, and `postgresRepo`'s `writeRows()`,
-  `update` and `updateWhere`. A row or patch naming another tenant is `X_TENANCY_ACTOR_MISMATCH` —
+  well, by `assertRowTenant` (`tenancy.ts`) at the seams every write passes: `memoryRepo`'s
+  `write()` plus its `insertAll`/`upsertAll` batch loops and its `updateWhere`, and
+  `postgresRepo`'s `writeRows()`, `update` and `updateWhere`. **A filtered update judges the PATCH,
+  before it reads a row** — `As of 2026-08-23`, in both drivers. `memoryRepo` judged the merged
+  rows inside its loop, and a loop over no rows judges nothing, so
+  `updateWhere(filter, { orgId: theirs })` over a filter matching nothing answered `0` in memory
+  and `X_TENANCY_ACTOR_MISMATCH` in Postgres: whether the guard fired depended on what the table
+  held rather than on what the caller asked for. A row or patch naming another tenant is `X_TENANCY_ACTOR_MISMATCH` —
   the same code the read path throws, because it is the same mistake in a different argument.
   Rules, none optional. **Refuse, never stamp**: a row that names no tenant is left alone and the
   column's `NOT NULL` answers it. Filling one in from the actor would change the column list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "9.0.0",
+  "version": "11.0.0",
   "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": "9.0.0",
-    "@ultimat3/db": "9.0.0",
-    "@ultimat3/schema": "9.0.0",
-    "@ultimat3/time": "9.0.0"
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/db": "11.0.0",
+    "@ultimat3/schema": "11.0.0",
+    "@ultimat3/time": "11.0.0"
   }
 }

package/src/entity.ts

@@ -3,6 +3,7 @@
 // (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
 // this one call.
 
+import { renderThrowable } from '@ultimat3/core';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
@@ -284,9 +285,13 @@ export const entity = <const C extends ColumnMap>(
           try {
             return { value: parse(value) };
           } catch (error) {
-            return {
-              issues: [{ message: error instanceof Error ? error.message : String(error) }],
-            };
+            // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`:
+            // both halves of that read the caught value directly. `instanceof` consults
+            // `getPrototypeOf` and `String()` runs the value's own coercion, so a `Proxy` or a
+            // null-prototype throwable raised a SECOND, uncatchable `TypeError` out of the
+            // validator — where a rejection belongs. A column parser is app-reachable and an
+            // app's `$parse` may throw anything at all.
+            return { issues: [{ message: renderThrowable(error) }] };
           }
         },
       },

package/src/errors.ts

@@ -61,6 +61,14 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
+/**
+ * Base for every error this package throws. No `docs:` — `UltimateError` fills it from
+ * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
+ * code, never one per code, because `wiki/` is the framework's only public documentation surface
+ * and a code lives there in a TABLE ROW, which has no anchor. The
+ * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
+ * included, on every refusal it has ever raised.
+ */
 export class EntityError extends UltimateError {
   override readonly name = 'EntityError';
 
@@ -69,7 +77,6 @@ export class EntityError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: `https://ultimate.dev/errors/${init.code}`,
     });
   }
 }

package/src/memory-match.ts

@@ -141,7 +141,20 @@ export const matchesPredicate = <Row>(
   // predicate and a money sort key both name.
   const kind = kindOf(entity, predicate.column);
   const actual = valueAt(row, predicate.column);
-  const same = (candidate: unknown): boolean => sameValueOfKind(kind, actual, candidate);
+  /**
+   * `col = <value>`, with SQL's three-valued logic on both sides: a NULL is never EQUAL to
+   * anything, the other NULL included, so `equals` answers false the moment either side is one
+   * and the operators below decide what that means for them.
+   *
+   * The row side reads through `isNull`, so a row that never NAMED a nullable column is the same
+   * row as one that stored `null` — which is what the table holds for both, and what `is-null`
+   * has always answered here. `===` made them two: `eq null` skipped the absent row, `in [null]`
+   * missed it and `neq null` answered it, each the opposite of the same predicate in production.
+   * A `money()` column holding NULL reaches this every time, with no hand-built row at all —
+   * `valueAt(row, 'price.minor')` has nothing to read.
+   */
+  const equals = (candidate: unknown): boolean =>
+    !isNull(actual) && !isNull(candidate) && sameValueOfKind(kind, actual, candidate);
   // `col > NULL` is UNKNOWN in SQL and UNKNOWN is not a match, so a NULL on EITHER side matches no
   // row here either — `predicateSql` emits a bare `"col" > $1` and Postgres returns nothing. Without
   // this the fall-through compared `String(null)` as the text `"null"`, which sorts after `"5"` and
@@ -151,14 +164,25 @@ export const matchesPredicate = <Row>(
   const unknown = (): boolean => isNull(actual) || isNull(predicate.value);
   const order = (): number => compareByKind(kind, actual, predicate.value);
   switch (predicate.op) {
+    // `predicateSql` compiles a null operand to `"col" is null` rather than binding it, so this
+    // is the same predicate, not a widening of it.
     case 'eq':
-      return same(predicate.value);
+      return predicate.value === null ? isNull(actual) : equals(predicate.value);
+    // `is distinct from` reads a NULL as a value on BOTH sides: TRUE where one side is null and
+    // the other is not, FALSE where both are. A bound `undefined` is a NULL parameter there, so
+    // the operand side reads through `isNull` and the two spellings mean one thing.
     case 'neq':
-      return !same(predicate.value);
+      return isNull(predicate.value) ? !isNull(actual) : !equals(predicate.value);
     // `in` reads a LIST or nothing: an operand that is not an array matches no row, which is what
     // `predicateSql` now compiles it to and what `@ultimat3/query` answers for the same operand.
+    // A NULL inside the list is asked as `is null` beside the list there, for the same reason.
     case 'in':
-      return Array.isArray(predicate.value) && predicate.value.some(same);
+      return (
+        Array.isArray(predicate.value) &&
+        predicate.value.some((candidate) =>
+          isNull(candidate) ? isNull(actual) : equals(candidate),
+        )
+      );
     case 'gt':
       return !unknown() && order() > 0;
     case 'gte':

package/src/repo.ts

@@ -413,10 +413,17 @@ export const memoryRepo = <Row>(
     },
 
     async updateWhere(filter, patch, options) {
+      const plan = updatePlan(entity, filter, patch, options, 'updateWhere');
+      // The PATCH, judged whole and before the rows are read — the same call `postgresRepo` makes
+      // before its statement exists. Inside the loop below it is judged only where a row was
+      // matched, so a patch handing rows to another tenant was refused or accepted depending on
+      // what the table happened to hold: `updateWhere(filter, { orgId: theirs })` over a filter
+      // matching nothing answered `0` here and threw there, from one call.
+      assertRowTenant(entity.$name, entity.$tenantColumn, 'updateWhere', patch);
       // `rowsOf` again, so a soft-deleted row is as unreachable here as it is through
       // `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(updatePlan(entity, filter, patch, options, 'updateWhere'), {});
+      const found = rowsOf(plan, {});
       for (const row of found) write(Object.assign({}, row, patch), options, 'updateWhere');
       return found.length;
     },

package/src/view.ts

@@ -3,6 +3,7 @@
 // already describe. Values are validated by the entity's own column parsers; an unknown key is a
 // declaration-time failure, not a surprise on the first request.
 
+import { renderThrowable } from '@ultimat3/core';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { invariantViolated } from './errors';
 import type { AnyColumn, ColumnMap } from './types';
@@ -83,9 +84,10 @@ export const viewFor = <Row, K extends keyof Row & string>(
         try {
           return { value: parse(value) };
         } catch (error) {
-          return {
-            issues: [{ message: error instanceof Error ? error.message : String(error) }],
-          };
+          // The entity's rule, for the same reason: `instanceof` and `String()` are both reads of
+          // a caught value, and a throwable that fights being read turned a rejected projection
+          // into an uncatchable `TypeError`. `renderThrowable` is total.
+          return { issues: [{ message: renderThrowable(error) }] };
         }
       },
     },