@nanobpm/nano-workforce 0.128.0 → 0.129.1

package/app/service.ts

@@ -7,7 +7,6 @@
 //
 // Data access goes through the record-oriented gateway (`data.table<T>(name, pk)` — the RAD
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
-import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { escalationFormId } from "./agentCompletion.ts";
@@ -51,6 +50,7 @@ import {
   type PrState,
   requestCopilotReview,
 } from "./github.ts";
+import { activeStatusesFor, derivedTrackingTable } from "./instanceTracking.ts";
 import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import {
@@ -253,6 +253,16 @@ interface Escalation {
 }
 
 const prs = (data: DataLayer) => data.table<PullRequest>("pull_requests", "pr_key");
+/** A PR row as seen through its derived tracking VIEW (`pull_requests__tracking`): the base columns
+ * plus urban's ADR-0065 `derived_status`, which folds the reconciler's terminal edge
+ * (out-of-band terminate → `abandoned`) over the worker-owned transient. */
+type TrackedPullRequest = PullRequest & { derived_status: string };
+/** Read-only accessor over the PR derived tracking VIEW. Use this — and read `derived_status`, not
+ * `status` — for any terminal-edge classification (delivery/promotion/feature reconciliation), so an
+ * out-of-band-terminated PR (whose base row is still `converging`) is correctly seen as `abandoned`.
+ * Worker-written terminals (`merged`/`converged`) pass through unchanged. Writes stay on `prs`. */
+const prsTracking = (data: DataLayer) =>
+  derivedTrackingTable<TrackedPullRequest>(data, "pull_requests", "pr_key");
 const escs = (data: DataLayer) => data.table<Escalation>("escalations", "id");
 const deps = (data: DataLayer) => data.table<PrDependency>("pr_dependencies", "pr_key");
 
@@ -1948,7 +1958,8 @@ export async function derivePlanDelivery(
     let status = statusByPrKey?.get(t.pr_key);
     if (status === undefined && !statusByPrKey) {
       // On-demand caller: fetch just this slice's PR row rather than loading the whole table.
-      status = (await prs(data).get(t.pr_key))?.status;
+      // Read the ADR-0065 derived edge so an out-of-band-terminated slice reads `abandoned`.
+      status = (await prsTracking(data).get(t.pr_key))?.derived_status;
     }
     prStatuses.push(status ?? MISSING_PR_STATUS);
   }
@@ -2028,8 +2039,9 @@ export async function pollWaitGate(data: DataLayer) {
  * default branch, so there is nothing to promote. Best-effort + per-plan isolated. */
 export async function pollPromotion(data: DataLayer, engine: EngineClient, token: string) {
   // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
+  // Read the ADR-0065 derived edge (`derived_status`) so a terminated slice reads `abandoned`.
   const statusByPrKey = new Map<string, string>();
-  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  for (const pr of await prsTracking(data).all()) statusByPrKey.set(pr.pr_key, pr.derived_status);
   for (const plan of await plans(data).all()) {
     const base = plan.base_branch;
     // A non-`epic/*` base is never promotable — short-circuit before the per-plan delivery join.
@@ -2107,8 +2119,9 @@ export async function pollPromotion(data: DataLayer, engine: EngineClient, token
  * Never touches a run that isn't `converging` — additive/derived only, idempotent, best-effort. */
 export async function pollFeatureDelivery(data: DataLayer) {
   // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
+  // Read the ADR-0065 derived edge (`derived_status`) so a terminated run reads `abandoned`.
   const statusByPrKey = new Map<string, string>();
-  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  for (const pr of await prsTracking(data).all()) statusByPrKey.set(pr.pr_key, pr.derived_status);
   // Only `converging` runs are ever reconciled — query them via the `feature_runs(status)` index
   // (db/migrations/028) instead of scanning all history, so this pass stays O(in-flight), not
   // O(total runs), as the table grows.
@@ -2130,26 +2143,6 @@ export async function pollFeatureDelivery(data: DataLayer) {
   }
 }
 
-/** The app manifest, read and parsed exactly ONCE at module load. `activeStatusesFor` is invoked
- * three times during module initialization (the PR/plan/feature constants below); parsing here keeps
- * that to a single synchronous `readFileSync` + `JSON.parse` instead of one per lookup. */
-const APP_MANIFEST: { instanceTracking?: { table: string; activeStatuses?: string[] }[] } = JSON.parse(
-  readFileSync(new URL("../nano.app.json", import.meta.url), "utf8"),
-);
-
-/** Read a tracked table's parked-and-active statuses from the single source of truth
- * (`instanceTracking.<table>.activeStatuses` in nano.app.json), so an app-side scan can never drift
- * from the reconciler's notion of "in-flight". Throws if the binding is missing/empty. */
-function activeStatusesFor(table: string): readonly string[] {
-  const binding = APP_MANIFEST.instanceTracking?.find((b) => b.table === table);
-  if (!binding?.activeStatuses?.length) {
-    throw new Error(
-      `nano.app.json: instanceTracking[table="${table}"].activeStatuses is missing or empty`,
-    );
-  }
-  return binding.activeStatuses;
-}
-
 /** The `pull_requests` statuses a PR instance can be parked-and-active on, DERIVED from the single
  * source of truth (`instanceTracking.pull_requests.activeStatuses` in nano.app.json) so the app-side
  * scan can never drift from the reconciler's notion of "in-flight". `pollUserTasks` scans only these

package/e2e/convergence-loop.e2e.ts

@@ -22,6 +22,7 @@ import { mkdtempSync, rmSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { after, before, describe, test } from "node:test";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { trackingTargetFor } from "../app/instanceTracking.ts";
 
 // The app root is this repo's root (one level up from `e2e/`) — where nano.app.json + openapi.yaml
 // + db/migrations + resources/processes live.
@@ -160,16 +161,20 @@ describe("nano-workforce e2e (urban-testkit pilot)", () => {
 
     // The operation registered the PR aggregate (instanceTracking table) and started a real engine
     // instance — synchronously, before any worker ran (we never settled).
-    const prs = app.db.table<{ pr_key: string; status: string; process_key: string | null }>(
-      "pull_requests",
-      "pr_key",
-    );
+    const prs = app.db.table<{
+      pr_key: string;
+      status: string;
+      process_key: string | null;
+      abandon_token: string | null;
+    }>("pull_requests", "pr_key");
     const row = await prs.findOne({ pr_key: prKey });
     assert.ok(row, "a pull_requests row was registered");
     assert.equal(row?.status, "converging", "the PR is tracked as actively converging");
     assert.ok(row?.process_key, "the row carries the engine process-instance key");
+    assert.ok(row?.abandon_token, "the row carries a #76 abandon-check capability token");
 
     const processInstanceKey = row!.process_key!;
+    const abandonToken = row!.abandon_token!;
     const before = await app.engine.searchProcessInstances({
       processInstanceKeys: [processInstanceKey],
     });
@@ -182,11 +187,39 @@ describe("nano-workforce e2e (urban-testkit pilot)", () => {
     assert.equal(stillActive?.status, "converging", "row not yet reconciled before any poll fires");
 
     // Advance past the instanceTracking pollMs (derived from nano.app.json above, plus a margin):
-    // the reconciler observes TERMINATED and applies the manifest `onTerminated.set` → status
-    // `abandoned`.
+    // the reconciler observes TERMINATED and feeds urban's instance projection. Under ADR-0065
+    // (urban 0.81.0, the writer→source inversion) it NO LONGER writes `abandoned` onto the base row;
+    // the terminal edge is DERIVED on read via the managed `pull_requests__tracking` VIEW.
     await app.advanceTime(PR_POLL_MS + 1000);
-    const reconciled = await prs.findOne({ pr_key: prKey });
-    assert.equal(reconciled?.status, "abandoned", "reconciler abandoned the terminated PR's row");
+
+    // (1) The base row keeps only the worker-owned transient — it stays `converging`, NOT rewritten.
+    const baseRow = await prs.findOne({ pr_key: prKey });
+    assert.equal(
+      baseRow?.status,
+      "converging",
+      "ADR-0065: the reconciler no longer writes the terminal edge onto the base row",
+    );
+
+    // (2) The derived tracking VIEW reports the terminal edge (`abandoned`) via `derived_status`. Its
+    // name/column are resolved by the app's SSOT helper, which defers to urban's own target resolver.
+    const target = trackingTargetFor("pull_requests");
+    const view = app.db.table<{ pr_key: string } & Record<string, unknown>>(target.view, "pr_key");
+    const derived = await view.findOne({ pr_key: prKey });
+    assert.equal(
+      derived?.[target.statusColumn],
+      "abandoned",
+      "the derived read-model reports the terminated PR as abandoned",
+    );
+
+    // (3) End-to-end, the #76 cooperative abandon-check endpoint (which a servicing agent curls
+    // before any irreversible action) now reports `abandoned: true` — the whole point of the edge.
+    const abandonCheck = await api.call<{ prKey: string; status: string; abandoned: boolean }>(
+      "checkAbandon",
+      { query: { token: abandonToken } },
+    );
+    assert.equal(abandonCheck.status, 200, "the abandon check resolves the known token");
+    assert.equal(abandonCheck.body.abandoned, true, "a servicing agent is told to abort the run");
+    assert.equal(abandonCheck.body.status, "abandoned", "the reported status is the derived edge");
   });
 
   test("coverage gate: every operation the pilot claims to own was exercised", () => {

package/operations/acknowledgeEpic.test.ts

@@ -18,6 +18,7 @@ import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { deriveEpicBucket, epicIsAcknowledgeable } from "../app/delivery.ts";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./acknowledgeEpic.ts";
 
 // An in-memory data layer wired through the `plans` gateway (now a plain record table). `extra` seeds
@@ -52,7 +53,7 @@ function memApp(
     };
   }
   const app = {
-    data: { table: (n: string, pk?: string) => tbl(n, pk) },
+    data: { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) },
     log: noopLog(),
   } as any as AppApi;
   return { app, rows: stores.plans };

package/operations/checkAbandon.test.ts

@@ -3,6 +3,7 @@ import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./checkAbandon.ts";
 
 function memApp(): { app: AppApi } {
@@ -19,7 +20,7 @@ function memApp(): { app: AppApi } {
       },
     };
   }
-  const app = { data: { table: (n: string) => tbl(n) }, log: noopLog() } as any as AppApi;
+  const app = { data: { table: withTrackingViews((n: string) => tbl(n)) }, log: noopLog() } as any as AppApi;
   return { app };
 }
 

package/operations/getLineage.test.ts

@@ -6,6 +6,7 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./getLineage.ts";
 
 function memApp(stores: Record<string, any[]>): AppApi {
@@ -20,7 +21,7 @@ function memApp(stores: Record<string, any[]>): AppApi {
       },
     };
   };
-  return { data: { table }, log: noopLog() } as any as AppApi;
+  return { data: { table: withTrackingViews(table) }, log: noopLog() } as any as AppApi;
 }
 
 function input(query: Record<string, string> = {}, headers: Record<string, string> = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.128.0",
+  "version": "0.129.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -59,17 +59,18 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.80.0",
+    "@nanobpm/urban": "^0.81.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.12.16",
+    "@nanobpm/urban-testkit": "^0.13.1",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",
     "@types/node": "^22",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
     "semantic-release": "^24.2.9",
     "typescript": "^5.6.0"
   },