@ultimat3/query 1.2.0 → 3.0.0

package/src/input-shape.ts

@@ -0,0 +1,74 @@
+// Single responsibility: what a read's `input:` may be, given that a read is projected to
+// `GET /_x/query/<kebab>` and a query string is characters.
+//
+// `client.ts` encoded a nested member as `JSON.stringify(item)` and skipped a `null`; the server's
+// own route decodes with `coerceQuery`, which has no inverse for either — `case 'object'` hands
+// the raw value back untouched and there is no `JSON.parse` on that path. So the typed client
+// type-checked calls the server then answered `X_INPUT_INVALID` for, which is precisely the
+// failure `client.ts`'s header claims to prevent ("a compile error in a Solid component rather
+// than a 404 at runtime").
+//
+// The fix is the DECLARATION, not the encoder. Teaching `coerceQuery` to `JSON.parse` a string
+// would make the one HTTP-boundary decoder invent structure for every surface that shares it —
+// forms and route params included — against that file's own rule that it "never invents data";
+// and a `null` sentinel would be a reserved string colliding with the legitimate value `"null"`.
+// Refusing here means the client can never encode something the server rejects, because such an
+// input cannot be written.
+
+import { type SchemaNode, tryIntrospect } from '@ultimat3/schema';
+import { QueryInputUnencodableError } from './errors';
+
+/** Node kinds whose value is a structure, not characters. `money` is `{ minor, currency }`. */
+const STRUCTURAL = new Set(['object', 'record', 'money']);
+
+/**
+ * The first key this input could not put on a wire, or `undefined`. One key, not a list: a fix
+ * line names one edit, and the next declaration attempt reports the next key.
+ */
+function unencodable(node: SchemaNode): string | undefined {
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    // Required AND nullable: `searchOf` sends nothing for a `null`, and absence is what the far
+    // side then sees — so the value the caller explicitly chose fails validation on arrival.
+    // Optional or defaulted, absence is already the schema's own answer and nothing is lost.
+    if (child.nullable === true && child.optional !== true && child.hasDefault !== true) {
+      return `${key} is nullable and required`;
+    }
+    const kind = structuralKind(child);
+    if (kind !== undefined) return `${key} is a ${kind}`;
+  }
+  return undefined;
+}
+
+/** The structural kind inside a member, through an array or a union. */
+function structuralKind(node: SchemaNode): string | undefined {
+  if (STRUCTURAL.has(node.kind)) return node.kind;
+  if (node.kind === 'array' && node.items !== undefined) return structuralKind(node.items);
+  if (node.kind === 'union') {
+    for (const member of node.anyOf ?? []) {
+      const kind = structuralKind(member);
+      if (kind !== undefined) return kind;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Refused at `query()`, which is the first import of the authoring file — the same place
+ * `@ultimat3/schema` refuses a `discriminatedUnion` it could never route, and for the same reason:
+ * the declaration is wrong for every input, so the earliest honest moment is where it is written.
+ *
+ * A schema this package cannot introspect is left alone rather than guessed at: `tryIntrospect`
+ * answering `undefined` means a foreign Standard Schema, and refusing one would make the seam
+ * `configureSchemaProvider` exists for unusable.
+ */
+export function assertEncodableInput(input: unknown): void {
+  const node = tryIntrospect(input);
+  if (node === undefined) return;
+  if (node.kind !== 'object') {
+    // `searchOf` answers `''` for anything that is not a plain object, so the server receives no
+    // arguments at all — a read declared this way is called with an input nothing ever carries.
+    throw new QueryInputUnencodableError(`the input is a ${node.kind}, not an object`);
+  }
+  const offender = unencodable(node);
+  if (offender !== undefined) throw new QueryInputUnencodableError(offender);
+}

package/src/live.ts

@@ -2,8 +2,11 @@
  * What `live: true` actually produces: the descriptor @ultimat3/realtime
  * subscribes to. It carries the SQL shape (for the matcher), the dependency set
  * (which entities/tags a change feed must touch to matter), the policy (re-run
- * per subscriber, never once for a channel) and a cursor for cheap reconnects.
+ * per subscriber, never once for a channel) and a cursor for cheap reconnects —
+ * and it runs that read (`execute`), so the shared window and the matcher over it
+ * come from one build of one `(query, input)` rather than two that agree by luck.
  */
+import { tagKeys } from '@ultimat3/cache';
 import type { Ctx } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Patch } from './matcher';
@@ -15,7 +18,6 @@ import { queryHash } from './query';
 import { queryName, sourceFor } from './read';
 import type { QueryShape, SeekKey } from './shape';
 import { seekKeyOf } from './shape';
-import { tagKeys } from './tags';
 
 /**
  * Reconnect state. Deliberately tiny — an id, a sort key and a version — because
@@ -58,6 +60,17 @@ export interface LiveQuery {
   readonly policy: QueryPolicy;
   readonly sqlText: string;
   readonly limit: number | null;
+  /**
+   * The read this descriptor describes, run. It is the *same* source the shape, the reads and the
+   * SQL text were taken from, which is the point: a subscriber's window and the matcher that
+   * patches it have to come from one build of one `(query, input)`. A caller that wanted rows and
+   * called `sourceFor` itself would be a second build — twice the parse, twice the `sql()`, and
+   * two descriptions of one read that are only equal by luck.
+   *
+   * It executes on every call rather than memoising: a client joining an existing subscription
+   * must see the rows as they are now, not the window someone else opened.
+   */
+  execute(): Promise<readonly object[]>;
   /** Per-subscriber authorization. Called on subscribe *and* on every fanout. */
   authorize(subject: QuerySubject): Promise<void>;
   initialCursor(rows: readonly object[]): LiveCursor;
@@ -81,6 +94,13 @@ export interface ToLiveOptions {
   readonly enforce?: boolean;
 }
 
+/**
+ * Why a shared window builds with no policy evaluation. Spelled once, here, so the reason a sync
+ * node gives `sourceFor` cannot drift from the one `ToLiveOptions.enforce` documents.
+ */
+const SHARED_WINDOW_REASON =
+  'the shared subject-less window has no subscriber to decide about; authorize() runs per subscriber';
+
 /** Changing the build changes the epoch, which forces reconnects to refetch. */
 export function liveEpoch(): string {
   return Bun.env['X_BUILD_ID'] ?? 'dev';
@@ -94,7 +114,10 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
   const name = queryName(target);
   const source = await sourceFor(target, input, {
     ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-    ...(options.enforce === undefined ? {} : { enforce: options.enforce }),
+    // The boolean stays this layer's spelling because it has exactly ONE reason, stated on
+    // `ToLiveOptions.enforce` above; `sourceFor` takes that reason as a string so every skipped
+    // policy in the framework is greppable with its justification attached.
+    ...(options.enforce === false ? { unenforced: SHARED_WINDOW_REASON } : {}),
     surface: 'live',
   });
   const shape = source.shape();
@@ -115,6 +138,7 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
     policy,
     sqlText: source.toSQL().sql,
     limit: shape.limit,
+    execute: () => source.execute(),
     authorize: async (subject) => {
       guard(policy, subject, 'live');
     },

package/src/matcher.ts

@@ -4,9 +4,9 @@
  * filters + orderBy + limit; anything else throws X_MATCHER_UNSUPPORTED, because
  * an honest refusal beats a silently wrong result set.
  */
-import { MatcherUnsupportedError } from './errors';
+import { MatcherUnsupportedError, QueryNotPageableError } from './errors';
 import type { QueryShape } from './shape';
-import { compareRows, matchesFilters } from './shape';
+import { compareRows, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
 export type ChangeOp = 'insert' | 'update' | 'delete';
@@ -55,13 +55,13 @@ export function match<TRow extends object>(
   assertMatchable(name, shape);
   if (event.entity !== shape.entity) return [];
 
-  const id = idOf(event.row);
-  const index = rows.findIndex((row) => idOf(row) === id);
+  const id = idOf(event.row, shape.entity);
+  const index = rows.findIndex((row) => idOf(row, shape.entity) === id);
   const inSet = index >= 0;
   const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
 
   if (event.op === 'delete' || (inSet && !belongs)) {
-    return inSet ? removeAt(shape, index, id, true) : [];
+    return inSet ? removeAt(shape, index, id, true, rows.length) : [];
   }
   if (!belongs) return [];
   if (!inSet) return insert(shape, rows, event.row);
@@ -74,9 +74,22 @@ export function match<TRow extends object>(
     compareRows(event.row, current, shape.orderBy) !== 0;
   if (!moved) return [{ kind: 'update', position: index, row: event.row }];
 
-  // A move keeps the window full, so it never needs a refill.
   const without = [...rows.slice(0, index), ...rows.slice(index + 1)];
-  return [...removeAt<TRow>(shape, index, id, false), ...insert(shape, without, event.row)];
+  // A move to the TAIL of a full window is a position only the server can fill. `insert()` places
+  // the row among the `limit - 1` rows the client still holds, so its position can never reach
+  // `shape.limit` and the `position >= shape.limit` bail below is unreachable on this path — the
+  // row was re-inserted INSIDE the window. Proven with `limit: 3`, window `[a:1, b:2, c:3]` and a
+  // server also holding `d:4, e:5`: moving `a` to `99` rendered `[b, c, a:99]` where the true
+  // window is `[b, c, d]`. Whether the moved row is still in the window is the server's answer
+  // too, so the refill covers both.
+  const wasFull = shape.limit !== null && rows.length >= shape.limit;
+  if (wasFull && positionFor(shape, without, event.row) >= without.length) {
+    return removeAt<TRow>(shape, index, id, true, rows.length);
+  }
+  return [
+    ...removeAt<TRow>(shape, index, id, false, rows.length),
+    ...insert(shape, without, event.row),
+  ];
 }
 
 function insert<TRow extends object>(
@@ -91,36 +104,66 @@ function insert<TRow extends object>(
   if (shape.limit !== null && rows.length >= shape.limit) {
     const evicted = rows[shape.limit - 1];
     if (evicted !== undefined) {
-      patches.push({ kind: 'remove', position: shape.limit, id: idOf(evicted) });
+      patches.push({ kind: 'remove', position: shape.limit, id: idOf(evicted, shape.entity) });
     }
   }
   return patches;
 }
 
+/**
+ * `held` is how many rows the window actually holds, and it is the whole condition on the refill.
+ *
+ * A refill says the tail is unknown to the client, and it is answered by a full re-read: the bridge
+ * folds it into `BridgeResult.refill`, and the fanout then sends NO patch frame that round —
+ * suppressing the `remove` beside it and leaving a deleted row on screen until the next change to
+ * the same query. A window under `limit` has no unknown tail: the source served fewer rows than it
+ * was allowed to, so what the client holds IS the result set. Unconditional, this also named a
+ * position no result set has — `limit: 50` over three rows emitted `{ refill, from: 49 }`.
+ */
 function removeAt<TRow extends object>(
   shape: QueryShape,
   index: number,
   id: string,
   refill: boolean,
+  held: number,
 ): readonly Patch<TRow>[] {
   const patches: Patch<TRow>[] = [{ kind: 'remove', position: index, id }];
-  // A limited window may now be one row short, and the tail lives on the server.
-  if (refill && shape.limit !== null) patches.push({ kind: 'refill', from: shape.limit - 1 });
+  // A window that WAS full is now one row short, and that row lives on the server.
+  if (refill && shape.limit !== null && held >= shape.limit) {
+    patches.push({ kind: 'refill', from: shape.limit - 1 });
+  }
   return patches;
 }
 
-/** Insertion index under the query's ordering; append when the query is unordered. */
+/**
+ * Insertion index under the ordering the source serves — `totalOrder`, not the declared keys.
+ *
+ * A page arrives as `order by <declared keys>, "id" asc` and `isAfterKey` reads the next one the
+ * same way, so a row tied on every declared key belongs where its id puts it. Placing it at the
+ * end of the tie group instead is a position the database would never return: the client renders
+ * one order, a re-read answers another, and the cursor cut from the window's tail skips the ties
+ * the matcher pushed past it.
+ *
+ * An unordered query has no position to get wrong — SQL promises none — so it appends.
+ */
 export function positionFor<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
 ): number {
   if (shape.orderBy.length === 0) return rows.length;
-  const found = rows.findIndex((current) => compareRows(row, current, shape.orderBy) < 0);
+  const order = totalOrder(shape.orderBy);
+  const found = rows.findIndex((current) => compareRows(row, current, order) < 0);
   return found === -1 ? rows.length : found;
 }
 
-function idOf(row: object): string {
+/**
+ * The row's identity, and the tiebreak `positionFor` sorts by. Refused when absent for the reason
+ * `seekKeyOf` refuses it: `String(undefined)` is `"undefined"`, an id every id-less row shares, so
+ * one row's patch lands on another's position and a `remove` names a row no client holds.
+ */
+function idOf(row: object, entity: string): string {
   const value = columnOf(row, 'id');
+  if (value === undefined || value === null) throw new QueryNotPageableError(entity);
   return typeof value === 'string' ? value : String(value);
 }

package/src/mcp-tool.ts

@@ -5,9 +5,9 @@
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import type { JsonSchema } from '@ultimat3/schema';
 import { toMcpInputSchema } from '@ultimat3/schema';
-import { toToolName } from './naming';
 import type { QueryPolicy } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, sourceFor } from './read';
@@ -20,6 +20,11 @@ export interface QueryToolReadOptions {
 }
 
 export interface QueryToolDescriptor {
+  /**
+   * The export name VERBATIM, and identical to `query` below. `@ultimat3/mcp` serves a read
+   * under `queryName(target)` and answers `tools/call` for nothing else, so a snake_cased
+   * descriptor named a tool the server had never heard of — which it did until 2026-08.
+   */
   readonly name: string;
   /** The query's `mcp.description`, or its name when the author gave none. */
   readonly description: string;
@@ -38,7 +43,7 @@ export interface QueryToolDescriptor {
 export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
   const name = queryName(target);
   return {
-    name: toToolName(name),
+    name,
     description: target.mcp?.description ?? name,
     query: name,
     policy: target.policy,
@@ -57,11 +62,12 @@ export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
 }
 
 /**
- * Opt-in, unlike an action's tool: a read hands rows to an agent, so silence
- * exposes nothing. `mcp: { expose: true }` is the whole opt-in.
+ * Opt-in: a read hands rows to an agent, so silence exposes nothing. `mcp: { expose: true }` is
+ * the whole opt-in — `isMcpExposed` from `@ultimat3/core` is the framework's one answer, and an
+ * action's tool is now decided by the same call rather than by a second, looser rule.
  */
 export function isExposed(target: AnyQuery): boolean {
-  return target.mcp?.expose === true;
+  return isMcpExposed(target.mcp);
 }
 
 /** Deterministic order — the tool list is part of the agent-visible contract. */

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