@rindle/client 0.1.0-rc.5

package/src/types.ts

@@ -0,0 +1,234 @@
+// Wire + protocol types for the flat-change client core (WASM-CLIENT-DESIGN.md §2, §6).
+//
+// Cells cross the boundary BARE (the host has a typed schema, so per-column types are
+// known here, not per-cell). JSON columns cross as their raw JSON string.
+
+/** A bare wire cell. (JSON columns arrive as their raw JSON string.) */
+export type WireValue = number | string | boolean | null;
+
+/** Declared column type (from the typed schema) — drives the comparator + JSON parsing. */
+export type ColType = "string" | "number" | "boolean" | "json";
+
+/** A scalar-projection annotation on a relationship slot (REDUCE-DESIGN.md §9): a
+ *  relationship aggregate (`issue { commentCount: count(comments) }`) lives as a singular
+ *  one-row relationship whose child is the aggregate row; this tells the receiver to unwrap
+ *  it into a scalar field — `commentCount: 5` instead of `commentCount: [{ count: 5 }]`. */
+export interface WireProjection {
+  /** Which CHILD column to surface as the scalar value (the aggregate column). */
+  col: number;
+  /** The value to emit when the relationship is empty (a childless parent) — the
+   *  aggregate identity (`0` for count, `null` for sum/avg). */
+  identity: WireValue;
+}
+
+export interface WireRel {
+  name: string;
+  slot: number;
+  /** `null` ⇒ an out-of-view / gating slot (the in-view gate drops `Child`s addressed here). */
+  child: WireSchema | null;
+  /** Non-null ⇒ a scalar-projected relationship aggregate the receiver unwraps to a scalar
+   *  (REDUCE-DESIGN.md §9). Absent/`null` for an ordinary (plural or `.one()`) relationship. */
+  project?: WireProjection | null;
+}
+
+export interface WireSchema {
+  columns: string[];
+  primaryKey: number[];
+  /** Resolved, PK-completed sort: `[columnIndex, ascending]` pairs (the comparator input). */
+  sort: [number, boolean][];
+  singular: boolean;
+  relationships: WireRel[];
+}
+
+export interface WireNode {
+  row: WireValue[];
+  rels: { rel: number; children: WireNode[] }[];
+}
+
+export interface PathSeg {
+  rel: number;
+  parentRow: WireValue[];
+}
+
+export type FlatOp =
+  | { tag: "add"; node: WireNode }
+  | { tag: "remove"; row: WireValue[] }
+  | { tag: "edit"; old: WireValue[]; new: WireValue[] };
+
+export interface FlatChange {
+  path: PathSeg[];
+  op: FlatOp;
+}
+
+/**
+ * What a {@link Backend} pushes per query: the handshake (`hello`), the (possibly
+ * chunked) hydrate `snapshot`, then incremental `batch`es. The core builds an ArrayView
+ * on `hello`, hydrates on `snapshot`, folds on `batch` — identically for any backend.
+ */
+export type ChangeEvent =
+  | { type: "hello"; schema: WireSchema; comparatorVersion: number }
+  | { type: "snapshot"; adds: FlatChange[]; last: boolean }
+  | { type: "batch"; events: FlatChange[] };
+
+export type Mutation =
+  | { op: "add"; table: string; row: WireValue[] }
+  | { op: "remove"; table: string; row: WireValue[] }
+  | { op: "edit"; table: string; old: WireValue[]; new: WireValue[] };
+
+/**
+ * A table-tagged, path-free row delta — the **normalized** wire payload (the path-free twin
+ * of {@link FlatChange}; NORMALIZED-CHANGES-DESIGN.md §3). Rows are positional (bare cells; a
+ * json column is its raw JSON string). `op` is the discriminant. Lives here (not in
+ * `@rindle/normalized`) so both the protocol (`@rindle/remote`) and the sync layer share one type.
+ */
+export type NormalizedOp =
+  | { table: string; op: "add"; row: WireValue[] }
+  | { table: string; op: "remove"; row: WireValue[] }
+  | { table: string; op: "edit"; old: WireValue[]; new: WireValue[] };
+
+/** One base table's flat schema on the normalized `hello` (§3): column names (in order) +
+ *  primary-key column indices. Wire rows are positional against `columns`. */
+export interface NormalizedTableSchema {
+  name: string;
+  columns: string[];
+  primaryKey: number[];
+}
+
+/**
+ * A per-query NORMALIZED stream event — the path-free twin of {@link ChangeEvent}. The
+ * `hello` carries the flat per-table schemas (no nested view schema, §3); `snapshot`/`batch`
+ * carry table-tagged {@link NormalizedOp}s. The `NormalizedSync` layer folds these into the
+ * local engine's base tables.
+ *
+ * `cv` (the global commit version the frame's data reflects — OPTIMISTIC-WRITES-DESIGN.md
+ * §8.3/§8.6) is present on sources that speak the optimistic protocol; the plain normalized
+ * path may omit it.
+ */
+export type NormalizedEvent =
+  | { type: "hello"; tables: NormalizedTableSchema[]; comparatorVersion: number; normalizedFp: string }
+  | { type: "snapshot"; ops: NormalizedOp[]; cv?: number }
+  | { type: "batch"; ops: NormalizedOp[]; cv?: number };
+
+export type QueryId = number;
+
+/** A query's SERVER-CHANNEL state, surfaced on its {@link ArrayView} (FOLDED-MUTATIONS-DESIGN §7 —
+ *  formerly conflated with pending-ness, OPTIMISTIC-WRITES-DESIGN.md §6):
+ *   - `unknown`  — not hydrated: the server has not produced a first result for this query yet;
+ *   - `complete` — the server has answered. STAYS `complete` while a local mutation is pending (the
+ *                  prediction is the client's best current answer); reversion on rejection is an
+ *                  event (`onRejected`), not a downgrade of completeness;
+ *   - `error`    — RESERVED for a future server-side, query-level error signal
+ *                  (see `designs/QUERY-ERRORS-DESIGN.md`); no longer produced by a pending mutation.
+ *  "Is a prediction pending here?" is now a separate reactive axis (the backend's `pending(qid)` /
+ *  `onPending`), not folded into this type. A backend with no server lifecycle (the in-process
+ *  engine) leaves every view `complete`. */
+export type ResultType = "unknown" | "complete" | "error";
+
+/** The network identity for a named query subscription. The local AST remains local; remote
+ *  normalized/optimistic sources use only this `(name,args)` pair upstream. */
+export interface RemoteQuery {
+  name: string;
+  args: unknown;
+}
+
+/**
+ * The seam the core talks to. Backend-agnostic: the same interface for the in-process
+ * WASM backend and a remote (network) backend. The core never knows which. A backend
+ * pushes a per-query {@link ChangeEvent} stream via {@link Backend.onEvent}; the remote
+ * backend additionally owns the epoch/seq/gap protocol and emits only clean, in-order
+ * events (so the ArrayView never sees the wire protocol).
+ */
+export interface Backend {
+  registerQuery(queryId: QueryId, ast: unknown, remote?: RemoteQuery): void;
+  unregisterQuery(queryId: QueryId): void;
+  /** Optional split path for local-first backends: retain/release a named remote footprint
+   *  without creating another local materialized view. `localQueryId`, when provided, names
+   *  the local AST view this remote footprint feeds. */
+  retainRemoteQuery?(queryId: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void;
+  releaseRemoteQuery?(queryId: QueryId): void;
+  /** Local: applies now (changes flow back on the stream). Remote: sends to the server. */
+  mutate(mutations: Mutation[]): Promise<void>;
+  onEvent(handler: (queryId: QueryId, event: ChangeEvent) => void): void;
+  /** Optional: the backend pushes per-query {@link ResultType} changes here and the core routes
+   *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the
+   *  in-process engine) omit it and every view stays `complete`. */
+  onResultType?(handler: (queryId: QueryId, resultType: ResultType) => void): void;
+}
+
+/**
+ * The server side of the **normalized** local-first path (NORMALIZED-CHANGES-DESIGN.md §5/§7):
+ * registers queries and pushes each one's normalized footprint stream ({@link NormalizedEvent}s).
+ * Both the in-process native (`@rindle/replica`) source and the ws (`@rindle/remote`
+ * `RemoteNormalizedSource`) implement it; `@rindle/normalized`'s `NormalizedBackend` consumes one,
+ * never knowing which — a sibling seam of {@link Backend} for the normalized composition.
+ */
+export interface NormalizedSource {
+  registerQuery(queryId: QueryId, remote: RemoteQuery): void;
+  unregisterQuery(queryId: QueryId): void;
+  /** Send base-table writes to the server; the authoritative stream flows back. */
+  mutate(mutations: Mutation[]): Promise<void>;
+  onNormalized(handler: (queryId: QueryId, event: NormalizedEvent) => void): void;
+  /** Optional: the backend hands its OWN typed per-table schemas so the source can validate
+   *  each server `hello` against them (column order / PK by name) and reject a schema skew
+   *  rather than silently transposing positional cells (CRIT#4 / §3 "drift ⇒ re-subscribe").
+   *  Sources that can't skew (the in-process native source) may omit it. */
+  expectClientSchema?(tables: NormalizedTableSchema[]): void;
+}
+
+/** The upstream named-mutator envelope (OPTIMISTIC-WRITES-DESIGN.md §8.1): the wire
+ *  carries the name + JSON args, never code; `mid` totally orders a client's mutations. */
+export interface MutationEnvelope {
+  clientID: string;
+  mid: number;
+  name: string;
+  args: unknown;
+}
+
+/** The connection-level progress frame (§8.6): advances the coherent-apply release point
+ *  (`cvMin`). A pure release signal — mutation confirmation does NOT ride it: `lmid` is a
+ *  row in {@link CLIENT_MUTATIONS_TABLE}, delivered through the client's own per-client
+ *  system query ({@link LMID_QUERY_NAME}) like any data, so it is released by the same
+ *  `cvMin` as the commit's effects (transactionally coherent by construction). */
+export interface ProgressFrame {
+  cvMin: number;
+}
+
+/** The replicated bookkeeping table carrying each client's high-water mutation id
+ *  (`lmid`). Engine-hosted and served like any base table; reserved (never part of a
+ *  user schema). Columns: `[client_id, last_mutation_id]`, PK `client_id`. */
+export const CLIENT_MUTATIONS_TABLE = "_rindle_client_mutations";
+
+/** The reserved server-query name every optimistic client subscribes at connect: the
+ *  one-row system query `CLIENT_MUTATIONS_TABLE WHERE client_id = <me>`. The server
+ *  derives the identity from the connection (args are ignored). */
+export const LMID_QUERY_NAME = "_rindle/clientLmid";
+
+/** The system table's wire schema — appended to the client's expected schemas so the
+ *  lmid query's `hello` passes CRIT#4 validation. */
+export const CLIENT_MUTATIONS_SCHEMA: NormalizedTableSchema = {
+  name: CLIENT_MUTATIONS_TABLE,
+  columns: ["client_id", "last_mutation_id"],
+  primaryKey: [0],
+};
+
+/**
+ * The server side of the OPTIMISTIC path (OPTIMISTIC-WRITES-DESIGN.md §8): the
+ * {@link NormalizedSource} stream with `cv`-tagged data frames, plus the connection-level
+ * {@link ProgressFrame} channel and the named-mutator upstream. The client buffers data
+ * frames by `cv` and applies all `cv ≤ cvMin` as one coherent release (§8.5).
+ */
+export interface OptimisticSource {
+  registerQuery(queryId: QueryId, remote: RemoteQuery): void;
+  unregisterQuery(queryId: QueryId): void;
+  /** Ship one named-mutator invocation upstream (§8.1). Confirmation rides the progress frames. */
+  pushMutation(envelope: MutationEnvelope): Promise<void>;
+  onNormalized(handler: (queryId: QueryId, event: NormalizedEvent) => void): void;
+  onProgress(handler: (frame: ProgressFrame) => void): void;
+  /** Optional: the backend hands its OWN typed per-table schemas so the source validates each
+   *  server `hello` against them and rejects a schema skew (CRIT#4); see {@link NormalizedSource}. */
+  expectClientSchema?(tables: NormalizedTableSchema[]): void;
+  /** Optional: fired when the server restarts (a transport that can detect it, e.g. via a daemon
+   *  boot id). The backend resets its `cv` watermark so the server's reset `cv` sequence is
+   *  accepted rather than dropped as stale. In-process sources never restart and omit it. */
+  onRestart?(handler: () => void): void;
+}

package/src/view.ts

@@ -0,0 +1,348 @@
+// The JS ArrayView — the materialized, typed result tree a backend's ChangeEvent stream
+// folds into (WASM-CLIENT-DESIGN.md §7, §8). A faithful port of the View's `apply_change`
+// (src/view.rs / src/flat_receiver.rs), the §6 receiver contract of FLAT-CHANGES-DESIGN.md:
+// descend the path with the in-view gate, then Add / Remove / Edit (rc + the edit-move
+// ghost/adjusted-position/merge protocol) located by value-driven binary search.
+//
+// Reads are cheap and reference-stable: each node memoizes its projected output (`out`),
+// invalidated only along the root→mutation spine, so `.data` re-projects only what changed
+// and untouched subtrees keep their object identity (React/Solid memoize on it).
+
+import { compareRows } from "./compare.ts";
+import type { ColType, FlatChange, FlatOp, ResultType, WireNode, WireSchema, WireValue } from "./types.ts";
+
+/** Per-level column types (parallel to the WireSchema), used to JSON.parse json columns on
+ *  projection. Built by the Store from the typed schema; absent ⇒ no parsing (bare values). */
+export interface ViewTypes {
+  columnTypes: ColType[];
+  rels: Record<number, ViewTypes>;
+}
+
+/** The public ArrayView contract `materialize()` returns. */
+export interface ArrayView<R> {
+  /** The current materialized result (reference-stable where data is unchanged). */
+  readonly data: readonly R[];
+  /** The query's SERVER-CHANNEL state (`unknown` while loading, `complete` once server-authoritative;
+   *  the `error` variant is reserved and currently unproduced). A pending optimistic mutation no
+   *  longer moves this — it is a separate axis (FOLDED-MUTATIONS-DESIGN §7). `complete` for backends
+   *  with no server lifecycle. Changes notify subscribers. */
+  readonly resultType: ResultType;
+  /** Subscribe; fires immediately with the current data, then after each applied batch (and after
+   *  a {@link resultType} change — re-read `resultType` in the listener). */
+  subscribe(listener: (data: readonly R[]) => void): () => void;
+  /** Tear down + stop receiving updates. */
+  destroy(): void;
+}
+
+/** What a top-level `.one()` query materializes to: the single row (or `null`), not an array.
+ *  A thin adapter over a {@link FlatArrayView} — all the folding is shared; only the result
+ *  boundary unwraps (`data[0] ?? null`). Reference identity of the row is preserved. */
+export interface SingularArrayView<R> {
+  /** The single current row, or `null` when the query matches nothing. */
+  readonly data: R | null;
+  /** The query's lifecycle state — see {@link ArrayView.resultType}. */
+  readonly resultType: ResultType;
+  /** Subscribe; fires immediately with the current row, then after each applied batch (and after
+   *  a {@link resultType} change). */
+  subscribe(listener: (data: R | null) => void): () => void;
+  /** Tear down + stop receiving updates. */
+  destroy(): void;
+}
+
+/** Wrap a plural {@link FlatArrayView} as a {@link SingularArrayView} for a `.one()` query
+ *  (the engine caps it to `limit = 1`, so the top list holds at most one node). */
+export class SingularView<R> implements SingularArrayView<R> {
+  private readonly inner: ArrayView<R>;
+
+  constructor(inner: ArrayView<R>) {
+    this.inner = inner;
+  }
+
+  get data(): R | null {
+    return this.inner.data[0] ?? null;
+  }
+
+  get resultType(): ResultType {
+    return this.inner.resultType;
+  }
+
+  subscribe(listener: (data: R | null) => void): () => void {
+    return this.inner.subscribe((d) => listener(d[0] ?? null));
+  }
+
+  destroy(): void {
+    this.inner.destroy();
+  }
+}
+
+/** An internal reconstruction node: the row, multi-path refcount, per-slot child lists,
+ *  and a memoized projected output (`null` ⇒ stale, rebuilt on next read). */
+interface Node {
+  row: WireValue[];
+  rc: number;
+  rels: Node[][];
+  out: unknown;
+}
+
+function binarySearch(
+  list: Node[],
+  row: WireValue[],
+  sort: [number, boolean][],
+): { found: boolean; index: number } {
+  let lo = 0;
+  let hi = list.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    const c = compareRows(list[mid].row, row, sort);
+    if (c < 0) lo = mid + 1;
+    else if (c > 0) hi = mid;
+    else return { found: true, index: mid };
+  }
+  return { found: false, index: lo };
+}
+
+/** Build a fresh node (rc = 1) with its inline subtree, mirroring `init_rels_for_new_entry`:
+ *  one list per declared slot; fill in-view slots from the payload (children inserted in the
+ *  order shipped — NEVER re-sorted — folding same-sort-key dups to rc += 1). */
+function buildNode(wnode: WireNode, schema: WireSchema): Node {
+  const rels: Node[][] = schema.relationships.map(() => []);
+  for (const { rel, children } of wnode.rels) {
+    const child = schema.relationships[rel]?.child;
+    if (!child) continue; // join-only / gating slot — not materialized
+    const built: Node[] = [];
+    for (const c of children) {
+      const at = binarySearch(built, c.row, child.sort);
+      if (at.found) built[at.index].rc += 1;
+      else built.splice(at.index, 0, buildNode(c, child));
+    }
+    rels[rel] = built;
+  }
+  return { row: wnode.row, rc: 1, rels, out: null };
+}
+
+function cloneNode(n: Node): Node {
+  return { row: n.row.slice(), rc: n.rc, rels: n.rels.map((r) => r.map(cloneNode)), out: null };
+}
+
+const EMPTY: readonly never[] = Object.freeze([]);
+
+export class FlatArrayView<R = unknown> implements ArrayView<R> {
+  // `null` ⇒ PENDING (no schema yet): a remote backend's `hello` arrives async, so the view
+  // exists (and reads as `[]`) before its schema lands. Set by `reset` (first hello / re-hydrate).
+  private schema: WireSchema | null;
+  private types?: ViewTypes;
+  // SSR first-paint seed (SSR-DESIGN.md §6): pre-projected rows installed by `seed`, returned by
+  // `data` WHILE pending (no live schema yet). Cleared on `reset` — the first live `hello` —
+  // so the maintained tree takes over and the live snapshot reconciles. `null` ⇒ no seed.
+  private seeded: readonly R[] | null = null;
+  private top: Node[] = [];
+  private dirty = true;
+  private cached: readonly R[] | null = null;
+  // `complete` by default: a backend with no server lifecycle (the in-process engine) never pushes
+  // a resultType, so its views read as authoritative. The Store overrides this for backends that do
+  // (the optimistic backend: `unknown` until hydrated, etc.).
+  private rt: ResultType = "complete";
+  private readonly listeners = new Set<(data: readonly R[]) => void>();
+
+  constructor(schema?: WireSchema, types?: ViewTypes) {
+    this.schema = schema ?? null;
+    this.types = types;
+  }
+
+  get resultType(): ResultType {
+    return this.rt;
+  }
+
+  /** Set the query's lifecycle state (the Store routes the backend's per-query signal here).
+   *  Notifies subscribers on a change so a status-bound listener (React `useQueryStatus`) re-reads,
+   *  WITHOUT re-projecting data (it is unchanged). */
+  setResultType(rt: ResultType): void {
+    if (this.rt === rt) return;
+    this.rt = rt;
+    for (const l of this.listeners) l(this.data);
+  }
+
+  /** (Re)bind to a schema and clear the tree IN PLACE. The first `hello` (pending → ready)
+   *  and a re-hydrate (gap → new epoch — FLAT-CHANGES-DESIGN.md §2.3) both go through here, so
+   *  the caller's view reference and its subscribers survive a re-subscribe. Does NOT notify —
+   *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker. */
+  reset(schema: WireSchema, types?: ViewTypes): void {
+    this.schema = schema;
+    this.types = types;
+    this.seeded = null; // live data takes over; the seed was first-paint only
+    this.top = [];
+    this.cached = null;
+    this.dirty = true;
+  }
+
+  /** Install a pre-projected SSR first-paint snapshot (SSR-DESIGN.md §6). The rows are already
+   *  in result shape (json columns parsed, relationships nested), so a view with no live backend
+   *  (the server one-shot Store) reads them directly, and a browser view shows them until its
+   *  first live `hello` (`reset`) swaps in the maintained tree. Does NOT notify — it is set at
+   *  materialize time, before any subscriber, and the live snapshot that follows notifies. */
+  seed(rows: readonly R[]): void {
+    this.seeded = rows;
+  }
+
+  /** Apply a batch (the hydrate snapshot or one transaction's events) in order, then
+   *  notify subscribers once. Order is significant (FLAT-CHANGES-DESIGN.md §5.4). A no-op
+   *  while pending (changes never precede the `hello` that resets the schema). */
+  applyChanges(events: FlatChange[]): void {
+    if (this.schema === null) return;
+    for (const e of events) this.applyAt(this.top, this.schema, e.path, e.op, 0);
+    this.dirty = true;
+    this.notify();
+  }
+
+  get data(): readonly R[] {
+    if (this.schema === null) return this.seeded ?? (EMPTY as readonly R[]);
+    if (!this.dirty && this.cached !== null) return this.cached;
+    this.cached = this.top.map((n) => this.project(n, this.schema as WireSchema, this.types)) as R[];
+    this.dirty = false;
+    return this.cached;
+  }
+
+  subscribe(listener: (data: readonly R[]) => void): () => void {
+    this.listeners.add(listener);
+    listener(this.data);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  destroy(): void {
+    this.listeners.clear();
+    this.top = [];
+  }
+
+  // --- apply -------------------------------------------------------------------
+
+  private applyAt(list: Node[], schema: WireSchema, path: FlatChange["path"], op: FlatOp, depth: number): void {
+    if (depth === path.length) {
+      this.applyOp(list, schema, op);
+      return;
+    }
+    const seg = path[depth];
+    const child = schema.relationships[seg.rel]?.child;
+    if (!child) return; // in-view gate: a gating slot drops the whole change
+    const { found, index } = binarySearch(list, seg.parentRow, schema.sort);
+    if (!found) throw new Error("flat ArrayView: parent not found at path hop (inconsistent stream)");
+    const node = list[index];
+    node.out = null; // a descendant changed → this node must re-project its rel array
+    this.applyAt(node.rels[seg.rel], child, path, op, depth + 1);
+  }
+
+  private applyOp(list: Node[], schema: WireSchema, op: FlatOp): void {
+    if (op.tag === "add") this.applyAdd(list, schema, op.node);
+    else if (op.tag === "remove") this.applyRemove(list, schema, op.row);
+    else this.applyEdit(list, schema, op.old, op.new);
+  }
+
+  private applyAdd(list: Node[], schema: WireSchema, wnode: WireNode): void {
+    const at = binarySearch(list, wnode.row, schema.sort);
+    if (at.found) list[at.index].rc += 1; // duplicate path to an existing row; ignore subtree
+    else list.splice(at.index, 0, buildNode(wnode, schema));
+  }
+
+  private applyRemove(list: Node[], schema: WireSchema, row: WireValue[]): void {
+    const at = binarySearch(list, row, schema.sort);
+    if (!at.found) throw new Error("flat ArrayView: remove of a non-existent node");
+    if (list[at.index].rc === 1) list.splice(at.index, 1);
+    else list[at.index].rc -= 1;
+  }
+
+  private applyEdit(list: Node[], schema: WireSchema, oldRow: WireValue[], newRow: WireValue[]): void {
+    const sort = schema.sort;
+    if (compareRows(oldRow, newRow, sort) === 0) {
+      // Sort key unchanged → edit in place (keeps position + children + rc).
+      const at = binarySearch(list, oldRow, sort);
+      if (!at.found) throw new Error("flat ArrayView: edit of a non-existent node");
+      list[at.index].row = newRow;
+      list[at.index].out = null;
+      return;
+    }
+
+    // Sort key changed → the row may move; rc may be > 1.
+    const oldAt = binarySearch(list, oldRow, sort);
+    if (!oldAt.found) throw new Error("flat ArrayView: edit old node does not exist");
+    const oldPos = oldAt.index;
+    const oldRc = list[oldPos].rc;
+    const raw = binarySearch(list, newRow, sort);
+    const found = raw.found;
+    const pos = raw.index;
+    const oldEntry = cloneNode(list[oldPos]); // capture (with children) BEFORE mutating
+
+    // Fast path: rc==1 and the row lands in the same slot after removal → edit in place.
+    if (oldRc === 1 && (pos === oldPos || pos - 1 === oldPos)) {
+      list[oldPos].row = newRow;
+      list[oldPos].out = null;
+      return;
+    }
+
+    // General move.
+    const newRc = oldRc - 1;
+    let adjusted: number;
+    if (newRc === 0) {
+      list.splice(oldPos, 1);
+      adjusted = oldPos < pos ? pos - 1 : pos;
+    } else {
+      list[oldPos].rc = newRc; // ghost survives for the other path(s); its row is unchanged
+      adjusted = pos;
+    }
+    if (found) {
+      // Merge into the existing destination entry (keep its children); bump its rc.
+      const existingRc = list[adjusted].rc;
+      list[adjusted].row = newRow;
+      list[adjusted].rc = existingRc + 1;
+      list[adjusted].out = null;
+    } else {
+      // Move the (edited) old entry — keeping its children — to the new position.
+      oldEntry.row = newRow;
+      oldEntry.rc = 1;
+      list.splice(adjusted, 0, oldEntry);
+    }
+  }
+
+  // --- projection (memoized, structurally shared) -----------------------------
+
+  private project(node: Node, schema: WireSchema, types?: ViewTypes): unknown {
+    if (node.out !== null) return node.out;
+    const obj: Record<string, unknown> = {};
+    for (let i = 0; i < schema.columns.length; i++) {
+      const v = node.row[i];
+      // A projected query carries an ABSENT cell (`undefined`, PROJECTION-SUPPORT-DESIGN.md
+      // §5.3) for a column it did not sync; omit it from the result object so a query never
+      // resolves a row from columns it did not select (§6). A present-and-null cell is `null`
+      // and is kept. For a `'*'` query no cell is ever `undefined`, so this is inert (§7).
+      if (v === undefined) continue;
+      // convert-once: a json column's raw string is parsed to an object on store (cached in `out`).
+      obj[schema.columns[i]] = types?.columnTypes[i] === "json" && typeof v === "string" ? JSON.parse(v) : v;
+    }
+    for (const rel of schema.relationships) {
+      if (rel.child === null) continue; // gating slot — not part of .data
+      const childList = node.rels[rel.slot] ?? [];
+      const ct = types?.rels[rel.slot];
+      if (rel.project) {
+        // A scalar-projected relationship aggregate (REDUCE-DESIGN.md §9): unwrap the one-row
+        // child to a bare scalar (its project.col cell), substituting the aggregate identity
+        // when empty (a childless parent). A json-typed projected column is parsed like a column.
+        const cell = childList.length > 0 ? childList[0].row[rel.project.col] : rel.project.identity;
+        const projType = ct?.columnTypes[rel.project.col];
+        obj[rel.name] = projType === "json" && typeof cell === "string" ? JSON.parse(cell) : cell;
+        continue;
+      }
+      obj[rel.name] = rel.child.singular
+        ? childList.length > 0
+          ? this.project(childList[0], rel.child, ct)
+          : null
+        : childList.map((c) => this.project(c, rel.child as WireSchema, ct));
+    }
+    node.out = obj;
+    return obj;
+  }
+
+  private notify(): void {
+    const d = this.data;
+    for (const l of this.listeners) l(d);
+  }
+}