@nanobpm/urban 0.77.4 → 0.78.0

package/dist/runtime/index.d.ts

@@ -40,6 +40,8 @@ export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINE
 export type { ApplyLineageOptions, LineageAttachment, LineageEdge, LineageEdgeType, LineageEnvelope, LineageNode, LineageTree, } from "./core/lineage.ts";
 export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, LineageStore, systemClock as lineageSystemClock, } from "./core/modules/lineage-store.ts";
 export type { Clock as LineageClock, LineageJobLike, LineageStoreOptions, } from "./core/modules/lineage-store.ts";
+export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.ts";
+export type { AndExpr, BaseRow, CaseExpr, ColExpr, CompareExpr, CompareOp, DerivationFn, ExistsExpr, Expr, Literal, LitExpr, NotExpr, OrExpr, ParityDb, ParityOptions, ParitySample, ProjColExpr, ProjectionRows, ProjectionSource, ReadModel, ReadModelDecl, SqlCompileOptions, WhenClause, } from "./core/read-model.ts";
 export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.ts";
 export type { CrumbKind, CrumbSource, DerivePhaseOptions, FurthestReached, InstancePhase, LineagePhaseRollup, Phase, PhaseCrumb, PhaseGranularity, ProvenanceProgressRow, ScopeElement, ScopeIndex, } from "./core/phase.ts";
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";

package/dist/runtime/index.js

@@ -40,6 +40,19 @@ export { evalCorrelation } from "./core/modules/triggers.js";
 // progress (a root request → the instances/PRs/tasks it causes).
 export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINEAGE_NAMESPACE, mintRootRequestKey, readLineage, writeLineage, } from "./core/lineage.js";
 export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, LineageStore, systemClock as lineageSystemClock, } from "./core/modules/lineage-store.js";
+// ─────────────────────────────────────────── Read models ────────────────────────────────────────
+// The declare-once, compile-to-both derived read-model primitive (ADR 0065): a closed expression DSL
+// (`col`/`lit`/comparisons/`and`/`or`/`not`/`caseWhen`/`exists`) declared ONCE via `defineReadModel`,
+// compiled to BOTH a SQLite VIEW select-list (`compileToSqlSelect`) and an in-process TS function
+// (`compileToFn`) from the SAME AST, plus the framework-derived managed VIEW DDL and the parity guard
+// that replaces per-projection hand-written parity tests.
+//
+// SIBLING REGISTRATION POINTS (ADR 0065 rollout — see core/read-model.ts for the full seam docs):
+//   • `readModelRegistry`  — register a `defineReadModel(...)` result; the boot path (core/modules/
+//     workers.ts) applies its managed VIEW. The `writer-source-inversion` task registers here.
+//   • `projectionRegistry` — register a canonical engine-truth projection NAME usable in `exists(...)`.
+//     The `canonical-projections` task registers `urban_open_user_tasks` / `urban_instance_state`.
+export { and, assertReadModelParity, assertSqlIdentifier, caseWhen, col, compileToFn, compileToSqlSelect, defineReadModel, deriveReadModelViewDdl, eq, exists, gt, gte, lit, lt, lte, neq, not, or, pcol, ProjectionRegistry, projectionRegistry, ReadModelRegistry, readModelRegistry, when, } from "./core/read-model.js";
 // Phase — the framework-level *domain phase* primitive (issue #266): derive "which phase is this
 // instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
 // optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.4",
+	"version": "0.78.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/modules/workers.ts

@@ -11,6 +11,7 @@ import { runInJobContext } from "../execContext.ts";
 import type { JobExecContext } from "../execContext.ts";
 import { readLineage } from "../lineage.ts";
 import { LineageStore } from "./lineage-store.ts";
+import { readModelRegistry } from "../read-model.ts";
 import { defaultScheduler, schedulerClock, type SchedulerDeps } from "./scheduler.ts";
 
 /** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
@@ -135,6 +136,28 @@ function tryLineageStore(app: AppApi, log: RuntimeContext["host"]["log"]): Linea
   }
 }
 
+/**
+ * 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: AppApi, log: RuntimeContext["host"]["log"]): void {
+  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: LineageStore, job: EngineJob, log: RuntimeContext["host"]["log"]): void {
   try {
@@ -192,6 +215,11 @@ export async function mountWorkers(
   // 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<string, Record<string, unknown>>();
   const joinRoot = (p: string): string =>