@rindle/client 0.1.0-rc.5

package/src/schema.ts

@@ -0,0 +1,181 @@
+// The typed schema: `table("issue").columns({...}).primaryKey("id")` + `createSchema`.
+//
+// A table definition doubles as a field→condition factory (a runtime Proxy):
+// `issue.priority(gt(8))` produces a `Cond<RowOf<issue>>`. THAT is where the table type is
+// bound — which is why `or`/`exists` are plain top-level functions, no closure needed
+// (WASM-CLIENT-DESIGN.md §6). Schema metadata is stored under a `unique symbol` key so it
+// never collides with a column name.
+
+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. */
+export interface Col<T> {
+  readonly type: ColType;
+  readonly __t?: T;
+}
+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" });
+
+/** Metadata key on a {@link TableDef} (a `unique symbol`, so no column name collides). */
+export const SCHEMA: unique symbol = Symbol("rindle.schema");
+
+export interface TableMeta<N extends string = string, C extends AnyCols = AnyCols> {
+  readonly name: N;
+  readonly columns: C;
+  // Plain `string[]` (NOT `keyof C`): `keyof C` is contravariant, which would make
+  // `TableMeta` non-covariant in `C` and break `TableDef<concrete>` → `AnyTable`. Key
+  // validity is enforced on the `primaryKey()` builder method (`K extends keyof C`).
+  readonly primaryKey: readonly string[];
+}
+
+export type TableDef<N extends string, C extends AnyCols> = {
+  readonly [SCHEMA]: TableMeta<N, C>;
+} & {
+  readonly [K in keyof C]: (arg: Arg<ColT<C[K]>>) => Cond<RowOf<C>>;
+};
+
+/** Any table, for positions that only read its metadata. The field-factory part of a
+ *  `TableDef` is invariant in `C`, so callers constrain on the `[SCHEMA]` meta only — to
+ *  which every concrete `TableDef<N, C>` is assignable. */
+export type TableLike<C extends AnyCols> = { readonly [SCHEMA]: TableMeta<string, C> };
+export type AnyTable = TableLike<AnyCols>;
+
+/** The row type of a table definition: `Row<typeof issue>` → `{ id: string; … }`. The
+ *  whole-table ergonomic form of {@link RowOf}, so app code derives its row interfaces from
+ *  the schema instead of hand-maintaining a parallel twin. */
+export type Row<T extends AnyTable> = RowOf<T[typeof SCHEMA]["columns"]>;
+
+/** `table("issue").columns({ id: string(), … }).primaryKey("id")`. */
+export function table<N extends string>(name: N) {
+  return {
+    columns<C extends AnyCols>(cols: C) {
+      return {
+        primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C> {
+          return makeTableDef<N, C>({ name, columns: cols, primaryKey: keys });
+        },
+      };
+    },
+  };
+}
+
+function makeTableDef<N extends string, C extends AnyCols>(meta: TableMeta<N, C>): TableDef<N, C> {
+  return new Proxy({} as Record<string | symbol, unknown>, {
+    get(_target, prop) {
+      if (prop === SCHEMA) return meta;
+      if (typeof prop === "string") return (arg: unknown) => fieldCondition(prop, arg);
+      return undefined;
+    },
+  }) as unknown as TableDef<N, C>;
+}
+
+/** Read a table's metadata (columns / PK / name). */
+export function tableMeta(t: AnyTable): TableMeta {
+  return t[SCHEMA];
+}
+
+/** name → columns, derived from the tables array (for typing `store.query.<table>`). */
+export type SchemaOf<T extends readonly AnyTable[]> = {
+  [E in T[number] as E[typeof SCHEMA]["name"]]: E[typeof SCHEMA]["columns"];
+};
+
+/** name → columns, the resolved schema map carried in the {@link Schema} type. */
+export type ColsMap = Record<string, AnyCols>;
+
+export interface Schema<S extends ColsMap = ColsMap> {
+  readonly tables: Readonly<Record<string, TableMeta>>;
+  /** Phantom carrying name→columns for query-root inference (never read at runtime). */
+  readonly __cols: S;
+}
+
+export function createSchema<const T extends readonly AnyTable[]>(opts: {
+  tables: T;
+}): Schema<SchemaOf<T>> {
+  const tables: Record<string, TableMeta> = {};
+  for (const t of opts.tables) {
+    const m = t[SCHEMA];
+    tables[m.name] = m;
+  }
+  return { tables } as Schema<SchemaOf<T>>;
+}
+
+// ----------------------------- relationships (FRAGMENT-COMPOSITION-DESIGN §4.2, named edges) -----
+//
+// A relationship is the correlation (`parent.col → child.col`) declared ONCE as a value, so `sub`,
+// `countAs`, and `exists` don't restate `{ parent, child }` keys at every spread/filter site. It is a
+// plain typed value (not registered on the schema), passed where `(child, corr)` used to go.
+
+/** Brand on a {@link Relationship} value (a `unique symbol`, distinct from a {@link TableDef}). */
+const RELATIONSHIP_BRAND: unique symbol = Symbol("rindle.relationship");
+
+/**
+ * A reusable, typed JOIN between two tables — the correlation declared once (design §4). Built with
+ * {@link rel}; parameterized by the parent columns `PC` (so a `sub` checks the relationship belongs to
+ * the query's table) and the child columns `CC` (which flow into the nested result type). Pass it to
+ * `sub`/`countAs`/`exists` in place of an explicit `child` + `{ parent, child }` correlation.
+ */
+export interface Relationship<PC extends AnyCols, CC extends AnyCols> {
+  /** The child table the relationship points at. */
+  readonly child: TableLike<CC>;
+  /** Correlation keys: `parent[i]` (a parent column) joins to `child[i]` (a child column). */
+  readonly correlation: { readonly parent: readonly string[]; readonly child: readonly string[] };
+  /** Phantom binding the parent columns so `Query<C>.sub(alias, rel)` rejects a rel for another table. */
+  readonly __parent?: PC;
+  readonly [RELATIONSHIP_BRAND]: true;
+}
+
+/** Any relationship, for positions that only read its correlation / child table. */
+export type AnyRelationship = Relationship<AnyCols, AnyCols>;
+
+/**
+ * Declare a relationship once: `rel(issue, user, { ownerId: "id" })` means `issue.ownerId → user.id`.
+ * `mapping` is `{ [parentColumn]: childColumn }` (a composite join is multiple entries). The `parent`
+ * table is used only to type-check the keys; pass the result to `sub`/`countAs`/`exists`.
+ */
+export function rel<PC extends AnyCols, CC extends AnyCols>(
+  _parent: TableLike<PC>,
+  child: TableLike<CC>,
+  mapping: Partial<Record<keyof PC & string, keyof CC & string>>,
+): Relationship<PC, CC> {
+  const parent = Object.keys(mapping);
+  const childKeys = parent.map((k) => mapping[k as keyof PC & string] as string);
+  return { child, correlation: { parent, child: childKeys }, [RELATIONSHIP_BRAND]: true };
+}
+
+/** A typed registry of named {@link Relationship}s — `defineRelationships({ issueOwner: rel(...) })`.
+ *  A thin identity helper that names the bag and constrains its values; the keys are yours to choose. */
+export function defineRelationships<R extends Record<string, AnyRelationship>>(rels: R): R {
+  return rels;
+}
+
+/** Runtime guard: is `v` a {@link Relationship} value (not a table or a plain object)? */
+export function isRelationship(v: unknown): v is AnyRelationship {
+  return typeof v === "object" && v !== null && (v as Partial<AnyRelationship>)[RELATIONSHIP_BRAND] === true;
+}
+
+/** The `SchemaSpec` (`columns` + `primaryKey` indices) the wasm `Db.registerTable` wants. */
+export function tableSpec(meta: TableMeta): { columns: string[]; primaryKey: number[] } {
+  const columns = Object.keys(meta.columns);
+  const primaryKey = meta.primaryKey.map((k) => columns.indexOf(k));
+  return { columns, primaryKey };
+}
+
+/** The client's per-table flat schema (name + column order + PK indices), the shape a
+ *  normalized `hello` advertises (NORMALIZED-CHANGES-DESIGN.md §3). Used to validate a
+ *  server hello against the CLIENT's own typed schema so a column-order / PK skew is caught
+ *  instead of silently transposing positional cells (CRIT#4). Sorted by name for stable
+ *  ordering. */
+export function normalizedTableSchemas<S extends ColsMap>(
+  schema: Schema<S>,
+): { name: string; columns: string[]; primaryKey: number[] }[] {
+  return Object.keys(schema.tables)
+    .sort()
+    .map((name) => ({ name, ...tableSpec(schema.tables[name]) }));
+}

package/src/ssr.ts

@@ -0,0 +1,115 @@
+// SSR client integration (SSR-DESIGN.md §6). Server-side render is synchronous, so the data
+// must already be in the cache when the render reads it. The seam is the BACKEND, not the hook:
+//
+//   - Browser: the normal ws-backed Store — retain → lease → subscribe → live.
+//   - Server : a Store over a one-shot REST backend ({@link OneShotBackend}) that never streams.
+//              The route loader `preload`s each query (`POST /query`), which seeds the view for an
+//              instant correct first paint; `dehydrate` serializes those seeds into the HTML; the
+//              browser `store.hydrate(...)`s them and its live `subscribe` reconciles (§5).
+//
+// `useQuery` is byte-for-byte identical in both — only the injected backend (and whether a live
+// subscribe ever happens) differs.
+
+import type { Query } from "./query.ts";
+import type { ColsMap, Schema } from "./schema.ts";
+import { type AssembledNode, type DehydratedState, Store } from "./store.ts";
+import type { Backend, ChangeEvent, Mutation, QueryId, RemoteQuery } from "./types.ts";
+
+/** A `POST /query` response, as far as the server Store needs it (SSR-DESIGN.md §3.3): the
+ *  assembled rows plus the `cvMin` baseline they reflect. (Matches `@rindle/daemon-client`'s
+ *  `QueryOnceOutput`, but `@rindle/client` stays dependency-free — inject the call.) */
+export interface OneShotResult {
+  rows: AssembledNode[];
+  cvMin?: number;
+}
+
+/** The one-shot read the server Store calls to preload a query. Two topologies inject different
+ *  fns (SSR-DESIGN.md §6):
+ *
+ *   - **Direct to the daemon** (the trusted tier holds the daemon token): use `ast` —
+ *     `(i) => daemon.query(i)`.
+ *   - **Through the application's API tier** (the authority resolves names → ASTs, the loader never
+ *     sends a raw AST): use `name`/`args` — `(i) => fetch('/api/rindle/read', {name: i.name, args: i.args})`.
+ *
+ *  `ast` is always present (the Store seeds the local view by its `viewKey`); `name`/`args` are
+ *  present when the preloaded query came from `defineQuery`. The Store applies no policy/auth —
+ *  that lives upstream (the daemon, or the API tier's `authorizeQuery`). */
+export type OneShotQueryFn = (
+  input: { ast: unknown; name?: string; args?: unknown; visibilityKey?: string; ttlMs?: number },
+) => Promise<OneShotResult>;
+
+/**
+ * A no-op live backend for SSR (SSR-DESIGN.md §6.1): it opens no transport and never streams.
+ * `registerQuery`/`mutate` are inert and no `ChangeEvent` is ever pushed, so every view stays
+ * PENDING — reading its SSR {@link Store.seedAssembled seed} — and, lacking `onResultType`,
+ * reports `complete` (a backend with no server lifecycle leaves every view authoritative).
+ */
+export class OneShotBackend implements Backend {
+  registerQuery(_qid: QueryId, _ast: unknown, _remote?: RemoteQuery): void {}
+  unregisterQuery(_qid: QueryId): void {}
+  mutate(_mutations: Mutation[]): Promise<void> {
+    return Promise.reject(new Error("the SSR one-shot backend is read-only; mutate on the browser store"));
+  }
+  onEvent(_handler: (queryId: QueryId, event: ChangeEvent) => void): void {}
+}
+
+export interface ServerStoreOptions {
+  /** Performs the one-shot `POST /query` read (e.g. a `@rindle/daemon-client` instance's `query`). */
+  query: OneShotQueryFn;
+  /** Optional RLS/visibility dedup key forwarded to every preload (SSR-DESIGN.md §3.2). The daemon
+   *  scopes the materialization's dedup `QueryKey` by it, so the same AST under two visibility keys
+   *  never shares one pipeline; absent ⇒ the daemon's configured default. */
+  visibilityKey?: string;
+  /** Optional idle TTL (ms) the warm pipeline is left at, forwarded to every preload (SSR-DESIGN.md
+   *  §3.4). The TTL is NOT part of the dedup key, so a shared materialization keeps the LONGEST TTL
+   *  any caller requested (max-wins) — `ttlMs` can extend a query's warm-handoff window, never
+   *  shrink it; absent ⇒ the daemon's default idle TTL. */
+  ttlMs?: number;
+}
+
+/**
+ * The server-side Store wrapper (SSR-DESIGN.md §6.2). Wraps a {@link Store} over a
+ * {@link OneShotBackend} and adds the loader-phase `preload` plus `dehydrate`. Pass `.store` to
+ * the React `<Rindle>` provider for the synchronous render; return `.dehydrate()` from the loader.
+ */
+export class ServerStore<S extends ColsMap> {
+  readonly store: Store<S>;
+  private readonly opts: ServerStoreOptions;
+
+  constructor(schema: Schema<S>, opts: ServerStoreOptions) {
+    this.store = new Store(schema, new OneShotBackend());
+    this.opts = opts;
+  }
+
+  /** Run the one-shot read for `query` and seed its first-paint snapshot (SSR-DESIGN.md §6.2).
+   *  Call once per query in the route loader, before the synchronous render. */
+  async preload(query: Query<any, any, any>): Promise<void> {
+    const ast = query.ast();
+    // Forward the AST (a direct-to-daemon backend reads it) plus the named identity when this came
+    // from `defineQuery` (an API-tier backend resolves `(name, args)` → AST itself, never trusting
+    // a client AST). The seed is keyed by the AST's `viewKey` either way, so the browser's
+    // `getServerSnapshot` finds it (SSR-DESIGN.md §6.2).
+    const named = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
+    const result = await this.opts.query({
+      ast,
+      ...named,
+      visibilityKey: this.opts.visibilityKey,
+      ttlMs: this.opts.ttlMs,
+    });
+    this.store.seedAssembled(ast, result.rows, result.cvMin ?? 0);
+  }
+
+  /** The dehydrated first-paint cache for every preloaded query — embed in the HTML, then
+   *  `store.hydrate(...)` it in the browser. */
+  dehydrate(): DehydratedState {
+    return this.store.dehydrate();
+  }
+}
+
+/** Construct a {@link ServerStore} — the one-shot REST Store for server-side rendering. */
+export function createServerStore<S extends ColsMap>(
+  schema: Schema<S>,
+  opts: ServerStoreOptions,
+): ServerStore<S> {
+  return new ServerStore(schema, opts);
+}

package/src/store.ts

@@ -0,0 +1,279 @@
+// The Store — backend-agnostic glue (WASM-CLIENT-DESIGN.md §2). Holds the typed schema +
+// a `Backend`, exposes `store.query.<table>…materialize()` and `store.write(tx => …)`, and
+// routes the backend's per-query `ChangeEvent` stream into per-query `ArrayView`s.
+//
+// It never knows whether the backend is the in-process WASM engine or a remote server —
+// both speak `registerQuery` / `mutate` / `onEvent`. The Store owns: query-id assignment,
+// building each `ArrayView` (typed from the schema, so json columns parse), dispatching
+// hello/snapshot/batch events, and turning object-shaped writes into positional mutations.
+
+import type { Ast } from "./ast.ts";
+import { stableKey } from "./key.ts";
+import { queries, type Query, type QueryRoot } from "./query.ts";
+import type { ColsMap, RowOf, Schema } from "./schema.ts";
+import type { Backend, ChangeEvent, ColType, Mutation, QueryId, RemoteQuery, WireSchema, WireValue } from "./types.ts";
+import { type ArrayView, FlatArrayView, type SingularArrayView, SingularView, type ViewTypes } from "./view.ts";
+
+/** One query's SSR snapshot, keyed by its `viewKey` ({@link stableKey} of the AST): the
+ *  pre-projected first-paint `rows` plus the `cvMin` watermark they reflect (SSR-DESIGN.md §6.2).
+ *  Serializable as-is into the HTML — `rows` are already JSON values (json columns parsed). */
+export interface DehydratedQuery {
+  rows: unknown[];
+  cvMin: number;
+}
+
+/** The whole dehydrated cache: every preloaded query's snapshot, keyed by `viewKey`. The server
+ *  builds it with {@link Store.dehydrate}; the browser seeds it with {@link Store.hydrate}. */
+export type DehydratedState = Record<string, DehydratedQuery>;
+
+/** A single assembled (nested-by-name) row from `POST /query` (SSR-DESIGN.md §3.3): the cells
+ *  under `cols`, each in-view relationship inlined by its alias (a nested array / object, or a
+ *  scalar for a `countAs` aggregate). {@link Store.assembleSnapshot} converts these to the
+ *  view's projected result shape. */
+export interface AssembledNode {
+  cols: Record<string, WireValue>;
+  [rel: string]: unknown;
+}
+
+/** The write transaction handed to `store.write(tx => …)`. Rows are objects keyed by column;
+ *  the Store positionalizes them (and stringifies json columns) before the backend sees them. */
+export interface WriteTx<S extends ColsMap> {
+  add<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
+  remove<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
+  edit<N extends keyof S & string>(table: N, oldRow: RowOf<S[N]>, newRow: RowOf<S[N]>): void;
+}
+
+export interface CachedQueryView<Q extends Query<any, any, any>> {
+  readonly view: ReturnType<Q["materialize"]>;
+  /** Retain this query's named remote footprint and release it later. Ad-hoc local queries
+   *  return a no-op release function. */
+  retain(query: Q): () => void;
+  destroy(): void;
+}
+
+export class Store<S extends ColsMap> {
+  /** Type-safe query entry: `store.query.issue.where.closed(false).materialize()`. */
+  readonly query: QueryRoot<S>;
+
+  private readonly schema: Schema<S>;
+  private readonly backend: Backend;
+  private nextId = 1;
+  private readonly views = new Map<QueryId, FlatArrayView>();
+  private readonly asts = new Map<QueryId, Ast>();
+  // 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.
+  private readonly seeds = new Map<string, DehydratedQuery>();
+
+  constructor(schema: Schema<S>, backend: Backend) {
+    this.schema = schema;
+    this.backend = backend;
+    this.backend.onEvent((qid, ev) => this.onEvent(qid, ev));
+    // Route the backend's per-query lifecycle onto its view (`view.resultType`). Backends without a
+    // lifecycle omit `onResultType`, leaving every view `complete`.
+    this.backend.onResultType?.((qid, rt) => this.views.get(qid)?.setResultType(rt));
+    this.query = queries(this.schema, (query) => this.materialize(query)) as QueryRoot<S>;
+  }
+
+  /** Materialize any fluent query object. Named queries subscribe remotely by `(name,args)`;
+   *  ad-hoc builder queries are local-only for local-first backends. */
+  materialize<Q extends Query<any, any, any>>(query: Q): ReturnType<Q["materialize"]> {
+    const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
+    return this.registerMaterialized(query.ast(), remote).view as ReturnType<Q["materialize"]>;
+  }
+
+  /** True when the backend can retain a remote named query independently from the local
+   *  materialized AST view. React uses this to keep one local view per AST while still sending
+   *  every mounted `(name,args)` lease through the backend. */
+  canRetainRemoteQueries(): boolean {
+    return (
+      typeof this.backend.retainRemoteQuery === "function" &&
+      typeof this.backend.releaseRemoteQuery === "function"
+    );
+  }
+
+  /** Build one local AST view, with remote syncing retained separately through the returned
+   *  handle. This is a lower-level API for UI bindings; ordinary app code should keep using
+   *  `materialize(query)`. */
+  createCachedQueryView<Q extends Query<any, any, any>>(query: Q): CachedQueryView<Q> {
+    const { qid, view } = this.registerMaterialized(query.ast(), undefined);
+    let destroyed = false;
+    return {
+      view: view as ReturnType<Q["materialize"]>,
+      retain: (nextQuery: Q) => this.retainRemote(nextQuery, qid),
+      destroy: () => {
+        if (destroyed) return;
+        destroyed = true;
+        view.destroy();
+      },
+    };
+  }
+
+  /** 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. */
+  write(fn: (tx: WriteTx<S>) => void): Promise<void> {
+    const muts: Mutation[] = [];
+    const tx = {
+      add: (t: string, row: Record<string, unknown>) =>
+        muts.push({ op: "add", table: t, row: this.positionalize(t, row) }),
+      remove: (t: string, row: Record<string, unknown>) =>
+        muts.push({ op: "remove", table: t, row: this.positionalize(t, row) }),
+      edit: (t: string, o: Record<string, unknown>, n: Record<string, unknown>) =>
+        muts.push({ op: "edit", table: t, old: this.positionalize(t, o), new: this.positionalize(t, n) }),
+    } as unknown as WriteTx<S>;
+    fn(tx);
+    return Promise.resolve(this.backend.mutate(muts));
+  }
+
+  // --- SSR (SSR-DESIGN.md §6) ---------------------------------------------------
+
+  /** Seed a query's first-paint snapshot from a `POST /query` response (server side): convert the
+   *  assembled rows to the view's projected shape and stash them by `viewKey`. A view materialized
+   *  for this AST (during the synchronous render) reads the seed; {@link dehydrate} serializes it. */
+  seedAssembled(ast: Ast, rows: AssembledNode[], cvMin: number): void {
+    this.seeds.set(stableKey(ast), { rows: this.assembleSnapshot(ast, rows), cvMin });
+  }
+
+  /** The dehydrated first-paint cache for every preloaded query — embed it in the HTML and pass it
+   *  to {@link hydrate} in the browser (SSR-DESIGN.md §6.2). */
+  dehydrate(): DehydratedState {
+    return Object.fromEntries(this.seeds);
+  }
+
+  /** Seed the browser store from the server's {@link dehydrate} output (SSR-DESIGN.md §6.2): each
+   *  view materialized for a hydrated AST shows these rows until its first live `hello` reconciles. */
+  hydrate(state: DehydratedState): void {
+    for (const [key, snap] of Object.entries(state)) this.seeds.set(key, snap);
+  }
+
+  /** A query's hydrated first-paint snapshot, by `viewKey` — what React's `getServerSnapshot`
+   *  reads so an SSR render (and the matching client hydration pass) sees the seeded rows without
+   *  opening a subscription. */
+  seedSnapshot(viewKey: string): DehydratedQuery | undefined {
+    return this.seeds.get(viewKey);
+  }
+
+  /** 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). */
+  assembleSnapshot(ast: Ast, rows: AssembledNode[]): unknown[] {
+    return rows.map((row) => this.assembleNode(ast, row));
+  }
+
+  private assembleNode(ast: Ast, node: AssembledNode): Record<string, unknown> {
+    const cols = this.columns(ast.table);
+    const out: Record<string, unknown> = {};
+    for (const [name, v] of Object.entries(node.cols ?? {})) {
+      out[name] = cols[name]?.type === "json" && typeof v === "string" ? JSON.parse(v) : v;
+    }
+    for (const sub of ast.related ?? []) {
+      const alias = sub.subquery.alias;
+      if (alias === undefined || !(alias in node)) continue;
+      const child = node[alias];
+      if (Array.isArray(child)) {
+        out[alias] = child.map((c) => this.assembleNode(sub.subquery, c as AssembledNode));
+      } else if (child !== null && typeof child === "object") {
+        out[alias] = this.assembleNode(sub.subquery, child as AssembledNode); // .one() singular
+      } else {
+        out[alias] = child; // a `countAs` scalar aggregate, or a null singular relationship
+      }
+    }
+    return out;
+  }
+
+  // --- internals ---------------------------------------------------------------
+
+  private registerMaterialized(
+    ast: Ast,
+    remote?: RemoteQuery,
+  ): { qid: QueryId; view: ArrayView<unknown> | SingularArrayView<unknown> } {
+    const qid: QueryId = this.nextId++;
+    this.asts.set(qid, ast);
+    // Pre-create the view (PENDING) so `materialize` is synchronous for ANY backend — a remote
+    // backend's `hello` arrives async (the view reads as `[]` until then). A synchronous backend
+    // (wasm/replica) resets it during `registerQuery` below, so it returns already-hydrated.
+    const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView()).get(qid)!;
+    // Wire teardown: `destroy()` must unregister the query from the backend and drop our routing
+    // entry. Otherwise the engine keeps emitting events for the destroyed query and the Store
+    // routes them to the now-empty view — which throws on the next Child/remove ("parent not
+    // found") and, because dispatch is a single loop, aborts delivery to sibling queries too.
+    // This bites whenever a query is re-materialized (e.g. a changed limit/filter rebuilds it).
+    const baseDestroy = view.destroy.bind(view);
+    view.destroy = () => {
+      if (this.views.delete(qid)) {
+        this.asts.delete(qid);
+        this.backend.unregisterQuery(qid);
+      }
+      baseDestroy();
+    };
+    this.backend.registerQuery(qid, ast, remote);
+    // SSR first paint (SSR-DESIGN.md §6): if this AST was preloaded/hydrated, seed the view now.
+    // A synchronous backend (wasm) already reset the view above, so its live data wins and the
+    // seed is inert; an async backend (ws) leaves it PENDING, so the seed shows until `hello`.
+    const seed = this.seeds.get(stableKey(ast));
+    if (seed) view.seed(seed.rows);
+    // A top-level `.one()` (engine-capped to limit 1) unwraps at the result boundary.
+    return { qid, view: ast.one ? new SingularView(view) : view };
+  }
+
+  private retainRemote<Q extends Query<any, any, any>>(query: Q, localQueryId: QueryId): () => void {
+    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);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.backend.releaseRemoteQuery?.(qid);
+    };
+  }
+
+  private onEvent(qid: QueryId, ev: ChangeEvent): void {
+    if (ev.type === "hello") {
+      const ast = this.asts.get(qid);
+      // First live hello for this view ⇒ retire its SSR seed: the maintained tree now owns the
+      // result, so no future mount of the same query should flash the stale first-paint rows.
+      if (ast) this.seeds.delete(stableKey(ast));
+      const types = ast ? this.viewTypes(ev.schema, ast) : undefined;
+      // Reset the (pre-created or existing) view IN PLACE — first hello OR a re-hydrate (new
+      // epoch) — so the materialized reference the caller holds survives a re-subscribe.
+      const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView()).get(qid)!;
+      view.reset(ev.schema, types);
+    } else if (ev.type === "snapshot") {
+      this.views.get(qid)?.applyChanges(ev.adds);
+    } else {
+      this.views.get(qid)?.applyChanges(ev.events);
+    }
+  }
+
+  private columns(table: string): Record<string, { type: ColType }> {
+    const meta = this.schema.tables[table];
+    if (!meta) throw new Error(`unknown table: ${table}`);
+    return meta.columns as unknown as Record<string, { type: ColType }>;
+  }
+
+  /** An object row → a positional cell array in the table's column order (json → string). */
+  private positionalize(table: string, obj: Record<string, unknown>): WireValue[] {
+    const cols = this.columns(table);
+    return Object.keys(cols).map((name) => {
+      const v = obj[name];
+      if (cols[name].type === "json" && v != null && typeof v === "object") return JSON.stringify(v);
+      return (v ?? null) as WireValue;
+    });
+  }
+
+  /** The per-level column types parallel to the WireSchema, so the view parses json columns. */
+  private viewTypes(ws: WireSchema, ast: Ast): ViewTypes {
+    const cols = this.columns(ast.table);
+    const columnTypes = ws.columns.map((name) => cols[name]?.type ?? "string");
+    const rels: Record<number, ViewTypes> = {};
+    for (const rel of ws.relationships) {
+      if (!rel.child) continue;
+      const sub = (ast.related ?? []).find((r) => r.subquery.alias === rel.name);
+      if (sub) rels[rel.slot] = this.viewTypes(rel.child, sub.subquery);
+    }
+    return { columnTypes, rels };
+  }
+}