@rindle/client 0.1.0-rc.5

package/src/query.ts

@@ -0,0 +1,734 @@
+// The fluent, type-safe query builder. It accumulates state immutably and compiles to the
+// Zero-wire {@link Ast} via `.ast()` (which the wasm `Db.query`/a remote server parses).
+//
+// Two runtime Proxies give the requested ergonomics (WASM-CLIENT-DESIGN.md §6):
+//   - `where` is callable (`where(or(...))`) AND a field proxy (`where.closed(false)`);
+//   - `where<Field>(…)` camelCase sugar (`whereClosed(false)`) is intercepted too.
+// Both are fully typed via mapped types + template-literal keys.
+
+import type { Ast, Bound, Condition, CorrelatedSubquery, Dir, ExistsOp, LitValue, OrderPart } from "./ast.ts";
+import { stableKey } from "./key.ts";
+import type { Arg, Cond } from "./operators.ts";
+import { fieldCondition } from "./operators.ts";
+import type { AnyCols, AnyRelationship, AnyTable, ColsMap, ColT, Relationship, RowOf, Schema, TableLike, TableMeta } from "./schema.ts";
+import { isRelationship, SCHEMA } from "./schema.ts";
+import type { ArrayView, SingularArrayView } from "./view.ts";
+
+// ----------------------------- the public Query type -----------------------------
+
+// `One` tracks a top-level `.one()`: it flips `materialize()` from a plural `ArrayView`
+// (`data: R[]`) to a `SingularArrayView` (`data: R | null`). It threads through every chained
+// method so the unwrap survives `.one().where(…)`, etc. Defaults `false` (plural).
+
+type FieldFn<C extends AnyCols, K extends keyof C, Rels, One extends boolean, Sel extends string> = (
+  arg: Arg<ColT<C[K]>>,
+) => Query<C, Rels, One, Sel>;
+
+/** `where.closed(false)`, `where.priority(gt(3))`. */
+type WhereProxy<C extends AnyCols, Rels, One extends boolean, Sel extends string> = {
+  [K in keyof C]: FieldFn<C, K, Rels, One, Sel>;
+};
+
+/** `whereClosed(false)`, `wherePriority(gt(3))`. */
+type WhereSugar<C extends AnyCols, Rels, One extends boolean, Sel extends string> = {
+  [K in keyof C as `where${Capitalize<string & K>}`]: FieldFn<C, K, Rels, One, Sel>;
+};
+
+/** What `materialize()` returns: singular (`R | null`) for a top-level `.one()`, else plural. */
+type MaterializedView<R, One extends boolean> = One extends true ? SingularArrayView<R> : ArrayView<R>;
+
+/**
+ * The result row type of a projection (masking, FRAGMENT-COMPOSITION-DESIGN.md §6 / §10.6).
+ * `Sel` is the union of columns named via `select(...)`. With nothing selected (`Sel = never`)
+ * it stays the full {@link RowOf} — the "no `select` ⇒ all columns" convention, kept and made
+ * type-honest. Once any column is selected, the row is **masked** to exactly those columns, so a
+ * component (its fragment) can read only what it declared. `Pick` only ever *removes* fields, so
+ * narrowing is always sound versus a runtime row that may still carry more.
+ */
+type Projected<C extends AnyCols, Sel extends string> = [Sel] extends [never]
+  ? RowOf<C>
+  : Pick<RowOf<C>, Sel & keyof C>;
+
+interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends string> {
+  /** Present when this local query came from `defineQuery`; used as the remote identity. */
+  readonly name?: string;
+  /** Present when this local query came from `defineQuery`; sent with `name` upstream. */
+  readonly args?: unknown;
+  /** Condition form — consumes `or()`/`and()`/`exists()`/field conditions (AND-ed across calls).
+   *  Filters over the FULL column set (`RowOf<C>`), independent of what's `select`ed/masked. */
+  where(cond: Cond<RowOf<C>>): Query<C, Rels, One, Sel>;
+  orderBy<K extends keyof C>(col: K, dir: Dir): Query<C, Rels, One, Sel>;
+  /** Project a subset of columns (PROJECTION-SUPPORT-DESIGN.md §6, masking §6/§10.6). Chainable
+   *  (each call unions into `Sel`); omit to select all. Drives what the server syncs, what the
+   *  view reports, AND — once any column is named — narrows the result row TYPE to exactly the
+   *  selection (masking). `where`/`orderBy`/`start`/`sub` still see the full column set. */
+  select<K extends keyof C & string>(...cols: K[]): Query<C, Rels, One, Sel | K>;
+  limit(n: number): Query<C, Rels, One, Sel>;
+  /** Cursor paging: start at (or, with `exclusive`, after) the partial `cursor` row over the
+   *  sort columns. Lowers to a `Skip` in the engine. */
+  start(cursor: Partial<RowOf<C>>, opts?: { exclusive?: boolean }): Query<C, Rels, One, Sel>;
+  /** Return a single row: `materialize()` yields a {@link SingularArrayView} (`data: R | null`)
+   *  and the engine caps the query to `limit = 1`. */
+  one(): Query<C, Rels, true, Sel>;
+  /** **Merge** a {@link Fragment} into THIS node — Relay's "spread on the same type" (§5). The
+   *  fragment must be over the same table (enforced in the result type: a fragment over a different
+   *  table yields `never`, plus a runtime throw). Unions the projection (`Sel | FSel`), folds in the
+   *  fragment's nested relationships (`Rels & FRels`), and merges any same-`alias` edge recursively
+   *  — canonically, so `include` order doesn't matter (§10.5). Two fragments that spread the same
+   *  alias with a conflicting row-set (correlation/where/orderBy/…) **throw** (§10.2); an included
+   *  fragment may **not** add a root `where`/`orderBy`/`limit` (§10.3). This is also the single-shot
+   *  way to ROOT a fragment onto a base query (`queries.issue.where.id(x).include(IssueCard)`) — the
+   *  loader's composed root — equivalent to applying the fragment, but canonicalized.
+   *
+   *  The fragment's columns are a *separate* inferred parameter `FC` (not the class `C`) so that
+   *  `include` keeps `C` out of any contravariant position — preserving `Query<Concrete>`'s
+   *  assignability to `Query<AnyCols>` (needed by `Store<ColsMap>`/`QueryRoot`). Same-table is then
+   *  checked as the mutual-assignability of `C` and `FC` in the return type. */
+  include<FC extends AnyCols, FRels = {}, FSel extends string = never>(
+    fragment: Fragment<FC, FRels, FSel>,
+  ): [C] extends [FC] ? ([FC] extends [C] ? Query<C, Rels & FRels, One, Sel | FSel> : never) : never;
+  /** Nest a child by EXPLICIT correlation (no schema relationship). `alias` is the result key.
+   *  The child's own projection (`CSel`) masks the nested row, so a fragment spread here
+   *  contributes exactly the columns it declared. */
+  sub<A extends string, CC extends AnyCols, CRels = {}, CSel extends string = never>(
+    alias: A,
+    child: TableLike<CC>,
+    corr: { parent: Array<keyof C & string>; child: Array<keyof CC & string> },
+    build?: (q: Query<CC>) => Query<CC, CRels, boolean, CSel>,
+  ): Query<C, Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> }, One, Sel>;
+  /** Nest a child by a named {@link Relationship} (`rel(parent, child, {...})`) — the correlation comes
+   *  from the relationship, so no `{ parent, child }` keys are restated. The relationship must belong to
+   *  THIS table (its parent columns are checked against `C`). `alias` is still the result key. */
+  sub<A extends string, CC extends AnyCols, CRels = {}, CSel extends string = never>(
+    alias: A,
+    relationship: Relationship<C, CC>,
+    build?: (q: Query<CC>) => Query<CC, CRels, boolean, CSel>,
+  ): Query<C, Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> }, One, Sel>;
+  /** Add a **relationship aggregate** — `issue.countAs("commentCount", comment, …)`
+   *  (`REDUCE-DESIGN.md` §9). Like {@link sub} (explicit correlation, optional child
+   *  `build` for a filtered `count(child WHERE …)`), but the relationship surfaces a single
+   *  scalar `count(*)` of the correlated child rows named `alias` — so the result key is a
+   *  `number`, not an array; an empty (childless) parent reads `0`. */
+  countAs<A extends string, CC extends AnyCols>(
+    alias: A,
+    child: TableLike<CC>,
+    corr: { parent: Array<keyof C & string>; child: Array<keyof CC & string> },
+    build?: (q: Query<CC>) => Query<CC, unknown>,
+  ): Query<C, Rels & { [P in A]: number }, One, Sel>;
+  /** `countAs` by a named {@link Relationship} — like the explicit form, but the correlation comes from
+   *  `rel(...)` instead of being restated. */
+  countAs<A extends string, CC extends AnyCols>(
+    alias: A,
+    relationship: Relationship<C, CC>,
+    build?: (q: Query<CC>) => Query<CC, unknown>,
+  ): Query<C, Rels & { [P in A]: number }, One, Sel>;
+  /** The compiled Zero-wire AST (what a backend's `query` consumes). */
+  ast(): Ast;
+  /** Materialize into a live, typed view. Wired by the Store/backend. A top-level `.one()`
+   *  yields a {@link SingularArrayView}; otherwise an {@link ArrayView}. The row is masked to the
+   *  projection ({@link Projected}) — full {@link RowOf} until a column is `select`ed. */
+  materialize(): MaterializedView<Projected<C, Sel> & Rels, One>;
+}
+
+export type Query<C extends AnyCols, Rels = {}, One extends boolean = false, Sel extends string = never> =
+  & Omit<QueryBase<C, Rels, One, Sel>, "where">
+  & { where: QueryBase<C, Rels, One, Sel>["where"] & WhereProxy<C, Rels, One, Sel> }
+  & WhereSugar<C, Rels, One, Sel>;
+
+type AnyQuery = Query<any, any, any>;
+const STAMP_NAMED_QUERY: unique symbol = Symbol("rindle.stampNamedQuery");
+
+interface QueryInternals {
+  [STAMP_NAMED_QUERY](name: string, args: unknown): unknown;
+}
+
+function stampNamedQuery<Q extends AnyQuery>(query: Q, name: string, args: unknown): Q {
+  const stamp = (query as unknown as QueryInternals)[STAMP_NAMED_QUERY];
+  if (typeof stamp !== "function") {
+    throw new Error("defineQuery's build must return a Query built by newQueryBuilder/queries");
+  }
+  return stamp(name, args) as Q;
+}
+
+/** Turn raw, UNTRUSTED wire args into the canonical, typed args a query is built from. Its return
+ *  type IS the query's args type — written once, it flows to both the client call signature and the
+ *  `build` step, so there's no second place to restate the shape. */
+export type QueryValidator<Args> = (rawArgs: unknown) => Args;
+/**
+ * Build a `Query` (an `Ast` constructor) from already-validated args, plus an optional CONTEXT — the
+ * authenticated principal the query is scoped to. `Ctx` is **off-wire**: the client passes its own
+ * session ctx at the callsite, the server injects the AUTHORITATIVE ctx ({@link NamedQuery.resolve}
+ * via `registerQueries`), and the wire still carries only `name` + args. Both tiers run the same
+ * `build`, so whenever their ctx agrees the AST is byte-identical — and a client can never spoof it,
+ * since the server re-derives ctx from its trusted session and ignores anything the client claimed.
+ *
+ * The ctx is a *tuple* so a query opts into it by how it types `build`'s second parameter — and that
+ * shape becomes the call signature verbatim:
+ *   - `(args) => Q` — no ctx (`q(args)`).
+ *   - `(args, ctx: C) => Q` — ctx REQUIRED (`q(args, ctx)`); for always-authenticated queries.
+ *   - `(args, ctx?: C) => Q` — ctx OPTIONAL (`q(args)` or `q(args, ctx)`); sound only when "no ctx"
+ *     is a real, SYMMETRIC state — i.e. the build yields the SAME broad AST whether ctx is absent or
+ *     present-with-no-user (anonymous / SSR), since the server always forwards a ctx (possibly
+ *     anonymous). Otherwise type ctx required so the type catches an omitted ctx.
+ */
+export type QueryBuilder<Args, Q extends AnyQuery, Ctx extends readonly unknown[] = []> = (
+  args: Args,
+  ...ctx: Ctx
+) => Q;
+
+/**
+ * A single, co-located NAMED query (see {@link defineQuery}). It is:
+ *   - **callable on the client** — `q(args, ctx?)` validates + builds + stamps the result with its
+ *     remote subscription identity (`name` + args — NOT ctx), so a component that imports it always
+ *     SYNCS. There is no unstamped builder to import by accident.
+ *   - **registerable on the server** — it carries its `queryName` and a `resolve` that re-runs the
+ *     SAME validator on untrusted wire args and builds the AUTHORITATIVE `Query` from the server's
+ *     own ctx ({@link registerQueries `registerQueries`} in `@rindle/api-server`).
+ *
+ * `Ctx` is the ctx parameter list mirrored from `build` — `[]`, `[ctx: C]`, or `[ctx?: C]`. It is
+ * never part of the wire identity.
+ */
+export interface NamedQuery<Args, Ctx extends readonly unknown[], Q extends AnyQuery> {
+  (args: Args, ...ctx: Ctx): Q;
+  /** The wire identity. The daemon leases by this name; client and server MUST agree on it — which
+   *  they do, because both sides import the SAME `defineQuery` value. */
+  readonly queryName: string;
+  /** Server-side: validate raw wire args, then build the authoritative `Query` from the server's
+   *  authoritative ctx (forwarded by `registerQueries`). */
+  resolve(rawArgs: unknown, ...ctx: Ctx): Q;
+}
+
+/**
+ * Define ONE co-located, named query. Keep it next to the component that reads it (a `*.queries.ts`
+ * file), so a query lives where its fragments and its component live.
+ *
+ * The returned value is callable on the client (it stamps its result with `name` + args, so the
+ * subscription SYNCS) and registerable on the server ({@link registerQueries}). The optional
+ * `validate` step turns untrusted wire args into the canonical args type — and that type flows to
+ * both the call signature and `build`, so the shape is written exactly once. `validate` runs on
+ * BOTH tiers (it builds the byte-identical authoritative AST on the server, and guards + guarantees
+ * the same AST on the client). If the server must DIVERGE from the client, define a second
+ * `defineQuery` with the same `name` for the server and register that one instead.
+ *
+ * `build` may take a second CONTEXT parameter (see {@link QueryBuilder}). Context is off-wire: the
+ * client passes its session ctx at the callsite, the server injects its authoritative ctx — so a
+ * per-user query stays symmetric without ever trusting (or transmitting) a client-supplied identity.
+ *
+ * ```ts
+ * // recentComments({ limit }) — validated, no ctx, byte-identical on both tiers
+ * export const recentCommentsQuery = defineQuery(
+ *   "recentComments",
+ *   (raw): { limit: number } => ({ limit: validateFeedLimit(raw) }),
+ *   ({ limit }) => q.comment.orderBy("createdAt", "desc").limit(limit).include(FeedItemFragment),
+ * );
+ *
+ * // myIssues({ limit }, ctx) — ctx-scoped; the wire still carries only { limit }
+ * export const myIssuesQuery = defineQuery(
+ *   "myIssues",
+ *   (raw): { limit: number } => ({ limit: validateLimit(raw) }),
+ *   ({ limit }, ctx: { user: string }) => q.issue.where.ownerId(ctx.user).limit(limit),
+ * );
+ * // client: myIssuesQuery({ limit: 20 }, { user: currentUser() })
+ * ```
+ */
+export function defineQuery<Q extends AnyQuery>(name: string, build: () => Q): NamedQuery<void, [], Q>;
+export function defineQuery<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(
+  name: string,
+  build: (args: Args, ...ctx: Ctx) => Q,
+): NamedQuery<Args, Ctx, Q>;
+export function defineQuery<Args, Ctx extends readonly unknown[], Q extends AnyQuery>(
+  name: string,
+  validate: QueryValidator<Args>,
+  build: (args: Args, ...ctx: Ctx) => Q,
+): NamedQuery<Args, Ctx, Q>;
+export function defineQuery(
+  name: string,
+  validateOrBuild: (...a: any[]) => any,
+  maybeBuild?: (...a: any[]) => any,
+): NamedQuery<any, any, AnyQuery> {
+  const hasValidator = maybeBuild !== undefined;
+  const validate = (hasValidator ? validateOrBuild : (raw: unknown) => raw) as (raw: unknown) => unknown;
+  const build = (hasValidator ? maybeBuild : validateOrBuild) as (args: unknown, ...ctx: unknown[]) => AnyQuery;
+  const resolve = (rawArgs: unknown, ...ctx: unknown[]): AnyQuery => build(validate(rawArgs), ...ctx);
+  // The wire identity is (name, args) ONLY — ctx is never stamped, so it never crosses the wire.
+  const call = (args: unknown, ...ctx: unknown[]): AnyQuery =>
+    stampNamedQuery(build(validate(args), ...ctx), name, args ?? null);
+  return Object.assign(call, { queryName: name, resolve }) as NamedQuery<any, any, AnyQuery>;
+}
+
+// ----------------------------- fragments (FRAGMENT-COMPOSITION-DESIGN.md, Phase 0) -----------------------------
+
+const FRAGMENT_BRAND: unique symbol = Symbol("rindle.fragment");
+
+/**
+ * A reusable, typed *selection over a table* — Relay's "fragment", promoted to a first-class
+ * value. **Two verbs** compose a fragment, on one axis — does its data belong to THIS row or to a
+ * related one:
+ *
+ *   - SAME node — `q.include(Frag)`: merge its selection into this node. This is also how you
+ *     **root** a fragment onto a base query — `queries.t.where.id(x).include(Frag)`.
+ *   - CHILD node — `q.sub(alias, child, corr, Frag)`: nest it under a relationship (`sub`'s 4th arg).
+ *
+ * A `Fragment` is therefore also a `build` transform (`(q: Query<C>) => Query<C, Rels>`); that
+ * call signature is the mechanism by which `sub` accepts a fragment as its build. Prefer
+ * `include` to root a fragment (canonical + merged) over calling it directly. It additionally
+ * carries its `table` (for {@link FragmentRef}/`useFragment` typing and masking). Composing
+ * fragments assembles ONE {@link Ast} → one materialization → one `/query` — the whole point
+ * (no request waterfall; design §1).
+ */
+export interface Fragment<C extends AnyCols, Rels = {}, Sel extends string = never> {
+  (q: Query<C>): Query<C, Rels, false, Sel>;
+  readonly table: TableLike<C>;
+  readonly [FRAGMENT_BRAND]: true;
+}
+
+/**
+ * The "fragment ref" a parent passes down for a {@link Fragment} read: the already-projected
+ * node(s) at the fragment's alias in the shared root view — i.e. the fragment's result shape.
+ * It is **masked** ({@link Projected}) to the fragment's own `select` — a fragment reads only the
+ * columns it declared. A fragment with no `select` stays the full `RowOf<C> & Rels` (§10.6).
+ */
+export type FragmentRef<F> = F extends Fragment<infer C, infer Rels, infer Sel>
+  ? Projected<C, Sel> & Rels
+  : never;
+
+/**
+ * Define a co-located, composable {@link Fragment}: a named selection over `table`. The returned
+ * value is callable (the `build` transform), so it threads through the existing `sub`/`Rels`
+ * spine — no GraphQL, no codegen, no schema change (design §3).
+ *
+ * ```ts
+ * const UserAvatar = defineFragment(schema.user, (f) => f.select("id", "name", "avatarUrl"));
+ * const CommentRow = defineFragment(schema.comment, (f) =>
+ *   f.select("id", "body", "authorId")
+ *    .sub("author", schema.user, { parent: ["authorId"], child: ["id"] }, UserAvatar));
+ * ```
+ */
+export function defineFragment<C extends AnyCols, Rels = {}, Sel extends string = never>(
+  table: TableLike<C>,
+  build: (q: Query<C>) => Query<C, Rels, boolean, Sel>,
+): Fragment<C, Rels, Sel> {
+  const frag = (q: Query<C>): Query<C, Rels, false, Sel> => build(q) as Query<C, Rels, false, Sel>;
+  return Object.assign(frag, { table, [FRAGMENT_BRAND]: true as const }) as unknown as Fragment<C, Rels, Sel>;
+}
+
+/** Runtime guard: is `v` a {@link Fragment} (a `defineFragment` value, not a plain build fn)? */
+export function isFragment(v: unknown): v is Fragment<AnyCols, unknown> {
+  return typeof v === "function" && (v as Partial<Fragment<AnyCols>>)[FRAGMENT_BRAND] === true;
+}
+
+// ----------------------------- the runtime builder -----------------------------
+
+interface State {
+  table: string;
+  alias?: string;
+  wheres: Condition[];
+  orderBy: OrderPart[];
+  related: CorrelatedSubquery[];
+  start?: Bound;
+  limit?: number;
+  one: boolean;
+  select?: string[];
+}
+
+interface NamedQueryState {
+  name: string;
+  args: unknown;
+}
+
+function emptyState(table: string): State {
+  return { table, wheres: [], orderBy: [], related: [], one: false };
+}
+
+function compile(s: State): Ast {
+  const ast: Ast = { table: s.table };
+  if (s.alias !== undefined) ast.alias = s.alias;
+  if (s.wheres.length === 1) ast.where = s.wheres[0];
+  else if (s.wheres.length > 1) ast.where = { type: "and", conditions: s.wheres };
+  if (s.related.length > 0) ast.related = s.related;
+  if (s.start !== undefined) ast.start = s.start;
+  if (s.orderBy.length > 0) ast.orderBy = s.orderBy;
+  if (s.limit !== undefined) ast.limit = s.limit;
+  if (s.one) ast.one = true;
+  if (s.select && s.select.length > 0) ast.select = s.select;
+  return ast;
+}
+
+/** Build a child AST for `sub`/`exists`: a fresh child query, the optional `build`, compiled. */
+function childAst(child: AnyTable, build: ((q: unknown) => unknown) | undefined): Ast {
+  const cm = child[SCHEMA];
+  let cq: unknown = makeQuery(cm, emptyState(cm.name));
+  if (build) cq = build(cq);
+  return (cq as { ast(): Ast }).ast();
+}
+
+interface ResolvedCorrelated {
+  child: AnyTable;
+  corr: { parent: string[]; child: string[] };
+  build: ((q: unknown) => unknown) | undefined;
+}
+
+/** Resolve the two `sub`/`countAs`/`exists` call shapes to a common `{ child, corr, build }`:
+ *  either a named {@link Relationship} (`(rel, build?)`) or an explicit `(child, corr, build?)`. */
+function resolveCorrelated(a: AnyTable | AnyRelationship, b: unknown, c: unknown): ResolvedCorrelated {
+  if (isRelationship(a)) {
+    return {
+      child: a.child as AnyTable,
+      corr: { parent: [...a.correlation.parent], child: [...a.correlation.child] },
+      build: b as ((q: unknown) => unknown) | undefined,
+    };
+  }
+  return {
+    child: a,
+    corr: b as { parent: string[]; child: string[] },
+    build: c as ((q: unknown) => unknown) | undefined,
+  };
+}
+
+// ----------------------------- the merge pass (`include`, FRAGMENT-COMPOSITION-DESIGN §5) -----------
+//
+// `include(fragment)` folds a fragment's selection into the CURRENT node (same table). The merge is
+// canonical (sorted) so include order is irrelevant — `q.include(A).include(B)` and
+// `q.include(B).include(A)` compile to byte-identical ASTs → one `viewKey` → one materialization
+// (§10.5). Two fragments that spread the same relationship `alias` are merged recursively; if they
+// disagree on what rows that edge selects (correlation / table / where / orderBy / limit / paging /
+// aggregate), that is an unresolvable conflict and we throw (§10.2).
+
+function uniqSort(cols: string[]): string[] {
+  return [...new Set(cols)].sort();
+}
+
+/** Merge two same-node *fragment* selections: an empty (absent) `select` means "all columns", so
+ *  merging "all" with anything stays "all" (§5). Both sides here are fragment-contributed. */
+function mergeNestedSelect(a: string[] | undefined, b: string[] | undefined): string[] | undefined {
+  if (a === undefined || a.length === 0 || b === undefined || b.length === 0) return undefined;
+  return uniqSort([...a, ...b]);
+}
+
+/** Merge a fragment's `select` into the ROOTING query's `select`. A pure **union** — this mirrors
+ *  the type level (`Sel | FSel`, where a fragment that selects nothing contributes `never`) and keeps
+ *  `q.include(Frag)` equivalent to applying `Frag(q)`. An absent `select` (on either side) means
+ *  "contributes no columns", NOT "all columns" — so a relationship-only fragment (e.g. an edge that
+ *  just `sub`s, no root columns) doesn't blow the projection open. The result is "all columns" (a
+ *  dropped `select`) only when nothing anywhere selected, i.e. the union is empty. (This differs from
+ *  {@link mergeNestedSelect}: a *nested* same-alias child is an INTERSECTION of row types at the
+ *  type level — `Proj<A> & Proj<B>` — so there a no-select side, meaning "all child columns", wins.) */
+function mergeRootSelect(baseSel: string[] | undefined, fragSel: string[] | undefined): string[] | undefined {
+  const union = uniqSort([...(baseSel ?? []), ...(fragSel ?? [])]);
+  return union.length === 0 ? undefined : union;
+}
+
+function aliasOf(csq: CorrelatedSubquery): string {
+  return csq.subquery.alias ?? "";
+}
+
+/** A canonical key over everything that defines *which* rows a related edge yields — the fields
+ *  two same-alias spreads must AGREE on (select + related are merged, so they're excluded). */
+function edgeShapeKey(csq: CorrelatedSubquery): string {
+  const sq = csq.subquery;
+  return stableKey({
+    correlation: csq.correlation,
+    system: csq.system,
+    table: sq.table,
+    where: sq.where,
+    orderBy: sq.orderBy,
+    limit: sq.limit,
+    start: sq.start,
+    one: sq.one,
+    aggregate: sq.aggregate,
+    aggregatePrecomputed: sq.aggregatePrecomputed,
+  });
+}
+
+/** Merge the `select` + nested `related` of two same-alias subqueries (callers verified the edge
+ *  shape agrees). Returns a canonical (sorted) AST, omitting empty `select`/`related` like compile. */
+function mergeSubqueryAst(base: Ast, frag: Ast): Ast {
+  const out: Ast = { ...base };
+  const select = mergeNestedSelect(base.select, frag.select);
+  if (select === undefined) delete out.select;
+  else out.select = select;
+  const related = mergeRelatedLists(base.related ?? [], frag.related ?? []);
+  if (related.length === 0) delete out.related;
+  else out.related = related;
+  return out;
+}
+
+/** Merge two related lists by `alias`: same alias ⇒ recurse (after an edge-shape agreement check);
+ *  distinct aliases ⇒ kept side by side. Output is ordered by alias (canonical, §10.5). */
+function mergeRelatedLists(base: CorrelatedSubquery[], add: CorrelatedSubquery[]): CorrelatedSubquery[] {
+  const byAlias = new Map<string, CorrelatedSubquery>();
+  for (const csq of base) byAlias.set(aliasOf(csq), csq);
+  for (const csq of add) {
+    const alias = aliasOf(csq);
+    const existing = byAlias.get(alias);
+    if (existing === undefined) {
+      byAlias.set(alias, csq);
+      continue;
+    }
+    if (edgeShapeKey(existing) !== edgeShapeKey(csq)) {
+      throw new Error(
+        `include(): conflicting definitions for relationship "${alias}" — two fragments spread the ` +
+          `same alias with different correlation/table/where/orderBy/limit. Give them distinct aliases ` +
+          `or align them (FRAGMENT-COMPOSITION-DESIGN §10.2).`,
+      );
+    }
+    byAlias.set(alias, { ...existing, subquery: mergeSubqueryAst(existing.subquery, csq.subquery) });
+  }
+  return [...byAlias.values()].sort((a, b) => {
+    const x = aliasOf(a);
+    const y = aliasOf(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+}
+
+/** Fold an `include`d fragment's compiled AST into the current builder {@link State}. An included
+ *  fragment contributes only `select` + nested relationships; it may not constrain the node's row
+ *  set / window — adding a root `where` (§10.3) or `orderBy`/`limit`/`start`/`one` throws. */
+function mergeIncludedFragment(s: State, frag: Ast): State {
+  if (frag.where !== undefined) {
+    throw new Error(
+      "include(): a fragment may not add a root `where` — only the rooting query filters " +
+        "(FRAGMENT-COMPOSITION-DESIGN §10.3).",
+    );
+  }
+  if (frag.orderBy !== undefined || frag.limit !== undefined || frag.start !== undefined || frag.one) {
+    throw new Error(
+      "include(): a fragment may not set a root `orderBy`/`limit`/`start`/`one` — it contributes only " +
+        "`select` and nested relationships (those define the node's window, which is the rooting query's job).",
+    );
+  }
+  const select = mergeRootSelect(s.select, frag.select);
+  const next: State = { ...s, related: mergeRelatedLists(s.related, frag.related ?? []) };
+  if (select === undefined) delete next.select;
+  else next.select = select;
+  return next;
+}
+
+// Internal: the runtime is untyped (Proxy magic); the public `Query<C,Rels>` type is the contract.
+function makeQuery(
+  meta: TableMeta,
+  s: State,
+  onMat?: (query: AnyQuery) => unknown,
+  named?: NamedQueryState,
+): unknown {
+  const next = (patch: Partial<State>): unknown => makeQuery(meta, { ...s, ...patch }, onMat, named);
+  const applyField = (field: string, arg: unknown) =>
+    next({ wheres: [...s.wheres, fieldCondition(field, arg)] });
+  let proxy: unknown;
+
+  const base: Record<string, unknown> = {
+    name: named?.name,
+    args: named?.args,
+    where: (cond: Condition) => next({ wheres: [...s.wheres, cond] }),
+    orderBy: (col: string, dir: Dir) => next({ orderBy: [...s.orderBy, [col, dir]] }),
+    select: (...cols: string[]) => next({ select: [...(s.select ?? []), ...cols] }),
+    limit: (n: number) => next({ limit: n }),
+    start: (cursor: Record<string, LitValue>, opts?: { exclusive?: boolean }) =>
+      next({ start: { row: { ...cursor }, exclusive: opts?.exclusive ?? false } }),
+    one: () => next({ one: true }),
+    include: (fragment: Fragment<AnyCols, unknown, string>) => {
+      const fragTable = fragment.table;
+      if (fragTable[SCHEMA].name !== s.table) {
+        throw new Error(
+          `include(): the fragment is over "${fragTable[SCHEMA].name}" but this query is over "${s.table}". ` +
+            `include() merges a fragment into the SAME table — use sub() to nest a different table.`,
+        );
+      }
+      const fragAst = childAst(fragTable as AnyTable, fragment as unknown as (q: unknown) => unknown);
+      return makeQuery(meta, mergeIncludedFragment(s, fragAst), onMat, named);
+    },
+    sub: (alias: string, childOrRel: AnyTable | AnyRelationship, b?: unknown, c?: unknown) => {
+      const { child, corr, build } = resolveCorrelated(childOrRel, b, c);
+      const sub = childAst(child, build);
+      sub.alias = alias;
+      const csq: CorrelatedSubquery = {
+        correlation: { parentField: corr.parent, childField: corr.child },
+        subquery: sub,
+      };
+      return next({ related: [...s.related, csq] });
+    },
+    countAs: (alias: string, childOrRel: AnyTable | AnyRelationship, b?: unknown, c?: unknown) => {
+      // Same correlated-child mechanism as `sub`, but mark the child a `count` aggregate:
+      // the builder lowers it to a scalar-projected singular relationship (REDUCE-DESIGN §9).
+      const { child, corr, build } = resolveCorrelated(childOrRel, b, c);
+      const sub = childAst(child, build);
+      sub.alias = alias;
+      sub.aggregate = "count";
+      const csq: CorrelatedSubquery = {
+        correlation: { parentField: corr.parent, childField: corr.child },
+        subquery: sub,
+      };
+      return next({ related: [...s.related, csq] });
+    },
+    ast: () => compile(s),
+    materialize: () => {
+      if (!onMat) throw new Error("materialize() requires a Store — use store.query.<table>");
+      return onMat(proxy as AnyQuery);
+    },
+  };
+
+  // `where` is callable AND a field proxy.
+  const whereProxy = new Proxy(base.where as object, {
+    get(_t, prop) {
+      if (typeof prop === "string") return (arg: unknown) => applyField(prop, arg);
+      return undefined;
+    },
+  });
+
+  proxy = new Proxy(base, {
+    get(target, prop) {
+      if (prop === "where") return whereProxy;
+      if (prop === STAMP_NAMED_QUERY) return (name: string, args: unknown) => makeQuery(meta, s, onMat, { name, args });
+      if (typeof prop === "string" && prop.length > 5 && prop.startsWith("where")) {
+        const field = prop[5].toLowerCase() + prop.slice(6);
+        return (arg: unknown) => applyField(field, arg);
+      }
+      return target[prop as string];
+    },
+  });
+  return proxy;
+}
+
+// ----------------------------- EXISTS / NOT EXISTS -----------------------------
+
+/** Options for `exists` / `notExists`. */
+export interface ExistsOpts {
+  /**
+   * Fold this `EXISTS` as a build-time **scalar** subquery: when the child binds a
+   * statically-unique key, the engine reads it once, inlines the correlation value as a
+   * literal, and deletes the join. **Snapshot semantics** — the inlined value does not
+   * react to later child changes. Defaults to `false` (a live `EXISTS` join).
+   */
+  scalar?: boolean;
+}
+
+function existsImpl(
+  child: AnyTable,
+  corr: { parent: string[]; child: string[] },
+  build: ((q: unknown) => unknown) | undefined,
+  op: ExistsOp,
+  // `"permissions"` ⇒ a server-only, non-syncing gate (`exists_noSync`): the normalized
+  // serializer prunes its witnesses so the permission table is never synced to the client.
+  system?: "permissions",
+  opts?: ExistsOpts,
+): Condition {
+  const sub = childAst(child, build);
+  sub.alias = child[SCHEMA].name;
+  const related: CorrelatedSubquery = {
+    correlation: { parentField: corr.parent, childField: corr.child },
+    subquery: sub,
+  };
+  if (system) related.system = system;
+  return {
+    type: "correlatedSubquery",
+    op,
+    related,
+    ...(opts?.scalar ? { scalar: true } : {}),
+  };
+}
+
+/** `EXISTS` by a named {@link Relationship} — correlation from the rel; the parent row type is the
+ *  relationship's parent, so the condition lands on the matching `.where()`. */
+export function exists<PC extends AnyCols, CC extends AnyCols>(
+  relationship: Relationship<PC, CC>,
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+  opts?: ExistsOpts,
+): Cond<RowOf<PC>>;
+/** `EXISTS (<correlated subquery>)` — a condition (use inside `where`/`or`/`and`). */
+export function exists<CC extends AnyCols, R = unknown>(
+  child: TableLike<CC>,
+  corr: { parent: Array<keyof R & string>; child: Array<keyof CC & string> },
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+  opts?: ExistsOpts,
+): Cond<R>;
+export function exists(a: AnyTable | AnyRelationship, b?: unknown, c?: unknown, d?: unknown): Cond<unknown> {
+  const { child, corr, build } = resolveCorrelated(a, b, c);
+  const opts = (isRelationship(a) ? c : d) as ExistsOpts | undefined;
+  return existsImpl(child, corr, build, "EXISTS", undefined, opts) as Cond<unknown>;
+}
+
+/** `NOT EXISTS` by a named {@link Relationship}. */
+export function notExists<PC extends AnyCols, CC extends AnyCols>(
+  relationship: Relationship<PC, CC>,
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+  opts?: ExistsOpts,
+): Cond<RowOf<PC>>;
+/** `NOT EXISTS (<correlated subquery>)`. */
+export function notExists<CC extends AnyCols, R = unknown>(
+  child: TableLike<CC>,
+  corr: { parent: Array<keyof R & string>; child: Array<keyof CC & string> },
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+  opts?: ExistsOpts,
+): Cond<R>;
+export function notExists(a: AnyTable | AnyRelationship, b?: unknown, c?: unknown, d?: unknown): Cond<unknown> {
+  const { child, corr, build } = resolveCorrelated(a, b, c);
+  const opts = (isRelationship(a) ? c : d) as ExistsOpts | undefined;
+  return existsImpl(child, corr, build, "NOT EXISTS", undefined, opts) as Cond<unknown>;
+}
+
+/**
+ * `EXISTS (<correlated subquery>)` as a **server-only, non-syncing** gate (`exists_noSync`).
+ * Identical to {@link exists} for filtering parent visibility, but stamps the subquery
+ * `system: "permissions"`, so the engine's normalized serializer prunes its witnesses from the
+ * footprint — the permission table's rows are never synced to the client and the client never
+ * re-evaluates the gate. Use this when building the **server's** query (the user's API server);
+ * the client holds its own un-gated query.
+ */
+export function existsNoSync<PC extends AnyCols, CC extends AnyCols>(
+  relationship: Relationship<PC, CC>,
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+): Cond<RowOf<PC>>;
+export function existsNoSync<CC extends AnyCols, R = unknown>(
+  child: TableLike<CC>,
+  corr: { parent: Array<keyof R & string>; child: Array<keyof CC & string> },
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+): Cond<R>;
+export function existsNoSync(a: AnyTable | AnyRelationship, b?: unknown, c?: unknown): Cond<unknown> {
+  const { child, corr, build } = resolveCorrelated(a, b, c);
+  return existsImpl(child, corr, build, "EXISTS", "permissions") as Cond<unknown>;
+}
+
+/** `NOT EXISTS (<correlated subquery>)` as a **server-only, non-syncing** gate — the `NOT EXISTS` form of {@link existsNoSync} (a deny-style permission rule). */
+export function notExistsNoSync<PC extends AnyCols, CC extends AnyCols>(
+  relationship: Relationship<PC, CC>,
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+): Cond<RowOf<PC>>;
+export function notExistsNoSync<CC extends AnyCols, R = unknown>(
+  child: TableLike<CC>,
+  corr: { parent: Array<keyof R & string>; child: Array<keyof CC & string> },
+  build?: (q: Query<CC>) => Query<CC, unknown>,
+): Cond<R>;
+export function notExistsNoSync(a: AnyTable | AnyRelationship, b?: unknown, c?: unknown): Cond<unknown> {
+  const { child, corr, build } = resolveCorrelated(a, b, c);
+  return existsImpl(child, corr, build, "NOT EXISTS", "permissions") as Cond<unknown>;
+}
+
+// ----------------------------- the query root (store.query.<table>) -----------------------------
+
+export type QueryRoot<S extends ColsMap> = { [N in keyof S]: Query<S[N]> };
+
+/** A typed query entry over a schema: `queries(schema).issue.where.closed(false)…`. */
+export function queries<S extends ColsMap>(
+  schema: Schema<S>,
+  onMaterialize?: (query: AnyQuery) => unknown,
+): QueryRoot<S> {
+  return new Proxy({} as Record<string, unknown>, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return undefined;
+      // Framework/JS introspection probes are never table names — return undefined instead of
+      // throwing so the query root (and a `Store` carrying it) can be safely enumerated by code
+      // that inspects objects. React 19's dev-mode prop diffing reads `$$typeof` on every prop
+      // value; `then` is the thenable check; `toJSON` is JSON serialization. A real typo'd table
+      // (`store.query.isue`) is a plain identifier and still throws below.
+      if (prop[0] === "$" || prop === "then" || prop === "toJSON") return undefined;
+      const meta = schema.tables[prop];
+      if (!meta) throw new Error(`unknown table: ${prop}`);
+      return makeQuery(meta, emptyState(meta.name), onMaterialize);
+    },
+  }) as QueryRoot<S>;
+}
+
+/** A schema-bound query-builder factory for portable client/server query definitions. */
+export function newQueryBuilder<S extends ColsMap>(schema: Schema<S>): QueryRoot<S> {
+  return queries(schema);
+}