@nanobpm/urban 0.28.0 → 0.30.0

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -0,0 +1,345 @@
+import { 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 { 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 { InstanceTracking } from "../manifest.ts";
+import {
+  DEFAULT_INSTANCE_TRACKING_POLL_MS,
+  mountInstanceTracking,
+} from "./instance-tracking.ts";
+import { MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+
+// A real-timer flush drains the entire pending microtask chain (find → engine → update)
+// each time a fake timer fires — deeper than a fixed number of `await Promise.resolve()`s.
+const realSetTimeout = globalThis.setTimeout;
+const flush = () => new Promise<void>((r) => realSetTimeout(r, 0));
+
+// A deterministic timer + clock seam (mirrors triggers.test.ts): `advance` fires every due
+// timer in order, draining microtasks between fires so the async reconcile completes.
+function fakeScheduler(): SchedulerDeps & { advance: (ms: number) => Promise<void>; pending: () => number } {
+  let clock = 0;
+  let seq = 0;
+  const timers = new Map<number, { at: number; fn: () => void }>();
+  return {
+    now: () => clock,
+    setTimer: (fn, delayMs) => {
+      const id = ++seq;
+      timers.set(id, { at: clock + delayMs, fn });
+      return id;
+    },
+    clearTimer: (h) => {
+      if (typeof h === "number") timers.delete(h);
+    },
+    pending: () => timers.size,
+    advance: async (ms) => {
+      const target = clock + ms;
+      // deno-lint-ignore no-constant-condition
+      while (true) {
+        let nextId = -1;
+        let nextAt = Infinity;
+        for (const [id, t] of timers) {
+          if (t.at <= target && t.at < nextAt) {
+            nextAt = t.at;
+            nextId = id;
+          }
+        }
+        if (nextId < 0) break;
+        const t = timers.get(nextId)!;
+        timers.delete(nextId);
+        clock = t.at;
+        t.fn();
+        await flush();
+      }
+      clock = target;
+    },
+  };
+}
+
+/** An EngineClient whose only live method is searchProcessInstances, driven by a fixed map of
+ *  processInstanceKey → state. Records the keys asked for on each call. */
+function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
+  engine: EngineClient;
+  queries: string[][];
+} {
+  const queries: string[][] = [];
+  const notUsed = (m: string) => (): never => {
+    throw new Error(`fakeEngine.${m} is not exercised by this test`);
+  };
+  // Typed as EngineClient (not `as unknown as`) so the compiler enforces the full contract:
+  // if EngineClient gains/changes a method, this fake fails to compile instead of drifting.
+  const engine: EngineClient = {
+    async searchProcessInstances(filter?: {
+      processInstanceKeys?: string[];
+      state?: ProcessInstanceSnapshot["state"];
+    }): Promise<ProcessInstanceSnapshot[]> {
+      const keys = filter?.processInstanceKeys ?? [];
+      queries.push([...keys]);
+      const out: ProcessInstanceSnapshot[] = [];
+      for (const key of keys) {
+        const state = states[key];
+        if (state && (!filter?.state || filter.state === state)) {
+          out.push({ processInstanceKey: key, state });
+        }
+      }
+      return out;
+    },
+    deployResources: notUsed("deployResources"),
+    createInstance: notUsed("createInstance"),
+    cancelInstance: notUsed("cancelInstance"),
+    publishMessage: notUsed("publishMessage"),
+    searchUserTasks: notUsed("searchUserTasks"),
+    completeUserTask: notUsed("completeUserTask"),
+    registerWorker: notUsed("registerWorker"),
+    close: notUsed("close"),
+  };
+  return { engine, queries };
+}
+
+interface Harness {
+  api: AppApi;
+  table: Table<PlanRow>;
+  dir: string;
+  close: () => Promise<void>;
+  logs: { level: string; msg: string }[];
+}
+
+// The row shape every test seeds (matches PLANS_DDL); typing the harness table with it lets
+// `table.get(...)` return a typed row instead of the generic `object` constraint that
+// `ReturnType<DataLayer["table"]>` collapses to.
+interface PlanRow {
+  plan_key: string;
+  process_key: string | null;
+  status: string;
+  note: string | null;
+}
+
+async function withHarness(
+  engine: EngineClient,
+  ddl: string,
+  seed: (t: Table<PlanRow>) => Promise<void>,
+  keyField = "process_key",
+  table = "plans",
+): Promise<Harness> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-instance-tracking-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec(ddl);
+  const source: ProvisionedSource = {
+    name: "app",
+    driver: "sqlite",
+    db,
+    source: makeGateway(db),
+    migrationsApplied: [],
+    close: () => db.close(),
+  };
+  const data = new DataLayer(new Map([["app", source]]), "app", {});
+  const tbl = data.table<PlanRow>(table, keyField);
+  await seed(tbl);
+  const logs: { level: string; msg: string }[] = [];
+  const api: AppApi = {
+    manifest: { schemaVersion: 1, id: "app", name: "App" },
+    data,
+    engine,
+    env: () => undefined,
+    log: (level, msg) => logs.push({ level, msg }),
+  };
+  return {
+    api,
+    table: tbl,
+    dir,
+    logs,
+    close: async () => {
+      db.close();
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+const PLANS_DDL =
+  "CREATE TABLE plans (plan_key TEXT PRIMARY KEY, process_key TEXT, status TEXT NOT NULL, note TEXT)";
+
+const planBinding = (over: Partial<InstanceTracking> = {}): InstanceTracking => ({
+  table: "plans",
+  keyField: "process_key",
+  statusField: "status",
+  activeStatuses: ["planning", "dispatched"],
+  onTerminated: { set: { status: "abandoned", note: null } },
+  pollMs: 1000,
+  ...over,
+});
+
+test("reconciles an active row whose instance is TERMINATED", async () => {
+  const { engine } = fakeEngine({ pi1: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "abandoned");
+  assert.equal(row?.note, null);
+  await handle.stop();
+  await h.close();
+});
+
+test("leaves an active row whose instance is still ACTIVE untouched", async () => {
+  const { engine } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "dispatched");
+  await handle.stop();
+  await h.close();
+});
+
+test("does NOT reconcile a COMPLETED instance (a finalize worker owns that row)", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "COMPLETED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: "hi" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "dispatched"); // untouched
+  // and it did ask the engine, filtered to TERMINATED
+  assert.deepEqual(queries, [["pi1"]]);
+  await handle.stop();
+  await h.close();
+});
+
+test("only polls rows in an active status (skips already-terminal rows)", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "abandoned", note: null }); // terminal
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries, [["pi1"]]); // pi2 was already terminal, never polled
+  await handle.stop();
+  await h.close();
+});
+
+test("skips rows whose key column is null/empty", async () => {
+  const { engine, queries } = fakeEngine({});
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: null, status: "dispatched", note: null });
+    await t.insert({ plan_key: "p2", process_key: "", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  assert.equal(queries.length, 0); // no keys to poll → no engine call
+  await handle.stop();
+  await h.close();
+});
+
+test("re-arms after each tick and stops cleanly", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched);
+  await sched.advance(1000);
+  await sched.advance(1000);
+  await sched.advance(1000);
+  assert.equal(queries.length, 3); // polled once per interval
+  assert.equal(sched.pending(), 1); // one timer armed for the next tick
+  await handle.stop();
+  assert.equal(sched.pending(), 0); // stop() cleared it
+  await h.close();
+});
+
+test("without statusField/activeStatuses, polls every row", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "TERMINATED", pi2: "TERMINATED" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "abandoned", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi2", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ statusField: undefined, activeStatuses: undefined });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(1000);
+  assert.deepEqual(queries[0]?.sort(), ["pi1", "pi2"]);
+  // both got reconciled (already-abandoned p1 is a no-op change, p2 flips)
+  assert.equal((await h.table.get("pi2"))?.status, "abandoned");
+  await handle.stop();
+  await h.close();
+});
+
+test("defaults pollMs when the binding omits it", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const binding = planBinding({ pollMs: undefined });
+  const handle = mount(h, [binding], sched);
+  await sched.advance(DEFAULT_INSTANCE_TRACKING_POLL_MS - 1);
+  assert.equal(queries.length, 0); // not yet
+  await sched.advance(1);
+  assert.equal(queries.length, 1); // fired at the default interval
+  await handle.stop();
+  await h.close();
+});
+
+test("clamps a pollMs beyond setTimeout's 32-bit range instead of firing immediately", async () => {
+  const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  // A pollMs past the 32-bit signed range would overflow setTimeout and fire at ~0 (a hot loop).
+  const handle = mount(h, [planBinding({ pollMs: MAX_TIMER_DELAY_MS * 3 })], sched);
+  await sched.advance(1000);
+  assert.equal(queries.length, 0); // did NOT fire immediately …
+  await sched.advance(MAX_TIMER_DELAY_MS);
+  assert.equal(queries.length, 1); // … it fired at the clamped delay
+  await handle.stop();
+  await h.close();
+});
+
+// A binding mounted without validation (or with a hand-built binding) must not become a
+// 0-delay hot loop when pollMs is non-positive/NaN — it falls back to the default interval.
+for (const bad of [0, -1000, Number.NaN]) {
+  test(`falls back to the default interval for a non-positive/NaN pollMs (${bad})`, async () => {
+    const { engine, queries } = fakeEngine({ pi1: "ACTIVE" });
+    const h = await withHarness(engine, PLANS_DDL, async (t) => {
+      await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+    });
+    const sched = fakeScheduler();
+    const handle = mount(h, [planBinding({ pollMs: bad })], sched);
+    await sched.advance(DEFAULT_INSTANCE_TRACKING_POLL_MS - 1);
+    assert.equal(queries.length, 0); // did NOT hot-loop at ~0 …
+    await sched.advance(1);
+    assert.equal(queries.length, 1); // … it fired at the default interval instead
+    await handle.stop();
+    await h.close();
+  });
+}
+
+
+function mount(h: Harness, bindings: InstanceTracking[], sched: SchedulerDeps) {
+  h.api.manifest.instanceTracking = bindings;
+  return mountInstanceTracking(
+    // biome-ignore lint/plugin: RuntimeContext test double — mountInstanceTracking reads only manifest/engine/root; host is unused here.
+    { manifest: h.api.manifest, host: {} as never, engine: h.api.engine, root: "." },
+    h.api,
+    sched,
+  );
+}

package/src/runtime/core/modules/instance-tracking.ts

@@ -0,0 +1,180 @@
+// instance-tracking — the process-instance lifecycle reconciler (manifest `instanceTracking`).
+//
+// The problem it closes: an Urban app derives a row's status from the workers that run
+// along a process's *happy path*. When an instance instead reaches a terminal state with
+// no completion job — an operator/`cancelInstance` termination, or a crash — no worker
+// runs, so the read-model row stays "active" forever and any UI derived from it lies.
+//
+// Each `instanceTracking` binding names a datasource table whose rows track an instance by
+// a key column. This module polls the engine for those rows' instances and, when one is
+// `TERMINATED`, applies the binding's `onTerminated.set` patch to the row. It deliberately
+// reconciles only on `TERMINATED` — the state that by definition runs no completion worker
+// — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
+// (reconciling it here would race that worker and could clobber a legitimately-completed
+// row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
+
+/** Default poll interval when a binding does not set `pollMs`. */
+export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
+
+export interface InstanceTrackingHandle extends Mounted {
+  /** `table.keyField` labels of the armed bindings, for `inspect()`. */
+  readonly bindings: string[];
+}
+
+type Row = Record<string, unknown>;
+
+/** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
+ *  Only the binding whose table owns that key has a matching row, so callers can fan this over
+ *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
+ *  writes the terminal patch (and logs the reconcile): both the poll reconciler below (`reconcileOnce`,
+ *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
+ *  instance) route through here, so the two can never drift on the patch or the log. */
+export async function reconcileTerminatedKey(
+  api: Pick<AppApi, "data" | "log">,
+  bindings: InstanceTracking[],
+  processInstanceKey: string,
+): Promise<number> {
+  const key = String(processInstanceKey);
+  let reconciled = 0;
+  for (const binding of bindings) {
+    const table = api.data.table<Row>(binding.table, binding.keyField);
+    const changed = await table.update(key, binding.onTerminated.set);
+    if (changed > 0) {
+      reconciled += changed;
+      api.log("info", "instanceTracking: reconciled terminated instance", {
+        table: binding.table,
+        keyField: binding.keyField,
+        processInstanceKey: key,
+        rowsChanged: changed,
+      });
+    }
+  }
+  return reconciled;
+}
+
+/** Poll one binding's instances once. Selects the active rows, asks the engine which of their
+ *  instances are TERMINATED, and applies `onTerminated.set` to each. Returns how many keys were
+ *  scanned and how many rows were reconciled this tick. */
+async function reconcileOnce(
+  api: AppApi,
+  binding: InstanceTracking,
+): Promise<{ scanned: number; reconciled: number }> {
+  const table = api.data.table<Row>(binding.table, binding.keyField);
+
+  // Select the rows worth polling. With a statusField + activeStatuses, only rows in an
+  // active status are candidates, so a row already in a terminal status is skipped; without
+  // them every row is polled and a terminal instance's row is idempotently re-patched (the
+  // engine query returns only TERMINATED instances and the patch is a no-op once applied).
+  let candidates: Row[];
+  const statusField = binding.statusField;
+  if (statusField && binding.activeStatuses && binding.activeStatuses.length > 0) {
+    const perStatus = await Promise.all(
+      binding.activeStatuses.map((s): Promise<Row[]> => table.find({ [statusField]: s })),
+    );
+    candidates = perStatus.flat();
+  } else {
+    candidates = await table.all();
+  }
+
+  // Map each active row to its tracked instance key. A row with no/empty key can't be
+  // reconciled (it never started an instance, or the column is unset) — skip it.
+  const keyToRows = new Map<string, Row[]>();
+  for (const row of candidates) {
+    const raw = row[binding.keyField];
+    if (raw == null || raw === "") continue;
+    const key = String(raw);
+    const list = keyToRows.get(key);
+    if (list) list.push(row);
+    else keyToRows.set(key, [row]);
+  }
+  const keys = [...keyToRows.keys()];
+  if (keys.length === 0) return { scanned: 0, reconciled: 0 };
+
+  const snapshots = await api.engine.searchProcessInstances({
+    processInstanceKeys: keys,
+    state: "TERMINATED",
+  });
+
+  // Apply the terminal patch through the shared `reconcileTerminatedKey` — the one place that
+  // writes `onTerminated.set` and logs the reconcile — so the poll path and the cancel primitive
+  // can never drift on the patch or its logging (No Drift Surfaces).
+  let reconciled = 0;
+  for (const snap of snapshots) {
+    if (snap.state !== "TERMINATED") continue; // defensive; we asked for TERMINATED only
+    if (!keyToRows.has(snap.processInstanceKey)) continue; // not one we were tracking
+    reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
+  }
+  return { scanned: keys.length, reconciled };
+}
+
+/**
+ * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
+ * the active rows, asks the engine which of their instances are terminated, and applies the
+ * declared patch. `stop()` cancels every armed timer.
+ */
+export function mountInstanceTracking(
+  ctx: RuntimeContext,
+  api: AppApi,
+  sched: SchedulerDeps = defaultScheduler(),
+): InstanceTrackingHandle {
+  const bindings = ctx.manifest.instanceTracking ?? [];
+  const timers = new Set<unknown>();
+  const armed: string[] = [];
+  let stopped = false;
+
+  for (const binding of bindings) {
+    // `pollMs` feeds a self-rescheduling timer, so a non-number/NaN/zero/negative value would
+    // clamp to a 0-delay hot loop. `??` only guards null/undefined; sanitize to a finite positive
+    // number and otherwise fall back to the default. (Manifest validation rejects bad values up
+    // front; this is belt-and-suspenders for a binding mounted without validation.)
+    const rawPoll = binding.pollMs;
+    const pollMs = typeof rawPoll === "number" && Number.isFinite(rawPoll) && rawPoll > 0
+      ? rawPoll
+      : DEFAULT_INSTANCE_TRACKING_POLL_MS;
+    // A single setTimeout delay overflows its 32-bit signed range (~24.8 days) and fires
+    // immediately — which for a self-rescheduling poll would become a hot loop. Clamp through
+    // the one shared constant the cron trigger loop uses (derive-don't-duplicate).
+    const delayMs = Math.min(pollMs, MAX_TIMER_DELAY_MS);
+    const label = `${binding.table}.${binding.keyField}`;
+    armed.push(label);
+
+    const arm = (): void => {
+      if (stopped) return;
+      let handle: unknown;
+      handle = sched.setTimer(() => {
+        timers.delete(handle);
+        if (stopped) return;
+        void (async () => {
+          try {
+            await reconcileOnce(api, binding);
+          } catch (err) {
+            api.log("error", `instanceTracking "${label}": reconcile failed`, {
+              error: String(err),
+            });
+          } finally {
+            arm(); // reschedule regardless of outcome (at-least-once, idempotent)
+          }
+        })();
+      }, delayMs);
+      timers.add(handle);
+    };
+    arm();
+  }
+
+  return {
+    name: "instanceTracking",
+    bindings: armed,
+    async stop(): Promise<void> {
+      stopped = true;
+      for (const h of timers) sched.clearTimer(h);
+      timers.clear();
+    },
+    describe(): Record<string, unknown> {
+      return { bindings: armed };
+    },
+  };
+}

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

@@ -2,7 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import type { EngineClient, HttpRequest, HttpResponse } from "../host.ts";
 import { makeRouter } from "../router.ts";
-import { createPagesRoutes, type PagesDataSource } from "./pages.ts";
+import { createPagesRoutes, type PagesDataSource, type PagesDeps } from "./pages.ts";
 
 function req(
   method: string,
@@ -41,6 +41,7 @@ function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
     },
     async searchUserTasks() { return []; },
     async completeUserTask() {},
+    async searchProcessInstances() { return []; },
     async registerWorker(jobType) { return { jobType, unsubscribe: async () => {} }; },
     async close() {},
   };
@@ -60,7 +61,7 @@ function fakeDb(overrides: Partial<PagesDataSource> = {}): PagesDataSource {
   };
 }
 
-function build(dbOverrides: Partial<PagesDataSource> = {}) {
+function build(dbOverrides: Partial<PagesDataSource> = {}, deps: Partial<PagesDeps> = {}) {
   const { engine, calls } = fakeEngine();
   const db = fakeDb(dbOverrides);
   const readPage = async (path: string) => {
@@ -73,6 +74,7 @@ function build(dbOverrides: Partial<PagesDataSource> = {}) {
     engine,
     readPage,
     listPages: async () => ["home", "epic"],
+    ...deps,
   });
   const router = makeRouter(routes);
   return { router, calls };
@@ -355,6 +357,49 @@ test("POST /app/actions/cancel cancels, 400 without a key", async () => {
   assert.equal(bad.status, 400);
 });
 
+test("POST /app/actions/cancel uses the injected cancel primitive and returns its result", async () => {
+  const seen: string[] = [];
+  const cancel: PagesDeps["cancel"] = async (key) => {
+    seen.push(key);
+    return { ok: true, processInstanceKey: key, state: "TERMINATED", reconciled: 1 };
+  };
+  const { router } = build({}, { cancel });
+  const res = await router(req("POST", "/app/actions/cancel", { body: { processInstanceKey: "pi-7" } }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(seen, ["pi-7"]);
+  assert.deepEqual(JSON.parse(res.body ?? "{}"), {
+    ok: true,
+    processInstanceKey: "pi-7",
+    state: "TERMINATED",
+    reconciled: 1,
+  });
+});
+
+test("POST /app/actions/cancel surfaces a 502 when the cancel primitive reports failure", async () => {
+  const cancel: PagesDeps["cancel"] = async (key) => ({
+    ok: false,
+    processInstanceKey: key,
+    state: "ACTIVE",
+    reconciled: 0,
+    error: "engine rejected the cancellation",
+  });
+  const { router } = build({}, { cancel });
+  const res = await router(req("POST", "/app/actions/cancel", { body: { processInstanceKey: "pi-8" } }));
+  assert.equal(res.status, 502);
+  assert.equal(JSON.parse(res.body ?? "{}").ok, false);
+  assert.match(JSON.parse(res.body ?? "{}").error, /engine rejected/);
+});
+
+test("POST /app/actions/cancel maps a throwing cancel primitive to a 502", async () => {
+  const cancel: PagesDeps["cancel"] = async () => {
+    throw new Error("boom");
+  };
+  const { router } = build({}, { cancel });
+  const res = await router(req("POST", "/app/actions/cancel", { body: { processInstanceKey: "pi-x" } }));
+  assert.equal(res.status, 502);
+  assert.equal(JSON.parse(res.body ?? "{}").ok, false);
+});
+
 test("POST /app/actions/message publishes, 400 on missing fields", async () => {
   const { router, calls } = build();
   const ok = await router(req("POST", "/app/actions/message", {

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

@@ -19,6 +19,7 @@ import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
 import type { EngineClient } from "../host.ts";
 import { html, json, type Route } from "../router.ts";
+import { cancelInstanceReconciling, type CancelInstanceResult } from "./cancel.ts";
 import { quoteIdent } from "./gateway.ts";
 
 /** The subset of the datasource gateway the page runtime needs. */
@@ -49,6 +50,13 @@ export interface PagesDeps {
    * Optional; when absent the index is empty. Injectable for tests.
    */
   listPages?(): Promise<string[]>;
+  /**
+   * Cancel a process instance honestly: terminate it, verify it is actually gone, and reconcile
+   * any `instanceTracking` row bound to its key. Injected by `mountPages` (bound to the app's
+   * engine, datasource, and instanceTracking bindings). When absent, the `/app/actions/cancel`
+   * route falls back to a bare `engine.cancelInstance` (used by tests that inject no cancel dep).
+   */
+  cancel?(processInstanceKey: string): Promise<CancelInstanceResult>;
 }
 
 /** A JavaScript-body response (the renderer module served at /app/runtime.js). */
@@ -70,7 +78,7 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
   const rowLimitRaw = opts.rowLimit ?? 200;
   const rowLimit = Number.isFinite(rowLimitRaw) ? Math.max(0, Math.floor(rowLimitRaw)) : 200;
   const sourceName = opts.sourceName ?? "app";
-  const { db, engine, readPage, listPages } = deps;
+  const { db, engine, readPage, listPages, cancel } = deps;
 
   // The table-name whitelist is memoised: an Urban app runs its migrations at boot
   // (before serving), so the schema is stable for the process lifetime, and the renderer
@@ -285,6 +293,18 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
         return json({ error: "body must be JSON" }, 400);
       }
       if (key === undefined || key === "") return json({ error: "processInstanceKey is required" }, 400);
+      // The reconcile-aware primitive verifies the real post-cancel state and flips the tracked
+      // row immediately; a !ok result means the engine did NOT stop the instance, so surface 502.
+      if (cancel) {
+        try {
+          const result = await cancel(String(key));
+          return json(result, result.ok ? 200 : 502);
+        } catch (e) {
+          // Defensive: the primitive is designed not to throw, but if it ever does, mirror the
+          // fallback path's honest 502 rather than letting the request reject as a 500.
+          return json({ ok: false, processInstanceKey: String(key), error: errorMessage(e) }, 502);
+        }
+      }
       try {
         await engine.cancelInstance({ processInstanceKey: String(key) });
         return json({ ok: true });
@@ -354,9 +374,11 @@ export function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle {
     sourceName: typeof decl.sourceName === "string" ? decl.sourceName : undefined,
   };
   const sourceName = opts.sourceName ?? "app";
+  const bindings = ctx.manifest.instanceTracking ?? [];
   const routes = createPagesRoutes(opts, {
     db: app.data.open(sourceName),
     engine: app.engine,
+    cancel: (key) => cancelInstanceReconciling(app, bindings, key),
     readPage: (p) => ctx.host.readTextFile(p),
     listPages: async () => {
       const dir = opts.pagesDir ?? "pages";