@nanobpm/urban 0.81.0 → 0.82.0

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,6 +149,19 @@ 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
@@ -155,8 +190,17 @@ export declare function isReservedObjectName(name: string): boolean;
  * {@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
@@ -187,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 {
@@ -197,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. */
@@ -251,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 {
@@ -293,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;