@rindle/normalized 0.1.0-rc.5

package/dist/sync.js

@@ -0,0 +1,366 @@
+// NormalizedSync — the client-side cross-query refcount + GC layer of the normalized
+// local-first path (NORMALIZED-CHANGES-DESIGN.md §5), extended with the client column
+// UNION for projection support (PROJECTION-SUPPORT-DESIGN.md §4). It sits between the
+// per-query normalized streams (each an independent, validated `NormalizedOp` batch from
+// the server, via `@rindle/remote`) and the client's one shared normalized store (the wasm
+// `Db`'s base tables). The server already de-duplicates *intra-query* multi-path (§4.2);
+// this layer does the *cross-query* refcount the server deliberately does NOT — so a base
+// row shared by N queries lands in the local `Db` exactly once and is GC'd only when the
+// last query stops referencing it.
+//
+// It is the half the design calls out as "NO CVR" ([[no-cvr-client-refcounts]]): the
+// refcount is per-row on the *client*, keyed by `(table, pk)`, with each query's footprint
+// tracked as a membership set. The query-id rides at the subscription envelope, never on a
+// row (§5.1) — so this layer is fed per-query (`applyBatch(queryId, ops)`).
+//
+// **Projection (the client column union, PROJECTION-SUPPORT-DESIGN.md §4).** A *projected*
+// query streams rows positional over its OWN (narrower) schema; the client scatters those
+// cells into the shared base-table positions via the query's registered column map
+// (`registerProjection`) and leaves the rest ABSENT (the `undefined` marshal token, §5.3).
+// The same map also absorbs the reverse skew — a server WIDER than the client (an expanded
+// table mid `expand-then-contract` migration): a wire column the client doesn't have maps to a
+// DROP sentinel (`-1`) and its cell is discarded, so an old client keeps working against a
+// newer server. (Mapping is BY NAME, so neither a narrower nor a wider server mis-aligns.)
+// The base row a query group holds is the **union over all referencing queries'
+// projections** (§2): widening (`add`/`edit` brings new columns) column-merges them in;
+// narrowing (`dropQuery`, or a query's `remove` of a still-referenced row) recomputes the
+// union from the *remaining* queries and resets dropped columns to ABSENT — the client-side
+// equivalent of Zero's `remove-keys` (§4.2). A `'*'` query (no registered projection)
+// contributes all columns, so any row it references is full and present everywhere: the
+// union never introduces ABSENT and behavior is byte-identical to before projection (§7).
+//
+// Output: a NET `Mutation[]` to apply to the wasm `Db` in ONE `write()` transaction (the
+// design's "stage into one txn, commit once"). This module is pure logic — it never
+// touches the `Db`; the `NormalizedStore` (Slice 5) feeds the mutations to it.
+/**
+ * The Absent token on the JS side (PROJECTION-SUPPORT-DESIGN.md §5.3): an absent cell in a
+ * positional UNION row. The wasm marshal maps `undefined` → `OwnedValue::Absent` (and `null`
+ * → present-and-null), so forwarding a union row with `undefined` cells is how the local
+ * engine learns a column is not present on a shared row.
+ */
+const ABSENT = undefined;
+/** Elementwise equality over positional rows (json columns compare as strings; `ABSENT`
+ *  compares equal only to `ABSENT`). */
+function rowEq(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+export class NormalizedSync {
+    pkCols;
+    /** Per-table full width, for scattering projected rows. Empty ⇒ projection unsupported
+     *  (every query must be `'*'`), which is the pre-projection behavior. */
+    colCounts;
+    /** `(table, pk)` key → the one shared base entry. */
+    base = new Map();
+    /** queryId → the set of `(table, pk)` keys that query currently footprints. */
+    qfoot = new Map();
+    /** queryId → (table → the base ColIds it contributes for that table, in the order its wire
+     *  rows are positional against — its `required_cols` for the table, §4.1). A query spans
+     *  multiple base tables (root + related/EXISTS children), each projected independently; a
+     *  table absent from the inner map ⇒ that query syncs it `'*'` (all columns, full width). */
+    qcols = new Map();
+    constructor(pkCols, colCounts = {}) {
+        this.pkCols = pkCols;
+        this.colCounts = colCounts;
+    }
+    /**
+     * Register a query's projection for one base table (PROJECTION-SUPPORT-DESIGN.md §4.1): the
+     * base ColIds it contributes for `table`, in the order that table's wire rows are positional
+     * against. Omit a table (or never call) for a `'*'` table — it then contributes every column
+     * and its rows are full width. Must be called before the query's first batch.
+     *
+     * A `cols[i] < 0` entry is a DROP sentinel: wire column `i` is an EXPANDED server column the
+     * client doesn't have (the server side of an `expand-then-contract` migration), so its cell is
+     * discarded rather than scattered. The query still contributes only its real (`>= 0`) ColIds.
+     */
+    registerProjection(queryId, table, cols) {
+        let byTable = this.qcols.get(queryId);
+        if (!byTable) {
+            byTable = new Map();
+            this.qcols.set(queryId, byTable);
+        }
+        byTable.set(table, cols.slice());
+    }
+    /**
+     * Drop a query's projection for one table, reverting it to `'*'` (full presence, rows scattered
+     * verbatim). The inverse of {@link registerProjection}; a no-op if none was registered. Needed
+     * because `qcols` persists across re-hydrate epochs: if a live subscription's hello narrows from
+     * an EXPANDED layout (a `-1`-bearing map) back to an exact full-width one, the stale map must be
+     * cleared or it would mis-scatter the now-exact rows. A no-op for an unprojected (`'*'`) table.
+     */
+    unregisterProjection(queryId, table) {
+        this.qcols.get(queryId)?.delete(table);
+    }
+    /**
+     * Register a table's primary-key columns after construction — for a **synthetic aggregate
+     * table** (`AGGREGATE-SYNC-DESIGN.md` §3.3): a relationship `count` is synced as a
+     * server-authoritative `__agg_*` base table that is not in the client's typed schema, so
+     * the backend registers it here (and on the local engine) as queries that use it arrive.
+     * Idempotent — re-registering the same table (a second query over the same aggregate)
+     * is a no-op. Once registered, its rows refcount/GC exactly like any base table.
+     */
+    registerTable(table, primaryKey) {
+        this.pkCols[table] = primaryKey;
+    }
+    /**
+     * The inverse of {@link registerTable} for a synthetic aggregate table whose last
+     * referencing query is gone (`AGGREGATE-SYNC-DESIGN.md` §4): drop its primary-key
+     * registration so the table is unknown again. A balanced stream has already GC'd its rows
+     * at the `1→0` transition (via {@link dropQuery}); defensively this also sweeps any residual
+     * base rows + per-query footprint entries for the table, so a later re-registration of the
+     * same name starts clean. A no-op for an unregistered table.
+     */
+    unregisterTable(table) {
+        delete this.pkCols[table];
+        // A balanced stream GC's the rows at 1→0 (dropQuery); defensively sweep any residual base
+        // rows + footprint references for this table (matched on the entry's stored table —
+        // separator-agnostic) so a re-register of the same name starts clean.
+        const stale = new Set();
+        for (const [k, e] of this.base)
+            if (e.table === table)
+                stale.add(k);
+        for (const k of stale)
+            this.base.delete(k);
+        if (stale.size)
+            for (const foot of this.qfoot.values())
+                for (const k of stale)
+                    foot.delete(k);
+    }
+    /**
+     * Apply one query's normalized batch (its hydrate snapshot or one transaction's ops) and
+     * return the NET base-table mutations to commit to the wasm `Db` in a single transaction.
+     * Cross-query refcount + per-query dedup + column union (§4, §5):
+     * - `add`: counted into this query's footprint once; on the base `0→1` transition the row
+     *   enters at this query's projection; on a `1→N` transition the query's columns are merged
+     *   into the shared union (widen) and an `edit` is forwarded if the union changed.
+     * - `remove`: on the base `N→0` transition the row leaves; on `N→M>0` the union is recomputed
+     *   from the remaining queries and an `edit` narrows the shared row.
+     * - `edit`: column-merge this query's cells into the shared union; forward once (idempotent
+     *   across queries — same source row, same values).
+     */
+    applyBatch(queryId, ops) {
+        const muts = [];
+        const foot = this.footOf(queryId);
+        for (const op of ops) {
+            if (op.op === "add")
+                this.add(queryId, foot, op.table, this.scatter(queryId, op.table, op.row), muts);
+            else if (op.op === "remove")
+                this.remove(queryId, foot, op.table, this.scatter(queryId, op.table, op.row), muts);
+            else
+                this.edit(op.table, this.scatter(queryId, op.table, op.new), muts);
+        }
+        return muts;
+    }
+    /**
+     * Re-hydrate one query under a new epoch (§5.3): the server re-sent `queryId`'s whole
+     * footprint as seq-0 `add`s. Diff the new footprint against the query's current one —
+     * rows only in the old set leave (refcount out, GC/narrow), rows only in the new set enter
+     * (refcount in / widen), and an intersecting row whose value changed during the gap is an
+     * edit. Only `queryId`'s references move; other queries' counts are untouched. Returns the
+     * net mutations to commit.
+     */
+    rehydrate(queryId, snapshot) {
+        const muts = [];
+        const foot = this.footOf(queryId);
+        // The new footprint, keyed; a re-hydrate snapshot is all `add`s.
+        const next = new Map();
+        for (const op of snapshot) {
+            if (op.op !== "add")
+                continue;
+            const row = this.scatter(queryId, op.table, op.row);
+            next.set(this.key(op.table, row), { table: op.table, row });
+        }
+        // Rows that left: in the old footprint but not the new one.
+        for (const key of [...foot]) {
+            if (!next.has(key))
+                this.removeKey(queryId, foot, key, muts);
+        }
+        // Rows that entered or changed.
+        for (const [key, { table, row }] of next) {
+            if (foot.has(key)) {
+                // Still referenced — only forward an edit if the union changed during the gap.
+                const e = this.base.get(key);
+                if (e)
+                    this.mergeInto(e, row, table, muts);
+            }
+            else {
+                this.add(queryId, foot, table, row, muts);
+            }
+        }
+        return muts;
+    }
+    /**
+     * Drop a query (§5.1): decrement its footprint's refcounts, GC each row at the last
+     * reference (or narrow the union if others remain), and forget the query. `O(footprint)`,
+     * no per-row scan. Returns the net mutations. (The caller also tells the server to
+     * deregister the stream.)
+     */
+    dropQuery(queryId) {
+        const muts = [];
+        const foot = this.qfoot.get(queryId);
+        if (!foot)
+            return muts;
+        for (const key of [...foot])
+            this.removeKey(queryId, foot, key, muts);
+        this.qfoot.delete(queryId);
+        this.qcols.delete(queryId);
+        return muts;
+    }
+    // --- introspection (for tests / the Store) ---------------------------------
+    /** The number of distinct base rows currently synced into the local store. */
+    baseSize() {
+        return this.base.size;
+    }
+    /** How many queries currently reference `(table, row)` (0 if absent). The lookup keys by PK,
+     *  so a projected `row` need only carry its PK columns at the base positions. */
+    refCount(table, row) {
+        return this.base.get(this.key(table, row))?.queries.size ?? 0;
+    }
+    /**
+     * The synced (server-authoritative) row currently held for `(table, pkCells)`, or
+     * `undefined` if no query references it. `pkCells` are the primary-key cells in
+     * `primaryKey` order (NOT a full row) — the same key the cross-query refcount uses.
+     *
+     * The optimistic aggregate overlay (`AGGREGATE-SYNC-DESIGN.md` §4) reads the server's
+     * `__agg` count cell through this so it can compute `displayed = server_base ⊕ delta`
+     * from the authoritative base rather than re-deriving it from the local engine's head
+     * (which already carries the optimistic layer — a torn read).
+     */
+    baseRow(table, pkCells) {
+        const cols = this.pkCols[table];
+        if (!cols)
+            throw new Error(`NormalizedSync: no primary key registered for table ${table}`);
+        // Place the pk cells at their schema positions so `key()` reduces this probe to the
+        // exact same string it builds for any full row with these key cells.
+        const probe = [];
+        cols.forEach((c, j) => (probe[c] = pkCells[j]));
+        return this.base.get(this.key(table, probe))?.row;
+    }
+    // --- internals -------------------------------------------------------------
+    footOf(queryId) {
+        let foot = this.qfoot.get(queryId);
+        if (!foot) {
+            foot = new Set();
+            this.qfoot.set(queryId, foot);
+        }
+        return foot;
+    }
+    /** Scatter a query's (possibly narrower) wire row for `table` into the shared full-width
+     *  positional layout. No registered projection for `(queryId, table)` ⇒ a `'*'` table whose
+     *  row is already full width (returned as-is). Otherwise allocate a full-width row of
+     *  `ABSENT` and place `row[i]` at `cols[i]`. */
+    scatter(queryId, table, row) {
+        const cols = this.qcols.get(queryId)?.get(table);
+        if (!cols)
+            return row; // '*' — already full width, present everywhere
+        const width = this.colCounts[table];
+        if (width === undefined) {
+            throw new Error(`NormalizedSync: no column count registered for projected table ${table}`);
+        }
+        const out = new Array(width).fill(ABSENT);
+        // `cols[i] < 0` ⇒ wire column `i` is an expanded server column the client lacks: drop its
+        // cell, leaving the client's narrower row intact. Known columns map by name to their base
+        // position, so a server wider than (or reordered vs.) the client still scatters correctly.
+        for (let i = 0; i < cols.length; i++)
+            if (cols[i] >= 0)
+                out[cols[i]] = row[i];
+        return out;
+    }
+    /** Column-merge `incoming`'s present cells over `e.row` (a widen / pure-value change) and
+     *  forward a single `edit` if the union changed. Both rows are full width. */
+    mergeInto(e, incoming, table, muts) {
+        const merged = e.row.map((cur, i) => (incoming[i] !== ABSENT ? incoming[i] : cur));
+        if (!rowEq(merged, e.row)) {
+            muts.push(mut("edit", table, e.row, merged));
+            e.row = merged;
+        }
+    }
+    add(queryId, foot, table, row, muts) {
+        const key = this.key(table, row);
+        if (foot.has(key))
+            return; // this query already references it
+        foot.add(key);
+        const e = this.base.get(key);
+        if (e) {
+            e.queries.add(queryId); // another query already synced the row → no Db add (would dup-key)
+            // …but this query may carry NEW columns (widen) or a NEWER value for a shared column
+            // (the gainer half of a server commit that edits the same row on a holder query's
+            // stream, CRIT#3). Column-merge and forward an edit at the new union if it changed.
+            this.mergeInto(e, row, table, muts);
+        }
+        else {
+            this.base.set(key, { table, row, queries: new Set([queryId]) });
+            muts.push(mut("add", table, undefined, row)); // 0→1
+        }
+    }
+    remove(queryId, foot, table, row, muts) {
+        this.removeKey(queryId, foot, this.key(table, row), muts);
+    }
+    removeKey(queryId, foot, key, muts) {
+        if (!foot.has(key))
+            return; // not referenced by this query
+        foot.delete(key);
+        const e = this.base.get(key);
+        if (!e)
+            return; // defensive: inconsistent stream
+        e.queries.delete(queryId);
+        if (e.queries.size === 0) {
+            this.base.delete(key);
+            muts.push(mut("remove", e.table, undefined, e.row)); // N→0
+        }
+        else {
+            // Others still reference it → recompute the union from the remaining queries and narrow
+            // the shared row (reset any column no longer contributed to ABSENT). §4.2.
+            const present = this.presentCols(e.queries, e.table);
+            if (present === null)
+                return; // a '*' query still holds it → full presence, no narrowing
+            const narrowed = e.row.map((cell, i) => (present.has(i) ? cell : ABSENT));
+            if (!rowEq(narrowed, e.row)) {
+                muts.push(mut("edit", e.table, e.row, narrowed));
+                e.row = narrowed;
+            }
+        }
+    }
+    edit(table, next, muts) {
+        // PK is stable across an edit, so `next` keys the existing entry.
+        const key = this.key(table, next);
+        const e = this.base.get(key);
+        if (!e)
+            return; // defensive: edit of an untracked row
+        this.mergeInto(e, next, table, muts); // column-merge; dedups (no-op) if already applied
+    }
+    /** The columns present on a `table` row footprinted by `queries`: the union of their
+     *  projections for that table. `null` ⇒ all columns present (some referencing query syncs
+     *  the table `'*'`), so the row is full. */
+    presentCols(queries, table) {
+        const out = new Set();
+        for (const q of queries) {
+            const cols = this.qcols.get(q)?.get(table);
+            if (!cols)
+                return null; // a '*' query contributes every column for this table
+            for (const c of cols)
+                if (c >= 0)
+                    out.add(c); // skip DROP sentinels (expanded server cols)
+        }
+        return out;
+    }
+    key(table, row) {
+        const cols = this.pkCols[table];
+        if (!cols)
+            throw new Error(`NormalizedSync: no primary key registered for table ${table}`);
+        return `${table} ${JSON.stringify(cols.map((i) => row[i]))}`;
+    }
+}
+/** Build a `Mutation`. A union row may carry `ABSENT` (`undefined`) cells — the wasm `mutate`
+ *  ABI accepts them as the Absent token (§5.3) — so the row crosses as `WireValue[]` with that
+ *  understood sentinel. */
+function mut(op, table, old, row) {
+    if (op === "edit")
+        return { op, table, old: old ?? [], new: row };
+    return { op, table, row: row };
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rindle/normalized",
+  "version": "0.1.0-rc.5",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "directory": "packages/normalized"
+  },
+  "type": "module",
+  "description": "Normalized local-first client glue: NormalizedSync (cross-query refcount + GC + footprint diffing) driving the wasm Db's base tables (NORMALIZED-CHANGES-DESIGN.md §5).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rindle/client": "0.1.0-rc.5",
+    "@rindle/wasm": "0.1.0-rc.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "@rindle/replica": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit && node --conditions=@rindle/source --test test/*.test.ts && node --conditions=@rindle/source test/e2e.mjs && node --conditions=@rindle/source test/projection.e2e.mjs"
+  }
+}

package/src/agg-table.ts

@@ -0,0 +1,216 @@
+// Synthetic aggregate tables (AGGREGATE-SYNC-DESIGN.md §3.1/§3.3) — the client twin of
+// `rindle-replica/src/normalize.rs`. A relationship `count` is never recomputed locally
+// (the client lacks the child rows); the server ships the reduce's `(group_key, count)`
+// output as a SYNTHETIC base table, and the client:
+//   1. registers that table on its local engine + the `NormalizedSync` refcount layer,
+//   2. rewrites the local AST so the relationship reads the table with a plain singular
+//      join + the same scalar projection (`aggregatePrecomputed`) instead of a reduce.
+//
+// The table NAME is a content hash of the aggregate's definition, so client and server
+// agree without coordinating. `aggTableName` is the **byte-exact** twin of Rust
+// `agg_table_name` — the FNV-1a-64 byte protocol documented there; cross-language vectors
+// pin it (Rust `agg_table_name_cross_language_vector` ↔ this module's test).
+
+import type {
+  Aggregate,
+  Ast,
+  Condition,
+  CorrelatedSubquery,
+  Correlation,
+  LitValue,
+  NormalizedTableSchema,
+  ValuePosition,
+} from "@rindle/client";
+
+// FNV-1a-64, the same constants as `protocol.ts`'s `Fnv` (a local copy so `@rindle/normalized`
+// keeps no dependency on `@rindle/remote`). The byte methods mirror Rust `normalize::Fnv`.
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x00000100000001b3n;
+const MASK = 0xffffffffffffffffn;
+const enc = new TextEncoder();
+
+class Fnv {
+  h = FNV_OFFSET;
+  byte(b: number): void {
+    this.h = ((this.h ^ BigInt(b & 0xff)) * FNV_PRIME) & MASK;
+  }
+  /** A `u32` little-endian (Rust `v.to_le_bytes()`). */
+  u32(v: number): void {
+    this.byte(v & 0xff);
+    this.byte((v >>> 8) & 0xff);
+    this.byte((v >>> 16) & 0xff);
+    this.byte((v >>> 24) & 0xff);
+  }
+  /** A length-prefixed string: `u32(byteLen)` then UTF-8 bytes. */
+  s(str: string): void {
+    const bytes = enc.encode(str);
+    this.u32(bytes.length);
+    for (const b of bytes) this.byte(b);
+  }
+  /** An `f64` little-endian (Rust `n.to_le_bytes()` — IEEE-754 binary64). */
+  f64(v: number): void {
+    const buf = new ArrayBuffer(8);
+    new DataView(buf).setFloat64(0, v, true);
+    for (const b of new Uint8Array(buf)) this.byte(b);
+  }
+  hex(): string {
+    return this.h.toString(16).padStart(16, "0");
+  }
+}
+
+/** The synthetic base-table name for a relationship `count` aggregate — the byte-exact twin
+ *  of Rust `agg_table_name` (`normalize.rs` §3.1). A content hash of the aggregate definition
+ *  (child table, kind, group key = correlation **child** fields, child `where`); the parent
+ *  correlation field is excluded. Same definition ⇒ same name (cross-query sharing); a
+ *  different filter ⇒ a different name (no `(table, pk)` collision). */
+export function aggTableName(csq: CorrelatedSubquery): string {
+  const f = new Fnv();
+  f.u32(csq.correlation.childField.length);
+  for (const cf of csq.correlation.childField) f.s(cf);
+  hashAggSubquery(f, csq.subquery);
+  return `__agg_${f.hex()}`;
+}
+
+function hashAggSubquery(f: Fnv, ast: Ast): void {
+  f.s(ast.table);
+  f.byte(ast.aggregate === "count" ? 1 : 0); // Some(Count)=1, None=0
+  if (ast.where === undefined) f.byte(0);
+  else {
+    f.byte(1);
+    hashCondition(f, ast.where);
+  }
+  const related = ast.related ?? [];
+  f.u32(related.length);
+  for (const r of related) {
+    hashCorrelation(f, r.correlation);
+    hashAggSubquery(f, r.subquery);
+  }
+}
+
+function hashCorrelation(f: Fnv, c: Correlation): void {
+  f.u32(c.parentField.length);
+  for (const p of c.parentField) f.s(p);
+  f.u32(c.childField.length);
+  for (const x of c.childField) f.s(x);
+}
+
+function hashCondition(f: Fnv, cond: Condition): void {
+  switch (cond.type) {
+    case "simple":
+      f.byte(0);
+      f.s(cond.op); // SimpleOp is the wire string ("=", "!=", …) === Rust `op_str`
+      hashValuePosition(f, cond.left);
+      hashValuePosition(f, cond.right);
+      break;
+    case "and":
+      f.byte(1);
+      f.u32(cond.conditions.length);
+      for (const c of cond.conditions) hashCondition(f, c);
+      break;
+    case "or":
+      f.byte(2);
+      f.u32(cond.conditions.length);
+      for (const c of cond.conditions) hashCondition(f, c);
+      break;
+    case "correlatedSubquery":
+      f.byte(3);
+      f.byte(cond.op === "EXISTS" ? 1 : 0); // Exists=1, NotExists=0
+      f.byte(systemByte(cond.related.system));
+      hashCorrelation(f, cond.related.correlation);
+      hashAggSubquery(f, cond.related.subquery);
+      break;
+  }
+}
+
+function systemByte(sys: CorrelatedSubquery["system"]): number {
+  switch (sys) {
+    case "permissions":
+      return 1; // System::Permissions
+    case "client":
+      return 2; // System::Client
+    case "test":
+      return 3; // System::Test
+    default:
+      return 0; // None
+  }
+}
+
+function hashValuePosition(f: Fnv, vp: ValuePosition): void {
+  if (vp.type === "column") {
+    f.byte(0);
+    f.s(vp.name);
+  } else {
+    f.byte(1);
+    hashLit(f, vp.value);
+  }
+}
+
+function hashLit(f: Fnv, lit: LitValue): void {
+  if (lit === null) f.byte(0);
+  else if (typeof lit === "boolean") {
+    f.byte(1);
+    f.byte(lit ? 1 : 0);
+  } else if (typeof lit === "number") {
+    f.byte(2);
+    f.f64(lit);
+  } else if (typeof lit === "string") {
+    f.byte(3);
+    f.s(lit);
+  } else {
+    f.byte(4);
+    f.u32(lit.length);
+    for (const x of lit) hashLit(f, x);
+  }
+}
+
+/** Every synthetic aggregate table `ast` surfaces (recursively, a nested aggregate under a
+ *  materialized relationship included), as flat table schemas — the twin of Rust
+ *  `agg_table_schemas`. Columns `[childField…, "count"]`; PK = the leading group columns. */
+export function aggTableSchemas(ast: Ast): NormalizedTableSchema[] {
+  const out: NormalizedTableSchema[] = [];
+  collectAggTables(ast, out);
+  return out;
+}
+
+function collectAggTables(ast: Ast, out: NormalizedTableSchema[]): void {
+  for (const r of ast.related ?? []) {
+    if (r.subquery.aggregate) {
+      const k = r.correlation.childField.length;
+      out.push({
+        name: aggTableName(r),
+        columns: [...r.correlation.childField, "count"],
+        primaryKey: Array.from({ length: k }, (_, i) => i),
+      });
+    } else {
+      collectAggTables(r.subquery, out);
+    }
+  }
+}
+
+/** Rewrite an AST for the LOCAL engine: each relationship `count` becomes a precomputed,
+ *  source-backed singular relationship over its synthetic table — read the server's count
+ *  with a plain join + the same scalar projection (`aggregatePrecomputed`), never a `reduce`
+ *  (which would recount the already-aggregated rows). Non-aggregate relationships recurse
+ *  (a nested aggregate is rewritten too); the parent's frame is otherwise untouched, so the
+ *  view-schema slot order is preserved. Returns a new AST; the input is not mutated. */
+export function rewriteAggregates(ast: Ast): Ast {
+  if (!ast.related?.length) return ast;
+  return { ...ast, related: ast.related.map(rewriteRelationship) };
+}
+
+function rewriteRelationship(csq: CorrelatedSubquery): CorrelatedSubquery {
+  if (csq.subquery.aggregate) {
+    const subquery: Ast = {
+      table: aggTableName(csq),
+      aggregate: csq.subquery.aggregate as Aggregate,
+      aggregatePrecomputed: true,
+    };
+    // The correlation is unchanged: the synthetic table's group columns are named after the
+    // child correlation fields, so `childField` still resolves against `[childField…, count]`.
+    if (csq.subquery.alias !== undefined) subquery.alias = csq.subquery.alias;
+    const out: CorrelatedSubquery = { correlation: csq.correlation, subquery };
+    if (csq.system !== undefined) out.system = csq.system;
+    return out;
+  }
+  return { ...csq, subquery: rewriteAggregates(csq.subquery) };
+}