@nanobpm/urban 0.77.3 → 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/dist/toolkit/addConnector.js

@@ -12,6 +12,7 @@
 // package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
 // unit-testable.
 import { errorMessage, isRecord } from "../runtime/core/guards.js";
+import { detectJsonIndent } from "./scaffold.js";
 const MANIFEST_FILE = "nano-ide.ext.json";
 function joinPath(a, b) {
     // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
@@ -61,9 +62,11 @@ export async function addConnector(opts) {
     if (!(await io.exists(appManifestPath))) {
         throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
     }
+    let appRaw;
     let app;
     try {
-        app = JSON.parse(await io.readText(appManifestPath));
+        appRaw = await io.readText(appManifestPath);
+        app = JSON.parse(appRaw);
     }
     catch (err) {
         throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
@@ -161,7 +164,10 @@ export async function addConnector(opts) {
         workers.push(entry);
         wired.push({ taskType: spec.type, alreadyPresent: false });
     }
-    await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+    // Preserve the manifest's own indentation (default tab, matching the scaffold's Biome config)
+    // so enabling a connector never reformats nano.app.json out from under `npm run lint` — the same
+    // fidelity `urban gen` gives via detectJsonIndent, kept as the single source of truth.
+    await io.writeText(appManifestPath, `${JSON.stringify(app, null, detectJsonIndent(appRaw))}\n`);
     return {
         packId: pack.id,
         wired,

package/dist/toolkit/scaffold/operations.js

@@ -29,16 +29,21 @@ export function renderOperationStub(operationId, dir = DEFAULT_OPERATIONS_DIR) {
         `// (ADR 0059). This file is yours to edit — \`urban gen\` will never overwrite it. The\n` +
         `// generated controller (nano-generated/controller.ts) imports this default export and\n` +
         `// type-checks it against the spec, so the signature cannot drift. Implement the body below\n` +
-        `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`) and delete the throw.\n` +
+        `// (the validated \`{ req, params, query, body }\` input + the injected \`app\`), replacing the\n` +
+        `// guard warn + throw.\n` +
         `import { NotImplemented } from "@nanobpm/urban";\n` +
         `import { defineOperation } from ${JSON.stringify(`${up}nano-generated/operations.ts`)};\n` +
         `\n` +
         `export default defineOperation(${key}, async (input, app) => {\n` +
-        `  // \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
-        `  // through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
-        `  // auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
-        `  // Return \`{ status?, headers?, body? }\` (or nothing → 204).\n` +
-        `  throw new NotImplemented(${key});\n` +
+        `\t// \`input\` is the validated request (params/query/body/req); reach app state + services\n` +
+        `\t// through the injected \`app\` API. Structured logs via \`app.log.info("…", { … })\` are\n` +
+        `\t// auto-tagged with this request's { method, path, operationId } (ADR 0061).\n` +
+        `\t// Return \`{ status?, headers?, body? }\` (or nothing → 204). Replace the two lines below.\n` +
+        `\tapp.log.warn("operation not implemented", {\n` +
+        `\t\toperationId: ${key},\n` +
+        `\t\tmethod: input.req.method,\n` +
+        `\t});\n` +
+        `\tthrow new NotImplemented(${key});\n` +
         `});\n`);
 }
 /**

package/dist/toolkit/scaffold/workers.js

@@ -38,21 +38,26 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
     else if (typedOut)
         generic = `<Record<string, unknown>, WorkerOutputs[${key}]>`;
     const varsNote = typedIn
-        ? `  // \`job.variables\` is typed as WorkerInputs[${key}].`
-        : `  // \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+        ? `\t// \`job.variables\` is typed as WorkerInputs[${key}].`
+        : `\t// \`job.variables\` is an open Record<string, unknown> (no declared input type).`;
+    // The stub arrives lint-clean under the scaffold's own Biome config: tab-indented, and
+    // referencing both `job` and `app` (via the warn line) so `noUnusedFunctionParameters`
+    // does not fire before the author has filled in the body.
     return (`// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
         `// This file is yours to edit — \`urban gen\` will never overwrite it. Implement the body\n` +
-        `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
+        `// below (use \`app.data.table(...)\` for state), replacing the guard warn + throw so the\n` +
+        `// "worker not implemented" warning does not survive into a working handler.\n` +
         `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
         generatedImport +
         `\n` +
         `const handler: AppJobHandler${generic} = async (job, app) => {\n` +
         varsNote +
         `\n` +
-        `  // Reach app state and services through the injected \`app\` API.\n` +
-        `  // Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
-        `  // { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
-        `  throw new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
+        `\t// Reach app state and services through the injected \`app\` API.\n` +
+        `\t// Structured logs: \`app.log.info("done", { … })\` — auto-tagged with this job's\n` +
+        `\t// { jobKey, jobType, processInstanceKey, elementId } (ADR 0061).\n` +
+        `\tapp.log.warn("worker not implemented", { jobKey: job.jobKey });\n` +
+        `\tthrow new Error(${JSON.stringify(`worker not implemented: ${taskType}`)});\n` +
         `};\n` +
         `\n` +
         `export default handler;\n`);

package/dist/toolkit/scaffold.d.ts

@@ -1,5 +1,17 @@
 import type { GenIO } from "./gen.ts";
 import { type SkippedWorker, type StubManifestEntry } from "./scaffold/workers.ts";
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export declare function detectJsonIndent(json: string): string;
 export interface ScaffoldOptions {
     root: string;
     io: GenIO;

package/dist/toolkit/scaffold.js

@@ -6,13 +6,38 @@ import { joinPath, readModels } from "./gen.js";
 import { planWorkerScaffold, } from "./scaffold/workers.js";
 import { planOperationScaffold } from "./scaffold/operations.js";
 import { parseSpec } from "../openapi/spec.js";
+/**
+ * Detect the indentation of a JSON document from its first indented line, so a rewrite can
+ * reuse it (`"\t"` or an N-space string) instead of hard-coding one style. Falls back to a tab
+ * — the scaffold's Biome default — when the file is empty/single-line or uses no indentation.
+ *
+ * Any indent — spaces or tabs — is clamped to 10 characters because `JSON.stringify` silently
+ * truncates a string `space` argument to 10; returning a wider prefix would promise a fidelity the
+ * serializer cannot honor (e.g. an 11+-tab manifest would be rewritten at a different width than
+ * its input). Tab indentation (the scaffold default) and any realistic width (2/4 spaces) are
+ * unaffected.
+ */
+export function detectJsonIndent(json) {
+    // Anchor on any line terminator, not just `\n`, so the width is detected regardless of the
+    // manifest's line endings: LF (`\n`), CRLF (`\r\n`, where `\n` already precedes the indent),
+    // bare-CR old-Mac (`\r`), and LFCR (`\n\r`) all resolve to the indentation that follows.
+    const m = json.match(/[\r\n]([ \t]+)\S/);
+    if (!m)
+        return "\t";
+    const indent = m[1];
+    return indent.length > 10 ? indent.slice(0, 10) : indent;
+}
 /** Scaffold write-once worker stubs from the model, wiring them into `manifest.workers[]`. */
 export async function scaffoldWorkers(opts) {
     const { root, io } = opts;
     const write = opts.write ?? false;
     const manifestFile = opts.manifestFile ?? "nano.app.json";
     const manifestPath = joinPath(root, manifestFile);
-    const manifest = JSON.parse(await io.readText(manifestPath));
+    const manifestRaw = await io.readText(manifestPath);
+    const manifest = JSON.parse(manifestRaw);
+    // Preserve the manifest's own indentation when we patch it back (default tab, matching the
+    // scaffold's Biome config), so wiring a worker never reformats the file out from under lint.
+    const manifestIndent = detectJsonIndent(manifestRaw);
     const models = await readModels(root, io, manifest);
     const declaredTypeIds = Object.keys(manifest.types ?? {});
     const { plans, skipped } = planWorkerScaffold(models, manifest.workers ?? [], declaredTypeIds, manifest.externalTaskTypes ?? []);
@@ -49,7 +74,7 @@ export async function scaffoldWorkers(opts) {
             ...manifest,
             workers: [...(manifest.workers ?? []), ...wired],
         };
-        await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, 2)}\n`);
+        await io.writeText(manifestPath, `${JSON.stringify(withWorkers, null, manifestIndent)}\n`);
         manifestPatched = true;
     }
     return { outcomes, skipped, wired, manifestPatched, write };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.3",
+	"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",
@@ -103,7 +103,7 @@
 		"@nanobpm/nano-sdk": "^1.2.5",
 		"@nanobpm/workflow": "^0.14.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.15.1",
+		"create-urban-app": "^0.15.2",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

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 =>