@nanobpm/nano-workforce 0.130.0 → 0.131.0

package/app/deliveryGraphCompiler.ts

@@ -37,6 +37,7 @@ import type {
 } from "../nano-generated/api-io.d.ts";
 import { DELIVERY_CONNECTOR_TASK_TYPE } from "./deliveryConnector.ts";
 import {
+  analyzeExclusiveTopology,
   type DeliveryGraphError,
   deliveryNodeFacts,
   resolveDeliveryFrom,
@@ -105,6 +106,15 @@ function escapeXml(value: string): string {
     .replace(/'/g, "'");
 }
 
+/** Escape a string for XML ELEMENT TEXT content while KEEPING literal double-quotes — the convention
+ * every authored `<bpmn:conditionExpression>` FEEL uses (e.g. `=status = "converged"`). Only `&`, `<`,
+ * `>` are entity-escaped (required for text-node well-formedness); quotes stay literal so a FEEL string
+ * literal survives to the engine. Safe because the compiler grafts DI onto its own semantic XML without
+ * re-serializing it, so these text nodes are never round-tripped/normalized. Deterministic and total. */
+function escapeXmlText(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 /** Render a `name=value` XML attribute, choosing the delimiter so FEEL string literals survive the
  * WASM engine's deploy path. That path does NOT decode `&#34;`/`&quot;` entities before FEEL parsing,
  * so a FEEL expression containing a string literal MUST use a SINGLE-QUOTE attribute delimiter with
@@ -168,13 +178,44 @@ function feelStr(value: string): string {
   return JSON.stringify(value);
 }
 
+/** Render a guard `equals` literal (S7) as its FEEL form — a string becomes a `"…"` literal, a number
+ * its decimal, a boolean `true`/`false`. `undefined` renders as `""` so it can double as a stable sort
+ * key for edges without a guard. Deterministic and total over the `string|number|boolean` scalar set. */
+function feelLiteral(value: string | number | boolean | undefined): string {
+  if (typeof value === "string") return feelStr(value);
+  if (typeof value === "number") return String(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return "";
+}
+
+/** The FEEL predicate a guarded edge (S7) contributes to its exclusive-split flow condition — e.g.
+ * `n0_result = "breaking"` — comparing the producer's published `<element>_<fact>` variable to the
+ * edge's `equals` literal. `when` names `<fromNode>.<fact>` (validated: a scalar fact of this edge's
+ * producer), so the variable is `<producerElement>_<fact>`. Returns `undefined` for a plain or default
+ * edge (no `when`). Deterministic. */
+function guardConditionPart(
+  edge: ResolvedDeliveryEdge,
+  elementById: ReadonlyMap<string, string>,
+  nodeFacts: ReadonlyMap<string, ReadonlySet<string>>,
+): string | undefined {
+  if (edge.when === undefined || edge.default === true) return undefined;
+  const { fact } = resolveDeliveryFrom(edge.when, nodeFacts);
+  if (fact === undefined) return undefined;
+  const producerElement = elementById.get(edge.fromNode) ?? edge.fromNode;
+  return `${producerElement}_${fact} = ${feelLiteral(edge.equals)}`;
+}
+
 /** One sequence flow in the compiled process — `source`/`target` are element ids, `name` an optional
- * (fact) label. */
+ * (fact / guard) label. `condition` is a FEEL boolean guard rendered as a `<bpmn:conditionExpression>`
+ * child (S7 guarded edge); `isDefault` marks the exclusive split's default (else) flow, whose id the
+ * split gateway carries as its `default` attribute. */
 interface Flow {
   id: string;
   source: string;
   target: string;
   name?: string;
+  condition?: string;
+  isDefault?: boolean;
 }
 
 /** One late-binding input a consumer node receives (S4): the producer node's business id, the
@@ -187,14 +228,18 @@ interface BoundInput {
 }
 
 /** A compiled node's structural fixtures: its own BPMN `element` id, and — when it has >1 downstream
- * or >1 upstream — the parallel fork/join gateway that fans its flow out/in. `entry` is the id
- * upstream flows target (the join, else the element); `exit` is the id downstream flows leave from
- * (the fork, else the element). */
+ * or >1 upstream — the fork/join gateway that fans its flow out/in. `entry` is the id upstream flows
+ * target (the join, else the element); `exit` is the id downstream flows leave from (the fork, else
+ * the element). `forkExclusive`/`joinExclusive` select an EXCLUSIVE gateway (S7): a guarded-split
+ * source forks on an `exclusiveGateway` (data-based branch), and a fan-in reconverging exclusive
+ * branches joins on an `exclusiveGateway` (first-token-proceeds) rather than a parallel AND-join. */
 interface NodeWiring {
   node: DeliveryNode;
   element: string;
   forkGateway?: string;
   joinGateway?: string;
+  forkExclusive: boolean;
+  joinExclusive: boolean;
   entry: string;
   exit: string;
 }
@@ -239,19 +284,27 @@ export async function compileDeliveryGraph(
   const edges = Array.isArray(typed.edges) ? typed.edges : [];
 
   // Resolve every edge's `from` endpoint against the SAME node/fact map the validator checked (shared
-  // helper — no drift), then sort edges deterministically by (consumer, producer, fact).
+  // helper — no drift), then sort edges deterministically by (consumer, producer, fact). Guard fields
+  // (`when`/`equals`/`default`, S7) are carried through verbatim so the preview and the compiled
+  // gateway conditions derive from one resolved edge.
   const nodeFacts = deliveryNodeFacts(typed);
   const resolvedEdges: ResolvedDeliveryEdge[] = edges
     .map((edge) => {
       const { nodeId, fact } = resolveDeliveryFrom(edge.from, nodeFacts);
-      const resolved: ResolvedDeliveryEdge = { from: edge.from, to: edge.to, fromNode: nodeId };
-      return fact !== undefined ? { ...resolved, fromFact: fact } : resolved;
+      let resolved: ResolvedDeliveryEdge = { from: edge.from, to: edge.to, fromNode: nodeId };
+      if (fact !== undefined) resolved = { ...resolved, fromFact: fact };
+      if (edge.when !== undefined) resolved = { ...resolved, when: edge.when };
+      if (edge.equals !== undefined) resolved = { ...resolved, equals: edge.equals };
+      if (edge.default === true) resolved = { ...resolved, default: true };
+      return resolved;
     })
     .sort(
       (a, b) =>
         byCodeUnit(a.to, b.to) ||
         byCodeUnit(a.fromNode, b.fromNode) ||
-        byCodeUnit(a.fromFact ?? "", b.fromFact ?? ""),
+        byCodeUnit(a.fromFact ?? "", b.fromFact ?? "") ||
+        byCodeUnit(a.when ?? "", b.when ?? "") ||
+        byCodeUnit(feelLiteral(a.equals), feelLiteral(b.equals)),
     );
 
   // Per-node producer/consumer adjacency (by node id), each sorted + de-duplicated for determinism.
@@ -268,25 +321,74 @@ export async function compileDeliveryGraph(
   for (const list of producersById.values()) list.sort(byCodeUnit);
   for (const list of consumersById.values()) list.sort(byCodeUnit);
 
+  // Exclusive-split topology (S7): a node with a GUARDED (`when`) out-edge is an exclusive split; a
+  // fan-in that re-converges a split's branches is an exclusive merge. Derived from the ONE shared
+  // `analyzeExclusiveTopology` the validator also uses, so gateway-type selection never drifts from the
+  // parity the validator enforced. A lone `default: true` edge (no guarded sibling) always fires and is
+  // NOT a split; and a node whose guarded + `default` edges all converge on ONE downstream target has
+  // no real fan-out either — mirror the validator: key off a guarded `when` fanning to >=2 DISTINCT
+  // downstream targets only.
+  const splitNodes = new Set<string>();
+  const guardedNodes = new Set<string>();
+  const branchTargetsByNode = new Map<string, Set<string>>();
+  for (const edge of resolvedEdges) {
+    const guarded = edge.when !== undefined && edge.default !== true;
+    if (!guarded && edge.default !== true) continue;
+    if (guarded) guardedNodes.add(edge.fromNode);
+    const targets = branchTargetsByNode.get(edge.fromNode) ?? new Set<string>();
+    targets.add(edge.to);
+    branchTargetsByNode.set(edge.fromNode, targets);
+  }
+  for (const node of guardedNodes) {
+    if ((branchTargetsByNode.get(node)?.size ?? 0) > 1) splitNodes.add(node);
+  }
+  const forwardAdj = new Map<string, string[]>();
+  for (const node of nodes) forwardAdj.set(node.id, [...(consumersById.get(node.id) ?? [])]);
+  const topology = analyzeExclusiveTopology(
+    nodes.map((n) => n.id),
+    forwardAdj,
+    splitNodes,
+  );
+
   // Assign the deterministic BPMN element id per node (`n0`, `n1`, … in sorted order) plus the
-  // fork/join gateway ids (`gwf<i>` / `gwj<i>`) any fan-out/fan-in node needs.
+  // fork/join gateway ids any fan-out/fan-in node needs: a PARALLEL fork/join is `gwf<i>`/`gwj<i>`; an
+  // EXCLUSIVE split/merge (S7) is `gwx<i>`/`gwm<i>`. Each id space has its own positional counter so the
+  // scheme stays deterministic and non-colliding.
   const elementById = new Map<string, string>();
   const wirings: NodeWiring[] = [];
   const wiringById = new Map<string, NodeWiring>();
   let forkSeq = 0;
   let joinSeq = 0;
+  let splitSeq = 0;
+  let mergeSeq = 0;
   nodes.forEach((node, i) => {
     const element = `n${i}`;
     elementById.set(node.id, element);
     const consumers = consumersById.get(node.id) ?? [];
     const producers = producersById.get(node.id) ?? [];
-    const forkGateway = consumers.length > 1 ? `gwf${forkSeq++}` : undefined;
-    const joinGateway = producers.length > 1 ? `gwj${joinSeq++}` : undefined;
+    const forkExclusive = splitNodes.has(node.id);
+    // A fan-in is an EXCLUSIVE merge (first-token-proceeds) iff EVERY incoming branch is conditional —
+    // a split's own guarded/default out-edge, or a producer only conditionally reached. This is the
+    // SAME parity predicate the validator enforces (`edgeConditional`), so gateway-type selection never
+    // drifts from it. Deriving `joinExclusive` from `mergeNodes` alone over-fires: `analyzeExclusive
+    // Topology` marks every node reachable from >=2 branch targets as a merge, including nodes DOWNSTREAM
+    // of the real re-convergence — so a post-merge node that ALSO joins an independent always-firing
+    // producer would wrongly compile to an exclusive merge instead of the parallel AND-join both the
+    // validator and the semantics demand.
+    const joinExclusive =
+      producers.length > 1 &&
+      producers.every((p) => splitNodes.has(p) || topology.conditional.has(p));
+    const forkGateway =
+      consumers.length > 1 ? (forkExclusive ? `gwx${splitSeq++}` : `gwf${forkSeq++}`) : undefined;
+    const joinGateway =
+      producers.length > 1 ? (joinExclusive ? `gwm${mergeSeq++}` : `gwj${joinSeq++}`) : undefined;
     const wiring: NodeWiring = {
       node,
       element,
       forkGateway,
       joinGateway,
+      forkExclusive: forkGateway !== undefined && forkExclusive,
+      joinExclusive: joinGateway !== undefined && joinExclusive,
       entry: joinGateway ?? element,
       exit: forkGateway ?? element,
     };
@@ -297,7 +399,11 @@ export async function compileDeliveryGraph(
   const roots = nodes.filter((n) => (producersById.get(n.id) ?? []).length === 0);
   const leaves = nodes.filter((n) => (consumersById.get(n.id) ?? []).length === 0);
   const startForkGateway = roots.length > 1 ? "gwf_start" : undefined;
-  const endJoinGateway = leaves.length > 1 ? "gwj_end" : undefined;
+  // The End sink is an exclusive merge when its leaves are mutually-exclusive branch tails (only one
+  // fires per run); a parallel AND-join there would deadlock on the untaken branch. The validator has
+  // already rejected a leaf set that MIXES conditional and always-firing tails.
+  const endExclusive = leaves.length > 1 && leaves.some((n) => topology.conditional.has(n.id));
+  const endJoinGateway = leaves.length > 1 ? (endExclusive ? "gwm_end" : "gwj_end") : undefined;
 
   // ── Build the flow list in a DETERMINISTIC order, then assign `f0…` ids positionally ────────────
   const flows: Omit<Flow, "id">[] = [];
@@ -320,30 +426,58 @@ export async function compileDeliveryGraph(
   //    two fact-qualified edges between the same pair (e.g. `a.x -> b` and `a.y -> b`) would otherwise
   //    emit parallel flows between endpoints with no diverging gateway — invalid BPMN that schedules
   //    the consumer more than once. `resolvedEdges` is already sorted by (to, fromNode, fromFact), so
-  //    same-endpoint edges are contiguous and their fact labels accumulate in deterministic order.
-  const collapsedEdges: { fromNode: string; to: string; facts: string[] }[] = [];
+  //    same-endpoint edges are contiguous and their fact labels accumulate in deterministic order. For
+  //    a guarded split (S7) the collapsed flow carries the OR of its guard conditions (or is the split
+  //    default); the producer's exit is its exclusive gateway.
+  const collapsedEdges: { fromNode: string; to: string; facts: string[]; conditions: string[]; isDefault: boolean }[] =
+    [];
   for (const edge of resolvedEdges) {
     const last = collapsedEdges[collapsedEdges.length - 1];
+    const guardPart = guardConditionPart(edge, elementById, nodeFacts);
     if (last && last.fromNode === edge.fromNode && last.to === edge.to) {
       if (edge.fromFact !== undefined && !last.facts.includes(edge.fromFact)) last.facts.push(edge.fromFact);
+      if (edge.default === true) last.isDefault = true;
+      if (guardPart !== undefined && !last.conditions.includes(guardPart)) last.conditions.push(guardPart);
     } else {
-      collapsedEdges.push({ fromNode: edge.fromNode, to: edge.to, facts: edge.fromFact !== undefined ? [edge.fromFact] : [] });
+      collapsedEdges.push({
+        fromNode: edge.fromNode,
+        to: edge.to,
+        facts: edge.fromFact !== undefined ? [edge.fromFact] : [],
+        conditions: guardPart !== undefined ? [guardPart] : [],
+        isDefault: edge.default === true,
+      });
     }
   }
   for (const edge of collapsedEdges) {
     const producer = mustGet(wiringById, edge.fromNode);
     const consumer = mustGet(wiringById, edge.to);
-    const flow: Omit<Flow, "id"> = { source: producer.exit, target: consumer.entry };
-    flows.push(edge.facts.length > 0 ? { ...flow, name: edge.facts.join(", ") } : flow);
+    let flow: Omit<Flow, "id"> = { source: producer.exit, target: consumer.entry };
+    // A guard LABEL for the diagram/preview: the fact name(s), else the rendered condition / "default".
+    const label =
+      edge.facts.length > 0
+        ? edge.facts.join(", ")
+        : edge.isDefault
+          ? "default"
+          : edge.conditions.length > 0
+            ? edge.conditions.join(" or ")
+            : undefined;
+    if (label !== undefined) flow = { ...flow, name: label };
+    if (edge.isDefault) {
+      flow = { ...flow, isDefault: true };
+    } else if (edge.conditions.length > 0) {
+      flow = { ...flow, condition: `=${edge.conditions.join(" or ")}` };
+    }
+    flows.push(flow);
   }
   // 5. Leaf(s) → End.
   if (leaves.length === 1) {
     flows.push({ source: mustGet(wiringById, leaves[0].id).exit, target: "End" });
   } else if (leaves.length > 1) {
+    const endGateway = endExclusive ? "gwm_end" : "gwj_end";
     for (const leaf of leaves) {
-      flows.push({ source: mustGet(wiringById, leaf.id).exit, target: "gwj_end" });
+      flows.push({ source: mustGet(wiringById, leaf.id).exit, target: endGateway });
     }
-    flows.push({ source: "gwj_end", target: "End" });
+    flows.push({ source: endGateway, target: "End" });
   }
   const numberedFlows: Flow[] = flows.map((f, i) => ({ id: `f${i}`, ...f }));
 
@@ -532,6 +666,26 @@ function renderBpmn(
   const refs = (tag: string, ids: readonly string[]): string =>
     ids.map((id) => `      <bpmn:${tag}>${id}</bpmn:${tag}>`).join("\n");
 
+  // The default (else) flow id per exclusive-split gateway (S7) — the flow the gateway names in its
+  // `default` attribute so an unmatched runtime value takes the else-branch instead of erroring.
+  const defaultFlowBySource = new Map<string, string>();
+  for (const f of flows) if (f.isDefault) defaultFlowBySource.set(f.source, f.id);
+
+  // Render a diverging/converging gateway. `exclusive` picks `exclusiveGateway` (data-based XOR split /
+  // first-token merge, S7) over the parallel AND fork/join; a diverging exclusive gateway carries its
+  // `default` flow id when one exists.
+  const gateway = (id: string, exclusive: boolean, name: string): string[] => {
+    const tag = exclusive ? "exclusiveGateway" : "parallelGateway";
+    const def = defaultFlowBySource.get(id);
+    const defAttr = def !== undefined ? ` default="${def}"` : "";
+    return [
+      `    <bpmn:${tag} id="${id}"${defAttr} name="${escapeXml(name)}">`,
+      refs("incoming", incoming(id)),
+      refs("outgoing", outgoing(id)),
+      `    </bpmn:${tag}>`,
+    ];
+  };
+
   const lines: string[] = [];
   lines.push('<?xml version="1.0" encoding="UTF-8"?>');
   lines.push(
@@ -551,48 +705,52 @@ function renderBpmn(
   lines.push(refs("outgoing", outgoing("Start")));
   lines.push("    </bpmn:startEvent>");
 
-  // Start fork gateway (fan-out to multiple roots).
+  // Start fork gateway (fan-out to multiple roots) — always a PARALLEL fork: Start unconditionally
+  // activates every independent root.
   if (startForkGateway) {
-    lines.push(`    <bpmn:parallelGateway id="${startForkGateway}" name="fan out to roots">`);
-    lines.push(refs("incoming", incoming(startForkGateway)));
-    lines.push(refs("outgoing", outgoing(startForkGateway)));
-    lines.push("    </bpmn:parallelGateway>");
+    lines.push(...gateway(startForkGateway, false, "fan out to roots"));
   }
 
-  // Node elements (sorted), each preceded by its join gateway and followed by its fork gateway.
+  // Node elements (sorted), each preceded by its join gateway and followed by its fork gateway. An
+  // exclusive split's fork (S7) is an `exclusiveGateway` with guard conditions on its out-flows; an
+  // exclusive-merge's join is a first-token `exclusiveGateway`.
   for (const w of wirings) {
     if (w.joinGateway) {
-      lines.push(`    <bpmn:parallelGateway id="${w.joinGateway}" name="join into ${escapeXml(w.node.id)}">`);
-      lines.push(refs("incoming", incoming(w.joinGateway)));
-      lines.push(refs("outgoing", outgoing(w.joinGateway)));
-      lines.push("    </bpmn:parallelGateway>");
+      lines.push(...gateway(w.joinGateway, w.joinExclusive, `join into ${w.node.id}`));
     }
     lines.push(renderNodeElement(w, incoming(w.element), outgoing(w.element), boundInputsByElement.get(w.element) ?? []));
     if (w.forkGateway) {
-      lines.push(`    <bpmn:parallelGateway id="${w.forkGateway}" name="fan out of ${escapeXml(w.node.id)}">`);
-      lines.push(refs("incoming", incoming(w.forkGateway)));
-      lines.push(refs("outgoing", outgoing(w.forkGateway)));
-      lines.push("    </bpmn:parallelGateway>");
+      lines.push(...gateway(w.forkGateway, w.forkExclusive, `fan out of ${w.node.id}`));
     }
   }
 
-  // End join gateway (fan-in from multiple leaves) + end event.
+  // End join gateway (fan-in from multiple leaves) + end event. Exclusive when the leaves are
+  // mutually-exclusive branch tails (S7), else a parallel AND-join.
   if (endJoinGateway) {
-    lines.push(`    <bpmn:parallelGateway id="${endJoinGateway}" name="join leaves">`);
-    lines.push(refs("incoming", incoming(endJoinGateway)));
-    lines.push(refs("outgoing", outgoing(endJoinGateway)));
-    lines.push("    </bpmn:parallelGateway>");
+    lines.push(...gateway(endJoinGateway, endJoinGateway.startsWith("gwm"), "join leaves"));
   }
   lines.push('    <bpmn:endEvent id="End" name="Graph complete">');
   lines.push(refs("incoming", incoming("End")));
   lines.push("    </bpmn:endEvent>");
 
-  // Sequence flows.
+  // Sequence flows. A guarded flow (S7) carries a `<bpmn:conditionExpression>` FEEL child; the default
+  // flow is unconditional (the gateway names it). Condition text uses LITERAL double-quotes for FEEL
+  // string literals (the authored-BPMN convention, e.g. `=status = "converged"`) — text content is not
+  // subject to the attribute entity-decoding hazard, and the compiler grafts DI without re-serializing
+  // this XML, so the literal quotes survive to deploy.
   for (const f of flows) {
     const nameAttr = f.name !== undefined ? ` name="${escapeXml(f.name)}"` : "";
-    lines.push(
-      `    <bpmn:sequenceFlow id="${f.id}"${nameAttr} sourceRef="${f.source}" targetRef="${f.target}" />`,
-    );
+    if (f.condition !== undefined) {
+      lines.push(
+        `    <bpmn:sequenceFlow id="${f.id}"${nameAttr} sourceRef="${f.source}" targetRef="${f.target}">` +
+          `<bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">${escapeXmlText(f.condition)}</bpmn:conditionExpression>` +
+          "</bpmn:sequenceFlow>",
+      );
+    } else {
+      lines.push(
+        `    <bpmn:sequenceFlow id="${f.id}"${nameAttr} sourceRef="${f.source}" targetRef="${f.target}" />`,
+      );
+    }
   }
 
   lines.push("  </bpmn:process>");
@@ -926,8 +1084,19 @@ function renderMermaid(
   for (const edge of edges) {
     const from = mustGet(elementById, edge.fromNode);
     const to = mustGet(elementById, edge.to);
-    if (edge.fromFact !== undefined) {
-      lines.push(`  ${from} -- "${escapeMermaid(edge.fromFact)}" --> ${to}`);
+    // Label a guarded edge with its predicate (`fact == value`) and a default with `default` (S7), a
+    // fact-qualified edge with the fact name, else an unlabelled arrow.
+    let label: string | undefined;
+    if (edge.when !== undefined && edge.default !== true) {
+      const guardFact = edge.when.includes(".") ? edge.when.slice(edge.when.lastIndexOf(".") + 1) : edge.when;
+      label = `${guardFact} == ${feelLiteral(edge.equals)}`;
+    } else if (edge.default === true) {
+      label = "default";
+    } else if (edge.fromFact !== undefined) {
+      label = edge.fromFact;
+    }
+    if (label !== undefined) {
+      lines.push(`  ${from} -- "${escapeMermaid(label)}" --> ${to}`);
     } else {
       lines.push(`  ${from} --> ${to}`);
     }

package/app/deliveryGraphDeploy.test.ts

@@ -207,3 +207,151 @@ test("di coverage: every compiled flow node carries a BPMNShape and every sequen
 function escapeRe(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+// ── S7: guarded (conditional) routing DEPLOYS and ROUTES on the real engine (ADR 0005 S7) ──────────
+// The compiler tests prove a guarded split emits an exclusiveGateway with FEEL conditions; only a live
+// deploy proves the engine EVALUATES those conditions and takes exactly ONE branch. Here the `bump`
+// agent's emitted scalar (`result`) is published to a process var and the exclusive gateway routes on
+// it: the breaking outcome runs the `migrate` node, the green outcome skips straight to `release`, and
+// BOTH re-converge on the exclusive merge to a COMPLETED instance (a parallel merge would deadlock the
+// skipped branch). A guarded string fact needs a `default`, so green rides the else-flow.
+const GUARDED_ADOPT: DeliveryGraph = {
+  name: "adopt runbook",
+  nodes: [
+    { id: "bump", kind: "agent", agent: { jobType: "senior:bump" }, emits: [{ name: "result", type: "string" }] },
+    { id: "migrate", kind: "agent", agent: { jobType: "senior:migrate" } },
+    { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "rel-1" } },
+  ],
+  edges: [
+    { from: "bump", to: "migrate", when: "bump.result", equals: "breaking" },
+    { from: "bump", to: "release", default: true },
+    { from: "migrate", to: "release" },
+  ],
+};
+
+async function driveGuarded(outcome: "breaking" | "green"): Promise<{ state: string; migrateRan: boolean; releaseRan: boolean }> {
+  const engine = await createWasmEngineClient();
+  try {
+    let migrateRan = false;
+    let releaseRan = false;
+    // The split agent publishes its scalar outcome; the exclusive gateway routes on it.
+    await engine.registerWorker("senior:bump", async () => ({ result: outcome }));
+    await engine.registerWorker("senior:migrate", async () => {
+      migrateRan = true;
+      return {};
+    });
+    await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => {
+      releaseRan = true;
+      return {};
+    });
+
+    const run = await runDeliveryGraph(engine, GUARDED_ADOPT);
+    assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+    const key = run.handle.processInstanceKey;
+
+    let state = "?";
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+      await engine.drain();
+      const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+      assert(pi, `no process instance snapshot for ${key}`);
+      state = pi.state ?? "?";
+      if (state === "COMPLETED" || state === "TERMINATED") break;
+    }
+    return { state, migrateRan, releaseRan };
+  } finally {
+    await engine.close();
+  }
+}
+
+test("S7 deploy+route: the breaking guard branch runs `migrate` before re-converging on the exclusive merge to COMPLETED", async () => {
+  const r = await driveGuarded("breaking");
+  assertEquals(r.state, "COMPLETED", "the breaking branch must run to a COMPLETED instance");
+  assert(r.migrateRan, "the breaking outcome must route through the guarded `migrate` node");
+  assert(r.releaseRan, "both branches must re-converge on `release`");
+});
+
+test("S7 deploy+route: the green default branch SKIPS `migrate` and rides the else-flow straight to COMPLETED", async () => {
+  const r = await driveGuarded("green");
+  assertEquals(r.state, "COMPLETED", "the green branch must run to a COMPLETED instance");
+  assert(!r.migrateRan, "the green outcome must NOT route through `migrate` — it rides the default flow");
+  assert(r.releaseRan, "the green outcome still reaches `release` via the else-flow (proof the exclusive merge fires on one token)");
+});
+
+test("S7 deploy+route: mutually-exclusive leaves join End on an exclusive merge — the untaken leaf never blocks completion", async () => {
+  // Mode D: `adopt` routes a missing surface to an escalate (human) leaf, else to a `done` connector
+  // leaf. On the default path the escalate leaf never fires; an exclusive End merge must still let the
+  // instance COMPLETE (a parallel End join would wait forever on the untaken human leaf).
+  const graph: DeliveryGraph = {
+    name: "surface check",
+    nodes: [
+      { id: "adopt", kind: "agent", agent: { jobType: "senior:adopt" }, emits: [{ name: "surface", type: "string" }] },
+      { id: "escalate", kind: "human", human: { prompt: "file the upstream issue" } },
+      { id: "done", kind: "connector", connector: { target: "npm:install", dedupeKey: "done-1" } },
+    ],
+    edges: [
+      { from: "adopt", to: "escalate", when: "adopt.surface", equals: "missing" },
+      { from: "adopt", to: "done", default: true },
+    ],
+  };
+
+  // Default path (surface present): the human leaf is skipped and the instance COMPLETES on its own.
+  {
+    const engine = await createWasmEngineClient();
+    try {
+      let doneRan = false;
+      await engine.registerWorker("senior:adopt", async () => ({ surface: "present" }));
+      await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => {
+        doneRan = true;
+        return {};
+      });
+      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H" });
+      assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+      const key = run.handle.processInstanceKey;
+      let state = "?";
+      for (let round = 0; round < MAX_ROUNDS; round++) {
+        await engine.drain();
+        const [pi] = await engine.searchProcessInstances({ processInstanceKeys: [key] });
+        state = pi?.state ?? "?";
+        if (state === "COMPLETED" || state === "TERMINATED") break;
+        const open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+        assertEquals(open.length, 0, "the default path must never surface the escalate human leaf");
+      }
+      assertEquals(state, "COMPLETED", "the default (present) path completes without the human leaf");
+      assert(doneRan, "the default path routes to the `done` connector leaf");
+    } finally {
+      await engine.close();
+    }
+  }
+
+  // Guarded path (surface missing): the human leaf parks; `done` never runs.
+  {
+    const engine = await createWasmEngineClient();
+    try {
+      let doneRan = false;
+      await engine.registerWorker("senior:adopt", async () => ({ surface: "missing" }));
+      await engine.registerWorker(DELIVERY_CONNECTOR_TASK_TYPE, async () => {
+        doneRan = true;
+        return {};
+      });
+      const run = await runDeliveryGraph(engine, graph, { escalationSlaTimeout: "PT1H" });
+      assert(run.ok, `runDeliveryGraph failed: ${JSON.stringify(run)}`);
+      const key = run.handle.processInstanceKey;
+      let parked = "";
+      for (let round = 0; round < MAX_ROUNDS; round++) {
+        await engine.drain();
+        const open = await engine.searchUserTasks({ processInstanceKey: key, state: "CREATED" });
+        if (open.length > 0) {
+          parked = open[0].elementId ?? "";
+          break;
+        }
+      }
+      assert(
+        parked.startsWith("delivery-human-task__") && !parked.endsWith("__esc"),
+        `the missing outcome must park on the escalate human leaf, saw ${JSON.stringify(parked)}`,
+      );
+      assert(!doneRan, "the guarded (missing) path must NOT run the `done` leaf");
+    } finally {
+      await engine.close();
+    }
+  }
+});

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -225,6 +225,31 @@ resume cannot double-fire.
 - **Non-npm emit facts** (OCI/github-release) and behavioural edges beyond the `command` escape hatch —
   added when a real case lands.
 
+> **Amendment (issue #492): conditional (guarded) edges landed (S7).** The "behavioural edges" deferral
+> above is **partially lifted**: an edge may now carry an optional guard — `when: "<node>.<fact>"` +
+> `equals: <scalar>` — or be the split's single `default: true` else-branch. A node whose out-edges
+> carry guards is an **exclusive** (data-based) split instead of the default parallel fan-out; its guarded branches compile to a BPMN `exclusiveGateway` (`gwx<i>`) with one FEEL
+> `conditionExpression` per guarded flow (`=<producerElement>_<fact> = <literal>`) and a named default
+> flow, and where those branches re-converge they merge on an **exclusive** gateway (`gwm<i>`,
+> first-token-proceeds) rather than the parallel AND-join that would deadlock the untaken branch. The
+> validator enforces the guard's shape and closes the deadlock/ambiguity classes: a guard must
+> reference a **scalar** fact **declared by the edge's own producer** (`bad-when`), carry an `equals`
+> whose type matches the fact (`guard-missing-equals` / `guard-type-mismatch`), never combine `when`
+> with `default` (`guard-default-conflict`); a split must not **mix** guarded and plain out-edges
+> (`mixed-fan-out`) nor declare **two** defaults (`multiple-defaults`), must be **exhaustive** — a
+> `default`, unless a single boolean fact is guarded on both `true` and `false` (`non-exhaustive-split`)
+> — and a plain (parallel) AND-join may not be fed by an exclusive-split branch (`exclusive-merge-parity`),
+> including the implicit **End sink**: the terminal nodes may not mix a conditional (exclusive-split)
+> tail with an always-firing one, which would deadlock the End join or double-fire its exclusive merge.
+> The exclusive-split topology (both the validator's parity analysis and the compiler's gateway
+> selection) is derived from the **guarded (`when`) edges fanning out to \>=2 distinct downstream
+> targets only** — a lone `default: true` edge with no guarded sibling always fires, and a node whose
+> guarded + `default` edges all converge on **one** downstream target has no real fan-out, so in
+> either case its producer is **not** a split and must not mark downstream nodes/leaves conditional;
+> the per-node mixing/exhaustiveness checks still apply to any `default`.
+> Determinism is preserved: gateway ids are positional over id-sorted nodes, so a graph with no guards
+> compiles byte-for-byte as before.
+
 ## Open questions
 
 - **Compiler target for the first cut** — confirm compile-to-native (diagram + native scheduling) vs a

package/openapi.yaml

@@ -1502,7 +1502,9 @@ components:
         `from` is either a bare `<nodeId>` (wait for the upstream node's completion fact) or a
         qualified `<nodeId>.<fact>` referencing a declared `emits` fact of that node. Both endpoints
         must resolve to a node in the graph, the referenced fact must be declared, and the whole edge
-        set must be a DAG — all enforced by `validateDeliveryGraph`.
+        set must be a DAG — all enforced by `validateDeliveryGraph`. An OPTIONAL `when`/`equals` guard
+        (or a `default` else-branch) makes the edge CONDITIONAL, turning its producer into an
+        exclusive split (ADR 0005 S7) — a node's out-edges are then ALL guarded or ALL unconditional.
       type: object
       additionalProperties: false
       required:
@@ -1517,6 +1519,33 @@ components:
           type: string
           minLength: 1
           description: The dependent node's id — proceeds once `from` is observed.
+        when:
+          type: string
+          minLength: 1
+          description: >-
+            OPTIONAL guard reference `<nodeId>.<fact>` naming a SCALAR emitted fact (`string`,
+            `number`, or `boolean`) of the `from`-adjacent producer (ADR 0005 S7). Its presence makes
+            this a GUARDED edge and turns the producer into an exclusive-split point: the edge is taken
+            only when that runtime fact `equals` the literal below. Equality-only — no arbitrary
+            expressions (the trust boundary). Mutually exclusive with `default`.
+        equals:
+          description: >-
+            The literal value `when`'s fact must equal for this guarded edge to be taken (ADR 0005 S7).
+            REQUIRED iff `when` is present, and its JSON type must match the referenced fact's declared
+            type (`string`/`number`/`boolean`).
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+        default:
+          type: boolean
+          enum: [true]
+          description: >-
+            OPTIONAL — marks this edge as the ELSE branch of the exclusive split (taken when no guarded
+            edge matches at runtime). A FLAG: only `true` is meaningful, so it is constrained to `true`
+            (omit the field entirely for a non-default edge — `default: false` is not a valid wire
+            value). At most one `default` edge per split node. Mutually exclusive with `when`/`equals`
+            (ADR 0005 S7).
     DeliveryCompileError:
       description: >-
         One semantic-validation or compile failure, path-qualified at the offending input
@@ -1749,6 +1778,19 @@ components:
         fromFact:
           type: string
           description: The referenced emitted fact, when the edge `from` was qualified.
+        when:
+          type: string
+          description: The guard reference (`<nodeId>.<fact>`) verbatim, present only on a guarded edge (ADR 0005 S7).
+        equals:
+          description: The literal the guard fact must equal, present only on a guarded edge (ADR 0005 S7).
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+        default:
+          type: boolean
+          enum: [true]
+          description: True when this is the exclusive split's default (else) branch; a FLAG, only ever `true` and omitted otherwise (ADR 0005 S7).
     ResolvedDeliveryGraph:
       description: >-
         The normalised graph the compiler resolved from the input (ADR 0005 slice S1) — nodes and