@nanobpm/nano-workforce 0.128.0 → 0.129.1

package/app/mergeLoopBehaviour.test.ts

@@ -0,0 +1,446 @@
+// Behavioural coverage for the sub-process merge-loop (issue #466).
+//
+// The merge-loop was refactored from a flat state machine into sub-processes
+// (`SP_cifix`, `SP_rebase`) whose outcomes are propagated to the top level via
+// end-event `ciOutcome`/`rebaseOutcome` output mappings and re-discriminated by
+// `gw-ci-outcome`/`gw-rebase-outcome`. The previous merge guards were *structural
+// text assertions* over the flat topology; they broke by construction under any
+// re-shaping and re-encoded the model's shape rather than its behaviour.
+//
+// Per direction (issue #466) these are replaced with **behavioural** tests that
+// deploy the committed model into the real WASM engine (`@nanobpm/urban-testkit`)
+// and drive tokens through it, asserting the observable invariant — activated
+// jobs, taken outcomes, terminal state, escalations, budget counters — so they
+// protect what the loop *does*, not how it is drawn. The invariants preserved
+// here are exactly those the retired guards protected:
+//   - mergeRetryArm (#334): transient-retry arm re-arms within budget, escalates
+//     when exhausted, advances the attempt counter only on a retry, no agent.
+//   - mergeCiReattempt (#134): fix-ci `reattempt`/no-verdict re-arms (never pages
+//     a human); blocked reconciles once from ground truth before escalating.
+//   - mergeRebaseArm: conflict → bounded rebase agent → re-arm / escalate /
+//     reconcile / wait-on-PR.
+//   - mergeEscalationQuestion (#329/#454): the four blocked/SLA triggers and the
+//     draft verdict each produce a distinct, human-actionable question; a
+//     persist-escalation `escalated:false` re-enters the poller instead of
+//     parking a dead user task.
+//   - mergeEscalationUserTask (#256): escalation parks on the native
+//     `wait-merge-answer` user task and the answer reconciles then re-arms.
+// Plus the terminate semantics the refactor had to preserve: `MergeAbandoned`
+// terminates the whole instance (it stays at the root, not inside a sub-process).
+import { after, test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+import {
+  assertThatInstance,
+  assertThatUserTask,
+  byProcessId,
+  createWasmEngineClient,
+  type WasmEngineClient,
+} from "@nanobpm/urban-testkit";
+
+const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+
+const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
+
+type Output = Record<string, unknown>;
+type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
+
+const ALL_JOB_TYPES = [
+  "pr.arm-merge",
+  "pr.merge",
+  "pr.mark-merged",
+  "senior:fix-ci",
+  "senior:rebase",
+  "pr.persist-escalation",
+  "pr.answer-escalation",
+  "pr.record-dependency",
+] as const;
+
+const DEFAULT_RESPONSES: Record<string, Responder> = {
+  "pr.arm-merge": {},
+  "pr.mark-merged": {},
+  "pr.record-dependency": {},
+  "pr.answer-escalation": {},
+  "pr.persist-escalation": { escalated: true },
+};
+
+// Every FEEL expression in the model references these; start them defined (null,
+// or a typed zero where the model compares/arithmetics the value, e.g.
+// `failingChecks > 0`) so a missing-variable access can never raise a spurious
+// incident in a test.
+const DEFAULT_VARS: Record<string, unknown> = {
+  prKey: "pr-1",
+  repo: "acme/app",
+  prNumber: 1,
+  prUrl: "https://example.test/pr/1",
+  ciFixMax: 3,
+  rebaseMax: 3,
+  mergeRetryMax: 3,
+  ciFixRound: 0,
+  rebaseRound: 0,
+  mergeRetryRound: 0,
+  agentSlaTimeout: "PT30M",
+  abandonBrief: null,
+  failingChecksList: null,
+  status: null,
+  mergeState: null,
+  mergeStatus: null,
+  ciBlockedReconciled: null,
+  failingChecks: 0,
+};
+
+/**
+ * Deploy the committed merge-loop and start one instance, wired to a per-job-type
+ * responder. A responder may be a fixed output, a queue consumed per activation,
+ * or a function of the job. A job type mapped to `null` registers **no** worker,
+ * so its token parks on the task — used to let an agent SLA boundary fire.
+ */
+async function startMergeLoop(opts: {
+  responses?: Record<string, Responder | null>;
+  vars?: Record<string, unknown>;
+} = {}): Promise<WasmEngineClient> {
+  const engine = await createWasmEngineClient();
+  await engine.deployResources([{ name: "merge-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const responses: Record<string, Responder | null> = { ...DEFAULT_RESPONSES, ...(opts.responses ?? {}) };
+  for (const jobType of ALL_JOB_TYPES) {
+    const responder = jobType in responses ? responses[jobType] : undefined;
+    if (responder === null) continue; // park the token (e.g. to let the SLA timer fire)
+    const queue = Array.isArray(responder) ? [...responder] : null;
+    await engine.registerWorker(jobType, (job) => {
+      // The escalation `question`/`status` are job-LOCAL input mappings on
+      // `merge-esc-*` (fed to `pr.persist-escalation`), so they never surface as
+      // instance variables — capture them off the job the worker sees instead.
+      if (jobType === "pr.persist-escalation") {
+        lastEscalationByEngine.set(engine, (job as { variables?: Record<string, unknown> }).variables ?? {});
+      }
+      if (queue) return queue.length > 1 ? queue.shift()! : queue[0] ?? {};
+      if (typeof responder === "function") return responder(job as { variables: Record<string, unknown> });
+      return (responder as Output | undefined) ?? {};
+    });
+  }
+  await engine.createInstance({
+    processDefinitionId: "merge-loop",
+    awaitCompletion: false,
+    variables: { ...DEFAULT_VARS, ...(opts.vars ?? {}) },
+  });
+  return engine;
+}
+
+// Positive checks use the engine-testkit `assertThat*` DSL below. The DSL has no
+// *negative* element matcher ("element X did NOT complete") and no *substring*
+// variable matcher (`hasVariable` is deep-equal), so the two readers below cover
+// exactly those gaps. They read via the **same canonical snapshot accessors the
+// DSL uses internally** (`instance.js`): completions from the snapshot-global
+// `elementStats` (`{ elementId, completed }`) and live vars from
+// `instances[].variables`. Sound because every test runs one isolated instance
+// per engine — the single-instance precondition the DSL's own aggregate read
+// relies on.
+
+/** Element ids completed by the single instance — mirrors the DSL's `completedElementIds`. */
+function completedElementIds(engine: WasmEngineClient): Set<string> {
+  const snap = engine.snapshot() as { elementStats?: { elementId: string; completed: number }[] };
+  return new Set((snap.elementStats ?? []).filter((s) => s.completed > 0).map((s) => s.elementId));
+}
+
+/** The single instance's live variables — mirrors the DSL's `variablesOf`. */
+function instanceVars(engine: WasmEngineClient): Record<string, unknown> {
+  const snap = engine.snapshot() as { instances?: { variables?: Record<string, unknown> }[] };
+  return snap.instances?.[0]?.variables ?? {};
+}
+
+/**
+ * The variables the `pr.persist-escalation` worker was last activated with, captured
+ * in `startMergeLoop`. The escalation `question`/`status` are job-local `zeebe:input`
+ * mappings on `merge-esc-*`, so they are only observable on the persist-escalation job
+ * — not as instance variables — this is the canonical read for the escalation payload.
+ */
+const lastEscalationByEngine = new WeakMap<WasmEngineClient, Record<string, unknown>>();
+function escalation(engine: WasmEngineClient): Record<string, unknown> {
+  return lastEscalationByEngine.get(engine) ?? {};
+}
+
+const engines: WasmEngineClient[] = [];
+
+/**
+ * urban-testkit's `assertThat*` DSL reads through a booted-app port: instance
+ * matchers use `app.snapshot()`, user-task matchers use
+ * `app.engine.{search,open}UserTasks`. These tests drive the WASM engine
+ * directly (no full app boot), so expose the client as its own read-model app:
+ * `snapshot()` is native, and `.engine` self-references so the task reads land
+ * on the same client.
+ */
+function asReadModelApp(engine: WasmEngineClient): WasmEngineClient {
+  (engine as unknown as { engine: WasmEngineClient }).engine = engine;
+  return engine;
+}
+
+async function boot(opts?: Parameters<typeof startMergeLoop>[0]): Promise<WasmEngineClient> {
+  const engine = asReadModelApp(await startMergeLoop(opts));
+  engines.push(engine);
+  return engine;
+}
+
+/** The key of the single open `wait-merge-answer` task, via the typed read model. */
+async function mergeAnswerTaskKey(engine: WasmEngineClient): Promise<string> {
+  const tasks = await engine.searchUserTasks({});
+  const row = tasks.find((t) => t.elementId === "wait-merge-answer");
+  assert(row, "expected an open wait-merge-answer user task");
+  return row.userTaskKey;
+}
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+// ---------------------------------------------------------------------------
+// Happy paths
+// ---------------------------------------------------------------------------
+
+test("a ready PR merges and the instance completes via mark-merged", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "merged" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasNoIncident().hasCompletedElements("mark-merged");
+});
+
+test("a queued merge parks on the event gateway; the landed message marks it merged", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElements("wait-landed", "wait-evicted");
+  await engine.publishMessage({ name: "merge-landed", correlationKey: "pr-1" });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("mark-merged");
+});
+
+test("an evicted queued merge re-arms the poller rather than completing", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await engine.publishMessage({ name: "merge-evicted", correlationKey: "pr-1" });
+  // back at the poller's wait, not merged
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("mark-merged"), "an evicted merge must not mark-merged");
+});
+
+// ---------------------------------------------------------------------------
+// Transient-retry arm (mergeRetryArm, #334)
+// ---------------------------------------------------------------------------
+
+test("a transient retry re-arms the poller within budget and advances the retry counter only on retry", async () => {
+  const engine = await boot({ responses: { "pr.merge": [{ mergeStatus: "retry" }, { mergeStatus: "merged" }] } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  // 1st attempt: retry (base moved) → within budget → re-arm → 2nd attempt: merged
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  // the retry re-armed and re-polled; feed a second mergeable so the 2nd attempt runs
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a within-budget retry must NOT escalate");
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted();
+});
+
+test("a retry that exhausts the budget escalates as a repeated race, not a generic refusal", async () => {
+  const engine = await boot({
+    responses: { "pr.merge": { mergeStatus: "retry" } },
+    vars: { mergeRetryMax: 0 }, // first retry → mergeRetryRound 1 > 0 → exhausted
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "retry budget", "the retry escalation must read as a repeated race");
+});
+
+// ---------------------------------------------------------------------------
+// CI-fix sub-process (SP_cifix) — mergeCiReattempt (#134), #329
+// ---------------------------------------------------------------------------
+
+async function driveToCiFix(engine: WasmEngineClient): Promise<void> {
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({
+    name: "merge-ready",
+    correlationKey: "pr-1",
+    variables: { mergeState: "blocked", failingChecks: 1, failingChecksList: "build" },
+  });
+}
+
+test("a fixed CI verdict runs the agent, advances the fix counter, and re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "fixed" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("fix-ci")
+    .hasVariable("ciFixRound", 1); // the fix counter advanced across the sub-process boundary
+  const done = completedElementIds(engine);
+  assert(!done.has("merge-esc-attempt") && !done.has("merge-esc-conflict"), "a fixed verdict must never escalate");
+});
+
+test("a reattempt CI verdict re-arms the poller and never pages a human (#134)", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "reattempt" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  const done = completedElementIds(engine);
+  assert(!done.has("merge-esc-attempt") && !done.has("merge-esc-conflict"), "a reattempt must not escalate");
+});
+
+test("a no-verdict CI result reconciles from ground truth (re-arm), not escalation (#134)", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { summary: "unclear" } } }); // no `status`
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a missing status must not escalate");
+});
+
+test("a blocked CI verdict with nothing pushed reconciles once before escalating", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "blocked", pushed: false } } });
+  await driveToCiFix(engine);
+  // ci-reconcile re-arms and re-checks mergeable; it does not escalate on the first block
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("ci-reconcile")
+    .hasVariable("ciBlockedReconciled", true); // the one-shot reconcile is marked spent
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "the first block episode must reconcile, not page a human");
+});
+
+test("a blocked CI verdict that already pushed escalates with a could-not-fix question", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "blocked", pushed: true } } });
+  await driveToCiFix(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "CI-fix agent could not", "the question must name the could-not-fix trigger");
+});
+
+test("a CI-fix that discovers a dependency records it and waits on the other PR", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "waiting-on-pr", dependsOn: "acme/app#2" } } });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-deps")
+    .hasCompletedElements("record-merge-dep"); // a waiting-on-pr verdict records the dependency
+});
+
+test("CI-fix budget exhaustion escalates as not-mergeable without running the agent", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "fixed" } }, vars: { ciFixMax: 0 } });
+  await driveToCiFix(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assert(!completedElementIds(engine).has("fix-ci"), "budget exhaustion must not run the fix-ci agent");
+});
+
+test("the fix-ci agent SLA interrupts the sub-process and escalates", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": null } }); // park on the agent so the SLA fires
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("fix-ci");
+  await engine.advanceTime(AGENT_SLA_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "time budget (SLA)", "the SLA escalation must name the SLA trigger");
+});
+
+// ---------------------------------------------------------------------------
+// Rebase sub-process (SP_rebase) — mergeRebaseArm
+// ---------------------------------------------------------------------------
+
+async function driveToRebase(engine: WasmEngineClient): Promise<void> {
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "conflict" } });
+}
+
+test("a conflict runs the bounded rebase agent and a rebased result re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } } });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("rebase") // a conflict runs the rebase agent, not page a human
+    .hasVariable("rebaseRound", 1); // the rebase counter advanced across the sub-process boundary
+});
+
+test("a rebase that cannot resolve escalates with a conflict question", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "rebase agent could not resolve", "the question must name the conflict trigger");
+});
+
+test("a no-verdict rebase result reconciles from ground truth, not escalation (#134)", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { summary: "unclear" } } }); // no `status`
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "a missing rebase status must not escalate");
+});
+
+test("rebase budget exhaustion escalates as not-mergeable without running the agent", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } }, vars: { rebaseMax: 0 } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assert(!completedElementIds(engine).has("rebase"), "budget exhaustion must not run the rebase agent");
+});
+
+test("the rebase agent SLA interrupts the sub-process and escalates as not-mergeable", async () => {
+  const engine = await boot({ responses: { "senior:rebase": null } });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("rebase");
+  await engine.advanceTime(AGENT_SLA_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+});
+
+// ---------------------------------------------------------------------------
+// Escalation user task (mergeEscalationUserTask #256, mergeEscalationQuestion #329/#454)
+// ---------------------------------------------------------------------------
+
+test("an escalation parks on the native user task; answering it reconciles then re-arms the poller", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  await engine.completeUserTask(await mergeAnswerTaskKey(engine), { answer: "rebased manually, retry" });
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("record-merge-answer"); // answering runs the pr.answer-escalation reconcile
+});
+
+test("a persist-escalation that opens nothing (escalated:false) re-enters the poller, not a dead user task", async () => {
+  const engine = await boot({
+    responses: { "senior:rebase": { status: "blocked" }, "pr.persist-escalation": { escalated: false } },
+  });
+  await driveToRebase(engine);
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+  const openTasks = await engine.searchUserTasks({});
+  assert(
+    !openTasks.some((t) => t.elementId === "wait-merge-answer"),
+    "escalated:false must not park a user task",
+  );
+});
+
+test("a not-landable gate verdict gives a draft PR an actionable 'mark it ready' question (#454)", async () => {
+  const engine = await boot();
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "draft" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "draft", "a draft PR must get a mark-it-ready question");
+});
+
+// ---------------------------------------------------------------------------
+// Terminate semantics — the refactor kept MergeAbandoned at the root
+// ---------------------------------------------------------------------------
+
+test("an abandoned merge ends the whole instance via the root terminate, without merging", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "abandoned" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  // `MergeAbandoned` is a terminate end event at the ROOT scope: it ends all tokens, so the whole
+  // instance finishes (BPMN: a terminate end event *completes* the instance — `Completed`, not a
+  // cancellation `Terminated`). Had it lived inside `SP_cifix`/`SP_rebase`, the terminate would end
+  // only that sub-process scope and the outer poller would re-arm, leaving the instance ACTIVE —
+  // so `hasCompleted()` (nothing left running) is exactly what proves the terminate stayed at root.
+  const done = completedElementIds(engine);
+  assert(done.has("MergeAbandoned"), "the abandon terminate end event must fire");
+  assert(!done.has("mark-merged"), "an abandoned PR must not mark-merged");
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("MergeAbandoned");
+  const open = await engine.searchUserTasks({});
+  assert(open.length === 0, "the root terminate must leave nothing running (no re-armed poller, no parked escalation)");
+});

package/app/promotionPoll.test.ts

@@ -6,6 +6,7 @@
 // recording engine: open exactly one PR, never a duplicate on re-run, never for a converging epic,
 // and never for a `main`-based epic.
 import { test } from "node:test";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { assert, assertEquals } from "#test-assert";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { resetDefaultBranchCache } from "./github.ts";
@@ -41,7 +42,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  const data = { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) } as any as DataLayer;
   return { data, stores };
 }
 

package/app/retro.test.ts

@@ -3,6 +3,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { memBlackboardSource } from "../test/blackboardDb.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { appendEntry } from "./blackboard.ts";
 import { recordTaskDelta } from "./taskDelta.ts";
 import {
@@ -47,7 +48,7 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
       },
     };
   }
-  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
+  const data = { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)), source: memBlackboardSource().source } as any as DataLayer;
   return { data, stores };
 }
 

package/app/retro.ts

@@ -17,6 +17,7 @@ import type { DataLayer, EngineClient, Logger } from "@nanobpm/urban";
 import { type BlackboardEntry, isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { hasDeliveredImplementationForPlan } from "./conformance.ts";
 import { TERMINAL_STATUSES } from "./delivery.ts";
+import { derivedTrackingTable } from "./instanceTracking.ts";
 import { planReviews, planTasks } from "./plan.ts";
 import { aggregateEpicDeltas } from "./taskDelta.ts";
 
@@ -55,7 +56,11 @@ interface PlanRow extends Record<string, unknown> {
 
 const plansTbl = (data: DataLayer) => data.table<PlanRow>("plans", "plan_key");
 const prsTbl = (data: DataLayer) =>
-  data.table<{ pr_key: string; status: string }>("pull_requests", "pr_key");
+  derivedTrackingTable<{ pr_key: string; derived_status: string }>(
+    data,
+    "pull_requests",
+    "pr_key",
+  );
 const retroStartsTbl = (data: DataLayer) =>
   data.table<{ plan_key: string; started_at: string }>("plan_retro_starts", "plan_key");
 
@@ -77,8 +82,10 @@ export async function isPlanComplete(data: DataLayer, planKey: string): Promise<
     if (SETTLED_TASKLESS.has(t.status)) continue;
     // Any task that is meant to yield a PR must have a terminal PR to be settled.
     if (!t.pr_key) return false; // pending/escalated/etc. with no PR yet → still in flight
+    // Any task that is meant to yield a PR must have a terminal PR to be settled. Read the ADR-0065
+    // derived edge so an out-of-band-terminated (`abandoned`) PR is recognised as terminal here.
     const pr = await prsTbl(data).get(t.pr_key);
-    if (!pr || !TERMINAL_PR_STATUSES.has(pr.status)) return false;
+    if (!pr || !TERMINAL_PR_STATUSES.has(pr.derived_status)) return false;
   }
   return true;
 }

package/app/service.test.ts

@@ -8,6 +8,7 @@
 import { test } from "node:test";
 import { assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
 import { memDataFor } from "../test/worldDb.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
 import { abandonClosedPr, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
@@ -71,7 +72,7 @@ test("re-submit of a cancelled PR marks stale open escalations", async () => {
       pr_dependencies: { rows: [], key: "pr_key" },
     };
     const data = {
-      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
     } as any;
     const engine = {
       createInstance: () => Promise.resolve({ processInstanceKey: "PI-9" }),
@@ -137,7 +138,7 @@ test("pollIncidents mirrors an ACTIVE incident onto the PR row, then clears it,
     pull_requests: { rows: [row], key: "pr_key" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   const headers = { "content-type": "application/json" };
 
@@ -190,7 +191,7 @@ test("pollIncidents never queries a PR with no live instance and clears any stal
     pull_requests: { rows: [noKey, terminal], key: "pr_key" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   const headers = { "content-type": "application/json" };
 
@@ -223,7 +224,7 @@ test("pollIncidents picks the oldest incident by creationTime, sorting a missing
     pull_requests: { rows: [row], key: "pr_key" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   const headers = { "content-type": "application/json" };
 
@@ -262,7 +263,7 @@ test("submitPr stringifies a numeric processInstanceKey (contract: string | null
       pr_dependencies: { rows: [], key: "pr_key" },
     };
     const data = {
-      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
     } as any;
     const engine = {
       // A large key delivered as a JS number — the exact case that breaks dev response validation
@@ -296,7 +297,7 @@ function captureConvergeOnly() {
     pr_dependencies: { rows: [], key: "pr_key" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   let captured: unknown;
   const engine = {
@@ -347,7 +348,7 @@ function captureRoot() {
     pr_dependencies: { rows: [], key: "pr_key" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
   let captured: unknown;
   const engine = {
@@ -629,7 +630,7 @@ test("pollWaveGatesImpl is level-triggered: PRs merged before the token arrives
       },
     };
     const data = {
-      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
     } as any;
 
     const published: { name: string; correlationKey?: string }[] = [];
@@ -718,7 +719,7 @@ test("pollWaveGatesImpl never releases the barrier on an unverifiable subscripti
       },
     };
     const data = {
-      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
     } as any;
 
     const published: { name: string; correlationKey?: string }[] = [];
@@ -822,7 +823,7 @@ test("pollWaveGatesImpl releases the wave when a member PR is closed-unmerged an
       merges: { rows: [], key: "id" },
     };
     const data = {
-      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
     } as any;
 
     const published: { name: string; correlationKey?: string }[] = [];
@@ -878,7 +879,7 @@ test("abandonClosedPr is idempotent — the terminal merges audit row is written
     merges: { rows: [], key: "id" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
 
   await abandonClosedPr(data, "owner/repo#70", "closed without merging");
@@ -906,7 +907,7 @@ test("abandonClosedPr self-heals a missing pull_requests parent row before the F
     merges: { rows: [], key: "id" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
 
   await abandonClosedPr(data, "owner/repo#71", "closed without merging");
@@ -932,7 +933,7 @@ test("abandonClosedPr rejects a malformed prKey with a clear error before any FK
     merges: { rows: [], key: "id" },
   };
   const data = {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
 
   const err = await assertRejects(() => abandonClosedPr(data, "not-a-valid-pr-key", "closed without merging"));
@@ -1004,7 +1005,7 @@ function capsProbeExec(ready: boolean) {
 
 function capsDataLayer(stores: Record<string, { rows: any[]; key: string }>) {
   return {
-    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
   } as any;
 }