@nanobpm/urban 0.78.0 → 0.80.0

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

@@ -0,0 +1,172 @@
+// 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 type { SqliteDb } from "../host.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { type Clock, systemClock } 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 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);`;
+
+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;
+}
+
+interface OpenTaskDbRow {
+  process_instance_key: string;
+  user_task_key: string;
+  element_id: string | null;
+}
+
+/**
+ * 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 {
+  readonly #db: SqliteDb;
+  readonly #clock: Clock;
+
+  constructor(db: SqliteDb, options: OpenUserTasksStoreOptions = {}) {
+    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(): void {
+    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: string, task: UserTaskSummary): boolean {
+    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: string, openTasks: readonly UserTaskSummary[]): void {
+    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<string>();
+      for (const task of openTasks) {
+        if (!task.userTaskKey) continue;
+        keep.add(task.userTaskKey);
+        this.recordOpenTask(processInstanceKey, task);
+      }
+      const existing = this.#db.all<{ user_task_key: string }>(
+        `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: string): void {
+    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: string): boolean {
+    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<{ one: number }>(
+      `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: string): OpenUserTaskRow[] {
+    const rows = this.#db.all<OpenTaskDbRow>(
+      `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/src/runtime/core/modules/pages.test.ts

@@ -1950,3 +1950,102 @@ test("the nested serve declines (does not shadow) a same-path trigger route regi
   assert.equal(hook.status, 202);
   assert.deepEqual(JSON.parse(hook.body ?? "{}"), { queued: true });
 });
+
+// ── engine-declared forms in a dataGrid detail (ADR 0026 / #457) ────────────
+// The pages surface exposes the SAME two seams the taskInbox surface uses:
+//   GET  /app/actions/form?formKey=…   → resolve a deployed .form's form-js schema
+//   POST /app/actions/complete         → complete the row's user task
+// so one grid can render the several different typed forms a heterogeneous task
+// inbox carries, instead of duplicating each into a page-local `detail.form`.
+
+/** A recording engine for the form-resolution + completion seams. `resolveForm`
+ * supplies the getForm result while the wrapper still records every call, so a test
+ * can assert BOTH the resolved schema and the exact `{formKey, formId}` the shared
+ * presence gate passed through. */
+function formEngine(
+  resolveForm: (input: { formKey?: string; formId?: string }) => Awaited<ReturnType<EngineClient["getForm"]>> = () => null,
+): {
+  engine: EngineClient;
+  formCalls: { formKey?: string; formId?: string }[];
+  completeCalls: { userTaskKey: string; variables?: Record<string, unknown> }[];
+} {
+  const formCalls: { formKey?: string; formId?: string }[] = [];
+  const completeCalls: { userTaskKey: string; variables?: Record<string, unknown> }[] = [];
+  const { engine } = fakeEngine();
+  const withSeams: EngineClient = {
+    ...engine,
+    async getForm(input: { formKey?: string; formId?: string }) {
+      formCalls.push(input);
+      return resolveForm(input);
+    },
+    async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>) {
+      completeCalls.push({ userTaskKey, variables });
+    },
+  };
+  return { engine: withSeams, formCalls, completeCalls };
+}
+
+function formRouter(engine: EngineClient) {
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db: fakeDb(),
+    engine,
+    readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+    listPages: async () => ["home"],
+  });
+  return makeRouter(routes);
+}
+
+test("GET /app/actions/form resolves a row's engine formKey to its form-js schema", async () => {
+  const schema = { type: "default", components: [{ type: "textfield", key: "note" }] };
+  const { engine, formCalls } = formEngine((input) => ({ formKey: input.formKey, schema }));
+  const res = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=form-123" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}").schema, schema);
+  assert.deepEqual(formCalls, [{ formKey: "form-123", formId: undefined }]);
+});
+
+test("GET /app/actions/form 400s when neither formKey nor formId is present (shared presence gate)", async () => {
+  const { engine } = formEngine();
+  const res = await formRouter(engine)(req("GET", "/app/actions/form"));
+  assert.equal(res.status, 400);
+  const blank = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=%20%20" }));
+  assert.equal(blank.status, 400, "a whitespace-only formKey is absent per the host.ts presence rule");
+});
+
+test("GET /app/actions/form 204s when the form can't be resolved (client falls back to bare completion)", async () => {
+  // getForm returns null (default) → 204, matching the taskInbox no-form fallback.
+  const { engine } = formEngine();
+  const res = await formRouter(engine)(req("GET", "/app/actions/form", { query: "formKey=missing" }));
+  assert.equal(res.status, 204);
+  assert.equal(res.body ?? "", "");
+});
+
+test("POST /app/actions/complete completes the row's user task with the submitted variables", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(
+    req("POST", "/app/actions/complete", { body: { userTaskKey: "ut-9", variables: { note: "ok" } } }),
+  );
+  assert.equal(res.status, 200);
+  assert.deepEqual(JSON.parse(res.body ?? "{}"), { ok: true });
+  assert.deepEqual(completeCalls, [{ userTaskKey: "ut-9", variables: { note: "ok" } }]);
+});
+
+test("POST /app/actions/complete supports the no-form bare completion (empty variables)", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(req("POST", "/app/actions/complete", { body: { userTaskKey: "ut-1" } }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(completeCalls, [{ userTaskKey: "ut-1", variables: undefined }]);
+});
+
+test("POST /app/actions/complete 400s without a userTaskKey", async () => {
+  const { engine, completeCalls } = formEngine();
+  const res = await formRouter(engine)(req("POST", "/app/actions/complete", { body: { variables: {} } }));
+  assert.equal(res.status, 400);
+  assert.equal(completeCalls.length, 0, "no completion is attempted for a keyless body");
+});
+
+test("the pages shell embeds the shared form-js renderer (NanoFormJs) for engine forms", async () => {
+  const res = await dispatch("GET", "/");
+  assert.match(res.body ?? "", /NanoFormJs/, "the shell exposes the shared renderer as a global");
+  assert.match(res.body ?? "", /function renderForm/, "the shared renderer is embedded, not forked");
+});

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

@@ -31,6 +31,8 @@ import type { EngineClient } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
 import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
 import { apiDocsPath } from "./api.ts";
+import { FORMJS_JS } from "./formjs.gen.ts";
+import { completeUserTaskResponse, resolveFormResponse } from "./forms.ts";
 import { quoteIdent } from "./gateway.ts";
 import { RENDERER_JS } from "./runtime.gen.ts";
 
@@ -545,6 +547,28 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     },
   });
 
+  // ── 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` →
@@ -668,6 +692,7 @@ function rendererShell(homePage: string, apiDocsPath?: string): string {
 </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>`;
@@ -736,6 +761,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); }