@ultimat3/query 1.2.0 → 2.0.0

package/src/naming.ts

@@ -1,8 +1,9 @@
 /**
- * The one naming rule for reads: a query's export name derives its HTTP path and
- * its MCP tool name. Pure string math, so the browser client derives the same URL
- * without importing a byte of server code. Ported rather than imported from
- * @ultimat3/action: that package is the same tier, and tiers never go sideways.
+ * The one naming rule for reads: a query's export name derives its HTTP path.
+ * Pure string math, so the browser client derives the same URL without importing
+ * a byte of server code. Ported rather than imported from @ultimat3/action: that
+ * package is the same tier, and tiers never go sideways. The MCP tool name is NOT
+ * derived — it is the export name verbatim, so there is one name to call.
  */
 
 /** Every read is served under one prefix, so a router can claim it in one rule. */
@@ -31,8 +32,3 @@ export function toKebabCase(name: string): string {
 export function derivePath(name: string): string {
   return `${QUERY_PREFIX}/${toKebabCase(name)}`;
 }
-
-/** MCP tool names are `snake_case`: `liveFeed` -> `live_feed`. */
-export function toToolName(name: string): string {
-  return splitWords(name).join('_');
-}

package/src/pagination.ts

@@ -9,8 +9,9 @@
  * The codec is `@ultimat3/core`'s. This file only decides what a cursor is bound
  * to — `queryHash(name, input)` — so one read's cursor cannot page another.
  */
-import { decodeCursor, encodeCursor } from '@ultimat3/core';
+import { assert, decodeCursor, encodeCursor } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { reviveSortKey, serializeSortValue } from './cursor-value';
 import type { Query, SourceOptions } from './query';
 import { queryHash, queryName, sourceFor } from './query';
 import type { QueryShape, SeekKey } from './shape';
@@ -29,6 +30,15 @@ export interface PaginateArgs extends SourceOptions {
   readonly after?: string;
 }
 
+/**
+ * The largest page a read will serve. A TWIN of `@ultimat3/entity`'s `MAX_PAGE_SIZE` — this
+ * package holds no dependency on that one, the same compromise `naming.ts` and `deprecation.ts`
+ * are ported under — and it exists for the same reason: `first` reaches here straight from an
+ * action's input or a route parameter, so `args.first + 1` bound whatever a client sent and one
+ * request could ask for five million rows.
+ */
+const MAX_PAGE_SIZE = 10_000;
+
 /**
  * One page. Push-down when the source implements `seek()`; otherwise the rows are
  * sliced after execution and the source is doing more work than it should.
@@ -38,12 +48,21 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   input: unknown,
   args: PaginateArgs,
 ): Promise<Page<TRow>> {
+  assert(
+    Number.isInteger(args.first) && args.first >= 1 && args.first <= MAX_PAGE_SIZE,
+    `first must be a whole number of rows between 1 and ${MAX_PAGE_SIZE}`,
+    `read.page(input, { first: Math.min(requested, ${MAX_PAGE_SIZE}) }) — or bound it in the input schema: t.number.int().min(1).max(50)`,
+  );
   const name = queryName(target);
   const hash = queryHash(name, input);
   // The scope is this read plus these arguments: a cursor from anywhere else is
   // already `X_CURSOR_INVALID` by the time it gets here.
   const decoded = args.after === undefined ? null : decodeCursor(args.after, hash);
-  const after: SeekKey | null = decoded === null ? null : { key: decoded.key, id: decoded.id };
+  // Revived to the types the columns hold, never left as the strings JSON handed back: a `Date`
+  // key decoded as an ISO string reaches `compareValues` as text and is compared against the
+  // row's own millisecond number, so page two matched nothing at all. See `cursor-value.ts`.
+  const after: SeekKey | null =
+    decoded === null ? null : { key: reviveSortKey(decoded.key), id: decoded.id };
   const base = await sourceFor(target, input, args);
   const shape = base.shape();
 
@@ -59,7 +78,10 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
 
   return {
     rows,
-    endCursor: seek === null ? null : encodeCursor({ scope: hash, key: seek.key, id: seek.id }),
+    endCursor:
+      seek === null
+        ? null
+        : encodeCursor({ scope: hash, key: seek.key.map(serializeSortValue), id: seek.id }),
     hasNextPage: scoped.length > args.first,
   };
 }

package/src/policy-gate.ts

@@ -7,7 +7,7 @@
 import type { Actor, Ctx } from '@ultimat3/core';
 import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce } from '@ultimat3/policy';
+import { enforce, policyPermissions as flattenedPermissions } from '@ultimat3/policy';
 import { QueryDeniedError } from './errors';
 
 /** Policies are opaque here: we evaluate them, we never introspect their rules. */
@@ -60,7 +60,18 @@ export function actorOf(ctx: Ctx): Actor | null {
   return isAnonymous(ctx.actor) ? null : ctx.actor;
 }
 
-/** The capability a read requires, for manifests and the `/_x` dashboard. */
+/** The capability a read requires, for manifests and the `/_x` dashboard. A DISPLAY label. */
 export function policyCapability(policy: QueryPolicy): string {
   return policy.label;
 }
+
+/**
+ * Every permission the policy tree references, flattened and deduped — and the only field a
+ * compliance report may match a grant against. `label` renders a composite as
+ * `or(feed:read, org:administer)`, which is a sentence and never equals a permission string, so
+ * matching on it reported every read guarded by a composite as enforcing nothing. The mirror of
+ * `@ultimat3/action`'s, because `x policy list` reads both lists the same way.
+ */
+export function policyPermissions(policy: QueryPolicy): readonly string[] {
+  return flattenedPermissions(policy);
+}

package/src/query.ts

@@ -7,24 +7,40 @@
  */
 
 import type { CacheTag } from '@ultimat3/cache';
+import { tagKeys } from '@ultimat3/cache';
 import type { Actor, Ctx } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { QueryCacheScope } from './cache';
 import type { QueryClientMethod, QueryClientOptions } from './client';
+import type { Deprecation } from './deprecation';
+import { QueryCacheTtlInvalidError } from './errors';
 import { facadeFor } from './facade';
+import { assertEncodableInput } from './input-shape';
 import type { LiveQuery, ToLiveOptions } from './live';
 import type { QueryToolDescriptor } from './mcp-tool';
 import type { Page, PaginateArgs } from './pagination';
 import type { QueryPolicy, QuerySurface } from './policy-gate';
-import { policyCapability } from './policy-gate';
+import { policyCapability, policyPermissions } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
 import type { SqlSource } from './source';
 import { fingerprint } from './stable';
-import { tagKeys } from './tags';
 
 export interface QueryCache {
   /** Tags this read depends on. An action's `invalidates` drops exactly these keys. */
   readonly tags: readonly CacheTag[];
+  /**
+   * Lifetime of a tier entry. Positive and finite — `Infinity`, `0` and `NaN` are refused at
+   * `query()` (`X_QUERY_CACHE_TTL_INVALID`), where the file that wrote them fails, rather than on
+   * every read of that query forever. Omitted takes `DEFAULT_READ_CACHE_TTL_MS`.
+   */
   readonly ttlMs?: number;
+  /**
+   * Who a cached answer may be handed back to. **Defaults to `actor`**, and that default is the
+   * mechanism: a read that declares nothing gets the narrowest key, which is always correct.
+   * `tenant` and `global` are written statements that the rows do not depend on the caller beyond
+   * their org, or at all — see `readAuthority`.
+   */
+  readonly scope?: QueryCacheScope;
 }
 
 export interface QueryMcp {
@@ -40,6 +56,17 @@ export interface QueryMcp {
   readonly visibleTo?: readonly string[];
 }
 
+/**
+ * The symmetric twin of `ActionRateLimit`, and the field whose absence meant a read could not be
+ * throttled at all: every `GET /_x/query/*` fell through to the `default` bucket (120 burst, 2/s
+ * per actor), so one authenticated caller could hold 120 cross-tenant aggregates in flight and
+ * then 2/s forever, from a single account, with no declaration able to say otherwise.
+ */
+export interface QueryRateLimit {
+  readonly limit: number;
+  readonly windowMs: number;
+}
+
 export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object> {
   readonly input: TInput;
   readonly policy: QueryPolicy;
@@ -48,12 +75,27 @@ export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object>
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
+  /** Burst and refill for THIS read's route, in the limiter's own vocabulary. */
+  readonly rateLimit?: QueryRateLimit;
+  /**
+   * On its way out. `Deprecation` and `Sunset` response headers (RFC 9745 / RFC 8594), a
+   * `rel="successor-version"` link when `replacedBy` names one, and a
+   * `deprecated_calls_total{name}` counter — the only way to answer "is anyone still reading
+   * it?" before deleting it. Versioning itself is two deployments behind one ingress, not a
+   * router feature; see the README.
+   */
+  readonly deprecated?: Deprecation;
 }
 
 export interface QueryOptions {
   readonly ctx?: Ctx;
   readonly surface?: QuerySurface;
-  /** Skips the cache tiers for this call. Live fanout always reads fresh. */
+  /**
+   * Skips every cache for this call — the request memo as well as the tiers, since a memo is a
+   * cache with a request's lifetime. The one way to read past a write made earlier in the same
+   * request: what it reads replaces the memo entry, so the next plain read of this key in this
+   * request sees the write too. Live fanout always reads fresh.
+   */
   readonly fresh?: boolean;
   /**
    * Run as someone else. Omitted keeps the context's own actor; `null` is the
@@ -65,20 +107,42 @@ export interface QueryOptions {
 
 export interface SourceOptions extends QueryOptions {
   /**
-   * `false` for developer tooling (`explain`, admin-gated) and for the shared, subject-less
-   * window a sync node builds once per `(query, input)` — see `ToLiveOptions.enforce`. Both are
-   * reads with no subscriber to decide about; every other caller leaves it alone.
+   * Build this source WITHOUT evaluating its policy, and say WHY — a written reason, never a bare
+   * boolean. It was `enforce: false`, and a boolean is wrong here for the reason
+   * `@ultimat3/entity`'s `cross-tenant.ts` gives for the same shape: it reads exactly like
+   * forgetting the check. The reason is the mechanism, not documentation of it — a blank one is
+   * refused (`X_INVARIANT`), so an escape with no argument cannot be written at all, and every
+   * skipped policy in a codebase is one `grep` away with the justification attached.
+   *
+   * Two situations qualify, and both are reads with no subscriber to decide about: developer
+   * tooling that returns no rows (`explain`, `describeSql`) and the shared, subject-less window a
+   * sync node builds once per `(query, input)` — see `ToLiveOptions.enforce`, which is that one
+   * use spelled as a boolean because it has exactly one reason and this file already states it.
+   *
+   * It is deliberately NOT gated on a capability the way `crossTenant` is: `explain` runs from the
+   * CLI with no actor at all to check one against, so a scope requirement would close the one
+   * surface this exists for. The rows are still tenant-scoped by `@ultimat3/entity` under the
+   * caller's own context, which `read.ts` now installs.
    */
-  readonly enforce?: boolean;
+  readonly unenforced?: string;
 }
 
 export interface QueryDescriptor {
   readonly kind: 'query';
   readonly name: string;
   readonly live: boolean;
+  /** The policy's DISPLAY label. A composite renders as `or(a:b, c:d)` — never a permission. */
   readonly capability: string;
+  /**
+   * Every permission the policy tree references, flattened. The field a compliance report
+   * matches a grant against; `capability` is a label and matching on it reported every
+   * composite-guarded read as enforcing nothing.
+   */
+  readonly permissions: readonly string[];
   readonly tags: readonly string[];
   readonly ttlMs: number | null;
+  readonly rateLimit: QueryRateLimit | null;
+  readonly deprecated: Deprecation | null;
 }
 
 /**
@@ -93,6 +157,8 @@ export interface AnyQueryDef {
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
+  readonly rateLimit?: QueryRateLimit;
+  readonly deprecated?: Deprecation;
 }
 
 export interface AnyQuery {
@@ -105,6 +171,9 @@ export interface AnyQuery {
   readonly policy: QueryPolicy;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
+  /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
+  readonly rateLimit?: QueryRateLimit;
+  readonly deprecated?: Deprecation;
   describe(): QueryDescriptor;
   /** A twin under another name. Registration names through `named`. */
   named(name: string): AnyQuery;
@@ -141,15 +210,42 @@ export interface Query<
 /** The fluent half of a query: lifted declaration plus one method per projection. */
 export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> = Pick<
   Query<TInput, TRow>,
-  'input' | 'policy' | 'cache' | 'mcp' | 'as' | 'page' | 'live' | 'tool' | 'client'
+  | 'input'
+  | 'policy'
+  | 'cache'
+  | 'mcp'
+  | 'rateLimit'
+  | 'deprecated'
+  | 'as'
+  | 'page'
+  | 'live'
+  | 'tool'
+  | 'client'
 >;
 
 export function query<TInput extends StandardSchemaV1, TRow extends object>(
   def: QueryDef<TInput, TRow>,
 ): Query<TInput, TRow> {
+  // Here and not in `toQueryRoute`: a read is projected to `GET /_x/query/<kebab>` whether or not
+  // anyone mounts it, and the typed client derives that same URL — so an input a query string
+  // cannot carry is wrong for every call, and the file that declared it is where it is repaired.
+  assertEncodableInput(def.input);
+  assertCacheTtl(def.cache);
   return build(def, '');
 }
 
+/**
+ * The same rule, for the same reason: a lease every `CacheTier` refuses is wrong for every read of
+ * this query, so it fails on the line that wrote it rather than on the first request. Positive and
+ * finite is `assertTtl`'s bar in `@ultimat3/cache`, restated as a refusal and never as a second
+ * resolution — there is no "never expires" to fall back to.
+ */
+function assertCacheTtl(cache: QueryCache | undefined): void {
+  const ttlMs = cache?.ttlMs;
+  if (ttlMs === undefined) return;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new QueryCacheTtlInvalidError(ttlMs);
+}
+
 /**
  * Structural, not nominal: an object only counts as a query if `query()` built it,
  * because only then does a declaration exist for `sourceFor` to read. A look-alike
@@ -203,8 +299,12 @@ export function describeQuery(target: AnyQuery): QueryDescriptor {
     name: queryName(target),
     live: target.isLive,
     capability: policyCapability(target.policy),
+    // The flattened list, beside the label and never instead of it: one is read, one is matched.
+    permissions: policyPermissions(target.policy),
     tags: tagKeys(target.cache?.tags ?? []),
     ttlMs: target.cache?.ttlMs ?? null,
+    rateLimit: target.rateLimit ?? null,
+    deprecated: target.deprecated ?? null,
   };
 }
 

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);
 }