@ultimat3/query 1.2.0 → 3.0.0

package/src/client.ts

@@ -3,11 +3,18 @@
  * the same pure derivation the server uses, so a renamed query is a compile error
  * in a Solid component rather than a 404 at runtime. Browser-safe on purpose: no
  * server imports, nothing here touches a context, a policy or a database.
+ *
+ * Rows arrive as JSON and are handed back as parsed, exactly as `rpc` does: a query declares no
+ * output schema — row types come from the `SqlSource` its `sql:` returns — so there is nothing
+ * here to rehydrate a `Date` with, and an instant reaches a caller as the ISO string
+ * `JSON.stringify` wrote. A surface that formats one converts at its own edge.
  */
 
+import { currentSpanContext, traceparent } from '@ultimat3/core';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
 import { QueryRequestFailedError } from './errors';
 import { derivePath } from './naming';
+import type { Query } from './query';
 import { isJsonObject } from './stable';
 
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
@@ -28,7 +35,57 @@ export type QueryClientMethod<TInput extends StandardSchemaV1, TRow extends obje
   options?: QueryCallOptions,
 ) => Promise<readonly TRow[]>;
 
-/** One query's method — what `query.client()` returns. */
+/**
+ * Loose constraint on purpose: a map of concrete `Query<TInput, TRow>` values must be
+ * assignable to it, while `QueryClient<T>` still recovers each read's own input schema and
+ * row type. The mirror of `@ultimat3/action`'s `ActionLike`.
+ */
+export interface QueryLike {
+  readonly kind: 'query';
+  readonly name: string;
+}
+
+export type QueryMap = Record<string, QueryLike>;
+
+/** `queries.publicPost({ slug })`, with the input schema and the row type both inferred. */
+export type QueryClient<TQueries extends QueryMap> = {
+  readonly [K in keyof TQueries]: TQueries[K] extends Query<infer TInput, infer TRow>
+    ? QueryClientMethod<TInput, TRow>
+    : never;
+};
+
+/**
+ * The typed client for a whole query map: `queryClient<Api['queries']>({ baseUrl })`, the read
+ * half of `rpc<Api['actions']>`. A surface that must not import a feature — `site/`, whose one
+ * edge into `app/` would be a boundary violation — reaches every registered read through this
+ * and the `Api` TYPE, with no module-graph edge and no codegen step.
+ *
+ * One blessed name, and one implementation underneath it: every method is
+ * `queryClientMethodFor`, so the map-wide spelling and `read.client()` can never derive
+ * different URLs for the same read.
+ */
+export function queryClient<TQueries extends QueryMap>(
+  options: QueryClientOptions,
+): QueryClient<TQueries> {
+  const proxy = new Proxy(
+    {},
+    {
+      get(_target, property: string | symbol) {
+        // `then` is answered with `undefined` for the same reason a symbol is: `await client`,
+        // `Promise.resolve(client)` and returning the client from an async function all read it,
+        // and a method there makes the client a thenable that fetches a read named "then" and
+        // resolves the await to its rows. No query may be called `then` — it is the one name the
+        // language reserves at this seam.
+        if (typeof property !== 'string' || property === 'then') return undefined;
+        return queryClientMethodFor(property, options);
+      },
+    },
+  );
+  // The proxy realizes the mapped type structurally; TS cannot check a Proxy.
+  return proxy as QueryClient<TQueries>;
+}
+
+/** One query's method — what `query.client()` returns, and what `queryClient` proxies to. */
 export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
@@ -52,7 +109,10 @@ async function read(
   const url = `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`;
   const init: RequestInit = {
     method: 'GET',
-    headers: { accept: 'application/json', ...options.headers },
+    // `traceHeaders()` before the caller's, so an explicit `traceparent` still wins. Without it a
+    // service-to-service read started a fresh root trace on the other side, and "which of my
+    // downstreams is slow" was unanswerable across every Ultimate-to-Ultimate hop.
+    headers: { accept: 'application/json', ...traceHeaders(), ...options.headers },
     ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
   };
 
@@ -63,6 +123,27 @@ async function read(
   return body;
 }
 
+/** A `traceparent` is `00-<32 hex>-<16 hex>-<2 hex>`, and nothing else may be sent as one. */
+const TRACE_ID = /^[0-9a-f]{32}$/;
+const SPAN_ID = /^[0-9a-f]{16}$/;
+
+/**
+ * The current trace, as the W3C header — or nothing at all. `currentSpanContext()` answers with
+ * an empty `spanId` when a request context exists but no span is active, and `00-<trace>--01` is
+ * a header every collector drops, so an incomplete context sends none. In a browser there is no
+ * ambient context and this is always empty, which is also what keeps a cross-origin read from
+ * acquiring a CORS preflight it did not have.
+ *
+ * `@ultimat3/action`'s client carries the twin of this function: both are tier 3, so neither may
+ * import the other — the same reason `naming.ts` is ported rather than shared.
+ */
+function traceHeaders(): Record<string, string> {
+  const context = currentSpanContext();
+  if (context === undefined) return {};
+  if (!TRACE_ID.test(context.traceId) || !SPAN_ID.test(context.spanId)) return {};
+  return { traceparent: traceparent(context) };
+}
+
 /**
  * Input as a query string. Keys are sorted so the same input always produces the
  * same URL — a GET is a cache key, and an unstable one caches nothing.

package/src/cursor-value.ts

@@ -0,0 +1,65 @@
+// 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
+// `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
+// 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.
+
+import { CursorValueUnsupportedError } from './errors';
+
+/** The two tagged forms. `$x` is a key no column value can collide with: JSON has no bigints. */
+const DATE = 'date';
+const BIGINT = 'bigint';
+
+interface TaggedValue {
+  readonly $x: typeof DATE | typeof BIGINT;
+  readonly v: string;
+}
+
+function isTagged(value: unknown): value is TaggedValue {
+  if (typeof value !== 'object' || value === null) return false;
+  const tag = (value as Record<string, unknown>)['$x'];
+  return (
+    (tag === DATE || tag === BIGINT) && typeof (value as Record<string, unknown>)['v'] === 'string'
+  );
+}
+
+/**
+ * One sort value, in a form `JSON.stringify` carries losslessly.
+ *
+ * `undefined` becomes `null` because SQL has one absence and `isNull` reads both as it — a key
+ * that encoded `undefined` would be dropped by `JSON.stringify` and shift every later key one
+ * position left, which is a cursor that seeks by the wrong column.
+ *
+ * Everything JSON cannot carry AND this cannot tag is refused HERE, where the cursor is minted:
+ * the mistake is the read's `orderBy`, and reporting it on the next request would blame a client
+ * for a declaration it never saw.
+ */
+export function serializeSortValue(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new CursorValueUnsupportedError('an Invalid Date');
+    return { $x: DATE, v: value.toISOString() } satisfies TaggedValue;
+  }
+  if (typeof value === 'bigint') return { $x: BIGINT, v: value.toString() } satisfies TaggedValue;
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  // `NaN` and `±Infinity` are `null` in JSON, which is the largest value in this framework's sort
+  // order — so an unsortable number would decode as "past every row" and end the listing.
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return value;
+    throw new CursorValueUnsupportedError(`the number ${String(value)}`);
+  }
+  throw new CursorValueUnsupportedError(`a ${typeof value}`);
+}
+
+/** The inverse, over a whole decoded key. A value that is not one of ours is handed back as is. */
+export function reviveSortKey(key: readonly unknown[]): readonly unknown[] {
+  return key.map((value) => {
+    if (!isTagged(value)) return value;
+    return value.$x === DATE ? new Date(value.v) : BigInt(value.v);
+  });
+}

package/src/deprecation.ts

@@ -0,0 +1,81 @@
+/**
+ * A declared retirement, rendered as the two headers the standards already define — RFC 9745
+ * `Deprecation` and RFC 8594 `Sunset` — plus the successor link. Pure string and date maths, and
+ * deliberately throw-free: each package raises its own `X_*` for a date it cannot render.
+ *
+ * `@ultimat3/action` carries the twin of this file. Both are tier 3, so neither may import the
+ * other, and the shared home is `@ultimat3/http` (tier 2) once that package grows one — the same
+ * compromise `naming.ts` is ported under.
+ */
+import { counter } from '@ultimat3/core';
+
+export interface Deprecation {
+  /** When it was deprecated. ISO-8601, e.g. `'2026-08-01T00:00:00Z'`. */
+  readonly since: string;
+  /** When it stops answering. ISO-8601 — the date `Sunset` publishes and clients plan against. */
+  readonly sunset: string;
+  /** The export name of the replacement, projected to a `rel="successor-version"` link. */
+  readonly replacedBy?: string;
+}
+
+export type DeprecationField = 'since' | 'sunset';
+
+export type DeprecationRender =
+  | {
+      readonly ok: true;
+      readonly headers: Readonly<Record<string, string>>;
+      /** The same facts as data, for the descriptor and the manifest. */
+      readonly meta: Readonly<Record<string, string>>;
+    }
+  | { readonly ok: false; readonly field: DeprecationField; readonly value: string };
+
+/**
+ * How many calls a deprecated declaration is still taking — the number "can we remove it yet?"
+ * needs. Attributes are the primitive and the declared NAME, both bounded by the size of the
+ * codebase; a caller id here would be an unbounded series.
+ */
+const deprecatedCalls = counter('deprecated_calls_total', {
+  unit: '{call}',
+  description: 'Calls served by a declaration that has been deprecated, by primitive and name',
+});
+
+export function recordDeprecatedCall(primitive: 'action' | 'query', name: string): void {
+  deprecatedCalls.add(1, { primitive, name });
+}
+
+/**
+ * `Deprecation` is a structured-field Date (`@` + unix seconds, RFC 9745); `Sunset` is an
+ * HTTP-date (IMF-fixdate, RFC 8594). Two spellings of one instant because two RFCs chose
+ * differently — never render one in the other's format, and never emit `Invalid Date`.
+ */
+export function renderDeprecation(
+  deprecation: Deprecation,
+  successorPath: string | undefined,
+): DeprecationRender {
+  const since = Date.parse(deprecation.since);
+  if (Number.isNaN(since)) return { ok: false, field: 'since', value: deprecation.since };
+  const sunset = Date.parse(deprecation.sunset);
+  if (Number.isNaN(sunset)) return { ok: false, field: 'sunset', value: deprecation.sunset };
+
+  const headers: Record<string, string> = {
+    deprecation: `@${Math.floor(since / 1000)}`,
+    sunset: new Date(sunset).toUTCString(),
+  };
+  // The successor's URL, derived by the caller from the same `naming.ts` the client uses — a
+  // link this file built from the export name would be the second URL derivation in the package.
+  if (successorPath !== undefined) {
+    headers['link'] = `<${successorPath}>; rel="successor-version"`;
+  }
+
+  const meta: Record<string, string> = {
+    since: new Date(since).toISOString(),
+    sunset: new Date(sunset).toISOString(),
+    ...(deprecation.replacedBy === undefined ? {} : { replacedBy: deprecation.replacedBy }),
+  };
+  return { ok: true, headers, meta };
+}
+
+/** Set on a response that already exists, so a problem document carries them too. */
+export function applyHeaders(response: Response, headers: Readonly<Record<string, string>>): void {
+  for (const [name, value] of Object.entries(headers)) response.headers.set(name, value);
+}

package/src/errors.ts

@@ -9,9 +9,13 @@ export { CursorInvalidError } from '@ultimat3/core';
 
 /** Titles for the framework-wide code table — every one of them owned by this package. */
 const OWNED_TITLES: Readonly<Record<string, string>> = {
+  X_CURSOR_VALUE_UNSUPPORTED: 'a sort value cannot be carried in a cursor',
   X_MATCHER_UNSUPPORTED: 'live query shape cannot be patched incrementally',
+  X_QUERY_CACHE_TTL_INVALID: 'a query declares a cache ttlMs no tier can hold',
+  X_QUERY_DEPRECATION_INVALID: 'a query declares a deprecation whose dates cannot be rendered',
   X_QUERY_DUPLICATE: 'two queries are registered under one name',
   X_QUERY_FOREIGN: 'a value that is not a query was projected as one',
+  X_QUERY_INPUT_UNENCODABLE: 'a query input cannot be carried in a query string',
   X_QUERY_NOT_PAGEABLE: 'a read returned rows with no id, so a cursor cannot name a position',
   X_QUERY_POLICY_MISSING: 'a query was registered without a policy',
   X_QUERY_UNREGISTERED: 'a query was used before it was registered',
@@ -107,6 +111,49 @@ export class QueryForeignError extends UltimateError {
   }
 }
 
+/**
+ * A read whose declared input cannot survive its own route. Thrown at `query()`, so the file that
+ * wrote it is the file that fails.
+ *
+ * The `fix` names the three edits that exist, because which one applies depends on what the key
+ * means: a structure belongs in an `action`'s JSON body, a filter can be flattened into scalar
+ * keys, and an explicitly-null argument is spelled as an absent optional one.
+ */
+export class QueryInputUnencodableError extends UltimateError {
+  constructor(offender: string) {
+    super({
+      code: 'X_QUERY_INPUT_UNENCODABLE',
+      cause: `${offender}, and a read is served as GET /_x/query/<name> — a query string carries characters, not structures or nulls`,
+      fix: 'flatten the key into scalar arguments (status: t.string, limit: t.number), spell an absent value as `.optional()` rather than `t.nullable(...)`, or declare it as an action() if it really needs a JSON body',
+      docs: docs('X_QUERY_INPUT_UNENCODABLE'),
+    });
+  }
+}
+
+/**
+ * A `cache.ttlMs` no tier will accept, refused at `query()` — so the file that wrote it fails, and
+ * not every read of that query for the life of the process.
+ *
+ * Every `CacheTier` refuses a non-positive or non-finite lease (`assertTtl`, `X_CACHE_TTL_INVALID`)
+ * and the read path's only catch absorbs `X_CACHE_TOO_LARGE`, so `ttlMs: Infinity` used to make a
+ * working read fail permanently with a cause naming a cache key. The value is a number the author
+ * typed, so it is echoed: it is the one fact that repairs the line.
+ *
+ * The query has no name yet — `query()` runs before `registerQueries()` stamps one — which is why
+ * the cause describes the declaration, exactly as `X_QUERY_INPUT_UNENCODABLE` does.
+ */
+export class QueryCacheTtlInvalidError extends UltimateError {
+  constructor(ttlMs: number) {
+    super({
+      code: 'X_QUERY_CACHE_TTL_INVALID',
+      cause: `a query declares cache.ttlMs as ${ttlMs}, and every cache tier refuses a lease that is not positive and finite`,
+      fix: 'set `cache: { ttlMs: 60_000 }` to a positive whole number of milliseconds, or drop ttlMs to take the read cache default',
+      docs: docs('X_QUERY_CACHE_TTL_INVALID'),
+      meta: { ttlMs },
+    });
+  }
+}
+
 export class QueryDuplicateError extends UltimateError {
   constructor(name: string) {
     super({
@@ -118,17 +165,43 @@ export class QueryDuplicateError extends UltimateError {
   }
 }
 
+/**
+ * The `fix` pastes a PERMISSION and the `cause` names the query, and the two are not
+ * interchangeable: `can()` takes `resource:verb` (`Permission` is `` `${string}:${string}` ``), so
+ * the `can('${name}')` this used to emit did not compile, and `assertPermission` would refuse it
+ * the moment the app declared its own set. The reader needs the query's name to find the file and
+ * the permission's SHAPE to fill the argument — the same split `@ultimat3/policy`'s own
+ * `policyMissing()` already makes.
+ */
 export class QueryPolicyMissingError extends UltimateError {
   constructor(name: string) {
     super({
       code: 'X_QUERY_POLICY_MISSING',
       cause: `query "${name}" was registered without a policy`,
-      fix: `add \`policy: can('${name}')\` to the query definition in the file that exports it`,
+      fix: `add \`policy: can('<resource>:<verb>')\` to the query() that exports "${name}" — a permission your definePermissions() call declares, never the query's own name — or \`allow('<resource>:<verb>')\` to state that the read is public`,
       docs: docs('X_QUERY_POLICY_MISSING'),
     });
   }
 }
 
+/**
+ * A `deprecated:` block whose dates cannot become the headers it promises. Refused where the
+ * declaration is converted, so every projection that reads it refuses the same value — the mirror
+ * of `@ultimat3/action`'s `X_ACTION_DEPRECATION_INVALID`, and for the same reason: a `Sunset`
+ * header rendering `Invalid Date` is a contract statement no client can act on.
+ */
+export class QueryDeprecationInvalidError extends UltimateError {
+  constructor(name: string, field: string, value: string) {
+    super({
+      code: 'X_QUERY_DEPRECATION_INVALID',
+      cause: `query "${name}" declares deprecated.${field} as "${value}", which is not a date`,
+      fix: `edit \`deprecated: { ${field}: … }\` on ${name} to an ISO-8601 instant — e.g. '2026-12-31T23:59:59Z'`,
+      docs: docs('X_QUERY_DEPRECATION_INVALID'),
+      meta: { query: name, field, value },
+    });
+  }
+}
+
 /**
  * Thrown when a paged or live read hands back a row with no `id`. The id is the tiebreak that
  * makes the sort order total, so without one the position a cursor names is ambiguous — and the
@@ -146,6 +219,29 @@ export class QueryNotPageableError extends UltimateError {
   }
 }
 
+/**
+ * A sort key the cursor codec cannot carry, refused where the cursor is MINTED.
+ *
+ * Deliberately not `X_CURSOR_INVALID`: that code means "the cursor you sent is not one of ours",
+ * and its fix — request the first page again — repairs nothing here. This is the read's own
+ * `orderBy` naming a column whose values are objects, `NaN` or `±Infinity`, so the repair is one
+ * edit to the declaration and no retry will ever help. `Date` and `bigint` are NOT in this set:
+ * `cursor-value.ts` tags both and revives them, which is the whole reason it exists.
+ *
+ * The description says the SHAPE and never the value — a cursor's key is row data, and a `cause`
+ * reaches the log index and the problem document alike.
+ */
+export class CursorValueUnsupportedError extends UltimateError {
+  constructor(description: string) {
+    super({
+      code: 'X_CURSOR_VALUE_UNSUPPORTED',
+      cause: `a sort key holds ${description}, which no cursor can carry`,
+      fix: 'order by a scalar column — .orderBy("createdAt") or .orderBy("id") — and project the composite value into the row instead',
+      docs: docs('X_CURSOR_VALUE_UNSUPPORTED'),
+    });
+  }
+}
+
 /** The honest fallback: the matcher refuses to guess rather than patch wrongly. */
 export class MatcherUnsupportedError extends UltimateError {
   constructor(name: string, feature: string) {

package/src/facade.ts

@@ -27,6 +27,8 @@ export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
     policy: def.policy,
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
     // `.as()` is impersonation on the one read path: `runQuery` keeps the
     // surrounding context whole and swaps only the actor.
     as: (actor, input, options) => runQuery(self(), input, { ...options, actor }),

package/src/http.ts

@@ -0,0 +1,109 @@
+/**
+ * Projection: a query becomes `GET /_x/query/<kebab>` — the URL `client.ts` already
+ * derives and fetches. The search string is the input, decoded at the wire and judged
+ * by `runQuery`, so the endpoint cannot drift from the MCP tool, the live window or a
+ * direct server call, and cannot acquire a second authz path while doing it.
+ */
+
+import { tagKeys } from '@ultimat3/cache';
+import { isUltimateError } from '@ultimat3/core';
+import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
+import { json, problem, toBucket } from '@ultimat3/http';
+import { coerceQuery } from '@ultimat3/schema';
+import type { Deprecation } from './deprecation';
+import { applyHeaders, recordDeprecatedCall, renderDeprecation } from './deprecation';
+import { QueryDeprecationInvalidError } from './errors';
+import { derivePath } from './naming';
+import { policyCapability } from './policy-gate';
+import type { AnyQuery } from './query';
+import { queryName, runQuery } from './read';
+
+/**
+ * `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`.
+ */
+export function toQueryRoute(target: AnyQuery): Route {
+  const name = queryName(target);
+  // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
+  // not a surprise on the first read.
+  const sunsetting = deprecationHeadersFor(name, target.deprecated);
+
+  const handler = async (request: UltimateRequest): Promise<Response> => {
+    if (sunsetting !== undefined) recordDeprecatedCall('query', name);
+    try {
+      // Coerced, then validated — two different jobs, and only the first one belongs to a
+      // wire. A search string is characters, so `t.number` and `t.boolean` need the HTTP
+      // boundary's decode (`coerceQuery` never invents data: what it cannot convert it
+      // hands on untouched). VALIDATING here — `request.query(schema)` — would be the
+      // second parser: the same read would answer `X_BODY_INVALID` where every other
+      // surface answers `X_INPUT_INVALID` with the line that prints its schema. `runQuery`
+      // is the one that decides, exactly as it does for a direct server call.
+      const input = coerceQuery(target.input, request.queryRaw());
+      const response = json(await runQuery(target, input, { surface: 'http' }));
+      // On the failure path too, below: a client polling a deprecated read that is currently
+      // 403ing still has to learn the read is going away.
+      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
+      return response;
+    } catch (error) {
+      // Framework errors carry their own code, status and fix line; anything else is
+      // a bug and belongs to the server's error boundary, not to this route.
+      if (!isUltimateError(error)) throw error;
+      const response = problem(error);
+      if (sunsetting !== undefined) applyHeaders(response, sunsetting);
+      return response;
+    }
+  };
+
+  const meta: RouteMeta = {
+    name,
+    // `allow(...)` is the only way a read is public, and saying so explicitly is what
+    // keeps "forgot the policy" from ever looking like "meant to be readable".
+    auth: target.policy.kind === 'allow' ? 'public' : 'required',
+    policy: policyCapability(target.policy),
+    // `runQuery` is this route's one evaluation and it decides from the PARSED input the
+    // 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',
+    // `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
+    // handler, by the same `runQuery` every other surface goes through.
+
+    // A read is answered per actor — the policy decided for this caller, and `sql` may
+    // scope the rows to them — while the URL names no actor at all. `public` would hand
+    // one actor's rows to the next caller of that URL, so a read is `no-store` and a
+    // shared cache is something a CDN in front of the app configures knowingly. The tags
+    // 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.
+    ...(target.rateLimit === undefined
+      ? {}
+      : { rateLimit: name, rateLimitBucket: toBucket(name, target.rateLimit) }),
+    ...(target.mcp?.description === undefined ? {} : { description: target.mcp.description }),
+  };
+
+  return { method: 'GET', path: derivePath(name), handler, meta };
+}
+
+/**
+ * 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.
+ */
+function deprecationHeadersFor(
+  name: string,
+  deprecated: Deprecation | undefined,
+): Readonly<Record<string, string>> | undefined {
+  if (deprecated === undefined) return undefined;
+  const successor =
+    deprecated.replacedBy === undefined ? undefined : derivePath(deprecated.replacedBy);
+  const rendered = renderDeprecation(deprecated, successor);
+  if (!rendered.ok) throw new QueryDeprecationInvalidError(name, rendered.field, rendered.value);
+  return rendered.headers;
+}

package/src/index.ts

@@ -9,43 +9,59 @@
 /** Re-exported so a `query` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
-export type { ReadCache, ReadCacheEntry } from './cache';
+export type { QueryCacheScope } from './cache';
+/** `readAuthority` is the ONLY producer of `cacheKeyFor`'s authority — never spell one by hand. */
 export {
   cacheKeyFor,
-  getReadCache,
-  invalidateQueryTags,
-  MemoryReadCache,
+  DEFAULT_READ_CACHE_TTL_MS,
+  readAuthority,
+  readOnce,
   readThrough,
   requestMemo,
-  setReadCache,
 } from './cache';
 export type {
   FetchLike,
   QueryCallOptions,
+  QueryClient,
   QueryClientMethod,
   QueryClientOptions,
+  QueryLike,
+  QueryMap,
 } from './client';
-export { queryClientMethodFor } from './client';
+/** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
+export { queryClient, queryClientMethodFor } from './client';
+/** The compat window a retirement gets. Versioning is two deployments, not a router feature. */
+export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
+export { recordDeprecatedCall, renderDeprecation } from './deprecation';
 export type { QueryProblem } from './errors';
 export {
   CursorInvalidError,
+  CursorValueUnsupportedError,
   MatcherUnsupportedError,
   QueryDeniedError,
+  QueryDeprecationInvalidError,
   QueryDuplicateError,
   QueryForeignError,
   QueryInputInvalidError,
+  QueryInputUnencodableError,
   QueryNotPageableError,
   QueryPolicyMissingError,
   QueryRequestFailedError,
   QueryUnregisteredError,
 } from './errors';
+/** The HTTP projection: `GET /_x/query/<kebab>`, the URL `client()` derives. */
+export { toQueryRoute } from './http';
 export type { LiveCursor, LiveQuery, ResumeMode, ResumePlan, ToLiveOptions } from './live';
 export { advanceCursor, liveEpoch, planResume, seekOf, toLiveQuery } from './live';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
 export type { QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
 export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
-export { derivePath, toKebabCase, toToolName } from './naming';
+/**
+ * Path derivation only. There is no `toToolName`: an MCP tool is served under the export name
+ * verbatim, and an exported derivation would be a second way to spell one tool.
+ */
+export { derivePath, toKebabCase } from './naming';
 /**
  * The shapes `query.page(input, { first, after })` takes and answers with. `paginate` itself is
  * deliberately unexported: a page is the read's own answer, and a second, importable way to ask
@@ -54,7 +70,8 @@ export { derivePath, toKebabCase, toToolName } from './naming';
  */
 export type { Page, PaginateArgs } from './pagination';
 export type { QueryPolicy, QuerySubject, QuerySurface } from './policy-gate';
-export { actorOf, guard, policyCapability } from './policy-gate';
+/** `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on. */
+export { actorOf, guard, policyCapability, policyPermissions } from './policy-gate';
 export type {
   AnyQuery,
   Query,
@@ -64,11 +81,13 @@ export type {
   QueryFacade,
   QueryMcp,
   QueryOptions,
+  QueryRateLimit,
   SourceOptions,
 } from './query';
 export { describeQuery, isQuery, nameQuery, query, queryHash } from './query';
 /** The one read path. `defOf` stays unexported — that is the enforcement. */
 export { queryName, runQuery, sourceFor } from './read';
+
 export {
   describeQueries,
   getQuery,
@@ -78,7 +97,19 @@ export {
   resetRegistry,
 } from './registry';
 export type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
-export { compareRows, compareValues, matchesFilter, matchesFilters, seekKeyOf } from './shape';
+/**
+ * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
+ * `totalOrder` is the one definition of the order it must serve a page in.
+ */
+export {
+  compareRows,
+  compareValues,
+  isNull,
+  matchesFilter,
+  matchesFilters,
+  seekKeyOf,
+  totalOrder,
+} from './shape';
 export type { RowProvider, SqlSource, SqlText } from './source';
 /** `isAfterKey` is the one definition of "after this position" — both seek paths use it. */
 export { Builder, from, isAfterKey } from './source';