@nanobpm/urban 0.29.0 → 0.30.0

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

@@ -0,0 +1,310 @@
+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 { cancelInstanceReconciling } from "./cancel.ts";
+
+type State = ProcessInstanceSnapshot["state"];
+
+const PR_DDL = `CREATE TABLE pull_requests (
+  pr_key TEXT PRIMARY KEY,
+  process_key TEXT,
+  status TEXT NOT NULL
+);`;
+
+interface PrRow {
+  pr_key: string;
+  process_key: string | null;
+  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.
+const PR_BINDING: InstanceTracking = {
+  table: "pull_requests",
+  keyField: "process_key",
+  statusField: "status",
+  activeStatuses: ["converging"],
+  onTerminated: { set: { status: "abandoned", process_key: null } },
+};
+
+/** An EngineClient double for the cancel primitive. `cancelInstance` runs `onCancel` (which may
+ *  throw and/or mutate `states`); `searchProcessInstances` reflects the current `states` map, or
+ *  throws when `verifyThrows` is set (to exercise the unverifiable-read path). */
+function cancelEngine(opts: {
+  states: Record<string, State>;
+  onCancel: (key: string, states: Record<string, State>) => void;
+  verifyThrows?: boolean;
+}): { engine: EngineClient; cancels: string[] } {
+  const cancels: string[] = [];
+  const notUsed = (m: string) => (): never => {
+    throw new Error(`cancelEngine.${m} is not exercised by this test`);
+  };
+  const engine: EngineClient = {
+    async cancelInstance(args: { processInstanceKey: string }): Promise<void> {
+      cancels.push(args.processInstanceKey);
+      opts.onCancel(args.processInstanceKey, opts.states);
+    },
+    async searchProcessInstances(filter?: {
+      processInstanceKeys?: string[];
+      state?: State;
+    }): Promise<ProcessInstanceSnapshot[]> {
+      if (opts.verifyThrows) throw new Error("read model unavailable");
+      const keys = filter?.processInstanceKeys ?? [];
+      const out: ProcessInstanceSnapshot[] = [];
+      for (const key of keys) {
+        const state = opts.states[key];
+        if (state && (!filter?.state || filter.state === state)) {
+          out.push({ processInstanceKey: key, state });
+        }
+      }
+      return out;
+    },
+    deployResources: notUsed("deployResources"),
+    createInstance: notUsed("createInstance"),
+    publishMessage: notUsed("publishMessage"),
+    searchUserTasks: notUsed("searchUserTasks"),
+    completeUserTask: notUsed("completeUserTask"),
+    registerWorker: notUsed("registerWorker"),
+    close: notUsed("close"),
+  };
+  return { engine, cancels };
+}
+
+interface Harness {
+  api: AppApi;
+  table: Table<PrRow>;
+  logs: { level: string; msg: string }[];
+  close: () => Promise<void>;
+}
+
+async function withHarness(engine: EngineClient, seedStatus = "converging"): Promise<Harness> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-cancel-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "test.db"));
+  db.exec(PR_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 table = data.table<PrRow>("pull_requests", "process_key");
+  await table.insert({ pr_key: "pr-1", process_key: "100", status: seedStatus });
+  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,
+    logs,
+    close: async () => {
+      db.close();
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+test("terminating a tracked instance reconciles its row immediately", async () => {
+  // cancelInstance succeeds (no throw) and the engine commits the termination.
+  const { engine, cancels } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: (key, states) => {
+      states[key] = "TERMINATED";
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.deepEqual(cancels, ["100"]);
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 1);
+    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);
+  } finally {
+    await h.close();
+  }
+});
+
+test("a cancel that throws but reads back TERMINATED is idempotent success + reconciles", 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.
+  const { engine } = cancelEngine({
+    states: { "100": "TERMINATED" },
+    onCancel: () => {
+      throw new Error("instance is not active");
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    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");
+  } finally {
+    await h.close();
+  }
+});
+
+test("a failed cancel with a still-ACTIVE instance is an honest failure and touches no row", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {
+      throw new Error("permission denied");
+    },
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, false);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 0);
+    assert.match(r.error ?? "", /permission denied/);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // untouched — instance still running
+    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 () => {
+  const { engine } = cancelEngine({
+    states: { "100": "COMPLETED" },
+    onCancel: () => {}, // engine accepts the request; instance had already completed
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "COMPLETED");
+    assert.equal(r.reconciled, 0);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging"); // left for the finalize worker, not clobbered
+  } finally {
+    await h.close();
+  }
+});
+
+test("a gone/unknown instance is idempotent success with no reconcile", async () => {
+  const { engine } = cancelEngine({
+    states: {}, // the engine has no record of this key
+    onCancel: () => {},
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "999999");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "gone");
+    assert.equal(r.reconciled, 0);
+  } finally {
+    await h.close();
+  }
+});
+
+test("a TERMINATED instance with no matching binding row reconciles nothing", async () => {
+  const { engine } = cancelEngine({
+    states: { "555": "TERMINATED" },
+    onCancel: () => {},
+  });
+  const h = await withHarness(engine);
+  try {
+    // "555" matches no row (the seeded row tracks "100").
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "555");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "TERMINATED");
+    assert.equal(r.reconciled, 0);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging");
+  } finally {
+    await h.close();
+  }
+});
+
+test("a reconcile write failure does not fail the cancel (the engine already terminated it)", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: (key, states) => {
+      states[key] = "TERMINATED";
+    },
+  });
+  const h = await withHarness(engine);
+  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
+    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"));
+  } finally {
+    await h.close();
+  }
+});
+
+test("an accepted cancel whose verify read fails is trusted (gone) — the 204 committed", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {}, // accepted
+    verifyThrows: true,
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, true);
+    assert.equal(r.state, "gone");
+    assert.equal(r.reconciled, 0);
+    assert.ok(h.logs.some((l) => l.level === "warn"));
+  } finally {
+    await h.close();
+  }
+});
+
+test("a thrown cancel whose verify read also fails is reported as an honest failure", async () => {
+  const { engine } = cancelEngine({
+    states: { "100": "ACTIVE" },
+    onCancel: () => {
+      throw new Error("transport error");
+    },
+    verifyThrows: true,
+  });
+  const h = await withHarness(engine);
+  try {
+    const r = await cancelInstanceReconciling(h.api, [PR_BINDING], "100");
+    assert.equal(r.ok, false);
+    assert.equal(r.state, "ACTIVE");
+    assert.equal(r.reconciled, 0);
+    assert.match(r.error ?? "", /transport error/);
+    const row = await h.table.get("100");
+    assert.equal(row?.status, "converging");
+  } finally {
+    await h.close();
+  }
+});

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

@@ -0,0 +1,119 @@
+// The Urban-native "cancel a process instance" primitive.
+//
+// Cancelling a running process from a page action must do two honest things that a bare
+// `engine.cancelInstance` call does not:
+//
+//   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.
+//
+// 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 whose instance reads back still-ACTIVE is an honest failure. It
+// reuses the instanceTracking bindings' `onTerminated.set` patch, so the immediate reconcile can
+// never drift from the poll reconciler's.
+
+import type { AppApi } from "../context.ts";
+import type { InstanceTracking } from "../manifest.ts";
+import { errorMessage } from "../guards.ts";
+import { reconcileTerminatedKey } from "./instance-tracking.ts";
+
+export type CancelInstanceState = "ACTIVE" | "COMPLETED" | "TERMINATED" | "gone";
+
+export interface CancelInstanceResult {
+  ok: boolean;
+  processInstanceKey: string;
+  /** 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. */
+  reconciled: number;
+  error?: string;
+}
+
+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.
+ *
+ * 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.
+ *  - `cancelInstance` throws but the instance reads back non-ACTIVE (already TERMINATED/COMPLETED
+ *    /gone) → the cancel was effectively idempotent; treat as success.
+ *  - `cancelInstance` throws and the instance is still ACTIVE → an honest failure: report it and
+ *    do NOT touch any row (the instance is still running).
+ *
+ * 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.
+ */
+export async function cancelInstanceReconciling(
+  api: CancelApi,
+  bindings: InstanceTracking[],
+  processInstanceKey: string,
+): Promise<CancelInstanceResult> {
+  const key = String(processInstanceKey);
+
+  let threw: unknown;
+  try {
+    await api.engine.cancelInstance({ processInstanceKey: key });
+  } catch (error) {
+    threw = error;
+  }
+
+  const state = await readState(api, key, threw);
+
+  if (threw && state === "ACTIVE") {
+    // The cancel genuinely failed and the instance is still running — never flip a row to a
+    // terminal status while the engine keeps executing it.
+    api.log("error", "cancel: engine termination failed, instance still active", {
+      processInstanceKey: key,
+      error: errorMessage(threw),
+    });
+    return { ok: false, processInstanceKey: key, state, reconciled: 0, error: errorMessage(threw) };
+  }
+
+  let reconciled = 0;
+  if (state === "TERMINATED") {
+    try {
+      reconciled = await reconcileTerminatedKey(api, bindings, 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", {
+        processInstanceKey: key,
+        error: errorMessage(error),
+      });
+      return { ok: true, processInstanceKey: key, state, reconciled: 0, error: errorMessage(error) };
+    }
+  }
+
+  return { ok: true, processInstanceKey: key, state, reconciled };
+}
+
+/** Read the instance state back from the engine to verify what actually happened. When the read
+ *  itself fails we fall back to the cancel call's own result: a thrown cancel with an unverifiable
+ *  state is reported as still-ACTIVE (honest worst case); an accepted cancel is trusted as gone. */
+async function readState(
+  api: CancelApi,
+  key: string,
+  threw: unknown,
+): Promise<CancelInstanceState> {
+  try {
+    const [snapshot] = await api.engine.searchProcessInstances({ processInstanceKeys: [key] });
+    if (snapshot) return snapshot.state;
+    return "gone";
+  } catch (error) {
+    api.log("warn", "cancel: could not verify post-cancel state", {
+      processInstanceKey: key,
+      error: errorMessage(error),
+    });
+    return threw ? "ACTIVE" : "gone";
+  }
+}

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

@@ -13,6 +13,7 @@ import {
   type InsertObserver,
 } from "./gateway.ts";
 import { currentJobContext } from "../execContext.ts";
+import { isAbsolutePath } from "../../../toolkit/artifact.ts";
 
 export function sqlitePathFromUrl(url: string): string {
   // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -25,10 +26,10 @@ export function sqlitePathFromUrl(url: string): string {
  * that starts with a single backslash ("\data\app.db") and a Windows UNC path
  * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
  * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
- * path is never incorrectly prefixed with the app root. */
-export function isAbsolutePath(p: string): boolean {
-  return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
-}
+ * path is never incorrectly prefixed with the app root. Defined once in `toolkit/artifact.ts` (the
+ * shared, dependency-free layer) and re-exported here so the toolkit's gen path-join and this
+ * runtime resolver apply the identical rule (no gen/runtime drift). */
+export { isAbsolutePath };
 
 /** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
  * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so

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

@@ -27,6 +27,35 @@ export interface InstanceTrackingHandle extends Mounted {
 
 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. */
@@ -70,21 +99,14 @@ async function reconcileOnce(
     state: "TERMINATED",
   });
 
-  const patch: Partial<Row> = binding.onTerminated.set;
+  // 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
-    const changed = await table.update(snap.processInstanceKey, patch);
-    if (changed > 0) {
-      reconciled += changed;
-      api.log("info", "instanceTracking: reconciled terminated instance", {
-        table: binding.table,
-        keyField: binding.keyField,
-        processInstanceKey: snap.processInstanceKey,
-        rowsChanged: changed,
-      });
-    }
+    reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
   }
   return { scanned: keys.length, reconciled };
 }

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,
@@ -61,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) => {
@@ -74,6 +74,7 @@ function build(dbOverrides: Partial<PagesDataSource> = {}) {
     engine,
     readPage,
     listPages: async () => ["home", "epic"],
+    ...deps,
   });
   const router = makeRouter(routes);
   return { router, calls };
@@ -356,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";

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

@@ -6,6 +6,7 @@
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
 import { mountActions } from "./actions.ts";
+import { mountApi } from "./api.ts";
 import { mountPages } from "./pages.ts";
 
 /** Escape HTML-significant characters before embedding a value in markup. */
@@ -109,6 +110,15 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
     enabled.push(`actions(${actions.routes.length})`);
   }
 
+  // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
+  // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+  // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
+  const api = mountApi(ctx, app);
+  if (api.routes.length > 0) {
+    routes.push(...api.routes);
+    enabled.push("api");
+  }
+
   // The pages surface (the schema-driven page runtime) mounts its own routes.
   const pages = mountPages(ctx, app);
   if (pages.routes.length > 0) {