@ultimat3/query 1.0.0

package/src/query.ts

@@ -0,0 +1,221 @@
+/**
+ * The `query` primitive: a policy-checked read, optionally live, declared once.
+ * Row types are inferred from the `SqlSource` the `sql:` function returns, so a
+ * component gets the real row shape without a second declaration. Every projection
+ * in this package (live subscription, MCP tool, typed client) reads this
+ * declaration through `read.ts` — none of them re-declare it.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import type { Actor, Ctx } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { QueryClientMethod, QueryClientOptions } from './client';
+import { facadeFor } from './facade';
+import type { LiveQuery, ToLiveOptions } from './live';
+import type { QueryToolDescriptor } from './mcp-tool';
+import type { Page, PaginateArgs } from './pagination';
+import type { QueryPolicy, QuerySurface } from './policy-gate';
+import { policyCapability } from './policy-gate';
+import { hasDef, queryName, runQuery, stashDef } from './read';
+import type { SqlSource } from './source';
+import { fingerprint } from './stable';
+import { tagKeys } from './tags';
+
+export interface QueryCache {
+  /** Tags this read depends on. An action's `invalidates` drops exactly these keys. */
+  readonly tags: readonly CacheTag[];
+  readonly ttlMs?: number;
+}
+
+export interface QueryMcp {
+  /** Opt-in: a read reaches an agent only when it says so. Silence exposes nothing. */
+  readonly expose: boolean;
+  /** Contract text, not UI text — see `ActionMcp.description` for why it stays outside `t()`. */
+  readonly description?: string;
+  /**
+   * Roles that may SEE the projected tool — a catalog audience, not an authz rule; the `policy`
+   * still decides every call. A caller whose role is not named gets ToolNotFound, never
+   * Forbidden. See `ActionMcp.visibleTo`, which this mirrors exactly.
+   */
+  readonly visibleTo?: readonly string[];
+}
+
+export interface QueryDef<TInput extends StandardSchemaV1, TRow extends object> {
+  readonly input: TInput;
+  readonly policy: QueryPolicy;
+  /** `true` makes the read subscribable — see `toLiveQuery`. */
+  readonly live?: boolean;
+  sql(input: InferOutput<TInput>, ctx: Ctx): SqlSource<TRow>;
+  readonly cache?: QueryCache;
+  readonly mcp?: QueryMcp;
+}
+
+export interface QueryOptions {
+  readonly ctx?: Ctx;
+  readonly surface?: QuerySurface;
+  /** Skips the cache tiers for this call. Live fanout always reads fresh. */
+  readonly fresh?: boolean;
+  /**
+   * Run as someone else. Omitted keeps the context's own actor; `null` is the
+   * signed-out caller. The rest of the context is untouched, so impersonation
+   * stays on the one read path instead of forking a second one.
+   */
+  readonly actor?: Actor | null;
+}
+
+export interface SourceOptions extends QueryOptions {
+  /**
+   * `false` for developer tooling (`explain`, admin-gated) and for the shared, subject-less
+   * window a sync node builds once per `(query, input)` — see `ToLiveOptions.enforce`. Both are
+   * reads with no subscriber to decide about; every other caller leaves it alone.
+   */
+  readonly enforce?: boolean;
+}
+
+export interface QueryDescriptor {
+  readonly kind: 'query';
+  readonly name: string;
+  readonly live: boolean;
+  readonly capability: string;
+  readonly tags: readonly string[];
+  readonly ttlMs: number | null;
+}
+
+/**
+ * Schema-erased view of a definition, held only by `read.ts`'s private store —
+ * never reachable from a query. Method syntax is load-bearing: bivariant
+ * parameters are what make the erasure assignable.
+ */
+export interface AnyQueryDef {
+  readonly input: StandardSchemaV1;
+  readonly policy: QueryPolicy;
+  readonly live?: boolean;
+  sql(input: unknown, ctx: Ctx): SqlSource<object>;
+  readonly cache?: QueryCache;
+  readonly mcp?: QueryMcp;
+}
+
+export interface AnyQuery {
+  readonly kind: 'query';
+  readonly name: string;
+  /** Declared `live: true`. The subscription itself is `live()`. */
+  readonly isLive: boolean;
+  /** The declaration, minus `sql`: readable, and never a way to run it. */
+  readonly input: StandardSchemaV1;
+  readonly policy: QueryPolicy;
+  readonly cache?: QueryCache;
+  readonly mcp?: QueryMcp;
+  describe(): QueryDescriptor;
+  /** A twin under another name. Registration names through `named`. */
+  named(name: string): AnyQuery;
+  /** Read as this actor. Same read path, only the context's actor changes. */
+  as(actor: Actor | null, input: unknown, options?: QueryOptions): Promise<readonly object[]>;
+  /** One bounded page plus the signed cursor that continues it. There is no `offset`. */
+  page(input: unknown, args: PaginateArgs): Promise<Page<object>>;
+  live(input: unknown, options?: ToLiveOptions): Promise<LiveQuery>;
+  tool(): QueryToolDescriptor;
+}
+
+export interface Query<
+  TInput extends StandardSchemaV1 = StandardSchemaV1,
+  TRow extends object = Record<string, unknown>,
+> extends AnyQuery {
+  /** Callable server-side with the same types the client and the MCP tool see. */
+  (input: InferInput<TInput>, options?: QueryOptions): Promise<readonly TRow[]>;
+  readonly input: TInput;
+  named(name: string): Query<TInput, TRow>;
+  as(
+    actor: Actor | null,
+    input: InferInput<TInput>,
+    options?: QueryOptions,
+  ): Promise<readonly TRow[]>;
+  page(input: InferInput<TInput>, args: PaginateArgs): Promise<Page<TRow>>;
+  live(input: InferInput<TInput>, options?: ToLiveOptions): Promise<LiveQuery>;
+  /**
+   * Typed against this query's input and row type, which is the whole point of it —
+   * so it lives here and not on the schema-erased `AnyQuery` view.
+   */
+  client(options: QueryClientOptions): QueryClientMethod<TInput, TRow>;
+}
+
+/** The fluent half of a query: lifted declaration plus one method per projection. */
+export type QueryFacade<TInput extends StandardSchemaV1, TRow extends object> = Pick<
+  Query<TInput, TRow>,
+  'input' | 'policy' | 'cache' | 'mcp' | 'as' | 'page' | 'live' | 'tool' | 'client'
+>;
+
+export function query<TInput extends StandardSchemaV1, TRow extends object>(
+  def: QueryDef<TInput, TRow>,
+): Query<TInput, TRow> {
+  return build(def, '');
+}
+
+/**
+ * Structural, not nominal: an object only counts as a query if `query()` built it,
+ * because only then does a declaration exist for `sourceFor` to read. A look-alike
+ * with `kind: 'query'` never reaches the registry or a projection.
+ */
+export function isQuery(value: unknown): value is AnyQuery {
+  return (
+    typeof value === 'function' && (value as { kind?: unknown }).kind === 'query' && hasDef(value)
+  );
+}
+
+/**
+ * Stamp the export name onto the query the app declared, rather than handing back a
+ * differently-named copy of it. `import { liveFeed } from './live'` is then the query
+ * that projects — `liveFeed.tool()` after boot, with nothing to remember. The same
+ * rule `nameAction` follows; naming twice is the one case that still needs a twin.
+ */
+export function nameQuery<Q extends AnyQuery>(target: Q, name: string): Q {
+  if (target.name === name) return target;
+  if (target.name.length > 0) return target.named(name) as Q;
+  Object.defineProperty(target, 'name', { value: name, configurable: true });
+  return target;
+}
+
+function build<TInput extends StandardSchemaV1, TRow extends object>(
+  def: QueryDef<TInput, TRow>,
+  name: string,
+): Query<TInput, TRow> {
+  const callable = (
+    input: InferInput<TInput>,
+    options: QueryOptions = {},
+  ): Promise<readonly TRow[]> => runQuery(self, input, options);
+
+  const self: Query<TInput, TRow> = Object.assign(callable, {
+    kind: 'query' as const,
+    isLive: def.live === true,
+    describe: (): QueryDescriptor => describeQuery(self),
+    named: (next: string): Query<TInput, TRow> => build(def, next),
+    ...facadeFor(def, () => self),
+  });
+  // `name` on a function is non-writable, so Object.assign cannot set it.
+  Object.defineProperty(self, 'name', { value: name, configurable: true });
+  // The declaration goes to `read.ts` and stays there: `sql` has no other reader.
+  stashDef(self, def);
+  return self;
+}
+
+export function describeQuery(target: AnyQuery): QueryDescriptor {
+  return {
+    kind: 'query',
+    name: queryName(target),
+    live: target.isLive,
+    capability: policyCapability(target.policy),
+    tags: tagKeys(target.cache?.tags ?? []),
+    ttlMs: target.cache?.ttlMs ?? null,
+  };
+}
+
+/** Stable identity of a query + its arguments. Used for cursors and live keys. */
+export function queryHash(name: string, input: unknown): string {
+  return `${name}:${fingerprint(input)}`;
+}
+
+/**
+ * The read path lives in `read.ts`, next to the declaration store it needs; the
+ * primitive stays the package's one front door for it, so a sibling projection
+ * never has to know where the store happens to sit.
+ */
+export { queryName, runQuery, sourceFor } from './read';

package/src/read.ts

@@ -0,0 +1,143 @@
+/**
+ * The one read path: parse input, evaluate policy, build the source, execute it.
+ * The declaration lives in this module's private store, so `sql` is unreachable
+ * from anywhere else — HTTP, MCP, live, pagination and `.as()` hand `sourceFor` a
+ * payload, and none of them can become a second read path or a second authz path.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import {
+  anonymousActor,
+  createContext,
+  runWithContext,
+  tryUseContext,
+  useContext,
+  withChildContext,
+  withSpan,
+} from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { formatPath, validateAsync } from '@ultimat3/schema';
+import { cacheKeyFor, readThrough } from './cache';
+import { QueryForeignError, QueryInputInvalidError, QueryUnregisteredError } from './errors';
+import { actorOf, guard } from './policy-gate';
+import type { AnyQuery, AnyQueryDef, Query, QueryOptions, SourceOptions } from './query';
+import type { SqlSource } from './source';
+
+/**
+ * Private on purpose. `@ultimat3/query` exports no way to read this back, which is
+ * what makes "the only way to reach `sql` is `sourceFor`" structural rather than a
+ * rule someone has to remember.
+ */
+const DECLARATIONS = new WeakMap<object, AnyQueryDef>();
+
+/** Called once per built query, by `query()` and by every rename it produces. */
+export function stashDef(target: object, def: AnyQueryDef): void {
+  DECLARATIONS.set(target, def);
+}
+
+/** True only for objects this package built — `isQuery` leans on it. */
+export function hasDef(target: object): boolean {
+  return DECLARATIONS.has(target);
+}
+
+/** Internal read of the declaration. Never re-exported from `src/index.ts`. */
+export function defOf(target: AnyQuery): AnyQueryDef {
+  const def = DECLARATIONS.get(target);
+  if (def === undefined) throw new QueryForeignError(target.name);
+  return def;
+}
+
+/** Projections need a stable name; an unregistered query has none yet. */
+export function queryName(target: AnyQuery): string {
+  if (target.name.length === 0) throw new QueryUnregisteredError();
+  return target.name;
+}
+
+/** Validate, authorize, then read — the same three steps on every surface. */
+export function runQuery<TInput extends StandardSchemaV1, TRow extends object>(
+  target: Query<TInput, TRow>,
+  raw: unknown,
+  options: QueryOptions = {},
+): Promise<readonly TRow[]> {
+  return asActor(options, (ctx) => readRows(target, raw, ctx, options));
+}
+
+/**
+ * Validated, authorized `SqlSource` without executing it. `live`, `paginate`,
+ * `explain` and the MCP tool all build on this, so none of them re-implement the
+ * front half and none of them can skip the policy while doing it.
+ */
+export function sourceFor(
+  target: AnyQuery,
+  raw: unknown,
+  options: SourceOptions = {},
+): Promise<SqlSource<object>> {
+  return asActor(options, (ctx) => buildSource(target, raw, ctx, options));
+}
+
+/**
+ * Impersonation, in one place: keep the surrounding context whole — services,
+ * clock, locale, trace — and swap only the actor. Policy models "nobody" as null;
+ * core models it as the anonymous actor. Omitting `actor` touches no context at all.
+ */
+function asActor<T>(options: QueryOptions, run: (ctx: Ctx) => Promise<T>): Promise<T> {
+  if (options.actor === undefined) return run(options.ctx ?? useContext());
+  const patch = { actor: options.actor ?? anonymousActor() };
+  const inChild = (): Promise<T> => run(useContext());
+  const base = options.ctx ?? tryUseContext();
+  return base === undefined
+    ? runWithContext(createContext(patch), inChild)
+    : runWithContext(base, () => withChildContext(patch, inChild));
+}
+
+async function readRows<TInput extends StandardSchemaV1, TRow extends object>(
+  target: Query<TInput, TRow>,
+  raw: unknown,
+  ctx: Ctx,
+  options: QueryOptions,
+): Promise<readonly TRow[]> {
+  const def = defOf(target);
+  const name = queryName(target);
+  const source = await buildSource(target, raw, ctx, options);
+  const read = (): Promise<readonly object[]> => withSpan(`query.${name}`, () => source.execute());
+  // The source came from this query's own `sql()`, so its rows are TRow.
+  if (options.fresh === true || def.cache === undefined) {
+    return (await read()) as readonly TRow[];
+  }
+  const key = cacheKeyFor(name, raw, def.cache.tags);
+  const rows = await readThrough(ctx, key, def.cache.ttlMs ?? null, read);
+  return rows as readonly TRow[];
+}
+
+async function buildSource(
+  target: AnyQuery,
+  raw: unknown,
+  ctx: Ctx,
+  options: SourceOptions,
+): Promise<SqlSource<object>> {
+  const def = defOf(target);
+  const name = queryName(target);
+  const input = await validate(def.input, raw, name);
+  if (options.enforce !== false) {
+    guard(
+      def.policy,
+      { actor: actorOf(ctx), input, ctx, query: name },
+      options.surface ?? 'server',
+    );
+  }
+  return def.sql(input, ctx);
+}
+
+async function validate(schema: StandardSchemaV1, raw: unknown, name: string): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  if (result.issues !== undefined) {
+    const detail = result.issues
+      .map((issue) => {
+        const path = formatPath(issue.path);
+        return path === '' ? issue.message : `${path}: ${issue.message}`;
+      })
+      .join('; ');
+    throw new QueryInputInvalidError(name, detail);
+  }
+  return result.value;
+}

package/src/registry.ts

@@ -0,0 +1,69 @@
+/**
+ * The query registry. Names come from export names, so the manifest, the live
+ * subscription protocol and the `/_x` dashboard all address a read by the same
+ * identifier the source file uses.
+ */
+import { registerPrimitiveRegistrar } from '@ultimat3/core';
+import { QueryDuplicateError, QueryPolicyMissingError } from './errors';
+import type { AnyQuery, QueryDescriptor } from './query';
+import { isQuery, nameQuery } from './query';
+
+const registry = new Map<string, AnyQuery>();
+
+/**
+ * Register one query under an explicit name. The name lands on the query you passed,
+ * so the module's own export is projectable after boot and there is no "use the
+ * return value instead" rule to forget.
+ */
+export function registerQuery<Q extends AnyQuery>(name: string, target: Q): Q {
+  const seated = registry.get(name);
+  if (seated !== undefined) {
+    // Re-registering the SAME object under the SAME name is one registration seen twice, not a
+    // collision: `defineApi` registers a feature module at boot and the framework's module scan
+    // reaches the same declaration file directly, so both arrive at the identical query. Only a
+    // DIFFERENT query under a taken name is the ambiguity `X_QUERY_DUPLICATE` exists to refuse.
+    if (seated !== (target as AnyQuery)) throw new QueryDuplicateError(name);
+    return target;
+  }
+  if (target.policy === undefined || target.policy === null) {
+    throw new QueryPolicyMissingError(name);
+  }
+  const named = nameQuery(target, name);
+  registry.set(name, named);
+  return named;
+}
+
+/** `registerQueries(await import('./live'))` — export names become query names. */
+export function registerQueries(module: Readonly<Record<string, unknown>>): readonly AnyQuery[] {
+  const registered: AnyQuery[] = [];
+  for (const name of Object.keys(module).sort()) {
+    const value = module[name];
+    if (isQuery(value)) registered.push(registerQuery(name, value));
+  }
+  return registered;
+}
+
+// `defineApi` lives in `@ultimat3/action`, which sits on this tier and so cannot import this
+// file. Announcing the registrar in core's table is what lets one `defineApi({ queries })` call
+// register a read without a sideways import — importing the module you pass is what loads this.
+registerPrimitiveRegistrar('query', registerQueries);
+
+export function getQuery(name: string): AnyQuery | undefined {
+  return registry.get(name);
+}
+
+/** Sorted by name — manifest output must not depend on import order. */
+export function listQueries(): readonly AnyQuery[] {
+  return [...registry.entries()]
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([, value]) => value);
+}
+
+export function describeQueries(): readonly QueryDescriptor[] {
+  return listQueries().map((target) => target.describe());
+}
+
+/** Test-only. Production registers once at boot. */
+export function resetRegistry(): void {
+  registry.clear();
+}

package/src/shape.ts

@@ -0,0 +1,111 @@
+/**
+ * The read vocabulary shared by the matcher, the SQL sources, pagination and the
+ * live descriptor. Types only plus two pure predicates — no I/O lives here.
+ */
+import { QueryNotPageableError } from './errors';
+import { columnOf } from './stable';
+
+export type FilterOp = '=' | '!=' | 'in' | '>' | '>=' | '<' | '<=';
+
+export interface Filter {
+  readonly column: string;
+  readonly op: FilterOp;
+  readonly value: unknown;
+}
+
+export interface OrderKey {
+  readonly column: string;
+  readonly direction: 'asc' | 'desc';
+}
+
+/**
+ * The statically-known shape of a read. The incremental matcher works from this,
+ * never from SQL text — parsing SQL back is how frameworks get patches wrong.
+ */
+export interface QueryShape {
+  readonly entity: string;
+  readonly filters: readonly Filter[];
+  readonly orderBy: readonly OrderKey[];
+  readonly limit: number | null;
+  /** Features present in the query that the matcher cannot patch incrementally. */
+  readonly unsupported: readonly string[];
+}
+
+/** Where a page resumes: the sort-key values of the last row plus its id tiebreak. */
+export interface SeekKey {
+  readonly key: readonly unknown[];
+  readonly id: string;
+}
+
+/**
+ * Sort-key values of a row under an ordering, with its id as the final tiebreak.
+ *
+ * A row with no `id` is refused rather than stringified: `String(undefined)` is `"undefined"`,
+ * which every row in the result set then matches, so the cursor names a position that is both
+ * signed and meaningless. The tiebreak is what makes the order total — without it two rows
+ * sharing a sort value straddle a page boundary and one of them is lost.
+ */
+export function seekKeyOf(
+  row: object,
+  shape: { readonly orderBy: readonly OrderKey[]; readonly entity?: string },
+): SeekKey {
+  const id = columnOf(row, 'id');
+  if (id === undefined || id === null) throw new QueryNotPageableError(shape.entity);
+  return {
+    key: shape.orderBy.map((order) => columnOf(row, order.column)),
+    id: typeof id === 'string' ? id : String(id),
+  };
+}
+
+export function matchesFilters(row: object, filters: readonly Filter[]): boolean {
+  return filters.every((filter) => matchesFilter(row, filter));
+}
+
+export function matchesFilter(row: object, filter: Filter): boolean {
+  const actual = columnOf(row, filter.column);
+  switch (filter.op) {
+    case '=':
+      return same(actual, filter.value);
+    case '!=':
+      return !same(actual, filter.value);
+    case 'in':
+      return Array.isArray(filter.value) && filter.value.some((item) => same(actual, item));
+    case '>':
+      return compareValues(actual, filter.value) > 0;
+    case '>=':
+      return compareValues(actual, filter.value) >= 0;
+    case '<':
+      return compareValues(actual, filter.value) < 0;
+    case '<=':
+      return compareValues(actual, filter.value) <= 0;
+    default:
+      return false;
+  }
+}
+
+/** Dates compare by instant, everything else by value. No coercion across types. */
+export function compareValues(a: unknown, b: unknown): number {
+  const left = normalize(a);
+  const right = normalize(b);
+  if (typeof left === 'number' && typeof right === 'number') return left - right;
+  const l = String(left);
+  const r = String(right);
+  return l < r ? -1 : l > r ? 1 : 0;
+}
+
+function normalize(value: unknown): unknown {
+  return value instanceof Date ? value.getTime() : value;
+}
+
+function same(a: unknown, b: unknown): boolean {
+  return compareValues(a, b) === 0 && typeof normalize(a) === typeof normalize(b);
+}
+
+/** Row ordering under an `orderBy` list. Stable, and total when an id key is last. */
+export function compareRows(a: object, b: object, orderBy: readonly OrderKey[]): number {
+  for (const key of orderBy) {
+    const result = compareValues(columnOf(a, key.column), columnOf(b, key.column));
+    if (result !== 0) return key.direction === 'asc' ? result : -result;
+  }
+  return 0;
+}