@nanobpm/nano-workforce 0.130.0 → 0.131.1

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>");
@@ -665,6 +823,16 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
     case "human":
       inputs.push({ source: cfg("escalationSlaTimeout"), target: "escalationSlaTimeout" });
       inputs.push({ source: cfg("escalationAssignee"), target: "escalationAssignee" });
+      // Seed the authored instruction + node identity + emit context so the generic human form renders
+      // "now do X", names the parked node, and labels/hides its emit field (issue #499). `emits` is the
+      // single source of truth; the emit label/mode are derived from it in FEEL here (no duplicate seed).
+      inputs.push({ source: cfg("prompt"), target: "prompt" });
+      inputs.push({ source: cfg("nodeId"), target: "nodeId" });
+      inputs.push({ source: `=if count(${cfg("emits").slice(1)}) = 0 then "none" else "typed"`, target: "emitMode" });
+      inputs.push({
+        source: `=string join(for _e in ${cfg("emits").slice(1)} return _e.name + " (" + _e.type + ")", ", ")`,
+        target: "emitLabel",
+      });
       break;
     case "connector":
       inputs.push({ source: cfg("target"), target: "target" });
@@ -710,9 +878,9 @@ function innerBodyLines(w: NodeWiring): string[] {
   const node = w.node;
   switch (node.kind) {
     case "agent":
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), []);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], node.agent.jobType);
     case "connector":
-      return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, []);
+      return serviceBodyLines(el, node.id, `type="${DELEGATE_TASK_TYPE.connector}"`, [], `connector → ${node.connector.target}`);
     case "wait":
       return waitBodyLines(el, node.id);
     case "human":
@@ -724,8 +892,15 @@ function innerBodyLines(w: NodeWiring): string[] {
 
 /** `agent`/`connector` body: `start → serviceTask → end`, with a bounded `=nodeTimeout` boundary that
  * escalates the stalled node onto a human-completable user task. `taskDefAttr` is the pre-rendered
- * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines. */
-function serviceBodyLines(el: string, nodeId: string, taskDefAttr: string, taskProps: readonly string[]): string[] {
+ * `type="…"` attribute; `taskProps` are optional `<zeebe:property>` envelope lines; `descriptor`
+ * names the stalled work (job type / connector target) for the escalation task's context line (#499). */
+function serviceBodyLines(
+  el: string,
+  nodeId: string,
+  taskDefAttr: string,
+  taskProps: readonly string[],
+  descriptor: string,
+): string[] {
   const esc = escalationTaskElement(el);
   const taskExt =
     taskProps.length > 0
@@ -753,7 +928,18 @@ function serviceBodyLines(el: string, nodeId: string, taskDefAttr: string, taskP
     `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
     `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=nodeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
     "      </bpmn:boundaryEvent>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i2`], `${el}_i3`),
+    ...escalationTaskLines(
+      esc,
+      nodeId,
+      [`${el}_i2`],
+      `${el}_i3`,
+      escalationContextFeel(
+        nodeId,
+        descriptor,
+        "nodeTimeout",
+        "; in-flight work may already exist — check for a draft PR or partial state before retrying or reassigning.",
+      ),
+    ),
     `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i3</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_task`),
     flow(`${el}_i1`, `${el}_task`, `${el}_end`),
@@ -833,7 +1019,13 @@ function waitBodyLines(el: string, nodeId: string): string[] {
     `        <bpmn:outgoing>${el}_i7</bpmn:outgoing>`,
     `        <bpmn:outgoing>${el}_i4</bpmn:outgoing>`,
     "      </bpmn:exclusiveGateway>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i4`], `${el}_i5`),
+    ...escalationTaskLines(
+      esc,
+      nodeId,
+      [`${el}_i4`],
+      `${el}_i5`,
+      escalationContextFeel(nodeId, "readiness gate", "probeTimeout", " before its ReadinessProbe went green — decide how to proceed."),
+    ),
     `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming><bpmn:incoming>${el}_i7</bpmn:incoming></bpmn:endEvent>`,
     flow(`${el}_i0`, `${el}_start`, `${el}_probeLoop`),
     flow(`${el}_i1`, `${el}_probeLoop`, `${el}_end`),
@@ -889,14 +1081,29 @@ function humanBodyLines(el: string, nodeId: string): string[] {
 }
 
 /** A bounded node's escalation user task — a human-completable stop (`isDeliveryHumanElement`
- * convention) that a human OR an agent (ADR 0046) answers to unstick a stalled node. */
-function escalationTaskLines(esc: string, nodeId: string, incoming: readonly string[], outgoing: string): string[] {
+ * convention) that a human OR an agent (ADR 0046) answers to unstick a stalled node. `contextFeel` is
+ * a FEEL expression yielding the context line seeded onto the generic form's read-only prompt field
+ * (issue #499) — e.g. "Node n1 (senior:feature) exceeded its SLA (PT30M); …" — so the operator can see
+ * WHICH node timed out and that in-flight work may already exist, instead of a blank form. The emit
+ * field is labelled "none" so the generic form hides its (inert on an escalation) typed-value input. */
+function escalationTaskLines(
+  esc: string,
+  nodeId: string,
+  incoming: readonly string[],
+  outgoing: string,
+  contextFeel: string,
+): string[] {
   return [
     `      <bpmn:userTask id="${esc}" name="Escalate: ${escapeXml(nodeId)}">`,
     "        <bpmn:extensionElements>",
     `          <zeebe:formDefinition formId="${GENERIC_HUMAN_FORM}" />`,
     "          <zeebe:userTask />",
     '          <zeebe:assignmentDefinition candidateGroups="operators" />',
+    "          <zeebe:ioMapping>",
+    `            <zeebe:input ${attr("source", contextFeel)} target="prompt" />`,
+    `            <zeebe:input ${attr("source", `=${feelStr(nodeId)}`)} target="nodeId" />`,
+    `            <zeebe:input ${attr("source", '="none"')} target="emitMode" />`,
+    "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
     ...incoming.map((id) => `        <bpmn:incoming>${id}</bpmn:incoming>`),
     `        <bpmn:outgoing>${outgoing}</bpmn:outgoing>`,
@@ -904,6 +1111,15 @@ function escalationTaskLines(esc: string, nodeId: string, incoming: readonly str
   ];
 }
 
+/** Build the FEEL context line seeded onto an escalation task's read-only prompt field (issue #499).
+ * The node id + descriptor (job type / connector target / "readiness gate") are baked as compile-time
+ * literals; the elapsed SLA is read from the node body's runtime `timeoutVar` (`nodeTimeout` for a
+ * bounded service node, `probeTimeout` for a `wait` gate). `tail` closes the sentence per kind. */
+function escalationContextFeel(nodeId: string, descriptor: string, timeoutVar: string, tail: string): string {
+  const head = feelStr(`Node ${nodeId} (${descriptor}) exceeded its SLA (`);
+  return `=${head} + string(${timeoutVar}) + ${feelStr(`)${tail}`)}`;
+}
+
 /** A plain `<bpmn:sequenceFlow>` (6-space indented). */
 function flow(id: string, source: string, target: string): string {
   return `      <bpmn:sequenceFlow id="${id}" sourceRef="${source}" targetRef="${target}" />`;
@@ -926,8 +1142,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}`);
     }