@nanobpm/urban 0.78.0 → 0.80.0

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

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

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

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

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

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

package/src/runtime/core/modules/instance-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");
+});