@nanobpm/urban 0.77.4 → 0.79.0

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

@@ -0,0 +1,156 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import type { SqliteDb } from "../host.ts";
+import type { UserTaskSummary } from "../host.ts";
+import { makeGateway } from "./gateway.ts";
+import {
+  OPEN_USER_TASKS_PROJECTION,
+  OPEN_USER_TASKS_SCHEMA_SQL,
+  OPEN_USER_TASKS_TABLE,
+  OpenUserTasksStore,
+} from "./open-user-tasks-store.ts";
+
+async function withStore(fn: (store: OpenUserTasksStore, db: SqliteDb) => void | Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-open-tasks-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  const store = new OpenUserTasksStore(db, { clock: { now: () => 0 } });
+  store.ensureSchema();
+  try {
+    await fn(store, db);
+  } finally {
+    db.close();
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+function normaliseSql(sql: string): string {
+  return sql
+    .split("\n")
+    .map((line) => line.replace(/--.*$/, ""))
+    .join("\n")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const task = (userTaskKey: string, elementId?: string): UserTaskSummary => ({ userTaskKey, elementId });
+
+const migrationPath = fileURLToPath(
+  new URL("../../../../../../db/migrations/006_urban_open_user_tasks.sql", import.meta.url),
+);
+
+test("the open-user-tasks projection table is framework bookkeeping — `_urban_`-prefixed and hidden from the domain model", async () => {
+  assert.match(OPEN_USER_TASKS_TABLE, /^_urban_/, "projection table must be `_urban_`-prefixed to stay hidden");
+  await withStore(async (_store, db) => {
+    const surfaced = (await makeGateway(db).schema()).map((t) => t.name);
+    assert.ok(!surfaced.includes(OPEN_USER_TASKS_TABLE), "projection table must not surface in the domain model");
+  });
+});
+
+test("the boot migration and OpenUserTasksStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(OPEN_USER_TASKS_SCHEMA_SQL),
+    "db/migrations/006_urban_open_user_tasks.sql must match OPEN_USER_TASKS_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS _urban_open_user_tasks/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+  assert.match(migrationPath, /[/\\]006_urban_open_user_tasks\.sql$/);
+});
+
+test("ensureSchema creates the projection table idempotently", async () => {
+  await withStore((store, db) => {
+    store.ensureSchema();
+    store.ensureSchema();
+    const tables = db
+      .all<{ name: string }>("SELECT name FROM sqlite_master WHERE type='table' AND name = ?", [OPEN_USER_TASKS_TABLE])
+      .map((r) => r.name);
+    assert.deepEqual(tables, [OPEN_USER_TASKS_TABLE]);
+  });
+});
+
+test("recordOpenTask is idempotent (a re-record of the same user task is a no-op)", async () => {
+  await withStore((store) => {
+    assert.equal(store.recordOpenTask("pi-1", task("ut-1", "Approve")), true);
+    assert.equal(store.recordOpenTask("pi-1", task("ut-1", "Approve")), false, "re-record collapses to a no-op");
+    assert.equal(store.openTasks("pi-1").length, 1);
+    assert.equal(store.recordOpenTask("", task("ut-x")), false, "blank instance key is ignored");
+    assert.equal(store.recordOpenTask("pi-1", task("")), false, "blank user task key is ignored");
+  });
+});
+
+test("syncInstance makes the projection reflect the engine's CURRENT open set (retiring closed tasks)", async () => {
+  await withStore((store) => {
+    // Two open tasks initially.
+    store.syncInstance("pi-1", [task("ut-1", "Approve"), task("ut-2", "Review")]);
+    assert.deepEqual(store.openTasks("pi-1").map((t) => t.userTaskKey).sort(), ["ut-1", "ut-2"]);
+    assert.equal(store.hasOpenTask("pi-1"), true);
+
+    // ut-1 answered/closed, a new ut-3 created → engine now reports {ut-2, ut-3}.
+    store.syncInstance("pi-1", [task("ut-2", "Review"), task("ut-3", "Sign")]);
+    assert.deepEqual(store.openTasks("pi-1").map((t) => t.userTaskKey).sort(), ["ut-2", "ut-3"]);
+
+    // All answered → no open tasks: the instance is no longer parked on a human (nano-workforce#422).
+    store.syncInstance("pi-1", []);
+    assert.equal(store.hasOpenTask("pi-1"), false);
+    assert.deepEqual(store.openTasks("pi-1"), []);
+  });
+});
+
+test("syncInstance is idempotent and scoped to one instance", async () => {
+  await withStore((store) => {
+    store.syncInstance("pi-1", [task("ut-1")]);
+    store.syncInstance("pi-2", [task("ut-2")]);
+    // Re-syncing pi-1's unchanged open set must not touch pi-2.
+    store.syncInstance("pi-1", [task("ut-1")]);
+    assert.deepEqual(store.openTasks("pi-1").map((t) => t.userTaskKey), ["ut-1"]);
+    assert.deepEqual(store.openTasks("pi-2").map((t) => t.userTaskKey), ["ut-2"]);
+  });
+});
+
+test("clearInstance retires every open task for an instance", async () => {
+  await withStore((store) => {
+    store.syncInstance("pi-1", [task("ut-1"), task("ut-2")]);
+    store.clearInstance("pi-1");
+    assert.equal(store.hasOpenTask("pi-1"), false);
+  });
+});
+
+test("syncInstance is atomic — it composes inside an existing transaction and rolls back on failure", async () => {
+  await withStore((store, db) => {
+    // Composes inside an outer transaction (SAVEPOINT, not BEGIN): the whole replace commits as one unit.
+    db.exec("BEGIN");
+    store.syncInstance("pi-1", [task("ut-1"), task("ut-2")]);
+    db.exec("COMMIT");
+    assert.deepEqual(store.openTasks("pi-1").map((t) => t.userTaskKey).sort(), ["ut-1", "ut-2"]);
+
+    // A failure mid-sync must roll the whole operation back, leaving the prior open set intact rather
+    // than a torn partial state. A subclass that throws from recordOpenTask forces a mid-loop failure.
+    const boom = new Error("boom");
+    class ThrowingStore extends OpenUserTasksStore {
+      override recordOpenTask(): boolean {
+        throw boom;
+      }
+    }
+    const broken = new ThrowingStore(db, { clock: { now: () => 0 } });
+    assert.throws(() => broken.syncInstance("pi-1", [task("ut-9")]), boom);
+    // The prior open set is unchanged — nothing was half-written or half-deleted.
+    assert.deepEqual(store.openTasks("pi-1").map((t) => t.userTaskKey).sort(), ["ut-1", "ut-2"]);
+  });
+});
+
+test("the DSL projection name is stable and unprefixed (usable in `exists(...)`)", () => {
+  assert.equal(OPEN_USER_TASKS_PROJECTION, "urban_open_user_tasks");
+});

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/workers.ts

@@ -11,6 +11,10 @@ import { runInJobContext } from "../execContext.ts";
 import type { JobExecContext } from "../execContext.ts";
 import { readLineage } from "../lineage.ts";
 import { LineageStore } from "./lineage-store.ts";
+import { readModelRegistry } from "../read-model.ts";
+import { registerCanonicalProjections } from "./canonical-projections.ts";
+import { InstanceStateStore } from "./instance-state-store.ts";
+import { OpenUserTasksStore } from "./open-user-tasks-store.ts";
 import { defaultScheduler, schedulerClock, type SchedulerDeps } from "./scheduler.ts";
 
 /** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
@@ -135,6 +139,50 @@ function tryLineageStore(app: AppApi, log: RuntimeContext["host"]["log"]): Linea
   }
 }
 
+/**
+ * Apply every managed read-model VIEW registered in the process-wide `readModelRegistry` to the app's
+ * DEFAULT data source (ADR 0065, surface #3). A `defineReadModel(...)` declaration compiles to a
+ * managed SQLite VIEW; provisioning it here — the same per-source boot path `tryLineageStore` uses —
+ * means an app (or a canonical-projection sidecar) that registers a read model gets its VIEW created
+ * for free, with no hand-written migration. The registry is empty until a sibling task registers into
+ * it, so this is a silent no-op in the base framework. Absent- and error-safe like lineage: an app
+ * with no datasource provisions nothing, and a VIEW-provisioning failure never breaks a worker mount.
+ */
+function tryProvisionReadModelViews(app: AppApi, log: RuntimeContext["host"]["log"]): void {
+  if (readModelRegistry.all().length === 0) return;
+  if (!app.data.hasDefaultSource()) {
+    log("debug", "read-models: no default data source; managed VIEW provisioning skipped");
+    return;
+  }
+  try {
+    readModelRegistry.ensureViews(app.data.source().db);
+  } catch (err) {
+    log("warn", "read-models: failed to provision managed VIEWs", { error: String(err) });
+  }
+}
+
+/**
+ * Provision the canonical engine-truth projection sidecars (ADR 0065, proposal point #1) on the app's
+ * DEFAULT data source — `_urban_open_user_tasks` and `_urban_instance_state`, the sources a read model
+ * `EXISTS`-derives its status edges from. Exactly the per-source boot path `tryLineageStore` uses: an
+ * app with no datasource provisions nothing, and a schema failure degrades to no projection tables
+ * rather than a failed worker mount. The DSL projection-name registration is done unconditionally by
+ * the caller (so read models compile even without a datasource); this only creates the physical tables.
+ */
+function tryProvisionCanonicalProjections(app: AppApi, log: RuntimeContext["host"]["log"]): void {
+  if (!app.data.hasDefaultSource()) {
+    log("debug", "canonical-projections: no default data source; projection tables not provisioned");
+    return;
+  }
+  try {
+    const { db } = app.data.source();
+    new OpenUserTasksStore(db).ensureSchema();
+    new InstanceStateStore(db).ensureSchema();
+  } catch (err) {
+    log("warn", "canonical-projections: failed to provision projection tables", { error: String(err) });
+  }
+}
+
 /** Record an activated job's lineage edge, never letting a projection write break the job. */
 function recordJobLineage(store: LineageStore, job: EngineJob, log: RuntimeContext["host"]["log"]): void {
   try {
@@ -192,6 +240,19 @@ export async function mountWorkers(
   // app configures no default data source.
   const lineageStore = tryLineageStore(app, ctx.host.log);
 
+  // The framework read-model VIEWs (ADR 0065): apply every registered managed VIEW to the app's
+  // default data source, the same per-source boot path lineage uses. A no-op until a sibling task
+  // registers a read model into `readModelRegistry`.
+  //
+  // Register the canonical engine-truth projections (`urban_open_user_tasks`, `urban_instance_state`)
+  // FIRST and unconditionally: a read model's managed VIEW resolves each projection name to its
+  // physical `_urban_` table at DDL-compile time, so the name→table mapping must exist before
+  // `tryProvisionReadModelViews` compiles any VIEW that `EXISTS`-references a projection. Then
+  // provision the projection tables per source (absent-safe), and finally the read-model VIEWs.
+  registerCanonicalProjections();
+  tryProvisionCanonicalProjections(app, ctx.host.log);
+  tryProvisionReadModelViews(app, ctx.host.log);
+
   // Cache module loads so a multi-type handler module is imported once.
   const moduleCache = new Map<string, Record<string, unknown>>();
   const joinRoot = (p: string): string =>