@ultimat3/query 1.2.0 → 3.0.0

package/src/read.ts

@@ -8,7 +8,9 @@
 import type { Ctx } from '@ultimat3/core';
 import {
   anonymousActor,
+  assert,
   createContext,
+  logger,
   runWithContext,
   tryUseContext,
   useContext,
@@ -17,7 +19,14 @@ import {
 } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { formatPath, validateAsync } from '@ultimat3/schema';
-import { cacheKeyFor, readThrough } from './cache';
+import {
+  cacheKeyFor,
+  DEFAULT_READ_CACHE_TTL_MS,
+  readAuthority,
+  readFresh,
+  readOnce,
+  readThrough,
+} from './cache';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
 import { actorOf, guard } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
@@ -57,8 +66,23 @@ export function queryName(target: AnyQuery): string {
 export function runQuery<TInput extends StandardSchemaV1, TRow extends object>(
   target: Query<TInput, TRow>,
   raw: unknown,
+  options?: QueryOptions,
+): Promise<readonly TRow[]>;
+/**
+ * The same read from a schema-erased handle. The route projection maps `listQueries()`,
+ * which knows only `AnyQuery` — an overload rather than a second function, so what is
+ * gone is the row TYPE and never the parse, the policy or the memo.
+ */
+export function runQuery(
+  target: AnyQuery,
+  raw: unknown,
+  options?: QueryOptions,
+): Promise<readonly object[]>;
+export function runQuery(
+  target: AnyQuery,
+  raw: unknown,
   options: QueryOptions = {},
-): Promise<readonly TRow[]> {
+): Promise<readonly object[]> {
   return asActor(options, (ctx) => readRows(target, raw, ctx, options));
 }
 
@@ -81,7 +105,14 @@ export function sourceFor(
  * core models it as the anonymous actor. Omitting `actor` touches no context at all.
  */
 function asActor<T>(options: QueryOptions, run: (ctx: Ctx) => Promise<T>): Promise<T> {
-  if (options.actor === undefined) return run(options.ctx ?? useContext());
+  if (options.actor === undefined) {
+    // INSTALLED, never only handed over — the same fix `@ultimat3/action`'s `invoke` carries, for
+    // the same reason: `@ultimat3/entity`'s tenant guard derives from `tryUseContext()`, so a read
+    // built under an explicit `ctx` evaluated its policy against that actor and its row tenancy
+    // against nobody. Absent a `ctx` this reinstalls the ambient one, which changes nothing.
+    const ctx = options.ctx ?? useContext();
+    return runWithContext(ctx, () => run(ctx));
+  }
   const patch = { actor: options.actor ?? anonymousActor() };
   const inChild = (): Promise<T> => run(useContext());
   const base = options.ctx ?? tryUseContext();
@@ -90,23 +121,72 @@ function asActor<T>(options: QueryOptions, run: (ctx: Ctx) => Promise<T>): Promi
     : runWithContext(base, () => withChildContext(patch, inChild));
 }
 
-async function readRows<TInput extends StandardSchemaV1, TRow extends object>(
-  target: Query<TInput, TRow>,
+/**
+ * The span covers the WHOLE read, not just `execute()`. Wrapping the execution alone left the
+ * input parse, the policy evaluation and `sql()`'s own construction outside every span, so a read
+ * whose cost was in building the source reported milliseconds while its parent HTTP span reported
+ * seconds — a gap with no name, which reads as framework overhead and gets hand-instrumented.
+ *
+ * Attributes are bounded: surface, actor KIND, booleans, and a row count. Never the input, never
+ * an actor id — a read is keyed per tenant and per cursor, and either would be unbounded.
+ */
+function readRows(
+  target: AnyQuery,
+  raw: unknown,
+  ctx: Ctx,
+  options: QueryOptions,
+): Promise<readonly object[]> {
+  const name = queryName(target);
+  return withSpan(`query.${name}`, async (span) => {
+    span.setAttributes({
+      'ultimate.primitive': 'query',
+      'ultimate.query': name,
+      'ultimate.surface': options.surface ?? 'server',
+      'ultimate.actor.kind': ctx.actor.kind,
+      'ultimate.live': target.isLive,
+      'ultimate.fresh': options.fresh === true,
+      // Whether this read goes through the tier at all. Every read is memoized; only a `cache:`
+      // read is filled — and which of the two a slow read took is the first thing to ask.
+      'ultimate.cached': defOf(target).cache !== undefined,
+    });
+    const rows = await readRowsIn(target, raw, ctx, options);
+    span.setAttribute('ultimate.rows', rows.length);
+    return rows;
+  });
+}
+
+async function readRowsIn(
+  target: AnyQuery,
   raw: unknown,
   ctx: Ctx,
   options: QueryOptions,
-): Promise<readonly TRow[]> {
+): Promise<readonly object[]> {
   const def = defOf(target);
   const name = queryName(target);
   const source = await buildSource(target, raw, ctx, options);
-  const read = (): Promise<readonly object[]> => withSpan(`query.${name}`, () => source.execute());
-  // The source came from this query's own `sql()`, so its rows are TRow.
-  if (options.fresh === true || def.cache === undefined) {
-    return (await read()) as readonly TRow[];
-  }
-  const key = cacheKeyFor(name, raw, def.cache.tags);
-  const rows = await readThrough(ctx, key, def.cache.ttlMs ?? null, read);
-  return rows as readonly TRow[];
+  const read = (): Promise<readonly object[]> => source.execute();
+  // The source came from this query's own `sql()`, so its rows are TRow throughout —
+  // which is what the typed overload above states, and this body never has to assert.
+  const tags = def.cache?.tags ?? [];
+  // The authority is part of the key on EVERY read, cached or not, because there is one key
+  // function and a second one beside it is what this package's own rule forbids. It costs the memo
+  // nothing — a memo is already per-ctx — and it is the whole of what the tier was missing: keyed
+  // on the name, the input and the tags alone, the process-wide tier handed one org's rows to the
+  // next org that asked for them. `actor` when the declaration named no scope, always.
+  const key = cacheKeyFor(name, raw, tags, readAuthority(ctx.actor, def.cache?.scope ?? 'actor'));
+  // `fresh` is the caller saying no cache may answer this one — the memo included, a memo being
+  // a cache whose lifetime is the request. It still *publishes* into the memo: this read is the
+  // newest answer the request has, so the next plain read of the key joins it rather than the
+  // entry a write earlier in the request already moved past.
+  if (options.fresh === true) return await readFresh(ctx, key, read);
+  // `cache:` buys the tier, never the memo: a read asked twice in one request is one execution
+  // whether or not its author opted into caching.
+  // A declared `cache:` with no `ttlMs` gets one anyway. Tags are the primary eviction, but a
+  // read whose tags never fire would otherwise hold one entry per distinct input for the life of
+  // the process — a paginated feed over 10k tenants is 10k immortal entries.
+  return def.cache === undefined
+    ? await readOnce(ctx, key, read)
+    : await readThrough(ctx, key, def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS, read, tags);
 }
 
 async function buildSource(
@@ -118,14 +198,34 @@ async function buildSource(
   const def = defOf(target);
   const name = queryName(target);
   const input = await validate(def.input, raw, name);
-  if (options.enforce !== false) {
+  const unenforced = options.unenforced;
+  if (unenforced === undefined) {
     guard(
       def.policy,
       { actor: actorOf(ctx), input, ctx, query: name },
       options.surface ?? 'server',
     );
+  } else {
+    // The reason IS the mechanism, exactly as it is for `crossTenant`: a blank one leaves the
+    // escape with no argument, and the next reader cannot tell a considered skip from a forgotten
+    // policy. Refused before the source is built, so nothing is read on a blank justification.
+    assert(
+      unenforced.trim() !== '',
+      `query "${name}" was built with a blank unenforced reason, so the policy it skips carries no argument`,
+      `pass why this read needs no subject: sourceFor(target, input, { unenforced: 'explain returns no rows' })`,
+    );
+    // The audit half. `debug`, because the two shipped callers are dev tooling and a sync node's
+    // once-per-query-id window — never a per-request path — and core's logger costs one level
+    // comparison when nothing is listening.
+    logger.debug('query.policy.unenforced', { query: name, reason: unenforced });
   }
-  return def.sql(input, ctx);
+  const source = def.sql(input, ctx);
+  // A live window is served in the order its patches are placed in. The matcher breaks a tie on
+  // the declared keys with `id` (`totalOrder`) and so does the keyset re-read a reconnect resumes
+  // with, so an initial window served in the declared keys alone puts tied rows where neither of
+  // them would: the client renders one order and the next read answers another. A source that
+  // cannot say (`total` absent) already serves one order it can be resumed in.
+  return options.surface === 'live' && source.total !== undefined ? source.total() : source;
 }
 
 async function validate(schema: StandardSchemaV1, raw: unknown, name: string): Promise<unknown> {

package/src/shape.ts

@@ -57,6 +57,32 @@ export function seekKeyOf(
   };
 }
 
+/** Appended by `totalOrder`. Ascending whatever the declared keys do — so is the seek predicate. */
+const ID_TIEBREAK: OrderKey = { column: 'id', direction: 'asc' };
+
+/**
+ * The ordering a read is actually served in: the declared keys, then `id` to make it total.
+ *
+ * Two rows sharing every declared sort value have no order at all without it — the database
+ * returns them either way round while `isAfterKey` decides the next page as though `id` had
+ * settled it. `Builder.seek()` compiles this list, `paginate()` sorts by it, and the matcher
+ * places a row by it: a row inserted at the end of a tie group is a row the next re-read finds
+ * somewhere else. An ordering that already names `id` is total, and adding a second `id` term
+ * would compare the key to itself.
+ */
+export function totalOrder(orderBy: readonly OrderKey[]): readonly OrderKey[] {
+  return orderBy.some((key) => key.column === 'id') ? orderBy : [...orderBy, ID_TIEBREAK];
+}
+
+/**
+ * SQL NULL, as a row spells it. A column the row simply omits reads `undefined` here and NULL
+ * in Postgres, so both are the same absence — otherwise a fixture row without `deletedAt` and
+ * the same row round-tripped through a driver answer `where({ deletedAt: null })` differently.
+ */
+export function isNull(value: unknown): boolean {
+  return value === null || value === undefined;
+}
+
 export function matchesFilters(row: object, filters: readonly Filter[]): boolean {
   return filters.every((filter) => matchesFilter(row, filter));
 }
@@ -71,33 +97,104 @@ export function matchesFilter(row: object, filter: Filter): boolean {
     case 'in':
       return Array.isArray(filter.value) && filter.value.some((item) => same(actual, item));
     case '>':
-      return compareValues(actual, filter.value) > 0;
     case '>=':
-      return compareValues(actual, filter.value) >= 0;
     case '<':
-      return compareValues(actual, filter.value) < 0;
     case '<=':
-      return compareValues(actual, filter.value) <= 0;
+      return ordered(filter.op, actual, filter.value);
     default:
       return false;
   }
 }
 
-/** Dates compare by instant, everything else by value. No coercion across types. */
+/**
+ * `col > NULL` is unknown in SQL and unknown is not a match, so a NULL on either side of an
+ * ordering operator matches nothing here either. Only `=`, `!=` and `in` read NULL as a value —
+ * and those are exactly the three `Builder.toSQL()` compiles to `is null` / `is distinct from`.
+ */
+function ordered(op: '>' | '>=' | '<' | '<=', actual: unknown, value: unknown): boolean {
+  if (isNull(actual) || isNull(value)) return false;
+  const result = compareValues(actual, value);
+  switch (op) {
+    case '>':
+      return result > 0;
+    case '>=':
+      return result >= 0;
+    case '<':
+      return result < 0;
+    case '<=':
+      return result <= 0;
+  }
+}
+
+/**
+ * Dates compare by instant, everything else by value. No coercion across types.
+ *
+ * NULL is greater than every value and equal to itself — Postgres' own sort rule, which is what
+ * lets `Builder.toSQL()` write it down as `asc nulls last` / `desc nulls first` and mean this
+ * function. Sorting only: a comparison *filter* against NULL matches nothing (`ordered`). Before
+ * this, `null` sorted as the string `"null"`, so it landed between `"m"` and `"o"` in memory and
+ * at the end in the database — the same page read two ways.
+ */
 export function compareValues(a: unknown, b: unknown): number {
+  if (isNull(a) || isNull(b)) return isNull(a) ? (isNull(b) ? 0 : 1) : -1;
   const left = normalize(a);
   const right = normalize(b);
-  if (typeof left === 'number' && typeof right === 'number') return left - right;
+  if (isNumeric(left) && isNumeric(right)) return compareNumeric(left, right);
   const l = String(left);
   const r = String(right);
   return l < r ? -1 : l > r ? 1 : 0;
 }
 
+function isNumeric(value: unknown): value is number | bigint {
+  return typeof value === 'number' || typeof value === 'bigint';
+}
+
+/**
+ * Numbers and bigints, in one order, because **Postgres orders them in one order**.
+ *
+ * `bigint` is a first-class `ColumnKind` — the physical type of every `<p>_minor` column — and
+ * `@ultimat3/entity`'s `count-by.ts` lists it as groupable, so these values do reach the
+ * comparator. The old numeric fast path was `typeof left === 'number' && typeof right ===
+ * 'number'` alone, so a bigint fell through to `String(left) < String(right)`:
+ * `compareValues(9n, 10n)` answered `1` and a sort came out `["10", "100", "9"]`, which means the
+ * in-memory source, the live matcher and the seek fallback all disagreed with the database on any
+ * bigint-ordered read — including page two of one.
+ *
+ * A bigint pair never subtracts: the difference is exact but the return type is a `number`. A
+ * mixed pair goes through `BigInt` when the number is whole, so a value past 2^53 keeps its exact
+ * place; a fractional number cannot equal a bigint, so comparing it as a float is enough to place
+ * it. `Number.isInteger` is false for `NaN` and `±Infinity`, which is what keeps them out of the
+ * `BigInt()` call that would throw on them.
+ */
+function compareNumeric(left: number | bigint, right: number | bigint): number {
+  if (typeof left === 'number' && typeof right === 'number') return left - right;
+  if (typeof left === 'bigint' && typeof right === 'bigint') return sign(left, right);
+  // Widened rather than negated: `-sign(a, b)` answers `-0` for a tie, and `-0` is a different
+  // value from `0` to `Object.is` and to a caller writing `=== 0`.
+  return typeof left === 'bigint'
+    ? mixed(left, right as number)
+    : -mixed(right as bigint, left) || 0;
+}
+
+/** A bigint against a number, in that order. Whole numbers go through `BigInt` so a value past
+ * 2^53 keeps its exact place; a fractional number can never equal a bigint, so comparing it as a
+ * float is enough to place it. `Number.isInteger` is false for `NaN` and `±Infinity`, which is
+ * what keeps them out of the `BigInt()` call that would throw on them. */
+function mixed(big: bigint, other: number): number {
+  return Number.isInteger(other) ? sign(big, BigInt(other)) : sign(Number(big), other);
+}
+
+function sign<T extends number | bigint>(left: T, right: T): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** A `Date` compares by instant, so two of them order by time and never by their ISO text. */
 function normalize(value: unknown): unknown {
   return value instanceof Date ? value.getTime() : value;
 }
 
 function same(a: unknown, b: unknown): boolean {
+  if (isNull(a) || isNull(b)) return isNull(a) && isNull(b);
   return compareValues(a, b) === 0 && typeof normalize(a) === typeof normalize(b);
 }
 

package/src/source.ts

@@ -5,9 +5,15 @@
  * answer these four questions.
  */
 import type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-import { compareRows, compareValues, matchesFilters } from './shape';
+import { compareRows, compareValues, isNull, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
+/** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */
+const NEVER = '1 = 0';
+
+/** Binds a value and answers the `$n` that reads it. Nothing here interpolates a value. */
+type Slot = (value: unknown) => string;
+
 export interface SqlText {
   readonly sql: string;
   readonly params: readonly unknown[];
@@ -19,6 +25,12 @@ export interface SqlSource<TRow> {
   execute(): Promise<readonly TRow[]>;
   /** Required for `live: true`: the matcher patches from the shape, not from SQL. */
   shape(): QueryShape;
+  /**
+   * The same read served in `totalOrder` — the declared keys, then `id`. A live read is built
+   * through this, because the matcher places a patched row by that order and a reconnect resumes
+   * by it. Absent means the source already serves one order it can be resumed in.
+   */
+  total?(): SqlSource<TRow>;
   /** Cursor push-down. Absent means pagination slices after execution. */
   seek?(after: SeekKey | null, limit: number): SqlSource<TRow>;
 }
@@ -42,10 +54,16 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
     private readonly rowLimit: number | null,
     private readonly after: SeekKey | null,
     private readonly unsupported: readonly string[],
-    /** Set by `seek()`. Only a paged read pays for the id tiebreak — see `pageOrder()`. */
-    private readonly paged: boolean = false,
+    /** Set by `seek()` and `total()` — the only reads that pay for the id tiebreak. */
+    private readonly totalized: boolean = false,
   ) {}
 
+  /**
+   * One equality filter per key, and the clauses come out in **lexical key order** — not the order
+   * the object literal was typed in. The generated text is something callers compare across runs:
+   * `explain()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
+   * a call site must not rewrite the statement.
+   */
   where(equals: Readonly<Record<string, unknown>>): Builder<TRow> {
     const added = Object.keys(equals)
       .sort()
@@ -71,7 +89,15 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   }
 
   seek(after: SeekKey | null, limit: number): Builder<TRow> {
-    return this.derive({ after, rowLimit: limit, paged: true });
+    return this.derive({ after, rowLimit: limit, totalized: true });
+  }
+
+  /**
+   * The declared keys plus the `id` tiebreak, with no cursor and no window — page one of the
+   * ordering a paged read already serves. `seek()` implies it; a live read asks for it directly.
+   */
+  total(): Builder<TRow> {
+    return this.derive({ totalized: true });
   }
 
   shape(): QueryShape {
@@ -86,24 +112,12 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
 
   toSQL(): SqlText {
     const params: unknown[] = [];
-    const clauses = this.filters.map((filter) => {
-      if (filter.op === 'in' && Array.isArray(filter.value)) {
-        const slots = filter.value.map((item) => {
-          params.push(item);
-          return `$${params.length}`;
-        });
-        return `"${filter.column}" in (${slots.join(', ')})`;
-      }
-      params.push(filter.value);
-      return `"${filter.column}" ${filter.op} $${params.length}`;
-    });
-    if (this.after !== null) clauses.push(this.seekClause(this.after, params));
+    const slot = slotter(params);
+    const clauses = this.filters.map((filter) => filterClause(filter, slot));
+    if (this.after !== null) clauses.push(this.seekClause(this.after, slot));
     const where = clauses.length > 0 ? ` where ${clauses.join(' and ')}` : '';
-    const keys = this.pageOrder();
-    const order =
-      keys.length > 0
-        ? ` order by ${keys.map((key) => `"${key.column}" ${key.direction}`).join(', ')}`
-        : '';
+    const keys = this.servedOrder();
+    const order = keys.length > 0 ? ` order by ${keys.map(orderTerm).join(', ')}` : '';
     const limit = this.rowLimit === null ? '' : ` limit ${this.rowLimit}`;
     return { sql: `select * from "${this.entity}"${where}${order}${limit}`, params };
   }
@@ -111,7 +125,7 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   async execute(): Promise<readonly TRow[]> {
     const source = typeof this.rows === 'function' ? await this.rows() : this.rows;
     let result = source.filter((row) => matchesFilters(row, this.filters));
-    const keys = this.pageOrder();
+    const keys = this.servedOrder();
     if (keys.length > 0) {
       result = [...result].sort((a, b) => compareRows(a, b, keys));
     }
@@ -128,20 +142,14 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   }
 
   /**
-   * The ordering a page is actually served in: the declared keys, then `id` to make it total.
+   * The ordering this read is actually served in — `totalOrder`, so the SQL, the in-memory sort,
+   * `seekClause()` and the matcher all read one list.
    *
-   * Without the tiebreak the database is free to return two rows with the same sort value in
-   * either order, while `seekClause()` decides the next page as if they had been ordered by id —
-   * so one of the pair comes back twice and the other never does. `execute()` had the same split,
-   * sorting by the declared keys and then filtering with the id-aware predicate. One order, read
-   * by the SQL, the in-memory sort and the predicate alike, is what closes it.
-   *
-   * Only a paged read pays for it: an unpaginated `from()` over rows that have no `id` must keep
-   * generating exactly the SQL it was asked for.
+   * Only a read that asked for it pays: `seek()` for a page, `total()` for a live window. A plain
+   * `from()` over rows that have no `id` must keep generating exactly the SQL it was asked for.
    */
-  private pageOrder(): readonly OrderKey[] {
-    if (!this.paged || this.ordersById) return this.order;
-    return [...this.order, { column: 'id', direction: 'asc' }];
+  private servedOrder(): readonly OrderKey[] {
+    return this.totalized ? totalOrder(this.order) : this.order;
   }
 
   /**
@@ -152,25 +160,28 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
    * a mixed listing repeated and skipped rows while `execute()` did the right
    * thing. Same shape as `@ultimat3/entity`'s `seekSql`: one meaning, two drivers.
    */
-  private seekClause(after: SeekKey, params: unknown[]): string {
-    const slot = (value: unknown): string => {
-      params.push(value);
-      return `$${params.length}`;
-    };
-    // The same `pageOrder()` the ORDER BY is built from, so the predicate can only ever describe
+  private seekClause(after: SeekKey, slot: Slot): string {
+    // The same `servedOrder()` the ORDER BY is built from, so the predicate can only ever describe
     // the order the rows actually arrive in. The tiebreak is absent when the ordering already
     // named `id`: a second `id` term compares the key to itself, can never be true, and is dead
     // SQL an agent then has to reason about.
-    const keys = this.pageOrder();
+    const keys = this.servedOrder();
     const values = this.ordersById ? [...after.key] : [...after.key, after.id];
-    const terms = keys.map((key, index) => {
+    const terms: string[] = [];
+    for (const [index, key] of keys.entries()) {
+      const value = values[index];
+      // Under `nulls last` nothing sorts after a NULL, so this key's term is dead SQL — dropped
+      // rather than emitted, exactly as the doubled id tiebreak is. The remaining keys still
+      // carry the page: the equality prefix below reaches them as `"col" is null`.
+      if (isNull(value) && key.direction === 'asc') continue;
       const equal = keys
         .slice(0, index)
-        .map((earlier, position) => `"${earlier.column}" = ${slot(values[position])}`);
-      const compare = `"${key.column}" ${key.direction === 'desc' ? '<' : '>'} ${slot(values[index])}`;
-      return `(${[...equal, compare].join(' and ')})`;
-    });
-    return `(${terms.join(' or ')})`;
+        .map((earlier, position) => equalTerm(earlier.column, values[position], slot));
+      terms.push(`(${[...equal, afterTerm(key, value, slot)].join(' and ')})`);
+    }
+    // Every key null under an ascending order is the very end of the listing. Only reachable
+    // from a hand-built cursor — `seekKeyOf` refuses a row with no id — but `()` is a syntax error.
+    return terms.length === 0 ? NEVER : `(${terms.join(' or ')})`;
   }
 
   private derive(patch: Partial<BuilderState>): Builder<TRow> {
@@ -182,18 +193,95 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
       patch.rowLimit === undefined ? this.rowLimit : patch.rowLimit,
       patch.after === undefined ? this.after : patch.after,
       patch.unsupported ?? this.unsupported,
-      patch.paged ?? this.paged,
+      patch.totalized ?? this.totalized,
     );
   }
 }
 
+const slotter =
+  (params: unknown[]): Slot =>
+  (value) => {
+    params.push(value);
+    return `$${params.length}`;
+  };
+
+/**
+ * One filter, in SQL that means what `matchesFilter` means.
+ *
+ * `= $n` with a NULL parameter is unknown in Postgres and unknown is never true, so
+ * `where({ deletedAt: null })` matched every live row in memory and no row at all in the
+ * database. `is null` / `is distinct from` is the pair `@ultimat3/entity`'s `predicateSql`
+ * already emits — one meaning, two sources. An ordering operator needs no case: `"col" > $n`
+ * against a NULL matches nothing, which is what `ordered()` now answers too.
+ */
+function filterClause(filter: Filter, slot: Slot): string {
+  const column = `"${filter.column}"`;
+  if (filter.op === 'in') {
+    // `in` reads a list or nothing. A non-array operand matches no row in memory, so the SQL says
+    // the same constant — the fallback below would emit `"col" in $n`, which is a syntax error a
+    // driver reports instead of the empty result the two sources agree on.
+    if (!Array.isArray(filter.value)) return NEVER;
+    const present = filter.value.filter((item) => !isNull(item));
+    const list =
+      present.length === 0
+        ? null
+        : `${column} in (${present.map((item) => slot(item)).join(', ')})`;
+    const nulls = present.length === filter.value.length ? null : `${column} is null`;
+    if (list === null) return nulls ?? NEVER;
+    return nulls === null ? list : `(${list} or ${nulls})`;
+  }
+  if (filter.op === '=') return equalTerm(filter.column, filter.value, slot);
+  if (filter.op === '!=') {
+    return isNull(filter.value)
+      ? `${column} is not null`
+      : `${column} is distinct from ${slot(filter.value)}`;
+  }
+  return `${column} ${filter.op} ${slot(filter.value)}`;
+}
+
+/**
+ * NULL's place in the ordering, written down rather than inherited. Postgres already defaults
+ * to `nulls last` under `asc` and `nulls first` under `desc` — that is the rule `compareValues`
+ * implements, so the in-memory sort, the live matcher and `seekClause` below can only agree
+ * with it. Saying it out loud is what keeps a driver whose default differs from re-opening the
+ * divergence, and it is what an agent reads when a nullable sort key surprises it.
+ */
+function orderTerm(key: OrderKey): string {
+  const nulls = key.direction === 'desc' ? 'nulls first' : 'nulls last';
+  return `"${key.column}" ${key.direction} ${nulls}`;
+}
+
+/** `= $n` never matches a NULL — the same defect as a filter, one page later. */
+function equalTerm(column: string, value: unknown, slot: Slot): string {
+  return isNull(value) ? `"${column}" is null` : `"${column}" = ${slot(value)}`;
+}
+
+/**
+ * Strictly past this key's value, under the ordering `orderTerm` writes.
+ *
+ * `desc` is `nulls first`: every non-null row follows a NULL cursor, and no NULL row follows a
+ * value — which `"col" < $n` already excludes. `asc` is `nulls last`: the NULLs follow every
+ * value, so a value cursor has to reach them explicitly or page two ends at the first NULL.
+ */
+function afterTerm(key: OrderKey, value: unknown, slot: Slot): string {
+  const column = `"${key.column}"`;
+  if (key.direction === 'desc') {
+    return isNull(value) ? `${column} is not null` : `${column} < ${slot(value)}`;
+  }
+  const after = `${column} > ${slot(value)}`;
+  // `id` is the tiebreak that makes the order total and `seekKeyOf` refuses a row without one,
+  // so `"id" is null` is unsatisfiable: reaching for it would be dead SQL on every paged read,
+  // and an `or` the planner has to defeat before it can seek the index.
+  return key.column === 'id' ? after : `(${after} or ${column} is null)`;
+}
+
 interface BuilderState {
   readonly filters: readonly Filter[];
   readonly order: readonly OrderKey[];
   readonly rowLimit: number | null;
   readonly after: SeekKey | null;
   readonly unsupported: readonly string[];
-  readonly paged: boolean;
+  readonly totalized: boolean;
 }
 
 /**

package/src/sql.ts

@@ -27,7 +27,7 @@ export async function explain<TInput extends StandardSchemaV1, TRow extends obje
   ctx?: Ctx,
 ): Promise<ExplainResult> {
   const source = await sourceFor(target, input, {
-    enforce: false,
+    unenforced: 'explain returns the statement and never a row, and its surfaces are admin-gated',
     ...(ctx === undefined ? {} : { ctx }),
   });
   const text = source.toSQL();
@@ -65,7 +65,7 @@ export async function describeSql(
       continue;
     }
     const source = await sourceFor(target, sample, {
-      enforce: false,
+      unenforced: 'the dashboard listing renders SQL text for a sample input and reads no rows',
       ...(ctx === undefined ? {} : { ctx }),
     });
     entries.push({ query: name, live: target.isLive, sql: source.toSQL().sql });