@nanobpm/urban 0.78.0 → 0.80.0

package/src/runtime/browser/formjs.browser.test.ts

@@ -0,0 +1,136 @@
+// Unit tests for the shared form-js renderer (formjs.browser.js, ADR 0026/#457):
+// the ONE client implementation of "render a deployed .form's form-js schema and
+// collect its field values", shared by BOTH the taskInbox surface and the pages
+// dataGrid engine-form detail. Importing the module also registers it as the
+// `globalThis.NanoFormJs` global that the pages runtime consumes.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildField, renderForm } from "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+test("NanoFormJs is registered as a browser global on import", () => {
+  const g = Reflect.get(globalThis, "NanoFormJs");
+  assert.ok(g, "importing the module exposes globalThis.NanoFormJs");
+});
+
+test("buildField skips keyless layout components and renders static text", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildField({ type: "spacer" }), null, "a keyless, non-text component is skipped");
+  const textOnly = buildField({ type: "text", text: "Read me" });
+  assert.ok(textOnly && !textOnly.read, "a static text component has no reader");
+  assert.equal(textOnly!.field.textContent, "Read me");
+});
+
+test("buildField reads a textfield's entered value, and omits a blank one", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "textfield", key: "note", label: "Note" });
+  assert.ok(built?.read);
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input);
+  input!.value = "hello";
+  assert.deepEqual(built!.read!(), { key: "note", value: "hello" });
+  input!.value = "";
+  assert.equal(built!.read!(), null, "a blank field is omitted from the submitted variables");
+});
+
+test("buildField coerces a number field and drops a non-finite value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "number", key: "qty" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.value = "42";
+  assert.deepEqual(built!.read!(), { key: "qty", value: 42 });
+  input!.value = "not-a-number";
+  assert.equal(built!.read!(), null, "a tampered non-numeric number field is treated as absent, never NaN→null");
+});
+
+test("buildField maps a checkbox to a boolean value", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({ type: "checkbox", key: "agree", label: "Agree" });
+  const input = created.find((n) => n.tagName === "INPUT");
+  input!.checked = true;
+  assert.deepEqual(built!.read!(), { key: "agree", value: true });
+});
+
+test("buildField reads the checked radio option (and omits an unselected group)", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const built = buildField({
+    type: "radio",
+    key: "size",
+    label: "Size",
+    values: [
+      { value: "s", label: "Small" },
+      { value: "l", label: "Large" },
+    ],
+  });
+  assert.ok(built?.read);
+  assert.equal(built!.read!(), null, "an unselected radio group is omitted from the submitted variables");
+  const radios = created.filter((n) => n.tagName === "INPUT" && n.type === "radio");
+  assert.equal(radios.length, 2);
+  radios[1].checked = true;
+  assert.deepEqual(built!.read!(), { key: "size", value: "l" }, "read() finds the checked option via querySelector('input:checked')");
+});
+
+test("renderForm submits a null-prototype variables bag (prototype-pollution safe)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const schema = {
+    components: [
+      { type: "textfield", key: "note" },
+      { type: "textfield", key: "__proto__" },
+    ],
+  };
+  let submitted: Record<string, unknown> | undefined;
+  const form = renderForm(schema, {
+    heading: "Task A",
+    onSubmit: (variables) => {
+      submitted = variables;
+    },
+  });
+  const inputs = created.filter((n) => n.tagName === "INPUT");
+  inputs[0].value = "hi";
+  inputs[1].value = "evil";
+  await form.fire("submit");
+  assert.ok(submitted);
+  assert.equal(Object.getPrototypeOf(submitted!), null, "the variables bag has a null prototype");
+  assert.equal(submitted!.note, "hi");
+  assert.equal(Object.prototype.hasOwnProperty.call(submitted!, "__proto__"), true, "an untrusted key lands as an own property");
+  assert.equal(Object.getPrototypeOf({}), Object.prototype, "no prototype was mutated");
+});
+
+test("renderForm re-enables the submit button when onSubmit rejects (retryable)", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  const form = renderForm(
+    { components: [{ type: "textfield", key: "x" }] },
+    {
+      onSubmit: () => Promise.reject(new Error("boom")),
+    },
+  );
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.ok(submit);
+  await form.fire("submit");
+  // The rejected onSubmit settles a microtask later; flush it.
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.equal(submit!.disabled, false, "a failed submit re-enables the button so the operator can retry");
+});
+
+test("renderForm wires a cancel button only when onCancel is supplied", async (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  renderForm({ components: [] }, { onSubmit: () => {} });
+  assert.equal(created.filter((n) => n.tagName === "BUTTON").length, 1, "no cancel button without onCancel");
+  created.length = 0;
+  let cancelled = false;
+  renderForm({ components: [] }, { onSubmit: () => {}, onCancel: () => (cancelled = true) });
+  const buttons = created.filter((n) => n.tagName === "BUTTON");
+  assert.equal(buttons.length, 2, "a cancel button is added when onCancel is supplied");
+  await buttons[1].fire("click");
+  assert.equal(cancelled, true, "clicking cancel invokes onCancel");
+});

package/src/runtime/browser/runtime.browser.js

@@ -1859,6 +1859,101 @@ function buildDetailForm(f, row, onSuccess) {
   return box;
 }
 
+// Build a dataGrid detail's ENGINE-declared form (ADR 0026, #457). Where
+// buildDetailForm renders a page-authored `detail.form` (fields duplicated from a
+// deployed `.form`), this resolves the row's engine `formKey` and renders the
+// AUTHORITATIVE deployed form-js schema — so one grid can render the several
+// different typed forms carried by a heterogeneous task inbox, and no page-local
+// copy can drift from the deployed form. It reuses the ONE shared form-js renderer
+// (globalThis.NanoFormJs, embedded by the shell) and the shared `/app/actions/form`
+// resolution gate + `/app/actions/complete` completion — the same seams the
+// taskInbox surface uses, no fork.
+//
+// `cfg.formKeyField` (default "form_key") names the row column carrying the engine
+// formKey; `cfg.userTaskKeyField` (default "user_task_key") names the column
+// carrying the user-task key to complete. A row with no formKey degrades to a bare
+// "Complete" button (empty variables), matching taskInbox's no-form fallback.
+/** @param {any} cfg
+ *  @param {Record<string, any>} row
+ *  @param {() => void | Promise<void>} onSuccess
+ *  @returns {HTMLElement|null}
+ */
+function buildEngineForm(cfg, row, onSuccess) {
+  if (!cfg) return null;
+  const userTaskKey = row[cfg.userTaskKeyField || "user_task_key"];
+  // Without a user-task key there is nothing to complete — render nothing rather
+  // than a dead button.
+  if (userTaskKey == null || userTaskKey === "") return null;
+  const formKey = row[cfg.formKeyField || "form_key"];
+  const box = el("div", { class: "pc-subform" });
+  const msg = el("p", { class: "njf-msg", role: "status", "aria-live": "polite" });
+  /** @param {Record<string, any>} variables */
+  const complete = (variables) =>
+    getJSON("/app/actions/complete", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ userTaskKey, variables }),
+    }).then(() => onSuccess());
+  // No renderable form → the bare completion path (parity with taskInbox).
+  const renderBare = () => {
+    const bar = el("div", { class: "njf-actions" });
+    const b = el("button", { class: "pc-btn pc-btn-sm", type: "button" }, "Complete");
+    b.addEventListener("click", async () => {
+      b.disabled = true;
+      msg.className = "njf-msg";
+      msg.textContent = "Sending\u2026";
+      try {
+        await complete(Object.create(null));
+      } catch (e) {
+        b.disabled = false;
+        msg.className = "njf-msg err";
+        msg.textContent = String(e.message || e);
+      }
+    });
+    bar.append(b);
+    box.append(bar, msg);
+  };
+  if (formKey == null || formKey === "") {
+    renderBare();
+    return box;
+  }
+  box.append(el("p", { class: "njf-text" }, "loading form\u2026"));
+  getJSON("/app/actions/form?formKey=" + encodeURIComponent(String(formKey)))
+    .then((f) => {
+      box.replaceChildren();
+      const renderer = /** @type {any} */ (globalThis).NanoFormJs;
+      if (!f || !f.schema || !renderer) {
+        renderBare();
+        return;
+      }
+      box.append(
+        renderer.renderForm(f.schema, {
+          submitLabel: "Complete",
+          /** @param {Record<string, any>} variables */
+          onSubmit: (variables) => {
+            msg.className = "njf-msg";
+            msg.textContent = "Sending\u2026";
+            // Surface completion failures to the operator (parity with the bare-completion
+            // path). Rethrow so renderForm's catch still re-enables the submit button.
+            return complete(variables).catch((e) => {
+              msg.className = "njf-msg err";
+              msg.textContent = String(e.message || e);
+              throw e;
+            });
+          },
+        }),
+        msg,
+      );
+    })
+    .catch((e) => {
+      box.replaceChildren();
+      msg.className = "njf-msg err";
+      msg.textContent = "Failed to load form: " + String(e.message || e);
+      box.append(msg);
+    });
+  return box;
+}
+
 /** @param {any} node */
 function renderDataGrid(node) {
   const p = node.props;
@@ -2162,6 +2257,11 @@ function renderDataGrid(node) {
     }
     const form = buildDetailForm(d.form, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
     if (form) box.append(form);
+    // An engine-declared form (ADR 0026/#457) sits ALONGSIDE the page-authored
+    // `detail.form`, not replacing it: a grid may render the deployed form-js schema
+    // for the row's user task instead of (or in addition to) a hand-authored copy.
+    const engineForm = buildEngineForm(d.engineForm, row, onSuccess || (() => { document.dispatchEvent(new CustomEvent("pc:refresh")); }));
+    if (engineForm) box.append(engineForm);
     return box;
   }
 
@@ -2849,4 +2949,4 @@ function boot() {
 // renderer functions / RENDERERS registry can be imported directly.
 if (typeof document !== "undefined" && document.getElementById("page")) boot();
 
-export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };
+export { RENDERERS, renderText, renderButton, renderProse, renderNav, renderAppView, navLink, sameOriginPath, wireNavBadge, applyNavBadge, teardown, fmtCellValue, gridCell, buildDetailForm, buildEngineForm, evalDetailCondition, normalizeDetailOptions, chevronToggle, setChevronOpen };

package/src/runtime/browser/runtime.engineform.test.ts

@@ -0,0 +1,158 @@
+// Unit tests for buildEngineForm (#457) — the dataGrid detail's ENGINE-declared
+// form path. Where buildDetailForm renders a page-authored `detail.form`, this
+// resolves the row's engine `formKey` via the shared `/app/actions/form` gate and
+// renders the AUTHORITATIVE deployed form-js schema with the shared renderer
+// (globalThis.NanoFormJs), completing the row's user task via
+// `/app/actions/complete`. A row with no formKey degrades to a bare completion,
+// matching the taskInbox no-form fallback.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildEngineForm } from "./runtime.browser.js";
+// Importing the shared renderer registers globalThis.NanoFormJs, which
+// buildEngineForm reads lazily when it renders a resolved schema.
+import "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+interface FetchCall {
+  url: string;
+  method: string;
+  // Parsed request JSON body (or undefined), typed loosely so a test can assert on
+  // arbitrary shapes without ceremony — mirrors the runtime's JSDoc `any` payloads.
+  body?: any;
+}
+
+/** Install a fake `fetch` that resolves each request from a route→response map. */
+function installFakeFetch(
+  handler: (url: string, opts: { method?: string; body?: string }) => { status?: number; json?: unknown },
+  calls: FetchCall[],
+): () => void {
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  const fake = (input: string | URL, opts: { method?: string; body?: string } = {}) => {
+    const url = String(input);
+    calls.push({ url, method: opts.method ?? "GET", body: opts.body ? JSON.parse(opts.body) : undefined });
+    const res = handler(url, opts);
+    const status = res.status ?? 200;
+    return Promise.resolve({
+      ok: status >= 200 && status < 300,
+      status,
+      json: () =>
+        res.json === undefined ? Promise.reject(new Error("no body")) : Promise.resolve(res.json),
+      text: () => Promise.resolve(res.json === undefined ? "" : JSON.stringify(res.json)),
+    });
+  };
+  Reflect.set(globalThis, "fetch", fake);
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  };
+}
+
+const CFG = { formKeyField: "form_key", userTaskKeyField: "user_task_key" };
+
+test("buildEngineForm renders nothing when the row has no user-task key", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildEngineForm(CFG, { form_key: "f1" }, () => {}), null);
+  assert.equal(buildEngineForm(null, { user_task_key: "u1" }, () => {}), null);
+});
+
+test("buildEngineForm resolves the row's formKey and completes with the entered variables", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  let refreshed = false;
+  const box = buildEngineForm(CFG, { form_key: "form-9", user_task_key: "ut-9" }, () => {
+    refreshed = true;
+  });
+  assert.ok(box);
+  // Let the form fetch + render settle.
+  await new Promise((r) => setTimeout(r, 0));
+  const formReq = calls.find((c) => c.url.includes("/app/actions/form"));
+  assert.ok(formReq, "the row's formKey is resolved via the shared gate");
+  assert.match(formReq!.url, /formKey=form-9/);
+  // The shared renderer built the field; fill it and submit.
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input, "the deployed form-js schema was rendered by the shared renderer");
+  input!.value = "done";
+  const form = created.find((n) => n.tagName === "FORM");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "submitting completes the user task");
+  assert.equal(completeReq!.method, "POST");
+  assert.deepEqual(completeReq!.body, { userTaskKey: "ut-9", variables: { note: "done" } });
+  assert.equal(refreshed, true, "a successful completion invokes onSuccess (grid re-poll)");
+});
+
+test("buildEngineForm surfaces a completion failure in the rendered-form path", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 500 }; // completion fails
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "form-e", user_task_key: "ut-e" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  const form = created.find((n) => n.tagName === "FORM");
+  assert.ok(form, "the deployed schema was rendered");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const msg = created.find((n) => n.className.includes("njf-msg") && n.className.includes("err"));
+  assert.ok(msg, "a failed completion is surfaced to the operator (not silent)");
+  assert.notEqual(msg!.textContent, "", "the error message element has text");
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.equal(submit!.disabled, false, "the submit button is re-enabled so the operator can retry");
+});
+
+test("buildEngineForm degrades to bare completion when the row has no formKey", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  const box = buildEngineForm(CFG, { user_task_key: "ut-2" }, () => {});
+  assert.ok(box);
+  // No form fetch — a bare "Complete" button is shown directly.
+  assert.equal(calls.length, 0, "no formKey ⇒ no form resolution request");
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button);
+  assert.equal(button!.textContent, "Complete");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "the bare button completes the task");
+  assert.equal(completeReq!.body.userTaskKey, "ut-2");
+  assert.deepEqual(completeReq!.body.variables, {}, "bare completion sends empty variables");
+});
+
+test("buildEngineForm degrades to bare completion when the formKey resolves to no form (204)", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) return { status: 204 }; // no body
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "missing", user_task_key: "ut-3" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  assert.ok(calls.some((c) => c.url.includes("/app/actions/form")), "an unresolved formKey still hits the gate");
+  const button = created.find((n) => n.tagName === "BUTTON" && n.textContent === "Complete");
+  assert.ok(button, "a 204 (no form) falls back to the bare completion button");
+});

package/src/runtime/core/modules/canonical-projections.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import type { SqliteDb } from "../host.ts";
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  eq,
+  exists,
+  lit,
+  pcol,
+  projectionRegistry,
+  type ParitySample,
+  type ReadModel,
+  when,
+  assertReadModelParity,
+} from "../read-model.ts";
+import {
+  CANONICAL_PROJECTIONS,
+  registerCanonicalProjections,
+} from "./canonical-projections.ts";
+import { INSTANCE_STATE_TABLE, InstanceStateStore } from "./instance-state-store.ts";
+import { OPEN_USER_TASKS_TABLE, OpenUserTasksStore } from "./open-user-tasks-store.ts";
+
+// This suite registers into the process-wide `projectionRegistry` singleton; clear it after every
+// test so registrations never leak into later tests and make the suite order-dependent.
+afterEach(() => {
+  projectionRegistry.clear();
+});
+
+// A read model that derives an instance's status edge PURELY from the two canonical projections:
+//   terminated → "abandoned"  (terminated wins), else open user task → "awaiting_operator", else the
+// instance's own stored status. This is the shape the downstream writer-source-inversion task derives.
+function statusEdgeModel(): ReadModel {
+  return defineReadModel({
+    name: "urban_instance_status",
+    baseTable: "instances",
+    derive: {
+      status_edge: caseWhen(
+        [
+          when(
+            exists(
+              "urban_instance_state",
+              and(eq(pcol("process_instance_key"), col("process_instance_key")), eq(pcol("state"), lit("TERMINATED"))),
+            ),
+            lit("abandoned"),
+          ),
+          when(
+            exists("urban_open_user_tasks", eq(pcol("process_instance_key"), col("process_instance_key"))),
+            lit("awaiting_operator"),
+          ),
+        ],
+        col("status"),
+      ),
+    },
+  });
+}
+
+async function withDb(fn: (db: SqliteDb) => void | Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-canonical-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  try {
+    await fn(db);
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+test("registerCanonicalProjections maps each DSL name onto its `_urban_` physical table", () => {
+  registerCanonicalProjections();
+  assert.equal(projectionRegistry.sqlTableFor("urban_open_user_tasks"), OPEN_USER_TASKS_TABLE);
+  assert.equal(projectionRegistry.sqlTableFor("urban_instance_state"), INSTANCE_STATE_TABLE);
+  // Idempotent: a second registration is a no-op, not a conflict throw.
+  assert.doesNotThrow(() => registerCanonicalProjections());
+  assert.deepEqual(
+    CANONICAL_PROJECTIONS.map((p) => p.name).sort(),
+    ["urban_instance_state", "urban_open_user_tasks"],
+  );
+});
+
+test("a defineReadModel EXISTS over both projections materialises a VIEW that reads the sidecar tables", async () => {
+  registerCanonicalProjections();
+  await withDb((db) => {
+    // Provision the two engine-truth sidecars exactly as the runtime boot path does.
+    const openTasks = new OpenUserTasksStore(db, { clock: { now: () => 0 } });
+    const instanceState = new InstanceStateStore(db, { clock: { now: () => 0 } });
+    openTasks.ensureSchema();
+    instanceState.ensureSchema();
+
+    // The base domain table the read model derives over.
+    db.exec("CREATE TABLE instances (process_instance_key TEXT, status TEXT);");
+    for (const key of ["pi-active", "pi-human", "pi-terminated", "pi-both"]) {
+      db.run("INSERT INTO instances (process_instance_key, status) VALUES (?, ?);", [key, "running"]);
+    }
+
+    // Record engine truth into the projections (the sources the VIEW derives from).
+    instanceState.recordState("pi-active", "ACTIVE");
+    instanceState.recordState("pi-human", "ACTIVE", true);
+    openTasks.syncInstance("pi-human", [{ userTaskKey: "ut-1", elementId: "Approve" }]);
+    instanceState.recordState("pi-terminated", "TERMINATED");
+    // pi-both: terminated AND has an open task — terminated must win.
+    instanceState.recordState("pi-both", "TERMINATED");
+    openTasks.syncInstance("pi-both", [{ userTaskKey: "ut-2" }]);
+
+    // Materialise the framework-derived managed VIEW and read the derived edge.
+    const model = statusEdgeModel();
+    db.exec(model.viewDdl());
+    const rows = db.all<{ process_instance_key: string; status_edge: string }>(
+      "SELECT process_instance_key, status_edge FROM urban_instance_status ORDER BY process_instance_key;",
+    );
+    const byKey = Object.fromEntries(rows.map((r) => [r.process_instance_key, r.status_edge]));
+    assert.equal(byKey["pi-active"], "running", "no terminal/human edge ⇒ the base status survives");
+    assert.equal(byKey["pi-human"], "awaiting_operator", "an open user task ⇒ awaiting_operator");
+    assert.equal(byKey["pi-terminated"], "abandoned", "TERMINATED ⇒ abandoned");
+    assert.equal(byKey["pi-both"], "abandoned", "terminated wins over waiting-on-human");
+  });
+});
+
+test("the SQLite VIEW and the TS function agree over the canonical projections (parity guard)", async () => {
+  registerCanonicalProjections();
+  const model = statusEdgeModel();
+  const samples: ParitySample[] = [
+    // Terminal edge.
+    {
+      baseRow: { process_instance_key: "pi-1", status: "running" },
+      projections: { urban_instance_state: [{ process_instance_key: "pi-1", state: "TERMINATED" }] },
+    },
+    // Wait-on-human edge.
+    {
+      baseRow: { process_instance_key: "pi-2", status: "running" },
+      projections: { urban_open_user_tasks: [{ process_instance_key: "pi-2", user_task_key: "ut-1" }] },
+    },
+    // Neither edge ⇒ the base status survives.
+    {
+      baseRow: { process_instance_key: "pi-3", status: "running" },
+      projections: {},
+    },
+    // Correlation: an open task for a DIFFERENT instance must not match.
+    {
+      baseRow: { process_instance_key: "pi-4", status: "running" },
+      projections: { urban_open_user_tasks: [{ process_instance_key: "pi-x", user_task_key: "ut-2" }] },
+    },
+    // Precedence: terminated AND open task ⇒ abandoned (terminated wins).
+    {
+      baseRow: { process_instance_key: "pi-5", status: "running" },
+      projections: {
+        urban_instance_state: [{ process_instance_key: "pi-5", state: "TERMINATED" }],
+        urban_open_user_tasks: [{ process_instance_key: "pi-5", user_task_key: "ut-3" }],
+      },
+    },
+    // A non-terminal recorded state ⇒ no terminal edge.
+    {
+      baseRow: { process_instance_key: "pi-6", status: "converging" },
+      projections: { urban_instance_state: [{ process_instance_key: "pi-6", state: "ACTIVE" }] },
+    },
+  ];
+
+  await withDb((db) => {
+    // The parity guard builds its own isolated TEMP fixtures for the base + projection tables and
+    // asserts the SQL VIEW and the compiled TS function agree for every sample — no bespoke oracle.
+    assert.doesNotThrow(() => assertReadModelParity(model, db, samples));
+  });
+});
+
+test("the parity guard catches a divergence between the two backends", async () => {
+  registerCanonicalProjections();
+  const model = statusEdgeModel();
+  // Feed the guard's SQL side a sample, but hand a mutated TS function that disagrees, to prove the
+  // guard is actually comparing the two backends (not trivially passing).
+  const mutated: ReadModel = { ...model, fnFor: () => () => "WRONG" };
+  await withDb((db) => {
+    assert.throws(
+      () =>
+        assertReadModelParity(mutated, db, [
+          {
+            baseRow: { process_instance_key: "pi-1", status: "running" },
+            projections: { urban_instance_state: [{ process_instance_key: "pi-1", state: "TERMINATED" }] },
+          },
+        ]),
+      /parity mismatch/,
+    );
+  });
+});

package/src/runtime/core/modules/canonical-projections.ts

@@ -0,0 +1,38 @@
+// canonical-projections — register the framework's canonical engine-truth projections under their
+// stable DSL names (ADR 0065, proposal point #1). This is the concrete use of the projection-name
+// seam the read-model primitive established (`projectionRegistry.register({ name, sqlTable })`): it
+// maps each unprefixed DSL name a `defineReadModel(...)` `exists(...)` reads
+// (`urban_open_user_tasks`, `urban_instance_state`) onto its `_urban_`-prefixed physical sidecar
+// table, so the SQL backend's `EXISTS` compiles against the real table while the domain model / DB
+// Manager never sees it.
+//
+// Registration is idempotent (the registry no-ops a matching re-register), so calling this on every
+// worker mount — the boot path in `workers.ts` — is safe. It is decoupled from schema provisioning:
+// a read model must be able to reference these projections by name even in a process/app that has no
+// datasource to provision the physical tables into.
+
+import {
+  INSTANCE_STATE_PROJECTION,
+  INSTANCE_STATE_TABLE,
+} from "./instance-state-store.ts";
+import {
+  OPEN_USER_TASKS_PROJECTION,
+  OPEN_USER_TASKS_TABLE,
+} from "./open-user-tasks-store.ts";
+import { type ProjectionRegistry, projectionRegistry } from "../read-model.ts";
+
+/** The canonical projection name → physical `_urban_` table mappings this task owns. */
+export const CANONICAL_PROJECTIONS: ReadonlyArray<{ readonly name: string; readonly sqlTable: string }> = [
+  { name: OPEN_USER_TASKS_PROJECTION, sqlTable: OPEN_USER_TASKS_TABLE },
+  { name: INSTANCE_STATE_PROJECTION, sqlTable: INSTANCE_STATE_TABLE },
+];
+
+/**
+ * Register the canonical engine-truth projections in a {@link ProjectionRegistry} (defaults to the
+ * process-wide `projectionRegistry`), so a `defineReadModel(...)` authored anywhere can
+ * `exists("urban_open_user_tasks", …)` / `exists("urban_instance_state", …)` and have the SQL backend
+ * resolve them to the `_urban_`-prefixed physical tables. Idempotent.
+ */
+export function registerCanonicalProjections(registry: ProjectionRegistry = projectionRegistry): void {
+  for (const projection of CANONICAL_PROJECTIONS) registry.register(projection);
+}

package/src/runtime/core/modules/formjs.gen.ts

@@ -0,0 +1,6 @@
+// @generated by scripts/gen-runtime.mjs — DO NOT EDIT.
+// Source: src/runtime/browser/formjs.browser.js (the shared, type-checked/linted/tested
+// form-js renderer). Regenerate with `npm run gen:runtime`; CI enforces this file
+// is byte-identical to a fresh generation via `git diff --exit-code` (npm run check:runtime).
+
+export const FORMJS_JS: string = "// @ts-check\n// ── Shared, XSS-safe form-js schema renderer (ADR 0026, extended by #457) ─────\n// This is the ONE client implementation of \"render a deployed `.form`'s form-js\n// schema and collect its field values\", shared verbatim by BOTH:\n//   • the `taskInbox` surface (surfaces.ts `inboxPage`), and\n//   • the pages `dataGrid` engine-form detail (runtime.browser.js).\n// It used to live inline in surfaces.ts; factoring it here means the two surfaces\n// can never fork the renderer or drift on how a form-js component maps to an input\n// and its submitted value.\n//\n// Like the rest of the browser runtime it is authored/type-checked/linted/tested\n// as real source and served as a generated string artifact (formjs.gen.ts, emitted\n// by scripts/gen-runtime.mjs). It performs NO DOM access at load — every DOM touch\n// is inside a function — so it is import-safe under Node/Deno for unit testing.\n//\n// SECURITY: every value the engine returns is placed via textContent / setAttribute\n// (never innerHTML), so nothing in the form schema can inject markup. The submitted\n// `variables` bag is null-prototype so an engine-supplied component key of\n// `__proto__`/`constructor` lands as a plain own property and can never mutate a\n// prototype (prototype-pollution class).\n\n/** Create an element, setting attributes via setAttribute and text via textContent only.\n * @param {string} tag\n * @param {Record<string, string>} [attrs]\n * @param {string} [text]\n * @returns {any}\n */\nfunction fjEl(tag, attrs, text) {\n  const e = document.createElement(tag);\n  if (attrs) for (const k in attrs) e.setAttribute(k, attrs[k]);\n  if (text != null) e.textContent = text;\n  return e;\n}\n\n/** A plain type=\"button\" with an optional click handler.\n * @param {string} label\n * @param {(() => void) | null} [onClick]\n * @returns {any}\n */\nfunction fjBtn(label, onClick) {\n  const b = document.createElement(\"button\");\n  b.type = \"button\";\n  b.textContent = label;\n  if (onClick) b.addEventListener(\"click\", onClick);\n  return b;\n}\n\n/** Build one form-js component into its field element and (for keyed inputs) a reader\n * that returns the entered `{ key, value }` or null when blank. Static (keyless)\n * components render as inert text; layout-only components are skipped (null).\n * @param {any} c\n * @returns {{ field: any, read?: () => ({ key: string, value: any } | null) } | null}\n */\nfunction buildField(c) {\n  const type = c && c.type;\n  // Static (keyless) components: show text as a paragraph, ignore layout-only ones.\n  if (type === \"text\") {\n    return { field: fjEl(\"p\", { class: \"njf-text\" }, typeof c.text === \"string\" ? c.text : \"\") };\n  }\n  const key = c && c.key;\n  if (!key) return null;\n  const wrap = fjEl(\"div\", { class: \"njf-field\" });\n  const label = typeof c.label === \"string\" && c.label ? c.label : key;\n  if (type === \"checkbox\") {\n    const input = document.createElement(\"input\");\n    input.type = \"checkbox\";\n    const lab = fjEl(\"label\", {});\n    lab.appendChild(input);\n    lab.appendChild(document.createTextNode(\" \" + label));\n    wrap.appendChild(lab);\n    return { field: wrap, read: () => ({ key, value: input.checked }) };\n  }\n  const labelEl = fjEl(\"label\", {}, label);\n  wrap.appendChild(labelEl);\n  let input;\n  if (type === \"textarea\") {\n    input = document.createElement(\"textarea\");\n  } else if (type === \"select\") {\n    input = document.createElement(\"select\");\n    input.appendChild(fjEl(\"option\", { value: \"\" }, \"\\u2014\"));\n    for (const o of Array.isArray(c.values) ? c.values : []) {\n      input.appendChild(fjEl(\"option\", { value: String(o.value) }, String(o.label != null ? o.label : o.value)));\n    }\n  } else if (type === \"radio\") {\n    const name = \"r\" + Math.random().toString(36).slice(2);\n    const group = fjEl(\"div\", {});\n    for (const o of Array.isArray(c.values) ? c.values : []) {\n      const rlab = fjEl(\"label\", {});\n      const r = document.createElement(\"input\");\n      r.type = \"radio\";\n      r.name = name;\n      r.value = String(o.value);\n      rlab.appendChild(r);\n      rlab.appendChild(document.createTextNode(\" \" + String(o.label != null ? o.label : o.value)));\n      group.appendChild(rlab);\n    }\n    wrap.appendChild(group);\n    return {\n      field: wrap,\n      read: () => {\n        const sel = group.querySelector(\"input:checked\");\n        return sel ? { key, value: sel.value } : null;\n      },\n    };\n  } else {\n    input = document.createElement(\"input\");\n    input.type = type === \"number\" ? \"number\" : type === \"datetime\" ? \"datetime-local\" : \"text\";\n  }\n  // Associate the label with the input (for/id) so screen readers announce it on focus.\n  const fieldId = \"f\" + Math.random().toString(36).slice(2);\n  input.id = fieldId;\n  labelEl.setAttribute(\"for\", fieldId);\n  wrap.appendChild(input);\n  const isNumber = type === \"number\";\n  return {\n    field: wrap,\n    read: () => {\n      const raw = input.value;\n      if (raw === \"\" || raw == null) return null;\n      if (isNumber) {\n        const n = Number(raw);\n        // A non-numeric value in a number field is only reachable via tampering (the browser\n        // blanks invalid type=number input). Treat it as absent rather than silently submitting\n        // NaN, which JSON.stringify serializes as null — quietly changing the submitted value.\n        return Number.isFinite(n) ? { key, value: n } : null;\n      }\n      return { key, value: raw };\n    },\n  };\n}\n\n/**\n * Render a form-js schema into a `<form>` element with a submit + optional cancel.\n * On submit it assembles every keyed field's value into one null-prototype\n * `variables` bag and calls `opts.onSubmit(variables)`; a rejected submit re-enables\n * the button so the operator can retry. `opts.onCancel`, when supplied, wires a\n * cancel button.\n * @param {any} schema the parsed form-js document (`{ components: [...] }`)\n * @param {{ heading?: string, submitLabel?: string, cancelLabel?: string,\n *           onSubmit: (variables: Record<string, any>) => (void | Promise<void>),\n *           onCancel?: () => void }} opts\n * @returns {any} the built <form> element\n */\nfunction renderForm(schema, opts) {\n  const form = document.createElement(\"form\");\n  form.className = \"njf-form\";\n  if (opts.heading) form.appendChild(fjEl(\"h2\", { class: \"njf-heading\" }, opts.heading));\n  const components = schema && Array.isArray(schema.components) ? schema.components : [];\n  /** @type {Array<() => ({ key: string, value: any } | null)>} */\n  const inputs = [];\n  for (const c of components) {\n    const built = buildField(c);\n    if (!built) continue;\n    form.appendChild(built.field);\n    if (built.read) inputs.push(built.read);\n  }\n  const submit = fjBtn(opts.submitLabel || \"Submit\", null);\n  submit.type = \"submit\";\n  const bar = fjEl(\"div\", { class: \"njf-actions\" });\n  bar.appendChild(submit);\n  if (opts.onCancel) bar.appendChild(fjBtn(opts.cancelLabel || \"Cancel\", opts.onCancel));\n  form.appendChild(bar);\n  form.addEventListener(\"submit\", (e) => {\n    e.preventDefault();\n    // Null-prototype: field keys come from the engine-supplied form schema. A component\n    // keyed '__proto__'/'constructor' must land as a plain own property (and round-trip\n    // through JSON), never mutate a prototype — no prototype pollution in the page runtime.\n    const variables = Object.create(null);\n    for (const read of inputs) {\n      const kv = read();\n      if (kv) variables[kv.key] = kv.value;\n    }\n    submit.disabled = true;\n    Promise.resolve()\n      .then(() => opts.onSubmit(variables))\n      .catch(() => {\n        submit.disabled = false;\n      });\n  });\n  return form;\n}\n\n\n// Expose the renderer as a browser global so both self-contained page bundles can\n// reach the ONE implementation without importing it: the taskInbox page embeds this\n// module inline and the pages shell does the same before loading the ES-module\n// runtime, which reads `globalThis.NanoFormJs` lazily when it renders an engine form.\n// Guarded so importing under Node/Deno for tests is a harmless no-op-ish assignment.\nif (typeof globalThis !== \"undefined\") {\n  /** @type {any} */ (globalThis).NanoFormJs = { buildField, renderForm };\n}\n";