@rindle/client 0.2.0 → 0.4.2

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";
@@ -49,11 +49,36 @@ type Projected<C extends AnyCols, Sel extends string> = [Sel] extends [never]
   ? RowOf<C>
   : Pick<RowOf<C>, Sel & keyof C>;
 
+/**
+ * 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> {
+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. */
@@ -219,12 +244,49 @@ interface QueryBase<C extends AnyCols, Rels, One extends boolean, Sel extends st
     relationship: Relationship<C, CC>,
     build?: (q: Query<CC>) => Query<CC, unknown>,
   ): 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<
@@ -233,18 +295,21 @@ export type Query<
   One extends boolean = false,
   Sel extends string = never,
   LocalRels = Rels,
+  Agg = false,
 > =
-  & Omit<QueryBase<C, Rels, One, Sel, LocalRels>, "where">
-  & { where: QueryBase<C, Rels, One, Sel, LocalRels>["where"] & WhereProxy<C, Rels, One, Sel, LocalRels> }
+  & 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>;
 
-export type AnyQuery = Query<any, any, 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>
-    ? One extends true
-      ? (Projected<C, Sel> & LocalRels) | null
-      : readonly (Projected<C, Sel> & LocalRels)[]
+  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");
 
@@ -632,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 {
@@ -640,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 {
@@ -654,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;
 }
 
@@ -923,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);

package/src/resolve.ts

@@ -0,0 +1,136 @@
+// Positional → named change resolution: the inverse of the wire encoder.
+//
+// A backend ships per-query `FlatChange`s (types.ts): `{ path: PathSeg[], op: add|remove|edit }`,
+// where `path` indexes into the view's relationship tree and rows are POSITIONAL cells. The view
+// (view.ts) folds those into the materialized tree positionally; this module instead LIFTS one
+// change out of positional/indexed wire form into NAMED rows, resolving it against the query's OWN
+// `WireSchema` (the per-subscription view schema the engine ships once on its `hello` frame): per
+// level the column NAMES in wire order, and the relationships in SLOT order (a gating exists/notExists
+// slot is `child: null`; a `countAs` slot carries a `project` annotation). So `path[i].rel` indexes
+// `schema.relationships[i]` directly, and a positional `row` names against `schema.columns` — both
+// authoritative, straight from the engine.
+//
+// Resolving against the hello schema (rather than re-deriving positions from the query `Ast`) means
+// we assume NOTHING about slot ordering and NOTHING about column order: it stays correct under
+// `.select()` projections and any future slot layout. The result — named rows + an aggregate's exact
+// new value — is what a higher layer (e.g. @rindle/narrator) renders into prose, but it is broadly
+// useful to anything consuming a `FlatChange` (logging, devtools, change-driven overlays).
+//
+// NOTE on aggregates (`countAs`): the slot's `project.col` names the EXACT count cell in the child
+// row, so a count change reports the exact new value (and previous, on an edit) — not a best-effort
+// guess. A remove of the aggregate row means the count fell to its identity (`project.identity`).
+
+import type { FlatChange, PathSeg, WireNode, WireRel, WireSchema, WireValue } from "./types.ts";
+
+/** A row named against its level's wire columns. */
+export type NamedRow = Record<string, WireValue>;
+
+/** One resolved change: a `FlatChange` lifted out of positional/indexed wire form into names,
+ *  using the query's `WireSchema` (from `hello`) as the sole position→name source. */
+export interface ResolvedChange {
+  /** Relationship-alias chain from the query root to the changed level (`[]` ⇒ the root rows). */
+  aliasChain: string[];
+  /** The alias of the changed level (`""` ⇒ root), i.e. the last of `aliasChain`. */
+  alias: string;
+  op: "add" | "remove" | "edit";
+  /** The affected row, named. For `edit` this is the NEW row; see `old` for the prior one. */
+  row: NamedRow;
+  /** The prior row, named (present only for `edit`). */
+  old?: NamedRow;
+  /** The PARENT row (named), for a nested/aggregate change — e.g. the `ticket_type` whose `sold`
+   *  count moved. Taken from the path's last `parentRow`; absent for a root-level change. */
+  parent?: NamedRow;
+  /** Set when the changed level is a `countAs`/aggregate slot. The value is EXACT — read from the
+   *  slot's projected count column (`WireRel.project.col`). */
+  aggregate?: { alias: string; value: WireValue; previous?: WireValue };
+  /** The raw node whose children a consumer can dig a named sub-row out of (via {@link subRow}). On
+   *  an `add` the engine always ships it; on a `remove` it is present only when the consumer opted
+   *  into the removed subtree (see the `op` mapping below). */
+  node?: WireNode;
+  /** The changed level's `WireSchema` — used by {@link subRow} to resolve a named sub of `node`. */
+  levelSchema: WireSchema;
+}
+
+/** Name positional `cells` against a level's wire `columns` (insertion = wire order). */
+function nameRow(cells: WireValue[] | undefined, cols: string[]): NamedRow {
+  const out: NamedRow = {};
+  if (!cells) return out;
+  for (let i = 0; i < cols.length; i++) out[cols[i]] = cells[i] ?? null;
+  return out;
+}
+
+/** Walk a `path` from the root `WireSchema` down the relationship tree. Returns the reached level,
+ *  the alias chain, and the LAST relationship traversed (its `project` marks an aggregate slot).
+ *  `null` if a hop addresses an unknown or gating (`child: null`) slot. */
+function descend(
+  root: WireSchema,
+  path: PathSeg[],
+): { level: WireSchema; lastRel: WireRel | null; aliasChain: string[] } | null {
+  let level = root;
+  let lastRel: WireRel | null = null;
+  const aliasChain: string[] = [];
+  for (const seg of path) {
+    const rel = level.relationships[seg.rel];
+    if (!rel || !rel.child) return null; // unknown / gating slot — not a materialized level
+    lastRel = rel;
+    level = rel.child;
+    aliasChain.push(rel.name);
+  }
+  return { level, lastRel, aliasChain };
+}
+
+/** Lift one `FlatChange` into a {@link ResolvedChange} against the query's `WireSchema`, or `null`
+ *  if its path doesn't resolve to a materialized level. */
+export function resolveChange(schema: WireSchema, change: FlatChange): ResolvedChange | null {
+  const here = descend(schema, change.path);
+  if (!here) return null;
+  const { level, lastRel, aliasChain } = here;
+  const cols = level.columns;
+  const alias = aliasChain.length ? aliasChain[aliasChain.length - 1] : "";
+  const base: Omit<ResolvedChange, "op" | "row"> = { aliasChain, alias, levelSchema: level };
+  // The parent row (for a nested/aggregate change) sits in the last path seg, named against the
+  // level one hop up.
+  if (change.path.length) {
+    const up = descend(schema, change.path.slice(0, -1));
+    const parentCells = change.path[change.path.length - 1].parentRow;
+    if (up) base.parent = nameRow(parentCells, up.level.columns);
+  }
+
+  // A `countAs` slot carries a scalar `project` annotation on the relationship we descended through:
+  // `project.col` is the exact count cell, `project.identity` the empty value (0 for count).
+  const proj = lastRel?.project ?? null;
+  const agg = (cells: WireValue[] | undefined): WireValue => (proj && cells ? (cells[proj.col] ?? null) : null);
+
+  const op = change.op;
+  if (op.tag === "add") {
+    const r: ResolvedChange = { ...base, op: "add", row: nameRow(op.node.row, cols), node: op.node };
+    if (proj) r.aggregate = { alias, value: agg(op.node.row) };
+    return r;
+  }
+  if (op.tag === "remove") {
+    const r: ResolvedChange = { ...base, op: "remove", row: nameRow(op.row, cols) };
+    // The removed subtree rides along only when the consumer opted into it (the ArrayView attaches
+    // it client-side — `Store.subscribeChanges(_, { removedSubtree: true })`). When present, `subRow`
+    // resolves a removed row's nested subs exactly as on an `add`; absent, a remove is row-only.
+    if (op.node) r.node = op.node;
+    if (proj) r.aggregate = { alias, value: proj.identity };
+    return r;
+  }
+  // edit
+  const r: ResolvedChange = { ...base, op: "edit", row: nameRow(op.new, cols), old: nameRow(op.old, cols) };
+  if (proj) r.aggregate = { alias, value: agg(op.new), previous: agg(op.old) };
+  return r;
+}
+
+/** Read a named sub-row off a change's `node` by relationship alias (e.g. the `guest` under an
+ *  `rsvp`) — the `add` node, or a `remove`'s subtree when the consumer opted into it. The alias →
+ *  wire slot mapping comes from the changed level's `WireSchema`. `null` when no node rode along. */
+export function subRow(rc: ResolvedChange, alias: string): NamedRow | null {
+  if (!rc.node) return null;
+  const rel = rc.levelSchema.relationships.find((r) => r.name === alias);
+  if (!rel || !rel.child) return null;
+  const slot = rc.node.rels.find((s) => s.rel === rel.slot);
+  const child = slot?.children[0];
+  if (!child) return null;
+  return nameRow(child.row, rel.child.columns);
+}

package/src/schema.ts

@@ -10,7 +10,9 @@ import type { Arg, Cond } from "./operators.ts";
 import { fieldCondition } from "./operators.ts";
 import type { ColType } from "./types.ts";
 
-/** A column descriptor. `type` drives the comparator + JSON parsing; `__t` is a phantom. */
+/** A column descriptor. `type` drives the comparator + JSON parsing; `__t` is a phantom. A
+ *  nullable column is a `Col<T | null>` — that is the ONLY thing nullability changes at the type
+ *  level, so `RowOf` (and the field-condition factory) widen automatically. */
 export interface Col<T> {
   readonly type: ColType;
   readonly __t?: T;
@@ -19,10 +21,21 @@ export type ColT<X> = X extends Col<infer T> ? T : never;
 export type AnyCols = Record<string, Col<unknown>>;
 export type RowOf<C extends AnyCols> = { [K in keyof C]: ColT<C[K]> };
 
-export const string = (): Col<string> => ({ type: "string" });
-export const number = (): Col<number> => ({ type: "number" });
-export const boolean = (): Col<boolean> => ({ type: "boolean" });
-export const json = <T = unknown>(): Col<T> => ({ type: "json" });
+/** The chainable form returned by the column factories: a {@link Col} plus `.nullable()`.
+ *
+ *  `.nullable()` widens the column's value type to `T | null` — its `Row<…>` field becomes
+ *  `T | null`, and (design 206 Phase 2) it may be omitted from an insert. `rindle schema gen` emits
+ *  `.nullable()` for every nullable (non-`NOT NULL`) SQL column; you can also call it by hand on a
+ *  local-only table's columns. It is idempotent and stays chainable. */
+export interface ColBuilder<T> extends Col<T> {
+  nullable(): ColBuilder<T | null>;
+}
+const makeCol = <T>(type: ColType): ColBuilder<T> => ({ type, nullable: () => makeCol<T | null>(type) });
+
+export const string = <T extends string = string>(): ColBuilder<T> => makeCol<T>("string");
+export const number = <T extends number = number>(): ColBuilder<T> => makeCol<T>("number");
+export const boolean = (): ColBuilder<boolean> => makeCol<boolean>("boolean");
+export const json = <T = unknown>(): ColBuilder<T> => makeCol<T>("json");
 
 /** Metadata key on a {@link TableDef} (a `unique symbol`, so no column name collides). */
 export const SCHEMA: unique symbol = Symbol("rindle.schema");
@@ -175,6 +188,118 @@ function addTableMeta(tables: Record<string, TableMeta>, m: TableMeta, caller: "
   tables[m.name] = m;
 }
 
+// ----------------------------- refinement (narrowing generated column types) ---------------------
+//
+// SQL carries a column's KIND (string/number/boolean/json) but not a refinement WITHIN a kind — the
+// element type of `json<T>()`, or a string/number literal union. `refineTable` re-types those
+// columns on a generated `TableDef` (so its field conditions, `rel(...)`s, and `Row<typeof t>` all
+// narrow), and `refineSchema` swaps the refined defs into the generated schema (so query roots and
+// result rows narrow too). Both are runtime-validated IDENTITIES: a refinement narrows the phantom
+// TS type but can never change a column's runtime kind, so the def still matches the daemon's wire
+// schema exactly. Keep refinements in a hand-written module (beside `extendSchema`'s local tables);
+// `schema.gen.ts` stays a pure, wholesale-regenerated artifact.
+
+/** Per-column narrowings for {@link refineTable}: each entry must keep the column's kind and narrow
+ *  its TS type (`Col<T2>` with `T2 extends T`) — `json<Meta>()` on a json column, a literal-union
+ *  `string<"a" | "b">()` on a string column. Kind changes are rejected (cross-kind at compile time,
+ *  same-phantom kind flips like `string()` on a json column at runtime). */
+export type ColRefinements<C extends AnyCols> = {
+  readonly [K in keyof C]?: Col<ColT<C[K]>>;
+};
+
+/** `C` with the columns named in `R` re-typed to their refined `Col`s. */
+export type RefinedCols<C extends AnyCols, R extends ColRefinements<C>> = {
+  [K in keyof C]: K extends keyof R ? (R[K] extends Col<unknown> ? R[K] : C[K]) : C[K];
+};
+
+/** Narrow a generated table's column TYPES without touching its runtime shape.
+ *
+ *  Returns the SAME def, re-typed (identity, after validating that every refined column exists and
+ *  keeps its kind) — so conditions built from it, `rel(...)`s anchored on it, and `Row<typeof t>`
+ *  all see the narrowed types. Pass the result to {@link refineSchema} so query roots narrow too. */
+export function refineTable<N extends string, C extends AnyCols, R extends ColRefinements<C>>(
+  base: TableDef<N, C>,
+  cols: R,
+): TableDef<N, RefinedCols<C, R>> {
+  const meta = base[SCHEMA];
+  for (const [name, col] of Object.entries(cols) as [string, Col<unknown> | undefined][]) {
+    if (col === undefined) continue;
+    const baseCol = meta.columns[name];
+    if (baseCol === undefined) {
+      throw new Error(`refineTable: table "${meta.name}" has no column "${name}".`);
+    }
+    if (col.type !== baseCol.type) {
+      throw new Error(
+        `refineTable: column "${meta.name}.${name}" is ${baseCol.type}, not ${col.type} — a refinement ` +
+          `may only narrow the TS type WITHIN a column's kind, never change the kind itself.`,
+      );
+    }
+  }
+  return base as unknown as TableDef<N, RefinedCols<C, R>>;
+}
+
+/** A table def acceptable to {@link refineSchema} over `Schema<S>`: its NAME must be one of `S`'s
+ *  tables (a def for an unknown table is a compile error at the call site). */
+export type RefinableTable<S extends ColsMap> = {
+  readonly [SCHEMA]: TableMeta<Extract<keyof S, string>, AnyCols>;
+};
+
+/** `S` with each table named in `T` re-typed to that def's (refined) columns. (The inner
+ *  `extends AnyCols` guard is how the checker proves the remapped `SchemaOf<T>[K]` is a column
+ *  map while `T` is still generic; it always holds for a concrete `T`.) */
+export type RefinedColsMap<S extends ColsMap, T extends readonly AnyTable[]> = {
+  [K in keyof S]: K extends keyof SchemaOf<T> ? (SchemaOf<T>[K] extends AnyCols ? SchemaOf<T>[K] : S[K]) : S[K];
+};
+
+/** Swap {@link refineTable}-narrowed table defs into a generated schema, re-typing those tables for
+ *  everything downstream of the schema (`newQueryBuilder`/`queries` roots, store row types).
+ *
+ *  Runtime-validated identity: each def must name a table already in the schema and match its
+ *  runtime shape exactly (same columns, kinds, primary key, and locality) — refinement narrows TS
+ *  types, never what's on the wire. Composes with {@link extendSchema} in either order. */
+export function refineSchema<S extends ColsMap, const T extends readonly RefinableTable<S>[]>(
+  base: Schema<S>,
+  opts: { tables: T },
+): Schema<RefinedColsMap<S, T>> {
+  const seen = new Set<string>();
+  for (const t of opts.tables) {
+    const m = t[SCHEMA];
+    const baseMeta = base.tables[m.name];
+    if (baseMeta === undefined) {
+      throw new Error(
+        `refineSchema: schema has no table "${m.name}" — refinement re-types existing tables only ` +
+          `(add local-only tables with extendSchema).`,
+      );
+    }
+    if (seen.has(m.name)) {
+      throw new Error(`refineSchema: table "${m.name}" is refined twice.`);
+    }
+    seen.add(m.name);
+    assertRefinementMatches(m, baseMeta);
+  }
+  return base as unknown as Schema<RefinedColsMap<S, T>>;
+}
+
+/** The refined def must be the same table the schema already carries — identical column set, kinds,
+ *  primary key, and locality — so swapping its TYPE in cannot change any runtime behavior. */
+function assertRefinementMatches(m: TableMeta, baseMeta: TableMeta): void {
+  const cols = Object.keys(m.columns);
+  const baseCols = Object.keys(baseMeta.columns);
+  const matches =
+    cols.length === baseCols.length &&
+    cols.every((c) => baseMeta.columns[c] !== undefined && m.columns[c].type === baseMeta.columns[c].type) &&
+    m.primaryKey.length === baseMeta.primaryKey.length &&
+    m.primaryKey.every((k, i) => baseMeta.primaryKey[i] === k) &&
+    (m.local === true) === (baseMeta.local === true);
+  if (!matches) {
+    throw new Error(
+      `refineSchema: table "${m.name}" does not match the schema's table of that name — pass the ` +
+        `output of refineTable over the SAME generated def (identical columns, kinds, primary key, ` +
+        `and locality).`,
+    );
+  }
+}
+
 /** Whether `table` is a {@link TableMeta.local local-only} table in `schema` (an unknown table
  *  reads as non-local). The single locality predicate the backends key off. */
 export function isLocalTable<S extends ColsMap>(schema: Schema<S>, table: string): boolean {

package/src/ssr.ts

@@ -111,6 +111,27 @@ export class ServerStore<S extends ColsMap> {
   dehydrate(): DehydratedState {
     return this.store.dehydrate();
   }
+
+  /**
+   * Loader-phase convenience over {@link preload} + {@link dehydrate}: preload EVERY query (reads run
+   * concurrently) and return the dehydrated first-paint cache. Composition keeps this to one read per
+   * composed root query — no request waterfall (SSR-DESIGN.md §6.2).
+   *
+   * A failed read degrades to NO seed for that one query — `onError` fires and the browser's live
+   * engine fills it in right after hydration — rather than rejecting the whole batch (which would trip
+   * the route's error boundary). The seed is a first-paint optimization; the live `subscribe` is the
+   * source of truth, so a missing seed never affects correctness. Without `onError` a failed read is
+   * swallowed silently — pass one to log.
+   */
+  async preloadAll(
+    queries: Array<Query<any, any, any>>,
+    opts: { onError?: (query: Query<any, any, any>, err: unknown) => void } = {},
+  ): Promise<DehydratedState> {
+    await Promise.all(
+      queries.map((query) => this.preload(query).catch((err) => opts.onError?.(query, err))),
+    );
+    return this.dehydrate();
+  }
 }
 
 /** Construct a {@link ServerStore} — the one-shot REST Store for server-side rendering. */