@nanobpm/nano-workforce 0.112.0 → 0.114.0

package/resources/processes/delivery-human.bpmn

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_nano_workforce_delivery_human" targetNamespace="http://nanobpm.io/nano-workforce">
+  <bpmn:process id="delivery-human" name="Delivery graph — human node (scheduled user task)" isExecutable="true">
+    <bpmn:startEvent id="Start" name="Human node scheduled">
+      <bpmn:outgoing>f_start</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:userTask id="delivery-human-task" name="Delivery: human step (now do X)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="delivery-human-generic" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" assignee="=if (is defined(escalationAssignee) and escalationAssignee != null and trim(string(escalationAssignee)) != &#34;&#34;) then escalationAssignee else null" />
+        <zeebe:ioMapping>
+          <zeebe:output source="=&#34;completed&#34;" target="humanOutcome" />
+          <zeebe:output source="=if (is defined(value)) then value else null" target="humanEmitValue" />
+          <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="humanEmitArtifact" />
+          <zeebe:output source="=if (is defined(note)) then note else null" target="humanNote" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_start</bpmn:incoming>
+      <bpmn:outgoing>f_done</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:boundaryEvent id="be_delivery_human_sla" name="SLA elapsed" attachedToRef="delivery-human-task">
+      <bpmn:outgoing>f_sla</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_delivery_human_sla">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=escalationSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:endEvent id="human-done" name="Human step done (fact emitted)">
+      <bpmn:incoming>f_done</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:endEvent id="human-escalated" name="Human step timed out (escalated)">
+      <bpmn:extensionElements>
+        <zeebe:ioMapping>
+          <zeebe:input source="=&#34;escalated&#34;" target="humanOutcome" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_sla</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="delivery-human-task" />
+    <bpmn:sequenceFlow id="f_done" sourceRef="delivery-human-task" targetRef="human-done" />
+    <bpmn:sequenceFlow id="f_sla" sourceRef="be_delivery_human_sla" targetRef="human-escalated" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_delivery-human">
+    <bpmndi:BPMNPlane id="BPMNPlane_delivery-human" bpmnElement="delivery-human">
+      <bpmndi:BPMNShape id="BPMNShape_Start" bpmnElement="Start">
+        <dc:Bounds x="80" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="60" y="143" width="76" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_delivery-human-task" bpmnElement="delivery-human-task">
+        <dc:Bounds x="216" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_human-done" bpmnElement="human-done">
+        <dc:Bounds x="416" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="396" y="143" width="76" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_human-escalated" bpmnElement="human-escalated">
+        <dc:Bounds x="416" y="262" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="394" y="303" width="81" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_be_delivery_human_sla" bpmnElement="be_delivery_human_sla">
+        <dc:Bounds x="248" y="142" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="164" y="183" width="84" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
+        <di:waypoint x="116" y="120" />
+        <di:waypoint x="216" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_done" bpmnElement="f_done">
+        <di:waypoint x="316" y="120" />
+        <di:waypoint x="416" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_sla" bpmnElement="f_sla">
+        <di:waypoint x="266" y="178" />
+        <di:waypoint x="266" y="280" />
+        <di:waypoint x="416" y="280" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>

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

@@ -50,11 +50,12 @@ test("every corpus model is either ported or has a documented blocker", () => {
     "convergence-loop",
     "merge-loop",
     "plan-fanout",
+    "delivery-human",
   ];
   assertEquals(
     PORTS.map((p) => p.model),
     expected,
-    "PORTS must cover all seven goldens in the epic's authoring order",
+    "PORTS must cover all eight goldens in the epic's authoring order",
   );
   for (const port of PORTS) {
     assert(
@@ -66,14 +67,21 @@ test("every corpus model is either ported or has a documented blocker", () => {
 
 // The blockers are not guesses — prove each against the goldens themselves.
 //
-// CLASS 1 — five goldens have MORE THAN ONE top-level start and/or end event,
+// CLASS 1 — six goldens have MORE THAN ONE top-level start and/or end event,
 // which the published `@nanobpm/workflow@0.12.0` compiler (a single
 // `<startEvent id="Start">` + single `<endEvent id="End">`) cannot derive.
 test("class-1 blocked goldens genuinely have multiple top-level start/end events", () => {
   const countTag = (xml: string, tag: string): number =>
     (xml.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
 
-  const multiStartEndBlocked = new Set(["spine-demo", "readiness-gate", "feature", "merge-loop", "plan-fanout"]);
+  const multiStartEndBlocked = new Set([
+    "spine-demo",
+    "readiness-gate",
+    "feature",
+    "merge-loop",
+    "plan-fanout",
+    "delivery-human",
+  ]);
   for (const model of multiStartEndBlocked) {
     const xml = readFileSync(goldenPath(model), "utf8");
     const starts = countTag(xml, "startEvent");

package/test/derivation-parity/flows.ts

@@ -9,13 +9,13 @@
 // the structurally-derivable goldens at full whole-model parity, park the rest
 // pending an upstream construct, and do NOT relax to node-surface parity):
 //
-//   • `retro` is a GREEN whole-model parity port (see below). The remaining six
+//   • `retro` is a GREEN whole-model parity port (see below). The remaining seven
 //     goldens are `blockedReason`-parked, in TWO distinct classes, each awaiting
 //     an upstream `@nanobpm/workflow` (nano-ide) construct + re-release — never a
 //     golden edit and never relaxed acceptance:
 //
 //     (1) MULTI top-level start/end (spine-demo, readiness-gate, feature,
-//         merge-loop, plan-fanout). `@nanobpm/workflow` derives EXACTLY
+//         merge-loop, plan-fanout, delivery-human). `@nanobpm/workflow` derives EXACTLY
 //         ONE `<bpmn:startEvent id="Start">` + ONE `<bpmn:endEvent id="End">`,
 //         converging every dangler into that single end (see `Compiler.compile`
 //         in the package's `declarative.ts`). Needs a terminal/explicit-end
@@ -146,7 +146,7 @@ const MULTI_START_END_BLOCK =
   "cannot reproduce. Awaits an upstream terminal/explicit-end (+ multi-start) " +
   "construct in @nanobpm/workflow (nano-ide).";
 
-/** All seven ports, keyed by model, in the epic's stated authoring order. */
+/** All ports, keyed by model, in the epic's stated authoring order. */
 export const PORTS: readonly PortEntry[] = [
   { model: "retro", flow: retroFlow },
   {
@@ -183,4 +183,8 @@ export const PORTS: readonly PortEntry[] = [
     model: "plan-fanout",
     blockedReason: `${MULTI_START_END_BLOCK} (plan-fanout: 3 starts, 3 ends)`,
   },
+  {
+    model: "delivery-human",
+    blockedReason: `${MULTI_START_END_BLOCK} (delivery-human: 1 start, 2 ends)`,
+  },
 ];

package/workers/delivery-connector/worker.test.ts

@@ -0,0 +1,44 @@
+// Unit coverage for the pr.delivery-connector worker's input validation (workers/delivery-connector/worker.ts).
+// Job variables are UNTYPED at runtime, so the worker must not forward a misconfigured node's garbage
+// into the (side-effecting) connector I/O surface: a blank `target` fails CLOSED, and a wrong-shaped
+// `payload`/`boundFacts` is coerced to null with a surfaced warning rather than passed through.
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { readConnectorInput } from "./worker.ts";
+
+test("readConnectorInput: a blank/missing target fails closed (a connector with no destination is meaningless)", () => {
+  for (const target of [undefined, "", "   "]) {
+    assertThrows(() => readConnectorInput({ target }), Error, "target");
+  }
+});
+
+test("readConnectorInput: a valid target is trimmed and passed through; well-shaped payload/boundFacts survive", () => {
+  const facts = [{ from: "n1", name: "mergedSha", value: "abc" }];
+  const r = readConnectorInput({ target: "  slack  ", payload: { channel: "#rel" }, boundFacts: facts });
+  assertEquals(r.target, "slack");
+  assertEquals(r.payload, { channel: "#rel" });
+  assertEquals(r.boundFacts, facts);
+  assertEquals(r.warnings.length, 0);
+});
+
+test("readConnectorInput: absent payload/boundFacts default to null with no warning", () => {
+  const r = readConnectorInput({ target: "slack" });
+  assertEquals(r.payload, null);
+  assertEquals(r.boundFacts, null);
+  assertEquals(r.warnings.length, 0);
+});
+
+test("readConnectorInput: a non-object payload / non-array boundFacts is coerced to null and warned (never forwarded)", () => {
+  const r = readConnectorInput({ target: "slack", payload: "oops" as unknown as Record<string, unknown>, boundFacts: "nope" as unknown as [] });
+  assertEquals(r.payload, null, "a scalar payload never reaches the connector surface");
+  assertEquals(r.boundFacts, null, "a non-array boundFacts never reaches the connector surface");
+  assertEquals(r.warnings.length, 2, "both coercions are surfaced for logging (not silent)");
+  assert(r.warnings.some((w) => w.includes("payload")), "the payload coercion is named");
+  assert(r.warnings.some((w) => w.includes("boundFacts")), "the boundFacts coercion is named");
+});
+
+test("readConnectorInput: an array payload is rejected (arrays are not plain objects)", () => {
+  const r = readConnectorInput({ target: "slack", payload: [1, 2, 3] as unknown as Record<string, unknown> });
+  assertEquals(r.payload, null);
+  assertEquals(r.warnings.length, 1);
+});

package/workers/delivery-connector/worker.ts

@@ -0,0 +1,83 @@
+// pr.delivery-connector — the delivery-graph `connector` node's engine-native execution body (ADR 0005
+// slice S4). The service-task half of a compiled `connector` subProcess: it drives the forward-declared
+// connector I/O surface AT-MOST-ONCE per dedupe key, so the engine's at-least-once job delivery (a
+// worker/hub restart, a lost ack, a graph resume) can never double-fire the side effect (Decision 7).
+//
+// All the idempotency logic lives in `app/deliveryConnector.ts` (the durable-fence ledger + claim→act
+// envelope) so it is unit-testable without the engine and shares ONE implementation with any other
+// caller; this worker is the thin engine adapter that resolves the effective dedupe key from the job's
+// author-supplied `dedupeKey` or its stable engine identity (`processInstanceKey:elementId`).
+import type { AppJobHandler } from "@nanobpm/urban";
+import {
+  type BoundFact,
+  type ConnectorDispatchResult,
+  connectorDedupeKey,
+  dispatchConnector,
+} from "../../app/deliveryConnector.ts";
+
+// Typed off the compiled `connector` subProcess ioMapping (a RUNTIME-generated definition, so there is
+// no static data-envelope to derive from): `target`/`dedupeKey`/`payload` are seeded from the node's
+// config, `boundFacts` is the late-bound list of upstream producers' emitted facts.
+interface In extends Record<string, unknown> {
+  target?: string;
+  dedupeKey?: string | null;
+  payload?: Record<string, unknown> | null;
+  boundFacts?: BoundFact[] | null;
+}
+
+/** A plain (non-array, non-null) object — the only shape a connector `payload` may take. */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Validate + normalise the untyped job variables into the shape the connector surface accepts. Job
+ * variables are untyped at runtime, so a misconfigured node (or a hand-seeded instance) could hand us a
+ * blank `target`, a scalar `payload`, or a non-array `boundFacts`. Fail CLOSED on a blank `target` (a
+ * connector with no destination is meaningless and would write a junk ledger row); coerce a wrong-shaped
+ * `payload`/`boundFacts` to `null` (they are optional) and surface the coercion via `warnings` so the
+ * caller can log it rather than silently pass garbage into the I/O surface. */
+export function readConnectorInput(vars: In): {
+  target: string;
+  payload: Record<string, unknown> | null;
+  boundFacts: BoundFact[] | null;
+  warnings: string[];
+} {
+  const target = typeof vars.target === "string" ? vars.target.trim() : "";
+  if (!target) throw new Error("delivery-connector: 'target' is required (blank connector target)");
+  const warnings: string[] = [];
+  let payload: Record<string, unknown> | null = null;
+  if (vars.payload != null) {
+    if (isPlainObject(vars.payload)) payload = vars.payload;
+    else warnings.push("payload is not a plain object — coerced to null");
+  }
+  let boundFacts: BoundFact[] | null = null;
+  if (vars.boundFacts != null) {
+    if (Array.isArray(vars.boundFacts)) boundFacts = vars.boundFacts;
+    else warnings.push("boundFacts is not an array — coerced to null");
+  }
+  return { target, payload, boundFacts, warnings };
+}
+
+const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) => {
+  const { target, payload, boundFacts, warnings } = readConnectorInput(job.variables);
+  const dedupeKey = connectorDedupeKey({
+    dedupeKey: job.variables.dedupeKey ?? null,
+    processInstanceKey: job.processInstanceKey ?? null,
+    elementId: job.elementId ?? null,
+  });
+  if (!dedupeKey) {
+    // No author key AND no engine identity to derive one — un-dedupable. Fail closed rather than
+    // perform a side effect we could not make idempotent (never double-fire).
+    throw new Error("delivery-connector: no dedupe key (author-supplied or graph-derived) available");
+  }
+  for (const w of warnings) app.log.info("delivery-connector: input coerced", { target, dedupeKey, warning: w });
+  const result = await dispatchConnector(
+    app.data,
+    { dedupeKey, target, payload, boundFacts },
+    new Date().toISOString(),
+  );
+  app.log.info("delivery-connector", { target, dedupeKey, outcome: result.connectorOutcome });
+  return result;
+};
+
+export default handler;