@ultimat3/entity 30.8.0 → 31.0.0

package/src/driver-write-scope.ts

@@ -0,0 +1,107 @@
+// Single responsibility: the two write-side guards a custom store cannot be trusted with. The rows a
+// store hands back from a write are checked against the tenants the write named — a Mongo-style
+// upsert answering the STORED document of a global unique hands over another tenant's row — and a
+// same-tenant reference is judged by memory's own judge, over targets the kit looked up itself.
+
+import { keyOf } from './batch-read';
+import { kindOf, valueAt } from './cursor';
+import { describeReferences } from './describe';
+import { driverRowOutOfScope } from './driver-errors';
+import type { DriverRepo } from './driver-kit-types';
+import type { EntityCore } from './entity';
+import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
+import { getEntity } from './registry';
+import { assertRowTenant } from './tenancy';
+
+/** How the kit reaches another entity's raw store in the same driver. */
+export type RawFor = <R>(entity: EntityCore<R>) => DriverRepo<R>;
+
+const cell = (entity: EntityCore, property: string, value: unknown): string =>
+  keyOf(kindOf(entity, property) ?? '', value);
+
+/**
+ * Every returned row names a tenant one of the WRITTEN rows named — or, where a written row named
+ * none, passes the actor check `assertRowTenant` applies. Refused whole, never filtered.
+ */
+export const assertWrittenInScope = <Row>(
+  driverName: string,
+  entity: EntityCore<Row>,
+  operation: string,
+  written: readonly Row[],
+  returned: readonly Row[],
+): readonly Row[] => {
+  const column = entity.$tenantColumn;
+  if (column === null) return returned;
+  const own = entity as EntityCore;
+  const named = written.map((row) => valueAt(row, column));
+  const allowed = new Set(
+    named
+      .filter((value) => value !== null && value !== undefined)
+      .map((value) => cell(own, column, value)),
+  );
+  const anyUnnamed = named.some((value) => value === null || value === undefined);
+  for (const row of returned) {
+    const value = valueAt(row, column);
+    if (value !== null && value !== undefined && allowed.has(cell(own, column, value))) continue;
+    if (anyUnnamed) {
+      assertRowTenant(entity.$name, column, operation, row);
+      continue;
+    }
+    throw driverRowOutOfScope(driverName, entity.$name, operation, column);
+  }
+  return returned;
+};
+
+/** The properties holding a same-tenant reference — a patch naming one has to be judged. */
+export const sameTenantProperties = <Row>(entity: EntityCore<Row>): ReadonlySet<string> =>
+  entity.$tenantColumn === null
+    ? new Set()
+    : new Set(
+        describeReferences(entity.$name, Object.entries(entity.$columns))
+          .filter((edge) => edge.sameTenant !== null)
+          .map((edge) => edge.property),
+      );
+
+/**
+ * `sameTenantJudge` over a table of targets fetched first: each referenced value is read from the
+ * target's store UNSCOPED — the judge has to find a target in another tenant to refuse it — and the
+ * judge then answers exactly as it does for the memory driver (`X_DB_FOREIGN_KEY_VIOLATION`).
+ */
+export const sameTenantReferences = <Row>(entity: EntityCore<Row>, rawFor: RawFor) => {
+  const judge = (tables: MemoryTables) => sameTenantJudge(entity, tables);
+  return async (rows: readonly Row[]): Promise<void> => {
+    if (entity.$tenantColumn === null || rows.length === 0) return;
+    const edges = describeReferences(entity.$name, Object.entries(entity.$columns)).filter(
+      (edge) => edge.sameTenant !== null,
+    );
+    if (edges.length === 0) return;
+    const tables: MemoryTables = new Map();
+    for (const edge of edges) {
+      const target = getEntity(edge.targetEntity)?.core;
+      if (target === undefined || target.$tenantColumn === null) continue;
+      const values = [
+        ...new Set(
+          rows
+            .map((row) => valueAt(row, edge.property))
+            .filter((value) => value !== null && value !== undefined),
+        ),
+      ];
+      if (values.length === 0) continue;
+      const where = [{ column: edge.targetProperty, op: 'in' as const, value: values }];
+      const orderBy = target.$primaryKey.map((column) => ({ column, direction: 'asc' as const }));
+      const plan = { entity: target.$name, where, orderBy, limit: values.length };
+      const found = await rawFor(target).select({ plan, after: undefined, limit: values.length });
+      const prior = tables.get(target.$name);
+      tables.set(target.$name, {
+        entity: target,
+        find: (property, value) =>
+          found.find(
+            (row) =>
+              cell(target, property, valueAt(row, property)) === cell(target, property, value),
+          ) ?? prior?.find(property, value),
+      });
+    }
+    const verdict = judge(tables);
+    for (const row of rows) verdict(row, rows);
+  };
+};

package/src/entity-error.ts

@@ -49,6 +49,10 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_RETAIN_UNINDEXED',
   'X_ENTITY_COUNTS_INVALID',
   'X_ENTITY_READ_ONLY',
+  'X_DRIVER_UNSUPPORTED',
+  'X_DRIVER_CAPABILITY_MISSING',
+  'X_DRIVER_ROW_OUT_OF_SCOPE',
+  'X_ENTITY_PARTITION_INVALID',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -93,6 +97,12 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_COUNTS_INVALID:
     'references(…, { countedIn }) names no integer of its parent, or is no key to its primary key',
   X_ENTITY_READ_ONLY: 'a read-only entity was asked to write a row',
+  X_DRIVER_UNSUPPORTED: 'a custom driver was asked for a capability it does not declare',
+  X_DRIVER_CAPABILITY_MISSING:
+    'a custom driver declares a capability its raw repo does not implement',
+  X_DRIVER_ROW_OUT_OF_SCOPE: 'a custom driver returned a row outside the plan it was given',
+  X_ENTITY_PARTITION_INVALID:
+    'entity({ partitionBy }) declares a partitioning Postgres cannot build',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/entity-parse.ts

@@ -6,6 +6,7 @@ import { describeValue } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { newId } from './columns';
 import { invariantViolated } from './errors';
+import { holdsJsonNull } from './json-null';
 import { sealedMissing } from './sealed-errors';
 import type { AnyColumn, ColumnMeta } from './types';
 
@@ -41,7 +42,7 @@ export const rowParsers = <Row, Wire>(
       // spread of an omitted optional key produces and is the shape every existing caller has.
       const raw = input[property];
       const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
+      if (given === undefined || (given === null && !holdsJsonNull(column.$meta))) {
         if (column.$meta.notNull) {
           // A required sealed column ABSENT from a row is nearly always a spread of a repository
           // row, which does not enumerate it — so the refusal names that, and the rewrite.
@@ -72,7 +73,7 @@ export const rowParsers = <Row, Wire>(
     for (const [property, column] of wireEntries) {
       const raw = input[property];
       const given = raw === undefined ? defaultValue(column.$meta) : raw;
-      if (given === undefined || given === null) {
+      if (given === undefined || (given === null && !holdsJsonNull(column.$meta))) {
         if (column.$meta.notNull) {
           throw invariantViolated(name, property, 'is required and has no default');
         }

package/src/entity-patch.ts

@@ -3,6 +3,7 @@
 // would rewrite every column it did not name.
 
 import { invariantViolated } from './errors';
+import { holdsJsonNull } from './json-null';
 import { copyRow } from './sealed';
 import type { AnyColumn } from './types';
 
@@ -24,7 +25,8 @@ export const parseEntityPatch = <Patch>(
     const column = Object.hasOwn(columns, property) ? columns[property] : undefined;
     const value: unknown = descriptor.get === undefined ? descriptor.value : descriptor.get();
     if (column === undefined || value === undefined) continue;
-    if (value === null) {
+    // A NOT NULL `jsonb` column's `null` is the JSON value, judged by its schema below.
+    if (value === null && !holdsJsonNull(column.$meta)) {
       if (column.$meta.notNull) {
         throw invariantViolated(name, property, 'is required and has no default');
       }

package/src/entity.ts

@@ -7,6 +7,7 @@ import type { IndexMethod } from '@ultimat3/db';
 import type { Schema } from '@ultimat3/schema';
 import { assertAppendOnlyColumns } from './append-only';
 import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
+import { declaredIndexOf } from './declared-index';
 import {
   assertNotRetired,
   assertScan,
@@ -26,6 +27,7 @@ import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
 import { describeLifecycle, lifecycleHistory } from './lifecycle';
+import { type PartitionInit, partitionOf } from './partition';
 import { assertReadOnly } from './read-only';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
@@ -38,6 +40,7 @@ import { sealedInView } from './sealed-errors';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
+import { coveredByTenantIndex, tenantIndexOf, withoutDerivedDuplicate } from './tenant-index';
 import type { AnyColumn, ColumnMap, IndexDef, RowOf, WireRow } from './types';
 import type { EntityView } from './view';
 import { viewFor } from './view';
@@ -125,6 +128,12 @@ export interface EntityInit<C extends ColumnMap> {
   readonly retain?: RetainInit<keyof C & string>;
   /** Every row change recorded into `<table>_history` by trigger (`history.ts`, `$history`). */
   readonly history?: HistoryInit;
+  /**
+   * Range-partitioned by a `timestamp()`/`date()` in the primary key, one partition per `interval`
+   * (`partition.ts`). `x db gen` writes `partition by range` and the first partitions; a scheduled
+   * maintenance run creates `ahead` more and drops what `retain` expired. Never beside `retain`.
+   */
+  readonly partitionBy?: PartitionInit<keyof C & string>;
   /** Set by `history.ts` on the history entity it declares: the parent's name. Never by hand. */
   readonly historyOf?: string;
 }
@@ -307,6 +316,7 @@ export const entity = <const C extends ColumnMap>(
       const physical = [
         meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
       ];
+      if (coveredByTenantIndex(physical[0] ?? '', tenant, meta.unique)) return [];
       return [
         {
           name: indexName(name, table, physical, meta.unique),
@@ -315,58 +325,9 @@ export const entity = <const C extends ColumnMap>(
         },
       ];
     }),
-    ...(init.indexes ?? []).map((index) => {
-      const columns = index.on.map((property) => resolve([property]));
-      const unique = index.unique === true;
-      // `on: []` is type-legal and names nothing: the generated DDL would be `on "posts" ()`, a
-      // syntax error one migration later. Refused where it was written instead.
-      if (columns.length === 0) {
-        throw invariantViolated(name, 'index', 'an index must name at least one column');
-      }
-      const where = index.where?.(columnsExpr).toSql(resolve) ?? null;
-      if (index.where !== undefined && where === null) {
-        throw invariantViolated(
-          name,
-          'index',
-          'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
-        );
-      }
-      // Two rules Postgres has that a declaration can break, refused where the author wrote it.
-      // `@ultimat3/db` refuses both again at `createIndex` — that is not a duplicate, it is the
-      // guard for a description nobody built here — but its refusal lands at `x db gen` or, if a
-      // migration was already written, inside `ROLE=migrate` as the server's own syntax error with
-      // none of the entity's words in it.
-      if (index.using !== undefined && index.using !== 'btree') {
-        if (unique) {
-          throw invariantViolated(
-            name,
-            'index',
-            `the index on (${columns.join(', ')}) is unique and ${index.using}; ` +
-              `Postgres has no unique ${index.using} index — drop unique, or drop using`,
-          );
-        }
-        if (index.order !== undefined) {
-          throw invariantViolated(
-            name,
-            'index',
-            `the index on (${columns.join(', ')}) is ${index.using} and ${index.order}; ` +
-              'only a btree orders its keys — drop order, or drop using',
-          );
-        }
-      }
-      return {
-        name: indexName(name, table, columns, unique, index.order, where, index.using),
-        columns,
-        unique,
-        ...(index.order === undefined ? {} : { order: index.order }),
-        ...(where === null ? {} : { where }),
-        // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
-        // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
-        ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
-        // How it is BUILT, so not part of the name: `true` or absent, like `appendOnly`.
-        ...(index.concurrently === true ? { concurrently: true as const } : {}),
-      };
-    }),
+    ...(init.indexes ?? []).map((index) =>
+      declaredIndexOf(index, { name, table, resolve, columns: columnsExpr }),
+    ),
     // The one index nobody declared and every search needs. Through the SAME `IndexInit` path a
     // hand-written `using: 'gin'` takes — `indexName` gives it the method discriminator, so it can
     // never collide with a btree an author declares on the same column.
@@ -381,10 +342,34 @@ export const entity = <const C extends ColumnMap>(
           },
         ]),
   ];
+  // After every other index, so one that already starts with `(tenant, pk)` is seen (`tenant-index.ts`).
+  const physicalKey = primaryKey.map((property) => resolve([property]));
+  const [tenantIndex] = tenantIndexOf({
+    entityName: name,
+    table,
+    tenant,
+    primaryKey: physicalKey,
+    plainView: init.view != null && init.view.materialized !== true,
+    covering: [
+      ...declared.filter((index) => index.where == null && index.using === undefined),
+      ...invariants.filter((inv) => inv.kind === 'unique' && inv.where == null),
+    ].map((each) => each.columns),
+  });
   // A foreign key's own index named again in `indexes` is one index, not two (`index-identity.ts`).
-  const indexes = distinctIndexes(declared);
+  const indexes = distinctIndexes(
+    tenantIndex === undefined ? declared : [...declared, tenantIndex],
+  );
 
   const retain = retainOf(name, init.retain, entries, indexes, appendOnly);
+  const partition = partitionOf(name, init.partitionBy, {
+    table,
+    columns: entries,
+    primaryKey,
+    indexes,
+    uniques: invariants.filter((inv) => inv.kind === 'unique').map((inv) => inv.columns),
+    retain: init.retain !== undefined,
+    view: init.view != null,
+  });
   const sealed = sealedFields({ $name: name, $table: table, $columns: init.columns });
   assertSealedDeclaration({
     name,
@@ -411,7 +396,7 @@ export const entity = <const C extends ColumnMap>(
       columns: entries,
       primaryKey,
       invariants,
-      indexes,
+      indexes: withoutDerivedDuplicate(table, physicalKey, tenantIndex, indexes),
       tags,
       cacheTag,
       softDelete,
@@ -424,6 +409,7 @@ export const entity = <const C extends ColumnMap>(
       readOnly: init.readOnly,
       view: viewQuery,
       lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
+      partition,
     });
   assertNotRetired(name, entries, init.retired);
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);

package/src/enum-column.ts

@@ -14,6 +14,14 @@ import type { ColumnMeta, EnumeratedColumn } from './types';
  * transaction on older servers.
  */
 export const enumerated = <const V extends readonly string[]>(values: V): EnumeratedColumn<V> => {
+  // An empty set renders `x in ()`, which `x db migrate` dies on with 42601 — refused here instead.
+  if (values.length === 0) {
+    refuseColumn(
+      'enum',
+      'the set of allowed values is empty — no row could ever hold this column',
+      "enumerated(['draft', 'published']) — declare at least one value; a column with no legal value is a column to delete",
+    );
+  }
   const allowed = new Set<string>(values);
   const parse = (value: unknown): V[number] =>
     typeof value === 'string' && allowed.has(value)

package/src/index.ts

@@ -1,5 +1,12 @@
 // The public surface of @ultimat3/entity. Explicit, never `export *`.
 
+// The `entity.*` payloads are core's (the bus is tier 0); re-exported, never a second shape.
+export type {
+  EntityBulkEvent,
+  EntityCrossTenantEvent,
+  EntityRowEvent,
+  EntityRowOp,
+} from '@ultimat3/core';
 /** Re-exported so an `entity` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
@@ -32,10 +39,11 @@ export type { Counter } from './counter';
 export { countersOf, describeCounter } from './counter';
 // `crossTenantReason` stays internal: an app that could read the flag would have a second way to
 // reason about tenant scope — branch on it — next to the one way, which is entering the scope.
-export { CROSS_TENANT_SCOPE, crossTenant, setCrossTenantObserver } from './cross-tenant';
+export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
+// Leaves, so a reader of a row's key (`@ultimat3/jobs`' reindex sweep) skips `./adapter`'s driver kit.
+export { kindOf } from './cursor';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
-export type { DescribeInput } from './describe';
 export type { TenantColumnDescription } from './describe-tenancy';
 export { describeTenancy } from './describe-tenancy';
 export type { Entity, EntityCore, EntityInit } from './entity';
@@ -46,41 +54,24 @@ export { entity, SOFT_DELETE_COLUMN } from './entity';
 export type {
   EntityErrorCode,
   PreloadCandidate,
-  QueryLoopBatch,
-  WriteLoopBatch,
 } from './errors';
 // Every error factory this package owns, its three tenancy siblings included: `Driver` is public,
 // so a third-party driver has to be able to raise the same refusals the two shipped ones do.
 export {
-  crossTenantDenied,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
   EntityError,
   entityDuplicate,
   invariantViolated,
   notFound,
-  nPlusOneQuery,
-  nPlusOneWrite,
   patchEmpty,
   preloadUnknownRelation,
-  repoClientPinned,
-  tenancyActorMismatch,
   tenancyActorOrgRequired,
   tenancyRowMismatch,
-  tenancyUnscoped,
-  writeUnfiltered,
 } from './errors';
 export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
 export { iff } from './expr';
 /** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
-export type { IllegalTransition } from './feature-errors';
-export {
-  searchInMemory,
-  searchUndeclared,
-  stateConflict,
-  stateTransitionIllegal,
-  stateUndeclared,
-} from './feature-errors';
 export type { HistoryColumns, HistoryEntity, HistoryInit } from './history';
 export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
@@ -94,7 +85,20 @@ export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
 export { isOperator, OPERATORS } from './operator';
+// `entity({ partitionBy })`, checked at declaration (`partition.ts`); the SQL is `@ultimat3/db`'s.
+export type {
+  PartitionContext,
+  PartitionDescription,
+  PartitionInit,
+} from './partition';
+export { partitionOf } from './partition';
 export { persistedRecordTypes } from './persisted-types';
+// GDPR: the personal-data column marker and its readers (`personal-data.ts`).
+export type { PersonalDataColumn, PersonalDataEntity, PersonalDataKind } from './personal-data';
+export {
+  personalDataEntities,
+  personalDataOf,
+} from './personal-data';
 // For a change feed holding a table name and raw columns: `entityForTable` + `decodeRow` is the row
 // the app declared, money and all. Exported for `@ultimat3/realtime` (plan 101, 06 i).
 export type { PgArray } from './pg-array-literal';
@@ -154,8 +158,8 @@ export type {
   UpsertArgs,
 } from './repo';
 export type { Retain, RetainInit } from './retain';
-export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
-export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+export { rowKey } from './row-key';
+export { observedRepo } from './row-observer';
 export { rowSecuritySettings } from './row-security-settings';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
@@ -168,14 +172,27 @@ export { sealedRepo } from './sealed-repo';
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
 export {
-  DEFAULT_SEARCH_COLUMN,
-  DEFAULT_SEARCH_LANGUAGE,
-  DEFAULT_SEARCH_WEIGHT,
-  isSearchLanguage,
-  isSearchWeight,
   SEARCH_LANGUAGES,
   SEARCH_WEIGHTS,
 } from './search';
+// The searchIndex port: types, the document builder, the installed index, the two shipped ones.
+export type {
+  SearchDocument,
+  SearchHit,
+  SearchIndex,
+  SearchIndexOptions,
+  SearchListEntry,
+  SearchListPage,
+  SearchListQuery,
+  SearchQuery,
+  SearchScope,
+} from './search-index';
+export { searchDocumentOf } from './search-index';
+export { searchIndex } from './search-index-installed';
+export { memorySearchIndex } from './search-index-memory';
+export type { PostgresSearchIndexOptions } from './search-index-postgres';
+export { postgresSearchIndex } from './search-index-postgres';
+export { searchVersionColumn, searchVersionOf } from './search-index-version';
 export type {
   Seed,
   SeedContext,
@@ -195,7 +212,6 @@ export {
   canMove,
   isState,
   isTerminal,
-  movesFrom,
   stateMachineOf,
 } from './state-machine';
 export type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';

package/src/json-null.ts

@@ -0,0 +1,13 @@
+// Single responsibility: when a `null` handed to a column is the JSON VALUE `null` rather than SQL
+// NULL. One rule, read by the parsers, the Postgres binder and decoder, and the memory matcher —
+// a copy in any one of them is a row the two drivers spell differently.
+
+import type { ColumnMeta } from './types';
+
+/**
+ * A NOT NULL `jsonb` column: the table holds no SQL NULL, so a `null` reaching it can only be the
+ * JSON literal, judged by the column's schema like any other JSON value and stored as
+ * `'null'::jsonb`. A NULLABLE `jsonb` column keeps `null` as SQL NULL — the clear every other
+ * nullable column means by it, and what `is null` answers in both drivers.
+ */
+export const holdsJsonNull = (meta: ColumnMeta): boolean => meta.kind === 'jsonb' && meta.notNull;

package/src/memory-match.ts

@@ -5,6 +5,7 @@
 // deciding by `typeof` is answering a different question.
 
 import { keyOf } from './batch-read';
+import { columnFor } from './column';
 import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './containment';
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
@@ -12,6 +13,7 @@ import { EntityError } from './errors';
 import { searchInMemory } from './feature-errors';
 import { instantMicros } from './instant';
 import { isNullish as isNull } from './is-null';
+import { holdsJsonNull } from './json-null';
 import { likeMatches } from './like';
 import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import { operatorUnknown } from './operator';
@@ -21,15 +23,44 @@ import type { ColumnKind } from './types';
 const sign = <T extends number | bigint | string>(left: T, right: T): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
+/**
+ * Text in CODE-POINT order, which is byte order over UTF-8 and so Postgres' `C` collation — the
+ * order `auth`'s memory adapter already keeps. JS `<` compares UTF-16 code units, which puts an
+ * astral character (lead surrogate 0xD800–0xDBFF) ahead of U+E000–U+FFFF: `'😀' < '！'` is true
+ * here and false there, so a page cut on a text key differed between dev and prod. The first
+ * differing unit decides; `codePointAt` there reads the whole character when it is a lead surrogate.
+ */
+export const byCodePoint = (left: string, right: string): number => {
+  const shorter = Math.min(left.length, right.length);
+  for (let at = 0; at < shorter; at += 1) {
+    if (left.charCodeAt(at) !== right.charCodeAt(at)) {
+      return sign(left.codePointAt(at) ?? 0, right.codePointAt(at) ?? 0);
+    }
+  }
+  return sign(left.length, right.length);
+};
+
+/**
+ * An `integer()` operand written as TEXT is the number Postgres parses it as: the parameter takes
+ * the column's type, so `id = '007'` finds row 7 there, and `===` against `7` found nothing here.
+ * Only an integer literal is read; anything else stays as written and compares as text.
+ */
+const INTEGER_TEXT = /^\s*[+-]?\d+\s*$/;
+const asInteger = (kind: ColumnKind | undefined, value: unknown): unknown =>
+  kind === 'integer' && typeof value === 'string' && INTEGER_TEXT.test(value)
+    ? Number(value)
+    : value;
+
 /**
  * Two values of one column, ordered as Postgres orders that column. `-1`, `0` or `1` — never a
  * difference, so a `bigint` pair needs no subtraction it cannot express in a `number`.
  */
 export const compareByKind = (
   kind: ColumnKind | undefined,
-  left: unknown,
-  right: unknown,
+  given: unknown,
+  operand: unknown,
 ): number => {
+  const [left, right] = [asInteger(kind, given), asInteger(kind, operand)];
   // NULL is the LARGEST value, which is what `order by` means in Postgres and what `nulls last`
   // ascending / `nulls first` descending spell out (`pg-sql.ts`'s `orderSql`, `@ultimat3/query`'s
   // `compareValues`). Two absences are equal, so the next sort key decides — without this rule a
@@ -62,7 +93,7 @@ export const compareByKind = (
   // `undefined` means the pair is not a numeric comparison, and it falls through as text.
   const numeric = numericOrder(kind !== undefined && DECIMAL_TEXT.has(kind), left, right);
   if (numeric !== undefined) return numeric;
-  return sign(String(left), String(right));
+  return byCodePoint(String(left), String(right));
 };
 
 /**
@@ -74,9 +105,10 @@ export const compareByKind = (
  */
 export const sameValueOfKind = (
   kind: ColumnKind | undefined,
-  left: unknown,
-  right: unknown,
+  given: unknown,
+  operand: unknown,
 ): boolean => {
+  const [left, right] = [asInteger(kind, given), asInteger(kind, operand)];
   if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
   // An instant handed over as ISO text is the instant it names, as Postgres parses the bound
   // parameter: `eq` against a stored `Date` compared an object to a string and matched no row.
@@ -111,6 +143,10 @@ export const matchesPredicate = <Row>(
   // predicate and a money sort key both name.
   const kind = kindOf(entity, predicate.column);
   const actual = valueAt(row, predicate.column);
+  // The row side of every NULL test. A NOT NULL `jsonb` column holding `null` holds the JSON
+  // literal (`json-null.ts`), which Postgres' `is null` never matches and its `@>` compares.
+  const held = columnFor(entity.$columns, predicate.column);
+  const rowIsNull = isNull(actual) && !(held !== undefined && holdsJsonNull(held.$meta));
   /**
    * `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
@@ -124,34 +160,32 @@ export const matchesPredicate = <Row>(
    * `valueAt(row, 'price.minor')` has nothing to read.
    */
   const equals = (candidate: unknown): boolean =>
-    !isNull(actual) && !isNull(candidate) && sameValueOfKind(kind, actual, candidate);
+    !rowIsNull && !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
   // before `"z"`: `gt(seats, 5)` answered the null row in memory and never in production, and
   // `lt(seats, null)` answered every row. The guard is HERE and not in `compareByKind`, which also
   // orders a page — a sort puts NULLs last (`asc nulls last`) rather than dropping them.
-  const unknown = (): boolean => isNull(actual) || isNull(predicate.value);
+  const unknown = (): boolean => rowIsNull || 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 predicate.value === null ? isNull(actual) : equals(predicate.value);
+      return predicate.value === null ? rowIsNull : 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 isNull(predicate.value) ? !isNull(actual) : !equals(predicate.value);
+      return isNull(predicate.value) ? !rowIsNull : !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((candidate) =>
-          isNull(candidate) ? isNull(actual) : equals(candidate),
-        )
+        predicate.value.some((candidate) => (isNull(candidate) ? rowIsNull : equals(candidate)))
       );
     case 'gt':
       return !unknown() && order() > 0;
@@ -166,22 +200,22 @@ export const matchesPredicate = <Row>(
     case 'like':
       return !unknown() && likeMatches(entity.$name, String(predicate.value), String(actual));
     case 'is-null':
-      return isNull(actual);
+      return rowIsNull;
     case 'is-not-null':
-      return !isNull(actual);
+      return !rowIsNull;
     // The containment half, decided by the column's DECLARED kind exactly as everything above it
     // is: `@>` on a `jsonb` is recursive structural containment and `@>` on an array is plain
     // element containment, and those are two different operators that happen to share a symbol.
     // A NULL column value matches nothing, which is what the SQL answers too.
     case 'contains':
-      return !isNull(actual) && containsBy(kind, actual, predicate.value);
+      return !rowIsNull && containsBy(kind, actual, predicate.value);
     case 'contained-by':
-      return !isNull(actual) && containsBy(kind, predicate.value, actual);
+      return !rowIsNull && containsBy(kind, predicate.value, actual);
     // `&&` is arrays only. A `jsonb` column reaching it is refused rather than guessed at: there
     // is no `jsonb && jsonb` in Postgres, so any answer here would be one no statement can make.
     case 'overlaps':
       return (
-        !isNull(actual) &&
+        !rowIsNull &&
         arrayOverlaps(
           asArray(entity, predicate, actual),
           asArray(entity, predicate, predicate.value),