@ultimat3/query 1.2.0 → 2.0.0

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';

package/src/input-shape.ts

@@ -0,0 +1,74 @@
+// Single responsibility: what a read's `input:` may be, given that a read is projected to
+// `GET /_x/query/<kebab>` and a query string is characters.
+//
+// `client.ts` encoded a nested member as `JSON.stringify(item)` and skipped a `null`; the server's
+// own route decodes with `coerceQuery`, which has no inverse for either — `case 'object'` hands
+// the raw value back untouched and there is no `JSON.parse` on that path. So the typed client
+// type-checked calls the server then answered `X_INPUT_INVALID` for, which is precisely the
+// failure `client.ts`'s header claims to prevent ("a compile error in a Solid component rather
+// than a 404 at runtime").
+//
+// The fix is the DECLARATION, not the encoder. Teaching `coerceQuery` to `JSON.parse` a string
+// would make the one HTTP-boundary decoder invent structure for every surface that shares it —
+// forms and route params included — against that file's own rule that it "never invents data";
+// and a `null` sentinel would be a reserved string colliding with the legitimate value `"null"`.
+// Refusing here means the client can never encode something the server rejects, because such an
+// input cannot be written.
+
+import { type SchemaNode, tryIntrospect } from '@ultimat3/schema';
+import { QueryInputUnencodableError } from './errors';
+
+/** Node kinds whose value is a structure, not characters. `money` is `{ minor, currency }`. */
+const STRUCTURAL = new Set(['object', 'record', 'money']);
+
+/**
+ * The first key this input could not put on a wire, or `undefined`. One key, not a list: a fix
+ * line names one edit, and the next declaration attempt reports the next key.
+ */
+function unencodable(node: SchemaNode): string | undefined {
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    // Required AND nullable: `searchOf` sends nothing for a `null`, and absence is what the far
+    // side then sees — so the value the caller explicitly chose fails validation on arrival.
+    // Optional or defaulted, absence is already the schema's own answer and nothing is lost.
+    if (child.nullable === true && child.optional !== true && child.hasDefault !== true) {
+      return `${key} is nullable and required`;
+    }
+    const kind = structuralKind(child);
+    if (kind !== undefined) return `${key} is a ${kind}`;
+  }
+  return undefined;
+}
+
+/** The structural kind inside a member, through an array or a union. */
+function structuralKind(node: SchemaNode): string | undefined {
+  if (STRUCTURAL.has(node.kind)) return node.kind;
+  if (node.kind === 'array' && node.items !== undefined) return structuralKind(node.items);
+  if (node.kind === 'union') {
+    for (const member of node.anyOf ?? []) {
+      const kind = structuralKind(member);
+      if (kind !== undefined) return kind;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Refused at `query()`, which is the first import of the authoring file — the same place
+ * `@ultimat3/schema` refuses a `discriminatedUnion` it could never route, and for the same reason:
+ * the declaration is wrong for every input, so the earliest honest moment is where it is written.
+ *
+ * A schema this package cannot introspect is left alone rather than guessed at: `tryIntrospect`
+ * answering `undefined` means a foreign Standard Schema, and refusing one would make the seam
+ * `configureSchemaProvider` exists for unusable.
+ */
+export function assertEncodableInput(input: unknown): void {
+  const node = tryIntrospect(input);
+  if (node === undefined) return;
+  if (node.kind !== 'object') {
+    // `searchOf` answers `''` for anything that is not a plain object, so the server receives no
+    // arguments at all — a read declared this way is called with an input nothing ever carries.
+    throw new QueryInputUnencodableError(`the input is a ${node.kind}, not an object`);
+  }
+  const offender = unencodable(node);
+  if (offender !== undefined) throw new QueryInputUnencodableError(offender);
+}

package/src/live.ts

@@ -2,8 +2,11 @@
  * What `live: true` actually produces: the descriptor @ultimat3/realtime
  * subscribes to. It carries the SQL shape (for the matcher), the dependency set
  * (which entities/tags a change feed must touch to matter), the policy (re-run
- * per subscriber, never once for a channel) and a cursor for cheap reconnects.
+ * per subscriber, never once for a channel) and a cursor for cheap reconnects —
+ * and it runs that read (`execute`), so the shared window and the matcher over it
+ * come from one build of one `(query, input)` rather than two that agree by luck.
  */
+import { tagKeys } from '@ultimat3/cache';
 import type { Ctx } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Patch } from './matcher';
@@ -15,7 +18,6 @@ import { queryHash } from './query';
 import { queryName, sourceFor } from './read';
 import type { QueryShape, SeekKey } from './shape';
 import { seekKeyOf } from './shape';
-import { tagKeys } from './tags';
 
 /**
  * Reconnect state. Deliberately tiny — an id, a sort key and a version — because
@@ -58,6 +60,17 @@ export interface LiveQuery {
   readonly policy: QueryPolicy;
   readonly sqlText: string;
   readonly limit: number | null;
+  /**
+   * The read this descriptor describes, run. It is the *same* source the shape, the reads and the
+   * SQL text were taken from, which is the point: a subscriber's window and the matcher that
+   * patches it have to come from one build of one `(query, input)`. A caller that wanted rows and
+   * called `sourceFor` itself would be a second build — twice the parse, twice the `sql()`, and
+   * two descriptions of one read that are only equal by luck.
+   *
+   * It executes on every call rather than memoising: a client joining an existing subscription
+   * must see the rows as they are now, not the window someone else opened.
+   */
+  execute(): Promise<readonly object[]>;
   /** Per-subscriber authorization. Called on subscribe *and* on every fanout. */
   authorize(subject: QuerySubject): Promise<void>;
   initialCursor(rows: readonly object[]): LiveCursor;
@@ -81,6 +94,13 @@ export interface ToLiveOptions {
   readonly enforce?: boolean;
 }
 
+/**
+ * Why a shared window builds with no policy evaluation. Spelled once, here, so the reason a sync
+ * node gives `sourceFor` cannot drift from the one `ToLiveOptions.enforce` documents.
+ */
+const SHARED_WINDOW_REASON =
+  'the shared subject-less window has no subscriber to decide about; authorize() runs per subscriber';
+
 /** Changing the build changes the epoch, which forces reconnects to refetch. */
 export function liveEpoch(): string {
   return Bun.env['X_BUILD_ID'] ?? 'dev';
@@ -94,7 +114,10 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
   const name = queryName(target);
   const source = await sourceFor(target, input, {
     ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
-    ...(options.enforce === undefined ? {} : { enforce: options.enforce }),
+    // The boolean stays this layer's spelling because it has exactly ONE reason, stated on
+    // `ToLiveOptions.enforce` above; `sourceFor` takes that reason as a string so every skipped
+    // policy in the framework is greppable with its justification attached.
+    ...(options.enforce === false ? { unenforced: SHARED_WINDOW_REASON } : {}),
     surface: 'live',
   });
   const shape = source.shape();
@@ -115,6 +138,7 @@ export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends
     policy,
     sqlText: source.toSQL().sql,
     limit: shape.limit,
+    execute: () => source.execute(),
     authorize: async (subject) => {
       guard(policy, subject, 'live');
     },

package/src/matcher.ts

@@ -4,9 +4,9 @@
  * filters + orderBy + limit; anything else throws X_MATCHER_UNSUPPORTED, because
  * an honest refusal beats a silently wrong result set.
  */
-import { MatcherUnsupportedError } from './errors';
+import { MatcherUnsupportedError, QueryNotPageableError } from './errors';
 import type { QueryShape } from './shape';
-import { compareRows, matchesFilters } from './shape';
+import { compareRows, matchesFilters, totalOrder } from './shape';
 import { columnOf } from './stable';
 
 export type ChangeOp = 'insert' | 'update' | 'delete';
@@ -55,8 +55,8 @@ export function match<TRow extends object>(
   assertMatchable(name, shape);
   if (event.entity !== shape.entity) return [];
 
-  const id = idOf(event.row);
-  const index = rows.findIndex((row) => idOf(row) === id);
+  const id = idOf(event.row, shape.entity);
+  const index = rows.findIndex((row) => idOf(row, shape.entity) === id);
   const inSet = index >= 0;
   const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
 
@@ -74,8 +74,18 @@ export function match<TRow extends object>(
     compareRows(event.row, current, shape.orderBy) !== 0;
   if (!moved) return [{ kind: 'update', position: index, row: event.row }];
 
-  // A move keeps the window full, so it never needs a refill.
   const without = [...rows.slice(0, index), ...rows.slice(index + 1)];
+  // A move to the TAIL of a full window is a position only the server can fill. `insert()` places
+  // the row among the `limit - 1` rows the client still holds, so its position can never reach
+  // `shape.limit` and the `position >= shape.limit` bail below is unreachable on this path — the
+  // row was re-inserted INSIDE the window. Proven with `limit: 3`, window `[a:1, b:2, c:3]` and a
+  // server also holding `d:4, e:5`: moving `a` to `99` rendered `[b, c, a:99]` where the true
+  // window is `[b, c, d]`. Whether the moved row is still in the window is the server's answer
+  // too, so the refill covers both.
+  const wasFull = shape.limit !== null && rows.length >= shape.limit;
+  if (wasFull && positionFor(shape, without, event.row) >= without.length) {
+    return removeAt<TRow>(shape, index, id, true);
+  }
   return [...removeAt<TRow>(shape, index, id, false), ...insert(shape, without, event.row)];
 }
 
@@ -91,7 +101,7 @@ function insert<TRow extends object>(
   if (shape.limit !== null && rows.length >= shape.limit) {
     const evicted = rows[shape.limit - 1];
     if (evicted !== undefined) {
-      patches.push({ kind: 'remove', position: shape.limit, id: idOf(evicted) });
+      patches.push({ kind: 'remove', position: shape.limit, id: idOf(evicted, shape.entity) });
     }
   }
   return patches;
@@ -109,18 +119,35 @@ function removeAt<TRow extends object>(
   return patches;
 }
 
-/** Insertion index under the query's ordering; append when the query is unordered. */
+/**
+ * Insertion index under the ordering the source serves — `totalOrder`, not the declared keys.
+ *
+ * A page arrives as `order by <declared keys>, "id" asc` and `isAfterKey` reads the next one the
+ * same way, so a row tied on every declared key belongs where its id puts it. Placing it at the
+ * end of the tie group instead is a position the database would never return: the client renders
+ * one order, a re-read answers another, and the cursor cut from the window's tail skips the ties
+ * the matcher pushed past it.
+ *
+ * An unordered query has no position to get wrong — SQL promises none — so it appends.
+ */
 export function positionFor<TRow extends object>(
   shape: QueryShape,
   rows: readonly TRow[],
   row: TRow,
 ): number {
   if (shape.orderBy.length === 0) return rows.length;
-  const found = rows.findIndex((current) => compareRows(row, current, shape.orderBy) < 0);
+  const order = totalOrder(shape.orderBy);
+  const found = rows.findIndex((current) => compareRows(row, current, order) < 0);
   return found === -1 ? rows.length : found;
 }
 
-function idOf(row: object): string {
+/**
+ * The row's identity, and the tiebreak `positionFor` sorts by. Refused when absent for the reason
+ * `seekKeyOf` refuses it: `String(undefined)` is `"undefined"`, an id every id-less row shares, so
+ * one row's patch lands on another's position and a `remove` names a row no client holds.
+ */
+function idOf(row: object, entity: string): string {
   const value = columnOf(row, 'id');
+  if (value === undefined || value === null) throw new QueryNotPageableError(entity);
   return typeof value === 'string' ? value : String(value);
 }

package/src/mcp-tool.ts

@@ -5,9 +5,9 @@
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import type { JsonSchema } from '@ultimat3/schema';
 import { toMcpInputSchema } from '@ultimat3/schema';
-import { toToolName } from './naming';
 import type { QueryPolicy } from './policy-gate';
 import type { AnyQuery } from './query';
 import { queryName, sourceFor } from './read';
@@ -20,6 +20,11 @@ export interface QueryToolReadOptions {
 }
 
 export interface QueryToolDescriptor {
+  /**
+   * 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;
@@ -38,7 +43,7 @@ export interface QueryToolDescriptor {
 export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
   const name = queryName(target);
   return {
-    name: toToolName(name),
+    name,
     description: target.mcp?.description ?? name,
     query: name,
     policy: target.policy,
@@ -57,11 +62,12 @@ export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
 }
 
 /**
- * Opt-in, unlike an action's tool: a read hands rows to an agent, so silence
- * exposes nothing. `mcp: { expose: true }` is the whole opt-in.
+ * 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 target.mcp?.expose === true;
+  return isMcpExposed(target.mcp);
 }
 
 /** Deterministic order — the tool list is part of the agent-visible contract. */