@nanobpm/nano-workforce 0.91.0 → 0.93.0

package/openapi.yaml

@@ -845,6 +845,159 @@ components:
         alreadyRunning:
           type: boolean
           description: True when a non-terminal feature run for this issue already exists; no new instance was started.
+    EpicSetStart:
+      description: >-
+        The set/batch admission request body (issue #292, slice S2). Submits a SET of epics plus the
+        inter-epic dependency edges between them. `epics` is admitted all-or-nothing through the same
+        `admitPlan` gate as the single-issue door; `deps` declares that a `consumer` epic waits for a
+        `producer` epic's published `{ package, capabilityRef }` capability. Every edge must connect
+        two epics named in `epics`, and the edge set must be an acyclic DAG — otherwise the whole set
+        is rejected with a 4xx and nothing is persisted.
+      type: object
+      additionalProperties: false
+      required:
+        - epics
+      properties:
+        epics:
+          type: array
+          minItems: 1
+          description: The epics to admit as one set. Each is admitted through the `admitPlan` gate.
+          items:
+            $ref: "#/components/schemas/EpicSetMember"
+        deps:
+          type: array
+          description: >-
+            The inter-epic dependency edges. Each declares `consumer` waits for `producer` to publish
+            the `{ package, capabilityRef }` capability. Both endpoints must name epics in `epics`.
+            Omit or pass `[]` for a set of independent (root) epics.
+          items:
+            $ref: "#/components/schemas/EpicSetDep"
+    EpicSetMember:
+      description: >-
+        One epic in a submitted set. Names the target issue by EXACTLY ONE of `issue`
+        (`owner/repo#123`) or `url` (a bare issue URL), plus a REQUIRED `baseBranch` and the optional
+        admission acknowledgements — the same per-epic admission inputs as `PlanStart`.
+      oneOf:
+        - $ref: "#/components/schemas/EpicSetMemberByIssue"
+        - $ref: "#/components/schemas/EpicSetMemberByUrl"
+    EpicSetMemberByIssue:
+      type: object
+      additionalProperties: false
+      required:
+        - issue
+        - baseBranch
+      properties:
+        issue:
+          type: string
+          description: "Issue reference: owner/repo#123."
+        baseBranch:
+          type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED integration branch this epic branches off and opens its PRs against, admitted
+            through the same ADR 0003 policy as the single-issue door. See `PlanStartByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: Opt in to sharing a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
+          description: Acknowledge that `baseBranch` names the repository default branch. See `PlanStartByIssue.confirmDefaultBase`.
+    EpicSetMemberByUrl:
+      type: object
+      additionalProperties: false
+      required:
+        - url
+        - baseBranch
+      properties:
+        url:
+          type: string
+          description: A bare issue URL, when no `owner/repo#123` reference is supplied.
+        baseBranch:
+          type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: REQUIRED integration branch this epic branches off. See `EpicSetMemberByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
+          description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.
+    EpicSetDep:
+      description: >-
+        One inter-epic dependency edge: the `consumer` epic waits for the `producer` epic to publish
+        the `{ package, capabilityRef }` capability. `consumer`/`producer` are epic references
+        (`owner/repo#123` or an issue URL) that MUST both appear in the set's `epics`.
+      type: object
+      additionalProperties: false
+      required:
+        - consumer
+        - producer
+        - package
+        - capabilityRef
+      properties:
+        consumer:
+          type: string
+          description: The dependent epic (waits). An `owner/repo#123` reference or issue URL in the set.
+        producer:
+          type: string
+          description: The producer epic it waits for. An `owner/repo#123` reference or issue URL in the set.
+        package:
+          type: string
+          minLength: 1
+          description: The producer epic's published package name — the capability probe's target (S3).
+        capabilityRef:
+          type: string
+          minLength: 1
+          description: The producer epic's issue handle, used to resolve which published pkg@version first carries the capability (S3).
+    StartEpicSetResult:
+      description: The result of a successful set admission — the epics admitted and the edges staged (FK-free in `admitted_plan_deps`) for S3 to materialize.
+      type: object
+      required:
+        - epics
+        - roots
+        - edges
+      properties:
+        epics:
+          type: array
+          description: Every epic admitted, with its normalized base branch.
+          items:
+            type: object
+            required:
+              - planKey
+              - baseBranch
+            properties:
+              planKey:
+                type: string
+              baseBranch:
+                type: string
+        roots:
+          type: array
+          description: The plan keys of epics with NO inbound edge — the roots S3 starts immediately.
+          items:
+            type: string
+        edges:
+          type: array
+          description: The inter-epic edges staged FK-free into `admitted_plan_deps` for S3 to materialize into `plan_deps` (endpoints resolved to plan keys).
+          items:
+            type: object
+            required:
+              - consumer
+              - producer
+              - package
+              - capabilityRef
+            properties:
+              consumer:
+                type: string
+              producer:
+                type: string
+              package:
+                type: string
+              capabilityRef:
+                type: string
     ConvergenceStart:
       description: The start-convergence request body. Names the target PR by EXACTLY ONE of `pr`
         (an `owner/repo#123` reference) or `url` (a bare PR URL) — never both, never neither — with
@@ -1620,6 +1773,47 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/start/epic-set:
+    post:
+      operationId: startEpicSet
+      summary: Admit a SET of epics plus their inter-epic dependency edges in one all-or-nothing call (issue #292).
+      description: >-
+        The set/batch admission door (slice S2). Validates the WHOLE submission before persisting
+        anything: each epic passes the same `admitPlan` gate as the single-issue door, every edge must
+        connect two epics in the submitted set, and the edge set must be an acyclic DAG. A malformed
+        set fails as one clean 4xx at the offending epic/edge with nothing half-started — no edge is
+        persisted. On success the admitted epics and validated edges are staged FK-free into
+        `admitted_epics` / `admitted_plan_deps`; materializing them into `plans` / `plan_deps` and
+        scheduling/lowering (starting roots, seeding the capability readiness-gate, version binding)
+        is a later slice (S3).
+        Idempotent on the set: re-submitting the identical set records no duplicate edge.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EpicSetStart"
+      responses:
+        "202":
+          description: The whole set validated; every epic was admitted and every edge staged FK-free (in `admitted_plan_deps`) for S3 to materialize.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StartEpicSetResult"
+        "400":
+          description: >-
+            The set is malformed — an unparseable epic/edge reference, a rejected base branch, an edge
+            naming an epic outside the set, or a dependency cycle.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "409":
+          description: An epic's base branch is already in use by another active epic (shared-base guard).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/feature:
     post:
       operationId: startFeature
@@ -1898,6 +2092,57 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-epic:
+    post:
+      operationId: acknowledgeEpic
+      summary: "Dismiss a RESOLVED epic (issue #298). Stamps `acknowledged_at` on the `plans` row so
+        the gateway recomputes its `list_bucket` to 'history' (and `ack_open` to 0), dropping the
+        resolved epic out of the Active epic list into History. The epic twin of acknowledge-done, but
+        a resolved epic is not parked at a user task, so this completes no user task and only writes the
+        row. Keyed on the epic's `plan_key`. Rejects (409) an epic that is not yet resolved (still
+        `planning`/`dispatched`, or `done` but still `converging`), so a converging epic stays visible
+        in Active. Idempotent-safe (re-acknowledging keeps it in History)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - plan_key
+              properties:
+                plan_key:
+                  type: string
+                  minLength: 1
+                  description: The epic's key (plans.plan_key, `<owner>/<repo>#<n>`).
+      responses:
+        "200":
+          description: The resolved epic was acknowledged and moved to History. Applies to any
+            resolved epic — whether all slices merged (`delivery=landed`) or it resolved-not-landed
+            (`delivery=null`), not only landed epics.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field (plan_key) was missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No epic matches the plan_key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "409":
+          description: The epic is not yet resolved (still planning/dispatched, or converging), so it cannot be dismissed yet.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation

package/operations/acknowledgeEpic.test.ts

@@ -0,0 +1,130 @@
+// Tests for the POST /app/api/actions/acknowledge-epic operation `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic — landed (`delivery=landed`) or
+// resolved-not-landed (`delivery=null`); only still-`converging` epics are rejected. It stamps
+// `acknowledged_at` via the plans gateway, which recomputes `list_bucket` to 'history' (and
+// `ack_open` to 0), dropping the resolved epic from Active into History. Unlike acknowledge-blocked
+// it completes NO user task (a resolved epic is not parked). The epic twin of acknowledge-done.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { plans } from "../app/plan.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./acknowledgeEpic.ts";
+
+// An in-memory data layer wired through the REAL plans gateway proxy, so the test exercises the
+// gateway's list_bucket/ack_open projection exactly as production does.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  const stores: Record<string, any[]> = { plans: seed };
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  const app = {
+    data: { table: (n: string, pk?: string) => tbl(n, pk) },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, rows: stores.plans };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-epic: stamps acknowledged_at and flips list_bucket to 'history' on a landed epic", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#1", status: "done", delivery: "landed", acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (landed, unacknowledged → active).
+  await plans(app.data).update("o/r#1", { delivery: "landed" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#1" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a still-converging epic is rejected (409) and stays Active", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2", status: "done", delivery: "converging", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#2", { delivery: "converging" });
+
+  const res = await call(app, { plan_key: "o/r#2" });
+
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  // Untouched: no premature acknowledged_at, still Active.
+  assertEquals(rows[0].acknowledged_at, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("acknowledge-epic: a resolved-not-landed epic (delivery=null) is accepted (200) and flips to History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2b", status: "done", delivery: null, acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (resolved-not-landed, unacknowledged → active).
+  await plans(app.data).update("o/r#2b", { delivery: null });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#2b" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a live (dispatched) epic is rejected (409)", async () => {
+  const { app } = memApp([{ plan_key: "o/r#3", status: "dispatched", delivery: null, acknowledged_at: null }]);
+  const res = await call(app, { plan_key: "o/r#3" });
+  assertEquals(res.status, 409);
+});
+
+test("acknowledge-epic: a missing plan_key → 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, {});
+  assertEquals(res.status, 400);
+});
+
+test("acknowledge-epic: no matching epic → 404", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { plan_key: "o/r#404" });
+  assertEquals(res.status, 404);
+});
+
+test("acknowledge-epic: idempotent — re-acknowledging a landed epic keeps it in History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#5", status: "done", delivery: "landed", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#5", { delivery: "landed" });
+
+  assertEquals((await call(app, { plan_key: "o/r#5" })).status, 200);
+  const firstStamp = rows[0].acknowledged_at;
+  assertEquals(rows[0].list_bucket, "history");
+
+  const res2 = await call(app, { plan_key: "o/r#5" });
+  assertEquals(res2.status, 200);
+  assertEquals(rows[0].list_bucket, "history");
+  // Re-stamped (a fresh timestamp) but still resolved.
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  void firstStamp;
+});

package/operations/acknowledgeEpic.ts

@@ -0,0 +1,63 @@
+// POST /app/api/actions/acknowledge-epic → operationId `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic: an operator dismisses a `done` epic whose
+// fan-out has finished (all slice PRs reached a terminal state — whether all merged/landed or
+// resolved-not-landed) directly from the Epic / Overview pages so it drops out of the Active epic list
+// into History. It is the epic twin of `acknowledgeDone` (the feature-run tick-off) — a resolved epic
+// is NOT parked at a user task, so this op completes no user task and touches no engine/ledger: it
+// simply stamps `acknowledged_at` on the `plans` row via the plans gateway.
+//
+// The gateway (app/plan.ts) recomputes `list_bucket`/`ack_open` on that write — a landed, now-
+// acknowledged epic flips `list_bucket` to 'history' and `ack_open` to 0 — so this op NEVER hand-sets
+// a derived projection. Keyed on the row's `plan_key`. Idempotent-safe: re-acknowledging re-stamps
+// the timestamp and keeps the row in History.
+//
+// It rejects (409) an epic that is NOT yet resolved — i.e. anything the `epicIsAcknowledgeable`
+// guard refuses: a non-`done` status (`planning`/`dispatched`), or `done` but still `converging`. A
+// resolved epic is acknowledgeable whether all slices merged (`delivery=landed`) or it resolved-not-
+// landed (`delivery=null`); only a still-live or still-converging epic is refused, so those stay
+// visible in Active and can never pre-seed the tick-off.
+
+import { epicIsAcknowledgeable } from "../app/delivery.ts";
+import { plans } from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgeEpic", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-epic rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "plan_key is required" } };
+  }
+
+  const planKey = str(body.plan_key);
+  if (!planKey) return { status: 400, body: { ok: false, error: "plan_key is required" } };
+
+  const table = plans(app.data);
+  const plan = await table.get(planKey);
+  if (!plan) {
+    app.log.warn("acknowledge-epic: no such plan", { planKey });
+    return { status: 404, body: { ok: false, error: "no such epic" } };
+  }
+
+  // Guard: only a RESOLVED epic (`status=done` and no longer `converging`) carries the Dismiss
+  // affordance. Acknowledging a live/converging epic would pre-seed `acknowledged_at`, so the moment
+  // it later resolved `deriveEpicBucket` would drop it straight into History, skipping the operator
+  // tick-off this op exists to require — and a converging epic must stay visible while its slices land.
+  if (!epicIsAcknowledgeable(plan.status, plan.delivery ?? null)) {
+    app.log.warn("acknowledge-epic rejected: epic is not resolved", {
+      planKey,
+      status: plan.status,
+      delivery: plan.delivery ?? null,
+    });
+    return { status: 409, body: { ok: false, error: "epic is not resolved" } };
+  }
+
+  // Stamp the dismissal. The gateway recomputes `list_bucket` (→ 'history') and `ack_open` (→ 0) from
+  // the merged row, so we never hand-set them here. Idempotent: re-acknowledging re-stamps and stays
+  // in History.
+  const now = new Date().toISOString();
+  await table.update(planKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator dismissed resolved epic", { planKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});