@nanobpm/urban 0.78.0 → 0.80.0

package/dist/runtime/core/modules/canonical-projections.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectionRegistry } from "../read-model.ts";
+/** The canonical projection name → physical `_urban_` table mappings this task owns. */
+export declare const CANONICAL_PROJECTIONS: ReadonlyArray<{
+    readonly name: string;
+    readonly sqlTable: string;
+}>;
+/**
+ * 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 declare function registerCanonicalProjections(registry?: ProjectionRegistry): void;

package/dist/runtime/core/modules/canonical-projections.js

@@ -0,0 +1,30 @@
+// 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.js";
+import { OPEN_USER_TASKS_PROJECTION, OPEN_USER_TASKS_TABLE, } from "./open-user-tasks-store.js";
+import { projectionRegistry } from "../read-model.js";
+/** The canonical projection name → physical `_urban_` table mappings this task owns. */
+export const CANONICAL_PROJECTIONS = [
+    { 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) {
+    for (const projection of CANONICAL_PROJECTIONS)
+        registry.register(projection);
+}

package/dist/runtime/core/modules/formjs.gen.d.ts

@@ -0,0 +1 @@
+export declare const FORMJS_JS: string;

package/dist/runtime/core/modules/formjs.gen.js

@@ -0,0 +1,5 @@
+// @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 = "// @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/dist/runtime/core/modules/forms.d.ts

@@ -0,0 +1,22 @@
+import type { EngineClient, HttpResponse } from "../host.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 declare function resolveFormResponse(engine: Pick<EngineClient, "getForm">, formKey: string | undefined, formId: string | undefined): Promise<HttpResponse>;
+/**
+ * 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 declare function completeUserTaskResponse(engine: Pick<EngineClient, "completeUserTask">, bodyText: string): Promise<HttpResponse>;

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

@@ -0,0 +1,59 @@
+// 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 { presentFormIdentifier } from "../host.js";
+import { isRecord } from "../guards.js";
+import { json, noContent } from "../router.js";
+/**
+ * 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, formKey, formId) {
+    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, bodyText) {
+    let parsed;
+    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/dist/runtime/core/modules/instance-state-store.d.ts

@@ -0,0 +1,50 @@
+import type { ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb } from "../host.ts";
+import { type Clock } from "./lineage-store.ts";
+/** The instance-state projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export declare const INSTANCE_STATE_TABLE = "_urban_instance_state";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link INSTANCE_STATE_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_instance_state WHERE process_instance_key = base.process_instance_key)`. */
+export declare const INSTANCE_STATE_PROJECTION = "urban_instance_state";
+/**
+ * The canonical instance-state DDL — the single source of truth applied by
+ * {@link InstanceStateStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/007_urban_instance_state.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `process_instance_key` (one canonical state per instance) so a
+ * re-record upserts in place and is idempotent. `waiting_on_human` is 0/1 (SQLite has no boolean).
+ */
+export declare const INSTANCE_STATE_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS _urban_instance_state (\n  process_instance_key TEXT NOT NULL,\n  state                TEXT NOT NULL,\n  waiting_on_human     INTEGER NOT NULL DEFAULT 0,\n  updated_at           TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key)\n);";
+export interface InstanceStateStoreOptions {
+    readonly clock?: Clock;
+}
+/** One projected instance-state row, as {@link InstanceStateStore.getState} returns it. */
+export interface InstanceStateRow {
+    readonly processInstanceKey: string;
+    readonly state: ProcessInstanceState;
+    readonly waitingOnHuman: boolean;
+}
+/**
+ * The per-source sidecar behind the `urban_instance_state` projection. A thin, idempotent
+ * persistence + query layer over the engine's per-instance lifecycle truth.
+ */
+export declare class InstanceStateStore {
+    #private;
+    constructor(db: SqliteDb, options?: InstanceStateStoreOptions);
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/007_urban_instance_state.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema(): void;
+    /**
+     * Record an instance's canonical engine lifecycle state (and whether it is waiting on a human),
+     * upserting the single row keyed by `processInstanceKey`. Idempotent: re-recording the same
+     * `(state, waitingOnHuman)` is a no-op (returns `false`). A blank `processInstanceKey` is ignored.
+     */
+    recordState(processInstanceKey: string, state: ProcessInstanceState, waitingOnHuman?: boolean): boolean;
+    /** Record from a {@link ProcessInstanceSnapshot} (the engine's `searchProcessInstances` row),
+     *  carrying the optional waiting-on-human flag the reconciler probes separately. */
+    recordFromSnapshot(snapshot: ProcessInstanceSnapshot, waitingOnHuman?: boolean): boolean;
+    /** The projected canonical state for an instance, or `undefined` if none recorded. */
+    getState(processInstanceKey: string): InstanceStateRow | undefined;
+}

package/dist/runtime/core/modules/instance-state-store.js

@@ -0,0 +1,101 @@
+// instance-state-store — the canonical per-instance engine lifecycle-state projection (ADR 0065,
+// proposal point #1). A framework-level, per-source sidecar (exactly like the lineage store) that
+// records each tracked process instance's engine-truth lifecycle state (ACTIVE / COMPLETED /
+// TERMINATED) plus whether it is waiting on a human, from the same `searchProcessInstances` /
+// `openUserTasks` truth the `instanceTracking` reconciler already reads.
+//
+// A read model can then DERIVE an instance's status edge purely from this projection — e.g. the
+// terminal edge (`onTerminated`, → `abandoned`) becomes an `EXISTS(urban_instance_state WHERE
+// process_instance_key = … AND state = 'TERMINATED')` derivation, instead of a stored `status` write
+// that tears from engine truth. This projection PROVIDES that engine-truth source; retiring the
+// reconciler's writes is the downstream `writer-source-inversion` task.
+//
+// It is framework bookkeeping, so the physical table is `_urban_`-prefixed to stay hidden from the
+// domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables — and NEVER
+// app-written. Recording is idempotent: re-recording an unchanged state is a no-op.
+import { systemClock } from "./lineage-store.js";
+/** The instance-state projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export const INSTANCE_STATE_TABLE = "_urban_instance_state";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link INSTANCE_STATE_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_instance_state WHERE process_instance_key = base.process_instance_key)`. */
+export const INSTANCE_STATE_PROJECTION = "urban_instance_state";
+/**
+ * The canonical instance-state DDL — the single source of truth applied by
+ * {@link InstanceStateStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/007_urban_instance_state.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `process_instance_key` (one canonical state per instance) so a
+ * re-record upserts in place and is idempotent. `waiting_on_human` is 0/1 (SQLite has no boolean).
+ */
+export const INSTANCE_STATE_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${INSTANCE_STATE_TABLE} (
+  process_instance_key TEXT NOT NULL,
+  state                TEXT NOT NULL,
+  waiting_on_human     INTEGER NOT NULL DEFAULT 0,
+  updated_at           TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key)
+);`;
+function normalizeState(raw) {
+    // Validate rather than coerce: silently mapping an unknown value to "ACTIVE" would let corrupted rows
+    // or an unhandled new engine state masquerade as ACTIVE and produce incorrect derived edges. Surface
+    // the bad data loudly instead.
+    if (raw === "ACTIVE" || raw === "COMPLETED" || raw === "TERMINATED")
+        return raw;
+    throw new Error(`${INSTANCE_STATE_TABLE} contains an unexpected state ${JSON.stringify(raw)} — refusing to coerce to ACTIVE (data corruption or an unhandled engine state)`);
+}
+/**
+ * The per-source sidecar behind the `urban_instance_state` projection. A thin, idempotent
+ * persistence + query layer over the engine's per-instance lifecycle truth.
+ */
+export class InstanceStateStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/007_urban_instance_state.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema() {
+        this.#db.exec(INSTANCE_STATE_SCHEMA_SQL);
+    }
+    /**
+     * Record an instance's canonical engine lifecycle state (and whether it is waiting on a human),
+     * upserting the single row keyed by `processInstanceKey`. Idempotent: re-recording the same
+     * `(state, waitingOnHuman)` is a no-op (returns `false`). A blank `processInstanceKey` is ignored.
+     */
+    recordState(processInstanceKey, state, waitingOnHuman = false) {
+        if (!processInstanceKey)
+            return false;
+        const { changes } = this.#db.run(`INSERT INTO ${INSTANCE_STATE_TABLE}
+         (process_instance_key, state, waiting_on_human, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (process_instance_key) DO UPDATE SET
+         state = excluded.state,
+         waiting_on_human = excluded.waiting_on_human,
+         updated_at = excluded.updated_at
+       WHERE ${INSTANCE_STATE_TABLE}.state <> excluded.state
+          OR ${INSTANCE_STATE_TABLE}.waiting_on_human <> excluded.waiting_on_human`, [processInstanceKey, state, waitingOnHuman ? 1 : 0, new Date(this.#clock.now()).toISOString()]);
+        return changes > 0;
+    }
+    /** Record from a {@link ProcessInstanceSnapshot} (the engine's `searchProcessInstances` row),
+     *  carrying the optional waiting-on-human flag the reconciler probes separately. */
+    recordFromSnapshot(snapshot, waitingOnHuman = false) {
+        return this.recordState(snapshot.processInstanceKey, snapshot.state, waitingOnHuman);
+    }
+    /** The projected canonical state for an instance, or `undefined` if none recorded. */
+    getState(processInstanceKey) {
+        const rows = this.#db.all(`SELECT process_instance_key, state, waiting_on_human
+         FROM ${INSTANCE_STATE_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        return {
+            processInstanceKey: row.process_instance_key,
+            state: normalizeState(row.state),
+            waitingOnHuman: row.waiting_on_human !== 0,
+        };
+    }
+}

package/dist/runtime/core/modules/open-user-tasks-store.d.ts

@@ -0,0 +1,63 @@
+import type { SqliteDb } from "../host.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { type Clock } from "./lineage-store.ts";
+/** The open-user-tasks projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export declare const OPEN_USER_TASKS_TABLE = "_urban_open_user_tasks";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link OPEN_USER_TASKS_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.process_instance_key)`. */
+export declare const OPEN_USER_TASKS_PROJECTION = "urban_open_user_tasks";
+/**
+ * The canonical open-user-tasks DDL — the single source of truth applied by
+ * {@link OpenUserTasksStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/006_urban_open_user_tasks.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `user_task_key` so a re-record of the same open task is a no-op;
+ * `process_instance_key` carries an index so a read model's correlated `EXISTS(... WHERE
+ * process_instance_key = …)` and the reconciler's per-instance sync read only that instance's rows.
+ */
+export declare const OPEN_USER_TASKS_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS _urban_open_user_tasks (\n  process_instance_key TEXT NOT NULL,\n  user_task_key        TEXT NOT NULL,\n  element_id           TEXT,\n  created_at           TEXT NOT NULL,\n  PRIMARY KEY (user_task_key)\n);\nCREATE INDEX IF NOT EXISTS idx__urban_open_user_tasks_instance ON _urban_open_user_tasks (process_instance_key);";
+export interface OpenUserTasksStoreOptions {
+    readonly clock?: Clock;
+}
+/** One projected open-user-task row, as {@link OpenUserTasksStore.openTasks} returns it. */
+export interface OpenUserTaskRow {
+    readonly processInstanceKey: string;
+    readonly userTaskKey: string;
+    readonly elementId?: string;
+}
+/**
+ * The per-source sidecar behind the `urban_open_user_tasks` projection. A thin, idempotent
+ * persistence + query layer over the engine's open-user-task truth; it interprets no app schema.
+ */
+export declare class OpenUserTasksStore {
+    #private;
+    constructor(db: SqliteDb, options?: OpenUserTasksStoreOptions);
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/006_urban_open_user_tasks.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema(): void;
+    /**
+     * Record one open user task for an instance, idempotently. A re-record of the same `userTaskKey` is
+     * a no-op. A blank `processInstanceKey` or `userTaskKey` is ignored. Prefer {@link syncInstance} to
+     * record an instance's WHOLE current open set (which also retires closed tasks); this single-row
+     * form is the idempotent building block.
+     */
+    recordOpenTask(processInstanceKey: string, task: UserTaskSummary): boolean;
+    /**
+     * Make the projection reflect an instance's CURRENT open set exactly: insert the engine's open tasks
+     * and delete any previously-projected task for the instance that is no longer open. This is the
+     * authoritative record from engine truth (`openUserTasks({ processInstanceKey })`), the operation the
+     * reconciler drives each poll — so an answered/closed task disappears and the derived
+     * "waiting-on-human" edge re-flips by construction (nano-workforce#422). Idempotent: syncing the same
+     * open set twice leaves the table unchanged. A blank `processInstanceKey` is ignored.
+     */
+    syncInstance(processInstanceKey: string, openTasks: readonly UserTaskSummary[]): void;
+    /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
+    clearInstance(processInstanceKey: string): void;
+    /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
+    hasOpenTask(processInstanceKey: string): boolean;
+    /** The projected open tasks for an instance, in insertion order. */
+    openTasks(processInstanceKey: string): OpenUserTaskRow[];
+}

package/dist/runtime/core/modules/open-user-tasks-store.js

@@ -0,0 +1,135 @@
+// open-user-tasks-store — the canonical engine-truth projection of "which process instances are
+// parked on a human" (ADR 0065, proposal point #1). A framework-level, per-source sidecar (exactly
+// like the lineage store) that materialises the set of currently-open (CREATED-state) user tasks per
+// process instance from engine truth — the same `openUserTasks` / `searchUserTasks({state:"CREATED"})`
+// query the `instanceTracking` reconciler already runs.
+//
+// This ABSORBS nano-workforce's hand-rolled `user_tasks` table: it is the ONE authoritative projection
+// a read model can `EXISTS`-over to derive the "waiting-on-human" status edge, instead of an app
+// hand-maintaining a stored `awaiting_operator` column (the tearing surface of nano-workforce#422).
+//
+// It is framework bookkeeping, so the physical table is `_urban_`-prefixed to stay hidden from the
+// domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables — and it is NEVER
+// app-written. Recording is idempotent and authoritative-per-instance: {@link OpenUserTasksStore.syncInstance}
+// replaces an instance's rows with exactly the engine's current open set, so an answered/closed task
+// disappears on the next poll and the derived edge re-flips by construction (No Drift Surfaces).
+import { systemClock } from "./lineage-store.js";
+/** The open-user-tasks projection table. Framework bookkeeping, so `_urban_`-prefixed to stay hidden
+ *  from the domain model / DB Manager (see `SqliteGateway.schema()`), like the lineage tables. */
+export const OPEN_USER_TASKS_TABLE = "_urban_open_user_tasks";
+/** The stable DSL projection NAME a `defineReadModel` `exists(...)` references (registered in the
+ *  `projectionRegistry`, mapped to {@link OPEN_USER_TASKS_TABLE}). The DSL name is unprefixed so a read
+ *  model reads `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.process_instance_key)`. */
+export const OPEN_USER_TASKS_PROJECTION = "urban_open_user_tasks";
+/**
+ * The canonical open-user-tasks DDL — the single source of truth applied by
+ * {@link OpenUserTasksStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/006_urban_open_user_tasks.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. Keyed by `user_task_key` so a re-record of the same open task is a no-op;
+ * `process_instance_key` carries an index so a read model's correlated `EXISTS(... WHERE
+ * process_instance_key = …)` and the reconciler's per-instance sync read only that instance's rows.
+ */
+export const OPEN_USER_TASKS_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${OPEN_USER_TASKS_TABLE} (
+  process_instance_key TEXT NOT NULL,
+  user_task_key        TEXT NOT NULL,
+  element_id           TEXT,
+  created_at           TEXT NOT NULL,
+  PRIMARY KEY (user_task_key)
+);
+CREATE INDEX IF NOT EXISTS idx_${OPEN_USER_TASKS_TABLE}_instance ON ${OPEN_USER_TASKS_TABLE} (process_instance_key);`;
+/**
+ * The per-source sidecar behind the `urban_open_user_tasks` projection. A thin, idempotent
+ * persistence + query layer over the engine's open-user-task truth; it interprets no app schema.
+ */
+export class OpenUserTasksStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#clock = options.clock ?? systemClock;
+    }
+    /** Apply the canonical DDL (idempotent). Callers whose app DataLayer applies the boot migration
+     *  `db/migrations/006_urban_open_user_tasks.sql` do not need this; the runtime calls it so the store
+     *  is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+    ensureSchema() {
+        this.#db.exec(OPEN_USER_TASKS_SCHEMA_SQL);
+    }
+    /**
+     * Record one open user task for an instance, idempotently. A re-record of the same `userTaskKey` is
+     * a no-op. A blank `processInstanceKey` or `userTaskKey` is ignored. Prefer {@link syncInstance} to
+     * record an instance's WHOLE current open set (which also retires closed tasks); this single-row
+     * form is the idempotent building block.
+     */
+    recordOpenTask(processInstanceKey, task) {
+        if (!processInstanceKey || !task.userTaskKey)
+            return false;
+        const { changes } = this.#db.run(`INSERT OR IGNORE INTO ${OPEN_USER_TASKS_TABLE}
+         (process_instance_key, user_task_key, element_id, created_at)
+       VALUES (?, ?, ?, ?)`, [processInstanceKey, task.userTaskKey, task.elementId ?? null, new Date(this.#clock.now()).toISOString()]);
+        return changes > 0;
+    }
+    /**
+     * Make the projection reflect an instance's CURRENT open set exactly: insert the engine's open tasks
+     * and delete any previously-projected task for the instance that is no longer open. This is the
+     * authoritative record from engine truth (`openUserTasks({ processInstanceKey })`), the operation the
+     * reconciler drives each poll — so an answered/closed task disappears and the derived
+     * "waiting-on-human" edge re-flips by construction (nano-workforce#422). Idempotent: syncing the same
+     * open set twice leaves the table unchanged. A blank `processInstanceKey` is ignored.
+     */
+    syncInstance(processInstanceKey, openTasks) {
+        if (!processInstanceKey)
+            return;
+        // Wrap the insert+delete replace in a SAVEPOINT so the whole sync is atomic: no reader observes a
+        // transient mixed state mid-sync, and a mid-loop failure rolls back cleanly instead of leaving the
+        // instance with a torn open set. SAVEPOINT (not BEGIN) so this also composes when called inside an
+        // existing transaction, e.g. a reconciler poll that batches many instances.
+        this.#db.exec("SAVEPOINT urban_sync_open_tasks");
+        try {
+            const keep = new Set();
+            for (const task of openTasks) {
+                if (!task.userTaskKey)
+                    continue;
+                keep.add(task.userTaskKey);
+                this.recordOpenTask(processInstanceKey, task);
+            }
+            const existing = this.#db.all(`SELECT user_task_key FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+            for (const row of existing) {
+                if (!keep.has(row.user_task_key)) {
+                    this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE user_task_key = ?`, [row.user_task_key]);
+                }
+            }
+            this.#db.exec("RELEASE urban_sync_open_tasks");
+        }
+        catch (err) {
+            this.#db.exec("ROLLBACK TO urban_sync_open_tasks");
+            this.#db.exec("RELEASE urban_sync_open_tasks");
+            throw err;
+        }
+    }
+    /** Retire every projected open task for an instance (e.g. it terminated). Idempotent. */
+    clearInstance(processInstanceKey) {
+        if (!processInstanceKey)
+            return;
+        this.#db.run(`DELETE FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ?`, [processInstanceKey]);
+    }
+    /** True iff the instance currently has any open user task — the "parked on a human" predicate. */
+    hasOpenTask(processInstanceKey) {
+        if (!processInstanceKey)
+            return false;
+        // Existence predicate: `SELECT 1 … LIMIT 1` short-circuits on the first matching row rather than
+        // counting every open task for the instance.
+        const rows = this.#db.all(`SELECT 1 AS one FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ? LIMIT 1`, [processInstanceKey]);
+        return rows.length > 0;
+    }
+    /** The projected open tasks for an instance, in insertion order. */
+    openTasks(processInstanceKey) {
+        const rows = this.#db.all(`SELECT process_instance_key, user_task_key, element_id
+         FROM ${OPEN_USER_TASKS_TABLE} WHERE process_instance_key = ? ORDER BY rowid`, [processInstanceKey]);
+        return rows.map((r) => ({
+            processInstanceKey: r.process_instance_key,
+            userTaskKey: r.user_task_key,
+            ...(r.element_id ? { elementId: r.element_id } : {}),
+        }));
+    }
+}

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

@@ -28,6 +28,8 @@ import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
 import { cancelInstanceReconciling } from "./cancel.js";
 import { apiDocsPath } from "./api.js";
+import { FORMJS_JS } from "./formjs.gen.js";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.js";
 import { quoteIdent } from "./gateway.js";
 import { RENDERER_JS } from "./runtime.gen.js";
 /** A JavaScript-body response (the renderer module served at the fingerprinted
@@ -489,6 +491,26 @@ export function createPagesRoutes(opts, deps) {
             }
         },
     });
+    // ── GET /app/actions/form  &  POST /app/actions/complete (ADR 0026, #457) ───
+    // Engine-declared forms in a `dataGrid` detail drawer. A grid whose `detail`
+    // opts into `engineForm` resolves the selected row's `form_key` here and
+    // completes the row's user task here — the SAME two seams the `taskInbox`
+    // surface uses, reused (not forked) via `forms.ts` so the resolution gate and
+    // the completion contract can't drift between the two surfaces. This closes the
+    // form-duplication drift class: the grid renders the authoritative deployed
+    // `.form` rather than a hand-authored page-local `detail.form` copy.
+    routes.push({
+        method: "GET",
+        path: "/app/actions/form",
+        source: "surface:pages",
+        handler: (req) => resolveFormResponse(engine, req.query.get("formKey") ?? undefined, req.query.get("formId") ?? undefined),
+    });
+    routes.push({
+        method: "POST",
+        path: "/app/actions/complete",
+        source: "surface:pages",
+        handler: async (req) => completeUserTaskResponse(engine, await req.text()),
+    });
     // ── nested (multi-appView) sidecars (#442) ──────────────────────────────
     // An app with more than one `appView` cannot share the four FLAT sidecar names above:
     // each view ships its own SUBDIR sidecar — e.g. `pages/cockpit.page.json` →
@@ -603,6 +625,7 @@ function rendererShell(homePage, apiDocsPath) {
 </head>
 <body>${apiDocsBadge}
   <main id="page" data-home="${escapeAttr(homePage)}"><p class="pc-empty">Loading…</p></main>
+  <script>${FORMJS_JS}</script>
   <script type="module" src=".${RUNTIME_JS_PATH}"></script>
 </body>
 </html>`;
@@ -669,6 +692,19 @@ body { margin:0; font:15px/1.5 system-ui,sans-serif; padding:2rem; max-width:64r
 .pc-field-check input { width:auto; padding:0; accent-color:var(--nano-accent); cursor:pointer; }
 .pc-btn { padding:.5rem .9rem; border:0; border-radius:.4rem; background:var(--nano-accent); color:var(--nano-on-accent); font:inherit; cursor:pointer; }
 .pc-btn:disabled { opacity:.5; cursor:default; }
+/* The shared engine-form renderer (NanoFormJs, ADR 0026/#457) styled to match the
+   page runtime's native detail controls. njf-* are its stable class names; both
+   this surface and the taskInbox page style the same renderer output. */
+.njf-form { display:flex; flex-direction:column; gap:.4rem; margin-top:.5rem; }
+.njf-heading { font-size:1rem; margin:0 0 .25rem; }
+.njf-text { color:var(--nano-text-muted); margin:.25rem 0; }
+.njf-field { display:flex; flex-direction:column; gap:.25rem; }
+.njf-field label { font-size:.8rem; color:var(--nano-text-muted); }
+.njf-field input:not([type=checkbox]):not([type=radio]), .njf-field textarea, .njf-field select { padding:.5rem .6rem; border:1px solid var(--nano-edge); border-radius:.4rem; font:inherit; background:var(--nano-inset); color:var(--nano-text); max-width:24rem; }
+.njf-actions { display:flex; gap:.5rem; margin-top:.4rem; }
+.njf-actions button { padding:.5rem .9rem; border:0; border-radius:.4rem; background:var(--nano-accent); color:var(--nano-on-accent); font:inherit; cursor:pointer; }
+.njf-msg { font-size:.85rem; margin-top:.35rem; }
+.njf-msg.err { color:var(--nano-danger); }
 .pc-msg { font-size:.85rem; margin-top:.5rem; min-height:1.2em; }
 .pc-msg.err { color:var(--nano-danger); }
 .pc-msg.ok { color:var(--nano-ok); }