@rindle/client 0.1.5 → 0.2.0

package/src/query.ts

@@ -20,18 +20,18 @@ import type { ArrayView, SingularArrayView } from "./view.ts";
 // (`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> = (
+type FieldFn<C extends AnyCols, K extends keyof C, Rels, One extends boolean, Sel extends string, LocalRels> = (
   arg: Arg<ColT<C[K]>>,
-) => Query<C, Rels, One, Sel>;
+) => Query<C, Rels, One, Sel, LocalRels>;
 
 /** `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>;
+type WhereProxy<C extends AnyCols, Rels, One extends boolean, Sel extends string, LocalRels> = {
+  [K in keyof C]: FieldFn<C, K, Rels, One, Sel, LocalRels>;
 };
 
 /** `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>;
+type WhereSugar<C extends AnyCols, Rels, One extends boolean, Sel extends string, LocalRels> = {
+  [K in keyof C as `where${Capitalize<string & K>}`]: FieldFn<C, K, Rels, One, Sel, LocalRels>;
 };
 
 /** What `materialize()` returns: singular (`R | null`) for a top-level `.one()`, else plural. */
@@ -49,27 +49,31 @@ 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> {
+type FragmentEdge<C extends AnyCols, Rels, Sel extends string, LocalRels> = (
+  q: Query<C, Rels, false, Sel, LocalRels>,
+) => Query<C, Rels, boolean, Sel, LocalRels>;
+
+interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends string, LocalRels> {
   /** 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>;
+  where(cond: Cond<RowOf<C>>): Query<C, Rels, One, Sel, LocalRels>;
+  orderBy<K extends keyof C>(col: K, dir: Dir): Query<C, Rels, One, Sel, LocalRels>;
   /** 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>;
+  select<K extends keyof C & string>(...cols: K[]): Query<C, Rels, One, Sel | K, LocalRels>;
+  limit(n: number): Query<C, Rels, One, Sel, LocalRels>;
   /** 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>;
+  start(cursor: Partial<RowOf<C>>, opts?: { exclusive?: boolean }): Query<C, Rels, One, Sel, LocalRels>;
   /** 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>;
+  one(): Query<C, Rels, true, Sel, LocalRels>;
   /** **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
@@ -84,9 +88,90 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
    *  `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;
+  include<FC extends AnyCols, FRels = {}, FSel extends string = never, FLocalRels = FRels>(
+    fragment: Fragment<FC, FRels, FSel, FLocalRels>,
+  ): [C] extends [FC] ? ([FC] extends [C] ? Query<C, Rels & FRels, One, Sel | FSel, LocalRels & FLocalRels> : never) : never;
+  /** Nest a child fragment as an opaque local-read ref. The coverage query still composes the
+   *  child's full AST at runtime; the React-facing fragment data exposes only refs at this
+   *  boundary so the child component owns its local subscription. */
+  sub<
+    A extends string,
+    CC extends AnyCols,
+    CRels = {},
+    CSel extends string = never,
+    CLocalRels = CRels,
+    F extends Fragment<CC, CRels, CSel, CLocalRels> = Fragment<CC, CRels, CSel, CLocalRels>,
+  >(
+    alias: A,
+    child: TableLike<CC>,
+    corr: { parent: Array<keyof C & string>; child: Array<keyof CC & string> },
+    build: F,
+    edge: FragmentEdge<CC, CRels, CSel, CLocalRels>,
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<FragmentRef<F>> }
+  >;
+  sub<
+    A extends string,
+    CC extends AnyCols,
+    CRels = {},
+    CSel extends string = never,
+    CLocalRels = CRels,
+    F extends Fragment<CC, CRels, CSel, CLocalRels> = Fragment<CC, CRels, CSel, CLocalRels>,
+  >(
+    alias: A,
+    child: TableLike<CC>,
+    corr: { parent: Array<keyof C & string>; child: Array<keyof CC & string> },
+    build: F,
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<FragmentRef<F>> }
+  >;
+  /** Relationship-value form of the fragment-ref overload above. */
+  sub<
+    A extends string,
+    CC extends AnyCols,
+    CRels = {},
+    CSel extends string = never,
+    CLocalRels = CRels,
+    F extends Fragment<CC, CRels, CSel, CLocalRels> = Fragment<CC, CRels, CSel, CLocalRels>,
+  >(
+    alias: A,
+    relationship: Relationship<C, CC>,
+    build: F,
+    edge: FragmentEdge<CC, CRels, CSel, CLocalRels>,
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<FragmentRef<F>> }
+  >;
+  /** Relationship-value form of the fragment-ref overload above. */
+  sub<
+    A extends string,
+    CC extends AnyCols,
+    CRels = {},
+    CSel extends string = never,
+    CLocalRels = CRels,
+    F extends Fragment<CC, CRels, CSel, CLocalRels> = Fragment<CC, CRels, CSel, CLocalRels>,
+  >(
+    alias: A,
+    relationship: Relationship<C, CC>,
+    build: F,
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<FragmentRef<F>> }
+  >;
   /** 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. */
@@ -95,7 +180,13 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
     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>;
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<Projected<CC, CSel> & CRels> }
+  >;
   /** 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. */
@@ -103,7 +194,13 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
     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>;
+  ): Query<
+    C,
+    Rels & { [P in A]: Array<Projected<CC, CSel> & CRels> },
+    One,
+    Sel,
+    LocalRels & { [P in A]: Array<Projected<CC, CSel> & CRels> }
+  >;
   /** 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
@@ -114,14 +211,14 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
     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>;
+  ): Query<C, Rels & { [P in A]: number }, One, Sel, LocalRels & { [P in A]: number }>;
   /** `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>;
+  ): Query<C, Rels & { [P in A]: number }, One, Sel, LocalRels & { [P in A]: number }>;
   /** 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()`
@@ -130,12 +227,25 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
   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>;
+export type Query<
+  C extends AnyCols,
+  Rels = {},
+  One extends boolean = false,
+  Sel extends string = never,
+  LocalRels = Rels,
+> =
+  & Omit<QueryBase<C, Rels, One, Sel, LocalRels>, "where">
+  & { where: QueryBase<C, Rels, One, Sel, LocalRels>["where"] & WhereProxy<C, Rels, One, Sel, LocalRels> }
+  & WhereSugar<C, Rels, One, Sel, LocalRels>;
 
-type AnyQuery = Query<any, any, any>;
+export type AnyQuery = Query<any, any, any, any, any>;
+
+export type QueryLocalData<Q extends AnyQuery> =
+  Q extends Query<infer C, any, infer One, infer Sel, infer LocalRels>
+    ? One extends true
+      ? (Projected<C, Sel> & LocalRels) | null
+      : readonly (Projected<C, Sel> & LocalRels)[]
+    : never;
 const STAMP_NAMED_QUERY: unique symbol = Symbol("rindle.stampNamedQuery");
 
 interface QueryInternals {
@@ -259,6 +369,8 @@ export function defineQuery(
 // ----------------------------- fragments (FRAGMENT-COMPOSITION-DESIGN.md, Phase 0) -----------------------------
 
 const FRAGMENT_BRAND: unique symbol = Symbol("rindle.fragment");
+const LOCAL_FRAGMENT_REF_BRAND: unique symbol = Symbol("rindle.localFragmentRef");
+const FRAGMENT_REL_BRAND: unique symbol = Symbol("rindle.fragmentRelationship");
 
 /**
  * A reusable, typed *selection over a table* — Relay's "fragment", promoted to a first-class
@@ -276,22 +388,38 @@ const FRAGMENT_BRAND: unique symbol = Symbol("rindle.fragment");
  * 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>;
+export interface Fragment<C extends AnyCols, Rels = {}, Sel extends string = never, LocalRels = Rels> {
+  (q: Query<C>): Query<C, Rels, false, Sel, LocalRels>;
   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).
+ * The data returned by `useFragment(fragment, ref)`: the fragment's own selected columns plus
+ * immediate relationship values. Relationships whose builder is another fragment surface as
+ * opaque {@link FragmentRef}s, so child-owned payload is read only by the child fragment reader.
  */
-export type FragmentRef<F> = F extends Fragment<infer C, infer Rels, infer Sel>
-  ? Projected<C, Sel> & Rels
+export type FragmentData<F> = F extends Fragment<infer C, unknown, infer Sel, infer LocalRels>
+  ? Projected<C, Sel> & LocalRels
   : never;
 
+export interface FragmentCoverage<Q extends AnyQuery = AnyQuery> {
+  readonly key: string;
+  readonly query: Q;
+}
+
+export interface LocalFragmentRef<F extends Fragment<any, any, any, any> = Fragment<any, any, any, any>> {
+  readonly [LOCAL_FRAGMENT_REF_BRAND]: true;
+  readonly source: "local";
+  readonly table: string;
+  readonly pk: Readonly<Record<string, LitValue>>;
+  readonly coverage: FragmentCoverage;
+  readonly __fragment?: F;
+}
+
+/** The opaque token a parent passes to a component that reads {@link FragmentData} for `F`. */
+export type FragmentRef<F> = F extends Fragment<any, any, any, any> ? LocalFragmentRef<F> : 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`
@@ -304,17 +432,192 @@ export type FragmentRef<F> = F extends Fragment<infer C, infer Rels, infer Sel>
  *    .sub("author", schema.user, { parent: ["authorId"], child: ["id"] }, UserAvatar));
  * ```
  */
-export function defineFragment<C extends AnyCols, Rels = {}, Sel extends string = never>(
+export function defineFragment<C extends AnyCols, Rels = {}, Sel extends string = never, LocalRels = Rels>(
   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>;
+  build: (q: Query<C>) => Query<C, Rels, boolean, Sel, LocalRels>,
+): Fragment<C, Rels, Sel, LocalRels> {
+  const frag = (q: Query<C>): Query<C, Rels, false, Sel, LocalRels> => build(q) as Query<C, Rels, false, Sel, LocalRels>;
+  return Object.assign(frag, { table, [FRAGMENT_BRAND]: true as const }) as unknown as Fragment<C, Rels, Sel, LocalRels>;
 }
 
 /** 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;
+export function isFragment(v: unknown): v is Fragment<AnyCols, unknown, never, unknown> {
+  return typeof v === "function" && (v as Partial<Fragment<AnyCols, unknown, never, unknown>>)[FRAGMENT_BRAND] === true;
+}
+
+function isLocalFragmentRef(v: unknown): v is LocalFragmentRef {
+  return typeof v === "object" && v !== null && (v as Partial<LocalFragmentRef>)[LOCAL_FRAGMENT_REF_BRAND] === true;
+}
+
+type FragmentRelationship = CorrelatedSubquery & { [FRAGMENT_REL_BRAND]?: true };
+
+function markFragmentRelationship<T extends CorrelatedSubquery>(rel: T): T {
+  Object.defineProperty(rel, FRAGMENT_REL_BRAND, { value: true });
+  return rel;
+}
+
+export function isFragmentRelationship(rel: CorrelatedSubquery): boolean {
+  return (rel as FragmentRelationship)[FRAGMENT_REL_BRAND] === true;
+}
+
+export function fragmentKey(ref: FragmentRef<any>): string {
+  if (!isLocalFragmentRef(ref)) throw new Error("fragmentKey(): expected an opaque fragment ref.");
+  return stableKey({ table: ref.table, pk: ref.pk });
+}
+
+export function createLocalFragmentRef<F extends Fragment<any, any, any>>(
+  fragment: F,
+  pk: Record<string, LitValue>,
+  coverage: FragmentCoverage,
+): LocalFragmentRef<F> {
+  return createLocalFragmentRefForTable(fragment.table[SCHEMA].name, pk, coverage);
+}
+
+export function createLocalFragmentRefForTable<F extends Fragment<any, any, any>>(
+  table: string,
+  pk: Record<string, LitValue>,
+  coverage: FragmentCoverage,
+): LocalFragmentRef<F> {
+  return {
+    [LOCAL_FRAGMENT_REF_BRAND]: true,
+    source: "local",
+    table,
+    pk: { ...pk },
+    coverage,
+  };
+}
+
+export function createRootFragmentRef<F extends Fragment<any, any, any>, Q extends AnyQuery>(
+  fragment: F,
+  query: Q,
+  coverageKey = stableKey({
+    ast: query.ast(),
+    remote: typeof query.name === "string" ? { name: query.name, args: query.args } : null,
+  }),
+): LocalFragmentRef<F> {
+  const ast = query.ast();
+  const table = fragment.table[SCHEMA];
+  if (ast.table !== table.name) {
+    throw new Error(
+      `useRoot(): the coverage query is over "${ast.table}" but the fragment is over "${table.name}".`,
+    );
+  }
+  const pk = primaryKeyFromWhere(ast, table.primaryKey);
+  return createLocalFragmentRef(fragment, pk, { key: coverageKey, query });
+}
+
+export function fragmentAst<F extends Fragment<any, any, any>>(fragment: F): Ast {
+  return childAst(fragment.table as AnyTable, fragment as unknown as (q: unknown) => unknown);
+}
+
+export function localFragmentReadAst<F extends Fragment<any, any, any>>(
+  fragment: F,
+  ref: LocalFragmentRef<F>,
+  primaryKeyFor: (table: string) => readonly string[],
+): Ast {
+  const table = fragment.table[SCHEMA].name;
+  if (ref.table !== table) {
+    throw new Error(`useFragment(): the ref is for "${ref.table}" but the fragment is over "${table}".`);
+  }
+  const ast = localizeFragmentAst(fragmentAst(fragment), primaryKeyFor);
+  ast.where = andConditions(pkConditions(ref.pk), ast.where);
+  ast.one = true;
+  return ast;
+}
+
+export function localRootFragmentRefsAst<F extends Fragment<any, any, any>>(
+  fragment: F,
+  query: AnyQuery,
+  primaryKeyFor: (table: string) => readonly string[],
+): Ast {
+  const ast = query.ast();
+  const table = fragment.table[SCHEMA].name;
+  if (ast.table !== table) {
+    throw new Error(
+      `useRoot(): the coverage query is over "${ast.table}" but the fragment is over "${table}".`,
+    );
+  }
+  const out: Ast = { ...ast, select: uniqSort([...primaryKeyFor(table)]) };
+  delete out.related;
+  return out;
+}
+
+export function localQueryReadAst(
+  query: AnyQuery,
+  primaryKeyFor: (table: string) => readonly string[],
+): Ast {
+  return localizeFragmentAst(query.ast(), primaryKeyFor);
+}
+
+export function queryFromAst(ast: Ast): AnyQuery {
+  return {
+    ast: () => ast,
+    materialize: () => {
+      throw new Error("queryFromAst(): materialize() requires a Store; pass this query through Store/React.");
+    },
+  } as unknown as AnyQuery;
+}
+
+function primaryKeyFromWhere(ast: Ast, primaryKey: readonly string[]): Record<string, LitValue> {
+  const found = new Map<string, LitValue>();
+  collectLiteralEquals(ast.where, found);
+  const pk: Record<string, LitValue> = {};
+  for (const col of primaryKey) {
+    if (!found.has(col)) {
+      throw new Error(
+        `useRoot(): the coverage query must constrain primary key column "${col}" with a literal equality.`,
+      );
+    }
+    pk[col] = found.get(col)!;
+  }
+  return pk;
+}
+
+function collectLiteralEquals(cond: Condition | undefined, out: Map<string, LitValue>): void {
+  if (!cond) return;
+  if (cond.type === "and") {
+    for (const c of cond.conditions) collectLiteralEquals(c, out);
+    return;
+  }
+  if (cond.type !== "simple" || cond.op !== "=") return;
+  const leftCol = cond.left.type === "column" ? cond.left.name : undefined;
+  const rightCol = cond.right.type === "column" ? cond.right.name : undefined;
+  if (leftCol !== undefined && cond.right.type === "literal") out.set(leftCol, cond.right.value);
+  else if (rightCol !== undefined && cond.left.type === "literal") out.set(rightCol, cond.left.value);
+}
+
+function pkConditions(pk: Readonly<Record<string, LitValue>>): Condition[] {
+  return Object.keys(pk)
+    .sort()
+    .map((name) => fieldCondition(name, pk[name]));
+}
+
+function andConditions(conditions: Condition[], tail: Condition | undefined): Condition | undefined {
+  const all = tail ? [...conditions, tail] : conditions;
+  if (all.length === 0) return undefined;
+  if (all.length === 1) return all[0];
+  return { type: "and", conditions: all };
+}
+
+function localizeFragmentAst(ast: Ast, primaryKeyFor: (table: string) => readonly string[]): Ast {
+  const out: Ast = { ...ast };
+  if (ast.select !== undefined) out.select = uniqSort([...ast.select, ...primaryKeyFor(ast.table)]);
+  if (ast.related !== undefined) {
+    out.related = ast.related.map((rel) => {
+      if (rel.subquery.aggregate !== undefined) return rel;
+      if (!isFragmentRelationship(rel)) {
+        return { ...rel, subquery: localizeFragmentAst(rel.subquery, primaryKeyFor) };
+      }
+      const childPk = primaryKeyFor(rel.subquery.table);
+      const subquery: Ast = {
+        ...rel.subquery,
+        select: uniqSort([...childPk]),
+      };
+      delete subquery.related;
+      return markFragmentRelationship({ ...rel, subquery });
+    });
+  }
+  return out;
 }
 
 // ----------------------------- the runtime builder -----------------------------
@@ -401,22 +704,42 @@ interface ResolvedCorrelated {
   child: AnyTable;
   corr: { parent: string[]; child: string[] };
   build: ((q: unknown) => unknown) | undefined;
+  fragment: boolean;
+}
+
+function composeCorrelatedBuild(
+  build: ((q: unknown) => unknown) | undefined,
+  edge: ((q: unknown) => unknown) | undefined,
+): ((q: unknown) => unknown) | undefined {
+  if (edge === undefined) return build;
+  if (!isFragment(build)) {
+    throw new Error("sub(): an edge callback is only supported when the child build is a Fragment.");
+  }
+  return (q: unknown) => edge(build(q as Query<AnyCols>));
 }
 
 /** 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 {
+function resolveCorrelated(a: AnyTable | AnyRelationship, b: unknown, c: unknown, d?: 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,
+      build: composeCorrelatedBuild(
+        b as ((q: unknown) => unknown) | undefined,
+        c as ((q: unknown) => unknown) | undefined,
+      ),
+      fragment: isFragment(b),
     };
   }
   return {
     child: a,
     corr: b as { parent: string[]; child: string[] },
-    build: c as ((q: unknown) => unknown) | undefined,
+    build: composeCorrelatedBuild(
+      c as ((q: unknown) => unknown) | undefined,
+      d as ((q: unknown) => unknown) | undefined,
+    ),
+    fragment: isFragment(c),
   };
 }
 
@@ -507,7 +830,8 @@ function mergeRelatedLists(base: CorrelatedSubquery[], add: CorrelatedSubquery[]
           `or align them (FRAGMENT-COMPOSITION-DESIGN §10.2).`,
       );
     }
-    byAlias.set(alias, { ...existing, subquery: mergeSubqueryAst(existing.subquery, csq.subquery) });
+    const merged = { ...existing, subquery: mergeSubqueryAst(existing.subquery, csq.subquery) };
+    byAlias.set(alias, isFragmentRelationship(existing) || isFragmentRelationship(csq) ? markFragmentRelationship(merged) : merged);
   }
   return [...byAlias.values()].sort((a, b) => {
     const x = aliasOf(a);
@@ -576,15 +900,15 @@ function makeQuery(
       const fragAst = childAst(fragTable as AnyTable, fragment as unknown as (q: unknown) => unknown);
       return makeQuery(meta, mergeIncludedFragment(s, fragAst), onMat, named, guardAst);
     },
-    sub: (alias: string, childOrRel: AnyTable | AnyRelationship, b?: unknown, c?: unknown) => {
-      const { child, corr, build } = resolveCorrelated(childOrRel, b, c);
+    sub: (alias: string, childOrRel: AnyTable | AnyRelationship, b?: unknown, c?: unknown, d?: unknown) => {
+      const { child, corr, build, fragment } = resolveCorrelated(childOrRel, b, c, d);
       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] });
+      return next({ related: [...s.related, fragment ? markFragmentRelationship(csq) : csq] });
     },
     countAs: (alias: string, childOrRel: AnyTable | AnyRelationship, b?: unknown, c?: unknown) => {
       // Same correlated-child mechanism as `sub`, but mark the child a `count` aggregate:

package/src/store.ts

@@ -51,6 +51,19 @@ export interface CachedQueryView<Q extends Query<any, any, any>> {
   destroy(): void;
 }
 
+export interface SyncQueryLease {
+  readonly resultType: ResultType;
+  subscribe(listener: () => void): () => void;
+  release(): void;
+}
+
+interface SyncLeaseState {
+  resultType: ResultType;
+  listeners: Set<() => void>;
+  released: boolean;
+  seedKey?: string;
+}
+
 /** One live materialized view's read-only summary for a devtools pane (DEBUG-TOOLS-BROWSER-DESIGN
  *  §4.2 — "surface, not instrument"). All fields are already held by the {@link Store}; this is the
  *  single read-only accessor over the otherwise-private `views`/`asts` maps. */
@@ -93,6 +106,7 @@ export class Store<S extends ColsMap> {
   private nextId = 1;
   private readonly views = new Map<QueryId, FlatArrayView>();
   private readonly asts = new Map<QueryId, Ast>();
+  private readonly syncLeases = new Map<QueryId, SyncLeaseState>();
   // SSR seeds (SSR-DESIGN.md §6), keyed by `viewKey`: a view materialized for one of these is
   // seeded for first paint; a seed is consumed (dropped) the moment its query's first live
   // `hello` lands, so later mounts don't flash stale SSR data.
@@ -111,6 +125,12 @@ export class Store<S extends ColsMap> {
     // transition (it never displaces this single handler).
     this.backend.onResultType?.((qid, rt) => {
       this.views.get(qid)?.setResultType(rt);
+      const sync = this.syncLeases.get(qid);
+      if (sync && sync.resultType !== rt) {
+        sync.resultType = rt;
+        if (rt === "complete" && sync.seedKey !== undefined) this.seeds.delete(sync.seedKey);
+        for (const listener of sync.listeners) listener();
+      }
       if (this.devObservers) for (const o of this.devObservers) o.onResultType?.(qid, rt);
     });
     // `store.query` is the LOCAL builder (201-LOCAL-ONLY-TABLES-DESIGN.md §5): it scopes over
@@ -153,6 +173,49 @@ export class Store<S extends ColsMap> {
     };
   }
 
+  /** Retain a named remote query purely for normalized/local-first coverage. This does not
+   *  register or materialize the query AST locally, so React can keep server sync coverage alive
+   *  without subscribing to the broad coverage result tree. */
+  retainSyncQuery<Q extends Query<any, any, any>>(query: Q): SyncQueryLease {
+    if (!this.canRetainRemoteQueries()) {
+      throw new Error(
+        "store.retainSyncQuery: this backend cannot retain a remote query without a local view.",
+      );
+    }
+    const ast = query.ast();
+    const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
+    if (!remote) {
+      throw new Error("store.retainSyncQuery: sync-only coverage requires a named query.");
+    }
+    const qid = this.nextId++;
+    const state: SyncLeaseState = { resultType: "unknown", listeners: new Set(), released: false, seedKey: stableKey(ast) };
+    this.syncLeases.set(qid, state);
+    try {
+      this.backend.retainRemoteQuery?.(qid, remote, qid, ast);
+    } catch (e) {
+      this.syncLeases.delete(qid);
+      throw e;
+    }
+    return {
+      get resultType() {
+        return state.resultType;
+      },
+      subscribe: (listener: () => void) => {
+        state.listeners.add(listener);
+        listener();
+        return () => {
+          state.listeners.delete(listener);
+        };
+      },
+      release: () => {
+        if (state.released) return;
+        state.released = true;
+        this.syncLeases.delete(qid);
+        this.backend.releaseRemoteQuery?.(qid);
+      },
+    };
+  }
+
   /** Apply a batch of mutations (object rows → positional). Resolves when the backend has
    *  accepted them (local: applied; remote: sent). The resulting view updates flow back via
    *  the backend's event stream. */
@@ -234,6 +297,12 @@ export class Store<S extends ColsMap> {
     return this.seeds.get(viewKey);
   }
 
+  primaryKeyFor(table: string): readonly string[] {
+    const meta = this.schema.tables[table];
+    if (!meta) throw new Error(`unknown table: ${table}`);
+    return meta.primaryKey;
+  }
+
   /** Convert assembled (nested-by-name) rows (SSR-DESIGN.md §3.3) into the view's projected result
    *  shape: spread `cols` (parsing json columns), recurse into each relationship by its alias
    *  (plural → array, `.one()` → object/null, `countAs` → bare scalar). */
@@ -310,7 +379,7 @@ export class Store<S extends ColsMap> {
     const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
     if (!remote || !this.canRetainRemoteQueries()) return () => {};
     const qid = this.nextId++;
-    this.backend.retainRemoteQuery?.(qid, remote, localQueryId);
+    this.backend.retainRemoteQuery?.(qid, remote, localQueryId, query.ast());
     let released = false;
     return () => {
       if (released) return;