@ultimat3/query 17.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 |
@@ -242,6 +243,28 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `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": "17.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": "17.0.0",
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/http": "17.0.0",
-    "@ultimat3/policy": "17.0.0",
-    "@ultimat3/schema": "17.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/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);
+}