@nanobpm/urban 0.77.4 → 0.78.0

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

@@ -7,6 +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 { defaultScheduler, schedulerClock } from "./scheduler.js";
 /** Adapt an engine SDK client into the LLM module's `DecisionEvaluator`, parsing the
  *  decision's JSON-string `output` into the value fed back to the LLM job. Validates the
@@ -95,6 +96,29 @@ function tryLineageStore(app, log) {
         return undefined;
     }
 }
+/**
+ * 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
+ * managed SQLite VIEW; provisioning it here — the same per-source boot path `tryLineageStore` uses —
+ * means an app (or a canonical-projection sidecar) that registers a read model gets its VIEW created
+ * for free, with no hand-written migration. The registry is empty until a sibling task registers into
+ * it, so this is a silent no-op in the base framework. Absent- and error-safe like lineage: an app
+ * with no datasource provisions nothing, and a VIEW-provisioning failure never breaks a worker mount.
+ */
+function tryProvisionReadModelViews(app, log) {
+    if (readModelRegistry.all().length === 0)
+        return;
+    if (!app.data.hasDefaultSource()) {
+        log("debug", "read-models: no default data source; managed VIEW provisioning skipped");
+        return;
+    }
+    try {
+        readModelRegistry.ensureViews(app.data.source().db);
+    }
+    catch (err) {
+        log("warn", "read-models: failed to provision managed VIEWs", { error: String(err) });
+    }
+}
 /** Record an activated job's lineage edge, never letting a projection write break the job. */
 function recordJobLineage(store, job, log) {
     try {
@@ -142,6 +166,10 @@ export async function mountWorkers(ctx, app, sched = defaultScheduler()) {
     // edge its instance carries, so intent→progress lineage materialises for free. Absent when the
     // app configures no default data source.
     const lineageStore = tryLineageStore(app, ctx.host.log);
+    // The framework read-model VIEWs (ADR 0065): apply every registered managed VIEW to the app's
+    // default data source, the same per-source boot path lineage uses. A no-op until a sibling task
+    // registers a read model into `readModelRegistry`.
+    tryProvisionReadModelViews(app, ctx.host.log);
     // Cache module loads so a multi-type handler module is imported once.
     const moduleCache = new Map();
     const joinRoot = (p) => p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;

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

@@ -0,0 +1,267 @@
+/** The comparison operators the DSL supports, in both backends. */
+export type CompareOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
+/** A DSL literal value. Kept to the SQL/JS-portable scalars so both backends agree. */
+export type Literal = string | number | boolean | null;
+/**
+ * The closed expression AST — a discriminated union, NOT arbitrary strings or SQL fragments. This
+ * closedness is the whole point: one declaration compiles to two backends that cannot drift. Every
+ * node kind is handled exhaustively by both {@link compileToSqlSelect} and {@link compileToFn}.
+ *
+ * `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 interface LitExpr {
+    readonly kind: "lit";
+    readonly value: Literal;
+}
+export interface ColExpr {
+    readonly kind: "col";
+    readonly name: string;
+}
+export interface ProjColExpr {
+    readonly kind: "pcol";
+    readonly name: string;
+}
+export interface CompareExpr {
+    readonly kind: "compare";
+    readonly op: CompareOp;
+    readonly left: Expr;
+    readonly right: Expr;
+}
+export interface AndExpr {
+    readonly kind: "and";
+    readonly clauses: readonly Expr[];
+}
+export interface OrExpr {
+    readonly kind: "or";
+    readonly clauses: readonly Expr[];
+}
+export interface NotExpr {
+    readonly kind: "not";
+    readonly expr: Expr;
+}
+export interface WhenClause {
+    readonly when: Expr;
+    readonly then: Expr;
+}
+export interface CaseExpr {
+    readonly kind: "case";
+    readonly whens: readonly WhenClause[];
+    readonly else: Expr;
+}
+export interface ExistsExpr {
+    readonly kind: "exists";
+    /** The projection name referenced (resolved to a physical table via {@link ProjectionRegistry}). */
+    readonly projection: string;
+    /** The correlation predicate; may mix {@link pcol} (projection) and {@link col} (base) refs. */
+    readonly where: Expr;
+}
+/** A literal scalar. */
+export declare const lit: (value: Literal) => LitExpr;
+/** A reference to a BASE-row column. */
+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;
+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;
+export declare const lte: (left: Expr, right: Expr) => CompareExpr;
+export declare const gt: (left: Expr, right: Expr) => CompareExpr;
+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;
+/** 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}. */
+export declare const when: (whenExpr: Expr, thenExpr: Expr) => WhenClause;
+/** `EXISTS (SELECT 1 FROM <projection> WHERE <where>)` — a correlated existence test. */
+export declare const exists: (projection: string, where: Expr) => ExistsExpr;
+/**
+ * A canonical projection the DSL's {@link exists} can reference by name. A sidecar (the
+ * `canonical-projections` task) provides one per engine-truth projection so the SQL backend knows
+ * which physical table/view to read and the TS backend can be handed matching rows.
+ */
+export interface ProjectionSource {
+    /** The stable DSL name used in `exists(name, …)`. */
+    readonly name: string;
+    /**
+     * The physical SQLite table/view the SQL backend reads for `EXISTS`. Defaults to {@link name} when
+     * the stable DSL name already matches the physical relation; a sidecar sets it explicitly when the
+     * two differ (e.g. a stable DSL name like `urban_instance_state` mapped onto an `_urban_`-prefixed
+     * engine-truth table).
+     */
+    readonly sqlTable?: string;
+}
+/** The in-memory rows the TS backend sees for one evaluation, keyed by projection name. */
+export type ProjectionRows = Record<string, ReadonlyArray<Record<string, unknown>>>;
+/** A base row fed to the TS backend / parity guard. */
+export type BaseRow = Record<string, unknown>;
+/**
+ * The projection-name registry (seam (b)). A canonical engine-truth projection sidecar registers its
+ * name here so a `defineReadModel` authored anywhere can `exists(name, …)` over it. Advisory/idempotent:
+ * re-registering the same name with a matching `sqlTable` is a no-op; a conflicting `sqlTable` throws
+ * so two sidecars cannot silently claim one name.
+ */
+export declare class ProjectionRegistry {
+    #private;
+    register(source: ProjectionSource): void;
+    /** The physical SQL table/view for a projection name; falls back to the name itself if unregistered
+     *  (so a read model compiles against a not-yet-landed sidecar, which supplies the same-named table). */
+    sqlTableFor(name: string): string;
+    has(name: string): boolean;
+    names(): string[];
+    /** Reset all registrations. Mirrors {@link ReadModelRegistry.clear} so tests and dev harnesses can
+     *  restore this process-wide singleton to a deterministic empty state (isolation across test runs). */
+    clear(): void;
+}
+/**
+ * Process-wide projection registry — the concrete registration point sidecars import and call. The
+ * `canonical-projections` task registers `urban_open_user_tasks` and `urban_instance_state` here.
+ */
+export declare const projectionRegistry: ProjectionRegistry;
+/** Options for {@link compileToSqlSelect}. */
+export interface SqlCompileOptions {
+    /** The alias the managed VIEW gives the base table (so `col("x")` → `<baseAlias>."x"`). */
+    readonly baseAlias?: string;
+    /** Resolve a projection NAME to its physical SQL table/view. Defaults to {@link projectionRegistry}. */
+    readonly resolveProjectionTable?: (name: string) => string;
+}
+export declare function assertSqlIdentifier(kind: string, name: string): string;
+/**
+ * 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 compiled runtime derivation: same value as the SQL VIEW, computed in-process. */
+export type DerivationFn = (baseRow: BaseRow, projections?: ProjectionRows) => 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;
+/** The declarative read-model input passed to {@link defineReadModel}. */
+export interface ReadModelDecl {
+    /** The managed VIEW name (also the read-model identifier). */
+    readonly name: string;
+    /** The base table the VIEW selects from; the derived columns are functions of its rows. */
+    readonly baseTable: string;
+    /**
+     * The derived columns: name → derivation expression. Each is authored ONCE and compiled to both a
+     * SQLite select-list expression and a TS function.
+     */
+    readonly derive: Record<string, Expr>;
+    /**
+     * Optional: whether the managed VIEW re-exports the base columns (`base.*`) alongside the derived
+     * ones. Defaults to true (a read model is usually the base row PLUS its derived columns).
+     */
+    readonly selectBaseColumns?: boolean;
+}
+/** A compiled read model: the declaration plus its derived SQL, derived functions, and managed VIEW. */
+export interface ReadModel {
+    readonly decl: ReadModelDecl;
+    /** Projection names referenced by any derived column's `exists` (for registry/validation). */
+    readonly projectionNames: string[];
+    /** The SQLite select-list expression for one derived column. */
+    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>;
+    /** 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. */
+    viewDdl(options?: SqlCompileOptions, viewOptions?: ViewDdlOptions): string;
+}
+/** Shape modifiers for {@link ReadModel.viewDdl} (as opposed to the SQL compile options for its body). */
+export interface ViewDdlOptions {
+    /** Emit `CREATE TEMP VIEW` (SQLite TEMP schema) instead of a plain `CREATE VIEW`. */
+    readonly temp?: boolean;
+}
+/**
+ * Declare a derived read model ONCE, as a pure derivation over a base row plus named canonical
+ * projections. The returned {@link ReadModel} exposes both backends (SQL select-list + TS function)
+ * and the managed VIEW DDL, all driven from the same AST so surface #2 (double-authoring) is closed.
+ * Register it in the {@link readModelRegistry} to have the runtime apply its VIEW at boot (surface #3).
+ */
+export declare function defineReadModel(decl: ReadModelDecl): ReadModel;
+/** Convenience alias for {@link ReadModel.viewDdl} — the framework-derived managed VIEW DDL. */
+export declare function deriveReadModelViewDdl(model: ReadModel, options?: SqlCompileOptions): string;
+/**
+ * The read-model registry (seam (a)). Sidecars/apps register a {@link ReadModel}; the runtime boot
+ * path applies every registered model's managed VIEW to the app's data source (see
+ * `core/modules/workers.ts`). Idempotent: re-registering the same name whose VIEW DDL matches is a
+ * no-op; a conflicting redefinition throws so two definitions cannot silently claim one name.
+ */
+export declare class ReadModelRegistry {
+    #private;
+    register(model: ReadModel): void;
+    all(): ReadModel[];
+    get(name: string): ReadModel | undefined;
+    /** Apply every registered model's managed VIEW to a database (the boot-path entry point). Safe to
+     *  call repeatedly and it is truly MANAGED: each VIEW is dropped and recreated so a changed
+     *  read-model definition in code always replaces a stale VIEW body (a plain `CREATE VIEW IF NOT
+     *  EXISTS` would leave the SQL backend running an old definition, reintroducing backend drift).
+     *  Referenced base/projection tables need not exist yet — SQLite only resolves a VIEW's body when
+     *  it is queried.
+     *
+     *  The DROP is `main.`-qualified on purpose: an unqualified `DROP VIEW IF EXISTS "name"` resolves
+     *  TEMP first, so a stray TEMP view of the same name (e.g. leaked from a parity-guard run on a
+     *  long-lived handle) would be dropped INSTEAD of the managed `main` view — and the following
+     *  `CREATE VIEW IF NOT EXISTS` would then no-op against the surviving `main` view, leaving a stale
+     *  managed body in production. Qualifying to `main` drops exactly the managed view we recreate. */
+    ensureViews(db: {
+        exec(sql: string): void;
+    }, options?: SqlCompileOptions): void;
+    clear(): void;
+}
+/**
+ * Process-wide read-model registry — the concrete registration point. The `writer-source-inversion`
+ * 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. */
+export interface ParitySample {
+    readonly baseRow: BaseRow;
+    readonly projections?: ProjectionRows;
+}
+/** The seam a parity guard needs to run the SQL backend: a SQLite handle it can create/query/drop. */
+export interface ParityDb {
+    exec(sql: string): void;
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+}
+/** Options for {@link assertReadModelParity}. */
+export interface ParityOptions {
+    /** Only check these derived columns (defaults to all). */
+    readonly columns?: string[];
+    /** A failure sink; defaults to throwing an `Error`. */
+    readonly onMismatch?: (message: string) => never;
+    /**
+     * The SAME SQL compile options used to provision the runtime VIEW (e.g. a custom
+     * `resolveProjectionTable` or `baseAlias`). Threaded through so the guard builds fixtures and
+     * materialises the VIEW against the same physical projection tables the runtime uses — otherwise a
+     * caller with a custom resolver would test a different VIEW than production and get false mismatches.
+     */
+    readonly sql?: SqlCompileOptions;
+}
+/**
+ * The framework PARITY GUARD (surface #3). Given a compiled read model and sample base+projection
+ * rows, it materialises the managed VIEW over throwaway in-memory tables, reads the SQL-derived
+ * value for each column, computes the TS-function value for the same inputs, and asserts they agree —
+ * so an app no longer hand-writes a bespoke parity test per projection. Throws (or calls
+ * `onMismatch`) on the first divergence, naming the column, sample index, and both values.
+ *
+ * The caller supplies a SQLite handle (e.g. an in-memory DB from the node/deno host). The guard
+ * builds minimal fixture tables for the base table and each referenced projection from the sample
+ * rows' own keys — entirely in SQLite's TEMP schema (`CREATE TEMP TABLE`/`CREATE TEMP VIEW`, dropped
+ * `temp.`-qualified) — so it needs no pre-existing schema AND can never clobber real application
+ * 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;