@nanobpm/nano-workforce 0.200.7 → 0.200.8

package/test/derivation-parity/derivation-parity.test.ts

@@ -173,33 +173,57 @@ test("loop() inserts a gateway head, so back-edges cannot merge into a task", ()
 // structured topology (clears class 2), but issue #745 added the engine-native
 // AgentTask marker `<zeebe:agentDefinition agentType="external" />` to its two
 // prompt-bearing `senior:*` tasks and the published compiler cannot emit it.
-// Prove the blocker is real AND that it is the ONLY divergence, so the parked
-// entry is a complete, verified port held ready — not an abandoned one.
-test("retro's complete port differs from its golden by ONLY the agent-task marker", () => {
+// Issue #849 then added an interrupting `agentSlaTimeout` timer boundary to each
+// of those tasks (routing to the `conformance-escalation` user task) — the
+// code-first builder cannot express a boundary event on a task either (its
+// `FlowNode` union has no such node; AGENTS.md). Prove the blockers are real AND
+// that they are the ONLY divergence, so the parked entry is a complete, verified
+// port held ready — not an abandoned one.
+test("retro's complete port differs from its golden by ONLY the agent-task marker + SLA boundaries", () => {
   const golden = readFileSync(goldenPath("retro"), "utf8");
   const derived = declarativeToBpmn(retroFlow);
   const markers = (xml: string): number =>
     (xml.match(/<(?:\w+:)?agentDefinition\b[^>]*\bagentType="external"/g) ?? []).length;
+  const boundaries = (xml: string): number =>
+    (xml.match(/<(?:\w+:)?boundaryEvent\b/g) ?? []).length;
 
   // (a) the golden really carries the marker, on BOTH of its agent tasks — and it
   //     cannot simply be dropped: app/agentic/vocab/agent-marker.test.ts is a
   //     defect-class guard requiring it on every deployed prompt-bearing agent task.
   assertEquals(markers(golden), 2, "retro's golden should mark senior:conformance and senior:retro");
+  //     …and each marked task is SLA-bounded (issue #849; the defect-class guard is
+  //     app/agentic/vocab/agent-sla-boundary.test.ts).
+  assertEquals(boundaries(golden), 2, "retro's golden should SLA-bound both agent tasks");
 
-  // (b) the published compiler emits none of it — the blocker is real, not a guess.
-  //     When this starts failing, upstream task() grew marker support: un-park retro
-  //     by threading `retroFlow` back into its PORTS entry in ./flows.ts.
+  // (b) the published compiler emits none of it — the blockers are real, not a guess.
+  //     When the marker assertion starts failing, upstream task() grew marker support;
+  //     when the boundary assertion starts failing, the builder grew boundary events:
+  //     un-park retro by threading `retroFlow` back into its PORTS entry in ./flows.ts.
   assertEquals(markers(derived), 0, "@nanobpm/workflow can now emit <zeebe:agentDefinition/> — un-park retro");
+  assertEquals(boundaries(derived), 0, "@nanobpm/workflow can now emit boundary events — un-park retro");
 
-  // (c) strip exactly the marker lines from the golden and the port derives the
-  //     WHOLE model green, through the shared harness's own normalize/equality —
-  //     so nothing but the marker diverges.
-  const unmarked = golden.replace(/^[ \t]*<(?:\w+:)?agentDefinition\b[^>]*\/>[ \t]*\r?\n/gm, "");
+  // (c) strip exactly the marker lines AND the SLA boundary blocks (plus their
+  //     sequence flows, the two SLA recorder service tasks they feed, and the
+  //     extra incomings on the escalation user task) from the golden and the port
+  //     derives the WHOLE model green, through the shared harness's own
+  //     normalize/equality — so nothing but the marker + SLA-escalation apparatus
+  //     diverges.
+  const unmarked = golden
+    .replace(/^[ \t]*<(?:\w+:)?agentDefinition\b[^>]*\/>[ \t]*\r?\n/gm, "")
+    .replace(/^[ \t]*<(?:\w+:)?boundaryEvent\b[\s\S]*?<\/(?:\w+:)?boundaryEvent>\r?\n/gm, "")
+    // the SLA recorder service tasks (record-conformance-sla / record-synthesize-sla) and the
+    // `<!-- Agent-SLA recorders: … -->` comment block immediately preceding them
+    .replace(/^[ \t]*<!--[\s\S]*?-->[ \t]*\r?\n(?=[ \t]*<(?:\w+:)?serviceTask\b[^>]*\bid="record-(?:conformance|synthesize)-sla")/gm, "")
+    .replace(/^[ \t]*<(?:\w+:)?serviceTask\b[^>]*\bid="record-(?:conformance|synthesize)-sla"[\s\S]*?<\/(?:\w+:)?serviceTask>\r?\n/gm, "")
+    .replace(/^[ \t]*<(?:\w+:)?sequenceFlow\b[^>]*\bsourceRef="be_[^"]*"[^>]*\/>[ \t]*\r?\n/gm, "")
+    .replace(/^[ \t]*<(?:\w+:)?sequenceFlow\b[^>]*\bsourceRef="record-(?:conformance|synthesize)-sla"[^>]*\/>[ \t]*\r?\n/gm, "")
+    .replace(/^[ \t]*<(?:\w+:)?incoming>f_(?:conformanceSla|synthesizeSla)(?:ToEsc)?<\/(?:\w+:)?incoming>[ \t]*\r?\n/gm, "");
   assertEquals(markers(unmarked), 0, "the strip must remove every marker line");
+  assertEquals(boundaries(unmarked), 0, "the strip must remove every SLA boundary");
   const expected = normalize(unmarked);
   const actual = normalize(derived);
   assert(
     modelsEqual(expected, actual),
-    `retro's port must derive its golden once the agent-task marker is stripped — residual drift:\n${diffModels(expected, actual)}`,
+    `retro's port must derive its golden once the agent-task marker and SLA boundaries are stripped — residual drift:\n${diffModels(expected, actual)}`,
   );
 });

package/test/derivation-parity/flows.ts

@@ -133,7 +133,20 @@ export const retroFlow: DeclarativeFlow = defineFlow(
       jobType: "senior:conformance",
       prompt: { resourceId: "prompts/conformance.md", bindingType: "latest", append: "=conformanceDigest" },
     });
-    w.task("record-conformance", { jobType: "pr.conformance-record" });
+    w.task("record-conformance", {
+      jobType: "pr.conformance-record",
+      // The golden pins both SLA-mode control flags to `=false` on this NORMAL-path recorder
+      // (round-7 review, PR #864): the flags share the external conformance agent's result
+      // namespace, so a hoisted agent output must never select the SLA/preserve branch. The port
+      // reproduces those pins so the parity diagnostic's only residual is the class-3 marker +
+      // SLA boundaries.
+      io: {
+        input: [
+          { source: "=false", target: "agentSlaElapsed" },
+          { source: "=false", target: "preserveConformance" },
+        ],
+      },
+    });
     w.branch("hasDeviations = true", {
       then: (b) => {
         b.human("conformance-escalation", {

package/workers/conformance-record/worker.test.ts

@@ -1,5 +1,8 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { test } from "node:test";
-import { assertEquals, assertRejects } from "#test-assert";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals, assertRejects } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
@@ -239,3 +242,86 @@ test("conformance-record: fails (not a silent, untrackable escalation) when ther
   // Nothing was persisted: the throw precedes the write, so no untrackable row is left behind.
   assertEquals(stores.plan_conformance.length, 0);
 });
+
+test("conformance-record: an agent-SLA timeout persists a reviewing row (so the ack finds it) with no deviations", async () => {
+  const { app, stores } = fakeApp();
+  // The retro SLA arm routes here with agentSlaElapsed=true + an SLA summary and NO agent verdict
+  // (the conformance/synthesize agent timed out). The shared conformance-escalation ack task always
+  // runs pr.conformance-ack → acknowledgeConformance, which THROWS when no plan_conformance row
+  // exists — so the SLA path must persist a `reviewing` row even though nothing was scored.
+  const out = await handler(
+    {
+      processInstanceKey: "retro-inst-13",
+      variables: {
+        planKey: "o/r#13",
+        agentSlaElapsed: true,
+        summary: "The spec-conformance agent exceeded its time budget (SLA PT2H) without returning a verdict.",
+      },
+    } as any,
+    app as any,
+  );
+  const row = stores.plan_conformance[0];
+  // A timeout produces no verdict: status coerces to skipped, all counts zeroed, has_deviations 0 …
+  assertEquals(row.status, "skipped");
+  assertEquals(row.has_deviations, 0);
+  // … but the row IS parked at `reviewing` (keyed off the instance) so acknowledgeConformance settles
+  // it instead of throwing, and the Tasks inbox shows the SLA-timeout summary as the reason.
+  assertEquals(row.review_status, "reviewing");
+  assertEquals(row.process_key, "retro-inst-13");
+  assertEquals(row.summary, "The spec-conformance agent exceeded its time budget (SLA PT2H) without returning a verdict.");
+  // The SLA arm routes to the escalation task directly (not via gw-deviations), so the returned flag
+  // stays the ground-truth `hasDeviations` (false) — it is not read on the SLA path.
+  assertEquals(out, { hasDeviations: false });
+});
+
+test("conformance-record: an agent-SLA timeout with no processKey fails loudly (untrackable escalation)", async () => {
+  const { app, stores } = fakeApp();
+  await assertRejects(
+    () =>
+      handler(
+        { variables: { planKey: "o/r#14", agentSlaElapsed: true, summary: "sla" } } as any,
+        app as any,
+      ),
+    Error,
+    "no processInstanceKey",
+  );
+  assertEquals(stores.plan_conformance.length, 0);
+});
+
+// DEFECT-CLASS GUARD (PR #864 review r4181010853): the SLA-control flags `agentSlaElapsed` and
+// `preserveConformance` share the process-variable namespace the external conformance agent's
+// result-JSON is hoisted into. If a `pr.conformance-record` task does NOT pin both flags to a
+// literal via ioMapping, a completed agent that emits `agentSlaElapsed:true` / `preserveConformance:true`
+// could make the NORMAL recorder persist `review_status='reviewing'` (or take the preserve branch)
+// while `gw-deviations` routes away from the ack task — leaving the row permanently stuck. Every
+// recorder task must therefore pin BOTH flags to a constant so agent output can never select this
+// internal control path. This structural guard fails if any recorder (now or a future one) forgets.
+const RETRO_BPMN = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../resources/processes/retro.bpmn",
+);
+const SERVICE_TASK = /<bpmn:serviceTask\b[\s\S]*?<\/bpmn:serviceTask>/g;
+
+test("DEFECT-CLASS GUARD: every pr.conformance-record task pins agentSlaElapsed + preserveConformance to a literal (agent output cannot select SLA control path)", () => {
+  const xml = readFileSync(RETRO_BPMN, "utf8");
+  const recorders: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    if (!/type="pr\.conformance-record"/.test(block)) continue;
+    const id = block.match(/<bpmn:serviceTask\b[^>]*\bid="([^"]*)"/)?.[1] ?? "(unknown)";
+    recorders.push(id);
+    for (const flag of ["agentSlaElapsed", "preserveConformance"]) {
+      // A literal pin is `<zeebe:input source="=true|false" target="<flag>" />` — the source must be
+      // a boolean constant, NOT a process-variable reference (which would read hoisted agent output).
+      const pin = new RegExp(
+        `<zeebe:input\\s+source="=(?:true|false)"\\s+target="${flag}"\\s*/>`,
+      );
+      assert(
+        pin.test(block),
+        `retro.bpmn: record task "${id}" does not pin "${flag}" to a literal — agent output could ` +
+          `select the internal SLA/preserve control path (PR #864 review r4181010853)`,
+      );
+    }
+  }
+  // Sanity: there really are recorder tasks (guard is not vacuously green) — normal + 2 SLA arms.
+  assert(recorders.length >= 3, `expected >=3 pr.conformance-record tasks, found ${recorders.length}`);
+});

package/workers/conformance-record/worker.ts

@@ -9,7 +9,7 @@
 // reads `status`/`pr`/`summary` through), and exposes the raw transcript under the
 // `io.nanobpm.agentResult` envelope's `.output`.
 import type { AppJobHandler } from "@nanobpm/urban";
-import { recordConformance } from "../../app/conformance.ts";
+import { markConformanceSynthesisSla, recordConformance } from "../../app/conformance.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
@@ -81,6 +81,22 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // the same `String(...)` coercion app/service.ts applies when it stamps `process_key`.
   const processKey = job.processInstanceKey != null ? String(job.processInstanceKey) : null;
 
+  // Agent-SLA path (issue #849 review): the conformance/synthesize agent's interrupting timer
+  // boundary fired (retro.bpmn routes the SLA arm here with `agentSlaElapsed=true` + an SLA summary).
+  // The agent produced no verdict, so there is nothing to score — but the shared conformance-escalation
+  // ack task ALWAYS runs `pr.conformance-ack`, whose `acknowledgeConformance` throws when no
+  // `plan_conformance` row exists. Persist a `reviewing` row so the ack settles it and the Tasks inbox
+  // shows the SLA-timeout reason. This escalates exactly like a deviations finding.
+  const agentSlaElapsed = asBool(job.variables.agentSlaElapsed);
+  const escalate = hasDeviations || agentSlaElapsed;
+
+  // Synthesis-SLA preserve path (PR #864 review): the `record-synthesize-sla` arm runs AFTER
+  // `record-conformance` already persisted a real verdict, so it sets `preserveConformance=true` to
+  // flip the row to `reviewing` + append the synthesis-timeout context WITHOUT overwriting the filed
+  // status/counts/report/summary. Only the synthesize arm sets this; the conformance-SLA arm
+  // (`record-conformance-sla`) interrupts BEFORE any verdict exists, so it takes the upsert below.
+  const preserveConformance = asBool(job.variables.preserveConformance);
+
   // Invariant: an escalation must be trackable. If we found deviations to escalate but have no
   // process key to key the `reviewing` row off, the `hasDeviations` return below would still route
   // retro to the `conformance-escalation` user task — yet `pollUserTasks` can never surface that ack
@@ -88,13 +104,23 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // escalation wedges forever, invisible to any human. Rather than record that silent, unreachable
   // state, fail loudly so the run retries/alerts. `job.processInstanceKey` is always present for an
   // activated job, so this only fires on a genuine engine-contract violation.
-  if (hasDeviations && processKey == null) {
+  if (escalate && processKey == null) {
     throw new Error(
-      `conformance-record: ${planKey} has deviations to escalate but no processInstanceKey to track ` +
+      `conformance-record: ${planKey} has an escalation to record but no processInstanceKey to track ` +
         "the escalation — refusing to route to an untrackable conformance-escalation ack task",
     );
   }
 
+  if (preserveConformance) {
+    // Preserve the existing conformance verdict; only mark it reviewing + append the SLA reason.
+    await markConformanceSynthesisSla(app.data, planKey, {
+      summary: summary ?? "The retrospective-synthesis agent exceeded its time budget without completing.",
+      processKey,
+    });
+    app.log.info(`conformance-record: ${planKey} — synthesis SLA, preserved existing verdict (reviewing)`);
+    return { hasDeviations };
+  }
+
   await recordConformance(app.data, planKey, {
     status,
     commentUrl: filed ? commentUrl : null,
@@ -110,17 +136,18 @@ const handler: AppJobHandler<In> = async (job, app) => {
     // Only enter the `reviewing` inbox scan when we actually have a `processKey` to key off — a
     // null key can never be found by `pollUserTasks` (it skips rows without `process_key`) nor
     // cleared by the `instanceTracking` `onTerminated` binding, so a `reviewing` row with no key
-    // would wedge forever. The invariant guard above already rejected `hasDeviations` with a null
+    // would wedge forever. The invariant guard above already rejected any escalation with a null
     // key, so `reviewing` here always carries a non-null `processKey`.
-    reviewStatus: hasDeviations ? "reviewing" : "reviewed",
+    reviewStatus: escalate ? "reviewing" : "reviewed",
   });
 
   app.log.info(
-    `conformance-record: ${planKey} — status=${status} deviations=${hasDeviations ? "yes" : "no"}`,
+    `conformance-record: ${planKey} — status=${status} deviations=${hasDeviations ? "yes" : "no"} agentSla=${agentSlaElapsed ? "yes" : "no"}`,
   );
   // Return the ground-truth `hasDeviations` as a process variable so the `gw-deviations` gateway
   // routes to the human ack task (retro.bpmn) — overriding the agent's hoisted flag with the value
-  // reconciled against the recorded counts above.
+  // reconciled against the recorded counts above. (The SLA arm routes to the escalation task
+  // directly, not through gw-deviations, so this flag is only read on the normal path.)
   return { hasDeviations };
 };