@ultimat3/entity 11.3.0 → 12.0.0

package/src/aggregate.ts

@@ -0,0 +1,232 @@
+// Single responsibility: what an aggregate MEANS — which column kinds each function may be applied
+// to, what its answer is shaped like, and the exact arithmetic. Both drivers read it from here, so
+// a `sum` against memory means what a `sum` against Postgres means; a rule added to one driver
+// alone is the drift the two-driver split exists to prevent.
+//
+// Nothing here is a float. `sum` and `avg` answer decimal TEXT, money answers `MoneyValue` — the
+// same reason `bigint()` and `decimal()` hand back strings: a `number` loses digits past 2^53 and
+// a binary float loses cents.
+
+import { columnFor } from './column';
+import type { EntityCore } from './entity';
+import { EntityError } from './errors';
+import type { AnyColumn, ColumnKind } from './types';
+
+/** The four, closed. A fifth is a new member here and a new case in both drivers, never one. */
+export type AggregateFn = 'sum' | 'avg' | 'min' | 'max';
+
+/**
+ * Which kinds each function may be applied to. Closed sets rather than "whatever Postgres accepts",
+ * because the bar is what BOTH drivers can answer identically.
+ *
+ * `text` and `char` are deliberately absent from `min`/`max` even though Postgres has them: text
+ * ordering there is the database's COLLATION and here it is JS's UTF-16 code-unit order, and the
+ * two disagree on ordinary data (`'a' < 'B'` under `en_US`, `'B' < 'a'` by code unit). A comparison
+ * this package cannot make agree is refused rather than answered twice differently — the same
+ * decision `memory-match.ts` records for decimal text, in the other direction.
+ *
+ * `boolean`, `uuid`, `jsonb`, `array` and `bytea` are absent everywhere: none of them has an
+ * ordering or a sum a caller would mean.
+ */
+const NUMERIC: readonly ColumnKind[] = ['integer', 'bigint', 'numeric'];
+const ORDERED: readonly ColumnKind[] = ['integer', 'bigint', 'numeric', 'timestamptz', 'date'];
+
+const ALLOWED = new Map<AggregateFn, ReadonlySet<ColumnKind>>([
+  ['sum', new Set<ColumnKind>([...NUMERIC, 'money'])],
+  ['avg', new Set<ColumnKind>(NUMERIC)],
+  ['min', new Set<ColumnKind>([...ORDERED, 'money'])],
+  ['max', new Set<ColumnKind>([...ORDERED, 'money'])],
+]);
+
+export const aggregatable = (fn: AggregateFn, kind: ColumnKind): boolean =>
+  ALLOWED.get(fn)?.has(kind) === true;
+
+/**
+ * `avg` over money is refused rather than rounded. The average of 1, 1 and 2 minor units is 4/3 of
+ * a unit, and every representable answer is a rounding — which is the defect `MoneyValue.scale`
+ * exists to prevent, so inventing one at the aggregate would reopen it one layer up. The caller
+ * decides the rounding, out of two exact numbers.
+ */
+export const notAggregatable = (
+  entityName: string,
+  fn: AggregateFn,
+  property: string,
+  kind: ColumnKind,
+  candidates: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_AGGREGATE_UNSUPPORTED',
+    cause:
+      fn === 'avg' && kind === 'money'
+        ? `${entityName}.avg('${property}') — the mean of an integer number of minor units is not one, and every answer would be a silent rounding`
+        : `${entityName}.${fn}('${property}') — a ${kind} column has no ${fn} both drivers can answer the same way`,
+    fix:
+      fn === 'avg' && kind === 'money'
+        ? `${entityName}.sum('${property}') and ${entityName}.count() — divide at the call site, where the rounding is a decision somebody made`
+        : candidates.length === 0
+          ? `x entities describe ${entityName} --json   # this entity declares no column ${fn} can be applied to`
+          : `${entityName}.${fn}('${candidates[0]}')   # ${fn} takes one of: ${candidates.join(', ')}`,
+  });
+
+/**
+ * Money crossing currencies has no sum, no minimum and no maximum: 100 JPY and 100 EUR are not
+ * comparable and adding them answers a number in no currency at all. Both drivers count the
+ * distinct currencies of the rows they are about to aggregate and refuse past one, rather than
+ * silently answering in whichever currency happened to come first.
+ */
+export const mixedCurrency = (
+  entityName: string,
+  fn: AggregateFn,
+  property: string,
+  currencies: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_AGGREGATE_MIXED_CURRENCY',
+    cause: `${entityName}.${fn}('${property}') covers ${currencies.length} currencies (${[...currencies].sort().join(', ')}) — they have no common unit`,
+    fix: `${entityName}.andWhere('${property}.currency', 'eq', '${[...currencies].sort()[0]}').${fn}('${property}')   # one currency per call, or countBy('${property}.currency') first`,
+  });
+
+/** Digits only, optionally signed, optionally with a fraction. What `decimal()` hands back. */
+const DECIMAL_TEXT = /^-?\d+(\.\d+)?$/;
+
+/** The scale `avg` answers at, in both drivers. Fixed, so the two cannot round to different places. */
+export const AVG_SCALE = 6;
+
+interface Decimal {
+  readonly units: bigint;
+  readonly scale: number;
+}
+
+const parseDecimal = (text: string): Decimal | undefined => {
+  if (!DECIMAL_TEXT.test(text)) return undefined;
+  const [whole = '0', fraction = ''] = text.split('.');
+  return { units: BigInt(`${whole}${fraction}`), scale: fraction.length };
+};
+
+const rescale = (value: Decimal, scale: number): bigint =>
+  value.units * 10n ** BigInt(scale - value.scale);
+
+const render = (units: bigint, scale: number): string => {
+  if (scale === 0) return units.toString();
+  const negative = units < 0n;
+  const digits = (negative ? -units : units).toString().padStart(scale + 1, '0');
+  const whole = digits.slice(0, digits.length - scale);
+  return `${negative ? '-' : ''}${whole}.${digits.slice(digits.length - scale)}`;
+};
+
+/**
+ * The exact sum of decimal text, at the widest scale any term carries — which is what Postgres'
+ * `sum(numeric)` answers, and what no `Number()` can: `0.1 + 0.2` is `0.30000000000000004` in a
+ * binary float and `0.3` here, and an `int8` past 2^53 keeps every digit.
+ *
+ * `null` for an empty set, exactly as `sum` over no rows is NULL in SQL — never `0`, which would
+ * claim rows were counted.
+ */
+export const sumDecimalText = (values: readonly string[]): string | null => {
+  if (values.length === 0) return null;
+  const parsed = values.map(parseDecimal);
+  if (parsed.some((value) => value === undefined)) return null;
+  const decimals = parsed as readonly Decimal[];
+  const scale = decimals.reduce((widest, value) => Math.max(widest, value.scale), 0);
+  return render(
+    decimals.reduce((total, value) => total + rescale(value, scale), 0n),
+    scale,
+  );
+};
+
+/**
+ * `sum / count`, rounded half away from zero at `AVG_SCALE` — which is what Postgres' `round()`
+ * does to a `numeric`, and the reason the statement asks for `round(avg(...), 6)` rather than the
+ * server's own default scale: two drivers rounding at different places answer two numbers.
+ */
+export const averageDecimalText = (total: string | null, count: number): string | null => {
+  if (total === null || count === 0) return null;
+  const parsed = parseDecimal(total);
+  if (parsed === undefined) return null;
+  // The EXACT rational, rounded once. Dividing first and rounding after would truncate digits the
+  // rounding decision depends on — and rescaling to a fixed number of digits rather than to
+  // AVG_SCALE is what made this answer 11000.000000 where Postgres said 1.100000: `rescale` takes
+  // an absolute target scale, and the first draft handed it a relative one.
+  const digits = Math.max(parsed.scale, AVG_SCALE);
+  const numerator = rescale(parsed, digits);
+  const denominator = BigInt(count) * 10n ** BigInt(digits - AVG_SCALE);
+  const negative = numerator < 0n;
+  const magnitude = negative ? -numerator : numerator;
+  // `(2m + d) / 2d` is `floor(m/d + 1/2)` in integers — half AWAY FROM ZERO once the sign is put
+  // back, which is what Postgres' `round(numeric)` does. No float, no intermediate truncation.
+  const rounded = (2n * magnitude + denominator) / (2n * denominator);
+  return render(negative ? -rounded : rounded, AVG_SCALE);
+};
+
+/**
+ * The column an aggregate runs over, resolved and judged before either driver builds anything —
+ * so `sum('title')` is refused with the same words and the same code whichever driver is attached.
+ */
+export const aggregateColumnOf = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+): AnyColumn => {
+  const candidates = Object.entries(entity.$columns)
+    .filter(([, each]) => aggregatable(fn, each.$meta.kind))
+    .map(([name]) => name);
+  const column = columnFor(entity.$columns, property);
+  if (column === undefined) {
+    throw notAggregatable(entity.$name, fn, property, 'text', candidates);
+  }
+  if (!aggregatable(fn, column.$meta.kind)) {
+    throw notAggregatable(entity.$name, fn, property, column.$meta.kind, candidates);
+  }
+  return column;
+};
+
+/** One amount is one currency at one scale. Two of either have no common unit. */
+export interface MoneyUnit {
+  readonly currency: string;
+  readonly scale: number | null;
+}
+
+export const assertOneUnit = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+  units: readonly MoneyUnit[],
+): MoneyUnit | undefined => {
+  const seen = new Map<string, MoneyUnit>();
+  for (const unit of units) seen.set(`${unit.currency}/${unit.scale ?? ''}`, unit);
+  if (seen.size > 1) {
+    throw mixedCurrency(entity.$name, fn, property, [...seen.values()].map(unitLabel));
+  }
+  return [...seen.values()][0];
+};
+
+/**
+ * What the refusal names. The scale rides along because it is half of what makes two amounts
+ * incomparable: `{ minor: 5, currency: 'USD' }` is five cents and `{ minor: 5, currency: 'USD',
+ * scale: 6 }` is five millionths of a dollar, and adding them is a 10,000x error with no symptom.
+ */
+const unitLabel = (unit: MoneyUnit): string =>
+  unit.scale === null ? unit.currency : `${unit.currency}@${unit.scale}`;
+
+/**
+ * The minor unit an aggregate answers with, narrowed exactly where every other reader of that
+ * column narrows it. The column is `bigint` and `MoneyValue.minor` is a `number`, so a total past
+ * ±2^53 is a REFUSAL and never a rounded amount — the same bound `parseMinor` applies to one row,
+ * applied to the sum of many, where it is far easier to reach.
+ */
+export const aggregateMinor = <Row>(
+  entity: EntityCore<Row>,
+  fn: AggregateFn,
+  property: string,
+  total: string,
+): number => {
+  const units = BigInt(total);
+  if (units <= BigInt(Number.MAX_SAFE_INTEGER) && units >= BigInt(-Number.MAX_SAFE_INTEGER)) {
+    return Number(units);
+  }
+  throw new EntityError({
+    code: 'X_AGGREGATE_UNSUPPORTED',
+    cause: `${entity.$name}.${fn}('${property}') is ${total} minor units, past ±2^53 — no JS number holds it and MoneyValue.minor is one`,
+    fix: `${entity.$name}.andWhere(…).${fn}('${property}')   # narrow the rows, or read the total as text with a hand-written statement`,
+  });
+};

package/src/batch.ts

@@ -56,7 +56,8 @@ export const assertBatchable = <Row>(
   if (chain.limit !== undefined) throw limitedBatches(entity.$name, chain.limit, size);
   // The order the driver will sort by, primary key included: the cursor between two batches is
   // minted from it, and an ordering that cannot carry one fails on the batch *after* the first —
-  // where whatever size the caller happened to pass decides whether anyone ever finds out.
+  // where whatever size the caller happened to pass decides whether anyone ever finds out. A
+  // nullable column is NOT such an ordering `As of 2026-08-24`; a nullable primary-key column is.
   assertSeekable(entity, totalOrder(entity, chain.orderBy));
 };
 

package/src/column.ts

@@ -105,7 +105,12 @@ export const bindColumn = (column: AnyColumn, table: string, property: string):
         'build a new column instead of sharing one between entities',
     );
   }
-  const binding: Binding = { table, property, name: columnName(property, column.$meta) };
+  // The DERIVED name too, not only a declared one: `snake(property)` lower-cases and nothing else.
+  const binding: Binding = {
+    table,
+    property,
+    name: assertColumnName(columnName(property, column.$meta)),
+  };
   bindings.set(column, binding);
   return binding;
 };
@@ -203,6 +208,15 @@ export const makeColumn = <T, Optional extends boolean>(
  * identifier. `[a-z_][a-z0-9_$]*`, which is what an unquoted Postgres identifier may be, and the
  * bound is the same 63 bytes the server truncates at — a longer one silently addresses a
  * different column.
+ *
+ * **Every physical name, not only a declared one — `As of 2026-08-24`.** `columnName` is
+ * `meta.name ?? snake(property)` and for three majors only the first branch reached here, so a
+ * PROPERTY name went into the DDL untouched: `snake()` lower-cases and does nothing else, and a
+ * column named `n" , "x" text); drop table t; --` produced a `create table` carrying a real
+ * `drop table` (measured through `generateMigration`). Quoting is not a defence against a value
+ * that can close the quote, which is what the paragraph above already said. `bindColumn` is where
+ * the derived name is checked, because that runs once per column at `entity()` rather than on
+ * every statement.
  */
 export const assertColumnName = (name: string): string => {
   if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {

package/src/containment.ts

@@ -0,0 +1,94 @@
+// Single responsibility: what `@>`, `<@`, `&&` and a JSON key test MEAN, written once so the
+// in-memory driver answers what Postgres answers. A `jsonb` or an `arrayOf()` column was declared
+// and then unfilterable — the ten-operator vocabulary had nothing that could look inside one — so
+// an app with either had to leave the query language for hand-written SQL, which is the one path
+// in this framework with no tenancy guard on it.
+//
+// Every rule here is Postgres', reproduced rather than approximated. Where the two could not be
+// made to agree the operator is refused instead (`memory-match.ts`), never guessed at.
+
+/** Absent and NULL are one thing, exactly as they are to every other predicate. */
+const isNull = (value: unknown): boolean => value === null || value === undefined;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Neither an object nor an array — which is exactly the set the top-level exception below covers. */
+const isScalar = (value: unknown): boolean => !isRecord(value) && !Array.isArray(value);
+
+/**
+ * Two ELEMENTS, equal. `===` plus the one case it gets wrong here: an `arrayOf(timestamp())` row
+ * holds `Date` objects, and two Dates for the same instant are two references — the same trap
+ * `sameValueOfKind` closes for a predicate, one operator along.
+ *
+ * Nothing deeper, and that is a property rather than an omission: `arrayOf()` refuses `jsonb`,
+ * `bytea`, `money` and a nested array at declaration, so an element is always a scalar or a Date.
+ */
+const sameElement = (left: unknown, right: unknown): boolean => {
+  if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  return left === right;
+};
+
+/**
+ * `left @> right` for `jsonb`, to the letter of Postgres' definition — each clause below measured
+ * on Postgres 16 rather than read off a summary, because three of them are easy to state wrongly:
+ *
+ * - two objects: every key of `right` is present in `left` and its value is contained by the one
+ *   there — recursively, which is what makes `data @> '{"a":{"b":1}}'` a NESTED match and why this
+ *   package ships no second path-expression language beside it (axiom 1).
+ * - two arrays: every element of `right` is contained by SOME element of `left`, which is why
+ *   `[1,2,3] @> [3,1]` holds and order never matters.
+ * - an array on the left and a PRIMITIVE on the right, **at the top level only**: `'[1,2]' @> '2'`
+ *   is true. Both halves of that sentence are load-bearing and both were wrong here first —
+ *   `'{"list":[1,2,3]}' @> '{"list":2}'` is FALSE (the exception does not recurse) and
+ *   `'[{"a":1}]' @> '{"a":1}'` is FALSE (it does not extend to composites).
+ * - anything else: element equality, which for a jsonb scalar is what it sounds like.
+ */
+export const jsonContains = (left: unknown, right: unknown): boolean => contains(left, right, true);
+
+const contains = (left: unknown, right: unknown, top: boolean): boolean => {
+  if (Array.isArray(left)) {
+    if (Array.isArray(right)) {
+      return right.every((item) => left.some((candidate) => contains(candidate, item, false)));
+    }
+    return top && isScalar(right) && left.some((candidate) => sameElement(candidate, right));
+  }
+  if (isRecord(left) && isRecord(right)) {
+    return Object.keys(right).every(
+      (key) => Object.hasOwn(left, key) && contains(left[key], right[key], false),
+    );
+  }
+  return isScalar(left) && isScalar(right) && sameElement(left, right);
+};
+
+/**
+ * `left @> right` for a SQL array, which is a different operator with a different rule: element
+ * containment is plain equality, never the recursive one above, because an array's elements are
+ * scalars of one declared type rather than arbitrary JSON. An empty right-hand side is contained
+ * by every array, which is what Postgres answers.
+ */
+export const arrayContains = (left: readonly unknown[], right: readonly unknown[]): boolean =>
+  right.every((item) => left.some((candidate) => sameElement(candidate, item)));
+
+/**
+ * `left && right`: they share at least one element. Arrays only — `jsonb` has no `&&` — and the
+ * bound is the opposite way round from `@>`: an EMPTY operand overlaps nothing, where it is
+ * contained by everything.
+ */
+export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[]): boolean =>
+  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.
+ *
+ * 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.
+ */
+export const jsonHasKey = (value: unknown, key: unknown): boolean => {
+  if (typeof key !== 'string' || isNull(value)) return false;
+  if (Array.isArray(value)) return value.some((item) => item === key);
+  if (isRecord(value)) return Object.hasOwn(value, key);
+  return value === key;
+};

package/src/cursor.ts

@@ -10,6 +10,7 @@ import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
 import { columnFor } from './column';
 import type { EntityCore } from './entity';
 import { invariantViolated } from './errors';
+import { instantMicros } from './instant';
 import type { QueryPlan } from './tenancy';
 import type { AnyColumn, ColumnKind } from './types';
 
@@ -89,8 +90,36 @@ export const valueAt = (row: unknown, path: string): unknown => {
     : undefined;
 };
 
-/** Stringified so the cursor is JSON; `revive` restores the type from the column's kind. */
-const serializeSortValue = (value: unknown): string => {
+/**
+ * Stringified so the cursor is JSON; `revive` restores the type from the column's kind — and the
+ * KIND decides how, never the JS type in hand, because those are two different questions on
+ * exactly the column that made this file wrong.
+ *
+ * A `timestamptz` is carried as MICROSECONDS since the epoch, not as `toISOString()`. The column
+ * holds microseconds and a `Date` holds milliseconds, so an ISO rendition of a decoded row is the
+ * row's own position FLOORED — and a seek built from a floored position ranks rows differently
+ * from the `order by` that produced them, which silently drops every row inside the boundary
+ * millisecond. Proven against a real server: `pg-cursor-precision.live.test.ts`.
+ */
+const ABSENT_MARK = '~';
+const PRESENT_MARK = '!';
+
+/**
+ * A sort value's place in the cursor is TAGGED, so absence can be told from the text that spells
+ * it: `~` alone is NULL, `!` prefixes a present value. Positional, therefore total — a `text`
+ * column holding the four characters `null` encodes as `!null` and can never be read as an absent
+ * one, which is the collision a bare sentinel value would reopen.
+ *
+ * The tag exists because a nullable sort key is legal `As of 2026-08-24` (`asc nulls last` /
+ * `desc nulls first`, `@ultimat3/query`'s spelling), and a keyset position over one has to be able
+ * to say "the boundary row had none".
+ */
+const tagged = (text: string): string => `${PRESENT_MARK}${text}`;
+
+const serializeSortValue = (kind: ColumnKind, value: unknown): string | undefined => {
+  // `undefined`, never `'0'`: a position nothing could read would decode to the epoch, which is
+  // "start from the top" wearing a signature — the one thing a cursor must never mean.
+  if (kind === 'timestamptz') return instantMicros(value)?.toString();
   if (value instanceof Date) return value.toISOString();
   if (typeof value === 'bigint') return value.toString();
   return String(value);
@@ -108,8 +137,16 @@ const serializeSortValue = (value: unknown): string => {
 // constant three lines above it.
 const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
   switch (kind) {
-    case 'timestamptz':
-      return new Date(text);
+    case 'timestamptz': {
+      // Microseconds since the epoch — the precision the COLUMN keeps, which a `Date` cannot.
+      // A cursor minted before that decision carries an ISO string, so this is where it is
+      // refused: `BigInt('2026-…')` is a bare `SyntaxError` with no code and no fix.
+      const micros = instantMicros(text);
+      if (micros === undefined) {
+        throw new CursorInvalidError('its position is not a microsecond instant');
+      }
+      return micros;
+    }
     case 'bigint':
       return BigInt(text);
     case 'integer':
@@ -125,9 +162,12 @@ const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
  * 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.
  *
- * Checked when a cursor is minted as well as when one is decoded: an ordering that cannot carry
- * a position is the author's mistake, and reporting it on the *second* page hides it behind
- * whatever page size the caller happened to use.
+ * Checked where the PLAN is built (`planFor`), which is every read either driver sends, as well as
+ * when a cursor is minted and when one is decoded. The plan is the load-bearing one: `cursorFor`
+ * runs only when a page found a row past its limit, so the refusal used to depend on how many rows
+ * the table happened to hold — green on fifteen seeded rows, `X_INVARIANT_VIOLATED` on the first
+ * read past a page of twenty in production. An ordering that cannot carry a position is the
+ * author's mistake at any row count.
  */
 export const assertSeekable = <Row>(
   entity: EntityCore<Row>,
@@ -138,15 +178,28 @@ export const assertSeekable = <Row>(
     // money property named without its part — both mint a cursor nothing can decode.
     kindAt(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
+    // it. What is left is the TIEBREAK — `totalOrder` appends the primary key precisely so two
+    // rows sharing a sort value cannot straddle a page boundary, and a nullable primary-key column
+    // cannot do that job: `null = null` is unknown, so two such rows are indistinguishable to the
+    // seek and one of them is served twice or never. Reachable only through `primaryKey: [...]`,
+    // which takes the columns as declared.
+    if (!entity.$primaryKey.includes(key.column)) continue;
     throw invariantViolated(
       entity.$name,
       'cursor',
-      `${key.column} is nullable and cannot carry a cursor — order by a not-null column ` +
-        `(add .orderBy('${entity.$primaryKey[0] ?? 'id'}') or make ${key.column} not null)`,
+      `${key.column} is part of the primary key and is nullable, so no ordering can be total — ` +
+        'an ordinary nullable column orders fine (nulls last ascending, nulls first descending), ' +
+        `but the tiebreak cannot: drop .nullable() from ${key.column}`,
     );
   }
 };
 
+/** Whether a sort key may hold NULL — what decides the seek's SHAPE, not only its values. */
+export const isNullableKey = <Row>(entity: EntityCore<Row>, path: string): boolean =>
+  !columnAt(entity, path).$meta.notNull;
+
 /** Deterministic, and total over the value shapes a predicate can hold. */
 const renderValue = (value: unknown): string => {
   if (value === null || value === undefined) return 'null';
@@ -182,17 +235,37 @@ export const planScope = (plan: QueryPlan): string => {
     .slice(0, 16);
 };
 
-/** The cursor that continues this plan after `row`. Signed by core, scoped by the plan. */
+/**
+ * The cursor that continues this plan after `row`. Signed by core, scoped by the plan.
+ *
+ * `exact` is how a driver hands over a value the DECODED row cannot hold: a `timestamptz` comes
+ * back as a `Date`, which is milliseconds, and the microseconds it dropped are the difference
+ * between a position the `order by` agrees with and one it does not. Optional because the
+ * in-memory driver stores millisecond `Date`s and therefore has nothing finer to give.
+ */
 export const cursorFor = <Row>(
   entity: EntityCore<Row>,
   plan: QueryPlan,
   row: unknown,
   id: string,
+  exact?: ReadonlyMap<string, unknown>,
 ): string => {
   assertSeekable(entity, plan.orderBy);
   return encodeCursor({
     scope: planScope(plan),
-    key: plan.orderBy.map((entry) => serializeSortValue(valueAt(row, entry.column))),
+    key: plan.orderBy.map((entry) => {
+      const value = exact?.get(entry.column) ?? valueAt(row, entry.column);
+      // A column the row never named and a stored NULL are one absence everywhere else in this
+      // package (`isNull`), and they are one position here too.
+      if (value === null || value === undefined) return ABSENT_MARK;
+      const text = serializeSortValue(kindAt(entity, entry.column), value);
+      if (text !== undefined) return tagged(text);
+      throw invariantViolated(
+        entity.$name,
+        'cursor',
+        `${entry.column} on the last row of the page holds no instant a cursor can carry`,
+      );
+    }),
     id,
   });
 };
@@ -216,7 +289,20 @@ export const seekFrom = <Row>(
       `it carries ${key.length} sort values, this order needs ${plan.orderBy.length}`,
     );
   }
-  return plan.orderBy.map((entry, index) =>
-    reviveSortValue(kindAt(entity, entry.column), String(key[index])),
-  );
+  return plan.orderBy.map((entry, index) => {
+    // `segment` and `ABSENT_MARK`, never `token` and `NULL_KEY`: both names said CREDENTIAL to
+    // `bun run secret-compare`, whose rule is that a `===` on one leaks it a byte at a time. What
+    // this compares is a page POSITION against a one-character tag, where the repair the guard
+    // names — `timingSafeEqual` — would be constant-time nonsense. The guard reads names because a
+    // unit test cannot assert timing, so the name is the thing that has to be right.
+    const segment = String(key[index]);
+    if (segment === ABSENT_MARK) return null;
+    if (!segment.startsWith(PRESENT_MARK)) {
+      // Every cursor this package mints carries a tag. An untagged one was forged past the
+      // signature or minted before nullable sort keys existed; either way the alternative is a
+      // silent restart at the top, which is the one thing a cursor may never mean.
+      throw new CursorInvalidError('a sort value carries no null-or-value tag');
+    }
+    return reviveSortValue(kindAt(entity, entry.column), segment.slice(PRESENT_MARK.length));
+  });
 };

package/src/database.ts

@@ -2,11 +2,11 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
+import { memoryRepo } from './memory-repo';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
 import type { Repo } from './repo';
-import { memoryRepo } from './repo';
 import { observedRepo } from './row-observer';
 
 export type EntitySet = Readonly<Record<string, EntityCore>>;

package/src/describe.ts

@@ -188,6 +188,9 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
       unique: index.unique,
       where: index.where ?? null,
       order: index.order ?? null,
+      // Spread, never `?? null`: absent is what `@ultimat3/db` reads as the btree it always was,
+      // and a written-out `null` would be a field no existing snapshot carries.
+      ...(index.using === undefined ? {} : { using: index.using }),
     })),
     tags: input.tags,
     cacheTag: input.cacheTag,