@ultimat3/query 24.0.0 → 25.0.0

package/src/read.ts

@@ -7,9 +7,10 @@
 
 import type { Ctx } from '@ultimat3/core';
 import {
+  actorOf,
   anonymousActor,
   assert,
-  createContext,
+  ctxOf,
   finiteOption,
   logger,
   runWithContext,
@@ -20,6 +21,8 @@ import {
 } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { formatPath, validateAsync } from '@ultimat3/schema';
+import type { ReadAudit, ReadTrace } from './audit-gate';
+import { audited, auditedBuild, readAuditFor } from './audit-gate';
 import {
   cacheKeyFor,
   DEFAULT_READ_CACHE_TTL_MS,
@@ -29,8 +32,9 @@ import {
   readThrough,
 } from './cache';
 import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
-import { actorOf, guard, guardBeforeInput } from './policy-gate';
+import { guardQuery, guardQueryBeforeInput } from './policy-gate';
 import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
+import { spendReadLimit } from './rate-limit-gate';
 import type { SqlSource } from './source';
 
 /**
@@ -84,7 +88,12 @@ export function runQuery(
   raw: unknown,
   options: QueryOptions = {},
 ): Promise<readonly object[]> {
-  return asActor(options, (ctx) => readRows(target, raw, ctx, options));
+  return asActor(options, (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    return audit === null
+      ? readRows(target, raw, ctx, options, null)
+      : audited(audit, () => readRows(target, raw, ctx, options, audit.trace));
+  });
 }
 
 /**
@@ -97,7 +106,45 @@ export function sourceFor(
   raw: unknown,
   options: SourceOptions = {},
 ): Promise<SqlSource<object>> {
-  return asActor(options, (ctx) => buildSource(target, raw, ctx, options));
+  return asActor(options, (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    // A source handed out is executed by its caller — `@ultimat3/mcp`'s served tool among them —
+    // so an audited read records per `execute()`, and a build that refuses records here.
+    return audit === null
+      ? buildSource(target, raw, ctx, options, null)
+      : auditedBuild(audit, () => buildSource(target, raw, ctx, options, audit.trace));
+  });
+}
+
+/**
+ * One whole call over a built source, for a projection inside this package whose call is more
+ * than one `execute()` — `paginate`, which may answer a spent limit without executing at all. The
+ * record covers the build and `use` together, so the call is recorded exactly once either way.
+ */
+export function readCall<T>(
+  target: AnyQuery,
+  raw: unknown,
+  options: SourceOptions,
+  use: (source: SqlSource<object>) => Promise<T>,
+): Promise<T> {
+  return asActor(options, async (ctx) => {
+    const audit = auditFor(target, ctx, options);
+    if (audit === null) return use(await buildSource(target, raw, ctx, options, null));
+    return audited(audit, async () =>
+      use(await buildSource(target, raw, ctx, options, audit.trace)),
+    );
+  });
+}
+
+/** Resolved before the parse, so an audited read with no sink refuses while it has read nothing. */
+function auditFor(target: AnyQuery, ctx: Ctx, options: SourceOptions): ReadAudit | null {
+  return readAuditFor(
+    defOf(target).audit,
+    options.unenforced,
+    queryName(target),
+    ctx,
+    options.surface ?? 'server',
+  );
 }
 
 /**
@@ -118,7 +165,7 @@ function asActor<T>(options: QueryOptions, run: (ctx: Ctx) => Promise<T>): Promi
   const inChild = (): Promise<T> => run(useContext());
   const base = options.ctx ?? tryUseContext();
   return base === undefined
-    ? runWithContext(createContext(patch), inChild)
+    ? runWithContext(ctxOf(patch), inChild)
     : runWithContext(base, () => withChildContext(patch, inChild));
 }
 
@@ -136,6 +183,7 @@ function readRows(
   raw: unknown,
   ctx: Ctx,
   options: QueryOptions,
+  trace: ReadTrace | null,
 ): Promise<readonly object[]> {
   const name = queryName(target);
   return withSpan(`query.${name}`, async (span) => {
@@ -150,7 +198,7 @@ function readRows(
       // read is filled — and which of the two a slow read took is the first thing to ask.
       'ultimate.cached': defOf(target).cache !== undefined,
     });
-    const rows = await readRowsIn(target, raw, ctx, options);
+    const rows = await readRowsIn(target, raw, ctx, options, trace);
     span.setAttribute('ultimate.rows', rows.length);
     return rows;
   });
@@ -161,11 +209,18 @@ async function readRowsIn(
   raw: unknown,
   ctx: Ctx,
   options: QueryOptions,
+  trace: ReadTrace | null,
 ): Promise<readonly object[]> {
   const def = defOf(target);
   const name = queryName(target);
-  const source = await buildSource(target, raw, ctx, options);
-  const read = (): Promise<readonly object[]> => source.execute();
+  const source = await buildSource(target, raw, ctx, options, trace);
+  // Whether THIS call executed, for the audit record: a memo or tier hit never calls `read`, and
+  // its record says so (`replayed: true`) rather than being skipped.
+  if (trace !== null) trace.replayed = true;
+  const read = (): Promise<readonly object[]> => {
+    if (trace !== null) trace.replayed = false;
+    return source.execute();
+  };
   // The source came from this query's own `sql()`, so its rows are TRow throughout —
   // which is what the typed overload above states, and this body never has to assert.
   const tags = def.cache?.tags ?? [];
@@ -201,6 +256,7 @@ async function buildSource(
   raw: unknown,
   ctx: Ctx,
   options: SourceOptions,
+  trace: ReadTrace | null,
 ): Promise<SqlSource<object>> {
   const def = defOf(target);
   const name = queryName(target);
@@ -208,15 +264,36 @@ async function buildSource(
   // The actor half of the policy first, exactly as `invoke` does it: a reader refused whatever
   // they send learns nothing about this read's input schema from an `X_INPUT_INVALID`.
   if (unenforced === undefined) {
-    guardBeforeInput(
-      def.policy,
-      { actor: actorOf(ctx), ctx, query: name },
-      options.surface ?? 'server',
-    );
+    try {
+      guardQueryBeforeInput(
+        def.policy,
+        { actor: actorOf(ctx), ctx, query: name },
+        options.surface ?? 'server',
+      );
+    } catch (denial) {
+      // The record still names what was attempted, as an action's does: the denial is already
+      // decided, so parsing now tells the CALLER nothing, and an unparseable payload is no input.
+      if (trace !== null) trace.input = await parsedOrNothing(def.input, raw);
+      throw denial;
+    }
+  }
+  // The ONE place a read's declared `rateLimit:` is spent for every surface it runs on — the
+  // route, a paged read, the MCP tool. After the actor half (a refused reader learns that, not a
+  // 429), before the parse and `sql()`, which are the work being limited. An unenforced build has
+  // no caller to charge: the shared live window spends per subscriber (`spendQueryLimit`).
+  if (unenforced === undefined) {
+    await spendReadLimit(name, def.rateLimit, {
+      actor: ctx.actor,
+      surface: options.surface ?? 'server',
+      clientAddress: options.clientAddress,
+      onRateLimit: options.onRateLimit,
+      nowMs: ctx.now().getTime(),
+    });
   }
   const input = await validate(def.input, raw, name);
+  if (trace !== null) trace.input = input;
   if (unenforced === undefined) {
-    guard(
+    guardQuery(
       def.policy,
       { actor: actorOf(ctx), input, ctx, query: name },
       options.surface ?? 'server',
@@ -244,6 +321,12 @@ async function buildSource(
   return options.surface === 'live' && source.total !== undefined ? source.total() : source;
 }
 
+/** The parse without the refusal — only for the record of a read already refused on other grounds. */
+async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  return result.issues === undefined ? result.value : undefined;
+}
+
 async function validate(schema: StandardSchemaV1, raw: unknown, name: string): Promise<unknown> {
   const result = await validateAsync(schema, raw);
   if (result.issues !== undefined) {

package/src/record-answer.ts

@@ -10,7 +10,7 @@
 import type { RecordRows, Row } from '@ultimat3/core';
 import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core';
 import { hasEntityRows, rowsOf } from '@ultimat3/entity';
-import { json } from '@ultimat3/http';
+import { jsonResponse } from '@ultimat3/http';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Page } from './pagination';
 
@@ -23,10 +23,12 @@ export type RecordAnswer = (answer: readonly object[] | Page<object>) => Respons
  * `Page` — is the route's, not the declaration's.
  */
 export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswer {
-  if (!answersRecords(rows)) return (answer) => json(answer);
+  if (!answersRecords(rows)) return (answer) => jsonResponse(answer);
   return (answer) => {
     const records = collect(rows, isPage(answer) ? answer.rows : answer);
-    return json(encodeRecordEnvelope(answer, records), { headers: { [RECORDS_HEADER]: '1' } });
+    return jsonResponse(encodeRecordEnvelope(answer, records), {
+      headers: { [RECORDS_HEADER]: '1' },
+    });
   };
 }
 
@@ -36,9 +38,11 @@ export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswe
  * answers for a single output, so the transport unwraps both the same way.
  */
 export function recordRowAnswerFor(rows: StandardSchemaV1 | undefined): (row: object) => Response {
-  if (!answersRecords(rows)) return (row) => json(row);
+  if (!answersRecords(rows)) return (row) => jsonResponse(row);
   return (row) =>
-    json(encodeRecordEnvelope(row, collect(rows, [row])), { headers: { [RECORDS_HEADER]: '1' } });
+    jsonResponse(encodeRecordEnvelope(row, collect(rows, [row])), {
+      headers: { [RECORDS_HEADER]: '1' },
+    });
 }
 
 /** The one predicate the route and the OpenAPI projection both ask: can this read answer records? */

package/src/registry.ts

@@ -64,6 +64,6 @@ export function describeQueries(): readonly QueryDescriptor[] {
 }
 
 /** Test-only. Production registers once at boot. */
-export function resetRegistry(): void {
+export function resetQueries(): void {
   registry.clear();
 }

package/src/search.ts

@@ -6,12 +6,12 @@
  * syntax, and the tenant predicate is never optional.
  */
 
-import { type Ctx, finiteOption } from '@ultimat3/core';
+import { type Ctx, finiteOption, type McpExposureDeclaration } from '@ultimat3/core';
 import type { InferOutput, Shape, Simplify } from '@ultimat3/schema';
 import { t } from '@ultimat3/schema';
 import { QueryInputInvalidError } from './errors';
 import type { QueryPolicy } from './policy-gate';
-import type { QueryCache, QueryMcp, QueryRateLimit } from './query';
+import type { QueryCache, QueryRateLimit } from './query';
 import { query, queryName } from './query';
 import type { SeekKey } from './shape';
 import type { Builder, SqlSource, SqlText } from './source';
@@ -60,7 +60,7 @@ export interface SearchDef<S extends Shape, Row extends object> {
   readonly termMax?: number;
   readonly page?: SearchPage;
   readonly cache?: QueryCache;
-  readonly mcp?: QueryMcp;
+  readonly mcp?: McpExposureDeclaration;
   readonly rateLimit?: QueryRateLimit;
 }
 
@@ -84,7 +84,7 @@ const limitSchema = (max: number, fallback: number) =>
  * `SqlSource` is handed a `SeekKey` (the previous page's sort VALUES) and the chain wants its own
  * signed, plan-scoped string, and there is no way to mint one from the other here. Falling through
  * to `paginate`'s in-memory slice would cut inside the one page the provider fetched and report
- * `hasNextPage: false` at its edge — rows served on no page at all, which is the defect 12.0.0 spent
+ * `hasMore: false` at its edge — rows served on no page at all, which is the defect 12.0.0 spent
  * a release removing from the timestamp seek. So it is a refusal naming the alternative: page with
  * the entity chain's own `.search(term).after(cursor)`, or raise this read's `limit`.
  *
@@ -93,7 +93,7 @@ const limitSchema = (max: number, fallback: number) =>
  * `assert` they were `X_INVARIANT`, a 500 that blamed the server and paged whoever watches it.
  *
  * **The refusal is on the rows that would be CUT, never on the window** (`As of 2026-08-26`). It
- * used to serve `first` rows, mint an `endCursor` and report `hasNextPage: true` — a connection
+ * used to serve `first` rows, mint an `nextCursor` and report `hasMore: true` — a connection
  * protocol saying "call me again with this" for a call the cursor assert is guaranteed to throw on.
  * A first repair demanded `first >= limit` and refused the window itself, which refuses the
  * framework's OWN default pair: `limit` defaults to 20 and `first` arrives from a client
@@ -103,7 +103,7 @@ const limitSchema = (max: number, fallback: number) =>
  *
  * So the condition is the one thing that is actually wrong: the read answered MORE rows than the
  * window carries, and this seam has no second page to put the rest on. Below that, the page is
- * whole and `hasNextPage` is false by construction — the true stop signal, and no cursor is ever
+ * whole and `hasMore` is false by construction — the true stop signal, and no cursor is ever
  * handed back that a second call is guaranteed to refuse.
  *
  * **`seek` narrows the WINDOW and never the ORDER, and that is the whole reason this wrapper takes a
@@ -135,7 +135,7 @@ const onePage = <Row extends object>(
         `search of ${entity} serves one page: a relevance-filtered read has no cursor this layer can carry — raise this read's limit, or page the entity chain itself with .search(term).after(cursor)`,
       );
     }
-    // `paginate` asks for `first + 1` — the extra row IS `hasNextPage` — so the window it names is
+    // `paginate` asks for `first + 1` — the extra row IS `hasMore` — so the window it names is
     // one wider than the page it will serve.
     return windowOf(base, read, entity, served, window - 1);
   },
@@ -157,7 +157,7 @@ const windowOf = <Row extends object>(
   read: string,
   entity: string,
   served: number,
-  /** Rows `paginate` will serve. It fetched one more, to decide `hasNextPage`. */
+  /** Rows `paginate` will serve. It fetched one more, to decide `hasMore`. */
   first: number,
 ): SqlSource<Row> => {
   const windowed = base.limit(first + 1);

package/src/source.ts

@@ -52,7 +52,7 @@ export type RowProvider<TRow> =
 
 /**
  * In-memory reference source. `from<Post>('posts', rows).where({ orgId }).orderBy('createdAt')`
- * generates real SQL text for `explain()` while executing against the provided rows.
+ * generates real SQL text for `explainQuery()` while executing against the provided rows.
  */
 export function from<TRow extends object>(entity: string, rows: RowProvider<TRow>): Builder<TRow> {
   return new Builder<TRow>(entity, rows, [], [], null, null, []);
@@ -74,7 +74,7 @@ export class Builder<TRow extends object> implements SqlSource<TRow> {
   /**
    * One equality filter per key, and the clauses come out in **lexical key order** — not the order
    * the object literal was typed in. The generated text is something callers compare across runs:
-   * `explain()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
+   * `explainQuery()` prints it, `LiveQuery.sqlText` caches it, and tests pin it. Reordering two keys in
    * a call site must not rewrite the statement.
    */
   where(equals: Readonly<Record<string, unknown>>): Builder<TRow> {

package/src/sql.ts

@@ -1,7 +1,7 @@
 /**
  * SQL transparency. An agent that can read the SQL a query generates can fix a
  * slow or wrong read by itself; a query builder that hides its output forces it
- * to guess. `explain` is the read path for `/_x` and for `x db explain`.
+ * to guess. `explainQuery` is the read path for `/_x` and for `x db explain`.
  */
 import type { Ctx } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
@@ -18,10 +18,10 @@ export interface ExplainResult extends SqlText {
 }
 
 /**
- * Policy is deliberately NOT enforced here: `explain` never returns rows, and the
+ * Policy is deliberately NOT enforced here: `explainQuery` never returns rows, and the
  * surfaces that expose it (`/_x`, the CLI) are admin-gated in their own right.
  */
-export async function explain<TInput extends StandardSchemaV1, TRow extends object>(
+export async function explainQuery<TInput extends StandardSchemaV1, TRow extends object>(
   target: Query<TInput, TRow, boolean>,
   input: unknown,
   ctx?: Ctx,

package/src/stable.ts

@@ -11,9 +11,6 @@
 
 import { isJsonObject } from '@ultimat3/core';
 
-/** Re-exported, not re-declared: `./stable` stays this package's one import path for it. */
-export { isJsonObject };
-
 /** Column read that works for interfaces without an index signature. */
 export function columnOf(row: object, column: string): unknown {
   const record: unknown = row;

package/src/subscribes.ts

@@ -1,8 +1,8 @@
 /**
  * The relations a live read is patched from: the one thing about a query that cannot be derived,
- * and the two assertions that keep the declaration honest. `x db gen` grants those relations
- * `REPLICA IDENTITY FULL`, so a name that has gone stale is worse than none — it grants it to the
- * wrong table and leaves the right one unable to produce a patch, in silence (#357).
+ * and the two assertions that keep the declaration honest — a stale name is a declaration its
+ * author reads as true. Since #518 `x db gen` grants these relations no `REPLICA IDENTITY FULL`:
+ * every entity is keyed, and a keyed table is correct on DEFAULT (`x db gen` validates the names).
  */
 
 import { QuerySubscribesDriftError, QuerySubscribesInvalidError } from './errors';

package/src/type-pins.ts

@@ -0,0 +1,62 @@
+// Compile-time pins for this package's public surface. Source, not a `.test.ts`, on purpose:
+// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level claim written in one can never fail. This module emits nothing and exports nothing
+// anybody imports — a regression here is a build error, the only enforcement that counts.
+
+import type { McpExposureDeclaration } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { AnyQuery, Query, QueryDef } from './query';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+/**
+ * IDENTICAL, not merely mutually assignable: an object type without an optional key is assignable
+ * to one with it and back, so `Equals` cannot see an optional field added on one side only — and
+ * every field of the `mcp` block is optional but `expose`.
+ */
+type Identical<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+/**
+ * O-tool, 25.0.0: a query projects no MCP tool of its own — `@ultimat3/mcp`'s `toolFrom` is
+ * the one projection, and a tier-3 `.tool()` could only ever be a second one. A `tool` member
+ * coming back on either view flips these to `false`.
+ */
+export type _AQueryHasNoToolTwin = Assert<Equals<Extract<keyof AnyQuery, 'tool'>, never>>;
+export type _ATypedQueryHasNoToolTwin = Assert<Equals<Extract<keyof Query, 'tool'>, never>>;
+
+/**
+ * 25.0.0 (plan 101, M5): the deprecation TYPES are `@ultimat3/core`'s alone, as the helpers are.
+ * A runtime test cannot see a type re-export, so each is an expected error: a re-export coming
+ * back makes the directive unused, which `tsc` refuses.
+ */
+// @ts-expect-error — `Deprecation` is imported from `@ultimat3/core`, never from this barrel.
+export type _NoDeprecationReexport = import('./index').Deprecation;
+// @ts-expect-error — `DeprecationField` is imported from `@ultimat3/core`.
+export type _NoDeprecationFieldReexport = import('./index').DeprecationField;
+// @ts-expect-error — `DeprecationRender` is imported from `@ultimat3/core`.
+export type _NoDeprecationRenderReexport = import('./index').DeprecationRender;
+
+/**
+ * 25.0.0: a query's `mcp` block is core's ONE `McpExposureDeclaration`, on the declaration and on
+ * both views. `QueryMcp`, `QueryMcpAnnotations` and `QueryListParams` restated it; a twin coming
+ * back on the barrel makes its directive unused, and a field drifting flips the pins to `false`.
+ */
+export type _QueryDeclaresCoresBlock = Assert<
+  Identical<NonNullable<QueryDef<StandardSchemaV1, object>['mcp']>, McpExposureDeclaration>
+>;
+export type _AnyQueryCarriesCoresBlock = Assert<
+  Identical<NonNullable<AnyQuery['mcp']>, McpExposureDeclaration>
+>;
+export type _TypedQueryCarriesCoresBlock = Assert<
+  Identical<NonNullable<Query['mcp']>, McpExposureDeclaration>
+>;
+// @ts-expect-error — `QueryMcp` is gone: the block is `@ultimat3/core`'s `McpExposureDeclaration`.
+export type _NoQueryMcpTwin = import('./index').QueryMcp;
+// @ts-expect-error — `QueryMcpAnnotations` is core's `McpAnnotationHints`.
+export type _NoQueryMcpAnnotationsTwin = import('./index').QueryMcpAnnotations;
+// @ts-expect-error — `QueryListParams` is core's `McpListParams`.
+export type _NoQueryListParamsTwin = import('./index').QueryListParams;

package/src/deprecation.ts

@@ -1,76 +0,0 @@
-/**
- * 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 };
-}

package/src/mcp-tool.ts

@@ -1,102 +0,0 @@
-/**
- * A query as an MCP read tool. Its `read` goes through `sourceFor` — the same
- * authorized front half the HTTP read and the live subscription use — so the tool
- * cannot drift from the endpoint and cannot acquire a second authz path.
- */
-
-import type { Actor, Ctx } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
-import type { WireJsonSchema } from '@ultimat3/schema';
-import { toWireSchema } from '@ultimat3/schema';
-import type { QueryPolicy } from './policy-gate';
-import type { AnyQuery } from './query';
-import { queryName, sourceFor } from './read';
-import { listQueries } from './registry';
-import { readAnswer } from './single-answer';
-
-export interface QueryToolReadOptions {
-  readonly ctx?: Ctx;
-  /** The agent behind the call. `null` is the signed-out caller. */
-  readonly actor?: Actor | null;
-}
-
-/**
- * What `read()` resolves to, decided by the declaration: a list read's rows, a `single: true`
- * read's one row. Only a schema-erased query (`AnyQuery`, a mixed registry) answers the union —
- * a KNOWN list read typed as "rows or a row" made `.map` on its own answer a compile error.
- */
-export type QueryToolAnswer<TSingle extends boolean> = [TSingle] extends [true]
-  ? object
-  : [TSingle] extends [false]
-    ? readonly object[]
-    : readonly object[] | object;
-
-export interface QueryToolDescriptor<TSingle extends boolean = boolean> {
-  /**
-   * The export name VERBATIM, and identical to `query` below. `@ultimat3/mcp` serves a read
-   * under `queryName(target)` and answers `tools/call` for nothing else, so a snake_cased
-   * descriptor named a tool the server had never heard of — which it did until 2026-08.
-   */
-  readonly name: string;
-  /** The query's `mcp.description`, or its name when the author gave none. */
-  readonly description: string;
-  readonly query: string;
-  /**
-   * The query's own policy object, not a copy — `tool().policy === query.policy`
-   * is what makes "an MCP call cannot reach a different authz path" checkable.
-   */
-  readonly policy: QueryPolicy;
-  /** What `@ultimat3/mcp`'s `tools/list` serves for this read — `@ultimat3/schema`'s wire subset. */
-  readonly inputSchema: WireJsonSchema;
-  /** Always false: a query reads. Drives the rate-limit bucket in @ultimat3/mcp. */
-  readonly mutates: false;
-  /**
-   * The rows — or, for a `single: true` read, the one row itself and `X_NOT_FOUND` when there is
-   * none. The route's answer on both counts: an agent handed `[]` for a missing id reads "found,
-   * and empty" where the same read over HTTP said 404.
-   */
-  read(input: unknown, options?: QueryToolReadOptions): Promise<QueryToolAnswer<TSingle>>;
-}
-
-export function toQueryTool<TSingle extends boolean = boolean>(
-  target: AnyQuery & { readonly single?: TSingle },
-): QueryToolDescriptor<TSingle> {
-  const name = queryName(target);
-  return {
-    name,
-    description: target.mcp?.description ?? name,
-    query: name,
-    policy: target.policy,
-    inputSchema: toWireSchema(target.input),
-    mutates: false,
-    read: async (input, options = {}) => {
-      // Executed without the cache tiers on purpose: an agent diffing two tool
-      // calls must be reading the rows, not a TTL.
-      const source = await sourceFor(target, input, {
-        ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-        ...(options.actor === undefined ? {} : { actor: options.actor }),
-      });
-      // The declaration decides the shape, and `TSingle` is that declaration as a type.
-      return readAnswer(target, await source.execute()) as QueryToolAnswer<TSingle>;
-    },
-  };
-}
-
-/**
- * Opt-in: a read hands rows to an agent, so silence exposes nothing. `mcp: { expose: true }` is
- * the whole opt-in — `isMcpExposed` from `@ultimat3/core` is the framework's one answer, and an
- * action's tool is now decided by the same call rather than by a second, looser rule.
- */
-export function isExposed(target: AnyQuery): boolean {
-  return isMcpExposed(target.mcp);
-}
-
-/** Deterministic order — the tool list is part of the agent-visible contract. */
-export function toQueryTools(
-  queries: readonly AnyQuery[] = listQueries(),
-): readonly QueryToolDescriptor[] {
-  return queries
-    .filter(isExposed)
-    .map(toQueryTool)
-    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-}

package/src/naming.ts

@@ -1,22 +0,0 @@
-/**
- * The naming rule for reads, as this package has always exported it: a query's export name
- * derives its HTTP path. The rule itself is `@ultimat3/core`'s `client-paths.ts` — one tier-0 file
- * that `action`, `query` and `realtime` all read, so the path cannot be derived two ways. The MCP
- * tool name is NOT derived — it is the export name verbatim, so there is one name to call.
- */
-
-import { queryPath, splitWords } from '@ultimat3/core/page';
-
-export { splitWords };
-
-/** `liveFeed` -> `live-feed`. */
-export function toKebabCase(name: string): string {
-  return splitWords(name).join('-');
-}
-
-/**
- * `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. A read is a GET under its own
- * prefix so a CDN, a browser cache and a log line can all tell it apart from an action's
- * `POST /api/...` without parsing a body.
- */
-export const derivePath: (name: string) => string = queryPath;