@nanobpm/nano-workforce 0.90.0 → 0.92.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [0.92.0](https://github.com/nanobpm/nano-workforce/compare/v0.91.0...v0.92.0) (2026-08-19)
+
+
+### Bug Fixes
+
+* **e2e:** polyfill EngineClient.openUserTasks in the testkit shim ([#309](https://github.com/nanobpm/nano-workforce/issues/309)) ([#312](https://github.com/nanobpm/nano-workforce/issues/312)) ([22609d5](https://github.com/nanobpm/nano-workforce/commit/22609d57789d09a1062cf8388b37a76ef293d4f0)), closes [#297](https://github.com/nanobpm/nano-workforce/issues/297) [#294](https://github.com/nanobpm/nano-workforce/issues/294)
+
+
+### Features
+
+* **epics:** bucket epics on delivery, not raw status, with a dismiss affordance ([#303](https://github.com/nanobpm/nano-workforce/issues/303)) ([4f9bd1a](https://github.com/nanobpm/nano-workforce/commit/4f9bd1a6d2853ffeacbdd6b744d9dd4efffba0ea)), closes [#298](https://github.com/nanobpm/nano-workforce/issues/298) [#298](https://github.com/nanobpm/nano-workforce/issues/298)
+
+# [0.91.0](https://github.com/nanobpm/nano-workforce/compare/v0.90.0...v0.91.0) (2026-08-19)
+
+
+### Features
+
+* **tasks:** show subject title with repo/issue# as subtitle ([#308](https://github.com/nanobpm/nano-workforce/issues/308)) ([#311](https://github.com/nanobpm/nano-workforce/issues/311)) ([5771b38](https://github.com/nanobpm/nano-workforce/commit/5771b38abc33f4f88329d69c808214dfd42f5113))
+
 # [0.90.0](https://github.com/nanobpm/nano-workforce/compare/v0.89.0...v0.90.0) (2026-08-19)
 
 

package/SPEC.md

@@ -533,10 +533,16 @@ the same flat operation the form posts. `baseBranch`
 is required and admitted through the ADR 0003 gate (auto-create `epic/*`, confirm-default,
 shared-base guard).
 
-**Visibility**: the home page adds a **Plans** grid (Active: planning/dispatched;
-History: done/failed/abandoned) with a `plan_tasks` child grid showing each task's
-status and the PR it produced (`pr_key` cross-references the Pull requests grid for
-convergence status).
+**Visibility**: the home page adds a **Plans** grid (`plan_tasks` child grid showing each
+task's status and the PR it produced — `pr_key` cross-references the Pull requests grid for
+convergence status). Epics bucket into Active / History on the **derived `plans.list_bucket`**
+(issue #298), NOT raw `plans.status`: bucketing on raw `status` made an epic vanish from Active
+the instant `status=done`, even though `done` only means "fan-out dispatched to convergence" —
+its slice PRs may still be **converging**, or all merged (**landed**) but still needing the
+integration→main promotion PR. `deriveEpicBucket` (app/delivery.ts) keeps a `done` epic in Active
+until an operator **dismisses** it (`POST /actions/acknowledge-epic` stamps `plans.acknowledged_at`,
+the twin of the feature-run tick-off); a still-`converging` epic is never dismissable, and
+`failed`/`abandoned` epics fall to History directly. Projected at write time by the `plans` gateway.
 
 **Epic domain phase** (issue #261): `plans.status` only distinguishes the process-instance
 terminal (`dispatched` = "fan-out job done"), not the epic's *domain* lifecycle. The read model

package/app/admittedStaging.test.ts

@@ -0,0 +1,98 @@
+// Unit coverage for the S2 admission-STAGING data layer (issue #292 slice S2): `recordAdmittedEpic`
+// and `recordAdmittedPlanDep`, the FK-free twins the set/batch door persists into instead of the
+// durable `plans` / `plan_deps` graph. Driven against the same minimal in-memory data layer style as
+// app/planDeps.test.ts. The edge writer shares `insertEdgeIdempotent` with `recordPlanDep`, so these
+// pin the staging-specific surface: per-table isolation, epic idempotency on `plan_key`, and that a
+// self-edge is still rejected.
+import { test } from "node:test";
+import { assertEquals, assertRejects } from "#test-assert";
+import { recordAdmittedEpic, recordAdmittedPlanDep } from "./plan.ts";
+
+/** Minimal in-memory data layer with per-name tables (so `admitted_epics` and `admitted_plan_deps`
+ * stay isolated), matching the equality-filtered `find` / append `insert` / `get`-first style. */
+function memData() {
+  const tables = new Map<string, any[]>();
+  const rowsOf = (name: string) => tables.get(name) ?? (tables.set(name, []), tables.get(name)!);
+  return {
+    tables,
+    data: {
+      table: (name: string, key: string) => {
+        const rows = rowsOf(name);
+        return {
+          get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+          find: (q: any) =>
+            Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (r: any) => {
+            rows.push(r);
+            return Promise.resolve(r);
+          },
+        };
+      },
+    } as any,
+  };
+}
+
+const EPIC = {
+  plan_key: "owner/repo#1",
+  repo: "owner/repo",
+  issue_number: 1,
+  issue_url: "https://github.com/owner/repo/issues/1",
+  base_branch: "epic/a",
+};
+
+test("recordAdmittedEpic stages an epic with a stamped created_at", async () => {
+  const { data, tables } = memData();
+  const row = await recordAdmittedEpic(data, EPIC);
+  assertEquals(tables.get("admitted_epics")!.length, 1);
+  assertEquals(row.plan_key, "owner/repo#1");
+  assertEquals(row.base_branch, "epic/a");
+  assertEquals(typeof row.created_at, "string");
+  assertEquals(row.created_at.length > 0, true);
+});
+
+test("recordAdmittedEpic is idempotent on plan_key (no second row, existing wins)", async () => {
+  const { data, tables } = memData();
+  const first = await recordAdmittedEpic(data, EPIC);
+  const again = await recordAdmittedEpic(data, { ...EPIC, base_branch: "epic/ignored-on-dupe" });
+  assertEquals(tables.get("admitted_epics")!.length, 1);
+  assertEquals(again.created_at, first.created_at);
+  assertEquals(again.base_branch, "epic/a"); // the existing staged row is returned, not overwritten
+});
+
+test("recordAdmittedPlanDep stages an edge and stays out of plan_deps", async () => {
+  const { data, tables } = memData();
+  await recordAdmittedPlanDep(data, {
+    plan_key: "owner/repo#2",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/p",
+    capability_ref: "owner/repo#1",
+  });
+  assertEquals(tables.get("admitted_plan_deps")!.length, 1);
+  assertEquals(tables.get("plan_deps") ?? [], []); // never touches the durable graph
+});
+
+test("recordAdmittedPlanDep is idempotent on a duplicate edge (no second row)", async () => {
+  const { data, tables } = memData();
+  const edge = {
+    plan_key: "owner/repo#2",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/p",
+    capability_ref: "owner/repo#1",
+  };
+  await recordAdmittedPlanDep(data, edge);
+  await recordAdmittedPlanDep(data, { ...edge, package: "@nanobpm/ignored-on-dupe" });
+  assertEquals(tables.get("admitted_plan_deps")!.length, 1);
+});
+
+test("recordAdmittedPlanDep rejects a self-edge", async () => {
+  const { data, tables } = memData();
+  await assertRejects(() =>
+    recordAdmittedPlanDep(data, {
+      plan_key: "owner/repo#1",
+      depends_on_plan_key: "owner/repo#1",
+      package: "@nanobpm/p",
+      capability_ref: "owner/repo#1",
+    }),
+  );
+  assertEquals(tables.get("admitted_plan_deps") ?? [], []);
+});

package/app/contracts.ts

@@ -343,6 +343,15 @@ export const WIRE_CONTRACTS = {
     shape:
       '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string }',
   },
+  "epicSet.submit": {
+    category: "wire",
+    name: "epicSet.submit",
+    owner: "operations/startEpicSet.ts",
+    semantics:
+      "Set/batch admission payload POSTed to /actions/start/epic-set (issue #292, slice S2). Submits a whole set of epics plus the inter-epic dependency edges between them in one all-or-nothing call. Each `epics[]` member carries the same per-epic admission inputs as PlanStart (issue|url + baseBranch + allowSharedBase/confirmDefaultBase); each `deps[]` edge declares `consumer` waits for `producer`'s published { package, capabilityRef } capability, both endpoints naming epics in the set. Declared in openapi.yaml as EpicSetStart. S2 admits + STAGES the set into its own FK-free `admitted_epics` / `admitted_plan_deps` (043) — it writes NEITHER `plans` NOR `plan_deps`; slice S3 (lowering) reads that staging to materialize the durable graph, and S4 (visibility) builds on it — consume this ONE shape, do not re-declare a synonym.",
+    shape:
+      '{ epics: Array<{ issue|url: string, baseBranch: string, allowSharedBase?: boolean, confirmDefaultBase?: boolean }>, deps?: Array<{ consumer: string, producer: string, package: string, capabilityRef: string }> }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {
@@ -359,7 +368,7 @@ export const TYPE_CONTRACTS = {
     name: "PlanDep",
     owner: "app/plan.ts",
     semantics:
-      "One INTER-epic dependency edge (issue #292): dependent epic `plan_key` waits for producer epic `depends_on_plan_key`, gated by the producer's `{ package, capability_ref }` capability descriptor. Set admission (S2), planner lowering (S3), and operator visibility (S4) all import this ONE row shape from app/plan.ts — no re-declared synonym.",
+      "One INTER-epic dependency edge (issue #292): dependent epic `plan_key` waits for producer epic `depends_on_plan_key`, gated by the producer's `{ package, capability_ref }` capability descriptor. This ONE row shape backs BOTH the durable `plan_deps` table (materialized by planner lowering S3) AND its FK-free admission-staging twin `admitted_plan_deps` (staged by the S2 door). Set admission (S2), planner lowering (S3), and operator visibility (S4) all import it from app/plan.ts — no re-declared synonym.",
     module: "app/plan.ts",
   },
 } as const satisfies Record<string, TypeContract>;

package/app/delivery.ts

@@ -74,3 +74,64 @@ export function deriveDelivery(
   // Every slice PR is terminal but not all merged (some abandoned/converged): resolved, not landed.
   return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
 }
+
+/** The `plan.status` values that mean the epic's fan-out lifecycle is still LIVE — the planner is
+ * decomposing (`planning`) or the fleet is implementing (`dispatched`). Both are unambiguously
+ * in-flight, so an epic in either status is always in the Active bucket regardless of `delivery`. */
+export const EPIC_LIVE_STATUSES: readonly string[] = ["planning", "dispatched"];
+
+/** The Active/History partition for an EPIC (issue #298), the twin of feature runs'
+ * `deriveListBucket` (app/stage.ts). It exists because an epic must NOT vanish from the Active list
+ * the instant `plan.status` becomes `done`: `done` only means "the fan-out finished and ≥1 slice
+ * opened a PR, dispatched to convergence" (see the `Delivery` doc above — it "conflates hand-off with
+ * landing"), so a `done` epic whose slice PRs are still CONVERGING, or one that has fully LANDED but
+ * still needs its integration→main promotion PR raised, still needs the operator's attention.
+ *
+ * Bucket on the derived `delivery` rollup (the single source of truth this consumes), NOT raw
+ * `status`. An epic is *in-flight* (`active`) while:
+ *   • `status` is live (`planning`/`dispatched`), OR
+ *   • it is `done` and NOT yet acknowledged — a done epic stays visible/actionable (surfacing
+ *     `delivery_label`, e.g. "5/5 slices merged, promote to main") until the operator dismisses it,
+ *     mirroring feature runs' terminal tick-off. This deliberately covers `delivery = null` too:
+ *     record-results only reaches `done` with ≥1 opened PR (a zero-PR plan is `failed`, #86), so a
+ *     just-`done` epic whose `delivery` the poller has not yet projected must NOT flicker into
+ *     History — the very vanish this issue fixes. A `converging` epic is likewise Active, and its
+ *     Dismiss affordance stays closed (see {@link epicIsAcknowledgeable}) so it is never ticked off
+ *     mid-flight.
+ *
+ * It falls to `history` only once truly resolved: a `done` epic the operator has acknowledged, or a
+ * terminal non-`done` status (`failed`/`abandoned`, which carry their own incident signal and need no
+ * tick-off). Pure and read-only; projected at write time by the `plans` gateway (app/plan.ts) onto
+ * `plans.list_bucket`. */
+export function deriveEpicBucket(
+  status: string,
+  delivery: string | null | undefined,
+  acknowledgedAt: string | null | undefined,
+): "active" | "history" {
+  if (EPIC_LIVE_STATUSES.includes(status)) return "active";
+  if (status === "done") {
+    // A still-`converging` epic is Active regardless of any (stray) acknowledged_at — it is genuinely
+    // working and is not acknowledgeable, so it can never be ticked off mid-flight (fail-closed).
+    if (delivery === "converging") return "active";
+    // Otherwise `done` — landed or resolved-not-landed/poller-pending (`delivery = null`): stay Active
+    // until the operator dismisses it, so a just-`done` epic never flickers into History.
+    return (acknowledgedAt ?? null) === null ? "active" : "history";
+  }
+  return "history";
+}
+
+/** True iff an epic carries the operator "Dismiss" (acknowledge) affordance — a `done` epic whose
+ * fan-out has RESOLVED (it is no longer `converging`): every slice PR has reached a terminal state,
+ * whether all merged (`delivery = landed` — promote to main, then dismiss) or resolved-not-landed
+ * (`delivery = null` — some abandoned/converged). This is the set of Active epics a tick-off may move
+ * to History. A live (`planning`/`dispatched`) or still-`converging` epic is genuinely working —
+ * nothing to tick off — so its Dismiss stays closed; a `failed`/`abandoned` epic is already in
+ * History. The `acknowledgeEpic` operation guards on this (409 otherwise) and the gateway projects it
+ * to `plans.ack_open` (1/0) so the page's `showWhenField` Dismiss button renders only for a resolved-
+ * but-unacknowledged epic. */
+export function epicIsAcknowledgeable(
+  status: string,
+  delivery: string | null | undefined,
+): boolean {
+  return status === "done" && delivery !== "converging";
+}

package/app/epicBucket.test.ts

@@ -0,0 +1,57 @@
+// Read-model derivation test for the EPIC Active/History bucket (issue #298). `deriveEpicBucket` is
+// the single source of truth for `plans.list_bucket`, and `epicIsAcknowledgeable` gates the Dismiss
+// affordance (`plans.ack_open` + the acknowledge-epic 409 guard). The defect this guards: any epic
+// list that buckets on RAW terminal `status` (`done`) instead of the derived `delivery` rollup makes
+// an epic vanish from Active the instant `status=done` — while its slices are still converging, or
+// while it has landed but still needs its integration→main promotion PR.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { deriveEpicBucket, EPIC_LIVE_STATUSES, epicIsAcknowledgeable } from "./delivery.ts";
+
+test("a live epic (planning/dispatched) is always Active, whatever the delivery", () => {
+  for (const status of EPIC_LIVE_STATUSES) {
+    assertEquals(deriveEpicBucket(status, null, null), "active", `status=${status}`);
+    // delivery is always null pre-`done`, but guard the predicate anyway.
+    assertEquals(deriveEpicBucket(status, "converging", null), "active", `status=${status}`);
+  }
+});
+
+// The core regression (red before the fix): a `done` epic whose slices are still converging must NOT
+// fall to History just because `status=done`.
+test("done + converging -> Active (the epic must not vanish while slices converge)", () => {
+  assertEquals(deriveEpicBucket("done", "converging", null), "active");
+  // An operator has no way to acknowledge a converging epic away either.
+  assert(!epicIsAcknowledgeable("done", "converging"));
+});
+
+test("done + landed + unacknowledged -> Active (stays actionable until dismissed)", () => {
+  assertEquals(deriveEpicBucket("done", "landed", null), "active");
+  assert(epicIsAcknowledgeable("done", "landed"));
+});
+
+test("done + landed + acknowledged -> History", () => {
+  assertEquals(deriveEpicBucket("done", "landed", "2024-01-01T00:00:00Z"), "history");
+});
+
+// A `done` epic with no positive delivery signal is either just-`done` (the poller has not projected
+// `delivery` yet) or resolved-not-landed (every PR terminal, not all merged). Either way it must NOT
+// flicker into History on `status=done` alone — it stays Active and acknowledgeable until dismissed.
+test("done + delivery=null (poller-pending / resolved-not-landed) -> Active, acknowledgeable", () => {
+  assertEquals(deriveEpicBucket("done", null, null), "active");
+  assert(epicIsAcknowledgeable("done", null));
+  // Once the operator dismisses it (acknowledged), it settles to History.
+  assertEquals(deriveEpicBucket("done", null, "2024-01-01T00:00:00Z"), "history");
+});
+
+test("terminal non-done statuses (failed/abandoned) -> History, not acknowledgeable", () => {
+  for (const status of ["failed", "abandoned"]) {
+    assertEquals(deriveEpicBucket(status, null, null), "history", `status=${status}`);
+    assert(!epicIsAcknowledgeable(status, null), `status=${status}`);
+  }
+});
+
+// Fail-closed: an acknowledged timestamp on a still-converging epic must NOT drag it to History (only
+// a LANDED epic is acknowledgeable; a stale/premature stamp is ignored by the bucket).
+test("acknowledged_at on a converging epic is ignored -> still Active", () => {
+  assertEquals(deriveEpicBucket("done", "converging", "2024-01-01T00:00:00Z"), "active");
+});

package/app/epicSetValidation.test.ts

@@ -0,0 +1,169 @@
+// Unit coverage for the pure set-admission validator `validateEpicSet` (issue #292, slice S2). It
+// exercises the SHAPE + DAG rules directly (no HTTP / no admitPlan), mirroring how app/plan.test.ts
+// unit-tests the other pure plan helpers. The operation edge test
+// (operations/startEpicSet.admission.integration.test.ts) proves the composed door behaviour.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { EpicSetValidationError, validateEpicSet } from "./plan.ts";
+
+const REPO = "owner/repo";
+const key = (n: number) => `${REPO}#${n}`;
+
+function expectReject(fn: () => unknown): EpicSetValidationError {
+  try {
+    fn();
+  } catch (err) {
+    if (err instanceof EpicSetValidationError) return err;
+    throw err;
+  }
+  throw new Error("expected EpicSetValidationError, but validation passed");
+}
+
+test("valid linear DAG resolves every edge to plan keys", () => {
+  const edges = validateEpicSet(
+    [key(1), key(2), key(3)],
+    [
+      { consumer: key(2), producer: key(1), package: "p1", capabilityRef: key(1) },
+      { consumer: key(3), producer: key(2), package: "p2", capabilityRef: key(2) },
+    ],
+  );
+  assertEquals(edges, [
+    { consumer: key(2), producer: key(1), package: "p1", capabilityRef: key(1) },
+    { consumer: key(3), producer: key(2), package: "p2", capabilityRef: key(2) },
+  ]);
+});
+
+test("a diamond DAG (two producers into one consumer) is acyclic and accepted", () => {
+  const edges = validateEpicSet(
+    [key(1), key(2), key(3), key(4)],
+    [
+      { consumer: key(3), producer: key(1), package: "a", capabilityRef: key(1) },
+      { consumer: key(3), producer: key(2), package: "b", capabilityRef: key(2) },
+      { consumer: key(4), producer: key(3), package: "c", capabilityRef: key(3) },
+    ],
+  );
+  assertEquals(edges.length, 3);
+});
+
+test("empty set is rejected", () => {
+  assertEquals(expectReject(() => validateEpicSet([], [])).status, 400);
+});
+
+test("duplicate epic in the set is rejected", () => {
+  assertEquals(expectReject(() => validateEpicSet([key(1), key(1)], [])).status, 400);
+});
+
+test("edge endpoint outside the set is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet([key(1)], [{ consumer: key(1), producer: key(2), package: "p", capabilityRef: key(2) }]),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("self-edge is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet([key(1)], [{ consumer: key(1), producer: key(1), package: "p", capabilityRef: key(1) }]),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("blank package is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet(
+      [key(1), key(2)],
+      [{ consumer: key(2), producer: key(1), package: "  ", capabilityRef: key(1) }],
+    ),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("blank capabilityRef is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet(
+      [key(1), key(2)],
+      [{ consumer: key(2), producer: key(1), package: "p", capabilityRef: "" }],
+    ),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("a two-node cycle is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet(
+      [key(1), key(2)],
+      [
+        { consumer: key(2), producer: key(1), package: "p", capabilityRef: key(1) },
+        { consumer: key(1), producer: key(2), package: "p", capabilityRef: key(2) },
+      ],
+    ),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("a longer cycle (1→2→3→1) is rejected", () => {
+  const err = expectReject(() =>
+    validateEpicSet(
+      [key(1), key(2), key(3)],
+      [
+        { consumer: key(1), producer: key(2), package: "p", capabilityRef: key(2) },
+        { consumer: key(2), producer: key(3), package: "p", capabilityRef: key(3) },
+        { consumer: key(3), producer: key(1), package: "p", capabilityRef: key(1) },
+      ],
+    ),
+  );
+  assertEquals(err.status, 400);
+});
+
+test("a duplicate edge in one submission is collapsed, not rejected", () => {
+  const edges = validateEpicSet(
+    [key(1), key(2)],
+    [
+      { consumer: key(2), producer: key(1), package: "p", capabilityRef: key(1) },
+      { consumer: key(2), producer: key(1), package: "p", capabilityRef: key(1) },
+    ],
+  );
+  assertEquals(edges.length, 1);
+});
+
+test("edge endpoints given as issue URLs resolve to the same plan keys", () => {
+  const edges = validateEpicSet(
+    [key(1), key(2)],
+    [
+      {
+        consumer: `https://github.com/${REPO}/issues/2`,
+        producer: `https://github.com/${REPO}/issues/1`,
+        package: "p",
+        capabilityRef: `https://github.com/${REPO}/issues/1`,
+      },
+    ],
+  );
+  assertEquals(edges[0].consumer, key(2));
+  assertEquals(edges[0].producer, key(1));
+});
+
+// `deps` endpoints arrive untyped from the request body, so a padded-but-valid endpoint
+// (" owner/repo#1 ") must be trimmed and accepted — matching how the epic-member path trims — not
+// rejected as unparseable.
+test("whitespace-padded dep endpoints are trimmed and resolved", () => {
+  const edges = validateEpicSet(
+    [key(1), key(2)],
+    [{ consumer: ` ${key(2)} `, producer: `  ${key(1)}`, package: "p", capabilityRef: key(1) }],
+  );
+  assertEquals(edges, [{ consumer: key(2), producer: key(1), package: "p", capabilityRef: key(1) }]);
+});
+
+// `deps` arrives untyped from the request body, so a malformed entry must reject with a clean
+// EpicSetValidationError (400), never an uncaught TypeError. Each of these would previously have
+// thrown a raw TypeError (mapping to a 500 at the edge) before the defensive shape checks.
+for (const badDep of [
+  null,
+  "owner/repo#1", // non-object
+  {}, // missing endpoints
+  { consumer: 1, producer: key(1), package: "p", capabilityRef: key(1) }, // non-string consumer
+  { consumer: key(2), producer: key(1), package: 7, capabilityRef: key(1) }, // non-string package
+] as const) {
+  test(`malformed dep entry (${JSON.stringify(badDep)}) is rejected as a 400`, () => {
+    const err = expectReject(() => validateEpicSet([key(1), key(2)], [badDep]));
+    assertEquals(err.status, 400);
+  });
+}

package/app/migration045.test.ts

@@ -0,0 +1,97 @@
+// Regression guard for migration 045 (issue #292 slice S2): the durable constraints on the FK-FREE
+// admission-staging tables `admitted_epics` / `admitted_plan_deps`. Its sibling migration041.test.ts
+// proves `plan_deps` foreign-keys its consumer to an admitted `plans` row; this proves the staging
+// twin is deliberately NOT FK-constrained — it must accept an edge (and an epic) whose plan row does
+// not exist yet, since S2 stages BEFORE any `plans` row is materialized — while still rejecting a
+// self-edge (CHECK) and a duplicate (PRIMARY KEY), exactly like `plan_deps`.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // NOTE: deliberately NO `plans` table — the staging tables must apply and accept rows with no plan
+  // graph in existence (that is the whole point of FK-free staging).
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/045_epic_set_admission_staging.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+const insertEdge = (db: DatabaseSync, planKey: string, dependsOn: string) =>
+  db
+    .prepare(
+      `INSERT INTO admitted_plan_deps (plan_key, depends_on_plan_key, package, capability_ref, created_at)
+       VALUES (?, ?, '@nanobpm/p', ?, 't')`,
+    )
+    .run(planKey, dependsOn, dependsOn);
+
+const insertEpic = (db: DatabaseSync, planKey: string) =>
+  db
+    .prepare(
+      `INSERT INTO admitted_epics (plan_key, repo, issue_number, issue_url, base_branch, created_at)
+       VALUES (?, 'o/r', 1, 'https://github.com/o/r/issues/1', 'epic/a', 't')`,
+    )
+    .run(planKey);
+
+test("migration 045 applies cleanly with NO plans table (FK-free) and stages an edge", () => {
+  const db = migratedDb();
+  insertEdge(db, "o/r#2", "o/r#1"); // neither endpoint has a plans row — must NOT FK-fail
+  const row = db
+    .prepare("SELECT plan_key, depends_on_plan_key, package FROM admitted_plan_deps WHERE plan_key = ?")
+    .get("o/r#2") as { plan_key: string; depends_on_plan_key: string; package: string };
+  assertEquals(row.plan_key, "o/r#2");
+  assertEquals(row.depends_on_plan_key, "o/r#1");
+  assertEquals(row.package, "@nanobpm/p");
+});
+
+test("migration 045 stages an admitted epic with no plans row", () => {
+  const db = migratedDb();
+  insertEpic(db, "o/r#1");
+  const row = db.prepare("SELECT plan_key, base_branch FROM admitted_epics WHERE plan_key = ?").get("o/r#1") as {
+    plan_key: string;
+    base_branch: string;
+  };
+  assertEquals(row.plan_key, "o/r#1");
+  assertEquals(row.base_branch, "epic/a");
+});
+
+test("migration 045 CHECK rejects a self-edge", () => {
+  const db = migratedDb();
+  let threw = false;
+  try {
+    insertEdge(db, "o/r#1", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 045 PRIMARY KEY rejects a duplicate consumer→producer edge", () => {
+  const db = migratedDb();
+  insertEdge(db, "o/r#2", "o/r#1");
+  let threw = false;
+  try {
+    insertEdge(db, "o/r#2", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 045 PRIMARY KEY rejects a duplicate staged epic", () => {
+  const db = migratedDb();
+  insertEpic(db, "o/r#1");
+  let threw = false;
+  try {
+    insertEpic(db, "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});