@nanobpm/urban 0.78.0 → 0.79.0

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

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

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

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

package/src/runtime/core/modules/instance-state-store.test.ts

@@ -0,0 +1,143 @@
+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 { makeGateway } from "./gateway.ts";
+import {
+  INSTANCE_STATE_PROJECTION,
+  INSTANCE_STATE_SCHEMA_SQL,
+  INSTANCE_STATE_TABLE,
+  InstanceStateStore,
+} from "./instance-state-store.ts";
+
+async function withStore(fn: (store: InstanceStateStore, db: SqliteDb) => void | Promise<void>): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-instance-state-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  const store = new InstanceStateStore(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 migrationPath = fileURLToPath(
+  new URL("../../../../../../db/migrations/007_urban_instance_state.sql", import.meta.url),
+);
+
+test("the instance-state projection table is framework bookkeeping — `_urban_`-prefixed and hidden from the domain model", async () => {
+  assert.match(INSTANCE_STATE_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(INSTANCE_STATE_TABLE), "projection table must not surface in the domain model");
+  });
+});
+
+test("the boot migration and InstanceStateStore's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(INSTANCE_STATE_SCHEMA_SQL),
+    "db/migrations/007_urban_instance_state.sql must match INSTANCE_STATE_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_instance_state/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+  assert.match(migrationPath, /[/\\]007_urban_instance_state\.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 = ?", [INSTANCE_STATE_TABLE])
+      .map((r) => r.name);
+    assert.deepEqual(tables, [INSTANCE_STATE_TABLE]);
+  });
+});
+
+test("recordState upserts one canonical state per instance and is idempotent", async () => {
+  await withStore((store) => {
+    assert.equal(store.recordState("pi-1", "ACTIVE"), true);
+    assert.equal(store.recordState("pi-1", "ACTIVE"), false, "re-record of the same state is a no-op");
+    assert.deepEqual(store.getState("pi-1"), {
+      processInstanceKey: "pi-1",
+      state: "ACTIVE",
+      waitingOnHuman: false,
+    });
+
+    // A lifecycle transition upserts in place (still one row).
+    assert.equal(store.recordState("pi-1", "TERMINATED"), true);
+    assert.deepEqual(store.getState("pi-1"), {
+      processInstanceKey: "pi-1",
+      state: "TERMINATED",
+      waitingOnHuman: false,
+    });
+    assert.equal(store.recordState("", "ACTIVE"), false, "blank instance key is ignored");
+  });
+});
+
+test("recordState tracks the waiting-on-human flag", async () => {
+  await withStore((store) => {
+    store.recordState("pi-1", "ACTIVE", true);
+    assert.equal(store.getState("pi-1")?.waitingOnHuman, true);
+    // Flipping only the flag (state unchanged) is a real change.
+    assert.equal(store.recordState("pi-1", "ACTIVE", false), true);
+    assert.equal(store.getState("pi-1")?.waitingOnHuman, false);
+  });
+});
+
+test("recordFromSnapshot records from an engine ProcessInstanceSnapshot", async () => {
+  await withStore((store) => {
+    store.recordFromSnapshot({ processInstanceKey: "pi-9", state: "COMPLETED" });
+    assert.deepEqual(store.getState("pi-9"), {
+      processInstanceKey: "pi-9",
+      state: "COMPLETED",
+      waitingOnHuman: false,
+    });
+  });
+});
+
+test("getState surfaces (throws on) an unexpected persisted state rather than masquerading it as ACTIVE", async () => {
+  await withStore((store, db) => {
+    // Simulate a corrupted row / an unhandled future engine state landing in the table.
+    db.run(
+      `INSERT INTO ${INSTANCE_STATE_TABLE} (process_instance_key, state, waiting_on_human, updated_at)
+       VALUES (?, ?, 0, ?)`,
+      ["pi-bad", "SOMETHING_ELSE", new Date(0).toISOString()],
+    );
+    assert.throws(() => store.getState("pi-bad"), /unexpected state/);
+  });
+});
+
+test("getState returns undefined for an unrecorded instance", async () => {
+  await withStore((store) => {
+    assert.equal(store.getState("unknown"), undefined);
+  });
+});
+
+test("the DSL projection name is stable and unprefixed (usable in `exists(...)`)", () => {
+  assert.equal(INSTANCE_STATE_PROJECTION, "urban_instance_state");
+});

package/src/runtime/core/modules/instance-state-store.ts

@@ -0,0 +1,135 @@
+// 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 type { ProcessInstanceSnapshot, ProcessInstanceState, SqliteDb } from "../host.ts";
+import { type Clock, systemClock } 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 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)
+);`;
+
+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;
+}
+
+interface InstanceStateDbRow {
+  process_instance_key: string;
+  state: string;
+  waiting_on_human: number;
+}
+
+function normalizeState(raw: string): ProcessInstanceState {
+  // 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 {
+  readonly #db: SqliteDb;
+  readonly #clock: Clock;
+
+  constructor(db: SqliteDb, options: InstanceStateStoreOptions = {}) {
+    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(): void {
+    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: string, state: ProcessInstanceState, waitingOnHuman = false): boolean {
+    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: ProcessInstanceSnapshot, waitingOnHuman = false): boolean {
+    return this.recordState(snapshot.processInstanceKey, snapshot.state, waitingOnHuman);
+  }
+
+  /** The projected canonical state for an instance, or `undefined` if none recorded. */
+  getState(processInstanceKey: string): InstanceStateRow | undefined {
+    const rows = this.#db.all<InstanceStateDbRow>(
+      `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/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");
+});