@ultimat3/query 23.0.0 → 25.0.0

package/src/audit-errors.ts

@@ -0,0 +1,43 @@
+/**
+ * The two ways an audited read fails because of its audit, and nothing else. Their own module so
+ * `errors.ts` keeps one job — the codes' TITLES are registered there, with every other code this
+ * package owns — and so a read that declares no audit never constructs either.
+ */
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * `audit: true` with no sink installed. Raised before the input is parsed and before anything is
+ * read — the twin of `@ultimat3/action`'s `X_AUDIT_SINK_MISSING`, and for the same reason there is
+ * no logger-backed default to fall back on: a line nobody stores would satisfy the declaration
+ * while recording nothing, which for a read is "who saw what" silently answered "nobody".
+ */
+export class QueryAuditSinkMissingError extends UltimateError {
+  constructor(query: string) {
+    super({
+      code: 'X_QUERY_AUDIT_SINK_MISSING',
+      cause: `query "${query}" declares \`audit: true\` and no audit sink is installed`,
+      // The registered fix, verbatim: code first, so the line can be pasted (`wiki/Error-Codes.md`).
+      fix: 'setAuditSink(sink)   # from @ultimat3/core, at boot before defineApi()',
+    });
+  }
+}
+
+/**
+ * The sink refused the record of a read that SUCCEEDED, so the rows are withheld. The opposite of
+ * the action twin's position on one point: an action's handler had already committed and only the
+ * record is missing, while a read has changed nothing — so refusing the answer costs one retry,
+ * and handing back rows nobody recorded is exactly the gap an audited read exists to close.
+ */
+export class QueryAuditSinkFailedError extends UltimateError {
+  constructor(query: string, sourceError: unknown) {
+    super({
+      code: 'X_QUERY_AUDIT_SINK_FAILED',
+      cause: `"${query}" was read and its audit sink refused the record, so the rows were withheld — a read commits nothing, so nothing is left to reconcile`,
+      // The sink's own error is `sourceError`; a read commits nothing, so the retry is safe.
+      fix: 'setAuditSink(sink)   # install a sink that accepts the record, then retry the read',
+      meta: { query },
+      sourceError,
+    });
+  }
+}

package/src/audit-gate.ts

@@ -0,0 +1,177 @@
+/**
+ * The only file in this package that calls an `AuditSink`: `query({ audit: true })` records every
+ * call — allowed, denied, failed — into the one sink `@ultimat3/core` holds, in the record shape
+ * `@ultimat3/action` writes. It observes the read path; it never forks it.
+ */
+
+import type { AuditOutcome, AuditRecord, AuditSink, Ctx } from '@ultimat3/core';
+import { getAuditSink, isUltimateError, logger } from '@ultimat3/core';
+import { QueryAuditSinkFailedError, QueryAuditSinkMissingError } from './audit-errors';
+import { QueryDeniedError } from './errors';
+import type { QuerySurface } from './policy-gate';
+import type { SqlSource } from './source';
+
+/**
+ * What the read path learns on the way through, for the record — the same two facts `invoke`'s
+ * trace carries for an action, minus the idempotency key a read never has. Mutable on purpose:
+ * `buildSource` fills `input`, the memo fills `replayed`, and reading them back out here is what
+ * keeps the audited branch from becoming a second read path.
+ */
+export interface ReadTrace {
+  input: unknown;
+  replayed: boolean;
+}
+
+/** One audited call, resolved before anything is read: the sink, and what every record shares. */
+export interface ReadAudit {
+  readonly sink: AuditSink;
+  readonly name: string;
+  readonly ctx: Ctx;
+  readonly surface: QuerySurface;
+  readonly trace: ReadTrace;
+}
+
+/**
+ * `null` when the read is not audited — not declared, or built `unenforced`, which has no caller
+ * to attribute a sighting to (`explain`, the shared live window). Otherwise the sink, or
+ * `X_QUERY_AUDIT_SINK_MISSING` BEFORE the input parse: an audited read nothing can record refuses
+ * while it has still read nothing.
+ */
+export function readAuditFor(
+  audit: boolean | undefined,
+  unenforced: string | undefined,
+  name: string,
+  ctx: Ctx,
+  surface: QuerySurface,
+): ReadAudit | null {
+  if (audit !== true || unenforced !== undefined) return null;
+  const sink = getAuditSink();
+  if (sink === null) throw new QueryAuditSinkMissingError(name);
+  return { sink, name, ctx, surface, trace: { input: undefined, replayed: false } };
+}
+
+/**
+ * One call, one record. A memo or cache hit is recorded like a miss — with `replayed: true` — and
+ * that is the point of the option rather than an accident of where it sits: an audit of a read is
+ * about WHO SAW WHAT, and a reader handed rows from the request memo saw them exactly as much as
+ * the reader whose call executed the SQL. Recording only executions would answer "what did the
+ * database compute", which no auditor asks.
+ *
+ * The failure policies are `@ultimat3/action`'s: a refused record of a denied or failed read is
+ * logged and the original error still reaches the caller (replacing an `X_FORBIDDEN` would turn
+ * the audit backend's health into an oracle); a refused record of an ALLOWED read withholds the
+ * rows (`X_QUERY_AUDIT_SINK_FAILED`) — a read commits nothing, so refusing costs one retry.
+ */
+export async function audited<T>(audit: ReadAudit, run: () => Promise<T>): Promise<T> {
+  // When the attempt began, from the context's clock — never `new Date()`.
+  const at = audit.ctx.now();
+  let value: T;
+  try {
+    value = await run();
+  } catch (error) {
+    await recordThrew(audit.sink, recordOf(audit, at, readOutcomeFor(error), error));
+    throw error;
+  }
+  // Outside the `catch` on purpose, as in `invoke`: a refused record here describes the RECORD,
+  // and letting it fall into that branch would write a second record claiming the read failed.
+  await recordSettled(audit.sink, recordOf(audit, at, 'allowed', undefined));
+  return value;
+}
+
+/**
+ * The public `sourceFor`'s half: a build that refuses (denied, unparsed, rate-limited) is a call
+ * that ended, recorded now because no `execute()` will follow; a build that succeeds records
+ * nothing yet and hands back a source whose every execution is recorded.
+ */
+export async function auditedBuild<TRow>(
+  audit: ReadAudit,
+  build: () => Promise<SqlSource<TRow>>,
+): Promise<SqlSource<TRow>> {
+  const at = audit.ctx.now();
+  let source: SqlSource<TRow>;
+  try {
+    source = await build();
+  } catch (error) {
+    await recordThrew(audit.sink, recordOf(audit, at, readOutcomeFor(error), error));
+    throw error;
+  }
+  return auditedSource(source, audit);
+}
+
+/**
+ * A source handed OUT of this package (`sourceFor`) for an audited read: every `execute()` is one
+ * call and one record — `@ultimat3/mcp`'s served tool builds through `sourceFor` and executes once,
+ * so its reads are recorded under `surface: 'mcp'` without a second path. `seek()` and `total()`
+ * answer audited sources too, since `paginate` and a live build execute what those return.
+ */
+export function auditedSource<TRow>(source: SqlSource<TRow>, audit: ReadAudit): SqlSource<TRow> {
+  // Each execution is its own call: a fresh trace, so one call's facts never leak into the next.
+  const call = (): ReadAudit => ({ ...audit, trace: { ...audit.trace, replayed: false } });
+  const { total, seek } = source;
+  return {
+    toSQL: () => source.toSQL(),
+    shape: () => source.shape(),
+    execute: () => audited(call(), () => source.execute()),
+    ...(total === undefined ? {} : { total: () => auditedSource(total.call(source), audit) }),
+    ...(seek === undefined
+      ? {}
+      : { seek: (after, limit) => auditedSource(seek.call(source, after, limit), audit) }),
+  };
+}
+
+/**
+ * An authz refusal is `denied`; everything else that threw is `failed`, an unparsed input and a
+ * spent rate limit included — the same split `@ultimat3/action`'s `auditOutcomeFor` makes, and
+ * TOTAL for the same reason: `instanceof` runs a `Proxy`'s trap, and a probe that threw inside
+ * this `catch` would replace the caller's error with its own.
+ */
+export function readOutcomeFor(error: unknown): AuditOutcome {
+  try {
+    return error instanceof QueryDeniedError ? 'denied' : 'failed';
+  } catch {
+    return 'failed';
+  }
+}
+
+function recordOf(audit: ReadAudit, at: Date, outcome: AuditOutcome, error: unknown): AuditRecord {
+  return {
+    at,
+    name: audit.name,
+    primitive: 'query',
+    mutator: false,
+    surface: audit.surface,
+    ctx: audit.ctx,
+    // The PARSED input, exactly as an action's record carries it — never the raw payload, and
+    // never the rows: a sink that persists redacts through `auditableInput`, the walk core's
+    // credential table and `Secret` decide, and a result is absent from the record by design.
+    input: audit.trace.input,
+    idempotencyKey: null,
+    replayed: audit.trace.replayed,
+    outcome,
+    failure:
+      outcome === 'allowed' ? null : { code: isUltimateError(error) ? error.code : null, error },
+  };
+}
+
+async function recordSettled(sink: AuditSink, record: AuditRecord): Promise<void> {
+  try {
+    await sink.write(record);
+  } catch (error) {
+    throw new QueryAuditSinkFailedError(record.name, error);
+  }
+}
+
+async function recordThrew(sink: AuditSink, record: AuditRecord): Promise<void> {
+  try {
+    await sink.write(record);
+  } catch (error) {
+    // The same line `@ultimat3/action` writes, so `audit.sink.failed` is one alert rule over every
+    // audited primitive. Never the record: rendering an input the sink just choked on is the
+    // second throw this branch exists to prevent.
+    logger.error('audit.sink.failed', {
+      query: record.name,
+      outcome: record.outcome,
+      error,
+    });
+  }
+}

package/src/cache.ts

@@ -6,7 +6,7 @@
  */
 
 import type { CacheStack, CacheTag, CacheTier } from '@ultimat3/cache';
-import { createCacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
+import { cacheStack, registeredTiers, tagKeys } from '@ultimat3/cache';
 import type { Actor, Clock, Ctx } from '@ultimat3/core';
 import { assertNever, fingerprint } from '@ultimat3/core';
 
@@ -164,7 +164,7 @@ async function publish<T>(
 /**
  * One stack per (registry, clock) — never one per read.
  *
- * `createCacheStack` owns a single-flight map, so a stack built per call joins nothing and the
+ * `cacheStack` owns a single-flight map, so a stack built per call joins nothing and the
  * cross-request stampede guard would be a no-op. Keyed on the clock because the stack's expiry
  * decision and the tiers' own have to agree: a tier registered with a frozen clock under a stack
  * reading the wall clock calls every entry expired, which is the shape that made the old read
@@ -182,7 +182,7 @@ function stackFor(clock: Clock): CacheStack {
   // read, and `resetTiers()` between suites. Compared element-wise by identity: a tier object is
   // registered once and never mutated, so two equal lists are the same ladder.
   if (held !== undefined && sameTiers(held.tiers, tiers)) return held.stack;
-  const stack = createCacheStack(tiers, { clock });
+  const stack = cacheStack(tiers, { clock });
   stacks.set(clock, { tiers, stack });
   return stack;
 }
@@ -208,7 +208,7 @@ export function readThrough<T>(
  * package's own. Runs once per key per request; the rest join it at the memo above.
  *
  * Everything this used to do by hand — the fence sampled before the load, `bestEffort` around
- * every tier call, the expiry — is `createCacheStack`'s, which is the point: there was one read
+ * every tier call, the expiry — is `cacheStack`'s, which is the point: there was one read
  * cache too many, and the one that lived here was in no registry, so `invalidateTags` could not
  * reach it. A relative `ttlMs` and never an absolute expiry: the tier's own clock decides when
  * the entry dies, so a tier registered with a frozen clock is drivable end to end.

package/src/client.ts

@@ -11,15 +11,14 @@
  * transport, its rows adopted into the page's store, so the return type is the rows either way.
  *
  * `ClientFlight` is a TYPE here and never a value: dedup, retry, the deadline and the fence are
- * `@ultimat3/core`'s `client-flight.ts`, and a caller that never calls `createClientFlight` does
+ * `@ultimat3/core`'s `client-flight.ts`, and a caller that never calls `clientFlight` does
  * not pay a byte for any of them — an `import type` is erased and the value import would not be.
  */
 
 import type { ClientFlight, ClientRetry } from '@ultimat3/core';
 import type { FetchLike, RecordEnvelope } from '@ultimat3/core/page';
-import { clientTransport, isJsonObject } from '@ultimat3/core/page';
+import { clientTransport, isJsonObject, queryPath } from '@ultimat3/core/page';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
-import { derivePath } from './naming';
 import type { PageControls } from './page-controls';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 import type { Page } from './pagination';
@@ -33,7 +32,7 @@ export interface QueryClientOptions {
   readonly fetch?: FetchLike;
   readonly headers?: Readonly<Record<string, string>>;
   /**
-   * Opt-in flight control for every read this client makes — `createClientFlight({ principal })`.
+   * Opt-in flight control for every read this client makes — `clientFlight({ principal })`.
    * Absent, a read is one dispatch and nothing else, which is what every caller written before
    * this option existed already gets.
    */
@@ -183,7 +182,7 @@ function read(
   const search = searchOf(input, page);
   return clientTransport({
     method: 'GET',
-    url: `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`,
+    url: `${base}${queryPath(name)}${search === '' ? '' : `?${search}`}`,
     // The trace and budget are the transport's, from its server-side outbound slot, placed
     // before these so an explicit `traceparent` still wins; a browser bundles none of it.
     ...(options.headers === undefined ? {} : { headers: options.headers }),
@@ -203,6 +202,9 @@ function read(
  * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
  * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
  * split at `_first=` to recover the read underneath.
+ *
+ * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
+ * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
  */
 function searchOf(input: unknown, page?: PageControls): string {
   const params = new URLSearchParams();
@@ -211,7 +213,7 @@ function searchOf(input: unknown, page?: PageControls): string {
       const value = input[key];
       if (value === undefined || value === null) continue;
       for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
-        params.append(key, typeof item === 'object' ? JSON.stringify(item) : String(item));
+        params.append(key, wireText(item));
       }
     }
   }
@@ -221,3 +223,14 @@ function searchOf(input: unknown, page?: PageControls): string {
   }
   return params.toString();
 }
+
+/**
+ * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
+ * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
+ * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
+ * as the text it prints and the read's own schema says what is wrong with it.
+ */
+function wireText(item: unknown): string {
+  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
+  return typeof item === 'object' ? JSON.stringify(item) : String(item);
+}

package/src/column-kinds.ts

@@ -0,0 +1,28 @@
+// Single responsibility: the DECLARED kind of each column of the relation a read names. Postgres
+// compares two values by their column's type, so every comparison this package makes asks here
+// first and hands the answer to `@ultimat3/entity`'s comparator — never `typeof` the value.
+
+import type { ColumnKind } from '@ultimat3/entity';
+import { entityForTable } from '@ultimat3/entity';
+
+/** A column's declared kind, or `undefined` when nothing declares one. */
+export type KindOf = (column: string) => ColumnKind | undefined;
+
+const UNDECLARED: KindOf = () => undefined;
+
+/**
+ * The kinds of `QueryShape.entity`'s columns. Resolved once per read, sort or change event — the
+ * registry is a scan — and never per comparison.
+ *
+ * A relation no entity declares (`from('report', rows)` over a projection) has no kinds: its
+ * values compare as `@ultimat3/entity` compares an undeclared column, by what they are. `money` is
+ * two physical columns behind one property, so the property alone names no single value to order.
+ */
+export function kindsOf(relation: string): KindOf {
+  const columns = entityForTable(relation)?.$columns;
+  if (columns === undefined) return UNDECLARED;
+  return (column) => {
+    const kind = Object.hasOwn(columns, column) ? columns[column]?.$meta.kind : undefined;
+    return kind === 'money' ? undefined : kind;
+  };
+}

package/src/cursor-value.ts

@@ -1,11 +1,11 @@
 // Single responsibility: what a sort value becomes inside a cursor, and what it becomes again on
 // the way out. The codec is `@ultimat3/core`'s and it is JSON, so a `Date` went in and an ISO
-// STRING came back: `isAfterKey` then compared `"1769904000000"` against `"2026-02-01T…"` through
-// `compareValues`' string branch and page two came back empty. A `bigint` was worse — a bare
+// STRING came back: `isAfterKey` then compared `"1769904000000"` against `"2026-02-01T…"` as
+// text and page two came back empty. A `bigint` was worse — a bare
 // `TypeError` out of `JSON.stringify`, with no code and no fix.
 //
 // `@ultimat3/entity`'s `cursor.ts` solves the same problem by reading the column's declared kind.
-// A `query` has no column kinds — `QueryShape.orderBy` is a name and a direction — so the value
+// A read over a relation NO entity declares has no kinds to read (`column-kinds.ts`), so the value
 // carries its own tag instead. Self-describing, which is also what makes the revive total: nothing
 // here has to know which read minted the cursor.
 

package/src/errors.ts

@@ -9,8 +9,8 @@ import type { SurfaceDenial } from '@ultimat3/policy';
 // no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x answered
 // 404, host included, on every read this package has ever refused.
 
-/** One class, one code: core owns the cursor codec, so core owns `X_CURSOR_INVALID`. */
-export { CursorInvalidError } from '@ultimat3/core';
+// `CursorInvalidError` is core's and imported from there: core owns the cursor codec, so core
+// owns `X_CURSOR_INVALID` and its one import path.
 
 /** Titles for the framework-wide code table — every one of them owned by this package. */
 const OWNED_TITLES: Readonly<Record<string, string>> = {
@@ -28,6 +28,9 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   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',
   X_QUERY_SINGLE_INVALID: 'a query declares single: as something other than a boolean',
+  X_QUERY_AUDIT_SINK_MISSING: 'a query declares audit: true and no audit sink is installed',
+  X_QUERY_AUDIT_SINK_FAILED:
+    'an audited read was refused because the audit sink rejected its record',
 };
 
 /**
@@ -74,7 +77,7 @@ function denialReason(denial: SurfaceDenial): string {
 }
 
 /**
- * An authz denial from `guard()`. The code and reason come from the policy
+ * An authz denial from `guardQuery()`. The code and reason come from the policy
  * decision — this package never invents an authz code — and the surface-shaped
  * denial rides along so a live socket can close with 4403 rather than a 403 body.
  */

package/src/facade.ts

@@ -1,16 +1,16 @@
 /**
- * The fluent surface: every projection reachable as a method on the query itself,
- * `orgFeed.tool()` rather than `toQueryTool(orgFeed)`, and every declared field
- * lifted off `def` so app code never reaches through `.def`. The projection
- * functions stay exported for the framework's own call sites — this file only
- * binds them to the query, it never re-implements one.
+ * The fluent surface: every projection this package owns reachable as a method on the query
+ * itself, `orgFeed.live(input)` rather than `toLiveQuery(orgFeed, input)`, and every declared
+ * field lifted off `def` so app code never reaches through `.def`. The projection functions stay
+ * exported for the framework's own call sites — this file only binds them to the query, it never
+ * re-implements one. There is no `.tool()`: the MCP tool is `@ultimat3/mcp`'s one projection
+ * (`toolFrom(orgFeed)`), a tier this package cannot import.
  */
 
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryClientMethodOf } from './client';
 import { queryClientMethodFor } from './client';
 import { toLiveQuery } from './live';
-import { toQueryTool } from './mcp-tool';
 import { paginate } from './pagination';
 import type { Query, QueryDef, QueryFacade } from './query';
 import { queryName, runQuery } from './read';
@@ -45,7 +45,6 @@ export function facadeFor<
     // signed cursor is only reachable through the query that issued it.
     page: (input, args) => paginate(self(), input, args),
     live: (input, options) => toLiveQuery(self(), input, options),
-    tool: () => toQueryTool(self()),
     // One implementation for both wire shapes: the route decides the body, the transport parses
     // it, and only the TYPE differs — a single read's method answers the row, and has no `page`.
     client: (options) =>

package/src/http.ts

@@ -6,28 +6,24 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
-import { toBucket } from '@ultimat3/http';
+import type { Deprecation } from '@ultimat3/core';
+import { queryPath, recordDeprecatedCall, renderDeprecation, useContext } from '@ultimat3/core';
+import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
+import { publishRateLimit, toBucket } from '@ultimat3/http';
+import { admitsAnonymous, policyCapability } from '@ultimat3/policy';
 import { coerceQuery } from '@ultimat3/schema';
-import type { Deprecation } from './deprecation';
-import { recordDeprecatedCall, renderDeprecation } from './deprecation';
-import {
-  QueryDeprecationInvalidError,
-  QueryInputInvalidError,
-  QueryRowNotFoundError,
-} from './errors';
-import { derivePath } from './naming';
+import { QueryDeprecationInvalidError, QueryInputInvalidError } from './errors';
+import { absentArraysOf } from './input-shape';
 import { PAGE_FIRST_KEY, pageControlsOf } from './page-controls';
-import { admitsAnonymous, policyCapability } from './policy-gate';
-import type { AnyQuery } from './query';
+import type { AnyQuery, QueryRateLimit } from './query';
 import { queryName, runQuery } from './read';
 import { recordAnswerFor, recordRowAnswerFor } from './record-answer';
+import { oneRowOf } from './single-answer';
 
 /**
  * `liveFeed` -> `GET /_x/query/live-feed`. Named for the primitive rather than spelled
  * `toRoute`, because a host mounts this beside `@ultimat3/action`'s and an alias at the
- * import site is a name the reader has to hold — the same reason the tool projection
- * here is `toQueryTool`.
+ * import site is a name the reader has to hold.
  */
 export function toQueryRoute(target: AnyQuery): Route {
   const name = queryName(target);
@@ -62,8 +58,16 @@ export function toQueryRoute(target: AnyQuery): Route {
     //
     // The two page controls come OUT first (`page-controls.ts`): they are the route's, not the
     // read's, and a schema that refused unknown keys would otherwise refuse every paged call.
+    // The read spends its declared limit itself (`spendReadLimit`, on every surface), keyed on
+    // this request's address for an anonymous reader, and hands the decision back for the headers.
+    const spending = {
+      surface: 'http',
+      clientAddress: request.ctx.ip,
+      onRateLimit: (decision: RateLimitDecision) =>
+        publishRateLimit(request.ctx, decision, useContext().now().getTime()),
+    } as const;
     const { input: values, page } = pageControlsOf(name, request.queryRaw());
-    const input = coerceQuery(target.input, values);
+    const input = absentArraysOf(target.input, coerceQuery(target.input, values));
     if (target.single === true) {
       // Refused, not ignored: a caller paging a read of one object has the wrong read in mind, and
       // a silently dropped `_first` would answer a shape it did not ask for.
@@ -75,21 +79,18 @@ export function toQueryRoute(target: AnyQuery): Route {
       }
       // The first row — what every in-process `[0]` of the same read already takes. None is the
       // 404 a detail URL means, where a list read answers `200 []`.
-      const [row] = await runQuery(target, input, { surface: 'http' });
-      if (row === undefined) throw new QueryRowNotFoundError(name);
-      return answerRow(row);
+      return answerRow(oneRowOf(name, await runQuery(target, input, spending)));
     }
     // With a page control the answer is the `Page` envelope `query.page()` answers a server
-    // caller with — `{ rows, nextCursor, hasMore, endCursor, hasNextPage }`, the same names (the
-    // last two aliases of the first two), so a cursor read off the
+    // caller with — `{ rows, nextCursor, hasMore }`, the same names, so a cursor read off the
     // wire and one read off a direct call are the same string in the same field. Without one the
     // answer is the bare array it has always been: every client written before the controls
-    // existed keeps reading rows, and `hasNextPage` never rides on a row where a page marker
-    // has no business being.
+    // existed keeps reading rows, and `hasMore` never rides on a row where a page marker has no
+    // business being.
     return answer(
       page === undefined
-        ? await runQuery(target, input, { surface: 'http' })
-        : await target.page(input, { ...page, surface: 'http' }),
+        ? await runQuery(target, input, spending)
+        : await target.page(input, { ...page, ...spending }),
     );
   };
 
@@ -106,6 +107,9 @@ export function toQueryRoute(target: AnyQuery): Route {
     // rule reads (`ownsOrg(actor, input.orgId)`); the stage would decide the same policy
     // from raw strings, and would need an `authorize` hook wired to decide at all.
     enforcedBy: 'handler',
+    // Which primitive this is, for `@ultimat3/http`'s bucket check (a bucket named after a query
+    // limits nothing since 25.0.0, and is refused rather than ignored).
+    primitive: 'query',
     // `input` stays absent, deliberately: the pipeline's body stage validates `meta.input`
     // against the BODY, and a GET has none — declaring it would fail every read on an
     // absent body before the handler ran. The schema is not skipped, it is applied in the
@@ -118,23 +122,29 @@ export function toQueryRoute(target: AnyQuery): Route {
     // ride along so a purge can still name the read the tier keys by.
     cache: { mode: 'no-store', tags: tagKeys(target.cache?.tags ?? []) },
     tags: ['query'],
-    // Name AND numbers, exactly as an action's route sets them — the name alone selects a bucket
-    // the limiter's table never held, so `bucketFor` falls through to `default` (120 burst, 2/s)
-    // and a read declaring 5 runs on 120. `withRouteBuckets` registers the pair at construction.
-    // `toBucket` is `@ultimat3/http`'s: the limiter owns the maths, and a copy here would be a
-    // second conversion able to publish numbers the limiter refuses.
+    // The read spends its own declared bucket on every surface (`read.ts`), so the stage spends
+    // no caller bucket here: not this one (the old HTTP-only enforcement point the MCP tool never
+    // reached), and not `default` (a ceiling a read declaring more than it never had). The tenant
+    // allowance stays the stage's. Refused at mount, never on the first read, when the pair is one
+    // the limiter cannot run on: `toBucket` is `@ultimat3/http`'s, so the numbers cannot drift.
     ...(target.rateLimit === undefined
       ? {}
-      : { rateLimit: name, rateLimitBucket: toBucket(name, target.rateLimit) }),
+      : { rateLimitedBy: rateLimitedByHandler(name, target.rateLimit) }),
     ...(target.mcp?.description === undefined ? {} : { description: target.mcp.description }),
   };
 
-  return { method: 'GET', path: derivePath(name), handler, meta };
+  return { method: 'GET', path: queryPath(name), handler, meta };
+}
+
+/** Validates the declaration through the limiter's own conversion, then hands the route its flag. */
+function rateLimitedByHandler(name: string, limit: QueryRateLimit): 'handler' {
+  toBucket(name, limit);
+  return 'handler';
 }
 
 /**
  * The headers this read's `deprecated:` block renders to, or nothing. The successor's URL comes
- * from `derivePath` — the same derivation `client()` uses, never a second one.
+ * from `queryPath` — the same derivation `client()` uses, never a second one.
  */
 function deprecationHeadersFor(
   name: string,
@@ -142,7 +152,7 @@ function deprecationHeadersFor(
 ): Readonly<Record<string, string>> | undefined {
   if (deprecated === undefined) return undefined;
   const successor =
-    deprecated.replacedBy === undefined ? undefined : derivePath(deprecated.replacedBy);
+    deprecated.replacedBy === undefined ? undefined : queryPath(deprecated.replacedBy);
   const rendered = renderDeprecation(deprecated, successor);
   if (!rendered.ok) throw new QueryDeprecationInvalidError(name, rendered.field, rendered.value);
   return rendered.headers;