@nanobpm/urban 0.79.0 → 0.81.0

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

@@ -14,6 +14,7 @@ import {
 } from "./gateway.ts";
 import { currentJobContext } from "../execContext.ts";
 import { isAbsolutePath } from "../../../toolkit/artifact.ts";
+import { SQL_IDENT, isReservedObjectName } from "../read-model.ts";
 
 export function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -95,7 +96,7 @@ export function makeProvenanceRecorder(
   source: string,
 ): InsertObserver {
   return (table, pk) => {
-    if (table.startsWith("_urban_") || table.startsWith("_nano_") || table.startsWith("sqlite_")) {
+    if (isReservedObjectName(table)) {
       return;
     }
     const ctx = currentJobContext();
@@ -153,9 +154,11 @@ export async function openSqliteSource(
   return db;
 }
 
-/** A safe unquoted SQL identifier. Table/column names are interpolated directly into SQL,
- * so reject anything that isn't a plain identifier to prevent invalid SQL / injection. */
-const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A safe unquoted SQL identifier check. Table/column names are interpolated directly into SQL, so
+ * reject anything that isn't a plain identifier to prevent invalid SQL / injection. The regex itself
+ * is the runtime-wide single source of truth in `read-model.ts` (No Drift Surfaces — a divergent copy
+ * could let table validation and read-model/manifest validation disagree); we reuse it here rather than
+ * re-declaring it, keeping this module's own error message. */
 function assertSqlIdent(kind: string, name: string): string {
   if (!SQL_IDENT.test(name)) {
     throw new Error(`invalid ${kind} "${name}": must match ${SQL_IDENT.source}`);

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";

package/src/runtime/core/modules/forms.test.ts

@@ -0,0 +1,122 @@
+// The shared engine-form server seams (ADR 0026, #457): the /api/form resolution
+// gate and the user-task completion, factored out of surfaces.ts so the taskInbox
+// surface and the pages grid detail share ONE implementation. These tests pin the
+// gate's contract directly (both callers depend on it identically).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { EngineClient, FormSchema } from "../host.ts";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.ts";
+
+function formEngine(getForm: EngineClient["getForm"]): Pick<EngineClient, "getForm"> {
+  return { getForm };
+}
+
+test("resolveFormResponse 400s when neither identifier is present (empty/whitespace = absent)", async () => {
+  const engine = formEngine(async () => {
+    throw new Error("getForm must not be called when no identifier is present");
+  });
+  for (const [formKey, formId] of [
+    [undefined, undefined],
+    ["", ""],
+    ["   ", undefined],
+    [undefined, "\t"],
+  ] as const) {
+    const res = await resolveFormResponse(engine, formKey, formId);
+    assert.equal(res.status, 400);
+  }
+});
+
+test("resolveFormResponse passes raw identifiers through to getForm and returns its schema", async () => {
+  const seen: { formKey?: string; formId?: string }[] = [];
+  const schema: FormSchema = { formKey: "form-1", schema: { components: [] } };
+  const engine = formEngine(async (input) => {
+    seen.push(input);
+    return schema;
+  });
+  const res = await resolveFormResponse(engine, "form-1", undefined);
+  assert.equal(res.status, 200);
+  assert.ok(res.body);
+  assert.deepEqual(JSON.parse(res.body), schema);
+  // A blank formKey is passed through unchanged so getForm can fall back to formId
+  // (that fallback is getForm's single responsibility, not the gate's).
+  await resolveFormResponse(engine, "", "the-form-id");
+  assert.deepEqual(seen, [
+    { formKey: "form-1", formId: undefined },
+    { formKey: "", formId: "the-form-id" },
+  ]);
+});
+
+test("resolveFormResponse 204s (no body) when getForm can't resolve a form", async () => {
+  const res = await resolveFormResponse(formEngine(async () => null), "missing", undefined);
+  assert.equal(res.status, 204);
+  assert.equal(res.body, "");
+});
+
+test("completeUserTaskResponse completes the task with the submitted variables", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask(key, variables) {
+      calls.push({ key, variables });
+    },
+  };
+  const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-7", variables: { a: 1 } }));
+  assert.equal(res.status, 200);
+  assert.ok(res.body);
+  assert.deepEqual(JSON.parse(res.body), { ok: true });
+  assert.deepEqual(calls, [{ key: "ut-7", variables: { a: 1 } }]);
+});
+
+test("completeUserTaskResponse 400s on a missing userTaskKey or malformed body — no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  assert.equal((await completeUserTaskResponse(engine, JSON.stringify({ variables: {} }))).status, 400);
+  assert.equal((await completeUserTaskResponse(engine, "{ not json")).status, 400);
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse 400s on a non-object JSON body — no crash, no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  // `JSON.parse("null")` returns `null`, and a bare scalar/array parses to a
+  // non-record — reading `.userTaskKey` off those must 400, never throw a 500.
+  for (const bodyText of ["null", "123", '"a string"', "true", "[]"]) {
+    const res = await completeUserTaskResponse(engine, bodyText);
+    assert.equal(res.status, 400, `body=${bodyText} should 400`);
+  }
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse 400s on non-object variables — no completion attempted", async () => {
+  let called = false;
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask() {
+      called = true;
+    },
+  };
+  for (const variables of [1, "x", true, [], null]) {
+    const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-1", variables }));
+    assert.equal(res.status, 400, `variables=${JSON.stringify(variables)} should 400`);
+  }
+  assert.equal(called, false);
+});
+
+test("completeUserTaskResponse allows an omitted variables (undefined)", async () => {
+  const calls: { key: string; variables?: Record<string, unknown> }[] = [];
+  const engine: Pick<EngineClient, "completeUserTask"> = {
+    async completeUserTask(key, variables) {
+      calls.push({ key, variables });
+    },
+  };
+  const res = await completeUserTaskResponse(engine, JSON.stringify({ userTaskKey: "ut-2" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(calls, [{ key: "ut-2", variables: undefined }]);
+});

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

@@ -0,0 +1,67 @@
+// Shared engine-form plumbing (ADR 0026, extended to the pages surface).
+//
+// The `taskInbox` surface pioneered rendering a user task's *engine-declared*
+// form: resolve the task's `formKey`/`formId` via `EngineClient.getForm(...)`,
+// render the returned form-js schema client-side, and post the entered values
+// as the completion `variables`. The pages `dataGrid` engine-form detail (#457)
+// needs the SAME two server seams — the `/api/form` resolution gate and the
+// task-completion endpoint — so they live here ONCE and are wired by both
+// `surfaces.ts` (taskInbox) and `pages.ts` (the grid detail). No fork: a single
+// resolution gate, and the `host.ts` `presentFormIdentifier` presence rule stays
+// the single source of truth for "was an identifier provided".
+
+import type { EngineClient, HttpResponse } from "../host.ts";
+import { presentFormIdentifier } from "../host.ts";
+import { isRecord } from "../guards.ts";
+import { json, noContent } from "../router.ts";
+
+/**
+ * The shared `/api/form` resolution gate. Rejects only when *neither* identifier
+ * is present — presence follows getForm's canonical rule (`presentFormIdentifier`:
+ * empty/whitespace = absent) so a whitespace-only `?formKey=   ` 400s here instead
+ * of slipping past a raw truthiness check and returning a spurious 204. The raw
+ * values are passed through unchanged — resolving a blank key to its `formId`
+ * fallback is getForm's single responsibility. A form that can't be resolved
+ * returns 204 so the client renders the no-form fallback rather than erroring.
+ */
+export async function resolveFormResponse(
+  engine: Pick<EngineClient, "getForm">,
+  formKey: string | undefined,
+  formId: string | undefined,
+): Promise<HttpResponse> {
+  if (!presentFormIdentifier(formKey) && !presentFormIdentifier(formId))
+    return json({ error: "formKey or formId required" }, 400);
+  const form = await engine.getForm({ formKey, formId });
+  if (!form) return noContent();
+  return json(form);
+}
+
+/**
+ * The shared user-task completion endpoint. Parses `{ userTaskKey, variables }`
+ * from the request body and completes the task via `EngineClient.completeUserTask`.
+ * A body that isn't a JSON object (`null`, a scalar, an array) 400s instead of
+ * throwing a 500; a missing/blank `userTaskKey` 400s; a malformed body 400s; a
+ * present but non-object `variables` (number, string, array, `null`) 400s so the
+ * completion contract stays well-defined at this shared seam. Used by both the
+ * taskInbox surface and the pages grid's engine-form detail so the completion
+ * contract can't drift between them.
+ */
+export async function completeUserTaskResponse(
+  engine: Pick<EngineClient, "completeUserTask">,
+  bodyText: string,
+): Promise<HttpResponse> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bodyText || "{}");
+  } catch {
+    return json({ error: "invalid JSON body" }, 400);
+  }
+  if (!isRecord(parsed)) return json({ error: "invalid JSON body" }, 400);
+  const { userTaskKey, variables } = parsed;
+  if (typeof userTaskKey !== "string" || !userTaskKey)
+    return json({ error: "userTaskKey required" }, 400);
+  if (variables !== undefined && !isRecord(variables))
+    return json({ error: "variables must be a JSON object" }, 400);
+  await engine.completeUserTask(userTaskKey, variables);
+  return json({ ok: true });
+}

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

@@ -13,6 +13,7 @@
 //   const o = await orders.get(id);
 
 import type { SqliteDb } from "../host.ts";
+import { RESERVED_OBJECT_PREFIXES } from "../read-model.ts";
 
 export type Row = Record<string, unknown>;
 
@@ -264,11 +265,13 @@ class SqliteGateway implements DataSource {
     // Exclude SQLite internals (`sqlite_%`) and Nano's own bookkeeping tables (`_urban_%` /
     // `_nano_%`, e.g. the migrations ledger): neither is a user/domain object, so they must
     // never surface in the domain model, DB Manager, or forms. The same exclusions apply to
-    // views.
+    // views. The prefix set is derived from RESERVED_OBJECT_PREFIXES (No Drift Surfaces) so this
+    // read-side filter cannot diverge from the write-side skip / manifest-validation rejection.
+    const reservedClause = RESERVED_OBJECT_PREFIXES.map(
+      (p) => `AND name NOT LIKE '${p.replace(/_/g, "\\_")}%' ESCAPE '\\'`,
+    ).join(" ");
     const tables = this.#db.all<{ name: string; type: string }>(
-      "SELECT name, type FROM sqlite_master WHERE type IN ('table','view') " +
-        "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '\\_urban\\_%' ESCAPE '\\' " +
-        "AND name NOT LIKE '\\_nano\\_%' ESCAPE '\\' ORDER BY name",
+      `SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ${reservedClause} ORDER BY name`,
     );
     const out: TableMeta[] = [];
     for (const t of tables) {

package/src/runtime/core/modules/gen-artifacts.test.ts

@@ -0,0 +1,41 @@
+// Drift gate for the generated browser-runtime artifacts, enforced INSIDE the test
+// suite (which CI already runs) rather than in a workflow step. The browser runtime
+// and the shared form-js renderer are authored as real, type-checked/linted/tested
+// source (runtime.browser.js, formjs.browser.js) and emitted to committed string
+// artifacts (runtime.gen.ts, formjs.gen.ts) by scripts/gen-runtime.mjs. If either
+// checked-in artifact drifts from a fresh generation, the served bundle no longer
+// matches its source and a stale renderer could ship — so we regenerate-and-compare
+// here and fail on any drift, the same guarantee `npm run check:runtime` gives.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Resolve the generator relative to THIS file (cwd varies: `npm test` runs from the
+// package root, but a runner may invoke us from elsewhere).
+const GEN_SCRIPT = fileURLToPath(new URL("../../../../scripts/gen-runtime.mjs", import.meta.url));
+
+function hasStderr(e: unknown): e is { stderr?: unknown; stdout?: unknown } {
+  return typeof e === "object" && e !== null && ("stderr" in e || "stdout" in e);
+}
+
+test("the committed runtime + formjs artifacts are byte-identical to a fresh generation (no drift)", () => {
+  // `--check` regenerates both artifacts in-memory and diffs them against the
+  // committed files, exiting non-zero (with a diagnostic) on any drift. Spawn the real
+  // `node` binary explicitly: under `deno test`, `process.execPath` is the `deno`
+  // binary, which cannot run this Node script — mirrors the pages.test.ts node --check
+  // guard. Regenerate + commit locally with `npm run gen:runtime -w packages/urban`.
+  let ok = true;
+  let diagnostic = "";
+  try {
+    execFileSync("node", [GEN_SCRIPT, "--check"], { stdio: "pipe" });
+  } catch (err) {
+    ok = false;
+    diagnostic = hasStderr(err) ? `${String(err.stdout ?? "")}${String(err.stderr ?? "")}` : String(err);
+  }
+  assert.ok(
+    ok,
+    `a committed generated artifact is stale — run \`npm run gen:runtime -w packages/urban\` and commit the result.\n${diagnostic}`,
+  );
+});

package/src/runtime/core/modules/instance-status-read-model.ts

@@ -0,0 +1,156 @@
+// instance-status-read-model — the DERIVED half of the `instanceTracking` writer→source inversion
+// (ADR 0065, surface #1; #439-L1 / #318). The reconciler used to WRITE the derivable status edges
+// (`onTerminated.set` / `onWaitingHuman.set` applied as `table.update` patches); that stored-derived
+// value tore from its inputs (nano-workforce#422: an answered escalation still showed a stale ⚠).
+//
+// After the inversion, the reconciler is a SOURCE — it feeds engine truth into the canonical
+// projections (`urban_instance_state`, `urban_open_user_tasks`, ADR 0065 #1) — and the two derivable
+// status edges are DERIVED here, once, in the closed `defineReadModel` expression DSL:
+//
+//   terminal edge:      EXISTS(urban_instance_state    WHERE process_instance_key = base.<keyField>
+//                                                        AND state = 'TERMINATED')  -> onTerminated value
+//   wait-on-human edge: EXISTS(urban_open_user_tasks   WHERE process_instance_key = base.<keyField>)
+//                                                                                   -> onWaitingHuman value
+//
+// authored ONCE and compiled to BOTH the SQLite VIEW and the in-process TS function (surface #2 is
+// closed by the two-backend compiler). Because a derived edge is recomputed on every read over the
+// LIVE projections, a re-escalation after an answer re-flips by construction and #422 cannot recur:
+// once `OpenUserTasksStore.syncInstance` retires the answered task, the `EXISTS` goes false on the
+// next read — no stored column to leave stale.
+
+import type { InstanceTracking } from "../manifest.ts";
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  eq,
+  type Expr,
+  exists,
+  lit,
+  not,
+  pcol,
+  type ReadModel,
+  type WhenClause,
+  when,
+} from "../read-model.ts";
+import { INSTANCE_STATE_PROJECTION } from "./instance-state-store.ts";
+import { OPEN_USER_TASKS_PROJECTION } from "./open-user-tasks-store.ts";
+
+/** The engine-truth terminal lifecycle state the terminal edge keys on (mirrors
+ *  `ProcessInstanceState`'s `TERMINATED`). Reconciled only on `TERMINATED` — never `COMPLETED`, whose
+ *  terminal row-write the app's own finalize worker owns — exactly as the pre-inversion reconciler was. */
+export const TERMINATED_STATE = "TERMINATED";
+
+/** The default derived-status column name a binding's read-model VIEW exposes. Distinct from the base
+ *  `statusField` on purpose: the managed VIEW re-exports `base.*` (so pages keep every base column),
+ *  and SQLite lets the base column win over a same-named derived alias — so the EFFECTIVE (derived)
+ *  status is surfaced under its own column, which the operator page reads instead of the stored one.
+ *  A binding may override it via `readModel.statusColumn`. */
+export const DEFAULT_DERIVED_STATUS_COLUMN = "derived_status";
+
+/** The default managed-VIEW name for a binding: `<table>__tracking`. Distinct from the base table
+ *  (SQLite forbids a VIEW and a table sharing a name). An app with more than one binding on the same
+ *  base table must give each a distinct `readModel.view`. */
+export function defaultInstanceTrackingViewName(table: string): string {
+  return `${table}__tracking`;
+}
+
+/** `EXISTS(urban_instance_state WHERE process_instance_key = base.<keyField> AND state = 'TERMINATED')`
+ *  — the terminal edge, derived over the canonical instance-state projection. Authored once; compiles
+ *  to both the SQLite VIEW `EXISTS` and the TS `projections["urban_instance_state"].some(...)`. */
+export function terminatedEdgeExpr(keyField: string): Expr {
+  return exists(
+    INSTANCE_STATE_PROJECTION,
+    and(eq(pcol("process_instance_key"), col(keyField)), eq(pcol("state"), lit(TERMINATED_STATE))),
+  );
+}
+
+/** `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.<keyField>)` — the wait-on-human
+ *  edge, derived over the canonical open-user-tasks projection (an instance is parked on a human iff it
+ *  has an open user task). Authored once; compiles to both backends. */
+export function waitingHumanEdgeExpr(keyField: string): Expr {
+  return exists(OPEN_USER_TASKS_PROJECTION, eq(pcol("process_instance_key"), col(keyField)));
+}
+
+/**
+ * The effective-status derivation for one binding, in the closed expression DSL:
+ *
+ *   CASE
+ *     WHEN <terminated>                    THEN <onTerminated.set[statusField]>   -- terminal wins
+ *     WHEN <waiting-on-human> AND NOT <terminated> THEN <onWaitingHuman.set[statusField]>
+ *     ELSE base.<statusField>              -- the worker-owned / business-outcome transient status
+ *   END
+ *
+ * Precedence (terminated over waiting-human) is preserved: the terminal `WHEN` is emitted first, and
+ * the waiting `WHEN` is additionally guarded by `NOT <terminated>` so it is correct even when the two
+ * patches touch disjoint columns. When a binding's patch does not set the `statusField` (it reconciles
+ * only secondary columns), that edge contributes no `WHEN` and the derived status passes the stored
+ * value through — a derived read model never re-introduces a stored derivable write.
+ */
+export function deriveInstanceStatusExpr(binding: InstanceTracking, statusField: string): Expr {
+  const terminated = terminatedEdgeExpr(binding.keyField);
+  const whens: WhenClause[] = [];
+
+  const terminalStatus = patchValueForColumn(binding.onTerminated?.set, statusField);
+  if (terminalStatus !== undefined) {
+    whens.push(when(terminated, lit(terminalStatus)));
+  }
+
+  const waitingStatus = patchValueForColumn(binding.onWaitingHuman?.set, statusField);
+  if (waitingStatus !== undefined) {
+    whens.push(when(and(waitingHumanEdgeExpr(binding.keyField), not(terminated)), lit(waitingStatus)));
+  }
+
+  // No edge touches the status column ⇒ the derived status is exactly the stored transient (no CASE).
+  return whens.length > 0 ? caseWhen(whens, col(statusField)) : col(statusField);
+}
+
+/** Read the patch value a `*.set` map assigns to the status COLUMN, matching the key case-insensitively.
+ *  SQL column identifiers fold case (SQLite), but a JS `set[statusField]` lookup is case-sensitive, so a
+ *  binding with `statusField: "Status"` and `onTerminated.set: { status: "abandoned" }` would emit no
+ *  terminal `WHEN` and silently fall through to the base column. Fold the comparison so the derivation
+ *  matches the column the equivalent SQL UPDATE would have addressed. */
+function patchValueForColumn(set: unknown, statusField: string): string | number | boolean | null | undefined {
+  if (set === null || typeof set !== "object") return undefined;
+  const folded = statusField.toLowerCase();
+  for (const [k, v] of Object.entries(set)) {
+    if (k.toLowerCase() !== folded) continue;
+    if (v === undefined) return undefined;
+    if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") return v;
+    return undefined;
+  }
+  return undefined;
+}
+
+/** The managed-VIEW name + derived-status column a binding's read model uses (config overrides applied). */
+export function instanceTrackingReadModelTarget(binding: InstanceTracking): {
+  readonly view: string;
+  readonly statusColumn: string;
+} {
+  return {
+    view: binding.readModel?.view ?? defaultInstanceTrackingViewName(binding.table),
+    statusColumn: binding.readModel?.statusColumn ?? DEFAULT_DERIVED_STATUS_COLUMN,
+  };
+}
+
+/**
+ * Build the derived read model for one `instanceTracking` binding: a managed VIEW over the binding's
+ * base table that re-exports `base.*` plus one derived `statusColumn` computed by
+ * {@link deriveInstanceStatusExpr} over the canonical projections. Returns `undefined` when the binding
+ * declares no `statusField` (there is no single status column to derive — the projections still get fed,
+ * but nothing well-defined can be projected as "the effective status").
+ *
+ * The two backends (SQLite VIEW select-list + in-process TS function) fall out of the one AST, so they
+ * cannot drift; `assertReadModelParity` verifies it in tests.
+ */
+export function defineInstanceTrackingReadModel(binding: InstanceTracking): ReadModel | undefined {
+  const statusField = binding.statusField;
+  if (typeof statusField !== "string" || statusField.length === 0) return undefined;
+  const { view, statusColumn } = instanceTrackingReadModelTarget(binding);
+  return defineReadModel({
+    name: view,
+    baseTable: binding.table,
+    derive: { [statusColumn]: deriveInstanceStatusExpr(binding, statusField) },
+  });
+}