@ultimat3/query 23.0.0 → 25.0.0

package/src/pagination.ts

@@ -9,42 +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 { 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;
@@ -70,37 +55,88 @@ 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 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 : seekFromCursor(decoded, shape.orderBy.length);
+  // key decoded as an ISO string was compared as text against the row's own instant, so page two
+  // matched nothing at all. See `cursor-value.ts`.
+  const resumed = decoded === null ? null : seekFromCursor(decoded, shape.orderBy.length);
+  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);
 
-  // `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.
-  const window = args.first + 1;
+  // 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, 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) : executed;
+  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,
           // The id rides TYPED at the tail of the key — core's `id` slot is a string — so a
           // numeric or bigint tiebreak compares as a number on the next page, not lexically.
-          key: [...seek.key, seek.id].map(serializeSortValue),
+          // A limited read appends how much of its limit is now spent: a keyset cursor names a
+          // position and no count, and the count is the only thing that can end a "top N".
+          key: [
+            ...[...seek.key, seek.id].map(serializeSortValue),
+            ...(shape.limit === null ? [] : [(resumed?.served ?? 0) + rows.length]),
+          ],
           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. */
+interface Resumed {
+  readonly seek: SeekKey;
+  readonly served: number | undefined;
+}
+
+/**
+ * Rows a declared limit still allows, or no bound at all for a read that declares none.
+ *
+ * A cursor on a limited read MUST say how many rows came before it. One that does not was minted
+ * before the limit bounded the listing (or before the read declared one), and honouring it would
+ * start a fresh "top N" below the real one — so it is refused as any other cursor this read did
+ * not mint, with core's own instruction: request the first page again.
+ */
+function rowsLeft(limit: number | null, resumed: Resumed | null): number {
+  if (limit === null) return Number.POSITIVE_INFINITY;
+  if (resumed === null) return Math.max(0, limit);
+  const { served } = resumed;
+  if (served === undefined || !Number.isInteger(served) || served < 1) {
+    throw new CursorInvalidError('it does not say how much of this read’s limit is already served');
+  }
+  return Math.max(0, limit - served);
 }
 
 /**
@@ -128,20 +164,26 @@ function inTotalOrder(
   shape: QueryShape,
 ): readonly object[] {
   const keys = totalOrder(shape.orderBy);
-  const ordered = [...rows].sort((left, right) => compareRows(left, right, keys));
+  const kindOf = kindsOf(shape.entity);
+  const ordered = [...rows].sort((left, right) => compareRows(left, right, keys, kindOf));
   if (after === null) return ordered;
-  return ordered.filter((row) => isAfterKey(row, after, shape.orderBy));
+  return ordered.filter((row) => isAfterKey(row, after, shape.orderBy, kindOf));
 }
 
 /**
- * The seek a decoded cursor names. A cursor carrying one more key than the ordering has its typed
- * id at the tail; an older cursor, minted before the id rode there, falls back to the string slot.
+ * The seek a decoded cursor names. A cursor carrying more keys than the ordering has its typed id
+ * next, then — on a limited read — the count of rows served so far; an older cursor, minted before
+ * the id rode there, falls back to the string slot.
  */
 function seekFromCursor(
   decoded: { readonly key: readonly unknown[]; readonly id: string },
   width: number,
-): SeekKey {
+): Resumed {
   const key = reviveSortKey(decoded.key);
-  if (key.length !== width + 1) return { key, id: decoded.id };
-  return { key: key.slice(0, width), id: key[width] };
+  if (key.length <= width) return { seek: { key, id: decoded.id }, served: undefined };
+  const count = key[width + 1];
+  return {
+    seek: { key: key.slice(0, width), id: key[width] },
+    served: typeof count === 'number' ? count : undefined,
+  };
 }

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<
@@ -318,7 +285,6 @@ export type QueryFacade<
   | 'as'
   | 'page'
   | 'live'
-  | 'tool'
   | 'client'
 >;
 
@@ -372,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);
+  }
+}