@nanobpm/urban 0.80.0 → 0.82.0

package/dist/runtime/core/read-model.js

@@ -52,6 +52,13 @@ export const lit = (value) => ({ kind: "lit", value });
 export const col = (name) => ({ kind: "col", name });
 /** A reference to a correlated PROJECTION-row column (only valid inside {@link exists}). */
 export const pcol = (name) => ({ kind: "pcol", name });
+/**
+ * A reference to a column of a key-correlated ROLLUP LOOKUP row (see {@link ReadModelDecl.lookups}).
+ * `rcol("c", "prs_opened")` reads the `prs_opened` column of the rollup joined under alias `"c"` for
+ * the base row (compiling to `LEFT JOIN <rollup> ON <key>` on the SQL side / the matching group row on
+ * the TS side). Only valid in a {@link defineReadModel} whose `lookups` declares that alias.
+ */
+export const rcol = (lookup, name) => ({ kind: "rcol", lookup, name });
 const cmp = (op) => (left, right) => ({ kind: "compare", op, left, right });
 export const eq = cmp("eq");
 export const neq = cmp("neq");
@@ -62,6 +69,10 @@ export const gte = cmp("gte");
 export const and = (...clauses) => ({ kind: "and", clauses });
 export const or = (...clauses) => ({ kind: "or", clauses });
 export const not = (expr) => ({ kind: "not", expr });
+/** `<expr> IS NULL` — a null test (1/0 in SQL; `value == null` in TS). `not(isNull(x))` is `IS NOT NULL`. */
+export const isNull = (expr) => ({ kind: "isNull", expr });
+/** Sugar for `not(isNull(expr))` — `<expr> IS NOT NULL`. */
+export const isNotNull = (expr) => ({ kind: "not", expr: { kind: "isNull", expr } });
 /** Build a `CASE WHEN … THEN … [WHEN …] ELSE … END` expression. */
 export const caseWhen = (whens, otherwise) => ({
     kind: "case",
@@ -133,14 +144,37 @@ const DEFAULT_BASE_ALIAS = "base";
 function resolveBaseAlias(alias) {
     return assertSqlIdentifier("base alias", alias ?? DEFAULT_BASE_ALIAS);
 }
-/** A conservative SQL identifier guard — we interpolate names directly into DDL/SQL. */
-const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A conservative SQL identifier guard — we interpolate names directly into DDL/SQL. This is the
+ *  single source of truth for "is this a legal identifier"; the manifest validator imports it (rather
+ *  than re-declaring the regex) so a name accepted at author time is accepted at VIEW provisioning too
+ *  (No Drift Surfaces — a divergence would let a manifest validate but fail at boot). */
+export const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** True iff `name` is a legal SQL identifier per {@link SQL_IDENT}. The boolean twin of
+ *  {@link assertSqlIdentifier}, for callers (e.g. the manifest validator) that collect issues rather
+ *  than throw. */
+export function isSqlIdentifier(name) {
+    return SQL_IDENT.test(name);
+}
 export function assertSqlIdentifier(kind, name) {
     if (!SQL_IDENT.test(name)) {
         throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);
     }
     return name;
 }
+/** Object-name prefixes reserved for engine/runtime internals. Tables and views whose names begin
+ *  with one of these are Nano bookkeeping (`_urban_*` / `_nano_*`) or SQLite internals (`sqlite_*`):
+ *  the provenance recorder skips them (`modules/datasource.ts`) and the datasource `schema()` surface
+ *  filters them out (`modules/gateway.ts`), so they are invisible to `/app/data`, DB Manager, and forms.
+ *  This is the single source of truth for that prefix set (No Drift Surfaces — a manifest that provisions
+ *  a `_urban_*` VIEW would otherwise validate yet be unreadable by the documented pages surface). */
+export const RESERVED_OBJECT_PREFIXES = ["_urban_", "_nano_", "sqlite_"];
+/** True iff `name` begins with a {@link RESERVED_OBJECT_PREFIXES} prefix. Case-insensitive, matching
+ *  SQLite's ASCII identifier folding (a `_URBAN_x` table resolves to the same reserved object as
+ *  `_urban_x`), so a reserved name cannot slip through by casing. */
+export function isReservedObjectName(name) {
+    const folded = name.toLowerCase();
+    return RESERVED_OBJECT_PREFIXES.some((p) => folded.startsWith(p));
+}
 function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;
 }
@@ -199,12 +233,17 @@ export function compileToSqlSelect(expr, options = {}) {
             case "lit":
                 return sqlLiteral(node.value);
             case "col":
-                return `${quoteIdent(baseAlias)}.${quoteIdent(node.name)}`;
+                return options.resolveColumn ? options.resolveColumn(node.name) : `${quoteIdent(baseAlias)}.${quoteIdent(node.name)}`;
             case "pcol":
                 if (!projTable) {
                     throw new Error(`pcol("${node.name}") used outside an EXISTS projection context`);
                 }
                 return `${quoteIdent(projTable)}.${quoteIdent(node.name)}`;
+            case "rcol":
+                if (!options.resolveRollupColumn) {
+                    throw new Error(`rcol("${node.lookup}", "${node.name}") used outside a rollup-lookup context`);
+                }
+                return options.resolveRollupColumn(node.lookup, node.name);
             case "compare":
                 // SQLite comparisons against NULL yield NULL, but the TS backend (compareValues) collapses any
                 // nullish operand to `false`/0. COALESCE the SQL result to 0 so both backends agree on NULL inputs.
@@ -223,6 +262,9 @@ export function compileToSqlSelect(expr, options = {}) {
                 // `NOT NULL` is NULL in SQLite, while the TS backend returns `!truthy(NULL)` → true. Compile as
                 // `NOT COALESCE(x, 0)` so `not(NULL)` is 1 in both backends under the shared "NULL → false" rule.
                 return `(NOT COALESCE(${walk(node.expr, projTable, existsDepth)}, 0))`;
+            case "isNull":
+                // `x IS NULL` yields 1/0 in SQLite (never NULL), matching the TS backend's `value == null` test.
+                return `(${walk(node.expr, projTable, existsDepth)} IS NULL)`;
             case "case": {
                 const whens = node.whens
                     .map((w) => `WHEN ${walk(w.when, projTable, existsDepth)} THEN ${walk(w.then, projTable, existsDepth)}`)
@@ -360,39 +402,107 @@ function truthy(value) {
  * named projection's rows (the TS side of the projection-name seam). Both backends walk the SAME AST.
  */
 export function compileToFn(expr) {
-    const evalNode = (node, baseRow, projections, projRow) => {
+    const evalNode = (node, baseRow, projections, lookups, projRow) => {
         switch (node.kind) {
             case "lit":
                 return node.value;
             case "col":
-                return baseRow[node.name] ?? null;
+                return lookupColumn(baseRow, node.name);
             case "pcol":
                 if (!projRow)
                     throw new Error(`pcol("${node.name}") evaluated outside an EXISTS projection context`);
-                return projRow[node.name] ?? null;
+                return lookupColumn(projRow, node.name);
+            case "rcol": {
+                // Read the resolved row by the FOLDED alias: lookup aliases are identifier-validated and deduped
+                // case-insensitively (SQLite folding), and the SQL `resolveRollupColumn` resolves `node.lookup`
+                // through `foldSqlIdentifier` too, so a raw case-sensitive `lookups[node.lookup]` would let
+                // `rcol("C", …)` pass validation against a lookup declared `as: "c"` yet fail here at runtime.
+                // Read by OWN property (via {@link readOwn}) so an identifier-legal `__proto__` alias over a bare
+                // `fnFor` caller's plain `{}` can't resolve `Object.prototype` (truthy) and bypass the guard below.
+                const row = readOwn(lookups, foldSqlIdentifier(node.lookup));
+                // Every declared lookup alias is resolved to a full row up front (a LEFT-JOIN miss becomes a
+                // defaults/NULL-filled row, never an absent alias — see LookupRows). A missing alias here means a
+                // raw `fnFor` caller skipped lookup resolution; fail loudly rather than silently reading NULL.
+                if (!row) {
+                    throw new Error(`rcol("${node.lookup}", "${node.name}") evaluated without a resolved lookup row — ` +
+                        `use ReadModel.evaluate() (or pass the model's resolved lookups) instead of a bare fnFor call`);
+                }
+                return lookupColumn(row, node.name);
+            }
             case "compare":
-                return compareValues(node.op, evalNode(node.left, baseRow, projections, projRow), evalNode(node.right, baseRow, projections, projRow));
+                return compareValues(node.op, evalNode(node.left, baseRow, projections, lookups, projRow), evalNode(node.right, baseRow, projections, lookups, projRow));
             case "and":
-                return node.clauses.every((c) => truthy(evalNode(c, baseRow, projections, projRow)));
+                return node.clauses.every((c) => truthy(evalNode(c, baseRow, projections, lookups, projRow)));
             case "or":
-                return node.clauses.some((c) => truthy(evalNode(c, baseRow, projections, projRow)));
+                return node.clauses.some((c) => truthy(evalNode(c, baseRow, projections, lookups, projRow)));
             case "not":
-                return !truthy(evalNode(node.expr, baseRow, projections, projRow));
+                return !truthy(evalNode(node.expr, baseRow, projections, lookups, projRow));
+            case "isNull": {
+                const v = evalNode(node.expr, baseRow, projections, lookups, projRow);
+                return v === null || v === undefined;
+            }
             case "case": {
                 for (const w of node.whens) {
-                    if (truthy(evalNode(w.when, baseRow, projections, projRow))) {
-                        return evalNode(w.then, baseRow, projections, projRow);
+                    if (truthy(evalNode(w.when, baseRow, projections, lookups, projRow))) {
+                        return evalNode(w.then, baseRow, projections, lookups, projRow);
                     }
                 }
-                return evalNode(node.else, baseRow, projections, projRow);
+                return evalNode(node.else, baseRow, projections, lookups, projRow);
             }
             case "exists": {
-                const rows = projections[node.projection] ?? [];
-                return rows.some((r) => truthy(evalNode(node.where, baseRow, projections, r)));
+                // Read by OWN property so a projection literally named `__proto__` over a bare `fnFor` caller's
+                // plain `{}` resolves to no rows (empty EXISTS) instead of the inherited `Object.prototype`.
+                const rows = readOwn(projections, node.projection) ?? [];
+                return rows.some((r) => truthy(evalNode(node.where, baseRow, projections, lookups, r)));
             }
         }
     };
-    return (baseRow, projections = {}) => evalNode(expr, baseRow, projections);
+    return (baseRow, projections = {}, lookups = {}) => evalNode(expr, baseRow, projections, lookups);
+}
+/** Resolve a column value the way SQLite resolves an identifier: an exact-key match first, then a
+ *  case-insensitive fallback. SQLite folds ASCII identifier case even for quoted identifiers, so the
+ *  VIEW's `col("Status")` binds to a table declared with column `status`; a plain case-sensitive JS
+ *  `row["Status"]` would miss it and return null, breaking VIEW/TS parity on the no-edge fallback and on
+ *  `keyField` correlation. Fold here so both backends read the same column. (A table cannot declare two
+ *  columns differing only in case, so the fallback is unambiguous.) Returns `null` for a missing column,
+ *  preserving the previous `?? null` contract. */
+export function lookupColumn(row, name) {
+    if (Object.hasOwn(row, name))
+        return row[name] ?? null;
+    const folded = name.toLowerCase();
+    for (const key of Object.keys(row)) {
+        if (key.toLowerCase() === folded)
+            return row[key] ?? null;
+    }
+    return null;
+}
+/** Read a dictionary entry by OWN property only. A model-controlled identifier (a lookup alias or
+ *  projection name) reaching a bare `fnFor` caller's plain-`{}` dictionary must not resolve an inherited
+ *  prototype member: `dict["__proto__"]` / `dict["toString"]` on a `{}` return truthy `Object.prototype` /
+ *  function values, which would slip past a `?? default` / missing-key guard and read from the prototype
+ *  chain. The canonical resolved dictionaries are `Object.create(null)`, but this keeps the bare-caller
+ *  path safe too (the sibling of the OWN-key checks in {@link lookupColumn}/{@link resolveCandidateRows}). */
+function readOwn(dict, key) {
+    return Object.hasOwn(dict, key) ? dict[key] : undefined;
+}
+/** Read a rollup lookup's candidate rows from the caller-supplied `lookupRows` dictionary by its alias,
+ *  resolved the way SQLite folds identifiers: an exact OWN-key match first, then a case-insensitive
+ *  OWN-key fallback (the sibling of {@link lookupColumn}). Lookup aliases are case-insensitive SQL
+ *  identifiers — declared/deduped via `foldSqlIdentifier`, and `rcol` reads them folded — so candidates
+ *  supplied under a different casing (e.g. `{ C: [...] }` for an alias declared `c`) must still be found;
+ *  a raw case-sensitive `lookupRows[alias]` would silently treat them as "no candidates" and NULL/default-
+ *  fill, drifting from the folded treatment everywhere else. OWN-key checks (not the prototype-walking
+ *  `in`) also keep an identifier-legal `__proto__` alias from resolving to `Object.prototype` (inherited,
+ *  non-array) and throwing in the caller's `.filter(...)`. */
+function resolveCandidateRows(lookupRows, alias) {
+    if (Object.hasOwn(lookupRows, alias))
+        return lookupRows[alias];
+    const folded = foldSqlIdentifier(alias);
+    for (const key of Object.keys(lookupRows)) {
+        if (foldSqlIdentifier(key) === folded)
+            return lookupRows[key];
+    }
+    return [];
 }
 function collectProjectionNames(expr, into) {
     switch (expr.kind) {
@@ -412,6 +522,9 @@ function collectProjectionNames(expr, into) {
         case "not":
             collectProjectionNames(expr.expr, into);
             return;
+        case "isNull":
+            collectProjectionNames(expr.expr, into);
+            return;
         case "case":
             for (const w of expr.whens) {
                 collectProjectionNames(w.when, into);
@@ -423,10 +536,11 @@ function collectProjectionNames(expr, into) {
             return;
     }
 }
-/** Collect the base-row columns (`col`) and per-projection columns (`pcol`, inside `exists`) an
- *  expression references. Used by the parity guard to build fixture tables carrying every referenced
- *  column even when a sample supplies no rows for a projection. */
-function collectColumns(expr, baseCols, projCols, currentProjection) {
+/** Collect the base-row columns (`col`), per-projection columns (`pcol`, inside `exists`), and
+ *  per-rollup-lookup columns (`rcol`) an expression references. Used by the parity guard to build
+ *  fixture tables carrying every referenced column even when a sample supplies no rows for a
+ *  projection/lookup. */
+function collectColumns(expr, baseCols, projCols, lookupCols, currentProjection) {
     switch (expr.kind) {
         case "col":
             baseCols.add(expr.name);
@@ -438,29 +552,51 @@ function collectColumns(expr, baseCols, projCols, currentProjection) {
                 projCols.set(currentProjection, set);
             }
             return;
+        case "rcol": {
+            // Canonicalize the bucket key case-insensitively (SQLite folds lookup aliases): a derivation using
+            // rcol("C", …) must land in the SAME bucket as a lookup declared/seeded `as: "c"`, else the referenced
+            // column is recorded under a divergent key and both consumers (the parity guard and the SQL TEMP
+            // fixture builder, which fold on read) drop it — producing missing fixture columns / false parity
+            // failures. Reuse an existing key whose folded form matches (e.g. the pre-seeded declared alias).
+            const folded = foldSqlIdentifier(expr.lookup);
+            let key = expr.lookup;
+            for (const k of lookupCols.keys()) {
+                if (foldSqlIdentifier(k) === folded) {
+                    key = k;
+                    break;
+                }
+            }
+            const set = lookupCols.get(key) ?? new Set();
+            set.add(expr.name);
+            lookupCols.set(key, set);
+            return;
+        }
         case "compare":
-            collectColumns(expr.left, baseCols, projCols, currentProjection);
-            collectColumns(expr.right, baseCols, projCols, currentProjection);
+            collectColumns(expr.left, baseCols, projCols, lookupCols, currentProjection);
+            collectColumns(expr.right, baseCols, projCols, lookupCols, currentProjection);
             return;
         case "and":
         case "or":
             for (const c of expr.clauses)
-                collectColumns(c, baseCols, projCols, currentProjection);
+                collectColumns(c, baseCols, projCols, lookupCols, currentProjection);
             return;
         case "not":
-            collectColumns(expr.expr, baseCols, projCols, currentProjection);
+            collectColumns(expr.expr, baseCols, projCols, lookupCols, currentProjection);
+            return;
+        case "isNull":
+            collectColumns(expr.expr, baseCols, projCols, lookupCols, currentProjection);
             return;
         case "case":
             for (const w of expr.whens) {
-                collectColumns(w.when, baseCols, projCols, currentProjection);
-                collectColumns(w.then, baseCols, projCols, currentProjection);
+                collectColumns(w.when, baseCols, projCols, lookupCols, currentProjection);
+                collectColumns(w.then, baseCols, projCols, lookupCols, currentProjection);
             }
-            collectColumns(expr.else, baseCols, projCols, currentProjection);
+            collectColumns(expr.else, baseCols, projCols, lookupCols, currentProjection);
             return;
         case "exists": {
             if (!projCols.has(expr.projection))
                 projCols.set(expr.projection, new Set());
-            collectColumns(expr.where, baseCols, projCols, expr.projection);
+            collectColumns(expr.where, baseCols, projCols, lookupCols, expr.projection);
             return;
         }
         default:
@@ -501,11 +637,90 @@ export function defineReadModel(decl) {
         collectProjectionNames(decl.derive[c], projSet);
     for (const name of projSet)
         assertSqlIdentifier("projection name", name);
+    // ── Rollup lookups (#468): validate the LEFT-JOIN key-lookups and build the alias → metadata map the
+    // SQL `rcol` resolver and the TS row resolver share, so both backends read the same rollup columns. ──
+    const lookups = decl.lookups ?? [];
+    // Single source of truth for the base-alias/lookup-alias collision guard. A `baseAlias` that folds
+    // (SQLite compares identifiers case-insensitively) to a rollup lookup alias would make the managed
+    // VIEW reuse one identifier for both the base table and a joined rollup — ambiguous/invalid SQL. This
+    // runs both at definition time against the DEFAULT base alias AND inside `viewDdl` against a
+    // caller-supplied `baseAlias` override, which the definition-time check can't see (#468).
+    const assertBaseAliasDistinctFromLookups = (baseAlias) => {
+        const folded = foldSqlIdentifier(baseAlias);
+        for (const lk of lookups) {
+            if (foldSqlIdentifier(lk.as) === folded) {
+                throw new Error(`read model "${decl.name}" rollup lookup alias "${lk.as}" collides with the base alias "${baseAlias}"; choose another`);
+            }
+        }
+    };
+    const lookupByAlias = new Map();
+    for (const lk of lookups) {
+        assertSqlIdentifier("rollup lookup alias", lk.as);
+        const key = foldSqlIdentifier(lk.as);
+        if (lookupByAlias.has(key)) {
+            throw new Error(`read model "${decl.name}" declares two rollup lookups under alias "${lk.as}"`);
+        }
+        if (lk.on.length === 0)
+            throw new Error(`read model "${decl.name}" rollup lookup "${lk.as}" has an empty join key`);
+        for (const pair of lk.on) {
+            assertSqlIdentifier("lookup base column", pair.base);
+            assertSqlIdentifier("lookup rollup column", pair.rollup);
+        }
+        // The join must cover the rollup's FULL group key, so the joined row is single-valued (no fan-out
+        // of base rows). Compare the on-keys' rollup side against the rollup's declared groupBy set.
+        const onRollupKeys = new Set(lk.on.map((p) => foldSqlIdentifier(p.rollup)));
+        const groupKeys = new Set(lk.rollup.groupBy.map((g) => foldSqlIdentifier(g)));
+        if (onRollupKeys.size !== groupKeys.size || [...groupKeys].some((g) => !onRollupKeys.has(g))) {
+            throw new Error(`read model "${decl.name}" rollup lookup "${lk.as}" must join on the rollup's full group key ` +
+                `[${lk.rollup.groupBy.join(", ")}] to stay single-valued; got [${lk.on.map((p) => p.rollup).join(", ")}]`);
+        }
+        for (const dname of Object.keys(lk.defaults ?? {})) {
+            if (!lk.rollup.outputColumns.includes(dname)) {
+                throw new Error(`read model "${decl.name}" rollup lookup "${lk.as}" declares a default for "${dname}", ` +
+                    `not a column of rollup "${lk.rollup.projectionName}"`);
+            }
+        }
+        lookupByAlias.set(key, lk);
+    }
+    // Definition-time guard: no lookup alias may collide with the DEFAULT base alias (a caller-supplied
+    // `baseAlias` override is guarded separately inside `viewDdl`, which is the only place it's known).
+    assertBaseAliasDistinctFromLookups(DEFAULT_BASE_ALIAS);
+    // Validate every `rcol(alias, name)` reference resolves to a declared lookup and a real rollup column.
+    {
+        const baseColsSeen = new Set();
+        const projColsSeen = new Map();
+        const lookupColsSeen = new Map();
+        for (const c of columns)
+            collectColumns(decl.derive[c], baseColsSeen, projColsSeen, lookupColsSeen);
+        for (const [alias, names] of lookupColsSeen) {
+            const lk = lookupByAlias.get(foldSqlIdentifier(alias));
+            if (!lk) {
+                throw new Error(`read model "${decl.name}" references rollup-lookup alias "${alias}" with no matching lookup`);
+            }
+            for (const n of names) {
+                if (!lk.rollup.outputColumns.includes(n)) {
+                    throw new Error(`read model "${decl.name}" reads rcol("${alias}", "${n}") but "${n}" is not a column of ` +
+                        `rollup "${lk.rollup.projectionName}" [${lk.rollup.outputColumns.join(", ")}]`);
+                }
+            }
+        }
+    }
+    const resolveRollupColumn = (alias, name) => {
+        const lk = lookupByAlias.get(foldSqlIdentifier(alias));
+        if (!lk)
+            throw new Error(`read model "${decl.name}" has no rollup lookup "${alias}"`);
+        const qualified = `${quoteIdent(alias)}.${quoteIdent(name)}`;
+        const dflt = lk.defaults?.[name];
+        return dflt === undefined ? qualified : `COALESCE(${qualified}, ${sqlLiteral(dflt)})`;
+    };
+    const withLookupResolver = (options) => lookups.length === 0
+        ? (options ?? {})
+        : { ...options, resolveRollupColumn: options?.resolveRollupColumn ?? resolveRollupColumn };
     const sqlSelectFor = (column, options) => {
         const expr = decl.derive[column];
         if (!expr)
             throw new Error(`read model "${decl.name}" has no derived column "${column}"`);
-        return compileToSqlSelect(expr, options);
+        return compileToSqlSelect(expr, withLookupResolver(options));
     };
     const fnCache = new Map();
     const fnFor = (column) => {
@@ -521,27 +736,74 @@ export function defineReadModel(decl) {
     };
     const viewDdl = (options, viewOptions) => {
         const baseAlias = resolveBaseAlias(options?.baseAlias);
+        // A caller-supplied `baseAlias` override is only known here — guard it against the lookup aliases so
+        // the LEFT JOINs below can't reuse the base table's identifier for a joined rollup (invalid SQL).
+        assertBaseAliasDistinctFromLookups(baseAlias);
         const selectBase = decl.selectBaseColumns !== false;
         const derived = columns.map((c) => `${sqlSelectFor(c, options)} AS ${quoteIdent(c)}`);
         const selectList = [...(selectBase ? [`${quoteIdent(baseAlias)}.*`] : []), ...derived].join(",\n  ");
         const createView = viewOptions?.temp ? "CREATE TEMP VIEW IF NOT EXISTS" : "CREATE VIEW IF NOT EXISTS";
-        return (`${createView} ${quoteIdent(decl.name)} AS\n` +
-            `SELECT\n  ${selectList}\n` +
-            `FROM ${quoteIdent(decl.baseTable)} ${quoteIdent(baseAlias)};`);
+        // One `LEFT JOIN <rollup> ON <baseKey> = <rollupKey> …` per declared lookup, in declaration order so
+        // the DDL is deterministic. The rollup's `*_counts` VIEW is joined by name (its physical relation).
+        const joins = lookups.map((lk) => {
+            const on = lk.on
+                .map((p) => `${quoteIdent(baseAlias)}.${quoteIdent(p.base)} = ${quoteIdent(lk.as)}.${quoteIdent(p.rollup)}`)
+                .join(" AND ");
+            return `LEFT JOIN ${quoteIdent(lk.rollup.projectionName)} ${quoteIdent(lk.as)} ON ${on}`;
+        });
+        const fromClause = [`FROM ${quoteIdent(decl.baseTable)} ${quoteIdent(baseAlias)}`, ...joins].join("\n");
+        return `${createView} ${quoteIdent(decl.name)} AS\n` + `SELECT\n  ${selectList}\n` + `${fromClause};`;
+    };
+    const resolveLookupRows = (baseRow, lookupRows) => {
+        // Null-prototype dictionary: lookup aliases are only identifier-validated, so an alias like
+        // `__proto__` must set a plain own property rather than trip the magic prototype setter a normal
+        // `{}` inherits from `Object.prototype` (same treatment as `evaluate()`'s derived-output map below).
+        const resolved = Object.create(null);
+        for (const lk of lookups) {
+            // Read candidates by the lookup's alias via {@link resolveCandidateRows}: an OWN-property check
+            // (so an identifier-legal `__proto__` alias over a plain `{}` can't resolve `lookupRows["__proto__"]`
+            // to `Object.prototype` — inherited, truthy, non-array — and throw in the `.filter(...)` below), plus
+            // a case-insensitive fallback so a caller supplying candidates under a different casing (e.g.
+            // `{ C: [...] }` for an alias declared `c`) is still matched, mirroring the folded alias treatment
+            // used by `rcol`, the resolved-row keying below, and the SQL LEFT JOIN.
+            const candidates = resolveCandidateRows(lookupRows, lk.as);
+            const matches = candidates.filter((r) => lk.on.every((p) => compareValues("eq", lookupColumn(baseRow, p.base), lookupColumn(r, p.rollup))));
+            // The join covers the rollup's full group key, so a well-formed rollup yields at most one row per
+            // key. More than one match means the candidate set is not single-valued: SQL's LEFT JOIN would fan
+            // out to multiple rows while this TS resolver would silently keep one — the exact drift the parity
+            // guard exists to prevent. Fail loudly instead.
+            if (matches.length > 1) {
+                throw new Error(`read model "${decl.name}" rollup lookup "${lk.as}" matched ${matches.length} rows for the ` +
+                    `join key — a lookup must be single-valued (its join covers the rollup's full group key)`);
+            }
+            const match = matches[0];
+            // Build one resolved row over EVERY rollup output column so `rcol` reads a stable object; a
+            // missing/NULL value falls back to the declared default (the `COALESCE(alias.col, default)` twin).
+            const row = Object.create(null);
+            for (const name of lk.rollup.outputColumns) {
+                const raw = match ? lookupColumn(match, name) : null;
+                const dflt = lk.defaults?.[name];
+                row[name] = raw === null || raw === undefined ? (dflt === undefined ? null : dflt) : raw;
+            }
+            resolved[foldSqlIdentifier(lk.as)] = row;
+        }
+        return resolved;
     };
     return {
         decl,
         projectionNames: [...projSet],
         sqlSelectFor,
         fnFor,
-        evaluate: (baseRow, projections) => {
+        resolveLookups: resolveLookupRows,
+        evaluate: (baseRow, projections, lookupRows) => {
             // Derived column names are user-controlled and only identifier-validated, so a name like
             // `__proto__` must set a plain own property rather than trip the magic prototype setter a
             // normal `{}` inherits from `Object.prototype` (same null-prototype treatment as the
             // untrusted-key dictionaries elsewhere in this repo, e.g. `core/logger.ts`).
             const out = Object.create(null);
+            const resolvedLookups = resolveLookupRows(baseRow, lookupRows ?? {});
             for (const c of columns)
-                out[c] = fnFor(c)(baseRow, projections);
+                out[c] = fnFor(c)(baseRow, projections, resolvedLookups);
             return out;
         },
         viewDdl,
@@ -663,15 +925,28 @@ export function assertReadModelParity(model, db, samples, options = {}) {
             throw new Error(`read model "${model.decl.name}" has no derived column "${c}" to check parity for`);
         }
     }
-    // Collect the union of base columns and per-projection columns across all samples, so the fixture
-    // tables carry every referenced column. Seed from the AST first so a projection referenced by an
-    // `exists` predicate always has its correlated columns even when a sample supplies no rows for it.
+    // Collect the union of base columns, per-projection columns, and per-rollup-lookup columns across all
+    // samples, so the fixture tables carry every referenced column. Seed from the AST first so a
+    // projection/lookup referenced by the derivation always has its columns even when a sample supplies
+    // no rows for it.
+    const lookups = model.decl.lookups ?? [];
     const baseCols = new Set();
     const projCols = new Map();
+    const lookupColsByAlias = new Map();
     for (const name of model.projectionNames)
         projCols.set(name, new Set());
+    for (const lk of lookups) {
+        // Seed each lookup fixture with its join keys (so the LEFT JOIN's ON columns exist) even if no
+        // `rcol` reads them, plus every column that carries a declared default.
+        const set = new Set();
+        for (const p of lk.on)
+            set.add(p.rollup);
+        for (const d of Object.keys(lk.defaults ?? {}))
+            set.add(d);
+        lookupColsByAlias.set(lk.as, set);
+    }
     for (const c of columns)
-        collectColumns(model.decl.derive[c], baseCols, projCols);
+        collectColumns(model.decl.derive[c], baseCols, projCols, lookupColsByAlias);
     for (const s of samples) {
         for (const k of Object.keys(s.baseRow))
             baseCols.add(k);
@@ -685,6 +960,20 @@ export function assertReadModelParity(model, db, samples, options = {}) {
                 for (const k of Object.keys(r))
                     set.add(k);
         }
+        // Widen each DECLARED lookup's fixture from the sample's candidate rows read via
+        // {@link resolveCandidateRows} — the same case-insensitive OWN-key resolution `resolveLookups` uses
+        // (line ~1009) — so a sample supplying candidates under a different casing (e.g. `{ C: [...] }` for a
+        // lookup declared `as: "c"`) still widens the right fixture instead of being silently ignored (which
+        // would later insert nothing and fail parity for a non-parity reason). Keyed off `lookups`, not the
+        // sample's keys, so it mirrors the resolver exactly.
+        for (const lk of lookups) {
+            const set = lookupColsByAlias.get(lk.as);
+            if (!set)
+                continue;
+            for (const r of resolveCandidateRows(s.lookups ?? {}, lk.as))
+                for (const k of Object.keys(r))
+                    set.add(k);
+        }
     }
     const baseTable = model.decl.baseTable;
     const createFixture = (table, cols) => {
@@ -726,6 +1015,25 @@ export function assertReadModelParity(model, db, samples, options = {}) {
         tableOwner.set(tableKey, name);
         projectionTables.set(name, table);
     }
+    // Resolve each rollup lookup's fixture table (its rollup's physical relation name). Reject a lookup
+    // relation colliding with the base table or another lookup/projection, so the guard fabricates one
+    // isolated fixture per relation (mirrors the projection checks above).
+    const lookupTables = new Map(); // alias -> relation
+    for (const lk of lookups) {
+        const table = assertSqlIdentifier("rollup lookup relation", lk.rollup.projectionName);
+        const tableKey = foldSqlIdentifier(table);
+        if (tableKey === foldSqlIdentifier(baseTable)) {
+            throw new Error(`read model "${model.decl.name}" rollup lookup "${lk.as}" resolves to its base table "${baseTable}"; ` +
+                `a lookup needs a distinct relation so the parity guard can build an isolated fixture for it`);
+        }
+        const owner = tableOwner.get(tableKey);
+        if (owner !== undefined) {
+            throw new Error(`read model "${model.decl.name}" rollup lookup "${lk.as}" shares the physical relation "${table}" ` +
+                `with "${owner}"; each lookup needs a distinct relation for an isolated parity fixture`);
+        }
+        tableOwner.set(tableKey, lk.as);
+        lookupTables.set(lk.as, table);
+    }
     // Drop/create every fixture through this single helper so the pre-check reset (leaked objects from
     // an earlier call) and the post-check teardown (below) can never drift apart. Schema-qualified with
     // `temp.` so an unqualified name can never resolve to — and delete — a real `main` table/view.
@@ -734,6 +1042,8 @@ export function assertReadModelParity(model, db, samples, options = {}) {
         db.exec(`DROP TABLE IF EXISTS temp.${quoteIdent(baseTable)};`);
         for (const table of projectionTables.values())
             db.exec(`DROP TABLE IF EXISTS temp.${quoteIdent(table)};`);
+        for (const table of lookupTables.values())
+            db.exec(`DROP TABLE IF EXISTS temp.${quoteIdent(table)};`);
     };
     const insertRow = (table, row) => {
         const keys = Object.keys(row);
@@ -755,12 +1065,16 @@ export function assertReadModelParity(model, db, samples, options = {}) {
         createFixture(baseTable, baseCols);
         for (const [name, table] of projectionTables)
             createFixture(table, projCols.get(name) ?? new Set());
+        for (const [alias, table] of lookupTables)
+            createFixture(table, lookupColsByAlias.get(alias) ?? new Set());
         db.exec(model.viewDdl(options.sql, { temp: true }));
         samples.forEach((sample, idx) => {
             // Reset fixture data for this isolated sample.
             db.run(`DELETE FROM ${quoteIdent(baseTable)};`);
             for (const table of projectionTables.values())
                 db.run(`DELETE FROM ${quoteIdent(table)};`);
+            for (const table of lookupTables.values())
+                db.run(`DELETE FROM ${quoteIdent(table)};`);
             insertRow(baseTable, sample.baseRow);
             for (const [pname, rows] of Object.entries(sample.projections ?? {})) {
                 // Ignore projections the model never references — no fixture table exists for them, and they
@@ -771,14 +1085,31 @@ export function assertReadModelParity(model, db, samples, options = {}) {
                 for (const r of rows)
                     insertRow(table, r);
             }
+            // Insert each DECLARED lookup's candidate rows read via {@link resolveCandidateRows} — the same
+            // case-insensitive OWN-key resolution `resolveLookups` uses below — so candidates supplied under a
+            // different casing (e.g. `{ C: [...] }` for a lookup declared `as: "c"`) reach the SQL fixture the
+            // VIEW's LEFT JOIN reads, instead of being dropped by an exact-key `sample.lookups[alias]` lookup and
+            // failing parity for a non-parity reason. Keyed off `lookups`, mirroring the resolver.
+            for (const lk of lookups) {
+                const table = lookupTables.get(lk.as);
+                if (!table)
+                    continue;
+                for (const r of resolveCandidateRows(sample.lookups ?? {}, lk.as))
+                    insertRow(table, r);
+            }
             // Read the SQL-derived values straight from the managed VIEW — the VIEW body already computes
             // each derived column, so this exercises the exact DDL the framework emits (not a recompiled copy).
             const derivedList = columns.map((c) => quoteIdent(c)).join(", ");
             const sqlRows = db.all(`SELECT ${derivedList} FROM ${quoteIdent(model.decl.name)};`);
             const sqlRow = sqlRows[0] ?? {};
+            // Resolve each rollup lookup's single matching row (match on the join keys, fill declared
+            // defaults) via the model's OWN resolver — the single source of the lookup-resolution rule (incl.
+            // the single-valued/no-fan-out guard). Done here (rather than via `model.evaluate`) so a test that
+            // overrides `model.fnFor` to inject drift still drives the compared TS value.
+            const resolvedLookups = model.resolveLookups(sample.baseRow, sample.lookups ?? {});
             for (const c of columns) {
                 const sqlValue = normaliseSqlValue(sqlRow[c]);
-                const fnValue = normaliseSqlValue(model.fnFor(c)(sample.baseRow, sample.projections));
+                const fnValue = normaliseSqlValue(model.fnFor(c)(sample.baseRow, sample.projections, resolvedLookups));
                 if (!Object.is(sqlValue, fnValue)) {
                     onMismatch(`read-model parity mismatch in "${model.decl.name}".${c} (sample #${idx}): ` +
                         `SQL=${formatParityValue(sqlValue)} vs TS=${formatParityValue(fnValue)}`);
@@ -790,3 +1121,710 @@ export function assertReadModelParity(model, db, samples, options = {}) {
         dropFixtures();
     }
 }
+/** `COUNT(col)` (non-NULL) when `column` is given, else `COUNT(*)`. */
+export const count = (column) => (column === undefined ? { kind: "count" } : { kind: "count", column });
+/** `SUM(CASE WHEN pred THEN 1 ELSE 0 END)` — the count of group rows satisfying `pred`. */
+export const countWhere = (pred) => ({ kind: "countWhere", pred });
+/** `MAX(col)` over the group (ignores NULLs; NULL for an all-NULL/empty group). */
+export const max = (column) => ({ kind: "max", column });
+/** `MIN(CASE WHEN pred THEN col END)` — the min of `col` over group rows satisfying `pred`. */
+export const minWhere = (column, pred) => ({ kind: "minWhere", column, pred });
+/** `COALESCE(a, b)` over two aggregates — `a` unless it is NULL, then `b`. */
+export const coalesce = (a, b) => ({ kind: "coalesce", a, b });
+/** `expr + <integer literal>` (e.g. `MAX(wave) + 1`). Rejects a non-integer literal at build time. */
+export const add = (expr, literal) => {
+    if (!Number.isInteger(literal))
+        throw new Error(`add() literal must be an integer, got ${literal}`);
+    return { kind: "add", expr, literal };
+};
+/** Reject an {@link Expr} that has no meaning in a rollup predicate context (no correlated projection
+ *  or lookup exists there): `exists`/`pcol`/`rcol`. Keeps the rollup's predicate surface closed. */
+function assertRollupPredicate(where, expr) {
+    switch (expr.kind) {
+        case "exists":
+            throw new Error(`${where}: exists(...) is not valid in a rollup predicate`);
+        case "pcol":
+            throw new Error(`${where}: pcol(...) is not valid in a rollup predicate`);
+        case "rcol":
+            throw new Error(`${where}: rcol(...) is not valid in a rollup predicate`);
+        case "compare":
+            assertRollupPredicate(where, expr.left);
+            assertRollupPredicate(where, expr.right);
+            return;
+        case "and":
+        case "or":
+            for (const c of expr.clauses)
+                assertRollupPredicate(where, c);
+            return;
+        case "not":
+        case "isNull":
+            assertRollupPredicate(where, expr.expr);
+            return;
+        case "case":
+            for (const w of expr.whens) {
+                assertRollupPredicate(where, w.when);
+                assertRollupPredicate(where, w.then);
+            }
+            assertRollupPredicate(where, expr.else);
+            return;
+        default:
+            return;
+    }
+}
+/** Collect the source-row column names an aggregate references (its `column` plus any predicate cols),
+ *  used to seed fixture tables and to validate a rollup's non-join source references. */
+function collectAggColumns(agg, into) {
+    switch (agg.kind) {
+        case "count":
+            if (agg.column !== undefined)
+                into.add(agg.column);
+            return;
+        case "max":
+            into.add(agg.column);
+            return;
+        case "countWhere": {
+            const proj = new Map();
+            collectColumns(agg.pred, into, proj, new Map());
+            return;
+        }
+        case "minWhere": {
+            into.add(agg.column);
+            const proj = new Map();
+            collectColumns(agg.pred, into, proj, new Map());
+            return;
+        }
+        case "coalesce":
+            collectAggColumns(agg.a, into);
+            collectAggColumns(agg.b, into);
+            return;
+        case "add":
+            collectAggColumns(agg.expr, into);
+            return;
+    }
+}
+/** A rollup over a base table. */
+export const fromTable = (table) => ({ kind: "table", table });
+/** A rollup over a canonical projection (resolved to its physical relation via {@link projectionRegistry}). */
+export const fromProjection = (projection) => ({ kind: "projection", projection });
+/** A rollup over another rollup's `*_counts` VIEW (composable — e.g. wave's two levels). */
+export const fromRollup = (rollup) => ({ kind: "rollup", rollup });
+/** A rollup over a declared key-join of two relations (the two-hop reach — D4). */
+export const joinSource = (spec) => ({ kind: "join", ...spec });
+const ROLLUP_SRC_ALIAS = "__urban_rollup_src";
+/** Resolve a rollup source to its SQL `FROM` clause, a `col`-name → qualified-SQL resolver, its leaf
+ *  relation names, and the rollup dependencies it composes. */
+function compileRollupSourceSql(source, resolveProjectionTable) {
+    switch (source.kind) {
+        case "table": {
+            const table = assertSqlIdentifier("rollup source table", source.table);
+            return {
+                from: `${quoteIdent(table)} ${quoteIdent(ROLLUP_SRC_ALIAS)}`,
+                resolveColumn: (name) => `${quoteIdent(ROLLUP_SRC_ALIAS)}.${quoteIdent(name)}`,
+            };
+        }
+        case "projection": {
+            const table = assertSqlIdentifier("rollup source projection", resolveProjectionTable(source.projection));
+            return {
+                from: `${quoteIdent(table)} ${quoteIdent(ROLLUP_SRC_ALIAS)}`,
+                resolveColumn: (name) => `${quoteIdent(ROLLUP_SRC_ALIAS)}.${quoteIdent(name)}`,
+            };
+        }
+        case "rollup": {
+            const table = assertSqlIdentifier("rollup source rollup", source.rollup.projectionName);
+            return {
+                from: `${quoteIdent(table)} ${quoteIdent(ROLLUP_SRC_ALIAS)}`,
+                resolveColumn: (name) => `${quoteIdent(ROLLUP_SRC_ALIAS)}.${quoteIdent(name)}`,
+            };
+        }
+        case "join": {
+            const leftRel = assertSqlIdentifier("rollup join relation", resolveProjectionTable(source.left.relation));
+            const rightRel = assertSqlIdentifier("rollup join relation", resolveProjectionTable(source.right.relation));
+            const leftAlias = assertSqlIdentifier("rollup join alias", source.left.alias);
+            const rightAlias = assertSqlIdentifier("rollup join alias", source.right.alias);
+            const joinKw = source.type === "inner" ? "JOIN" : "LEFT JOIN";
+            const on = source.on
+                .map((p) => `${quoteIdent(leftAlias)}.${quoteIdent(assertSqlIdentifier("join key", p.left))} = ` +
+                `${quoteIdent(rightAlias)}.${quoteIdent(assertSqlIdentifier("join key", p.right))}`)
+                .join(" AND ");
+            const from = `${quoteIdent(leftRel)} ${quoteIdent(leftAlias)} ${joinKw} ` +
+                `${quoteIdent(rightRel)} ${quoteIdent(rightAlias)} ON ${on}`;
+            // Index the join-mapped output columns by their FOLDED (case-insensitive) name: SQLite folds
+            // identifiers case-insensitively and the TS twin (`materializeRollupSource`) resolves these columns
+            // via the case-insensitive `lookupColumn`, so a rollup predicate/groupBy that references a
+            // join-mapped column with different casing must resolve here too — a case-sensitive `source.columns[name]`
+            // would succeed in TS but throw in SQL. Fail fast on a case-only collision (two output columns SQLite
+            // cannot tell apart), and use a `Map` so a `__proto__`-named column can't resolve off the prototype chain.
+            const foldedColumns = new Map();
+            for (const [outName, mapped] of Object.entries(source.columns)) {
+                const key = foldSqlIdentifier(outName);
+                if (foldedColumns.has(key)) {
+                    throw new Error(`rollup join source declares output columns differing only in case ("${outName}"); ` +
+                        `SQLite folds identifiers case-insensitively so they would be ambiguous`);
+                }
+                foldedColumns.set(key, mapped);
+            }
+            const resolveColumn = (name) => {
+                const mapped = foldedColumns.get(foldSqlIdentifier(name));
+                if (!mapped)
+                    throw new Error(`rollup join source has no mapped column "${name}"`);
+                const [side, physical] = mapped;
+                const alias = side === "left" ? leftAlias : rightAlias;
+                return `${quoteIdent(alias)}.${quoteIdent(assertSqlIdentifier("join column", physical))}`;
+            };
+            return { from, resolveColumn };
+        }
+    }
+}
+/** The TS twin of {@link compileRollupSourceSql}: materialise a source's flat rows from leaf inputs. */
+function materializeRollupSource(source, inputs) {
+    switch (source.kind) {
+        case "table":
+            return [...(inputs[source.table] ?? [])];
+        case "projection":
+            return [...(inputs[source.projection] ?? [])];
+        case "rollup":
+            return source.rollup.reduce(inputs);
+        case "join": {
+            const leftRows = inputs[source.left.relation] ?? [];
+            const rightRows = inputs[source.right.relation] ?? [];
+            const map = (l, r) => {
+                const row = Object.create(null);
+                for (const [outName, [side, physical]] of Object.entries(source.columns)) {
+                    const from = side === "left" ? l : r;
+                    row[outName] = from ? lookupColumn(from, physical) : null;
+                }
+                return row;
+            };
+            // Build the composite join key with the SAME storage-class-tagged encoding the GROUP BY reduce
+            // uses (groupKeyPart): integer number/bigint of equal value collide, numeric never equals text —
+            // matching `compareValues("eq", …)`. A nullish part yields `null` (no key), because SQLite's
+            // `ON l.k = r.k` never matches a NULL key, so those rows are excluded from the join entirely.
+            const keyOf = (row, cols) => {
+                const parts = [];
+                for (const c of cols) {
+                    const v = lookupColumn(row, c);
+                    if (v === null || v === undefined)
+                        return null;
+                    parts.push(groupKeyPart(v));
+                }
+                return parts.join("\u0001");
+            };
+            // Index the right side once by its join key (O(|right|)) so each left row probes in O(1) rather
+            // than scanning every right row (was O(|left|·|right|)).
+            const rightCols = source.on.map((p) => p.right);
+            const leftCols = source.on.map((p) => p.left);
+            const rightByKey = new Map();
+            for (const r of rightRows) {
+                const k = keyOf(r, rightCols);
+                if (k === null)
+                    continue;
+                let bucket = rightByKey.get(k);
+                if (!bucket) {
+                    bucket = [];
+                    rightByKey.set(k, bucket);
+                }
+                bucket.push(r);
+            }
+            const out = [];
+            for (const l of leftRows) {
+                const k = keyOf(l, leftCols);
+                const matches = k === null ? undefined : rightByKey.get(k);
+                if (!matches || matches.length === 0) {
+                    if (source.type !== "inner")
+                        out.push(map(l, undefined));
+                }
+                else {
+                    for (const r of matches)
+                        out.push(map(l, r));
+                }
+            }
+            return out;
+        }
+    }
+}
+/** Leaf relation names a source reads, transitively (a `rollup` source recurses into its own leaves). */
+function rollupSourceRelations(source) {
+    switch (source.kind) {
+        case "table":
+            return [source.table];
+        case "projection":
+            return [source.projection];
+        case "join":
+            return [source.left.relation, source.right.relation];
+        case "rollup":
+            return [...source.rollup.sourceRelations];
+    }
+}
+/** The physical twin of {@link rollupSourceRelations}: each leaf relation name mapped to the physical
+ *  SQL table the compiled VIEW reads, applying the SAME projection→table resolution
+ *  {@link compileRollupSourceSql} uses — identity for a raw `table` source, `resolveProjectionTable` for
+ *  `projection`/`join` relations, recursing for a composed `rollup`. The parity guard builds its TEMP
+ *  fixtures under these names so they match the VIEW's `FROM`; otherwise a projection whose name maps to a
+ *  different physical relation (e.g. `urban_instance_state` → `_urban_instance_state`) would leave the
+ *  VIEW pointing at a table the logical-named fixture never created. */
+function rollupSourcePhysicalTables(source, resolveProjectionTable) {
+    switch (source.kind) {
+        case "table":
+            return new Map([[source.table, source.table]]);
+        case "projection":
+            return new Map([[source.projection, resolveProjectionTable(source.projection)]]);
+        case "join":
+            return new Map([
+                [source.left.relation, resolveProjectionTable(source.left.relation)],
+                [source.right.relation, resolveProjectionTable(source.right.relation)],
+            ]);
+        case "rollup":
+            return rollupSourcePhysicalTables(source.rollup.decl.source, resolveProjectionTable);
+    }
+}
+/** Evaluate one aggregate over a group's source rows (the TS backend). */
+function evalAgg(agg, rows) {
+    switch (agg.kind) {
+        case "count": {
+            const { column } = agg;
+            return column === undefined
+                ? rows.length
+                : rows.filter((r) => lookupColumn(r, column) !== null).length;
+        }
+        case "countWhere": {
+            const fn = compileToFn(agg.pred);
+            return rows.filter((r) => truthy(fn(r))).length;
+        }
+        case "max": {
+            const vals = rows.map((r) => lookupColumn(r, agg.column)).filter((v) => v !== null && v !== undefined);
+            if (vals.length === 0)
+                return null;
+            return vals.reduce((m, v) => (compareOrderable(orderable(v), orderable(m)) > 0 ? v : m));
+        }
+        case "minWhere": {
+            const fn = compileToFn(agg.pred);
+            const vals = rows
+                .filter((r) => truthy(fn(r)))
+                .map((r) => lookupColumn(r, agg.column))
+                .filter((v) => v !== null && v !== undefined);
+            if (vals.length === 0)
+                return null;
+            return vals.reduce((m, v) => (compareOrderable(orderable(v), orderable(m)) < 0 ? v : m));
+        }
+        case "coalesce": {
+            const a = evalAgg(agg.a, rows);
+            return a === null || a === undefined ? evalAgg(agg.b, rows) : a;
+        }
+        case "add": {
+            const base = evalAgg(agg.expr, rows);
+            if (base === null || base === undefined)
+                return null; // SQLite: NULL + literal = NULL
+            if (typeof base === "bigint")
+                return base + BigInt(agg.literal);
+            const n = typeof base === "number" ? base : Number(base);
+            return n + agg.literal;
+        }
+    }
+}
+/** Compile one aggregate to a SQLite select-list expression (the SQL backend). */
+function compileAggToSql(agg, options) {
+    const resolveColumn = options.resolveColumn ?? ((n) => quoteIdent(n));
+    switch (agg.kind) {
+        case "count":
+            return agg.column === undefined ? "COUNT(*)" : `COUNT(${resolveColumn(agg.column)})`;
+        case "countWhere":
+            return `SUM(CASE WHEN ${compileToSqlSelect(agg.pred, options)} THEN 1 ELSE 0 END)`;
+        case "max":
+            return `MAX(${resolveColumn(agg.column)})`;
+        case "minWhere":
+            return `MIN(CASE WHEN ${compileToSqlSelect(agg.pred, options)} THEN ${resolveColumn(agg.column)} END)`;
+        case "coalesce":
+            return `COALESCE(${compileAggToSql(agg.a, options)}, ${compileAggToSql(agg.b, options)})`;
+        case "add":
+            return `(${compileAggToSql(agg.expr, options)} + ${sqlLiteral(agg.literal)})`;
+    }
+}
+/** A composite group key for the TS reduce, tagged by storage class so `1`/`'1'`/NULL group distinctly
+ *  (matching SQLite's affinity-free grouping the parity fixtures pin), while integer `number`/`bigint`
+ *  of equal value group together (a driver may surface either). */
+function groupKeyPart(value) {
+    if (value === null || value === undefined)
+        return "\u0000null";
+    if (typeof value === "bigint")
+        return `\u0000int:${value}`;
+    if (typeof value === "number" && Number.isInteger(value))
+        return `\u0000int:${value}`;
+    if (typeof value === "number")
+        return `\u0000num:${value}`;
+    if (typeof value === "boolean")
+        return `\u0000int:${value ? 1 : 0}`;
+    return `\u0000str:${String(value)}`;
+}
+/**
+ * Declare a GROUP-BY rollup ONCE (ADR 0065, #468). Returns a {@link Rollup} exposing both backends (the
+ * managed `*_counts` VIEW DDL and the TS group-reduce) driven from one closed spec, plus the metadata
+ * the parity guard and registry need. Register it in {@link rollupRegistry} to have the runtime apply
+ * its VIEW at boot and expose its name as a canonical projection.
+ */
+export function defineRollup(decl) {
+    assertSqlIdentifier("rollup name", decl.name);
+    if (decl.groupBy.length === 0)
+        throw new Error(`rollup "${decl.name}" declares no group-by columns`);
+    for (const g of decl.groupBy)
+        assertSqlIdentifier("group-by column", g);
+    const aggNames = Object.keys(decl.aggregates).sort();
+    if (aggNames.length === 0)
+        throw new Error(`rollup "${decl.name}" declares no aggregates`);
+    for (const a of aggNames)
+        assertSqlIdentifier("aggregate column", a);
+    // An aggregate column name colliding with a group-key name would emit two SELECT aliases of one name.
+    const groupSet = new Set(decl.groupBy.map((g) => foldSqlIdentifier(g)));
+    for (const a of aggNames) {
+        if (groupSet.has(foldSqlIdentifier(a))) {
+            throw new Error(`rollup "${decl.name}" aggregate "${a}" collides with a group-by column of the same name`);
+        }
+    }
+    if (decl.where)
+        assertRollupPredicate(`rollup "${decl.name}" where`, decl.where);
+    for (const a of aggNames) {
+        const agg = decl.aggregates[a];
+        forEachAggPredicate(agg, (pred) => assertRollupPredicate(`rollup "${decl.name}" aggregate "${a}"`, pred));
+    }
+    // Fail-fast: when the source's output namespace is statically known — a key-`join` exposes its flat
+    // `columns` map, a composed `rollup` exposes its `outputColumns` — reject a rollup that references a
+    // `groupBy`/`col(...)` name absent from it. Otherwise the two backends drift silently: the SQL side
+    // throws (`no mapped column` for a join; `no such column` for a rollup source) at view compilation /
+    // query time, while the TS reduce reads NULL via `lookupColumn` and groups/counts against a phantom
+    // column. Fold names case-insensitively to mirror the resolvers (SQLite identifier folding +
+    // `lookupColumn`). A `table`/`projection` source has no statically-known namespace here, so it is
+    // left to the existing per-relation resolution.
+    const knownNamespaceCols = decl.source.kind === "join"
+        ? Object.keys(decl.source.columns)
+        : decl.source.kind === "rollup"
+            ? decl.source.rollup.outputColumns
+            : undefined;
+    if (knownNamespaceCols) {
+        const knownFolded = new Set(knownNamespaceCols.map(foldSqlIdentifier));
+        const referencedCols = new Set();
+        for (const g of decl.groupBy)
+            referencedCols.add(g);
+        if (decl.where)
+            collectColumns(decl.where, referencedCols, new Map(), new Map());
+        for (const a of aggNames)
+            collectAggColumns(decl.aggregates[a], referencedCols);
+        for (const name of referencedCols) {
+            if (!knownFolded.has(foldSqlIdentifier(name))) {
+                const kind = decl.source.kind === "join" ? "join source" : "rollup source";
+                throw new Error(`rollup "${decl.name}" references column "${name}" absent from its ${kind} output namespace ` +
+                    `[${knownNamespaceCols.join(", ")}]`);
+            }
+        }
+    }
+    const outputColumns = [...decl.groupBy, ...aggNames];
+    const sourceRelations = [...new Set(rollupSourceRelations(decl.source))];
+    const dependencies = decl.source.kind === "rollup" ? decl.source.rollup.viewChain : [];
+    // Dependency rollups first (dedup by name, preserving order); this rollup itself is appended last
+    // once `self` exists (see below).
+    const viewChain = [];
+    const seenChain = new Set();
+    for (const dep of dependencies) {
+        const key = foldSqlIdentifier(dep.projectionName);
+        if (!seenChain.has(key)) {
+            seenChain.add(key);
+            viewChain.push(dep);
+        }
+    }
+    const sqlAggFor = (column, options) => {
+        const agg = decl.aggregates[column];
+        if (!agg)
+            throw new Error(`rollup "${decl.name}" has no aggregate "${column}"`);
+        const { resolveColumn } = compileRollupSourceSql(decl.source, resolveProjectionTableFor(options));
+        return compileAggToSql(agg, { ...options, resolveColumn });
+    };
+    const viewDdl = (options, viewOptions) => {
+        const { from, resolveColumn } = compileRollupSourceSql(decl.source, resolveProjectionTableFor(options));
+        const colOptions = { ...options, resolveColumn };
+        const groupSelect = decl.groupBy.map((g) => `${resolveColumn(g)} AS ${quoteIdent(g)}`);
+        const aggSelect = aggNames.map((a) => `${compileAggToSql(decl.aggregates[a], colOptions)} AS ${quoteIdent(a)}`);
+        const selectList = [...groupSelect, ...aggSelect].join(",\n  ");
+        const whereClause = decl.where ? `\nWHERE ${compileToSqlSelect(decl.where, colOptions)}` : "";
+        const groupByClause = decl.groupBy.map((g) => resolveColumn(g)).join(", ");
+        const createView = viewOptions?.temp ? "CREATE TEMP VIEW IF NOT EXISTS" : "CREATE VIEW IF NOT EXISTS";
+        return (`${createView} ${quoteIdent(decl.name)} AS\n` +
+            `SELECT\n  ${selectList}\n` +
+            `FROM ${from}${whereClause}\n` +
+            `GROUP BY ${groupByClause};`);
+    };
+    const reduce = (inputs) => {
+        const src = materializeRollupSource(decl.source, inputs);
+        const whereFn = decl.where ? compileToFn(decl.where) : undefined;
+        const filtered = whereFn ? src.filter((r) => truthy(whereFn(r))) : src;
+        const groups = new Map();
+        const order = [];
+        for (const r of filtered) {
+            const key = decl.groupBy.map((g) => groupKeyPart(lookupColumn(r, g))).join("\u0001");
+            let bucket = groups.get(key);
+            if (!bucket) {
+                bucket = [];
+                groups.set(key, bucket);
+                order.push({ first: r, rows: bucket });
+            }
+            bucket.push(r);
+        }
+        return order.map(({ first, rows }) => {
+            const out = Object.create(null);
+            for (const g of decl.groupBy)
+                out[g] = lookupColumn(first, g);
+            for (const a of aggNames)
+                out[a] = evalAgg(decl.aggregates[a], rows);
+            return out;
+        });
+    };
+    const fixtureColumns = () => {
+        const cols = new Map();
+        const ensure = (rel) => {
+            let s = cols.get(rel);
+            if (!s) {
+                s = new Set();
+                cols.set(rel, s);
+            }
+            return s;
+        };
+        // Columns referenced by this rollup's group keys, where predicate, and aggregates (as source
+        // output-namespace names), then mapped onto the physical relation(s) of its source.
+        const referenced = new Set();
+        for (const g of decl.groupBy)
+            referenced.add(g);
+        if (decl.where)
+            collectColumns(decl.where, referenced, new Map(), new Map());
+        for (const a of aggNames)
+            collectAggColumns(decl.aggregates[a], referenced);
+        switch (decl.source.kind) {
+            case "table":
+            case "projection": {
+                const rel = decl.source.kind === "table" ? decl.source.table : decl.source.projection;
+                const s = ensure(rel);
+                for (const c of referenced)
+                    s.add(c);
+                break;
+            }
+            case "join": {
+                const leftSet = ensure(decl.source.left.relation);
+                const rightSet = ensure(decl.source.right.relation);
+                for (const [, [side, physical]] of Object.entries(decl.source.columns)) {
+                    (side === "left" ? leftSet : rightSet).add(physical);
+                }
+                for (const p of decl.source.on) {
+                    leftSet.add(p.left);
+                    rightSet.add(p.right);
+                }
+                break;
+            }
+            case "rollup": {
+                // The inner rollup provides its own output columns via its VIEW; recurse for its leaf fixtures.
+                for (const [rel, s] of decl.source.rollup.fixtureColumns()) {
+                    const dst = ensure(rel);
+                    for (const c of s)
+                        dst.add(c);
+                }
+                break;
+            }
+        }
+        return cols;
+    };
+    const self = {
+        decl,
+        projectionName: decl.name,
+        groupBy: [...decl.groupBy],
+        outputColumns,
+        sourceRelations,
+        viewChain,
+        sqlAggFor,
+        reduce,
+        viewDdl,
+        fixtureColumns,
+    };
+    viewChain.push(self);
+    return self;
+}
+/** Walk every predicate `Expr` embedded in an aggregate (countWhere/minWhere), recursing coalesce/add. */
+function forEachAggPredicate(agg, visit) {
+    switch (agg.kind) {
+        case "countWhere":
+            visit(agg.pred);
+            return;
+        case "minWhere":
+            visit(agg.pred);
+            return;
+        case "coalesce":
+            forEachAggPredicate(agg.a, visit);
+            forEachAggPredicate(agg.b, visit);
+            return;
+        case "add":
+            forEachAggPredicate(agg.expr, visit);
+            return;
+        default:
+            return;
+    }
+}
+function resolveProjectionTableFor(options) {
+    return options?.resolveProjectionTable ?? ((n) => projectionRegistry.sqlTableFor(n));
+}
+// ────────────────────────────────────────── Rollup registry ──────────────────────────────────────
+/**
+ * The rollup registry (ADR 0065, #468) — the GROUP-BY sibling of {@link ReadModelRegistry}. Registering
+ * a {@link Rollup} both (a) queues its managed VIEW for boot provisioning (in dependency order) and (b)
+ * registers its name as a canonical projection so read-model rollup lookups resolve. Idempotent: a
+ * re-register whose VIEW DDL matches is a no-op; a conflicting redefinition throws.
+ */
+export class RollupRegistry {
+    #byName = new Map();
+    register(rollup, projections = projectionRegistry) {
+        const key = foldSqlIdentifier(rollup.projectionName);
+        const existing = this.#byName.get(key);
+        if (existing) {
+            if (existing.projectionName !== rollup.projectionName) {
+                throw new Error(`rollup "${rollup.projectionName}" already registered as "${existing.projectionName}"; SQLite ` +
+                    `folds identifiers case-insensitively, so names differing only in case denote one VIEW`);
+            }
+            if (existing.viewDdl() !== rollup.viewDdl()) {
+                throw new Error(`rollup "${rollup.projectionName}" already registered with a different definition`);
+            }
+            return;
+        }
+        this.#byName.set(key, rollup);
+        // Expose the rollup's VIEW as a canonical projection so `exists(...)`/rollup lookups resolve to it.
+        projections.register({ name: rollup.projectionName });
+    }
+    all() {
+        return [...this.#byName.values()];
+    }
+    get(name) {
+        return this.#byName.get(foldSqlIdentifier(name));
+    }
+    /** Apply every registered rollup's managed VIEW to a database, dependency-ordered (a composed rollup
+     *  after the rollup it reads) and MANAGED (drop+recreate `main.`-qualified, mirroring
+     *  {@link ReadModelRegistry.ensureViews}). Safe to call repeatedly. */
+    ensureViews(db, options) {
+        const applied = new Set();
+        const applyChain = (rollup) => {
+            for (const r of rollup.viewChain) {
+                const key = foldSqlIdentifier(r.projectionName);
+                if (applied.has(key))
+                    continue;
+                applied.add(key);
+                db.exec(`DROP VIEW IF EXISTS main.${quoteIdent(r.projectionName)};`);
+                db.exec(r.viewDdl(options));
+            }
+        };
+        for (const rollup of this.#byName.values())
+            applyChain(rollup);
+    }
+    clear() {
+        this.#byName.clear();
+    }
+}
+/** Process-wide rollup registry — the concrete registration point apps/sidecars import and call. */
+export const rollupRegistry = new RollupRegistry();
+/**
+ * The framework PARITY GUARD for grouped rollups (#468) — the GROUP-BY sibling of
+ * {@link assertReadModelParity}. For each input-set it materialises the rollup's managed VIEW (and any
+ * composed dependency VIEWs) over throwaway TEMP fixtures built from the leaf rows, reads the SQL-derived
+ * group rows, computes the TS `reduce` for the same inputs, and asserts they agree as a SET keyed by the
+ * group columns (GROUP BY output order is unspecified, so rows are matched by key, not position).
+ */
+export function assertRollupParity(rollup, db, sampleSets, options = {}) {
+    const onMismatch = options.onMismatch ?? defaultOnMismatch;
+    const fixtureCols = rollup.fixtureColumns();
+    const relations = [...fixtureCols.keys()];
+    // Fixtures are keyed by LOGICAL relation name (what `RollupInputs`/`reduce` read), but the managed VIEW
+    // reads the PHYSICAL table `compileRollupSourceSql` resolves each projection/join relation to. Build the
+    // TEMP tables under those physical names (via the same resolver the VIEW is compiled with, line below)
+    // so the VIEW's `FROM` finds them; the column/row maps stay logical-keyed.
+    const resolveTable = options.sql?.resolveProjectionTable ?? ((n) => projectionRegistry.sqlTableFor(n));
+    const physicalTables = rollupSourcePhysicalTables(rollup.decl.source, resolveTable);
+    const physical = (rel) => physicalTables.get(rel) ?? rel;
+    const createFixture = (table, cols) => {
+        const colList = [...cols];
+        const ddl = colList.length
+            ? `CREATE TEMP TABLE ${quoteIdent(table)} (${colList.map((c) => quoteIdent(c)).join(", ")});`
+            : `CREATE TEMP TABLE ${quoteIdent(table)} (_placeholder);`;
+        db.exec(ddl);
+    };
+    const insertRow = (table, row) => {
+        const keys = Object.keys(row);
+        if (keys.length === 0) {
+            db.run(`INSERT INTO ${quoteIdent(table)} DEFAULT VALUES;`);
+            return;
+        }
+        const placeholders = keys.map(() => "?").join(", ");
+        db.run(`INSERT INTO ${quoteIdent(table)} (${keys.map((k) => quoteIdent(k)).join(", ")}) VALUES (${placeholders});`, keys.map((k) => normaliseSqlValue(row[k])));
+    };
+    const dropFixtures = () => {
+        // Drop dependent VIEWs before their base relations; drop the whole chain plus leaf fixtures.
+        for (let i = rollup.viewChain.length - 1; i >= 0; i--) {
+            db.exec(`DROP VIEW IF EXISTS temp.${quoteIdent(rollup.viewChain[i].projectionName)};`);
+        }
+        for (const rel of relations)
+            db.exec(`DROP TABLE IF EXISTS temp.${quoteIdent(physical(rel))};`);
+    };
+    // Widen each leaf fixture with any extra column keys present in the sample rows.
+    const cols = new Map();
+    for (const [rel, set] of fixtureCols)
+        cols.set(rel, new Set(set));
+    for (const inputs of sampleSets) {
+        for (const [rel, rows] of Object.entries(inputs)) {
+            const set = cols.get(rel);
+            if (!set)
+                continue;
+            for (const r of rows)
+                for (const k of Object.keys(r))
+                    set.add(k);
+        }
+    }
+    dropFixtures();
+    try {
+        for (const rel of relations)
+            createFixture(physical(rel), cols.get(rel) ?? new Set());
+        // Materialise the VIEW chain (dependencies first) as TEMP views over the leaf fixtures.
+        for (const r of rollup.viewChain)
+            db.exec(r.viewDdl(options.sql, { temp: true }));
+        const outputList = rollup.outputColumns.map((c) => quoteIdent(c)).join(", ");
+        sampleSets.forEach((inputs, idx) => {
+            for (const rel of relations)
+                db.run(`DELETE FROM ${quoteIdent(physical(rel))};`);
+            for (const [rel, rows] of Object.entries(inputs)) {
+                if (!cols.has(rel))
+                    continue;
+                for (const r of rows)
+                    insertRow(physical(rel), r);
+            }
+            const sqlRows = db.all(`SELECT ${outputList} FROM ${quoteIdent(rollup.projectionName)};`);
+            const tsRows = rollup.reduce(inputs);
+            const keyOf = (row) => rollup.groupBy.map((g) => groupKeyPart(normaliseSqlValue(lookupColumn(row, g)))).join("\u0001");
+            const sqlByKey = new Map();
+            for (const r of sqlRows)
+                sqlByKey.set(keyOf(r), r);
+            const tsByKey = new Map();
+            for (const r of tsRows)
+                tsByKey.set(keyOf(r), r);
+            if (sqlByKey.size !== tsByKey.size) {
+                onMismatch(`rollup parity mismatch in "${rollup.projectionName}" (sample #${idx}): ` +
+                    `SQL produced ${sqlByKey.size} group(s) vs TS ${tsByKey.size}`);
+            }
+            for (const [key, tsRow] of tsByKey) {
+                const sqlRow = sqlByKey.get(key);
+                if (!sqlRow) {
+                    onMismatch(`rollup parity mismatch in "${rollup.projectionName}" (sample #${idx}): TS group ${key} missing from SQL`);
+                    continue;
+                }
+                for (const c of rollup.outputColumns) {
+                    const sqlValue = normaliseSqlValue(sqlRow[c]);
+                    const tsValue = normaliseSqlValue(tsRow[c]);
+                    if (!Object.is(sqlValue, tsValue)) {
+                        onMismatch(`rollup parity mismatch in "${rollup.projectionName}".${c} (sample #${idx}, group ${key}): ` +
+                            `SQL=${formatParityValue(sqlValue)} vs TS=${formatParityValue(tsValue)}`);
+                    }
+                }
+            }
+        });
+    }
+    finally {
+        dropFixtures();
+    }
+}