fix(bpmn): keep subprocess bodies through the document PUT

[sfmskywalker]

Closes #8072. Part of #7909.

Problem

PUT bpmn/definitions/{id}/document wrote the posted BpmnDefinitions through BpmnXmlWriter.Write(document) with no bindings. In Bpmn.Interchange 0.2.0, the bodies of subprocesses, transactions and event subprocesses live only in the reader's NestedProcess bindings, so every PUT of a document declaring one emptied it. On a second PUT, an emptied event subprocess disappeared entirely.

Fix (option 2 from the issue)

The PUT now re-reads the stored Bpmn:SourceXml. For each subprocess-type element the posted document still declares, matched by element id, it writes that element's stored body and every stored binding inside that scope, recursively, under the posted element's bindingRef. The call is BpmnXmlWriter.Write(definitions, bindings).

• A subprocess the posted document removes, or retypes to something that is not a subprocess, stays gone. No stored body is brought back.
• Matching by element id means a new element that reuses an old bindingRef inherits nothing.
• Every binding in a kept scope is reused, not only NestedProcess. Otherwise a nested call activity's vw:waitForCompletion="false", which exists only on its CallProcess binding, would silently turn into a waiting call.
• A subprocess with a stored body but a null bindingRef is refused with the existing uncoded 400 path rather than emptied. Studio never produces this, because it echoes bindingRefs.

No contract change. The GET body, the ETag formula and the 428/412/404 and BpmnErrorResponse codes are unchanged, so the Studio client (elsa-workflows/elsa-studio#1031) works as is.

Why not option 1

BpmnWorkBinding has no JSON contract in the library: no property names, no polymorphism, and it is not in bpmn-payload.schema.json. Carrying nested bodies to the client would need an Elsa-owned DTO that restates the library's addressing. That gap is filed as #8076, blocked by valence-works/bpmn#22.

Library workaround

Bpmn.Interchange 0.2.0 also keeps an interpreted multiInstanceLoopCharacteristics inside the retained nested content (valence-works/bpmn#21). Handing stored bodies back unfiltered would add a copy on every PUT and let the stale copy override a client's changed or removed marker. The PUT drops the retained copy wherever the model carries the marker. It keeps the copy only when it is the sole record of a marker the reader degraded, for example a Camunda-authored one. The workaround is marked for removal.

Tests

• The D4 round-trip test from feat(bpmn): GET and PUT the BPMN document as library-format JSON #8060 is now a theory over five fixtures:
  • camunda-order-process;
  • subprocess-boundary-events and transaction-compensation, copied byte-identical from Studio's W9a fixtures;
  • two new files, nested-subprocesses and camunda-multi-instance-subprocess.
• DocumentPut_OfUnchangedContent_ReturnsTheETagTheGetReturned is a four-fixture theory.
• New cases:
  • a subprocess kept, removed or retyped;
  • a re-keyed bindingRef;
  • the null-bindingRef refusal;
  • a loop marker changed, removed or added.
• 15 service mutations, each turned the targeted tests red.
• Local runs:
  • Elsa.Bpmn.UnitTests: 30/30
  • Elsa.Bpmn.Interchange.UnitTests: 14/14, including the duplication guard
  • Elsa.Bpmn.IntegrationTests: 59/59
  • Elsa.Bpmn.Interchange.IntegrationTests: 99/99

Follow-ups filed

• BPMN W32: a subprocess nested in a same-id subprocess crashes the server on import #8074: a subprocess nested in a same-id subprocess crashes the server on import (stack overflow). Pre-existing.
• BPMN W33: the document PUT drops a top-level call activity's fire-and-forget flag #8075: a top-level call activity's fire-and-forget flag is lost on the document PUT. Pre-existing.
• BPMN W34: elements inside subprocesses cannot be edited through the document endpoints #8076: elements inside subprocesses are not editable through the document.
• BPMN W29: make the document PUT's precondition and save atomic #8064, already filed: the If-Match check and the stored-source reload are separate reads. Now documented in the remarks.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

Safe to merge: the document update flow preserves retained nested scope content and safely discards it when the corresponding scope is retyped.

What we checked:

• Exercised a real HTTP import, document read, conditional document update using the returned If-Match, and BPMN export requests, and all requests returned 200 OK.
• Validated endpoint status and reason phrase were captured in the command-output logs from the HTTP run.
• Confirmed the PR export retained every compared nested body element across event subprocess, transaction, and embedded subprocess cases, and retyping OnRecall to endEvent did not export a HandleRecall body.
• Security assessment concluded no issues were observed and noted the fixed behavior prevents silent workflow-structure data loss.

Summary

• BPMN document updates preserve embedded subprocess, transaction, and event-subprocess bodies when a document is read, written back, and exported.
• Removed or retyped subprocess elements do not retain their former nested body.
• The document update contract was exercised through HTTP import, document read, conditional update, and export requests. This change is safe to merge.

_{Reviews (1) · Last reviewed commit: "docs(bpmn): link the loop-marker workaro..."}