@ultimat3/query 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -22,6 +22,7 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `naming.ts` | export name → `/_x/query/<kebab>`. Pure string math. **Paths only** — no tool name |
 | `registry.ts` | export-name registration, `describeQueries()`, and the `registerPrimitiveRegistrar('query', …)` announcement |
 | `live.ts` | `LiveQuery` descriptor + cursor arithmetic |
+| `subscribes.ts` | the relations a live read declares, and the two assertions that keep them true |
 | `matcher.ts` | change event → minimal patch, `refill` when the window cannot place the row, or `X_MATCHER_UNSUPPORTED` |
 | `pagination.ts` | `paginate()` over core's cursor codec — no offset, ever |
 | `cursor-value.ts` | what a sort value becomes inside a cursor, and what it becomes again |
@@ -208,6 +209,11 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   --json` measures, and they must stay that: `errors.ts` runs `registerErrorCodes` at import in both
   packages, and query's `registry.ts` runs `registerPrimitiveRegistrar('query', …)` — drop either
   and a bundled app loses its error titles or throws `X_REGISTRAR_MISSING`. Never `false`.
+- **Every numeric option is refused when it is not a FINITE number, `As of 2026-08-26`.**
+  `@ultimat3/core`'s `finiteOption()` guards the read cache's `ttlMs` and `search()`'s `page.max`,
+  `page.default` and `termMax`; `bun run finite-bounds` is the ratchet and this package is pinned
+  at **zero**. `??` guards nullish and `NaN` is not, so an unchecked bound is a comparison that
+  reads false forever — and `Math.max`/`Math.floor` propagate `NaN` rather than validating it.
 - **`search()` is a FACTORY over `query()`, never a ninth primitive.** It owns the input schema
   (`q` + a `limit` bounded in the schema, beside the read's own keys), trims and refuses a blank
   term, and calls `.search(term)` on the chain the app hands it — which is what makes the term
@@ -221,7 +227,44 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   minting one from the other here, and falling through to `paginate`'s in-memory slice would cut
   inside the one page the provider fetched and report `hasNextPage: false` at its edge. Rows served
   on no page at all is the defect 12.0.0 spent a release removing from the timestamp seek; the
-  `fix:` names the entity chain, which pages this read correctly.
+  `fix:` names the entity chain, which pages this read correctly. **The refusal is on the rows that
+  would be CUT, never on the window**, `As of 2026-08-26`: a screen demanding `first >= limit`
+  refuses the framework's own default pair — `limit` defaults to 20 and `first` arrives from a
+  client — so every `pageSize` under 20 was a 500 at page ONE, including a search matching three
+  rows that fit the window twice over. `windowOf.execute` asserts on `rows.length` instead, so a
+  page that is whole is served with `hasNextPage: false` and no cursor is ever handed back that a
+  second call is guaranteed to refuse. **The one page it serves is the
+  chain's own ORDER**, `As of 2026-08-26`: `onePage.seek` narrows the window with `Builder.limit()`
+  and never with `Builder.seek()`, which sets `totalized` — `servedOrder()` is then `totalOrder([])`
+  = `id asc`, because the ranking lives inside the chain behind the row thunk and no `OrderKey` here
+  can name it, and `execute()` re-sorts the page the provider already ranked. Measured with a chain
+  serving `z, m, a`: `runQuery` answered `z, m, a` and `.page(input, { first: 2 })` answered `a, m`,
+  dropping the top-ranked row off page one. It exposes no `total()` for the same reason — an absent
+  `total` is how `SqlSource` says the source already serves one order it can be resumed in. The
+  fixture in `search.test.ts` must stay NOT id-ascending: `ROWS` is `a, b, c`, which is why the
+  shipped page test could not see this.
+- **`subscribes:` is DECLARED because nothing can derive it, and CROSS-CHECKED because a
+  declaration drifts** (`subscribes.ts`, `As of 2026-08-26`). `@ultimat3/realtime` refuses a
+  subscription to a table that is not `REPLICA IDENTITY FULL` — logical replication carries no old
+  row on an `UPDATE`, so no patch is computable — and nothing emitted the `alter`, so a scaffolded
+  app with a live query generated a schema its own preflight rejected (#357). It cannot be derived:
+  the relation name is a string inside `sql:`, a callback no generator can invoke without valid
+  input, so `QueryDescriptor` carried no table and `x db gen` had no live-query set to read. The
+  field is optional and a read that declares nothing is unchanged — the emitter sees no table.
+  The cross-check is what makes it worth shipping: `toLiveQuery` asserts `shape.entity` is among the
+  declared names at the first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`), one line under
+  `assertMatchable` and for its reason — a live read whose old row never arrives cannot be patched,
+  so a WARNING would preserve only a subscription that silently stops updating, and the stale
+  declaration has already granted the identity to the wrong table. `pg-preflight.ts`'s
+  `warnPartialIdentity` warns instead, and that precedent does NOT transfer: it fires for every app
+  on the postgres default, which nobody wrote, while this fires only on a declaration an author
+  wrote wrong. **Membership, never equality** — a `QueryShape` names one relation and a read may
+  join several, and `@ultimat3/db` keeps only the declared names an entity's table matches, so an
+  extra name costs nothing and the resolved one going missing is the whole failure. An empty list,
+  or one on a read that is not `live: true`, is refused at `query()`
+  (`X_QUERY_SUBSCRIBES_INVALID`) beside `assertCacheTtl`: a declaration nothing can act on is wrong
+  for every subscriber, and one on a non-live read would never reach the cross-check at all —
+  declared and never wired, which is the defect this field exists to close.
 - Policy runs per subscriber for live queries. Never cache a decision across actors.
 - The matcher patches from `QueryShape`, never from SQL text.
 - `paginate` has no `offset` parameter and must never grow one, and it is reachable **only** as

package/README.md

@@ -151,6 +151,42 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `policy` | evaluated **per subscriber**, on subscribe and on every fanout |
 | cursor | reconnect state: epoch + query hash + version + seek key |
 
+### `subscribes:` — the one fact about a live read nothing can derive
+
+```ts
+import { from, type QueryPolicy, query, t } from '@ultimat3/query';
+
+interface PostSummary {
+  readonly id: string;
+  readonly orgId: string;
+  readonly createdAt: Date;
+}
+
+declare const feedRead: QueryPolicy;
+declare const repo: () => Promise<readonly PostSummary[]>;
+
+export const liveFeed = query({
+  input: t.object({ orgId: t.uuid }),
+  policy: feedRead,
+  live: true,
+  subscribes: ['posts'],   // the table `x db gen` grants REPLICA IDENTITY FULL
+  sql: ({ orgId }) => from<PostSummary>('posts', repo).where({ orgId }).orderBy('createdAt'),
+});
+```
+
+Logical replication carries no old row on an `UPDATE` unless the table is `REPLICA IDENTITY FULL`,
+so no patch can be computed and `@ultimat3/realtime` refuses the subscription. The table name lives
+inside `sql:` — a callback nothing can invoke without valid input — so `x db gen` has no way to
+work it out and needs it declared.
+
+Optional: a read that declares nothing behaves exactly as it did, and the generator emits nothing
+for it. It is **checked, not trusted** — `toLiveQuery` refuses at the first subscribe when the
+relation the read resolves to is not among the declared names (`X_QUERY_SUBSCRIBES_DRIFT`), because
+a stale declaration grants the identity to the wrong table and leaves the right one unpatchable in
+silence. An empty list, or one on a read that is not `live: true`, is refused at `query()`
+(`X_QUERY_SUBSCRIBES_INVALID`). Naming more relations than the shape resolves to is legal — a join
+reads relations the shape's single `entity` cannot name.
+
 ### Cursor tradeoff (the reconnect risk, stated plainly)
 
 A cursor is not a snapshot. Resume re-runs the **bounded** query from the seek key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "16.0.0",
+  "version": "18.0.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -28,17 +28,17 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "16.0.0",
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/http": "16.0.0",
-    "@ultimat3/policy": "16.0.0",
-    "@ultimat3/schema": "16.0.0"
+    "@ultimat3/cache": "18.0.0",
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/http": "18.0.0",
+    "@ultimat3/policy": "18.0.0",
+    "@ultimat3/schema": "18.0.0"
   }
 }

package/src/errors.ts

@@ -23,6 +23,8 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_QUERY_INPUT_UNENCODABLE: 'a query input cannot be carried in a query string',
   X_QUERY_NOT_PAGEABLE: 'a read returned rows with no id, so a cursor cannot name a position',
   X_QUERY_POLICY_MISSING: 'a query was registered without a policy',
+  X_QUERY_SUBSCRIBES_DRIFT: 'a live query subscribes to a relation its own sql never reads',
+  X_QUERY_SUBSCRIBES_INVALID: 'a query declares subscribed relations no live read can use',
   X_QUERY_UNREGISTERED: 'a query was used before it was registered',
 };
 
@@ -248,6 +250,52 @@ export class MatcherUnsupportedError extends UltimateError {
   }
 }
 
+/**
+ * A `subscribes:` declaration that cannot mean anything, refused at `query()` so the file that
+ * wrote it is the file that fails — the rule `assertCacheTtl` follows one field over.
+ *
+ * `problem` is a closed union rather than two classes: both are the same author mistake in the
+ * same declaration, and a caller catching one wants the other too.
+ */
+export class QuerySubscribesInvalidError extends UltimateError {
+  constructor(problem: 'empty' | 'not-live') {
+    super({
+      code: 'X_QUERY_SUBSCRIBES_INVALID',
+      cause:
+        problem === 'empty'
+          ? 'subscribes: [] names no relation, so no table can be granted REPLICA IDENTITY FULL'
+          : 'subscribes: names relations on a read that is not live, and only a live read subscribes',
+      fix:
+        problem === 'empty'
+          ? "name the relation the read selects from — subscribes: ['posts'] — or drop the field"
+          : 'add `live: true` beside it, or delete `subscribes:` — nothing reads it on a plain read',
+    });
+  }
+}
+
+/**
+ * The declaration and the read disagreed. Thrown at the first subscribe, where the resolved shape
+ * is the first thing in the framework that can answer which relation the read really names.
+ *
+ * A refusal and not a warning, for the reason `assertMatchable` refuses one line above it: a live
+ * query whose old row never arrives cannot be patched, so what a warning would preserve is a
+ * subscription that silently stops updating. `x db gen` reads this declaration, so a stale one has
+ * already granted REPLICA IDENTITY FULL to the wrong table and left this one without it.
+ */
+export class QuerySubscribesDriftError extends UltimateError {
+  constructor(name: string, declared: readonly string[], entity: string) {
+    super({
+      code: 'X_QUERY_SUBSCRIBES_DRIFT',
+      cause:
+        `live query "${name}" declares subscribes: [${declared.join(', ')}], ` +
+        `and its sql reads "${entity}", which is not among them`,
+      fix:
+        `add "${entity}" to that query's subscribes:, then run \`x db gen\` — ` +
+        'the migration granting REPLICA IDENTITY FULL is keyed on the declared names',
+    });
+  }
+}
+
 export class QueryInputInvalidError extends UltimateError {
   constructor(name: string, detail: string) {
     super({

package/src/facade.ts

@@ -25,6 +25,7 @@ export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
   return {
     input: def.input,
     policy: def.policy,
+    ...(def.subscribes === undefined ? {} : { subscribes: def.subscribes }),
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),

package/src/index.ts

@@ -73,6 +73,8 @@ export {
   QueryNotPageableError,
   QueryPolicyMissingError,
   QueryRequestFailedError,
+  QuerySubscribesDriftError,
+  QuerySubscribesInvalidError,
   QueryUnregisteredError,
 } from './errors';
 /** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */

package/src/live.ts

@@ -18,6 +18,7 @@ import { queryHash } from './query';
 import { queryName, sourceFor } from './read';
 import type { QueryShape, SeekKey } from './shape';
 import { seekKeyOf } from './shape';
+import { assertSubscribed } from './subscribes';
 
 /**
  * Reconnect state. Deliberately tiny — an id, a sort key and a version — because
@@ -123,6 +124,10 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
   const shape = source.shape();
   // Fail at subscribe time, not on the first change event nobody can patch.
   assertMatchable(name, shape);
+  // The same moment and the same reason, one declaration further out: a `subscribes:` the read has
+  // outgrown means `x db gen` granted REPLICA IDENTITY FULL somewhere else, so every UPDATE on this
+  // relation arrives without its old row and no patch is computable from it.
+  assertSubscribed(name, target.subscribes, shape.entity);
 
   const epoch = options.epoch ?? liveEpoch();
   const hash = queryHash(name, input);

package/src/query.ts

@@ -24,6 +24,7 @@ import type { QueryPolicy, QuerySurface } from './policy-gate';
 import { policyCapability, policyPermissions } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
 import type { SqlSource } from './source';
+import { assertSubscribes } from './subscribes';
 
 export interface QueryCache {
   /** Tags this read depends on. An action's `invalidates` drops exactly these keys. */
@@ -72,6 +73,22 @@ export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object>
   readonly policy: QueryPolicy;
   /** `true` makes the read subscribable — see `toLiveQuery`. */
   readonly live?: boolean;
+  /**
+   * The relations this live read is patched from — the tables `x db gen` grants
+   * `REPLICA IDENTITY FULL`, without which logical replication carries no old row on an UPDATE
+   * and `@ultimat3/realtime` refuses the subscription.
+   *
+   * A DECLARATION because nothing can derive it: the relation name lives inside `sql:`, a callback
+   * no generator can invoke without valid input, so there is no live-query set to read off the
+   * registry (#357). Optional, and a read that declares nothing behaves exactly as before —
+   * the emitter sees no table and emits no statement.
+   *
+   * Checked, never trusted. An empty list or a read that is not live is refused here
+   * (`X_QUERY_SUBSCRIBES_INVALID`); a list the resolved shape is missing from is refused at the
+   * first subscribe (`X_QUERY_SUBSCRIBES_DRIFT`). Naming MORE relations than the shape resolves to
+   * is legal — a join reads relations the shape's single `entity` cannot name.
+   */
+  readonly subscribes?: readonly string[];
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -140,6 +157,13 @@ export interface QueryDescriptor {
    */
   readonly permissions: readonly string[];
   readonly tags: readonly string[];
+  /**
+   * The relations declared on a live read, or `null` when it declared none — the fact
+   * `@ultimat3/cli` reads out of the manifest to tell `x db gen` which tables need
+   * `REPLICA IDENTITY FULL`. `null` and not `[]`: an empty list is refused at `query()`, so
+   * absence has exactly one meaning and the manifest can drop the key rather than write it empty.
+   */
+  readonly subscribes: readonly string[] | null;
   readonly ttlMs: number | null;
   readonly rateLimit: QueryRateLimit | null;
   readonly deprecated: Deprecation | null;
@@ -154,6 +178,7 @@ export interface AnyQueryDef {
   readonly input: StandardSchemaV1;
   readonly policy: QueryPolicy;
   readonly live?: boolean;
+  readonly subscribes?: readonly string[];
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
@@ -169,6 +194,8 @@ export interface AnyQuery {
   /** The declaration, minus `sql`: readable, and never a way to run it. */
   readonly input: StandardSchemaV1;
   readonly policy: QueryPolicy;
+  /** Lifted for the same reason `rateLimit` is: `toLiveQuery` cross-checks it without `defOf`. */
+  readonly subscribes?: readonly string[];
   readonly cache?: QueryCache;
   readonly mcp?: QueryMcp;
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
@@ -212,6 +239,7 @@ export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> =
   Query<TInput, TRow>,
   | 'input'
   | 'policy'
+  | 'subscribes'
   | 'cache'
   | 'mcp'
   | 'rateLimit'
@@ -231,7 +259,13 @@ export function query<TInput extends StandardSchemaV1, TRow extends object>(
   // 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, '');
+  assertSubscribes(def.subscribes, def.live);
+  // Snapshot and freeze BEFORE registration. `build()` stores `def` and `facadeFor()` exposes the
+  // same array, so a caller holding the literal it passed could mutate the list AFTER validation
+  // — and that list is what the manifest publishes and what `x db gen` grants REPLICA IDENTITY
+  // FULL from. A frozen copy makes the declaration the descriptor carries the one that was checked.
+  const subscribes = def.subscribes === undefined ? undefined : Object.freeze([...def.subscribes]);
+  return build(subscribes === undefined ? def : { ...def, subscribes }, '');
 }
 
 /**
@@ -302,6 +336,7 @@ export function describeQuery(target: AnyQuery): QueryDescriptor {
     // 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 ?? []),
+    subscribes: target.subscribes ?? null,
     ttlMs: target.cache?.ttlMs ?? null,
     rateLimit: target.rateLimit ?? null,
     deprecated: target.deprecated ?? null,

package/src/read.ts

@@ -10,6 +10,7 @@ import {
   anonymousActor,
   assert,
   createContext,
+  finiteOption,
   logger,
   runWithContext,
   tryUseContext,
@@ -186,7 +187,13 @@ async function readRowsIn(
   // 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);
+    : await readThrough(
+        ctx,
+        key,
+        finiteOption('the read cache', 'ttlMs', def.cache.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS),
+        read,
+        tags,
+      );
 }
 
 async function buildSource(

package/src/search.ts

@@ -6,14 +6,14 @@
  * syntax, and the tenant predicate is never optional.
  */
 
-import { assert, type Ctx } from '@ultimat3/core';
+import { assert, type Ctx, finiteOption } from '@ultimat3/core';
 import type { InferOutput, Shape, Simplify } from '@ultimat3/schema';
 import { t } from '@ultimat3/schema';
 import type { QueryPolicy } from './policy-gate';
 import type { QueryCache, QueryMcp, QueryRateLimit } from './query';
 import { query } from './query';
 import type { SeekKey } from './shape';
-import type { SqlSource, SqlText } from './source';
+import type { Builder, SqlSource, SqlText } from './source';
 import { from } from './source';
 
 /**
@@ -76,7 +76,8 @@ const limitSchema = (max: number, fallback: number) =>
   t.number.int().min(1).max(max).default(fallback);
 
 /**
- * A search serves ONE page, and asking for a second is refused rather than answered wrongly.
+ * A search serves ONE page, in the order the chain served it, and asking for a second is refused
+ * rather than answered wrongly.
  *
  * The rows come from the entity chain, which pages by its own keyset cursor — proven against a real
  * server in `packages/entity/src/pg-search.live.test.ts`. That cursor cannot cross this seam: a
@@ -86,22 +87,90 @@ const limitSchema = (max: number, fallback: number) =>
  * `hasNextPage: false` at its edge — rows served on no page at all, which is the defect 12.0.0 spent
  * a release removing from the timestamp seek. So it is a refusal with the alternative in the `fix`:
  * page with the entity chain's own `.search(term).after(cursor)`, or raise this read's `limit`.
+ *
+ * **The refusal is on the rows that would be CUT, never on the window** (`As of 2026-08-26`). It
+ * used to serve `first` rows, mint an `endCursor` and report `hasNextPage: true` — a connection
+ * protocol saying "call me again with this" for a call the cursor assert is guaranteed to throw on.
+ * A first repair demanded `first >= limit` and refused the window itself, which refuses the
+ * framework's OWN default pair: `limit` defaults to 20 and `first` arrives from a client
+ * (`{ first: query.pageSize }`), so every `pageSize` under 20 was a 500 at page ONE — including
+ * every search that matched three rows and fit the window twice over. A screen that fires on a
+ * request the read can answer completely is not protecting anyone.
+ *
+ * So the condition is the one thing that is actually wrong: the read answered MORE rows than the
+ * window carries, and this seam has no second page to put the rest on. Below that, the page is
+ * whole and `hasNextPage` is false by construction — the true stop signal, and no cursor is ever
+ * handed back that a second call is guaranteed to refuse.
+ *
+ * **`seek` narrows the WINDOW and never the ORDER, and that is the whole reason this wrapper takes a
+ * `Builder`.** `Builder.seek()` sets `totalized`, so `servedOrder()` becomes `totalOrder([])` —
+ * `id asc`, because the relevance ordering lives inside the chain behind the row thunk and no key
+ * here can name it — and `execute()` then re-sorts the page the provider already ranked. Measured
+ * with a chain serving `z, m, a`: `runQuery` answered `z, m, a` and `.page(input, { first: 2 })`
+ * answered `a, m`, dropping the top-ranked row off page one. `limit()` is the same window with no
+ * ordering claim attached, which is what an already-ranked page needs.
  */
-const onePage = <Row extends object>(base: SqlSource<Row>, entity: string): SqlSource<Row> => ({
+const onePage = <Row extends object>(
+  base: Builder<Row>,
+  entity: string,
+  /** Rows the chain was capped at — this read's `limit` input, and its whole page. */
+  served: number,
+): SqlSource<Row> => ({
   toSQL: (): SqlText => base.toSQL(),
   execute: () => base.execute(),
   shape: () => base.shape(),
-  ...(base.total === undefined ? {} : { total: () => onePage(base.total?.() ?? base, entity) }),
-  seek: (after: SeekKey | null, limit: number): SqlSource<Row> => {
+  // No `total()`: `SqlSource` reads its absence as "the source already serves one order it can be
+  // resumed in", which is exactly true of a relevance ranking — and `total()` would totalize the
+  // Builder, re-sorting that ranking by id for the same reason `seek` must not.
+  seek: (after: SeekKey | null, window: number): SqlSource<Row> => {
     assert(
       after === null,
       `search of ${entity} serves one page: a relevance-filtered read has no cursor this layer can carry`,
       `db.${entity}.search(term).orderBy('<key>').after(cursor).page()   # the entity chain pages this read — or raise its limit`,
     );
-    return onePage(base.seek?.(after, limit) ?? base, entity);
+    // `paginate` asks for `first + 1` — the extra row IS `hasNextPage` — so the window it names is
+    // one wider than the page it will serve.
+    return windowOf(base, entity, served, window - 1);
   },
 });
 
+/**
+ * The one page, narrowed to the window `paginate` asked for and refused only when it does not FIT.
+ *
+ * The check is on the rows that came back, not on the two numbers, because those two numbers cannot
+ * decide it: `first: 10` against a `limit` of 20 is a complete answer whenever the term matched ten
+ * rows or fewer, which is most searches. Refusing it on the declaration alone made the framework's
+ * own defaults a 500.
+ *
+ * The `fix:` names `served` — the read's declared `limit` — and never the count that came back: a
+ * window sized to today's result set breaks on the first row added to the corpus.
+ */
+const windowOf = <Row extends object>(
+  base: Builder<Row>,
+  entity: string,
+  served: number,
+  /** Rows `paginate` will serve. It fetched one more, to decide `hasNextPage`. */
+  first: number,
+): SqlSource<Row> => {
+  const windowed = base.limit(first + 1);
+  return {
+    toSQL: (): SqlText => windowed.toSQL(),
+    shape: () => windowed.shape(),
+    // No `seek()` and no `total()`: `paginate` seeks once, and `SqlSource` reads an absent `total`
+    // as "the source already serves one order it can be resumed in" — exactly true of a relevance
+    // ranking, which `total()` would re-sort by id for the same reason `seek` must not.
+    execute: async () => {
+      const rows = await windowed.execute();
+      assert(
+        rows.length <= first,
+        `search of ${entity} answered more than the ${String(first)} rows .page() asked for, and this read has no second page: the rest would be on no page at all`,
+        `read.page(input, { first: ${String(served)} })   # widen the window to the read's whole page — or narrow the page: read({ q, limit: ${String(first)} })`,
+      );
+      return rows;
+    },
+  };
+};
+
 /**
  * The factory. `live: false` and the source declares itself unpatchable, because the incremental
  * matcher decides membership from `QueryShape` filters and a `tsvector` match is not one of them —
@@ -111,11 +180,14 @@ export const search = <Row extends object, S extends Shape = Record<string, neve
   def: SearchDef<S, Row>,
 ) => {
   const page = def.page ?? {};
-  const max = page.max ?? DEFAULT_PAGE_MAX;
+  const max = finiteOption('search()', 'page.max', page.max ?? DEFAULT_PAGE_MAX);
   const shape = {
     ...((def.input ?? {}) as S),
-    q: termSchema(def.termMax ?? DEFAULT_TERM_MAX),
-    limit: limitSchema(max, Math.min(page.default ?? DEFAULT_PAGE_SIZE, max)),
+    q: termSchema(finiteOption('search()', 'termMax', def.termMax ?? DEFAULT_TERM_MAX)),
+    limit: limitSchema(
+      max,
+      Math.min(finiteOption('search()', 'page.default', page.default ?? DEFAULT_PAGE_SIZE), max),
+    ),
   } as SearchShape<S>;
 
   return query({
@@ -139,7 +211,7 @@ export const search = <Row extends object, S extends Shape = Record<string, neve
       const chain = def.in({ input: parsed, ctx });
       const name = chain.plan().entity;
       const rows = () => chain.search(term).limit(parsed.limit).all();
-      return onePage(from<Row>(name, rows).raw('full-text search'), name);
+      return onePage(from<Row>(name, rows).raw('full-text search'), name, parsed.limit);
     },
   });
 };

package/src/subscribes.ts

@@ -0,0 +1,44 @@
+/**
+ * The relations a live read is patched from: the one thing about a query that cannot be derived,
+ * and the two assertions that keep the declaration honest. `x db gen` grants those relations
+ * `REPLICA IDENTITY FULL`, so a name that has gone stale is worse than none — it grants it to the
+ * wrong table and leaves the right one unable to produce a patch, in silence (#357).
+ */
+
+import { QuerySubscribesDriftError, QuerySubscribesInvalidError } from './errors';
+
+/**
+ * Judged at `query()`, beside `assertCacheTtl` and for its reason: a declaration nothing can act on
+ * is wrong for every subscriber of that read, so it fails on the line that wrote it.
+ *
+ * A read that is not live is refused rather than ignored. `subscribes:` has exactly one reader and
+ * that reader only walks live queries, so an accepted one would be a declaration nothing verifies
+ * and nothing emits — the shape of defect this field exists to close.
+ */
+export function assertSubscribes(
+  subscribes: readonly string[] | undefined,
+  live: boolean | undefined,
+): void {
+  if (subscribes === undefined) return;
+  if (subscribes.length === 0) throw new QuerySubscribesInvalidError('empty');
+  if (live !== true) throw new QuerySubscribesInvalidError('not-live');
+}
+
+/**
+ * Judged at the first subscribe, because `shape.entity` is the first answer the framework has to
+ * "which relation does this read actually name" — the string sits inside `sql:`, a callback no
+ * static reader can invoke without valid input.
+ *
+ * Membership, never equality: a `QueryShape` names ONE relation while a read may join several, and
+ * `@ultimat3/db` keeps only the declared names an entity's table matches. So a name the shape never
+ * resolves to costs nothing, and the resolved one going MISSING is the whole failure.
+ */
+export function assertSubscribed(
+  name: string,
+  subscribes: readonly string[] | undefined,
+  entity: string,
+): void {
+  if (subscribes === undefined) return;
+  if (subscribes.includes(entity)) return;
+  throw new QuerySubscribesDriftError(name, subscribes, entity);
+}