@rindle/client 0.1.6 → 0.3.1

package/src/query.ts

@@ -6,7 +6,7 @@
 //   - `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 type { Ast, Bound, Condition, CorrelatedSubquery, Dir, ExistsOp, LitValue, OrderPart, SimpleOp } from "./ast.ts";
 import { stableKey } from "./key.ts";
 import type { Arg, Cond } from "./operators.ts";
 import { fieldCondition } from "./operators.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,56 @@ 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> {
+/**
+ * The accumulating result row of a top-level aggregate (REDUCE-DESIGN.md §8). `Agg` is `false`
+ * until {@link QueryBase.count}/{@link QueryBase.groupBy} reshapes the query; then it is the
+ * group-by columns intersected with the synthetic `{ count: number }`. {@link AggAcc} treats the
+ * `false` state as `{}` so the intersections in `count`/`groupBy` compose either way.
+ */
+type AggAcc<Agg> = [Agg] extends [false] ? {} : Agg;
+
+/** `having`'s field binder: one accessor per aggregate-OUTPUT column (the group-by columns plus the
+ *  synthetic numeric `count`), each producing a {@link Cond} over that aggregate row. It is the only
+ *  way to name `count` in a predicate (it lives on no base table); compose several with `and`/`or`. */
+type HavingProxy<Row> = { [K in keyof Row & string]: (arg: Arg<Row[K]>) => Cond<Row> };
+
+/** The `countAs` relationship aliases of a query — the {@link Rels} keys whose value is the scalar
+ *  `number` a count aggregate surfaces. These are the only aliases {@link QueryBase.having}'s
+ *  parent-by-child-aggregate overload accepts (a plain `sub` alias carries a row object, not a
+ *  number, so it is rejected). */
+type AggregateAlias<Rels> = { [K in keyof Rels]: Rels[K] extends number ? K & string : never }[keyof Rels];
+
+/** What a query materializes: the post-aggregation row once reshaped by {@link QueryBase.count}
+ *  (`Agg`), else the projected base row plus its relationship values. */
+type ResultRow<C extends AnyCols, Rels, Sel extends string, Agg> = [Agg] extends [false]
+  ? Projected<C, Sel> & Rels
+  : Agg;
+
+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, Agg = false> {
   /** 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 +113,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 +205,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 +219,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,28 +236,81 @@ 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 }>;
+  /** Reshape this query into a top-level `count(*)` aggregate (`REDUCE-DESIGN.md` §8) — the SQL
+   *  `SELECT count(*) FROM table [GROUP BY …] [HAVING …]`. Without {@link groupBy} it is a GLOBAL
+   *  count (one `{ count }` row, value `0` even on empty input); with it, one `{ …group, count }`
+   *  row per distinct group. The result row becomes the aggregate's OUTPUT — the group-by columns
+   *  plus a numeric `count` — so chain {@link having} to filter it. Distinct from {@link countAs}
+   *  (a child-relationship scalar attached to the parent row); this reshapes the query ITSELF. The
+   *  engine rejects pairing a root aggregate with `select`/`sub`/`countAs`/`orderBy`/`limit`/`one`. */
+  count(): Query<C, Rels, One, Sel, LocalRels, AggAcc<Agg> & { count: number }>;
+  /** Add a top-level `GROUP BY` column (chain for a compound key); only meaningful with
+   *  {@link count}. Each grouped column joins the aggregate result row, keyed + sorted by the
+   *  group key. */
+  groupBy<K extends keyof C & string>(
+    col: K,
+  ): Query<C, Rels, One, Sel, LocalRels, AggAcc<Agg> & Pick<RowOf<C>, K>>;
+  /** `HAVING (…)` — filter the **post-aggregation** rows of a {@link count} query (`REDUCE-DESIGN.md`
+   *  §4: a filter directly above the reduce). `build` receives a field binder over the aggregate's
+   *  OUTPUT columns — the {@link groupBy} columns and the synthetic `count` — and returns a
+   *  {@link Cond}; compose several with `and`/`or`. E.g.
+   *  `.groupBy("status").count().having((h) => h.count(gt(3)))`. Distinct from {@link where}, which
+   *  filters base rows BELOW the reduce. */
+  having(build: (h: HavingProxy<AggAcc<Agg>>) => Cond<AggAcc<Agg>>): Query<C, Rels, One, Sel, LocalRels, Agg>;
+  /** `HAVING count(child) <op> n` — filter THIS parent by a child relationship aggregate's count
+   *  (`PARENT-AGGREGATE-FILTER-DESIGN.md`). `alias` must name a {@link countAs} relationship already
+   *  on this query; this drops parents whose child count fails `<op> val`, maintained incrementally
+   *  (a child add/remove crossing the threshold adds/removes the parent). The display `countAs` is
+   *  untouched — a survivor still shows its real count. Distinct from the {@link having} overload
+   *  above, which filters a top-level {@link count}'s own output rows.
+   *
+   *  **v1: high-pass predicates only** — predicates *false* at count 0 (`>`, `>=`/`=`/`!=` for
+   *  `n ≥ 1`). A childless parent forms no group, so the engine rejects (at build) a predicate *true*
+   *  at count 0 (`<=`, `< n` for `n ≥ 1`, `= 0`, `>= 0`); those need row-widening (deferred). */
+  having<A extends AggregateAlias<Rels>>(
+    alias: A,
+    op: SimpleOp,
+    val: number,
+  ): Query<C, Rels, One, Sel, LocalRels, Agg>;
   /** 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>;
+   *  yields a {@link SingularArrayView}; otherwise an {@link ArrayView}. The row is the aggregate
+   *  output once {@link count} reshaped the query, else masked to the projection ({@link Projected})
+   *  — full {@link RowOf} until a column is `select`ed. */
+  materialize(): MaterializedView<ResultRow<C, Rels, Sel, Agg>, 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,
+  Agg = false,
+> =
+  & Omit<QueryBase<C, Rels, One, Sel, LocalRels, Agg>, "where">
+  & { where: QueryBase<C, Rels, One, Sel, LocalRels, Agg>["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, any>;
+
+export type QueryLocalData<Q extends AnyQuery> =
+  Q extends Query<infer C, any, infer One, infer Sel, infer LocalRels, infer Agg>
+    ? [Agg] extends [false]
+      ? One extends true
+        ? (Projected<C, Sel> & LocalRels) | null
+        : readonly (Projected<C, Sel> & LocalRels)[]
+      : readonly Agg[]
+    : never;
 const STAMP_NAMED_QUERY: unique symbol = Symbol("rindle.stampNamedQuery");
 
 interface QueryInternals {
@@ -259,6 +434,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 +453,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 +497,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 -----------------------------
@@ -329,6 +697,12 @@ interface State {
   limit?: number;
   one: boolean;
   select?: string[];
+  // Top-level aggregate (REDUCE-DESIGN.md §8): `aggregate` reshapes the query into a `count(*)`;
+  // `groupBy` partitions it; `having` filters the post-aggregation rows. All three are read by the
+  // engine only together (see the guard in `compile`).
+  aggregate?: "count";
+  groupBy: string[];
+  having?: Condition;
 }
 
 interface NamedQueryState {
@@ -337,7 +711,7 @@ interface NamedQueryState {
 }
 
 function emptyState(table: string): State {
-  return { table, wheres: [], orderBy: [], related: [], one: false };
+  return { table, wheres: [], orderBy: [], related: [], one: false, groupBy: [] };
 }
 
 function compile(s: State): Ast {
@@ -351,6 +725,18 @@ function compile(s: State): Ast {
   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;
+  if (s.aggregate !== undefined) ast.aggregate = s.aggregate;
+  if (s.groupBy.length > 0) ast.groupBy = s.groupBy;
+  if (s.having !== undefined) ast.having = s.having;
+  // The engine takes the aggregate lowering ONLY when `aggregate` is set (REDUCE-DESIGN.md §8 /
+  // builder `build_pipeline`); `groupBy`/`having` on the row spine would be silently ignored. Fail
+  // loudly so a forgotten `.count()` is a clear error, not a query that quietly returns all rows.
+  if ((ast.groupBy !== undefined || ast.having !== undefined) && ast.aggregate === undefined) {
+    throw new Error(
+      "groupBy()/having() require count(): a top-level GROUP BY / HAVING is only honored on an " +
+        "aggregate query (REDUCE-DESIGN.md §8) — add .count().",
+    );
+  }
   return ast;
 }
 
@@ -401,22 +787,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 +913,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 +983,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:
@@ -599,6 +1006,52 @@ function makeQuery(
       };
       return next({ related: [...s.related, csq] });
     },
+    // Top-level aggregate (REDUCE-DESIGN §8): `count` reshapes this query into a `count(*)`;
+    // `groupBy` partitions it; `having` filters the post-aggregation rows. `having`'s callback gets
+    // a field binder over the aggregate's output columns (group cols + the synthetic `count`), so a
+    // predicate can name `count` — which lives on no base table — exactly like `where.<field>(…)`.
+    count: () => next({ aggregate: "count" }),
+    groupBy: (col: string) => next({ groupBy: [...s.groupBy, col] }),
+    having: (a: unknown, op?: SimpleOp, val?: number) => {
+      // Overload 1 — top-level aggregate HAVING: `having((h) => h.count(gt(3)))`. The callback
+      // binds the aggregate's output columns (group cols + the synthetic `count`).
+      if (typeof a === "function") {
+        const build = a as (h: Record<string, (arg: unknown) => Condition>) => Condition;
+        const h = new Proxy({} as Record<string, (arg: unknown) => Condition>, {
+          get: (_t, prop) => (typeof prop === "string" ? (arg: unknown) => fieldCondition(prop, arg) : undefined),
+        });
+        return next({ having: build(h) });
+      }
+      // Overload 2 — filter THIS parent by a child aggregate's count:
+      // `.having("commentCount", ">", 10)` (PARENT-AGGREGATE-FILTER-DESIGN.md). Bind the existing
+      // `countAs(alias, …)` relationship and push a hidden EXISTS whose subquery clones the same
+      // correlation + child + `count` aggregate, plus a `HAVING count <op> val`. The engine lowers
+      // it to an EXISTS over a HAVING-filtered reduce; the display `countAs` is untouched.
+      const alias = a as string;
+      const display = s.related.find(
+        (r) => r.subquery.alias === alias && r.subquery.aggregate === "count",
+      );
+      if (!display) {
+        throw new Error(
+          `having("${alias}", …): this query has no countAs("${alias}", …) relationship to filter ` +
+            `on — attach the child count aggregate first.`,
+        );
+      }
+      const gate: CorrelatedSubquery = {
+        correlation: display.correlation,
+        subquery: {
+          ...display.subquery,
+          alias: `__having_${alias}`,
+          having: {
+            type: "simple",
+            op: op as SimpleOp,
+            left: { type: "column", name: "count" },
+            right: { type: "literal", value: val as LitValue },
+          },
+        },
+      };
+      return next({ wheres: [...s.wheres, { type: "correlatedSubquery", op: "EXISTS", related: gate }] });
+    },
     ast: () => {
       const a = compile(s);
       guardAst?.(a);