@nanobpm/urban 0.80.0 → 0.82.0

package/dist/runtime/core/modules/open-user-tasks-store.d.ts

@@ -56,6 +56,11 @@ export declare class OpenUserTasksStore {
     syncInstance(processInstanceKey: string, openTasks: readonly UserTaskSummary[]): void;
     /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
     clearInstance(processInstanceKey: string): void;
+    /** Every distinct instance key currently projected as having ≥1 open user task. Used by the
+     *  reconciler to re-probe (and, when answered, RETIRE) keys that have dropped out of a binding's
+     *  `activeStatuses` allow-list — a projected row must be retired independently of the base-row
+     *  selector, or an answered escalation's row would linger and the derived edge tear (ADR 0065). */
+    instanceKeys(): string[];
     /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
     hasOpenTask(processInstanceKey: string): boolean;
     /** The projected open tasks for an instance, in insertion order. */

package/dist/runtime/core/modules/open-user-tasks-store.js

@@ -113,6 +113,14 @@ export class OpenUserTasksStore {
             return;
         this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
     }
+    /** Every distinct instance key currently projected as having ≥1 open user task. Used by the
+     *  reconciler to re-probe (and, when answered, RETIRE) keys that have dropped out of a binding's
+     *  `activeStatuses` allow-list — a projected row must be retired independently of the base-row
+     *  selector, or an answered escalation's row would linger and the derived edge tear (ADR 0065). */
+    instanceKeys() {
+        const rows = this.#db.all(`SELECT DISTINCT process_instance_key FROM ${OPEN_USER_TASKS_TABLE}`);
+        return rows.map((r) => r.process_instance_key);
+    }
     /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
     hasOpenTask(processInstanceKey) {
         if (!processInstanceKey)

package/dist/runtime/core/modules/pages.js

@@ -32,6 +32,7 @@ import { FORMJS_JS } from "./formjs.gen.js";
 import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { quoteIdent } from "./gateway.js";
 import { RENDERER_JS } from "./runtime.gen.js";
+import { isSqlIdentifier } from "../read-model.js";
 /** A JavaScript-body response (the renderer module served at the fingerprinted
  * `/app/runtime.<hash>.js`, and its `/app/runtime.js` back-compat route). */
 function javascript(body, status = 200, extraHeaders) {
@@ -118,9 +119,10 @@ async function serveAsset(read, filePath) {
         return { status: 404, headers: { "content-type": "text/plain; charset=utf-8" }, body: "not found" };
     }
 }
-/** A SQL identifier guard — a table name must be a bare identifier *and* a known table
- * (checked against `schema()`), so `/app/data/:table` can never inject SQL. */
-const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A table name must be a bare SQL identifier ({@link isSqlIdentifier}, the runtime-wide single source
+ * of truth) *and* a known table (checked against `schema()`), so `/app/data/:table` can never inject
+ * SQL. Reusing the shared guard (rather than a private regex) keeps this surface from drifting from
+ * manifest / read-model / data-source identifier validation. */
 // A query flag (e.g. ?count=1) is "on" when present and not one of the falsy
 // spellings. A bare `?count` (empty string) still counts as on, so a caller can
 // opt in without inventing a value.
@@ -299,7 +301,7 @@ export function createPagesRoutes(opts, deps) {
             // source is rejected rather than silently served off the default.
             if (source !== sourceName)
                 return json({ error: `unknown datasource "${source}"` }, 404);
-            if (!IDENT.test(table))
+            if (!isSqlIdentifier(table))
                 return json({ error: "invalid table name" }, 400);
             let tables;
             try {

package/dist/runtime/core/modules/workers.js

@@ -7,7 +7,7 @@ import { runLlmJob } from "./llm.js";
 import { runInJobContext } from "../execContext.js";
 import { readLineage } from "../lineage.js";
 import { LineageStore } from "./lineage-store.js";
-import { readModelRegistry } from "../read-model.js";
+import { readModelRegistry, rollupRegistry } from "../read-model.js";
 import { registerCanonicalProjections } from "./canonical-projections.js";
 import { InstanceStateStore } from "./instance-state-store.js";
 import { OpenUserTasksStore } from "./open-user-tasks-store.js";
@@ -99,6 +99,26 @@ function tryLineageStore(app, log) {
         return undefined;
     }
 }
+/**
+ * Apply every managed rollup VIEW registered in the process-wide `rollupRegistry` (ADR 0065, #468) to
+ * the app's DEFAULT data source, in dependency order (a composed rollup after the rollup it reads).
+ * Mirrors {@link tryProvisionReadModelViews}: empty until a sibling task registers a rollup, and
+ * absent-/error-safe so a missing datasource or a VIEW-provisioning failure never breaks a worker mount.
+ */
+function tryProvisionRollupViews(app, log) {
+    if (rollupRegistry.all().length === 0)
+        return;
+    if (!app.data.hasDefaultSource()) {
+        log("debug", "rollups: no default data source; managed VIEW provisioning skipped");
+        return;
+    }
+    try {
+        rollupRegistry.ensureViews(app.data.source().db);
+    }
+    catch (err) {
+        log("warn", "rollups: failed to provision managed VIEWs", { error: String(err) });
+    }
+}
 /**
  * Apply every managed read-model VIEW registered in the process-wide `readModelRegistry` to the app's
  * DEFAULT data source (ADR 0065, surface #3). A `defineReadModel(...)` declaration compiles to a
@@ -202,6 +222,10 @@ export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     // provision the projection tables per source (absent-safe), and finally the read-model VIEWs.
     registerCanonicalProjections();
     tryProvisionCanonicalProjections(app, ctx.host.log);
+    // Rollup VIEWs (ADR 0065, #468) BEFORE the read-model VIEWs: a read model's key-correlated rollup
+    // lookup `LEFT JOIN`s a rollup's `*_counts` VIEW, and a composed rollup reads another rollup's VIEW,
+    // so every rollup VIEW (in dependency order) must exist before any dependent VIEW compiles.
+    tryProvisionRollupViews(app, ctx.host.log);
     tryProvisionReadModelViews(app, ctx.host.log);
     // Cache module loads so a multi-type handler module is imported once.
     const moduleCache = new Map();

package/dist/runtime/core/read-model.d.ts

@@ -10,7 +10,7 @@ export type Literal = string | number | boolean | null;
  * `col` references a column of the BASE row. `pcol` references a column of the CORRELATED projection
  * row and is only meaningful inside an {@link ExistsExpr} `where` predicate.
  */
-export type Expr = LitExpr | ColExpr | ProjColExpr | CompareExpr | AndExpr | OrExpr | NotExpr | CaseExpr | ExistsExpr;
+export type Expr = LitExpr | ColExpr | ProjColExpr | RollupColExpr | CompareExpr | AndExpr | OrExpr | NotExpr | IsNullExpr | CaseExpr | ExistsExpr;
 export interface LitExpr {
     readonly kind: "lit";
     readonly value: Literal;
@@ -23,6 +23,13 @@ export interface ProjColExpr {
     readonly kind: "pcol";
     readonly name: string;
 }
+export interface RollupColExpr {
+    readonly kind: "rcol";
+    /** The read-model rollup-lookup alias this column is read from (see {@link RollupLookupDecl}). */
+    readonly lookup: string;
+    /** The rollup output column referenced (a column of the looked-up `*_counts` rollup row). */
+    readonly name: string;
+}
 export interface CompareExpr {
     readonly kind: "compare";
     readonly op: CompareOp;
@@ -41,6 +48,10 @@ export interface NotExpr {
     readonly kind: "not";
     readonly expr: Expr;
 }
+export interface IsNullExpr {
+    readonly kind: "isNull";
+    readonly expr: Expr;
+}
 export interface WhenClause {
     readonly when: Expr;
     readonly then: Expr;
@@ -63,6 +74,13 @@ export declare const lit: (value: Literal) => LitExpr;
 export declare const col: (name: string) => ColExpr;
 /** A reference to a correlated PROJECTION-row column (only valid inside {@link exists}). */
 export declare const pcol: (name: string) => ProjColExpr;
+/**
+ * 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 declare const rcol: (lookup: string, name: string) => RollupColExpr;
 export declare const eq: (left: Expr, right: Expr) => CompareExpr;
 export declare const neq: (left: Expr, right: Expr) => CompareExpr;
 export declare const lt: (left: Expr, right: Expr) => CompareExpr;
@@ -72,6 +90,10 @@ export declare const gte: (left: Expr, right: Expr) => CompareExpr;
 export declare const and: (...clauses: Expr[]) => AndExpr;
 export declare const or: (...clauses: Expr[]) => OrExpr;
 export declare const not: (expr: Expr) => NotExpr;
+/** `<expr> IS NULL` — a null test (1/0 in SQL; `value == null` in TS). `not(isNull(x))` is `IS NOT NULL`. */
+export declare const isNull: (expr: Expr) => IsNullExpr;
+/** Sugar for `not(isNull(expr))` — `<expr> IS NOT NULL`. */
+export declare const isNotNull: (expr: Expr) => NotExpr;
 /** Build a `CASE WHEN … THEN … [WHEN …] ELSE … END` expression. */
 export declare const caseWhen: (whens: WhenClause[], otherwise: Expr) => CaseExpr;
 /** Sugar for a single `{ when, then }` clause used by {@link caseWhen}. */
@@ -127,22 +149,72 @@ export interface SqlCompileOptions {
     readonly baseAlias?: string;
     /** Resolve a projection NAME to its physical SQL table/view. Defaults to {@link projectionRegistry}. */
     readonly resolveProjectionTable?: (name: string) => string;
+    /**
+     * Resolve a {@link col} reference to its qualified SQL expression, overriding the default
+     * `<baseAlias>."name"`. A rollup over a key-JOIN uses this to map a flat output-column name onto the
+     * correct joined relation (`col("pr_status")` → `"r"."status"`) so the closed {@link Expr} predicate
+     * machinery is reused unchanged across single-relation and join sources.
+     */
+    readonly resolveColumn?: (name: string) => string;
+    /**
+     * Resolve an {@link rcol} reference (a key-correlated rollup-lookup column) to its qualified SQL
+     * expression. {@link defineReadModel} supplies this from its `lookups` so the lookup's NULL default
+     * (a LEFT-JOIN miss) compiles to `COALESCE(<alias>."name", <default>)`.
+     */
+    readonly resolveRollupColumn?: (lookup: string, name: string) => string;
 }
+/** 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 declare const SQL_IDENT: RegExp;
+/** 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 declare function isSqlIdentifier(name: string): boolean;
 export declare function assertSqlIdentifier(kind: string, name: string): string;
+/** 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 declare const RESERVED_OBJECT_PREFIXES: readonly ["_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 declare function isReservedObjectName(name: string): boolean;
 /**
  * Compile ONE derivation expression to a SQLite select-list expression string — the derived column's
  * body inside the managed VIEW. Both backends walk the SAME AST, so the SQL here and the function
  * {@link compileToFn} produces cannot diverge.
  */
 export declare function compileToSqlSelect(expr: Expr, options?: SqlCompileOptions): string;
+/** The resolved single rollup-lookup rows for one evaluation, keyed by the FOLDED (case-insensitive,
+ *  SQLite-folded) lookup alias — see {@link rcol}, whose `node.lookup` is folded the same way on read.
+ *  Every declared lookup alias maps to exactly one resolved row: the matched rollup group with its
+ *  missing/NULL columns already filled from the lookup's declared defaults (the TS twin of the VIEW's
+ *  `COALESCE(alias.col, default)`). A LEFT-JOIN miss is therefore represented as a defaults/NULL-filled
+ *  row — NOT an absent alias — so `rcol` always reads a stable object. Framework resolvers
+ *  ({@link ReadModel.evaluate}, the parity guard) populate this; a raw `fnFor` caller on a model with
+ *  lookups must pass the resolved map. */
+export type LookupRows = Record<string, Record<string, unknown>>;
 /** The compiled runtime derivation: same value as the SQL VIEW, computed in-process. */
-export type DerivationFn = (baseRow: BaseRow, projections?: ProjectionRows) => unknown;
+export type DerivationFn = (baseRow: BaseRow, projections?: ProjectionRows, lookups?: LookupRows) => unknown;
 /**
  * Compile ONE derivation expression to a TS function computing the SAME value as {@link compileToSqlSelect}.
  * The function reads the base row for `col`, and — for `exists` — the `projections` argument for the
  * named projection's rows (the TS side of the projection-name seam). Both backends walk the SAME AST.
  */
 export declare function compileToFn(expr: Expr): DerivationFn;
+/** 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 declare function lookupColumn(row: Record<string, unknown>, name: string): unknown;
 /** The declarative read-model input passed to {@link defineReadModel}. */
 export interface ReadModelDecl {
     /** The managed VIEW name (also the read-model identifier). */
@@ -159,6 +231,37 @@ export interface ReadModelDecl {
      * ones. Defaults to true (a read model is usually the base row PLUS its derived columns).
      */
     readonly selectBaseColumns?: boolean;
+    /**
+     * Optional key-correlated ROLLUP LOOKUPS (ADR 0065, #468). Each declares a `LEFT JOIN <rollup> ON
+     * <key>` so a derived column can read the rollup's `*_counts` columns for the base row via
+     * {@link rcol}. This is the per-row half of the layering: the aggregate is single-sourced in
+     * {@link defineRollup}; the read model consumes its columns for a `CASE`-style per-row signal (the
+     * `plan_delivery`/`plan_wave_progress` shape). The join `on` must map the rollup's FULL group key so
+     * the lookup is single-valued (no fan-out of base rows).
+     */
+    readonly lookups?: readonly RollupLookupDecl[];
+}
+/** One key-correlated rollup lookup on a {@link defineReadModel} (see {@link ReadModelDecl.lookups}). */
+export interface RollupLookupDecl {
+    /** The alias `rcol(alias, …)` reads this lookup's columns under (a SQL identifier). */
+    readonly as: string;
+    /** The rollup whose `*_counts` VIEW is joined (its `name` is the physical relation, its columns the
+     *  readable set). Pass the {@link Rollup} object so the read model can validate referenced columns. */
+    readonly rollup: Rollup;
+    /**
+     * The equi-join key: each `{ base, rollup }` pair equates a base column to a rollup group-key column.
+     * Must cover the rollup's ENTIRE `groupBy` so the joined row is unique (≤1 match per base row).
+     */
+    readonly on: ReadonlyArray<{
+        readonly base: string;
+        readonly rollup: string;
+    }>;
+    /**
+     * Optional per-column defaults substituted when the join misses (no matching rollup group) or the
+     * rollup value is NULL — the `COALESCE(<alias>."col", <default>)` in the hand-authored VIEWs. Applied
+     * identically in both backends so an epic with no PRs reads `0` rather than NULL.
+     */
+    readonly defaults?: Record<string, Literal>;
 }
 /** A compiled read model: the declaration plus its derived SQL, derived functions, and managed VIEW. */
 export interface ReadModel {
@@ -169,8 +272,18 @@ export interface ReadModel {
     sqlSelectFor(column: string, options?: SqlCompileOptions): string;
     /** The TS derivation function for one derived column. */
     fnFor(column: string): DerivationFn;
-    /** Evaluate ALL derived columns for a base row in-process (the TS backend of the whole model). */
-    evaluate(baseRow: BaseRow, projections?: ProjectionRows): Record<string, unknown>;
+    /** Evaluate ALL derived columns for a base row in-process (the TS backend of the whole model). The
+     *  optional `lookupRows` supplies each rollup-lookup's candidate rows (keyed by lookup alias); the
+     *  model resolves the single matching group row per lookup (applying declared defaults) before
+     *  evaluating {@link rcol} references. */
+    evaluate(baseRow: BaseRow, projections?: ProjectionRows, lookupRows?: Record<string, ReadonlyArray<Record<string, unknown>>>): Record<string, unknown>;
+    /** Resolve each declared rollup lookup's single matching group row for `baseRow` (match on the join
+     *  keys, fill declared defaults), producing the {@link LookupRows} a {@link DerivationFn} reads via
+     *  {@link rcol}. The single source of the lookup-resolution rule: {@link evaluate} and the parity guard
+     *  both call this so they can never drift. Throws if a lookup's candidate set yields MORE than one
+     *  match for the join key — the lookup is required to be single-valued (its join covers the rollup's
+     *  full group key), so multiple matches would fan out in SQL while TS silently picked one. */
+    resolveLookups(baseRow: BaseRow, lookupRows: Record<string, ReadonlyArray<Record<string, unknown>>>): LookupRows;
     /** The managed `CREATE VIEW` DDL (seam (a) applies this at boot). Pass `{ temp: true }` to emit a
      *  `CREATE TEMP VIEW` in SQLite's TEMP schema (used by the parity guard so it never touches the
      *  application's real objects); the SELECT body is byte-identical either way. */
@@ -223,10 +336,15 @@ export declare class ReadModelRegistry {
  * task registers its derived status-edge read model here so the runtime provisions its VIEW at boot.
  */
 export declare const readModelRegistry: ReadModelRegistry;
-/** A single parity check case: a base row plus the projection rows in scope for it. */
+/** A single parity check case: a base row, the projection rows in scope for it, and (for a read model
+ *  with rollup lookups) the candidate rollup rows per lookup alias. */
 export interface ParitySample {
     readonly baseRow: BaseRow;
     readonly projections?: ProjectionRows;
+    /** Candidate rows for each declared rollup lookup, keyed by lookup alias (see {@link rcol}). The
+     *  guard inserts them into the lookup rollup's fixture table so the VIEW's `LEFT JOIN` materialises,
+     *  and hands the same rows to the TS backend to resolve — closing the lookup's parity surface. */
+    readonly lookups?: Record<string, ReadonlyArray<Record<string, unknown>>>;
 }
 /** The seam a parity guard needs to run the SQL backend: a SQLite handle it can create/query/drop. */
 export interface ParityDb {
@@ -265,3 +383,176 @@ export interface ParityOptions {
  * tables/views the caller's DB happens to hold under the same names.
  */
 export declare function assertReadModelParity(model: ReadModel, db: ParityDb, samples: ParitySample[], options?: ParityOptions): void;
+/** A closed, flat GROUP-BY aggregate expression (D2). `coalesce`/`add` wrap other aggregates so the
+ *  exact `COALESCE(MIN(…), MAX(…))` and `MAX(…)+1` shapes the plan VIEWs use are expressible; every
+ *  variant is handled exhaustively by both backends (SQL + TS reduce). */
+export type AggExpr = CountAgg | CountWhereAgg | MaxAgg | MinWhereAgg | CoalesceAgg | AddAgg;
+export interface CountAgg {
+    readonly kind: "count";
+    /** When set, `COUNT(col)` (non-NULL rows); omitted → `COUNT(*)` (all group rows). */
+    readonly column?: string;
+}
+export interface CountWhereAgg {
+    readonly kind: "countWhere";
+    /** `SUM(CASE WHEN pred THEN 1 ELSE 0 END)` — count of group rows satisfying the closed predicate. */
+    readonly pred: Expr;
+}
+export interface MaxAgg {
+    readonly kind: "max";
+    readonly column: string;
+}
+export interface MinWhereAgg {
+    readonly kind: "minWhere";
+    /** `MIN(CASE WHEN pred THEN col END)` — min of `col` over rows satisfying `pred` (NULL if none). */
+    readonly column: string;
+    readonly pred: Expr;
+}
+export interface CoalesceAgg {
+    readonly kind: "coalesce";
+    readonly a: AggExpr;
+    readonly b: AggExpr;
+}
+export interface AddAgg {
+    readonly kind: "add";
+    readonly expr: AggExpr;
+    /** An INTEGER literal added to `expr` (e.g. `MAX(wave) + 1`). NULL + literal is NULL, both backends. */
+    readonly literal: number;
+}
+/** `COUNT(col)` (non-NULL) when `column` is given, else `COUNT(*)`. */
+export declare const count: (column?: string) => CountAgg;
+/** `SUM(CASE WHEN pred THEN 1 ELSE 0 END)` — the count of group rows satisfying `pred`. */
+export declare const countWhere: (pred: Expr) => CountWhereAgg;
+/** `MAX(col)` over the group (ignores NULLs; NULL for an all-NULL/empty group). */
+export declare const max: (column: string) => MaxAgg;
+/** `MIN(CASE WHEN pred THEN col END)` — the min of `col` over group rows satisfying `pred`. */
+export declare const minWhere: (column: string, pred: Expr) => MinWhereAgg;
+/** `COALESCE(a, b)` over two aggregates — `a` unless it is NULL, then `b`. */
+export declare const coalesce: (a: AggExpr, b: AggExpr) => CoalesceAgg;
+/** `expr + <integer literal>` (e.g. `MAX(wave) + 1`). Rejects a non-integer literal at build time. */
+export declare const add: (expr: AggExpr, literal: number) => AddAgg;
+/** The relation a rollup groups over. `table`/`projection`/`rollup` expose their columns by name; a
+ *  key-`join` exposes a FLAT namespace mapped by {@link RollupJoinSource.columns} (the two-hop reach —
+ *  D4). All three are single-mechanism composable: a `rollup` source is another {@link Rollup}. */
+export type RollupSource = RollupTableSource | RollupProjectionSource | RollupJoinSource | RollupRollupSource;
+export interface RollupTableSource {
+    readonly kind: "table";
+    readonly table: string;
+}
+export interface RollupProjectionSource {
+    readonly kind: "projection";
+    readonly projection: string;
+}
+/** One relation in a {@link RollupJoinSource} — a base table/view/projection under a join alias. */
+export interface RollupRelation {
+    readonly relation: string;
+    readonly alias: string;
+}
+export interface RollupJoinSource {
+    readonly kind: "join";
+    /** `"left"` (default) or `"inner"`. LEFT keeps unmatched left rows with NULL right columns. */
+    readonly type?: "left" | "inner";
+    readonly left: RollupRelation;
+    readonly right: RollupRelation;
+    /** Equi-join key(s): `left.<left> = right.<right>`. */
+    readonly on: ReadonlyArray<{
+        readonly left: string;
+        readonly right: string;
+    }>;
+    /**
+     * The FLAT output namespace: output column name → `[side, physicalColumn]`. This resolves collisions
+     * (both sides may have a `status`) and is what `groupBy`/aggregate `col(...)` references resolve
+     * against, so the closed predicate/aggregate machinery is reused unchanged over a join.
+     */
+    readonly columns: Record<string, readonly [side: "left" | "right", column: string]>;
+}
+export interface RollupRollupSource {
+    readonly kind: "rollup";
+    readonly rollup: Rollup;
+}
+/** A rollup over a base table. */
+export declare const fromTable: (table: string) => RollupTableSource;
+/** A rollup over a canonical projection (resolved to its physical relation via {@link projectionRegistry}). */
+export declare const fromProjection: (projection: string) => RollupProjectionSource;
+/** A rollup over another rollup's `*_counts` VIEW (composable — e.g. wave's two levels). */
+export declare const fromRollup: (rollup: Rollup) => RollupRollupSource;
+/** A rollup over a declared key-join of two relations (the two-hop reach — D4). */
+export declare const joinSource: (spec: Omit<RollupJoinSource, "kind">) => RollupJoinSource;
+/** The in-memory rows the TS group-reduce sees per LEAF relation (base table/view/projection name). */
+export type RollupInputs = Record<string, ReadonlyArray<Record<string, unknown>>>;
+/** The declarative rollup input passed to {@link defineRollup}. */
+export interface RollupDecl {
+    /** The managed VIEW name (also the rollup / canonical-projection identifier). */
+    readonly name: string;
+    /** The relation to group over (table / projection / key-join / another rollup). */
+    readonly source: RollupSource;
+    /** One or more group-key columns (referenced by name in the source's output namespace). */
+    readonly groupBy: readonly string[];
+    /** Optional pre-aggregation row filter (the `WHERE` — e.g. `isNotNull(col("wave"))`). */
+    readonly where?: Expr;
+    /** The aggregate columns: name → closed {@link AggExpr}. Authored ONCE, compiled to both backends. */
+    readonly aggregates: Record<string, AggExpr>;
+}
+/** A compiled rollup: the declaration plus both backends and the managed VIEW DDL. */
+export interface Rollup {
+    readonly decl: RollupDecl;
+    /** The canonical-projection name (= `decl.name`). */
+    readonly projectionName: string;
+    /** The group-key columns (order preserved from the declaration). */
+    readonly groupBy: readonly string[];
+    /** All output columns: the group keys followed by the aggregate names (aggregates sorted by name). */
+    readonly outputColumns: readonly string[];
+    /** Leaf relation names this rollup reads, transitively (for fixtures / feeding the TS reduce). */
+    readonly sourceRelations: readonly string[];
+    /** This rollup and every rollup it composes, in dependency order (dependencies first) — the order the
+     *  managed VIEWs must be created in. */
+    readonly viewChain: readonly Rollup[];
+    /** The SQLite select-list expression for one aggregate column. */
+    sqlAggFor(column: string, options?: SqlCompileOptions): string;
+    /** The in-process group-reduce (the TS backend): leaf rows → one output row per group. */
+    reduce(inputs: RollupInputs): Record<string, unknown>[];
+    /** The managed `CREATE VIEW` DDL. `{ temp: true }` emits a `CREATE TEMP VIEW` (parity-guard use). */
+    viewDdl(options?: SqlCompileOptions, viewOptions?: ViewDdlOptions): string;
+    /** Fixture column requirements per leaf relation (referenced physical columns), for the parity guard. */
+    fixtureColumns(): Map<string, Set<string>>;
+}
+/**
+ * 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 declare function defineRollup(decl: RollupDecl): Rollup;
+/**
+ * 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 declare class RollupRegistry {
+    #private;
+    register(rollup: Rollup, projections?: ProjectionRegistry): void;
+    all(): Rollup[];
+    get(name: string): Rollup | undefined;
+    /** 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: {
+        exec(sql: string): void;
+    }, options?: SqlCompileOptions): void;
+    clear(): void;
+}
+/** Process-wide rollup registry — the concrete registration point apps/sidecars import and call. */
+export declare const rollupRegistry: RollupRegistry;
+/** Options for {@link assertRollupParity}. */
+export interface RollupParityOptions {
+    readonly onMismatch?: (message: string) => never;
+    readonly sql?: SqlCompileOptions;
+}
+/**
+ * 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 declare function assertRollupParity(rollup: Rollup, db: ParityDb, sampleSets: RollupInputs[], options?: RollupParityOptions): void;