@nanobpm/nano-workforce 0.26.0

package/app/mergeExclusion.test.ts

@@ -0,0 +1,168 @@
+// Unit tests for the merge-exclusion graph + conflict-scan (D1/D2, issues #57 #58 / #49).
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  clearExclusions,
+  deriveExclusions,
+  type ExclusionEdge,
+  mergeLanes,
+  normalizePair,
+  readExclusions,
+  recordExclusions,
+} from "./mergeExclusion.ts";
+import { computeWaves } from "./waves.ts";
+
+// In-memory record-gateway fake (insert/find/findOne/update/delete), mirroring the app tests.
+// deno-lint-ignore no-explicit-any
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    // deno-lint-ignore no-explicit-any
+    const rows = (stores[name] ??= [] as any[]);
+    // deno-lint-ignore no-explicit-any
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push({ id, ...row });
+        return id;
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row.id === id);
+        if (r) Object.assign(r, patch);
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async delete(id: any) {
+        const i = rows.findIndex((row) => row.id === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+const files = (e: ExclusionEdge) => e.files;
+
+Deno.test("normalizePair: orders deterministically and rejects self/blank pairs", () => {
+  assertEquals(normalizePair("b", "a"), ["a", "b"]);
+  assertEquals(normalizePair("a", "b"), ["a", "b"]);
+  assertEquals(normalizePair("a", "a"), null, "a task never excludes itself");
+  assertEquals(normalizePair("", "a"), null);
+});
+
+Deno.test("deriveExclusions: an edge per file-overlapping pair, carrying the sorted overlap", () => {
+  const edges = deriveExclusions(
+    new Map([
+      ["gap-2", ["engine/tests.rs", "engine/state.rs"]],
+      ["gap-8", ["engine/tests.rs"]],
+      ["gap-9", ["engine/tests.rs", "engine/state.rs"]],
+      ["gap-5", ["docs/readme.md"]], // no overlap with anyone
+    ]),
+  );
+  // Pairs with overlap: (gap-2,gap-8) share tests.rs; (gap-2,gap-9) share both; (gap-8,gap-9) tests.rs.
+  assertEquals(edges.map((e) => [e.taskA, e.taskB]), [
+    ["gap-2", "gap-8"],
+    ["gap-2", "gap-9"],
+    ["gap-8", "gap-9"],
+  ]);
+  assertEquals(files(edges[1]), ["engine/state.rs", "engine/tests.rs"], "overlap sorted");
+  assert(!edges.some((e) => e.taskA === "gap-5" || e.taskB === "gap-5"), "gap-5 excluded (no overlap)");
+});
+
+Deno.test("deriveExclusions: no overlap → no edges; blank paths ignored", () => {
+  assertEquals(
+    deriveExclusions(new Map([["a", ["x.rs"]], ["b", ["y.rs"]], ["c", ["", "  "]]])),
+    [],
+  );
+});
+
+Deno.test("recordExclusions: upserts per unordered pair — a re-scan refreshes files, never duplicates", async () => {
+  const { data, stores } = memData();
+  const first = await recordExclusions(data, "p", deriveExclusions(
+    new Map([["gap-2", ["a.rs"]], ["gap-8", ["a.rs"]]]),
+  ));
+  assertEquals(first, { inserted: 1, updated: 0 });
+
+  // Re-scan with a larger overlap and the pair given in the OTHER order → same row, updated.
+  const second = await recordExclusions(data, "p", [
+    { taskA: "gap-8", taskB: "gap-2", files: ["a.rs", "b.rs"], source: "file-overlap" },
+  ]);
+  assertEquals(second, { inserted: 0, updated: 1 });
+  assertEquals(stores["plan_merge_exclusions"].length, 1, "exactly one row for the pair");
+
+  const [edge] = await readExclusions(data, "p");
+  assertEquals([edge.taskA, edge.taskB], ["gap-2", "gap-8"]);
+  assertEquals(edge.files, ["a.rs", "b.rs"], "files refreshed in place");
+});
+
+Deno.test("recordExclusions: a duplicate pair within one batch folds into an update, never a second row", async () => {
+  const { data, stores } = memData();
+  // The same unordered pair appears twice in one call (second given in the other order + more files).
+  // The in-memory map must fold the newly inserted id back so the second occurrence updates in place.
+  const res = await recordExclusions(data, "p", [
+    { taskA: "a", taskB: "b", files: ["x.rs"], source: "file-overlap" },
+    { taskA: "b", taskB: "a", files: ["x.rs", "y.rs"], source: "file-overlap" },
+  ]);
+  assertEquals(res, { inserted: 1, updated: 1 });
+  assertEquals(stores["plan_merge_exclusions"].length, 1, "exactly one row for the pair");
+  const [edge] = await readExclusions(data, "p");
+  assertEquals(edge.files, ["x.rs", "y.rs"], "later occurrence refreshed files in place");
+});
+
+Deno.test("clearExclusions: drops one plan's graph, leaving others intact", async () => {
+  const { data } = memData();
+  await recordExclusions(data, "p", deriveExclusions(new Map([["a", ["x"]], ["b", ["x"]]])));
+  await recordExclusions(data, "q", deriveExclusions(new Map([["c", ["y"]], ["d", ["y"]]])));
+  await clearExclusions(data, "p");
+  assertEquals((await readExclusions(data, "p")).length, 0);
+  assertEquals((await readExclusions(data, "q")).length, 1, "the other plan survives");
+});
+
+Deno.test("mergeLanes: connected components are serial landing lanes; singletons land in parallel", () => {
+  // gap-2—gap-8—gap-9 form one chain (transitive shared surface); gap-5 stands alone.
+  const edges = deriveExclusions(
+    new Map([
+      ["gap-2", ["a.rs"]],
+      ["gap-8", ["a.rs", "b.rs"]],
+      ["gap-9", ["b.rs"]],
+      ["gap-5", ["z.rs"]],
+    ]),
+  );
+  const lanes = mergeLanes(edges, ["gap-2", "gap-8", "gap-9", "gap-5"]);
+  assertEquals(lanes, [["gap-2", "gap-8", "gap-9"], ["gap-5"]]);
+});
+
+Deno.test("mergeLanes: with no edges, every task is its own lane (fully parallel landing)", () => {
+  assertEquals(mergeLanes([], ["b", "a", "c"]), [["a"], ["b"], ["c"]]);
+});
+
+Deno.test("D1 invariant: a merge-exclusion is NOT a dispatch dependency", () => {
+  // Two tasks that collide on a shared file but declare no build-on dependency.
+  const overlap = new Map([["gap-2", ["engine/tests.rs"]], ["gap-8", ["engine/tests.rs"]]]);
+  const edges = deriveExclusions(overlap);
+  const lanes = mergeLanes(edges, ["gap-2", "gap-8"]);
+
+  // Landing: they share ONE lane → must land serially.
+  assertEquals(lanes, [["gap-2", "gap-8"]]);
+
+  // Dispatch: computeWaves sees only `dependsOn` (never the exclusion graph), so with no build-on
+  // edge both tasks are in wave 0 → dispatched in PARALLEL. This is the whole point of D1: the
+  // exclusion never over-encodes into a dispatch barrier.
+  const waves = computeWaves([{ id: "gap-2" }, { id: "gap-8" }]);
+  assertEquals(waves.waveCount, 1);
+  assertEquals(waves.waves[0].sort(), ["gap-2", "gap-8"]);
+});

package/app/mergeExclusion.ts

@@ -0,0 +1,211 @@
+// nano-workforce — the merge-exclusion graph + conflict-scan (D1/D2, issues #57 #58 / #49).
+//
+// The planner already models the DISPATCH-DAG (`plan_task_deps` → waves): edges that gate when a
+// task may *start*. This is the SECOND graph the retro (nano-bpm#614) exposed: **merge-exclusion**
+// — undirected edges between tasks that can run in parallel but touch the same surface and so can't
+// *land* independently. They gate ordering at merge time only and MUST NEVER enter `computeWaves`.
+//
+//   D1 (#57) — the graph as data: record/read/clear, and `mergeLanes` (connected components =
+//              the serial landing lanes the merge-train, D6, will drive).
+//   D2 (#58) — derive the edges MECHANICALLY from file-overlap (`deriveExclusions`): any two tasks
+//              whose known touched-file sets intersect get an edge carrying the overlap. Fed from
+//              D5's reported `newlyTouches` and/or a PR's actual changed files. This is a
+//              conservative over-approximation (file-overlap flags a *potential* landing collision;
+//              a textual `git merge-tree` / trial-merge, D3, would confirm/prune it later).
+//
+// Data access goes through the record gateway (`data.table`), never hand-written SQL.
+import type { DataLayer } from "@nanobpm/urban";
+
+const now = () => new Date().toISOString();
+
+/** The default provenance tag for a file-overlap-derived edge. */
+export const EXCLUSION_SOURCE_FILE_OVERLAP = "file-overlap";
+
+/** The stored row shape. `task_a < task_b` (normalised); `files` is JSON-encoded, or NULL. */
+export interface MergeExclusionRow {
+  id: number;
+  plan_key: string;
+  task_a: string;
+  task_b: string;
+  files: string | null;
+  source: string;
+  created_at: string;
+  updated_at: string;
+}
+
+/** One undirected merge-exclusion edge (agent-facing: files decoded, pair normalised). */
+export interface ExclusionEdge {
+  taskA: string;
+  taskB: string;
+  files: string[];
+  source: string;
+}
+
+/** Order a pair deterministically so an unordered `{a, b}` maps to exactly one `(task_a, task_b)`
+ * row (the upsert key). Returns `null` for a self-pair — a task never excludes itself. */
+export function normalizePair(a: string, b: string): [string, string] | null {
+  const x = a.trim();
+  const y = b.trim();
+  if (!x || !y || x === y) return null;
+  return x < y ? [x, y] : [y, x];
+}
+
+function decodeFiles(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Derive merge-exclusion edges from a map of `taskId → touched files`: an edge for every pair of
+ * distinct tasks whose file sets intersect, carrying the sorted overlap. Pure and deterministic —
+ * the same input always yields the same edges in the same order. */
+export function deriveExclusions(
+  taskFiles: Map<string, Iterable<string>>,
+  source: string = EXCLUSION_SOURCE_FILE_OVERLAP,
+): ExclusionEdge[] {
+  // Normalise to sorted, de-duplicated, non-blank file sets keyed by task, in stable task order.
+  const sets: { task: string; files: Set<string> }[] = [];
+  for (const [task, files] of taskFiles) {
+    const t = task.trim();
+    if (!t) continue;
+    const set = new Set<string>();
+    for (const f of files) {
+      const p = String(f).trim();
+      if (p) set.add(p);
+    }
+    if (set.size > 0) sets.push({ task: t, files: set });
+  }
+  sets.sort((a, b) => (a.task < b.task ? -1 : a.task > b.task ? 1 : 0));
+
+  const edges: ExclusionEdge[] = [];
+  for (let i = 0; i < sets.length; i++) {
+    for (let j = i + 1; j < sets.length; j++) {
+      const overlap: string[] = [];
+      for (const f of sets[i].files) if (sets[j].files.has(f)) overlap.push(f);
+      if (overlap.length === 0) continue;
+      const pair = normalizePair(sets[i].task, sets[j].task);
+      if (!pair) continue;
+      edges.push({ taskA: pair[0], taskB: pair[1], files: overlap.sort(), source });
+    }
+  }
+  return edges;
+}
+
+const exclusionTable = (data: DataLayer) =>
+  data.table<MergeExclusionRow>("plan_merge_exclusions", "id");
+
+/** Upsert derived edges for a plan: one row per unordered pair, `files` refreshed in place on a
+ * re-scan. Idempotent — re-running the scan never duplicates a pair. Existing pairs are preloaded
+ * with a single `find({plan_key})` into an in-memory map (keyed by the normalised pair) so a dense
+ * wave costs O(edges) writes instead of an `await findOne(...)` round-trip per edge (worst-case
+ * O(n²) queries). Newly inserted ids are folded back into the map so a duplicate pair in the same
+ * batch updates rather than inserts twice. */
+export async function recordExclusions(
+  data: DataLayer,
+  planKey: string,
+  edges: ExclusionEdge[],
+): Promise<{ inserted: number; updated: number }> {
+  const table = exclusionTable(data);
+  const ts = now();
+  let inserted = 0;
+  let updated = 0;
+  const key = (a: string, b: string) => `${a}\u0000${b}`;
+  const byPair = new Map<string, number>();
+  for (const r of await table.find({ plan_key: planKey })) {
+    byPair.set(key(r.task_a, r.task_b), r.id);
+  }
+  for (const e of edges) {
+    const pair = normalizePair(e.taskA, e.taskB);
+    if (!pair) continue;
+    const files = e.files.length ? JSON.stringify(e.files) : null;
+    const existingId = byPair.get(key(pair[0], pair[1]));
+    if (existingId !== undefined) {
+      await table.update(existingId, { files, source: e.source, updated_at: ts });
+      updated++;
+    } else {
+      const id = await table.insert({
+        plan_key: planKey,
+        task_a: pair[0],
+        task_b: pair[1],
+        files,
+        source: e.source,
+        created_at: ts,
+        updated_at: ts,
+      });
+      byPair.set(key(pair[0], pair[1]), Number(id));
+      inserted++;
+    }
+  }
+  return { inserted, updated };
+}
+
+/** A plan's exclusion graph in write order (files decoded). */
+export async function readExclusions(data: DataLayer, planKey: string): Promise<ExclusionEdge[]> {
+  const rows = await exclusionTable(data).find({ plan_key: planKey });
+  return rows
+    .slice()
+    .sort((a, b) => a.id - b.id)
+    .map((r) => ({ taskA: r.task_a, taskB: r.task_b, files: decodeFiles(r.files), source: r.source }));
+}
+
+/** Delete a plan's whole exclusion graph (re-plan cleanup). */
+export async function clearExclusions(data: DataLayer, planKey: string): Promise<void> {
+  for (const r of await exclusionTable(data).find({ plan_key: planKey })) {
+    await exclusionTable(data).delete(r.id);
+  }
+}
+
+/** Group tasks into serial LANDING LANES: each connected component of the exclusion graph is a
+ * lane whose members must land one-at-a-time (they collide on a shared surface), while separate
+ * lanes land in parallel. `allTasks` (optional) seeds singleton lanes for tasks with no exclusion
+ * so a caller gets the full partition. Lanes and their members are sorted for determinism.
+ *
+ * This is the merge-train's (D6) input; it is a LANDING order, never a dispatch order — these
+ * lanes must not be fed back into `computeWaves`. */
+export function mergeLanes(edges: ExclusionEdge[], allTasks: Iterable<string> = []): string[][] {
+  const parent = new Map<string, string>();
+  const find = (x: string): string => {
+    let root = x;
+    while (parent.get(root) !== root) root = parent.get(root)!;
+    // Path-compress so repeated finds stay near-flat.
+    let cur = x;
+    while (parent.get(cur) !== root) {
+      const next = parent.get(cur)!;
+      parent.set(cur, root);
+      cur = next;
+    }
+    return root;
+  };
+  const add = (x: string) => {
+    if (!parent.has(x)) parent.set(x, x);
+  };
+  const union = (a: string, b: string) => {
+    add(a);
+    add(b);
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra < rb ? rb : ra, ra < rb ? ra : rb);
+  };
+
+  for (const t of allTasks) add(t.trim());
+  for (const e of edges) {
+    const pair = normalizePair(e.taskA, e.taskB);
+    if (pair) union(pair[0], pair[1]);
+  }
+
+  const byRoot = new Map<string, string[]>();
+  for (const task of parent.keys()) {
+    if (!task) continue;
+    const root = find(task);
+    const lane = byRoot.get(root) ?? [];
+    lane.push(task);
+    byRoot.set(root, lane);
+  }
+  return [...byRoot.values()]
+    .map((lane) => lane.sort())
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}

package/app/mergeProtocol.test.ts

@@ -0,0 +1,124 @@
+// Contract for the per-repo merge protocol (#43): the descriptor parser must be total (any
+// malformed/partial input degrades to DEFAULT_MERGE_PROTOCOL, never throws), the AGENTS.md block
+// extractor must find the fenced ```merge-protocol JSON, and the fresh-head-run decision must fire
+// exactly once per landing attempt — only in the frugal-CI stuck state (no head run + waiting) —
+// so a converged PR is nudged into a fresh CI run without disturbing a run already in flight.
+// Run with `deno test -A`.
+import { assertEquals } from "jsr:@std/assert@1";
+import {
+  DEFAULT_MERGE_PROTOCOL,
+  extractProtocolBlock,
+  freshHeadRunAction,
+  type MergeProtocol,
+  parseMergeProtocol,
+} from "./mergeProtocol.ts";
+
+Deno.test("parseMergeProtocol: non-object / junk → defaults (total, never throws)", () => {
+  assertEquals(parseMergeProtocol(undefined), { ...DEFAULT_MERGE_PROTOCOL });
+  assertEquals(parseMergeProtocol(null), { ...DEFAULT_MERGE_PROTOCOL });
+  assertEquals(parseMergeProtocol("nope"), { ...DEFAULT_MERGE_PROTOCOL });
+  assertEquals(parseMergeProtocol([1, 2]), { ...DEFAULT_MERGE_PROTOCOL });
+});
+
+Deno.test("parseMergeProtocol: full nano-bpm-style descriptor", () => {
+  const got = parseMergeProtocol({
+    autoMerge: false,
+    freshHeadRun: "ready-or-reopen",
+    waitForChecks: true,
+    land: { method: "mergify-queue", comment: "@mergifyio queue" },
+    requiredChecks: ["rustfmt (pinned nightly)", "server (clippy + test)"],
+    doc: "AGENTS.md#merging-prs",
+  });
+  assertEquals(got.autoMerge, false);
+  assertEquals(got.freshHeadRun, "ready-or-reopen");
+  assertEquals(got.waitForChecks, true);
+  assertEquals(got.land, { method: "mergify-queue", comment: "@mergifyio queue" });
+  assertEquals(got.requiredChecks.length, 2);
+  assertEquals(got.doc, "AGENTS.md#merging-prs");
+});
+
+Deno.test("parseMergeProtocol: invalid enums / wrong types fall back per-field", () => {
+  const got = parseMergeProtocol({
+    autoMerge: "yes", // not a boolean → default
+    freshHeadRun: "sometimes", // not in the enum → default (none)
+    land: { method: "teleport" }, // not in the enum → default (gh-merge)
+    requiredChecks: ["ok", 7, null], // keep only strings
+  });
+  assertEquals(got.autoMerge, DEFAULT_MERGE_PROTOCOL.autoMerge);
+  assertEquals(got.freshHeadRun, "none");
+  assertEquals(got.land.method, "gh-merge");
+  assertEquals(got.requiredChecks, ["ok"]);
+});
+
+Deno.test("parseMergeProtocol: comment dropped when absent", () => {
+  const got = parseMergeProtocol({ land: { method: "admin" } });
+  assertEquals(got.land, { method: "admin" });
+});
+
+Deno.test("extractProtocolBlock: finds the fenced merge-protocol JSON (with info word)", () => {
+  const md = [
+    "## Merging PRs",
+    "Some prose about how to merge.",
+    "",
+    "```merge-protocol json",
+    '{ "autoMerge": false, "land": { "method": "mergify-queue" } }',
+    "```",
+    "",
+    "More prose.",
+  ].join("\n");
+  const block = extractProtocolBlock(md);
+  assertEquals(block !== null, true);
+  const p = parseMergeProtocol(JSON.parse(block ?? "{}"));
+  assertEquals(p.autoMerge, false);
+  assertEquals(p.land.method, "mergify-queue");
+});
+
+Deno.test("extractProtocolBlock: none present → null", () => {
+  assertEquals(extractProtocolBlock("# Doc\n```json\n{}\n```\n"), null);
+});
+
+const NANO: MergeProtocol = parseMergeProtocol({
+  freshHeadRun: "ready-or-reopen",
+  land: { method: "mergify-queue" },
+});
+
+Deno.test("freshHeadRunAction: fires in the frugal-CI stuck state (no run + waiting)", () => {
+  // ready PR, no head run at all → reopen (ready-or-reopen, not a draft)
+  assertEquals(freshHeadRunAction(NANO, "waiting", 0, false), "reopen");
+  // draft PR, no head run → mark ready
+  assertEquals(freshHeadRunAction(NANO, "waiting", 0, true), "ready");
+});
+
+Deno.test("freshHeadRunAction: fires once per landing-attempt head, then re-fires after rebase", () => {
+  assertEquals(
+    freshHeadRunAction(NANO, "waiting", 0, false, { headRefOid: "h1", lastActionHeadRefOid: null }),
+    "reopen",
+  );
+  assertEquals(
+    freshHeadRunAction(NANO, "waiting", 0, false, { headRefOid: "h1", lastActionHeadRefOid: "h1" }),
+    null,
+  );
+  assertEquals(
+    freshHeadRunAction(NANO, "waiting", 0, false, { headRefOid: "h2", lastActionHeadRefOid: "h1" }),
+    "reopen",
+  );
+});
+
+Deno.test("freshHeadRunAction: never fires once a run exists, or when not waiting", () => {
+  assertEquals(freshHeadRunAction(NANO, "waiting", 1, false), null); // run already in flight
+  assertEquals(freshHeadRunAction(NANO, "waiting", -1, false), null); // token mode (unknown) → conservative
+  assertEquals(freshHeadRunAction(NANO, "ready", 0, false), null); // already landable
+  assertEquals(freshHeadRunAction(NANO, "blocked", 0, false), null); // failed check → fix-ci arm
+  assertEquals(freshHeadRunAction(NANO, "blocked", 0, false, { headRefOid: "h2", lastActionHeadRefOid: "h1" }), null);
+  assertEquals(freshHeadRunAction(NANO, "conflict", 0, false), null); // conflict → rebase arm (#42)
+});
+
+Deno.test("freshHeadRunAction: protocol.freshHeadRun=none is a no-op (default repos unchanged)", () => {
+  assertEquals(freshHeadRunAction(DEFAULT_MERGE_PROTOCOL, "waiting", 0, false), null);
+});
+
+Deno.test("freshHeadRunAction: mode=ready only acts on drafts", () => {
+  const readyOnly = parseMergeProtocol({ freshHeadRun: "ready", land: { method: "gh-merge" } });
+  assertEquals(freshHeadRunAction(readyOnly, "waiting", 0, true), "ready");
+  assertEquals(freshHeadRunAction(readyOnly, "waiting", 0, false), null); // not a draft → nothing to ready
+});