@nanobpm/urban 0.79.0 → 0.81.0

package/src/runtime/browser/runtime.engineform.test.ts

@@ -0,0 +1,158 @@
+// Unit tests for buildEngineForm (#457) — the dataGrid detail's ENGINE-declared
+// form path. Where buildDetailForm renders a page-authored `detail.form`, this
+// resolves the row's engine `formKey` via the shared `/app/actions/form` gate and
+// renders the AUTHORITATIVE deployed form-js schema with the shared renderer
+// (globalThis.NanoFormJs), completing the row's user task via
+// `/app/actions/complete`. A row with no formKey degrades to a bare completion,
+// matching the taskInbox no-form fallback.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildEngineForm } from "./runtime.browser.js";
+// Importing the shared renderer registers globalThis.NanoFormJs, which
+// buildEngineForm reads lazily when it renders a resolved schema.
+import "./formjs.browser.js";
+import { type FakeElement, installFakeDom } from "./fake-dom.test-utils.ts";
+
+interface FetchCall {
+  url: string;
+  method: string;
+  // Parsed request JSON body (or undefined), typed loosely so a test can assert on
+  // arbitrary shapes without ceremony — mirrors the runtime's JSDoc `any` payloads.
+  body?: any;
+}
+
+/** Install a fake `fetch` that resolves each request from a route→response map. */
+function installFakeFetch(
+  handler: (url: string, opts: { method?: string; body?: string }) => { status?: number; json?: unknown },
+  calls: FetchCall[],
+): () => void {
+  const prior = Reflect.getOwnPropertyDescriptor(globalThis, "fetch");
+  const fake = (input: string | URL, opts: { method?: string; body?: string } = {}) => {
+    const url = String(input);
+    calls.push({ url, method: opts.method ?? "GET", body: opts.body ? JSON.parse(opts.body) : undefined });
+    const res = handler(url, opts);
+    const status = res.status ?? 200;
+    return Promise.resolve({
+      ok: status >= 200 && status < 300,
+      status,
+      json: () =>
+        res.json === undefined ? Promise.reject(new Error("no body")) : Promise.resolve(res.json),
+      text: () => Promise.resolve(res.json === undefined ? "" : JSON.stringify(res.json)),
+    });
+  };
+  Reflect.set(globalThis, "fetch", fake);
+  return () => {
+    if (prior) Reflect.defineProperty(globalThis, "fetch", prior);
+    else Reflect.deleteProperty(globalThis, "fetch");
+  };
+}
+
+const CFG = { formKeyField: "form_key", userTaskKeyField: "user_task_key" };
+
+test("buildEngineForm renders nothing when the row has no user-task key", (t) => {
+  const created: FakeElement[] = [];
+  t.after(installFakeDom(created));
+  assert.equal(buildEngineForm(CFG, { form_key: "f1" }, () => {}), null);
+  assert.equal(buildEngineForm(null, { user_task_key: "u1" }, () => {}), null);
+});
+
+test("buildEngineForm resolves the row's formKey and completes with the entered variables", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  let refreshed = false;
+  const box = buildEngineForm(CFG, { form_key: "form-9", user_task_key: "ut-9" }, () => {
+    refreshed = true;
+  });
+  assert.ok(box);
+  // Let the form fetch + render settle.
+  await new Promise((r) => setTimeout(r, 0));
+  const formReq = calls.find((c) => c.url.includes("/app/actions/form"));
+  assert.ok(formReq, "the row's formKey is resolved via the shared gate");
+  assert.match(formReq!.url, /formKey=form-9/);
+  // The shared renderer built the field; fill it and submit.
+  const input = created.find((n) => n.tagName === "INPUT");
+  assert.ok(input, "the deployed form-js schema was rendered by the shared renderer");
+  input!.value = "done";
+  const form = created.find((n) => n.tagName === "FORM");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "submitting completes the user task");
+  assert.equal(completeReq!.method, "POST");
+  assert.deepEqual(completeReq!.body, { userTaskKey: "ut-9", variables: { note: "done" } });
+  assert.equal(refreshed, true, "a successful completion invokes onSuccess (grid re-poll)");
+});
+
+test("buildEngineForm surfaces a completion failure in the rendered-form path", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) {
+        return { status: 200, json: { schema: { components: [{ type: "textfield", key: "note" }] } } };
+      }
+      return { status: 500 }; // completion fails
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "form-e", user_task_key: "ut-e" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  const form = created.find((n) => n.tagName === "FORM");
+  assert.ok(form, "the deployed schema was rendered");
+  await form!.fire("submit");
+  await new Promise((r) => setTimeout(r, 0));
+  const msg = created.find((n) => n.className.includes("njf-msg") && n.className.includes("err"));
+  assert.ok(msg, "a failed completion is surfaced to the operator (not silent)");
+  assert.notEqual(msg!.textContent, "", "the error message element has text");
+  const submit = created.find((n) => n.tagName === "BUTTON" && n.type === "submit");
+  assert.equal(submit!.disabled, false, "the submit button is re-enabled so the operator can retry");
+});
+
+test("buildEngineForm degrades to bare completion when the row has no formKey", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(installFakeFetch(() => ({ status: 200, json: { ok: true } }), calls));
+  const box = buildEngineForm(CFG, { user_task_key: "ut-2" }, () => {});
+  assert.ok(box);
+  // No form fetch — a bare "Complete" button is shown directly.
+  assert.equal(calls.length, 0, "no formKey ⇒ no form resolution request");
+  const button = created.find((n) => n.tagName === "BUTTON");
+  assert.ok(button);
+  assert.equal(button!.textContent, "Complete");
+  await button!.fire("click");
+  await new Promise((r) => setTimeout(r, 0));
+  const completeReq = calls.find((c) => c.url.includes("/app/actions/complete"));
+  assert.ok(completeReq, "the bare button completes the task");
+  assert.equal(completeReq!.body.userTaskKey, "ut-2");
+  assert.deepEqual(completeReq!.body.variables, {}, "bare completion sends empty variables");
+});
+
+test("buildEngineForm degrades to bare completion when the formKey resolves to no form (204)", async (t) => {
+  const created: FakeElement[] = [];
+  const calls: FetchCall[] = [];
+  t.after(installFakeDom(created));
+  t.after(
+    installFakeFetch((url) => {
+      if (url.includes("/app/actions/form")) return { status: 204 }; // no body
+      return { status: 200, json: { ok: true } };
+    }, calls),
+  );
+  const box = buildEngineForm(CFG, { form_key: "missing", user_task_key: "ut-3" }, () => {});
+  assert.ok(box);
+  await new Promise((r) => setTimeout(r, 0));
+  assert.ok(calls.some((c) => c.url.includes("/app/actions/form")), "an unresolved formKey still hits the gate");
+  const button = created.find((n) => n.tagName === "BUTTON" && n.textContent === "Complete");
+  assert.ok(button, "a 204 (no form) falls back to the bare completion button");
+});

package/src/runtime/core/manifest.ts

@@ -55,25 +55,58 @@ export type InstanceTracking = SchemaInstanceTracking & {
    *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
   readonly terminalStatuses?: readonly string[];
   /**
-   * The reconciliation applied to a row whose instance is **parked waiting on a human** — the
-   * wait-state twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is
-   * waiting on a human *iff* it has an open user task, so the runtime derives this edge from
-   * engine truth (`openUserTasks`) rather than from a written column: on each poll, an active,
-   * non-terminated row whose instance has any open user task has this patch applied (typically
-   * `status = "awaiting_operator"`). Terminated wins over waiting-human (the {@link
-   * SchemaInstanceTracking.onTerminated} edge is applied first and excludes the key from this
-   * pass); a row with neither a terminated instance nor an open user task is left untouched, so
-   * the worker-owned transient status (running / converging / merging) survives.
+   * The reconciliation for a row whose instance is **parked waiting on a human** — the wait-state
+   * twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is waiting on a
+   * human *iff* it has an open user task, so the runtime derives this edge from engine truth
+   * (`openUserTasks`); terminated wins over waiting-human, and a row with neither is left carrying
+   * its worker-owned transient status (running / converging / merging).
+   *
+   * Since ADR 0065 (the writer→source inversion, #439-L1 / #318) this is a DERIVED, not a stored,
+   * edge: the reconciler no longer writes `set` into the base row with `table.update`. Instead it
+   * feeds the canonical `urban_open_user_tasks` projection, and the read model derives the effective
+   * status from it via `defineReadModel` — so an answered escalation re-flips by construction and the
+   * stored-derived tearing of nano-workforce#422 cannot recur. `set[statusField]` now supplies the
+   * VALUE the derived wait-on-human edge resolves to (rather than a patch); any secondary columns in
+   * `set` are no longer written (a VIEW cannot reset a stored column). See {@link readModel}.
    *
    * Optional and, like `terminalStatuses`, bridged locally until the canonical schema
    * (`@nanobpm/nano-app-schema`) folds it in; drop this augmentation and re-export once the dep
    * bump lands (No Drift Surfaces).
    */
   readonly onWaitingHuman?: {
-    /** Column → literal value patch written to a row whose instance has an open user task
-     *  (e.g. set the status to a "waiting on human" value). */
+    /** Column → literal patch. Its `statusField` entry supplies the VALUE the derived wait-on-human
+     *  edge resolves to (an instance with an open user task ⇒ this status); no longer a stored write.
+     *  Since the inversion the reconciler makes NO base-row write at all, so only the `statusField` entry
+     *  is consumed — any other key is intentionally IGNORED (an app-owned column is the app worker's job,
+     *  not the reconciler's; ADR 0065). */
     readonly set: { readonly [k: string]: string | number | boolean | null };
   };
+  /**
+   * Optional overrides for the DERIVED read-model VIEW the runtime provisions per binding (ADR 0065,
+   * the writer→source inversion). The reconciler feeds engine truth into the canonical projections
+   * (`urban_instance_state`, `urban_open_user_tasks`) and the runtime provisions a managed SQLite VIEW
+   * over the binding's base table that re-exports `base.*` plus a derived status column — the terminal
+   * (`onTerminated`) and wait-on-human (`onWaitingHuman`) edges computed by `defineReadModel` over the
+   * projections, precedence-correct (terminated wins). The operator page reads this derived column; the
+   * base `statusField` column now holds only the worker-owned / business-outcome status. Both fields
+   * default sensibly (`view` → `<table>__tracking`, `statusColumn` → `derived_status`); override them to
+   * avoid a collision (e.g. more than one binding on one base table, or a base column already named
+   * `derived_status`). A binding with no `statusField` provisions no VIEW (nothing to derive), but the
+   * reconciler still feeds the projections.
+   *
+   * The VIEW is a first-class readable pages surface, not a separate wiring step: `SqliteGateway.schema()`
+   * introspects views (`type IN ('table','view')`) and `/app/data/<source>/<view>` serves `SELECT *`
+   * verbatim, so an operator page reads the derived status simply by pointing its page `data.table` at
+   * this managed VIEW (which re-exports `base.*`, so it is a drop-in for the base table) and its column at
+   * `statusColumn`. This is opt-in by design: the base table stays readable carrying the worker-owned
+   * status; the runtime does NOT silently rebind every page off the base table.
+   */
+  readonly readModel?: {
+    /** Managed VIEW name (must be a SQL identifier and differ from the base table). */
+    readonly view?: string;
+    /** Derived effective-status column name in that VIEW (must be a SQL identifier). */
+    readonly statusColumn?: string;
+  };
 };
 
 /**

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

@@ -9,9 +9,17 @@ import { makeGateway } from "./gateway.ts";
 import type { Table } from "./gateway.ts";
 import { DataLayer, type ProvisionedSource } from "./datasource.ts";
 import type { AppApi } from "../context.ts";
-import type { EngineClient, ProcessInstanceSnapshot } from "../host.ts";
+import type { EngineClient, ProcessInstanceSnapshot, SqliteDb } from "../host.ts";
 import type { InstanceTracking } from "../manifest.ts";
 import { cancelInstanceReconciling } from "./cancel.ts";
+import { INSTANCE_STATE_TABLE } from "./instance-state-store.ts";
+
+// ADR 0065 — the instanceTracking writer→source inversion. Cancel no longer WRITES a terminal patch on
+// the base row; it records the terminal fact into the canonical `_urban_instance_state` projection
+// through the SAME `reconcileTerminatedKey` the poll reconciler uses (so cancel and poll cannot drift),
+// and the terminal status is DERIVED from the projection by the read model. These tests therefore assert
+// on the recorded projection state and `reconciled` (1 = terminal source recorded) — never a base-row
+// mutation.
 
 type State = ProcessInstanceSnapshot["state"];
 
@@ -27,8 +35,9 @@ interface PrRow {
   status: string;
 }
 
-// The pull_requests binding: an ACTIVE row flips to `abandoned` (and drops the process pointer)
-// when its instance terminates — the exact patch the poll reconciler applies.
+// The pull_requests binding: an ACTIVE row derives to `abandoned` when its instance terminates — the
+// value the derived terminal edge resolves to (no longer a stored patch). Cancel feeds the projection;
+// the read model derives the status.
 const PR_BINDING: InstanceTracking = {
   table: "pull_requests",
   keyField: "process_key",
@@ -85,6 +94,7 @@ function cancelEngine(opts: {
 interface Harness {
   api: AppApi;
   table: Table<PrRow>;
+  db: SqliteDb;
   logs: { level: string; msg: string }[];
   close: () => Promise<void>;
 }
@@ -120,6 +130,7 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
   return {
     api,
     table,
+    db,
     logs,
     close: async () => {
       db.close();
@@ -128,7 +139,22 @@ async function withHarness(engine: EngineClient, seedStatus = "converging"): Pro
   };
 }
 
-test("terminating a tracked instance reconciles its row immediately", async () => {
+/** The recorded engine lifecycle state for a key in the `_urban_instance_state` projection, or
+ *  undefined when it was never recorded. The projection table is created lazily by cancel's own
+ *  `ensureSchema`; return undefined if it does not exist yet (nothing was ever recorded). */
+function projectedState(db: SqliteDb, key: string): string | undefined {
+  try {
+    const rows = db.all<{ state: string }>(
+      `SELECT state FROM ${INSTANCE_STATE_TABLE} WHERE process_instance_key = ?`,
+      [key],
+    );
+    return rows[0]?.state;
+  } catch {
+    return undefined; // projection table not provisioned ⇒ nothing recorded
+  }
+}
+
+test("terminating a tracked instance records its terminal source immediately (no base write)", async () => {
   // cancelInstance succeeds (no throw) and the engine commits the termination.
   const { engine, cancels } = cancelEngine({
     states: { "100": "ACTIVE" },
@@ -143,19 +169,21 @@ test("terminating a tracked instance reconciles its row immediately", async () =
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
     assert.equal(r.reconciled, 1);
+    // The terminal fact was recorded into the canonical projection …
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
+    // … and the base row was left UNTOUCHED (source-not-writer); the derived read model surfaces the
+    // terminal status without a stored write.
     const row = await h.table.get("100");
-    assert.equal(row, undefined); // process_key was cleared to null, so no row keyed by "100"
-    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
-    assert.equal(byPr?.status, "abandoned");
-    assert.equal(byPr?.process_key, null);
+    assert.equal(row?.status, "converging");
+    assert.equal(row?.process_key, "100");
   } finally {
     await h.close();
   }
 });
 
-test("a cancel that throws but reads back TERMINATED is idempotent success + reconciles", async () => {
+test("a cancel that throws but reads back TERMINATED is idempotent success + records the source", async () => {
   // The instance was already terminated; the engine rejects a second cancel, but the verify read
-  // confirms it is gone — treat as success and still reconcile the (stale-active) row.
+  // confirms it is gone — treat as success and still record the terminal source.
   const { engine } = cancelEngine({
     states: { "100": "TERMINATED" },
     onCancel: () => {
@@ -168,14 +196,13 @@ test("a cancel that throws but reads back TERMINATED is idempotent success + rec
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
     assert.equal(r.reconciled, 1);
-    const byPr = (await h.table.all()).find((x) => x.pr_key === "pr-1");
-    assert.equal(byPr?.status, "abandoned");
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
   } finally {
     await h.close();
   }
 });
 
-test("a failed cancel with a still-ACTIVE instance is an honest failure and touches no row", async () => {
+test("a failed cancel with a still-ACTIVE instance is an honest failure and records nothing", async () => {
   const { engine } = cancelEngine({
     states: { "100": "ACTIVE" },
     onCancel: () => {
@@ -189,15 +216,38 @@ test("a failed cancel with a still-ACTIVE instance is an honest failure and touc
     assert.equal(r.state, "ACTIVE");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /permission denied/);
+    assert.equal(projectedState(h.db, "100"), undefined); // instance still running — nothing recorded
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // untouched — instance still running
+    assert.equal(row?.status, "converging"); // untouched
     assert.ok(h.logs.some((l) => l.level === "error"));
   } finally {
     await h.close();
   }
 });
 
-test("a COMPLETED instance is not reconciled (the app's finalize logic owns that row)", async () => {
+test("an accepted cancel that still reads ACTIVE (engine lag) records the terminal source", async () => {
+  // The engine accepted the 204 but its query store still lags at ACTIVE. The cancel IS committed, so
+  // the terminal source must be recorded now — otherwise the derived view stays on the stored worker
+  // status until a poll catches up (and never, if the instance is later cleaned up). accepted-cancel/lag.
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {}, // accepted (204); state deliberately NOT flipped, to model read-model lag
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // base row untouched (source-not-writer)
+  } finally {
+    await h.close();
+  }
+});
+
+test("a COMPLETED instance is not recorded (the app's finalize logic owns that outcome)", async () => {
   const { engine } = cancelEngine({
     states: { "100": "COMPLETED" },
     onCancel: () => {}, // engine accepts the request; instance had already completed
@@ -208,16 +258,17 @@ test("a COMPLETED instance is not reconciled (the app's finalize logic owns that
     assert.equal(r.ok, true);
     assert.equal(r.state, "COMPLETED");
     assert.equal(r.reconciled, 0);
+    assert.equal(projectedState(h.db, "100"), undefined); // COMPLETED never recorded here
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // left for the finalize worker, not clobbered
+    assert.equal(row?.status, "converging"); // left for the finalize worker
   } finally {
     await h.close();
   }
 });
 
-test("a gone/unknown instance is idempotent success with no reconcile", async () => {
+test("an accepted cancel that reads back gone (engine cleanup) records the terminal source", async () => {
   const { engine } = cancelEngine({
-    states: {}, // the engine has no record of this key
+    states: {}, // the engine no longer exposes the key (already cleaned up)
     onCancel: () => {},
   });
   const h = await withHarness(engine);
@@ -225,13 +276,21 @@ test("a gone/unknown instance is idempotent success with no reconcile", async ()
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "999999");
     assert.equal(r.ok, true);
     assert.equal(r.state, "gone");
-    assert.equal(r.reconciled, 0);
+    // The accepted 204 is a committed termination, so record the terminal source even though the read
+    // model no longer exposes the instance — otherwise the derived view could never leave the stored
+    // worker status (the poll cannot observe a gone instance either). accepted-cancel/read-lag.
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "999999"), "TERMINATED");
   } finally {
     await h.close();
   }
 });
 
-test("a TERMINATED instance with no matching binding row reconciles nothing", async () => {
+test("records the terminal source even when no base row matches (the projection is binding-independent)", async () => {
+  // Post-inversion the terminal fact is recorded into the canonical projection for the cancelled key
+  // regardless of which base rows reference it — the projection is the engine-truth store, and the
+  // derived read model only surfaces the fact for rows that point at the key (none here). This agrees
+  // with the poll path (both record TERMINATED for the same key), so they cannot drift.
   const { engine } = cancelEngine({
     states: { "555": "TERMINATED" },
     onCancel: () => {},
@@ -242,37 +301,47 @@ test("a TERMINATED instance with no matching binding row reconciles nothing", as
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "555");
     assert.equal(r.ok, true);
     assert.equal(r.state, "TERMINATED");
-    assert.equal(r.reconciled, 0);
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "555"), "TERMINATED");
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging");
+    assert.equal(row?.status, "converging"); // the unrelated tracked row is untouched
   } finally {
     await h.close();
   }
 });
 
-test("a reconcile write failure does not fail the cancel (the engine already terminated it)", async () => {
+test("cancel succeeds and records nothing when there is no default data source (absent-safe)", async () => {
+  // The projection feed is a sidecar on the app's own data source. With no default source there is
+  // nothing to record into — but a successful engine termination must STILL be reported as a success:
+  // a projection feed must never break a cancel. `reconcileTerminatedKey` is absent-safe (returns 0).
   const { engine } = cancelEngine({
     states: { "100": "ACTIVE" },
     onCancel: (key, states) => {
       states[key] = "TERMINATED";
     },
   });
-  const h = await withHarness(engine);
+  const dir = await mkdtemp(join(tmpdir(), "urban-cancel-nosrc-"));
+  const logs: { level: string; msg: string }[] = [];
+  const data = new DataLayer(new Map(), undefined, {}); // no default source configured
+  const api: AppApi = {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data,
+    engine,
+    env: () => undefined,
+    now: () => 0,
+    wait: () => Promise.resolve(),
+    log: createLogger((level, msg) => {
+      logs.push({ level, msg });
+    }),
+  };
   try {
-    // A binding pointing at a table that does not exist makes the reconcile UPDATE throw.
-    const badBinding: InstanceTracking = {
-      table: "does_not_exist",
-      keyField: "process_key",
-      onTerminated: { set: { status: "abandoned" } },
-    };
-    const r = await cancelInstanceReconciling(h.api, [badBinding], "100");
-    assert.equal(r.ok, true); // engine termination succeeded — the cancel is a success
+    const r = await cancelInstanceReconciling(api, [PR_BINDING], "100");
+    assert.equal(r.ok, true); // the engine termination committed — a success
     assert.equal(r.state, "TERMINATED");
-    assert.equal(r.reconciled, 0);
-    assert.ok(r.error); // the reconcile failure is surfaced, not swallowed
-    assert.ok(h.logs.some((l) => l.level === "error"));
+    assert.equal(r.reconciled, 0); // nothing to record into
+    assert.equal(r.error, undefined); // absent-safe: not surfaced as an error
   } finally {
-    await h.close();
+    await rm(dir, { recursive: true, force: true });
   }
 });
 
@@ -287,7 +356,10 @@ test("an accepted cancel whose verify read fails is trusted (gone) — the 204 c
     const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
     assert.equal(r.ok, true);
     assert.equal(r.state, "gone");
-    assert.equal(r.reconciled, 0);
+    // Accepted 204 → committed termination; record the terminal source even though the verify read
+    // could not confirm it (read-model lag / cleanup must not strand the derived status).
+    assert.equal(r.reconciled, 1);
+    assert.equal(projectedState(h.db, "100"), "TERMINATED");
     assert.ok(h.logs.some((l) => l.level === "warn"));
   } finally {
     await h.close();
@@ -309,6 +381,7 @@ test("a thrown cancel whose verify read also fails is reported as an honest fail
     assert.equal(r.state, "ACTIVE");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /transport error/);
+    assert.equal(projectedState(h.db, "100"), undefined);
     const row = await h.table.get("100");
     assert.equal(row?.status, "converging");
   } finally {
@@ -336,8 +409,9 @@ test("a thrown cancel whose verify read comes back empty (gone) is an unverified
     assert.equal(r.state, "gone");
     assert.equal(r.reconciled, 0);
     assert.match(r.error ?? "", /fetch failed/);
+    assert.equal(projectedState(h.db, "100"), undefined); // never record a possibly-live run as terminal
     const row = await h.table.get("100");
-    assert.equal(row?.status, "converging"); // never flip a possibly-live run to a terminal status
+    assert.equal(row?.status, "converging");
     assert.ok(h.logs.some((l) => l.level === "error"));
   } finally {
     await h.close();

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

@@ -6,21 +6,23 @@
 //   1. Report the *real* outcome. A cancel can fail (permissions, the instance already gone,
 //      a transport error). Swallowing that and reporting success leaves an instance running in
 //      the engine while the UI claims it stopped — the worst possible lie for a "cancel" button.
-//   2. Reconcile the tracked row immediately. Apps bind process instances to rows via
-//      `instanceTracking`; the poll reconciler flips a row to its terminal status within a few
-//      seconds of the instance terminating. When *we* are the one terminating it, we can apply
-//      that same declared patch right away instead of waiting for the next poll tick.
+//   2. Reconcile the tracked instance immediately. Apps bind process instances to rows via
+//      `instanceTracking`; since ADR 0065 the reconciler is a SOURCE, not a writer — its poll feeds
+//      engine truth into the canonical `urban_instance_state` projection and the terminal status edge
+//      is DERIVED from it (no stored column to tear; nano-workforce#422). When *we* are the one
+//      terminating the instance, we can record that same terminal source right away instead of waiting
+//      for the next poll tick, and the derived read model reflects it on the next read.
 //
 // This primitive keys success on the engine's response, then reconciles off the read model: a
 // non-throwing `cancelInstance` is a committed termination (trusted even if the read model still
 // lags at ACTIVE), while a throw that does not read back a positively-terminal state (still ACTIVE,
-// or absent from the read model) is an honest failure. It reuses the instanceTracking bindings'
-// `onTerminated.set` patch, so the immediate reconcile can never drift from the poll reconciler's.
+// or absent from the read model) is an honest failure. It records the terminal source through the
+// SAME `reconcileTerminatedKey` the poll reconciler uses, so cancel and poll can never drift.
 
 import type { AppApi } from "../context.ts";
 import type { InstanceTracking } from "../manifest.ts";
 import { errorMessage } from "../guards.ts";
-import { reconcileTerminatedKey } from "./instance-tracking.ts";
+import { reconcileTerminatedKey, tryInstanceProjections } from "./instance-tracking.ts";
 
 export type CancelInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED" | "gone";
 
@@ -30,7 +32,8 @@ export interface CancelInstanceResult {
   /** The instance state as read back from the engine after the cancel attempt.
    *  `"gone"` means the engine has no record of the key (already cleaned up / never existed). */
   state: CancelInstanceState;
-  /** Rows flipped to their terminal status by the immediate instanceTracking reconcile. */
+  /** 1 when the immediate reconcile recorded the terminal source into the canonical instance-state
+   *  projection (so the derived terminal status edge reflects it at once), else 0. */
   reconciled: number;
   error?: string;
 }
@@ -39,22 +42,26 @@ type CancelApi = Pick<AppApi, "engine" | "data" | "log">;
 
 /**
  * Cancel a process instance honestly: terminate it, verify it is actually gone, and immediately
- * reconcile any instanceTracking row bound to its key.
+ * record the terminal source for its key into the canonical instance-state projection.
  *
  * Outcome rules:
  *  - `cancelInstance` returns without throwing → the engine accepted the termination (a committed
- *    204); trust it even if the read model still lags at ACTIVE.
+ *    204); trust it even if the read model still lags at ACTIVE or has already cleaned the instance
+ *    up ("gone"), and record the terminal source for the key so the derived view flips at once.
  *  - `cancelInstance` throws but the instance reads back positively terminal (TERMINATED/COMPLETED)
- *    → the cancel was effectively idempotent; treat as success. Only a TERMINATED read reconciles a
- *    row here (see below); a COMPLETED read intentionally reconciles nothing.
+ *    → the cancel was effectively idempotent; treat as success. A TERMINATED read records a terminal
+ *    source here; a COMPLETED read intentionally records nothing.
  *  - `cancelInstance` throws and the read is NOT positively terminal — still ACTIVE, or "gone"
  *    (absent from the read model, which after an engine restart can transiently lack a live
- *    instance) → an honest failure: report it and do NOT touch any row (the instance may still be
+ *    instance) → an honest failure: report it and do NOT record anything (the instance may still be
  *    running). A throw is not a committed cancel, and absence from the read model is not proof of
  *    termination, so success is never inferred from it.
  *
- * Reconcile only on `TERMINATED`: a COMPLETED instance's terminal row-write is owned by the app's
- * own finalize logic, and a gone/ACTIVE instance has nothing to flip here.
+ * Record when the cancellation is CONFIRMED — an accepted (non-throwing) cancel of any non-COMPLETED
+ * readback (ACTIVE lag / gone / TERMINATED), or a throw that reads back TERMINATED. A COMPLETED
+ * instance's terminal outcome is owned by the app's own finalize logic, so it records nothing. When
+ * the app declares no `instanceTracking` bindings there is nothing to reconcile, so the feed is
+ * skipped.
  */
 export async function cancelInstanceReconciling(
   api: CancelApi,
@@ -81,7 +88,7 @@ export async function cancelInstanceReconciling(
     //     before it rehydrates, so "gone" is absence-of-evidence, NOT proof of termination.
     // Trust neither as success: claiming a cancel that may not have happened (while the run keeps
     // executing) is the worst possible lie for a cancel button. Report ok:false so the caller
-    // surfaces it and retries; never flip a tracked row to terminal while the instance may live.
+    // surfaces it and retries; never record a terminal source while the instance may live.
     api.log("error", "cancel: engine termination not confirmed, instance may still be active", {
       processInstanceKey: key,
       state,
@@ -91,14 +98,27 @@ export async function cancelInstanceReconciling(
   }
 
   let reconciled = 0;
-  if (state === "TERMINATED") {
+  // Record the terminal source whenever the cancellation is CONFIRMED — not only on a positively
+  // TERMINATED readback. An accepted (non-throwing) `cancelInstance` is a committed 204: the instance
+  // WILL terminate, even if the read model still lags at ACTIVE or the engine has already cleaned the
+  // instance up ("gone"). A throw that nonetheless reads back TERMINATED is idempotently confirmed too.
+  // Excluded: COMPLETED (its terminal outcome is owned by the app's own finalize logic) and the honest-
+  // failure case (a throw with a non-terminal read), which already returned ok:false above. Without
+  // recording on the accepted-but-lagging read, a committed cancel returned ok:true / reconciled:0 and
+  // the derived view stayed on the stored worker status until a poll caught up — and NEVER, if the
+  // engine no longer exposes the instance for the poll to observe (issue: accepted-cancel/read-lag).
+  const cancelConfirmed = !threw || state === "TERMINATED";
+  if (cancelConfirmed && state !== "COMPLETED" && bindings.length > 0) {
+    // Record through the SAME `reconcileTerminatedKey` the poll path uses, over the app's own
+    // projection stores, so cancel and poll can never drift. It is internally absent-safe and never
+    // throws through — a projection-write failure logs a warn and returns 0 rather than turning a
+    // successful engine termination into a 500; the poll reconciler catches the projection up on its
+    // next tick. The extra try/catch is belt-and-suspenders against a store construction fault.
     try {
-      reconciled = await reconcileTerminatedKey(api, bindings, key);
+      const projections = tryInstanceProjections(api);
+      reconciled = reconcileTerminatedKey(api, projections, key);
     } catch (error) {
-      // The engine termination itself succeeded — a reconcile *write* failure (bad binding,
-      // transient DB error) must not turn that into an unhandled 500. Log it and let the
-      // instanceTracking poll reconciler catch the row up on its next tick.
-      api.log("error", "cancel: instance terminated but row reconcile failed", {
+      api.log("error", "cancel: instance terminated but projection reconcile failed", {
         processInstanceKey: key,
         error: errorMessage(error),
       });