@nanobpm/nano-workforce 0.100.0 → 0.101.1

package/test/worldDb.ts

@@ -0,0 +1,103 @@
+// A test-only DataLayer over a real in-memory `node:sqlite` db with the world-restore schema
+// (`db/migrations/049_world_checkpoint.sql`) applied, for exercising `app/world/store.ts` and the
+// `app/world/checkpoint.ts` orchestration against a REAL SQLite engine — so the durable fence (the
+// `UNIQUE(pr_key, idempotency_key)` constraint) and the monotonic offset are proven, not mocked.
+import { readFileSync } from "node:fs";
+import { DatabaseSync, type SQLInputValue } from "node:sqlite";
+import { afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+import type { DataLayer } from "@nanobpm/urban";
+
+const openDbs = new Set<DatabaseSync>();
+afterEach(() => {
+  for (const raw of openDbs) {
+    if (openDbs.delete(raw)) raw.close();
+  }
+});
+
+function coerce(p: unknown): SQLInputValue {
+  if (p === null || p === undefined) return null;
+  if (typeof p === "boolean") return p ? 1 : 0;
+  return p as SQLInputValue;
+}
+
+const quote = (id: string) => `"${id.replace(/"/g, '""')}"`;
+
+/** A minimal async `Table<T>`-shaped gateway over one real SQLite table — the insert/find/findOne/
+ * update/get subset the world store uses. Mirrors the runtime `Table<T>` semantics: `insert` omits
+ * `undefined` keys (schema default governs), `update` skips `undefined` keys and clears on `null`. */
+function gateway(db: DatabaseSync, name: string, pk: string) {
+  return {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async insert(row: any): Promise<number | bigint> {
+      const keys = Object.keys(row).filter((k) => row[k] !== undefined);
+      const cols = keys.map(quote).join(", ");
+      const placeholders = keys.map(() => "?").join(", ");
+      const r = db.prepare(`INSERT INTO ${quote(name)} (${cols}) VALUES (${placeholders})`).run(...keys.map((k) => coerce(row[k])));
+      return pk === "id" ? r.lastInsertRowid : (row[pk] as number);
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async find(where: any = {}): Promise<any[]> {
+      const keys = Object.keys(where);
+      const clause = keys.length ? `WHERE ${keys.map((k) => `${quote(k)} = ?`).join(" AND ")}` : "";
+      return db.prepare(`SELECT * FROM ${quote(name)} ${clause}`).all(...keys.map((k) => coerce(where[k])));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async findOne(where: any = {}): Promise<any> {
+      return (await this.find(where))[0];
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async get(id: any): Promise<any> {
+      return db.prepare(`SELECT * FROM ${quote(name)} WHERE ${quote(pk)} = ?`).get(coerce(id));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only gateway over dynamic row shapes.
+    async update(id: any, patch: any): Promise<number> {
+      const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
+      if (keys.length === 0) return 0;
+      const set = keys.map((k) => `${quote(k)} = ?`).join(", ");
+      const r = db.prepare(`UPDATE ${quote(name)} SET ${set} WHERE ${quote(pk)} = ?`).run(...keys.map((k) => coerce(patch[k])), coerce(id));
+      return Number(r.changes);
+    },
+  };
+}
+
+/** A minimal self-referential `DataSource`-shaped gateway over the real db: the `table` surface plus
+ * a real `tx()` that BEGIN/COMMIT/ROLLBACKs on the underlying SQLite connection, so the world store's
+ * atomic `recordCheckpoint` (checkpoint + effects in one transaction) is exercised against genuine
+ * transaction semantics rather than mocked. `tx(fn)` passes the SAME source object to `fn`, so a test
+ * that decorates `table` on the returned source sees its decoration inside the transaction too. */
+type MemDataSource = {
+  table: (name: string, pk?: string) => ReturnType<typeof gateway>;
+  tx<T>(fn: (t: MemDataSource) => Promise<T>): Promise<T>;
+};
+
+function openDataSource(db: DatabaseSync): MemDataSource {
+  const ds: MemDataSource = {
+    table: (name, pk = "id") => gateway(db, name, pk),
+    async tx(fn) {
+      db.exec("BEGIN");
+      try {
+        const r = await fn(ds);
+        db.exec("COMMIT");
+        return r;
+      } catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+      }
+    },
+  };
+  return ds;
+}
+
+/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
+export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
+  const db = new DatabaseSync(":memory:");
+  openDbs.add(db);
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/049_world_checkpoint.sql", import.meta.url)), "utf8");
+  db.exec(sql);
+  const data = {
+    table: (name: string, pk = "id") => gateway(db, name, pk),
+    open: () => openDataSource(db),
+  } as unknown as DataLayer;
+  return { data, db };
+}

package/workers/merge/worker.test.ts

@@ -245,3 +245,48 @@ test("pr.merge routes a transient base-moved race through the retry branch (no e
     },
   );
 });
+
+test("pr.merge abandons a closed-not-merged PR without escalating (terminal abandon, #342)", async () => {
+  // #342/#350: a PR CLOSED on GitHub without merging (e.g. superseded by a newer PR) can never
+  // land. The worker must NOT fall through to the land protocol — that returns blocked/conflict and
+  // escalates a merge no human can complete, orphaning the process on a dead PR. Instead it records
+  // a terminal `abandoned` audit row and returns `mergeStatus:"abandoned"` (the model's
+  // terminate/abandon end event), opening NO escalation. Symmetric with the already-merged
+  // short-circuit; both are decided from the same single live-state read.
+  await withGithub(
+    (url) => {
+      // Single-PR GET → PR is closed (state="closed") and NOT merged.
+      if (/\/pulls\/\d+$/.test(url))
+        return new Response(JSON.stringify({ merged: false, state: "closed", mergeable_state: "dirty" }));
+      return null; // no AGENTS.md / merge-protocol.json → DEFAULT gh-merge protocol
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const out = (await handler(
+        { variables: { prKey: "acme/widgets#13", repo: "acme/widgets", prNumber: 13 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      // Abandon short-circuit: loop-terminal `mergeStatus` only, NO escalation payload.
+      assertEquals(out, { mergeStatus: "abandoned" });
+      assertEquals(out.status, undefined);
+      assertEquals(out.question, undefined);
+
+      // Records exactly one terminal audit row tagged as the closed-PR abandon path.
+      assertEquals(stores.merges.length, 1);
+      assertEquals(stores.merges[0].outcome, "abandoned");
+      assertEquals(stores.merges[0].method, "pr-closed");
+
+      // Flips the PR row to the terminal `abandoned` status. This path drives a terminate end event
+      // that runs NO mark-merged/mark-abandoned worker, so the worker must set the terminal status
+      // itself — otherwise the row stays in a non-terminal in-flight status (e.g. `merging`) and is
+      // tracked/scanned forever even though the merge loop is done (#342 review).
+      const prRow = stores.pull_requests.find((r) => r.pr_key === "acme/widgets#13");
+      assertEquals(prRow?.status, "abandoned");
+
+      // Never attempts a merge PUT or posts an enqueue comment on the dead PR (only the read GET).
+      assertEquals(calls.some((c) => /\/merge$/.test(c.url)), false);
+      assertEquals(calls.some((c) => /\/comments$/.test(c.url)), false);
+    },
+  );
+});

package/workers/merge/worker.ts

@@ -12,9 +12,9 @@
 // shapes the escalation payload on a block.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { matchTags, tag } from "@nanobpm/urban/effect";
-import { abandonTokenFromUrl } from "../../app/abandon.ts";
+import { ABANDONED_STATUS, abandonTokenFromUrl } from "../../app/abandon.ts";
 import { checkBaseTarget, classifyBaseGuard } from "../../app/baseGuard.ts";
-import { enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
+import { classifyPrLiveness, enqueueViaComment, fetchPrState, mergePr } from "../../app/github.ts";
 import { classifyMergeLanding, DEFAULT_MERGE_PROTOCOL, loadMergeProtocol } from "../../app/mergeProtocol.ts";
 import { ensurePr, MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
@@ -23,7 +23,7 @@ import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 type In = WorkerInputs["pr.merge"];
 
 interface Out extends Record<string, unknown> {
-  mergeStatus: "merged" | "queued" | "blocked" | "retry";
+  mergeStatus: "merged" | "queued" | "blocked" | "retry" | "abandoned";
   status?: string;
   question?: string;
 }
@@ -54,7 +54,8 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // FK parent, and BEFORE the base-guard/protocol logic. Best-effort: a transport hiccup falls through
   // to the normal path rather than blocking a genuine merge.
   const pre = await fetchPrState(repo, prNumber, token).catch(() => null);
-  if (pre?.merged) {
+  const liveness = classifyPrLiveness(pre);
+  if (liveness === "merged") {
     await app.data.table("merges", "id").insert({
       pr_key: prKey,
       outcome: "merged",
@@ -65,6 +66,33 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     return { mergeStatus: "merged" };
   }
 
+  // Closed-not-merged short-circuit (#342). A PR CLOSED on GitHub without merging (e.g. superseded
+  // by a newer PR) can never land: falling through to the land protocol would return
+  // blocked/conflict and escalate a merge no human can complete, orphaning the process on a dead
+  // PR (#350). Instead record a terminal `abandoned` audit row and drive the loop down its
+  // terminate/abandon end event — NOT `merge-esc-conflict`. This opens NO escalation and parks NO
+  // user task: a closed PR is terminal state, not a human decision. Symmetric with the merged
+  // short-circuit above and runs on the same live-state read, so one `fetchPrState` classifies both.
+  if (liveness === "closed") {
+    await app.data.table("merges", "id").insert({
+      pr_key: prKey,
+      outcome: "abandoned",
+      method: "pr-closed",
+      detail: "PR was closed on GitHub without merging (e.g. superseded) — abandoning the merge loop",
+      at: now,
+    });
+    // Terminal status write. This branch drives the model's terminate/abandon end event, which runs
+    // NO mark-merged worker (the merged path's `pr.mark-merged` is what sets `status:"merged"`). If
+    // we don't flip the row here it lingers on its in-flight status (e.g. the transient `merging`),
+    // so `activePrs`/delivery keep treating a dead PR as live. Symmetric with mark-merged's write;
+    // `ensurePr` above guarantees the row exists to update.
+    await app.data.table("pull_requests", "pr_key").update(prKey, {
+      status: ABANDONED_STATUS,
+      updated_at: now,
+    });
+    return { mergeStatus: "abandoned" };
+  }
+
   // Dead-end-base guard (#60): never land a PR into a base branch that has itself already merged
   // to the default branch — the merge would land into a dead branch and never reach `main`.
   // GitHub only auto-retargets a PR when its base is *deleted* on merge; a merged-but-undeleted

package/workers/persist-round/worker.ts

@@ -7,6 +7,7 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { ensurePr, parsePr } from "../../app/service.ts";
+import { type Effect, isCommitSha, isEffectKind, recordWorldCheckpoint, WorldStore } from "../../app/world/index.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 // Input is typed off the model data envelope (`PrPersistRoundIn` in convergence-loop.bpmn),
@@ -32,6 +33,54 @@ function workerOf(vars: Record<string, unknown>): string | undefined {
   return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
 }
 
+/** The world-restore marker (issue #324, ADR 0062 Slice 4/5, the WORLD half). When a round pushed
+ * changes, the c8ctl harness reports `{commitSha, effects?}` under this reserved key so the app
+ * records a durable push-checkpoint: the pushed SHA a replacement activation reconstructs the working
+ * tree to (inverting `git push` → `git fetch && git checkout <sha>`), plus the round's irreversible
+ * effect ledger (each fence-keyed) so a resume skips an already-applied effect. Absent (a `waiting`
+ * round, or a harness predating #324) → no checkpoint is recorded (nothing was pushed). */
+const WORLD_MARKER_KEY = "worldMarker";
+
+interface WorldMarker {
+  readonly commitSha: string;
+  readonly effects?: readonly Effect[];
+}
+
+/** Normalize one externally-supplied effect from the harness `worldMarker`, or `null` when it is not
+ * a usable effect. This is a CONTRACT BOUNDARY: the marker arrives from out-of-process, so both the
+ * fence key AND the effect kind are untrusted. We (a) TRIM `idempotencyKey` so whitespace variants of
+ * one real effect collapse to a single fence key rather than manufacturing distinct ledger rows that
+ * defeat the fence, and (b) validate `kind` against the canonical {@link EFFECT_KINDS} so an unknown
+ * kind can never enter the durable ledger. `description` is trimmed to a non-empty note or dropped. */
+function normalizeEffect(raw: unknown): Effect | null {
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const e = raw as { kind?: unknown; idempotencyKey?: unknown; description?: unknown } | null | undefined;
+  if (!e || !isEffectKind(e.kind)) return null;
+  if (typeof e.idempotencyKey !== "string") return null;
+  const idempotencyKey = e.idempotencyKey.trim();
+  if (idempotencyKey === "") return null;
+  const description = typeof e.description === "string" ? e.description.trim() : "";
+  return { kind: e.kind, idempotencyKey, ...(description !== "" ? { description } : {}) };
+}
+
+export function worldMarkerOf(vars: Record<string, unknown>): WorldMarker | null {
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+  const m = vars[WORLD_MARKER_KEY] as { commitSha?: unknown; effects?: unknown } | undefined;
+  if (!m || typeof m.commitSha !== "string") return null;
+  // `commitSha` is used as an EXACT checkout target on restore (`git fetch && git checkout <sha>`),
+  // so validate it is a well-formed 40-hex SHA — the SAME guard the emit boundary `repoEnvelopeVars`
+  // applies (via `isCommitSha`) so the two boundaries can't drift. An arbitrary ref (e.g. `main`) or
+  // an abbreviated SHA would reconstruct to a moved branch tip or fail restore, undermining the
+  // "reconstruct the exact tree at <sha>" contract. Trim first so a whitespace-tainted valid SHA
+  // still passes; a value that isn't a full object name degrades to no checkpoint (a `waiting` round).
+  const commitSha = m.commitSha.trim();
+  if (!isCommitSha(commitSha)) return null;
+  const effects = Array.isArray(m.effects)
+    ? m.effects.map(normalizeEffect).filter((e): e is Effect => e !== null)
+    : undefined;
+  return { commitSha, ...(effects && effects.length > 0 ? { effects } : {}) };
+}
+
 const handler: AppJobHandler<In> = async (job, app) => {
   // This worker is the "addressed"/"waiting" path, so `status` resolves to one of those
   // domain values. `summary` is left undefined when absent: the write boundary omits it so the
@@ -75,6 +124,25 @@ const handler: AppJobHandler<In> = async (job, app) => {
     updated_at: now,
   });
 
+  // World checkpoint (issue #324, ADR 0062 Slice 4/5): when this round pushed, record the durable
+  // push-checkpoint — the pushed SHA a replacement activation reconstructs the tree to, plus the
+  // round's fence-keyed effect ledger. The JOIN to the mind's `session.checkpoint(...)` (Slice 1)
+  // happens harness-side (out of process); here we persist the WORLD marker so restore can invert
+  // the push. Best-effort: a checkpoint-store failure must not fail an already-recorded round.
+  const marker = worldMarkerOf(job.variables);
+  if (marker) {
+    try {
+      await recordWorldCheckpoint(new WorldStore(app.data), {
+        prKey,
+        roundNo: round,
+        commitSha: marker.commitSha,
+        ...(marker.effects ? { effects: marker.effects } : {}),
+      });
+    } catch (err) {
+      app.log.warn("world checkpoint record failed", { prKey, round, err: String(err) });
+    }
+  }
+
   return {};
 };