@ultimat3/query 24.0.0 → 25.1.0

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

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<TSingle>(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,17 +6,16 @@
  */
 
 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 } from './errors';
 import { absentArraysOf } from './input-shape';
-import { derivePath } from './naming';
 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';
@@ -24,8 +23,7 @@ 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);
@@ -60,6 +58,14 @@ 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 = absentArraysOf(target.input, coerceQuery(target.input, values));
     if (target.single === true) {
@@ -73,19 +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 []`.
-      return answerRow(oneRowOf(name, await runQuery(target, input, { surface: 'http' })));
+      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 }),
     );
   };
 
@@ -102,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
@@ -114,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,
@@ -138,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;

package/src/index.ts

@@ -6,8 +6,10 @@
  * authorize or execute on its own. One authz system, structurally.
  */
 
-// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
-// the module regardless (oven-sh/bun#40650). `registerPrimitiveRegistrar('query', …)` here is read
+// Anchored on purpose, and not by the `sideEffects` array alone: Bun before 1.4.1 read any array as
+// `false` and dropped the module regardless (oven-sh/bun#40650), and a bare import holds on every
+// bundler. The array still lists it, because a bundler that honours the array drops a bare import
+// of a module it does not list. `registerPrimitiveRegistrar('query', …)` here is read
 // by @ultimat3/core's registrar table on behalf of `x` and the manifest, and nothing that registers
 // a query imports this module for a binding. `SIDE_EFFECTS_ANCHORS` carries the argument and
 // `bun run side-effects` enforces it.
@@ -15,33 +17,25 @@ import './registry';
 
 /**
  * Flight control for the typed client, and OPT-IN by construction: `client.ts` names `ClientFlight`
- * as a TYPE only, so a caller that never mentions `createClientFlight` pays nothing for the fence,
+ * as a TYPE only, so a caller that never mentions `clientFlight` pays nothing for the fence,
  * the dedup map or the retry loop. Every mechanism underneath is `@ultimat3/core`'s — one fence,
  * one flight map, one gate, one backoff curve for the whole framework — and so is the pipeline
  * itself: it shipped as a byte-identical copy here and in `@ultimat3/action`, and
  * two tier-3 packages may not import each other, so the one copy lives at tier 0.
  *
- * Re-exported rather than re-declared, so every name is importable from this package exactly as
- * before. `isSuperseded` is core's too: reading a fenced answer is the point of installing a
- * flight, and it should not cost a second import.
+ * `ClientFlight` and `ClientRetry` are re-exported as TYPES because this barrel's options name
+ * them; every value (`clientFlight`, `isSuperseded`, …) is imported from `@ultimat3/core`,
+ * its one home — a re-export is a second import path (`X_HELPER_COPY`, `bun run flight-copies`).
  */
-export type {
-  ClientFlight,
-  ClientFlightOptions,
-  ClientRetry,
-  FlightKeyOptions,
-  FlightPlan,
-  WireAnswer,
-} from '@ultimat3/core';
-export {
-  createClientFlight,
-  DEFAULT_CLIENT_RETRY,
-  isSuperseded,
-  isTransientFailure,
-} from '@ultimat3/core';
+export type { ClientFlight, ClientRetry } from '@ultimat3/core';
 /** 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';
+/**
+ * The two refusals `query({ audit: true })` adds. The record and the sink are `@ultimat3/core`'s
+ * (`setAuditSink`) — one sink for every audited primitive, so this package re-exports neither.
+ */
+export { QueryAuditSinkFailedError, QueryAuditSinkMissingError } from './audit-errors';
 export type { QueryCacheScope } from './cache';
 /** `readAuthority` is the ONLY producer of `cacheKeyFor`'s authority — never spell one by hand. */
 export {
@@ -73,11 +67,7 @@ export { queryClient, queryClientMethodFor } from './client';
  */
 export type { KindOf } from './column-kinds';
 export { kindsOf } from './column-kinds';
-/** 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 {
-  CursorInvalidError,
   CursorValueUnsupportedError,
   MatcherUnsupportedError,
   QueryColumnUnselectedError,
@@ -98,27 +88,19 @@ export {
 /** 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 { planResume, seekOf, toLiveQuery } from './live';
+export { planResume, seekOf, spendQueryLimit, toLiveQuery } from './live';
 export type { ChangeEvent, ChangeOp, Patch } from './matcher';
 export { assertMatchable, match, positionFor } from './matcher';
-export type { QueryToolAnswer, QueryToolDescriptor, QueryToolReadOptions } from './mcp-tool';
-export { isExposed, toQueryTool, toQueryTools } from './mcp-tool';
-/**
- * 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 } from './naming';
 /**
  * The read half of `openapi.json`. `@ultimat3/cli` merges these paths into `@ultimat3/action`'s
  * `buildOpenApi` document — the two packages are one tier and cannot compose each other.
  */
 export { queryOpenApiPaths, toQueryOpenApiOperation } from './openapi';
 /**
- * The two search-string keys that page `GET /_x/query/<name>` — `_first` and `_after` — and the
- * shape the typed client's `.page()` takes. `MAX_PAGE_SIZE` is the bound both ends check.
+ * The shape the typed client's `.page()` takes. The bound both ends check is `@ultimat3/entity`'s
+ * `MAX_PAGE_SIZE` — imported from there, never re-published here.
  */
 export type { PageControls } from './page-controls';
-export { MAX_PAGE_SIZE } from './page-controls';
 /**
  * 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
@@ -128,19 +110,12 @@ export { MAX_PAGE_SIZE } from './page-controls';
 export type { Page, PaginateArgs } from './pagination';
 export type { QueryPolicy, QuerySubject, QuerySurface } from './policy-gate';
 /**
- * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
- * `admitsAnonymous` is `@ultimat3/policy`'s, re-exported here beside them: it is what
- * `toQueryRoute` derives `meta.auth` from, so a plain `route` sets that field from the same walk
- * rather than re-reading the root combinator.
+ * The one authz gate for reads, named after what it guards. The display label
+ * (`policyCapability`), what a report MATCHES on (`policyPermissions`) and what `toQueryRoute`
+ * derives `meta.auth` from (`admitsAnonymous`) are `@ultimat3/policy`'s, and the anonymous →
+ * `null` mapping (`actorOf`) is `@ultimat3/core`'s — imported from there, never re-published.
  */
-export {
-  actorOf,
-  admitsAnonymous,
-  guard,
-  guardBeforeInput,
-  policyCapability,
-  policyPermissions,
-} from './policy-gate';
+export { guardQuery, guardQueryBeforeInput } from './policy-gate';
 export type {
   AnyQuery,
   Query,
@@ -148,10 +123,6 @@ export type {
   QueryDef,
   QueryDescriptor,
   QueryFacade,
-  QueryListFilterOp,
-  QueryListParams,
-  QueryMcp,
-  QueryMcpAnnotations,
   QueryOptions,
   QueryRateLimit,
   SourceOptions,
@@ -165,7 +136,7 @@ export {
   listQueries,
   registerQueries,
   registerQuery,
-  resetRegistry,
+  resetQueries,
 } from './registry';
 /** The query FACTORY over an entity's searchable columns — a `query`, never a ninth primitive. */
 export type { SearchChain, SearchDef, SearchInput, SearchPage } from './search';
@@ -180,8 +151,9 @@ export {
 } from './shape';
 /** What a `single: true` read answers — one rule, also `@ultimat3/mcp`'s served tool's. */
 export { readAnswer } from './single-answer';
-export type { RowProvider, SqlSource, SqlText } from './source';
+/** `Builder` is a type only: `from()` is the one way to build one, so there is no `new Builder()`. */
+export type { Builder, 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';
+export { from, isAfterKey } from './source';
 export type { ExplainResult, QuerySqlInfo } from './sql';
-export { describeSql, explain } from './sql';
+export { describeSql, explainQuery } from './sql';

package/src/input-shape.ts

@@ -20,7 +20,7 @@ import { QueryInputUnencodableError } from './errors';
 import { PAGE_CONTROL_KEYS } from './page-controls';
 
 /** Node kinds whose value is a structure, not characters. `money` is `{ minor, currency }`. */
-const STRUCTURAL = new Set(['object', 'record', 'money']);
+const STRUCTURAL = new Set(['object', 'record', 'money', 'json']);
 
 /**
  * The first key this input could not put on a wire, or `undefined`. One key, not a list: a fix