@ultimat3/query 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @ultimat3/query 🔎
+
+A read. Optionally live. Never a mutation — writes are `action`.
+
+```ts
+import { query, t } from '@ultimat3/query';
+
+export const liveFeed = query({
+  input: t.object({ orgId: t.uuid }),
+  policy: can('feed:read'),
+  live: true,
+  mcp: { expose: true, description: 'The org feed' },
+  sql: ({ orgId }) => db.posts.where({ orgId }).orderBy('createdAt').limit(50),
+});
+
+const rows = await liveFeed({ orgId });        // typed rows, policy enforced
+```
+
+Register once at boot: `registerQueries(await import('./live'))`. Export names become
+query names, which the manifest, the live protocol and `/_x` all address.
+
+## One declaration, five projections
+
+Every projection is a method on the query itself. A query has no `.def`.
+
+| Call | Gives |
+|---|---|
+| `liveFeed({ orgId })` | the rows, policy enforced, through the cache tiers |
+| `liveFeed.as(actor, { orgId })` | the same read as another actor — the surrounding context is untouched, `null` is signed out |
+| `liveFeed.page({ orgId }, { first: 20, after })` | one bounded page plus the signed cursor that continues it. There is no `offset` |
+| `liveFeed.live({ orgId })` | the `LiveQuery` `@ultimat3/realtime` subscribes to, carrying the same policy object |
+| `liveFeed.tool()` | the MCP read tool. `tool().policy === liveFeed.policy`, and it reads fresh |
+| `liveFeed.client({ baseUrl })` | `GET /_x/query/live-feed?orgId=…`, typed both ways |
+| `liveFeed.describe()` | the manifest row |
+
+The declaration is lifted too: `.input`, `.policy`, `.cache`, `.mcp`, `.isLive`. `sql` is not
+among them — it lives in a private store inside `read.ts`, so `sourceFor` is the only thing
+that can build a source and there is nowhere for a second authz path to hide. Something that
+merely looks like a query (`kind: 'query'`, no declaration) is `X_QUERY_FOREIGN`.
+
+## What each file owns
+
+| File | Job |
+|---|---|
+| `query.ts` | the primitive, `describeQuery`, `queryHash` |
+| `read.ts` | the one read path — `runQuery`, `sourceFor` — and the declaration store |
+| `facade.ts` | binds each projection to the query; re-implements none of them |
+| `mcp-tool.ts` | the MCP read descriptor |
+| `client.ts` | the typed read client (browser-safe) |
+| `naming.ts` | export name → wire path + tool name |
+| `live.ts` | the `LiveQuery` descriptor `@ultimat3/realtime` subscribes to |
+| `matcher.ts` | change event → minimal patch (`add` / `update` / `remove` / `refill`) |
+| `pagination.ts` | `paginate()` — keyset pages over core's cursor codec |
+| `sql.ts` | `explain()` — the generated SQL, verbatim |
+| `cache.ts` | request memo + tag-keyed tier, one invalidation graph |
+| `source.ts` | the `SqlSource` contract + `from()`, the in-memory reference |
+
+## Live queries
+
+`live: true` produces a descriptor with four parts:
+
+| Part | Why |
+|---|---|
+| `shape` | the matcher patches from the shape, never by re-parsing SQL |
+| `reads` | entities + tags this read depends on — the change-feed filter |
+| `policy` | evaluated **per subscriber**, on subscribe and on every fanout |
+| cursor | reconnect state: epoch + query hash + version + seek key |
+
+### Cursor tradeoff (the reconnect risk, stated plainly)
+
+A cursor is not a snapshot. Resume re-runs the **bounded** query from the seek key
+(`limit` rows, one indexed keyset read) instead of replaying a per-subscriber change
+log, so a sync node holds no history and reconnect cost is O(limit). The price: the
+cursor cannot prove that rows sorting *before* it are unchanged, so any epoch change —
+new build, new policy, new schema — forces a full refetch instead of a resume. Bounded
+server memory bought with an occasional extra page fetch.
+
+## Matcher support
+
+| Shape | Result |
+|---|---|
+| equality / `!=` / `in` / range filters | patched incrementally |
+| `orderBy` (any number of keys) | insert position computed, moves become remove + add |
+| `limit` | tail eviction on insert, `refill` patch on removal |
+| joins, aggregates, `group by`, subqueries | `X_MATCHER_UNSUPPORTED` with a fix line |
+
+An honest refusal beats a silently wrong result set, so unsupported shapes fail at
+**subscribe** time, not on the first change event.
+
+## Pagination is cursor-only
+
+`offset` does not exist in this package on purpose: it makes the database count rows it
+throws away (O(offset) per page), and any concurrent insert or delete before the offset
+shifts every later page, so users see duplicates and holes. Cursors are opaque,
+HMAC-signed, and bound to one query + arguments — a cursor from another query is
+`X_CURSOR_INVALID`.
+
+`query.page(input, { first, after })` is the only way to ask for one — `paginate` backs it and is
+not exported, because a page is the read's own answer rather than an imported helper.
+
+The codec lives in `@ultimat3/core`, not here: `encodeCursor`, `decodeCursor`,
+`configureCursorSigning` (set the signing secret once at boot; rotating it invalidates every
+open cursor) and `usesDevCursorSecret` are all imported from there. `As of 2026-08`, `x doctor`
+reports `X_CURSOR_SECRET_DEV` when a production process is still signing with the key shipped in
+the package, and rotating the secret is what invalidates every open cursor. This package supplies
+the only thing that is its business — the scope, `queryHash(name, input)` — and re-exports
+`CursorInvalidError` so the failure keeps its name on this surface.
+
+A cursor names a **position in the ordering**, never a row and never a count. Both seek paths
+answer "is this row after that position?" through the one predicate, `isAfterKey`: `Builder.seek()`
+compiles it to SQL — spelled out per key, so a mixed `createdAt desc, id asc` listing is a real
+predicate rather than an id tiebreak — and `paginate()` applies the same comparison when a source
+has no `seek()`. Filtering by position is what makes a delete between two pages harmless; locating
+the cursor's row by id and slicing after it silently restarts the listing the moment that row is
+gone. A row with no `id` cannot name a position at all: that is `X_QUERY_NOT_PAGEABLE`, not a
+cursor signed over `"undefined"`.
+
+Because the predicate always carries that id, the ordering carries it too: a paged read is served
+`order by <declared keys>, "id" asc`, and the in-memory path sorts by the same list. Ordering by
+the declared keys alone leaves rows with equal sort values in whatever order the database chose,
+while the cursor reads them as if id had decided — so one of a tied pair comes back on both pages
+and the other on neither.
+
+## Caching
+
+Request memo (same read twice in one render ⇒ one round trip), then the tier behind
+`ReadCache`. Keys are `query:<name>:<input fingerprint>:<tags>`. An action's
+`cache.invalidates` and a query's `cache.tags` meet in the one graph owned by
+`@ultimat3/cache`.
+
+## Errors
+
+| Code | When | Fix |
+|---|---|---|
+| `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
+| `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
+| `X_MATCHER_UNSUPPORTED` | live query the matcher cannot patch | reshape it, or `live: false` |
+| `X_CURSOR_INVALID` | tampered / foreign / malformed cursor | request the first page again |
+| `X_QUERY_NOT_PAGEABLE` | a paged or live read returned a row with no `id` | select the primary key: `db.<rows>.select({ id: true, … })` |
+| `X_INPUT_INVALID` | input failed the Standard Schema | `x queries describe <name> --json` |
+| `X_QUERY_UNREGISTERED` | used before `registerQueries()` ran | register at boot |
+| `X_QUERY_FOREIGN` | a look-alike was projected as a query | declare it with `query({ … })` |
+| `X_RPC_FAILED` | `.client()` got a non-`problem+json` failure | check the gateway in front of the app |
+
+Denials re-throw the policy layer's own codes and keep the surface denial on
+`QueryDeniedError.denial`, so a live socket closes with 4403 instead of guessing.
+
+## Boundaries
+
+Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`. Never imports `action`,
+`jobs` or `realtime` (same tier) — `realtime` consumes `LiveQuery` from here.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ultimat3/query",
+  "version": "1.0.0",
+  "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/query"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/cache": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/policy": "1.0.0",
+    "@ultimat3/schema": "1.0.0"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,101 @@
+/**
+ * Read caching, two layers: a per-request memo (same query twice in one render
+ * costs one round trip) and a tag-keyed tier behind the `ReadCache` interface.
+ * Invalidation is never local — it goes through @ultimat3/cache so an action's
+ * `invalidates` and a query's `tags` meet in one graph.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import { invalidateTags } from '@ultimat3/cache';
+import type { Ctx } from '@ultimat3/core';
+import { fingerprint } from './stable';
+import { tagKeys } from './tags';
+
+export interface ReadCacheEntry {
+  readonly value: unknown;
+  readonly expiresAt: number | null;
+}
+
+export interface ReadCache {
+  get(key: string): Promise<ReadCacheEntry | undefined>;
+  set(key: string, entry: ReadCacheEntry): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/** In-memory default. Production installs the tiered cache from @ultimat3/cache. */
+export class MemoryReadCache implements ReadCache {
+  readonly #entries = new Map<string, ReadCacheEntry>();
+
+  async get(key: string): Promise<ReadCacheEntry | undefined> {
+    const entry = this.#entries.get(key);
+    if (entry === undefined) return undefined;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.#entries.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  async set(key: string, entry: ReadCacheEntry): Promise<void> {
+    this.#entries.set(key, entry);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.#entries.delete(key);
+  }
+}
+
+let tier: ReadCache = new MemoryReadCache();
+
+export function setReadCache(cache: ReadCache): void {
+  tier = cache;
+}
+
+export function getReadCache(): ReadCache {
+  return tier;
+}
+
+/** Request-scoped memo. Keyed by ctx identity so it dies with the request. */
+const memos = new WeakMap<object, Map<string, unknown>>();
+
+export function requestMemo(ctx: Ctx): Map<string, unknown> {
+  const key: object = ctx;
+  const existing = memos.get(key);
+  if (existing !== undefined) return existing;
+  const created = new Map<string, unknown>();
+  memos.set(key, created);
+  return created;
+}
+
+/** Deterministic: same query + same input + same tags => same key. */
+export function cacheKeyFor(name: string, input: unknown, tags: readonly CacheTag[]): string {
+  return `query:${name}:${fingerprint(input)}:${tagKeys(tags).join(',')}`;
+}
+
+/** Memo first, then the tier, then the source. */
+export async function readThrough<T>(
+  ctx: Ctx,
+  key: string,
+  ttlMs: number | null,
+  run: () => Promise<T>,
+): Promise<T> {
+  const memo = requestMemo(ctx);
+  const memoized = memo.get(key);
+  if (memoized !== undefined) return memoized as T;
+
+  const cached = await tier.get(key);
+  if (cached !== undefined) {
+    memo.set(key, cached.value);
+    return cached.value as T;
+  }
+
+  const value = await run();
+  memo.set(key, value);
+  await tier.set(key, { value, expiresAt: ttlMs === null ? null : Date.now() + ttlMs });
+  return value;
+}
+
+/** The one invalidation path. Actions call the same function via their `cache`. */
+export async function invalidateQueryTags(tags: readonly CacheTag[]): Promise<void> {
+  await invalidateTags(tags);
+}

package/src/client.ts

@@ -0,0 +1,87 @@
+/**
+ * The typed read client. Types come from the query's own declaration, the URL from
+ * the same pure derivation the server uses, so a renamed query is a compile error
+ * in a Solid component rather than a 404 at runtime. Browser-safe on purpose: no
+ * server imports, nothing here touches a context, a policy or a database.
+ */
+
+import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
+import { QueryRequestFailedError } from './errors';
+import { derivePath } from './naming';
+import { isJsonObject } from './stable';
+
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface QueryClientOptions {
+  readonly baseUrl: string;
+  readonly fetch?: FetchLike;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export interface QueryCallOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** `feed({ orgId })` with the input schema and the row type both inferred. */
+export type QueryClientMethod<TInput extends StandardSchemaV1, TRow extends object> = (
+  input: InferInput<TInput>,
+  options?: QueryCallOptions,
+) => Promise<readonly TRow[]>;
+
+/** One query's method — what `query.client()` returns. */
+export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
+  name: string,
+  options: QueryClientOptions,
+): QueryClientMethod<TInput, TRow> {
+  const doFetch: FetchLike = options.fetch ?? ((input, init) => fetch(input, init));
+  const base = options.baseUrl.replace(/\/+$/, '');
+  // Erased at the wire seam; the row type is this query's by construction.
+  return (input, callOptions = {}) =>
+    read(doFetch, base, options, name, input, callOptions) as Promise<readonly TRow[]>;
+}
+
+async function read(
+  doFetch: FetchLike,
+  base: string,
+  options: QueryClientOptions,
+  name: string,
+  input: unknown,
+  callOptions: QueryCallOptions,
+): Promise<unknown> {
+  const search = searchOf(input);
+  const url = `${base}${derivePath(name)}${search === '' ? '' : `?${search}`}`;
+  const init: RequestInit = {
+    method: 'GET',
+    headers: { accept: 'application/json', ...options.headers },
+    ...(callOptions.signal === undefined ? {} : { signal: callOptions.signal }),
+  };
+
+  const response = await doFetch(url, init);
+  if (!response.ok)
+    throw new QueryRequestFailedError(name, response.status, await problemOf(response));
+  const body: unknown = await response.json();
+  return body;
+}
+
+/**
+ * Input as a query string. Keys are sorted so the same input always produces the
+ * same URL — a GET is a cache key, and an unstable one caches nothing.
+ */
+function searchOf(input: unknown): string {
+  if (!isJsonObject(input)) return '';
+  const params = new URLSearchParams();
+  for (const key of Object.keys(input).sort()) {
+    const value = input[key];
+    if (value === undefined || value === null) continue;
+    for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
+      params.append(key, typeof item === 'object' ? JSON.stringify(item) : String(item));
+    }
+  }
+  return params.toString();
+}
+
+/** `application/problem+json`, or nothing when a proxy answered instead of the app. */
+async function problemOf(response: Response): Promise<Record<string, unknown>> {
+  const body: unknown = await response.json().catch(() => null);
+  return isJsonObject(body) ? body : {};
+}

package/src/errors.ts

@@ -0,0 +1,203 @@
+/** Every failure @ultimat3/query can produce, one subclass per stable code. */
+import { assertNever, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import type { SurfaceDenial } from '@ultimat3/policy';
+
+const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
+
+/** One class, one code: core owns the cursor codec, so core owns `X_CURSOR_INVALID`. */
+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_MATCHER_UNSUPPORTED: 'live query shape cannot be patched incrementally',
+  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_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',
+};
+
+/**
+ * Codes `@ultimat3/action` owns that this package only throws. Both describe an action's job —
+ * enforcing an input schema, and speaking the typed RPC wire — so action declares the title and
+ * query never re-declares it: two copies of a title are two titles, one of which is stale.
+ */
+export const QUERY_BORROWED_ERROR_CODES = ['X_INPUT_INVALID', 'X_RPC_FAILED'] as const;
+
+// One unconditional call: a presence guard would turn "another package claims one of these codes"
+// from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(OWNED_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+function denialCode(denial: SurfaceDenial): string {
+  switch (denial.surface) {
+    case 'http':
+      return denial.problem.code;
+    case 'live':
+    case 'job':
+      return denial.code;
+    case 'mcp':
+      return denial.content[0]?.text.split(':')[0] ?? 'X_FORBIDDEN';
+    default:
+      return assertNever(denial);
+  }
+}
+
+function denialReason(denial: SurfaceDenial): string {
+  switch (denial.surface) {
+    case 'http':
+      return denial.problem.detail;
+    case 'live':
+    case 'job':
+      return denial.reason;
+    case 'mcp':
+      return denial.content[0]?.text ?? 'denied';
+    default:
+      return assertNever(denial);
+  }
+}
+
+/**
+ * An authz denial from `guard()`. 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.
+ */
+export class QueryDeniedError extends UltimateError {
+  readonly denial: SurfaceDenial;
+
+  constructor(query: string, denial: SurfaceDenial) {
+    const code = denialCode(denial);
+    super({
+      code,
+      cause: `${query} denied: ${denialReason(denial)}`,
+      fix: `x policy explain ${query} --json   # shows which clause decided and why`,
+      docs: docs(code),
+    });
+    this.denial = denial;
+  }
+}
+
+/** Thrown when a read is used before `registerQueries()` gave it a name. */
+export class QueryUnregisteredError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_QUERY_UNREGISTERED',
+      cause: 'a query was used before it was registered, so it has no name',
+      fix: "call registerQueries(await import('./live')) at boot, before serving reads",
+      docs: docs('X_QUERY_UNREGISTERED'),
+    });
+  }
+}
+
+/**
+ * Thrown when a projection is handed something that never came out of `query()`.
+ * The declaration is private to `read.ts`, so an object that merely looks like a
+ * query has no `sql` to build and no policy to evaluate — refusing it here is how
+ * "there is one read path" stays true at runtime, not just in the types.
+ */
+export class QueryForeignError extends UltimateError {
+  constructor(name: string) {
+    super({
+      code: 'X_QUERY_FOREIGN',
+      cause: `"${name === '' ? 'anonymous' : name}" is not a query built by query()`,
+      fix: "declare it as `export const name = query({ input, policy, sql })` from '@ultimat3/query'",
+      docs: docs('X_QUERY_FOREIGN'),
+    });
+  }
+}
+
+export class QueryDuplicateError extends UltimateError {
+  constructor(name: string) {
+    super({
+      code: 'X_QUERY_DUPLICATE',
+      cause: `two queries are registered under the name "${name}"`,
+      fix: 'rename one export — query names are globally unique: x queries list --json',
+      docs: docs('X_QUERY_DUPLICATE'),
+    });
+  }
+}
+
+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`,
+      docs: docs('X_QUERY_POLICY_MISSING'),
+    });
+  }
+}
+
+/**
+ * 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
+ * old behaviour, `String(undefined)`, signed `"undefined"` into every cursor the read issued.
+ */
+export class QueryNotPageableError extends UltimateError {
+  constructor(entity: string | undefined) {
+    const subject = entity === undefined ? 'this read' : `"${entity}"`;
+    super({
+      code: 'X_QUERY_NOT_PAGEABLE',
+      cause: `a row from ${subject} has no "id", so a cursor cannot name its position`,
+      fix: `return the primary key from the query's sql: db.${entity ?? 'rows'}.select({ id: true, … })`,
+      docs: docs('X_QUERY_NOT_PAGEABLE'),
+    });
+  }
+}
+
+/** The honest fallback: the matcher refuses to guess rather than patch wrongly. */
+export class MatcherUnsupportedError extends UltimateError {
+  constructor(name: string, feature: string) {
+    super({
+      code: 'X_MATCHER_UNSUPPORTED',
+      cause: `live query "${name}" uses ${feature}, which the incremental matcher cannot patch`,
+      fix: `set \`live: false\` and poll, or reshape the query to equality filters + orderBy + limit`,
+      docs: docs('X_MATCHER_UNSUPPORTED'),
+    });
+  }
+}
+
+export class QueryInputInvalidError extends UltimateError {
+  constructor(name: string, detail: string) {
+    super({
+      code: 'X_INPUT_INVALID',
+      cause: `input for query "${name}" failed validation: ${detail}`,
+      fix: `x queries describe ${name} --json  # prints the expected input schema`,
+      docs: docs('X_INPUT_INVALID'),
+    });
+  }
+}
+
+/** The `problem+json` fields a failing read can send back. All optional: a proxy sends none. */
+export interface QueryProblem {
+  readonly code?: unknown;
+  readonly cause?: unknown;
+  readonly detail?: unknown;
+  readonly fix?: unknown;
+  readonly docs?: unknown;
+}
+
+/**
+ * The typed client's failure. A `problem+json` body is re-thrown verbatim — the
+ * server already said what broke and how to fix it, and inventing a second story
+ * here would bury it. Anything else answered instead of the app, so it is
+ * `X_RPC_FAILED` and the fix line points at the gateway.
+ */
+export class QueryRequestFailedError extends UltimateError {
+  constructor(name: string, status: number, problem: QueryProblem = {}) {
+    const code = text(problem.code) ?? 'X_RPC_FAILED';
+    super({
+      code,
+      cause: text(problem.cause) ?? text(problem.detail) ?? `${name} returned HTTP ${status}`,
+      fix:
+        text(problem.fix) ??
+        `check the gateway in front of the app, then: x queries describe ${name} --json`,
+      docs: text(problem.docs) ?? docs(code),
+    });
+  }
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/facade.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+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';
+
+/**
+ * `self` is a thunk on purpose: the façade is attached while the query is still
+ * being assembled, so every method resolves the query when it is called, not now.
+ */
+export function facadeFor<TInput extends StandardSchemaV1, TRow extends object>(
+  def: QueryDef<TInput, TRow>,
+  self: () => Query<TInput, TRow>,
+): QueryFacade<TInput, TRow> {
+  return {
+    input: def.input,
+    policy: def.policy,
+    ...(def.cache === undefined ? {} : { cache: def.cache }),
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    // `.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 }),
+    // A page is the read's own answer, not a helper someone has to import: the
+    // 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(self()),
+    client: (options) => queryClientMethodFor(queryName(self()), options),
+  };
+}