@ultimat3/query 24.0.0 → 25.0.0

package/src/live.ts

@@ -12,9 +12,11 @@ import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Patch } from './matcher';
 import { assertMatchable } from './matcher';
 import type { QueryPolicy, QuerySubject } from './policy-gate';
-import { guard } from './policy-gate';
-import type { Query } from './query';
+import { guardQuery } from './policy-gate';
+import type { AnyQuery, Query } from './query';
 import { queryHash } from './query';
+import type { QueryLimitCaller } from './rate-limit-gate';
+import { spendReadLimit } from './rate-limit-gate';
 import { queryName, sourceFor } from './read';
 import { assertNoSealedKey } from './sealed-shape';
 import type { QueryShape, SeekKey } from './shape';
@@ -103,6 +105,20 @@ export interface ToLiveOptions {
 const SHARED_WINDOW_REASON =
   'the shared subject-less window has no subscriber to decide about; authorize() runs per subscriber';
 
+/**
+ * A live SUBSCRIBE's spend of the read's declared `rateLimit:` — the bucket the HTTP route, a paged
+ * read and the MCP tool spend. Its own export because the subscribe is realtime's: the sync node
+ * builds one shared window per `(query, input)` with no subscriber (`enforce: false`, which spends
+ * nothing) and calls this once per subscriber, beside `authorize`. Never on a re-authorization:
+ * the subscription it already holds was paid for.
+ */
+export function spendQueryLimit(
+  target: AnyQuery,
+  caller: Omit<QueryLimitCaller, 'surface'>,
+): Promise<void> {
+  return spendReadLimit(queryName(target), target.rateLimit, { ...caller, surface: 'live' });
+}
+
 /** Changing the build changes the epoch, which forces reconnects to refetch. */
 export function liveEpoch(): string {
   return Bun.env['X_BUILD_ID'] ?? 'dev';
@@ -148,7 +164,7 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
     limit: shape.limit,
     execute: () => source.execute(),
     authorize: async (subject) => {
-      guard(policy, subject, 'live');
+      guardQuery(policy, subject, 'live');
     },
     initialCursor: (rows) => ({
       epoch,

package/src/openapi.ts

@@ -16,13 +16,17 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
-import { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from '@ultimat3/core';
+import {
+  isMcpExposed,
+  queryPath,
+  RECORDS_OPENAPI_HEADER,
+  recordEnvelopeSchema,
+} from '@ultimat3/core';
+import { MAX_PAGE_SIZE } from '@ultimat3/entity';
+import { policyCapability } from '@ultimat3/policy';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
-import { isExposed } from './mcp-tool';
-import { derivePath } from './naming';
-import { MAX_PAGE_SIZE, PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
-import { policyCapability } from './policy-gate';
+import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import type { AnyQuery } from './query';
 import { queryName } from './read';
 import { answersRecords } from './record-answer';
@@ -48,19 +52,22 @@ const ANSWERS: readonly Record<string, unknown>[] = [
   { type: 'array', items: {} },
   {
     type: 'object',
-    // `nextCursor`/`hasMore` are the preferred names; the other two are the same values, kept as
-    // aliases — documented as such, not deprecated — so every client written against them reads on.
-    required: ['rows', 'nextCursor', 'hasMore', 'endCursor', 'hasNextPage'],
+    // The one page shape: the `endCursor`/`hasNextPage` alias pair left in 25.0.0 (O-12).
+    required: ['rows', 'nextCursor', 'hasMore'],
     properties: {
       rows: { type: 'array', items: {} },
       nextCursor: {
         type: ['string', 'null'],
-        description: `the signed cursor that continues this listing — send it as ${PAGE_AFTER_KEY}; null on an empty page`,
+        description: `the signed cursor for the next page — send it as ${PAGE_AFTER_KEY}; null exactly when hasMore is false`,
       },
       hasMore: { type: 'boolean', description: 'whether another page follows' },
-      endCursor: { type: ['string', 'null'], description: 'alias of nextCursor — the same value' },
-      hasNextPage: { type: 'boolean', description: 'alias of hasMore — the same value' },
     },
+    // `@ultimat3/core`'s `Page` is a union, and so is its wire shape: the two facts cannot
+    // disagree in a body this document validates (25.0.0 — the last page used to keep a cursor).
+    oneOf: [
+      { properties: { nextCursor: { type: 'string' }, hasMore: { const: true } } },
+      { properties: { nextCursor: { type: 'null' }, hasMore: { const: false } } },
+    ],
   },
 ];
 
@@ -70,7 +77,7 @@ export function queryOpenApiPaths(
 ): Record<string, OpenApiPathItem> {
   const paths: Record<string, OpenApiPathItem> = {};
   for (const target of [...queries].sort(compareByName)) {
-    paths[derivePath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
+    paths[queryPath(queryName(target))] = { get: toQueryOpenApiOperation(target) };
   }
   return paths;
 }
@@ -117,9 +124,9 @@ export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknow
       capability: policyCapability(target.policy),
       live: target.isLive,
       cacheTags: tagKeys(target.cache?.tags ?? []),
-      // The same rule `toMcpTool` and the action side apply: a tool is advertised only where the
-      // MCP catalog lists one, under the export name verbatim (`mcp-tool.ts`).
-      tool: isExposed(target) ? name : null,
+      // Core's one predicate, the one `@ultimat3/mcp`'s catalog and the action side ask: a tool is
+      // advertised only where the MCP catalog lists one, under the export name verbatim.
+      tool: isMcpExposed(target.mcp) ? name : null,
     },
   };
 }
@@ -156,7 +163,7 @@ function singleOperation(target: AnyQuery, name: string): Record<string, unknown
       live: target.isLive,
       single: true,
       cacheTags: tagKeys(target.cache?.tags ?? []),
-      tool: isExposed(target) ? name : null,
+      tool: isMcpExposed(target.mcp) ? name : null,
     },
   };
 }
@@ -177,7 +184,7 @@ const PAGE_PARAMETERS: readonly Record<string, unknown>[] = [
     name: PAGE_AFTER_KEY,
     in: 'query',
     required: false,
-    description: `the nextCursor (alias endCursor) a previous page answered; needs ${PAGE_FIRST_KEY}`,
+    description: `the nextCursor a previous page answered; needs ${PAGE_FIRST_KEY}`,
     schema: { type: 'string' },
   },
 ];

package/src/page-controls.ts

@@ -11,21 +11,17 @@
 // the framework's own namespace mark — the route lives under `/_x/` for the same reason — and
 // `input-shape.ts` refuses a declaration that reaches for it, so the two names can never collide.
 
+import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { QueryInputInvalidError } from './errors';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 
 export { PAGE_AFTER_KEY, PAGE_FIRST_KEY };
 export const PAGE_CONTROL_KEYS: readonly string[] = [PAGE_FIRST_KEY, PAGE_AFTER_KEY];
 
-/**
- * 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 `paginate` 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. Lives here rather than in `pagination.ts` because the
- * route validates against it BEFORE `paginate` runs — see `pageControlsOf`.
- */
-export const MAX_PAGE_SIZE = 10_000;
+// The largest page a read will serve is `@ultimat3/entity`'s `MAX_PAGE_SIZE`, imported — a batch
+// and a page are one memory bound, and this package already depends on entity. `first` reaches
+// `paginate` straight from a route parameter, so the route judges it against that bound BEFORE
+// `paginate` runs (`pageControlsOf`), and one request can never ask for five million rows.
 
 /** What the route hands `query.page()` — `PaginateArgs` minus the server-side options. */
 export interface PageControls {

package/src/page-keys.ts

@@ -5,5 +5,5 @@
 
 /** `?_first=20` — the page size. Present is what makes the route answer a `Page`. */
 export const PAGE_FIRST_KEY = '_first';
-/** `?_after=<cursor>` — the signed cursor the previous page's `endCursor` carried. */
+/** `?_after=<cursor>` — the signed cursor the previous page's `nextCursor` carried. */
 export const PAGE_AFTER_KEY = '_after';

package/src/pagination.ts

@@ -9,44 +9,27 @@
  * 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 { assert, decodeCursor, encodeCursor } from '@ultimat3/core';
+import type { CursorPayload, Page } from '@ultimat3/core';
+import { assert, CursorInvalidError, decodeCursor, encodeCursor, pageOf } from '@ultimat3/core';
+import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { kindsOf } from './column-kinds';
 import { reviveSortKey, serializeSortValue } from './cursor-value';
-import { CursorInvalidError } from './errors';
-import { MAX_PAGE_SIZE } from './page-controls';
 import type { Query, SourceOptions } from './query';
-import { queryHash, queryName, sourceFor } from './query';
+import { queryHash, queryName } from './query';
+import { readCall } from './read';
 import type { QueryShape, SeekKey } from './shape';
 import { compareRows, seekKeyOf, totalOrder } from './shape';
 import type { SqlSource } from './source';
 import { isAfterKey } from './source';
 
 /**
- * One page. `nextCursor` / `hasMore` are the preferred names; `endCursor` / `hasNextPage` are the
- * same two values under the names every client before 22.12 reads — aliases, both always present,
- * never able to disagree because `pageOf` is the one place that writes them.
+ * One page is `@ultimat3/core`'s `Page` — the framework's ONE page shape (O-12, 25.0.0), the same
+ * type `@ultimat3/entity`'s `findMany` answers, re-exported so a `query` file needs one import.
+ * `nextCursor` is `null` exactly when `hasMore` is false: before 25.0.0 this page kept a cursor on
+ * its LAST page, so a `while (page.nextCursor)` loop fetched an empty page past the end.
  */
-export interface Page<TRow> {
-  readonly rows: readonly TRow[];
-  /** The signed cursor that continues this listing; `null` on an empty page. */
-  readonly nextCursor: string | null;
-  /** Whether another page follows. */
-  readonly hasMore: boolean;
-  /** Alias of `nextCursor`. */
-  readonly endCursor: string | null;
-  /** Alias of `hasMore`. */
-  readonly hasNextPage: boolean;
-}
-
-/** Builds a `Page` from its two facts — the only constructor, so the aliases cannot drift. */
-export function pageOf<TRow>(
-  rows: readonly TRow[],
-  nextCursor: string | null,
-  hasMore: boolean,
-): Page<TRow> {
-  return { rows, nextCursor, hasMore, endCursor: nextCursor, hasNextPage: hasMore };
-}
+export type { Page } from '@ultimat3/core';
 
 export interface PaginateArgs extends SourceOptions {
   readonly first: number;
@@ -72,7 +55,18 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   // 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 base = await sourceFor(target, input, args);
+  // One call: an audited read's record covers the build AND the page it serves — the early return
+  // below included, since a caller refused nothing and was answered (`audit-gate.ts`).
+  return readCall(target, input, args, (base) => pageFrom<TRow>(base, decoded, args.first, hash));
+}
+
+/** The page itself, over a source `readCall` already validated, authorized and built. */
+async function pageFrom<TRow extends object>(
+  base: SqlSource<object>,
+  decoded: CursorPayload | null,
+  first: number,
+  hash: string,
+): Promise<Page<TRow>> {
   const shape = base.shape();
   // Revived to the types the columns hold, never left as the strings JSON handed back: a `Date`
   // key decoded as an ISO string was compared as text against the row's own instant, so page two
@@ -81,25 +75,30 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
   const after = resumed?.seek ?? null;
   const left = rowsLeft(shape.limit, resumed);
   // The whole of a declared limit is already served: there is no row to ask the source for.
-  if (left === 0) return pageOf<TRow>([], null, false);
+  if (left === 0) return pageOf<TRow>([], null);
 
-  // `MAX_PAGE_SIZE` lives in `page-controls.ts`: the route checks the same bound at the wire, as
+  // `MAX_PAGE_SIZE` is `@ultimat3/entity`'s: `page-controls.ts` checks the same bound at the wire, as
   // a 400, before this `assert` — which is a 500 — can see the number.
-  // Fetch one extra row: its presence *is* `hasNextPage`, with no count query. Never past what a
+  // Fetch one extra row: its presence *is* `hasMore`, with no count query. Never past what a
   // declared `.limit()` has left — `first` used to REPLACE that limit, so `?_first=10000` walked a
   // "top 3" to the end of the table.
-  const window = Math.min(left, args.first + 1);
+  const window = Math.min(left, first + 1);
   const source: SqlSource<object> = base.seek === undefined ? base : base.seek(after, window);
   const executed = await source.execute();
   const scoped =
     base.seek === undefined ? inTotalOrder(executed, after, shape).slice(0, window) : executed;
   // The source came from this query's own `sql()`, so its rows are TRow.
-  const rows = scoped.slice(0, args.first) as unknown as readonly TRow[];
+  const rows = scoped.slice(0, first) as unknown as readonly TRow[];
   const last = rows[rows.length - 1];
+  // Read on EVERY page with a row, the last included: a read with no id is refused as unpageable
+  // on page one, never only once its listing grows past one page.
   const seek = last === undefined ? null : seekKeyOf(last, shape);
 
+  // A cursor is minted only when another page follows (the extra row arrived): the position of the
+  // last row of the LAST page is not a next page, and handing it back made a
+  // `while (page.nextCursor)` loop fetch an empty page past the end.
   const nextCursor =
-    seek === null
+    seek === null || scoped.length <= first
       ? null
       : encodeCursor({
           scope: hash,
@@ -113,7 +112,7 @@ export async function paginate<TInput extends StandardSchemaV1, TRow extends obj
           ],
           id: String(seek.id),
         });
-  return pageOf(rows, nextCursor, scoped.length > args.first);
+  return pageOf(rows, nextCursor);
 }
 
 /** A decoded cursor: where the page resumes, and how many rows of a declared limit are spent. */

package/src/policy-gate.ts

@@ -5,20 +5,20 @@
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assertNever, isAnonymous } from '@ultimat3/core';
+import { assertNever } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import {
-  enforce,
-  enforceBeforeInput,
-  policyPermissions as flattenedPermissions,
-  admitsAnonymous as policyAdmitsAnonymous,
-} from '@ultimat3/policy';
+import { enforce, enforceBeforeInput } from '@ultimat3/policy';
 import { QueryDeniedError } from './errors';
 
 /** Policies are opaque here: we evaluate them, we never introspect their rules. */
 export type QueryPolicy = Policy<unknown>;
 
-export type QuerySurface = 'server' | 'http' | 'live';
+/**
+ * Where a read came from. `'mcp'` is an agent's tool call — named so a declared `rateLimit:`
+ * spends for it (`'server'`, in-process app code, does not) — and is judged by the policy exactly
+ * as `'server'` always judged it, so no MCP read's authz answer moved.
+ */
+export type QuerySurface = 'server' | 'http' | 'live' | 'mcp';
 
 export interface QuerySubject {
   readonly actor: Actor | null;
@@ -33,7 +33,11 @@ export interface QuerySubject {
   readonly query: string;
 }
 
-export function guard(policy: QueryPolicy, subject: QuerySubject, surface: QuerySurface): void {
+export function guardQuery(
+  policy: QueryPolicy,
+  subject: QuerySubject,
+  surface: QuerySurface,
+): void {
   const denial = enforce(policySurface(surface), policy, {
     input: subject.input,
     actor: subject.actor,
@@ -44,11 +48,11 @@ export function guard(policy: QueryPolicy, subject: QuerySubject, surface: Query
 }
 
 /**
- * The actor-only half of `guard`, run BEFORE the input is parsed — the twin of
+ * The actor-only half of `guardQuery`, run BEFORE the input is parsed — the twin of
  * `@ultimat3/action`'s. A reader the policy refuses whatever they send is answered 403 (or 401),
- * never `X_INPUT_INVALID` with the read's input schema in it. Undecided passes to `guard`.
+ * never `X_INPUT_INVALID` with the read's input schema in it. Undecided passes to `guardQuery`.
  */
-export function guardBeforeInput(
+export function guardQueryBeforeInput(
   policy: QueryPolicy,
   subject: Omit<QuerySubject, 'input' | 'row'>,
   surface: QuerySurface,
@@ -68,45 +72,9 @@ function policySurface(surface: QuerySurface): PolicySurface {
     case 'live':
       return 'live';
     case 'server':
+    case 'mcp':
       return 'job';
     default:
       return assertNever(surface);
   }
 }
-
-/**
- * Core models "nobody" as an anonymous actor; policy models it as `null`, which is
- * what turns a missing session into `X_UNAUTHENTICATED` instead of a bare denial.
- */
-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. 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);
-}
-
-/**
- * Whether a policy admits an ANONYMOUS caller — `@ultimat3/policy`'s answer, re-exported here so
- * `http.ts` reads it through this file like every other authz question. `toQueryRoute` derives
- * `meta.auth` from it, never from `policy.kind === 'allow'`: that read looked at the ROOT
- * combinator only, so `or(allow(), can('x:y'))` was 401'd by the pipeline before `runQuery` ran
- * while the MCP tool and a direct server read allowed it. `true` is `meta.auth` only — the read is
- * still `no-store` and `runQuery` still evaluates the policy per caller. Declared once in
- * `policy.ts`, exactly as `policyPermissions` is: the answer is a property of the combinators.
- */
-export function admitsAnonymous(policy: QueryPolicy): boolean {
-  return policyAdmitsAnonymous(policy);
-}

package/src/query.ts

@@ -8,20 +8,19 @@
 
 import type { CacheTag } from '@ultimat3/cache';
 import { tagKeys } from '@ultimat3/cache';
-import type { Actor, Ctx } from '@ultimat3/core';
+import type { Actor, Ctx, Deprecation, McpExposureDeclaration } from '@ultimat3/core';
 import { fingerprint } from '@ultimat3/core';
+import type { RateLimitDecision } from '@ultimat3/http';
+import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import type { QueryCacheScope } from './cache';
 import type { QueryClientMethodOf, QueryClientOptions } from './client';
-import type { Deprecation } from './deprecation';
 import { QueryCacheTtlInvalidError, QuerySingleInvalidError } 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, policyPermissions } from './policy-gate';
 import { hasDef, queryName, runQuery, stashDef } from './read';
 import type { SqlSource } from './source';
 import { assertSubscribes } from './subscribes';
@@ -44,52 +43,6 @@ export interface QueryCache {
   readonly scope?: QueryCacheScope;
 }
 
-export interface QueryMcp {
-  /** Opt-in: a read reaches an agent only when it says so. Silence exposes nothing. */
-  readonly expose: boolean;
-  /** Contract text, not UI text — see `ActionMcp.description` for why it stays outside `t()`. */
-  readonly description?: string;
-  /**
-   * Roles that may SEE the projected tool — a catalog audience, not an authz rule; the `policy`
-   * still decides every call. A caller whose role is not named gets ToolNotFound, never
-   * Forbidden. See `ActionMcp.visibleTo`, which this mirrors exactly.
-   */
-  readonly visibleTo?: readonly string[];
-  /**
-   * The list whitelist an MCP meta surface composes over (`@ultimat3/mcp` `McpListParams`):
-   * `filters` field → operators, sortable `sort` fields, pickable `fields`, `maxLimit`. Flat keys:
-   * the query's own `input` declares `status_eq`, `sort`, `fields`, `cursor`, `limit` and
-   * implements them; `manage_resource` refuses anything outside the whitelist before it runs.
-   */
-  readonly listParams?: QueryListParams;
-  /** The tool's display name in an MCP client. See `ActionMcp.title`. */
-  readonly title?: string;
-  /**
-   * MCP tool annotations, overriding the derived `readOnlyHint: true` key by key — `openWorldHint:
-   * true` for a read that reaches outside the app. See `ActionMcp.annotations`.
-   */
-  readonly annotations?: QueryMcpAnnotations;
-}
-
-/** Structural twin of `@ultimat3/action`'s `McpAnnotationHints` (siblings cannot import). */
-export interface QueryMcpAnnotations {
-  readonly readOnlyHint?: boolean;
-  readonly destructiveHint?: boolean;
-  readonly idempotentHint?: boolean;
-  readonly openWorldHint?: boolean;
-}
-
-/** One comparison a list filter accepts. A filter key is `<field><op>`: `status_eq`. */
-export type QueryListFilterOp = '_eq' | '_in' | '_gt' | '_lt' | '_cont';
-
-/** Structural twin of `@ultimat3/mcp`'s `McpListParams` (tier 3 cannot import tier 4). */
-export interface QueryListParams {
-  readonly filters?: Readonly<Record<string, readonly QueryListFilterOp[]>>;
-  readonly sort?: readonly string[];
-  readonly fields?: readonly string[];
-  readonly maxLimit?: number;
-}
-
 /**
  * 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
@@ -147,7 +100,7 @@ export interface QueryDef<
   readonly rows?: StandardSchemaV1<unknown, TRow>;
   sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
   readonly cache?: QueryCache;
-  readonly mcp?: QueryMcp;
+  readonly mcp?: McpExposureDeclaration;
   /** Burst and refill for THIS read's route, in the limiter's own vocabulary. */
   readonly rateLimit?: QueryRateLimit;
   /**
@@ -158,6 +111,13 @@ export interface QueryDef<
    * router feature; see the README.
    */
   readonly deprecated?: Deprecation;
+  /**
+   * Record every call through the installed `AuditSink` (`@ultimat3/core`'s, the one an action's
+   * `audit: true` writes to) — allowed, denied and failed, and a memo or cache hit too: an audit of
+   * a read is who saw what, not what was computed. Off unless declared; no sink installed is
+   * `X_QUERY_AUDIT_SINK_MISSING` before the input is parsed.
+   */
+  readonly audit?: boolean;
 }
 
 export interface QueryOptions {
@@ -176,6 +136,13 @@ export interface QueryOptions {
    * stays on the one read path instead of forking a second one.
    */
   readonly actor?: Actor | null;
+  /**
+   * The reader's connection address — the only rate-limit subject an anonymous reader has. The
+   * HTTP projection passes the request's; elsewhere every anonymous reader shares one bucket.
+   */
+  readonly clientAddress?: string | null;
+  /** The declared `rateLimit:` decision, before a refusal: how HTTP answers `RateLimit-*`. */
+  readonly onRateLimit?: (decision: RateLimitDecision) => void;
 }
 
 export interface SourceOptions extends QueryOptions {
@@ -239,9 +206,10 @@ export interface AnyQueryDef {
   readonly rows?: StandardSchemaV1;
   sql(input: unknown, ctx: Ctx): SqlSource<object>;
   readonly cache?: QueryCache;
-  readonly mcp?: QueryMcp;
+  readonly mcp?: McpExposureDeclaration;
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
+  readonly audit?: boolean;
 }
 
 export interface AnyQuery {
@@ -259,7 +227,7 @@ export interface AnyQuery {
   /** Lifted for the route: whether an answer is a record envelope is decided at projection. */
   readonly rows?: StandardSchemaV1;
   readonly cache?: QueryCache;
-  readonly mcp?: QueryMcp;
+  readonly mcp?: McpExposureDeclaration;
   /** Lifted so `toQueryRoute` reads the declaration without reaching through `defOf`. */
   readonly rateLimit?: QueryRateLimit;
   readonly deprecated?: Deprecation;
@@ -271,7 +239,6 @@ export interface AnyQuery {
   /** One bounded page plus the signed cursor that continues it. There is no `offset`. */
   page(input: unknown, args: PaginateArgs): Promise<Page<object>>;
   live(input: unknown, options?: ToLiveOptions): Promise<LiveQuery>;
-  tool(): QueryToolDescriptor;
 }
 
 export interface Query<
@@ -297,8 +264,6 @@ export interface Query<
    * so it lives here and not on the schema-erased `AnyQuery` view.
    */
   client(options: QueryClientOptions): QueryClientMethodOf<TInput, TRow, TSingle>;
-  /** Narrowed by the declaration: a list read's tool answers rows, a single read's one row. */
-  tool(): QueryToolDescriptor<TSingle>;
 }
 
 /** The fluent half of a query: lifted declaration plus one method per projection. */
@@ -320,7 +285,6 @@ export type QueryFacade<
   | 'as'
   | 'page'
   | 'live'
-  | 'tool'
   | 'client'
 >;
 
@@ -374,7 +338,7 @@ export function isQuery(value: unknown): value is AnyQuery {
 /**
  * Stamp the export name onto the query the app declared, rather than handing back a
  * differently-named copy of it. `import { liveFeed } from './live'` is then the query
- * that projects — `liveFeed.tool()` after boot, with nothing to remember. The same
+ * that projects — `liveFeed.client()` after boot, with nothing to remember. The same
  * rule `nameAction` follows; naming twice is the one case that still needs a twin.
  */
 export function nameQuery<Q extends AnyQuery>(target: Q, name: string): Q {

package/src/rate-limit-gate.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a read's declared `rateLimit:` is spent: once, in the read path's front half, so the HTTP
+ * route, a paged read, the MCP tool and a live subscribe draw on ONE bucket. The store is
+ * `@ultimat3/http`'s installed one — the slot `@ultimat3/action`'s `invoke` spends from too.
+ */
+
+import type { Actor } from '@ultimat3/core';
+import { isAnonymous, systemClock } from '@ultimat3/core';
+import type { RateLimitDecision } from '@ultimat3/http';
+// The bucket maths, the subject precedence and the refusal are `@ultimat3/http`'s (tier 2): a copy
+// here would be a second answer to "what does this limit mean" and "whose bucket is it".
+import { installedRateLimitStore, rateLimited, rateLimitSpends, toBucket } from '@ultimat3/http';
+import type { QuerySurface } from './policy-gate';
+import type { QueryRateLimit } from './query';
+
+/**
+ * Namespaced, never the bare query name: the HTTP stage still spends its own buckets under
+ * `<route name>|<subject>`, and one key taken against two bucket shapes corrupts both counters.
+ */
+const QUERY_SCOPE = 'query';
+
+export interface QueryLimitCaller {
+  /** Who is reading — `ctx.actor` on a read, the socket's actor on a live subscribe. */
+  readonly actor: Actor;
+  readonly surface: QuerySurface;
+  /** The connection address — the only subject an anonymous reader has. */
+  readonly clientAddress?: string | null | undefined;
+  /** The decision, before a refusal is thrown: how HTTP puts `RateLimit-*` on the answer. */
+  readonly onRateLimit?: ((decision: RateLimitDecision) => void) | undefined;
+  /** Epoch ms from the caller's clock. Absent, the system clock. */
+  readonly nowMs?: number | undefined;
+}
+
+/**
+ * Spend one token of a read's declared limit for this caller, or throw `X_RATE_LIMITED`. Called by
+ * `read.ts`'s `buildSource` for every enforced build, and through `spendQueryLimit` (`live.ts`) by
+ * the one surface this package does not run: realtime's per-subscriber live subscribe.
+ *
+ * `surface: 'server'` spends nothing — app code reading in-process (a page's render, a service),
+ * the rule `@ultimat3/action` applies to its own `'server'` surface. A refused attempt spends
+ * nothing either: the token bucket only decrements on an admission.
+ */
+export async function spendReadLimit(
+  name: string,
+  limit: QueryRateLimit | undefined,
+  caller: QueryLimitCaller,
+): Promise<void> {
+  if (limit === undefined || caller.surface === 'server') return;
+  const actor = isAnonymous(caller.actor) ? null : caller.actor;
+  const spends = rateLimitSpends(
+    {
+      actorId: actor?.id ?? null,
+      orgId: actor?.orgId ?? null,
+      ip: caller.clientAddress ?? null,
+      routeName: `${QUERY_SCOPE}:${name}`,
+    },
+    // The tenant allowance is the HTTP pipeline's; counting it here too would charge twice.
+    { route: name, tenant: null },
+  );
+  const nowMs = caller.nowMs ?? systemClock.now().getTime();
+  for (const spend of spends) {
+    const decision = await installedRateLimitStore().take(
+      spend.key,
+      toBucket(name, limit),
+      1,
+      nowMs,
+    );
+    caller.onRateLimit?.(decision);
+    if (!decision.allowed) throw rateLimited(spend.key, decision.retryAfterSeconds);
+  }
+}