@ultimat3/query 1.0.0

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Public API of @ultimat3/query: reads, live reads, and the tools around them.
+ *
+ * `sql` is deliberately absent. A query's declaration lives in `read.ts`'s private
+ * store, and `sourceFor` is the only thing that reads it — so no adapter can parse,
+ * authorize or execute on its own. One authz system, structurally.
+ */
+
+/** 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 {
+  cacheKeyFor,
+  getReadCache,
+  invalidateQueryTags,
+  MemoryReadCache,
+  readThrough,
+  requestMemo,
+  setReadCache,
+} from './cache';
+export type {
+  FetchLike,
+  QueryCallOptions,
+  QueryClientMethod,
+  QueryClientOptions,
+} from './client';
+export { queryClientMethodFor } from './client';
+export type { QueryProblem } from './errors';
+export {
+  CursorInvalidError,
+  MatcherUnsupportedError,
+  QueryDeniedError,
+  QueryDuplicateError,
+  QueryForeignError,
+  QueryInputInvalidError,
+  QueryNotPageableError,
+  QueryPolicyMissingError,
+  QueryRequestFailedError,
+  QueryUnregisteredError,
+} from './errors';
+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';
+/**
+ * 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
+ * for one is a second way to do the thing `.page()` already does. The codec is
+ * `@ultimat3/core`'s — one place to encode, decode or re-key a cursor.
+ */
+export type { Page, PaginateArgs } from './pagination';
+export type { QueryPolicy, QuerySubject, QuerySurface } from './policy-gate';
+export { actorOf, guard, policyCapability } from './policy-gate';
+export type {
+  AnyQuery,
+  Query,
+  QueryCache,
+  QueryDef,
+  QueryDescriptor,
+  QueryFacade,
+  QueryMcp,
+  QueryOptions,
+  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,
+  listQueries,
+  registerQueries,
+  registerQuery,
+  resetRegistry,
+} from './registry';
+export type { Filter, FilterOp, OrderKey, QueryShape, SeekKey } from './shape';
+export { compareRows, compareValues, matchesFilter, matchesFilters, seekKeyOf } 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';
+export type { ExplainResult, QuerySqlInfo } from './sql';
+export { describeSql, explain } from './sql';

package/src/live.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ */
+import type { Ctx } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Patch } from './matcher';
+import { assertMatchable } from './matcher';
+import type { QueryPolicy, QuerySubject } from './policy-gate';
+import { guard } from './policy-gate';
+import type { Query } from './query';
+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
+ * the reconnect path is this framework's biggest identified risk.
+ *
+ * Tradeoff: a cursor is not a snapshot. Resuming re-runs the *bounded* query
+ * (`limit` rows from the sort key onward) instead of replaying a change log, so
+ * the server keeps no per-subscriber history and reconnect costs one indexed
+ * keyset read. The price: changes to rows the client holds but that sort *before*
+ * the cursor cannot be detected from the cursor alone, so any epoch change —
+ * new build, policy change, schema change — forces a full refetch rather than a
+ * resume. We buy bounded server memory with an occasional full page fetch.
+ */
+export interface LiveCursor {
+  /** Build/policy generation. A mismatch means refetch, never resume. */
+  readonly epoch: string;
+  readonly queryHash: string;
+  /** Monotonic per subscription; bumps once per applied patch batch. */
+  readonly version: number;
+  /** Sort-key values of the last row the client holds, plus its id tiebreak. */
+  readonly seek: SeekKey | null;
+  readonly rows: number;
+}
+
+export type ResumeMode = 'resume' | 'refetch';
+
+export interface ResumePlan {
+  readonly mode: ResumeMode;
+  readonly reason: string;
+  /** Present when `mode === 'resume'`: where the bounded re-read starts. */
+  readonly seek: SeekKey | null;
+}
+
+export interface LiveQuery {
+  readonly name: string;
+  readonly queryHash: string;
+  readonly shape: QueryShape;
+  /** Entities and cache tags this read depends on — the change-feed filter. */
+  readonly reads: readonly string[];
+  readonly policy: QueryPolicy;
+  readonly sqlText: string;
+  readonly limit: number | null;
+  /** Per-subscriber authorization. Called on subscribe *and* on every fanout. */
+  authorize(subject: QuerySubject): Promise<void>;
+  initialCursor(rows: readonly object[]): LiveCursor;
+  /** `tail` is the last row of the window after the patches applied, if any. */
+  advance(cursor: LiveCursor, patches: readonly Patch<object>[], tail?: object): LiveCursor;
+  resume(cursor: LiveCursor): ResumePlan;
+}
+
+export interface ToLiveOptions {
+  readonly ctx?: Ctx;
+  /** Overrides the process epoch. Tests pin it; the server derives it from the build. */
+  readonly epoch?: string;
+  /**
+   * `false` builds the descriptor with **no subject at all** — the shape, the SQL text and the
+   * matcher, and nothing that decided about an actor. Only a sync node passes it, and only for
+   * the window it shares across every subscriber of one `(query, input)`: a descriptor built
+   * under the first subscriber's authority and then cached by query id is the first subscriber's
+   * entitlements becoming everyone's. `authorize` below is still the subscribe-time decision and
+   * still runs per subscriber, so this removes no check — it removes a *shared* one.
+   */
+  readonly enforce?: boolean;
+}
+
+/** Changing the build changes the epoch, which forces reconnects to refetch. */
+export function liveEpoch(): string {
+  return Bun.env['X_BUILD_ID'] ?? 'dev';
+}
+
+export async function toLiveQuery<TInput extends StandardSchemaV1, TRow extends object>(
+  target: Query<TInput, TRow>,
+  input: unknown,
+  options: ToLiveOptions = {},
+): Promise<LiveQuery> {
+  const name = queryName(target);
+  const source = await sourceFor(target, input, {
+    ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
+    ...(options.enforce === undefined ? {} : { enforce: options.enforce }),
+    surface: 'live',
+  });
+  const shape = source.shape();
+  // Fail at subscribe time, not on the first change event nobody can patch.
+  assertMatchable(name, shape);
+
+  const epoch = options.epoch ?? liveEpoch();
+  const hash = queryHash(name, input);
+  const reads = [...new Set([shape.entity, ...tagKeys(target.cache?.tags ?? [])])].sort();
+  // The query's own policy object, not a copy: the same authz a direct read runs.
+  const policy = target.policy;
+
+  return {
+    name,
+    queryHash: hash,
+    shape,
+    reads,
+    policy,
+    sqlText: source.toSQL().sql,
+    limit: shape.limit,
+    authorize: async (subject) => {
+      guard(policy, subject, 'live');
+    },
+    initialCursor: (rows) => ({
+      epoch,
+      queryHash: hash,
+      version: 0,
+      seek: seekOf(rows[rows.length - 1], shape),
+      rows: rows.length,
+    }),
+    advance: (cursor, patches, tail) => advanceCursor(cursor, patches, shape, tail),
+    resume: (cursor) => planResume(cursor, epoch, hash),
+  };
+}
+
+/** Cursor arithmetic kept pure so the sync node can replay it deterministically. */
+export function advanceCursor(
+  cursor: LiveCursor,
+  patches: readonly Patch<object>[],
+  shape: QueryShape,
+  tail?: object,
+): LiveCursor {
+  let rows = cursor.rows;
+  for (const patch of patches) {
+    if (patch.kind === 'add') rows += 1;
+    if (patch.kind === 'remove') rows = Math.max(0, rows - 1);
+  }
+  const seek = tail === undefined ? cursor.seek : seekOf(tail, shape);
+  return { ...cursor, version: cursor.version + 1, rows, seek };
+}
+
+export function planResume(cursor: LiveCursor, epoch: string, hash: string): ResumePlan {
+  if (cursor.epoch !== epoch) {
+    return { mode: 'refetch', reason: 'epoch changed (new build, policy or schema)', seek: null };
+  }
+  if (cursor.queryHash !== hash) {
+    return { mode: 'refetch', reason: 'query arguments changed', seek: null };
+  }
+  if (cursor.seek === null) {
+    return { mode: 'refetch', reason: 'no sort key held', seek: null };
+  }
+  return { mode: 'resume', reason: 'bounded keyset re-read', seek: cursor.seek };
+}
+
+/** The sort-key values of a row under the query's ordering, id as the tiebreak. */
+export function seekOf(row: object | undefined, shape: QueryShape): SeekKey | null {
+  return row === undefined ? null : seekKeyOf(row, shape);
+}

package/src/matcher.ts

@@ -0,0 +1,126 @@
+/**
+ * The incremental matcher: given one change event, decide whether a live query's
+ * result set moves and emit the minimal patch. Supported shapes are equality-ish
+ * filters + orderBy + limit; anything else throws X_MATCHER_UNSUPPORTED, because
+ * an honest refusal beats a silently wrong result set.
+ */
+import { MatcherUnsupportedError } from './errors';
+import type { QueryShape } from './shape';
+import { compareRows, matchesFilters } from './shape';
+import { columnOf } from './stable';
+
+export type ChangeOp = 'insert' | 'update' | 'delete';
+
+export interface ChangeEvent<TRow extends object> {
+  readonly entity: string;
+  readonly op: ChangeOp;
+  readonly row: TRow;
+  /** Previous image, required for `update` to know whether the row was in the set. */
+  readonly before?: TRow;
+}
+
+export type Patch<TRow extends object> =
+  | { readonly kind: 'add'; readonly position: number; readonly row: TRow }
+  | { readonly kind: 'update'; readonly position: number; readonly row: TRow }
+  | { readonly kind: 'remove'; readonly position: number; readonly id: string }
+  /**
+   * The window lost a row and the tail is unknown to the client: ask the server
+   * for rows from `from` onward. Only reachable for `limit`ed queries.
+   */
+  | { readonly kind: 'refill'; readonly from: number };
+
+/** Filter operators the matcher can evaluate incrementally. */
+const SUPPORTED_OPS = new Set(['=', '!=', 'in', '>', '>=', '<', '<=']);
+
+export function assertMatchable(name: string, shape: QueryShape): void {
+  if (shape.unsupported.length > 0) {
+    throw new MatcherUnsupportedError(name, shape.unsupported.join(', '));
+  }
+  for (const filter of shape.filters) {
+    if (!SUPPORTED_OPS.has(filter.op)) {
+      throw new MatcherUnsupportedError(name, `filter operator "${filter.op}"`);
+    }
+  }
+}
+
+/**
+ * `rows` is the subscriber's current, ordered result set. Patches apply in order.
+ */
+export function match<TRow extends object>(
+  name: string,
+  shape: QueryShape,
+  rows: readonly TRow[],
+  event: ChangeEvent<TRow>,
+): readonly Patch<TRow>[] {
+  assertMatchable(name, shape);
+  if (event.entity !== shape.entity) return [];
+
+  const id = idOf(event.row);
+  const index = rows.findIndex((row) => idOf(row) === id);
+  const inSet = index >= 0;
+  const belongs = event.op !== 'delete' && matchesFilters(event.row, shape.filters);
+
+  if (event.op === 'delete' || (inSet && !belongs)) {
+    return inSet ? removeAt(shape, index, id, true) : [];
+  }
+  if (!belongs) return [];
+  if (!inSet) return insert(shape, rows, event.row);
+
+  // Present and still matching: a change to an ordering column is a move, not an update.
+  const current = rows[index];
+  const moved =
+    shape.orderBy.length > 0 &&
+    current !== undefined &&
+    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)];
+  return [...removeAt<TRow>(shape, index, id, false), ...insert(shape, without, event.row)];
+}
+
+function insert<TRow extends object>(
+  shape: QueryShape,
+  rows: readonly TRow[],
+  row: TRow,
+): readonly Patch<TRow>[] {
+  const position = positionFor(shape, rows, row);
+  // Sorted past the end of a full window: the row exists but nobody sees it.
+  if (shape.limit !== null && position >= shape.limit) return [];
+  const patches: Patch<TRow>[] = [{ kind: 'add', position, row }];
+  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) });
+    }
+  }
+  return patches;
+}
+
+function removeAt<TRow extends object>(
+  shape: QueryShape,
+  index: number,
+  id: string,
+  refill: boolean,
+): readonly Patch<TRow>[] {
+  const patches: Patch<TRow>[] = [{ kind: 'remove', position: index, id }];
+  // A limited window may now be one row short, and the tail lives on the server.
+  if (refill && shape.limit !== null) patches.push({ kind: 'refill', from: shape.limit - 1 });
+  return patches;
+}
+
+/** Insertion index under the query's ordering; append when the query is unordered. */
+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);
+  return found === -1 ? rows.length : found;
+}
+
+function idOf(row: object): string {
+  const value = columnOf(row, 'id');
+  return typeof value === 'string' ? value : String(value);
+}

package/src/mcp-tool.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 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';
+import { listQueries } from './registry';
+
+export interface QueryToolReadOptions {
+  readonly ctx?: Ctx;
+  /** The agent behind the call. `null` is the signed-out caller. */
+  readonly actor?: Actor | null;
+}
+
+export interface QueryToolDescriptor {
+  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;
+  readonly inputSchema: JsonSchema;
+  /** Always false: a query reads. Drives the rate-limit bucket in @ultimat3/mcp. */
+  readonly mutates: false;
+  read(input: unknown, options?: QueryToolReadOptions): Promise<readonly object[]>;
+}
+
+export function toQueryTool(target: AnyQuery): QueryToolDescriptor {
+  const name = queryName(target);
+  return {
+    name: toToolName(name),
+    description: target.mcp?.description ?? name,
+    query: name,
+    policy: target.policy,
+    inputSchema: toMcpInputSchema(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 }),
+      });
+      return source.execute();
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function isExposed(target: AnyQuery): boolean {
+  return target.mcp?.expose === true;
+}
+
+/** 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

@@ -0,0 +1,38 @@
+/**
+ * The one naming rule for reads: a query's export name derives its HTTP path and
+ * its MCP tool name. Pure string math, so the browser client derives the same URL
+ * without importing a byte of server code. Ported rather than imported from
+ * @ultimat3/action: that package is the same tier, and tiers never go sideways.
+ */
+
+/** Every read is served under one prefix, so a router can claim it in one rule. */
+const QUERY_PREFIX = '/_x/query';
+
+/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
+export function splitWords(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s_-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/** `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 function derivePath(name: string): string {
+  return `${QUERY_PREFIX}/${toKebabCase(name)}`;
+}
+
+/** MCP tool names are `snake_case`: `liveFeed` -> `live_feed`. */
+export function toToolName(name: string): string {
+  return splitWords(name).join('_');
+}

package/src/pagination.ts

@@ -0,0 +1,81 @@
+/**
+ * Cursor pagination, and only cursor pagination.
+ *
+ * OFFSET IS NOT AVAILABLE ON PURPOSE: `offset` makes the database count rows it
+ * will throw away (O(offset) per page), and any insert or delete before the
+ * offset shifts every later page, so users see duplicates and holes. A keyset
+ * cursor is O(log n) on the ordering index and stable under concurrent writes.
+ *
+ * The codec is `@ultimat3/core`'s. This file only decides what a cursor is bound
+ * to — `queryHash(name, input)` — so one read's cursor cannot page another.
+ */
+import { decodeCursor, encodeCursor } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Query, SourceOptions } from './query';
+import { queryHash, queryName, sourceFor } from './query';
+import type { QueryShape, SeekKey } from './shape';
+import { seekKeyOf } from './shape';
+import type { SqlSource } from './source';
+import { isAfterKey } from './source';
+
+export interface Page<TRow> {
+  readonly rows: readonly TRow[];
+  readonly endCursor: string | null;
+  readonly hasNextPage: boolean;
+}
+
+export interface PaginateArgs extends SourceOptions {
+  readonly first: number;
+  readonly after?: string;
+}
+
+/**
+ * One page. Push-down when the source implements `seek()`; otherwise the rows are
+ * sliced after execution and the source is doing more work than it should.
+ */
+export async function paginate<TInput extends StandardSchemaV1, TRow extends object>(
+  target: Query<TInput, TRow>,
+  input: unknown,
+  args: PaginateArgs,
+): Promise<Page<TRow>> {
+  const name = queryName(target);
+  const hash = queryHash(name, input);
+  // The scope is this read plus these arguments: a cursor from anywhere else is
+  // already `X_CURSOR_INVALID` by the time it gets here.
+  const decoded = args.after === undefined ? null : decodeCursor(args.after, hash);
+  const after: SeekKey | null = decoded === null ? null : { key: decoded.key, id: decoded.id };
+  const base = await sourceFor(target, input, args);
+  const shape = base.shape();
+
+  // Fetch one extra row: its presence *is* `hasNextPage`, with no count query.
+  const window = args.first + 1;
+  const source: SqlSource<object> = base.seek === undefined ? base : base.seek(after, window);
+  const executed = await source.execute();
+  const scoped = base.seek === undefined ? sliceAfter(executed, after, shape) : executed;
+  // The source came from this query's own `sql()`, so its rows are TRow.
+  const rows = scoped.slice(0, args.first) as unknown as readonly TRow[];
+  const last = rows[rows.length - 1];
+  const seek = last === undefined ? null : seekKeyOf(last, shape);
+
+  return {
+    rows,
+    endCursor: seek === null ? null : encodeCursor({ scope: hash, key: seek.key, id: seek.id }),
+    hasNextPage: scoped.length > args.first,
+  };
+}
+
+/**
+ * The cursor names a POSITION in the ordering, so the fallback filters by that position — the
+ * same comparison `Builder.seek()` pushes into SQL. Locating the cursor's row by id instead
+ * looks equivalent and is not: the row can be gone by the next request, `findIndex` answers -1,
+ * and every row from the top comes back as page two. Under a delete between two pages that is a
+ * silent restart, which is the failure keyset pagination exists to make impossible.
+ */
+function sliceAfter(
+  rows: readonly object[],
+  after: SeekKey | null,
+  shape: QueryShape,
+): readonly object[] {
+  if (after === null) return rows;
+  return rows.filter((row) => isAfterKey(row, after, shape.orderBy));
+}

package/src/policy-gate.ts

@@ -0,0 +1,66 @@
+/**
+ * The single point of contact with @ultimat3/policy. A live query evaluates its
+ * policy **per subscriber**, never once at subscribe time for everyone — so this
+ * gate is called on every fanout decision and its result is never cached.
+ */
+
+import type { Actor, Ctx } from '@ultimat3/core';
+import { assertNever, isAnonymous } from '@ultimat3/core';
+import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
+import { enforce } from '@ultimat3/policy';
+import { QueryDeniedError } from './errors';
+
+/** Policies are opaque here: we evaluate them, we never introspect their rules. */
+export type QueryPolicy = Policy<unknown>;
+
+export type QuerySurface = 'server' | 'http' | 'live';
+
+export interface QuerySubject {
+  readonly actor: Actor | null;
+  readonly input: unknown;
+  /**
+   * The already-loaded row a row-level rule decides about — the live row gate supplies it
+   * per subscriber per row. Omitted for a subscribe-time or whole-query decision. It is a
+   * field of its own and never folded into `input`: the predicate reads `args.row`.
+   */
+  readonly row?: unknown;
+  readonly ctx: Ctx;
+  readonly query: string;
+}
+
+export function guard(policy: QueryPolicy, subject: QuerySubject, surface: QuerySurface): void {
+  const denial = enforce(policySurface(surface), policy, {
+    input: subject.input,
+    actor: subject.actor,
+    row: subject.row,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new QueryDeniedError(subject.query, denial);
+}
+
+/** A direct server read is the job surface: no request, no socket to close. */
+function policySurface(surface: QuerySurface): PolicySurface {
+  switch (surface) {
+    case 'http':
+      return 'http';
+    case 'live':
+      return 'live';
+    case 'server':
+      return 'job';
+    default:
+      return assertNever(surface);
+  }
+}
+
+/**
+ * Core models "nobody" as an anonymous actor; policy models it as `null`, which is
+ * what turns a missing session into `X_UNAUTHENTICATED` instead of a bare denial.
+ */
+export function actorOf(ctx: Ctx): Actor | null {
+  return isAnonymous(ctx.actor) ? null : ctx.actor;
+}
+
+/** The capability a read requires, for manifests and the `/_x` dashboard. */
+export function policyCapability(policy: QueryPolicy): string {
+  return policy.label;
+}