Repository navigation
Releases
v0.5.0
Four packages released together for .NET 8 and .NET 10: Bpmn.Model, Bpmn.Interchange, Bpmn.Semantics and Bpmn.Runtime.InMemory. No shipped external NuGet dependencies.
Read the 0.4.0 → 0.5.0 migration notes before upgrading. The payload format is now 1.10.0 (previous stable 1.5.0); package and payload versions are separate. Upgrade all four packages, payload readers and host callbacks together.
This cut includes callback token identities, producing-handle provenance, refused host values, computed HasValue omission with legacy reads, cancellation pruning/history guidance, optional host availability assessment, Call Activity escalation boundaries, structured refusal element IDs, timer binding forms, and QName-value namespace provenance with safe same-element export aliases.
Qualification: 1,271 source tests on the reviewed head and resulting main, four samples, architecture/host-neutrality checks, schema byte comparison, old-writer negative control, four packages plus four symbol archives, and independent package-backed compile/execution on both .NET 8 and .NET 10. Exact qualified source: 021d2c5bba494f17d346144d97763cd3b2a13a4b; reviewed preparation: PR #99. The release evidence issue records publication and actual artifact verification separately.
Known limits remain explicit in the notes: unique never-reused host handles, uncapped unresolved stopped markers, degraded counted timer-cycle positions, lexical QName recognition/explicit collision refusals, and the existing SourceLink build-tool warning (#49). The in-memory reference host is not durable/distributed host qualification. Foundation adoption and production acceptance remain separate. PR #91 is not included in this cut.
Retain tested definition/state/work-ledger backups. Older readers can reject new discriminators; do not blindly downgrade persisted data. Publication across four packages is not atomic and published versions cannot be overwritten.
v0.4.0
Minor release from main (d631ff7). Released on Sipke's instruction. 0.4.0 contains breaking changes in graph building and routing; read Breaking changes before upgrading a host.
New
- Host-evaluated conditions (#71, ADR 0011). Hosts answer expression-only sequence-flow conditions through
IBpmnConditionEvaluatoronBpmnHostSnapshot.Conditions, gated by the newBpmnHostCapabilities.ConditionEvaluation(not inFull). Each answer is recorded as aConditionEvaluateddiagnostic. - Coded BPMN errors (#72, ADR 0012).
- Error catchers match by code: an exact match wins over the catch-all.
- Hosts name the error on
BpmnWorkFaultedRequest.ErrorCode, or onBpmnWorkCompletedRequest.ErrorCodewith a call activity's Faulted outcome. The code survives onBpmnContinuation.Fault.ErrorCodewhen nothing catches it. - Error end events throw. An uncaught throw faults the scope with
bpmn.error.thrown. - New diagnostics:
ErrorThrownandErrorCaught.
- Condition expressions in the model (#68).
BpmnSequenceFlow.ConditionExpression(BpmnConditionExpression) and the document'sExpressionLanguageare modeled and round-trip. - Error codes in interchange (#70). An
errorRefresolves to the referenced<error>'serrorCode, or to its id when it has none. Error end events anderrorRefs survive a round trip. - Concurrent work disambiguation (#60, ADR 0010). Hosts can echo
StartWork.TokenIdasWorkTokenId, so concurrent work that shares one binding is told apart. Additive: hosts that send no ID keep working wherever the slot is unambiguous. - Error routing on the common evaluation (#48): a public error disposition and transcript.
- Public escalation payload contract (#43).
- Work-binding JSON and schema contracts (#51).
- Single-process XML writer overload (#50).
- Timer-start schedule choices validated at graph build (#57).
Breaking changes
- Cycles (#39).
BpmnGraph.Buildrefuses a cycle on which nothing can hold a token, which previously hung the host. An evaluation that dispatches 10,000 tokens without coming to rest faults withbpmn.propagation.limit. - Faulted units (#42). A faulted unit is found by its binding and iteration, never by the enclosing scope's token.
- Conditions (#71):
- An exclusive gateway's unconditional flow counts as true, in declaration order.
- An element that takes no flow on arrival faults with
bpmn.flow.none-taken, including an unbound task. The exception is an escalation throw caught by an interrupting event subprocess of its own scope. - A
Failedanswer from the evaluator faults the scope. - An expression on a flow out of a start event, a parallel gateway or an event-based gateway is refused at graph build.
- The reader no longer reports expression conditions as
Degraded. - A default flow marked only by the element's
defaultreference is no longer also taken as an unconditional flow.
- Errors (#72):
- Coded catchers no longer catch uncoded or differently coded faults.
DispatchFailedandCancelledreach only catch-alls.- The reference host reports a called process's fault as a Faulted completion.
- The code-less error lookups are obsolete and return only the catch-all.
Payload format
The format goes from 1.1.0 (0.3.1) to 1.5.0:
- 1.2.0 adds the binding root union.
- 1.3.0 adds optional condition-expression properties.
- 1.4.0 adds the
ConditionEvaluateddiagnostic. - 1.5.0 adds the
ErrorThrownandErrorCaughtdiagnostics.
Older payloads read as before. A strict validator (additionalProperties: false) needs the regenerated schema.
Includes
v0.3.1
Patch release from release/0.3.x (v0.3.0 plus backports). The breaking changes on main (#39, #42) aren't included; they ship in 0.4.0.
Fixes
- Stopped-work handles (#33, via #41): the persisted payload format goes from 1.0.0 to 1.1.0. The change is additive: a new optional
stoppedHandlefield. If you run a strict validator (additionalProperties: false) against 1.0.0, it will reject 1.1.0 payloads until you update it. New host contract invariant 8: never reuse a handle within a scope. - Multi-instance marker (#21, via #44): the multi-instance marker is no longer duplicated on round-trip.
- conditionExpression (#30, via #45): fixes edge cases in reading and writing sequence-flow condition expressions. Prefixed
xsi:typevalues now resolve correctly, including a prefixedbpmn:tFormalExpression, and thexsiprefix mapping is handled on write.
Known limitation
- A multi-instance sibling on the fault path can be resolved incorrectly (see host-port.md). This is fixed only in 0.4.0.
v0.3.0: terminate and fault end a scope at once
A terminated or faulted scope now ends at once. Before this release, a terminate end event or a behavior fault reached in the same evaluation that had already started work could leave the process running forever.
Fixed
- #26: a terminate or a behavior fault in an evaluation that had already issued
StartWorkansweredDeferand parked the verdict on the state until the next work completion. If the work started in that evaluation waited on something that never came, such as a message, the process never ended. If it did complete, the parked path threwUnable to resolve the BPMN tokenfor hosts that don't hand correlation back.- The interpreter now withdraws that evaluation's
StartWorkcommands, along with their work records, and answersCompleteorFaultstraight away. Work activated and ended in the same instant is never started, and every other command keeps its order. - A terminate now also issues
CancelWorkSubtreefor every unit the host still reports live. Before, it stopped work only logically, and a host that doesn't cancel a completed scope's children itself left that work running. A unit already torn down in the same evaluation for a more specific reason keeps that reason; the rest get the newBpmnInterpreter.TerminateStopReason,bpmn.terminate.stopped-live-work. - A scope that has ended ignores later completions, faults and signals. It forwards no escalation to its parent and starts nothing.
- The interpreter now withdraws that evaluation's
Breaking changes
A terminate end event now requires the SubtreeCancellation host capability. A definition containing one is refused when the graph is built if the host doesn't declare it, the same rule 0.2.0 introduced for cancel end events.
Hosts should treat CancelWorkSubtree as idempotent. After a terminate, every later callback answers Complete again and repeats the teardowns still outstanding. A handle that is unknown or already torn down should be a no-op.
Behavior changes worth knowing
- A fault still carries no teardown, because a fault is a verdict, not a command (ADR 0003). A
Faultcontinuation may carry aSignalEnclosingScoperaised earlier in the same evaluation, and nothing else. - A caught error whose own path then faults now reports
Propagatedtogether with theFault. Before, it reportedCaughtwith aDefer. - States persisted by 0.2.0 with a parked terminate or fault still resolve on the next completion. The payload format is unchanged at 1.0.0.
Install
dotnet add package Bpmn.Semantics --version 0.3.0
dotnet add package Bpmn.Runtime.InMemory --version 0.3.0
Deterministic builds with SourceLink and .snupkg symbols. No dependencies beyond the base class library and each other.
v0.2.0 — the interpreter half goes stable
Bpmn.Semantics and Bpmn.Runtime.InMemory reach nuget.org for the first time. All four packages now ship together from one base version, so matching versions across the set is always correct.
Why now
The interpreter half was held back through all of 0.1.x. Not because it was unfinished — because a host port has no evidence behind it until somebody other than its author implements it, and publishing an unvalidated port turns every fix to it into a breaking change against a public surface.
A second host has now implemented it, and produced better evidence than "it compiled": it found two real defects in the port, both fixed here with coverage.
Fixed
- #13 — a cancelled transaction abandoned live work without issuing
CancelWorkSubtree, then restarted a compensation handler on the same(BindingRef, IterationId)slot the host was still holding. Two live units for one slot, whichBuildLiveWorkHandlescollapses last-wins, so a later teardown could cancel the wrong execution. The host could not defend: its ledger has exactly two inputs and both are interpreter commands. - #15 — the same shape on the own-scope escalation activation, found by looking where #13 pointed. Work abandoned by an interrupting activation is now torn down rather than held by the host for the rest of the scope's life.
Both were structural rather than one-line: teardowns discovered inside the token propagation loop could not travel on the evaluation result, because the loop keeps only each step's state. They now ride the evaluation context and drain under the same never-on-a-fault rule.
Transaction cancellation and compensation went from no test coverage at all to a dedicated suite.
Breaking changes
The payload format is frozen at 1.0.0, and state persisted by 0.1.x no longer deserializes. 53 property names were normalized to camelCase before the format was frozen, and every serialized property now declares its wire name explicitly. The cost of normalizing was bounded while the library was pre-1.0 with no published schema behind it, and unbounded once consumers generate types from a 1.0 contract. Nothing had shipped against a published schema, so there is nothing to migrate. The schema is published as a build artifact in Bpmn.Model under schema/, and BpmnPayloadFormat.Version is deliberately separate from the package version.
A cancel end event now requires the SubtreeCancellation host capability, and a definition containing one is refused at graph-build time without it. It issues CancelWorkSubtree as of #13, so it has to declare it — capabilities are a claim, not a default.
A cancelled transaction's other live work now receives a real teardown instead of being left running. Hosts observe this: work that previously ran on after the transaction was abandoned is now cancelled.
Also
BpmnHostSnapshot's at-most-one-live-unit-per-slot rule is now stated as holding once a command batch has been applied in full, in order — not continuously. An interrupting path may emit the replacement StartWork ahead of the CancelWorkSubtree it supersedes, so apply commands in the order returned and key your ledger by handle, not by slot.
Install
dotnet add package Bpmn.Semantics --version 0.2.0
dotnet add package Bpmn.Runtime.InMemory --version 0.2.0
Deterministic builds with SourceLink and .snupkg symbols. No dependencies beyond the base class library and each other.
v0.1.1 — configurable vendor namespace
Adds VendorNamespace and VendorPrefix to BpmnImportOptions and BpmnExportOptions.
var result = new BpmnXmlReader().Read(xml, new BpmnImportOptions
{
VendorNamespace = "https://example.com/schemas/bpmn",
VendorPrefix = "ex"
});Why
The first external consumer had already shipped its own vendor namespace and could not use it, because ours was a compile-time constant. Working around that took a 94-line XML-rewriting bridge that reparsed and reserialized the document on both sides of every call, to rename four attributes and one element.
Defaults are unchanged and byte-identical to 0.1.0, pinned by a regression test rather than assumed.
The part worth reading
A vendor name is interpreted only in the configured namespace. The same local name in a different namespace is foreign, and is retained verbatim rather than reinterpreted. So:
- read under A, written under B — vendor content migrates to B
- read under B when the document was authored under A — A's content survives as retained extension data
The writer does not blanket-skip retained content in its own vendor namespace, which would have dropped a retained attribute the model does not carry. It skips only an exact collision — the same attribute already written on that element, or an extension element with the same qualified name and name key. Never written twice, never lost. Both directions are tested.
One boundary is genuine and now explicit: collection and itemVariable hang on multiInstanceLoopCharacteristics, which the reader always consumes, so under a different configuration there is nothing left to retain them from. That previously surfaced as a confusing complaint about a missing loopCardinality; it now reports a Degraded finding naming both namespaces.
Invalid namespaces and prefixes — empty, reserved (xml, xmlns), or not an NCName — are rejected with a message naming the option, rather than producing malformed XML.
Tests
329 passing, 18 new.
Unchanged
Bpmn.Semantics and Bpmn.Runtime.InMemory remain on the preview feed, pending a second host validating the interpreter's port.
v0.1.0 — the interchange half
First release. Bpmn.Model and Bpmn.Interchange only.
What you get
Read and write BPMN 2.0 XML over a typed, immutable object model, with no external dependencies on either package. Targets net8.0 and net10.0, MIT licensed.
dotnet add package Bpmn.Interchange- Content-lossless round-trip. Foreign
extensionElements—camunda:*,zeebe:*,flowable:*, anything the reader does not itself interpret — survive a read-modify-write cycle, as does BPMN DI layout including edge waypoints and label bounds. - Element-scoped diagnostics on an Info / Degraded / Dropped ladder.
AnalyzeandReadshare one code path, so a dry run cannot disagree with the real one. - Constructible in code via
BpmnProcessBuilderandBpmnDefinitionsBuilder, which validate as they go.
Verified against the standard
Run over the 21 OMG BPMN MIWG reference models — the corpus the Model Interchange Working Group built to expose interchange defects:
- all 21 parse
- zero lose an element or a flow across a round trip
- zero drift between generations — writing twice is byte-identical
- every emitted edge carries at least two waypoints, as BPMN DI requires
- hand-arranged layout comes back unchanged: every shape bound, waypoint list and label box preserved
- vendor content retained from 14 distinct namespaces across the corpus
Coverage is reported rather than asserted. A dropped finding is not automatically a defect — the corpus exercises the whole specification and this release implements a large subset. The current gaps are mainly data objects and data stores, which are not modeled.
Not in this release
Bpmn.Semantics (the token-semantics interpreter) and Bpmn.Runtime.InMemory (a reference host with a virtual clock) are on the preview feed and ship at 0.2.0.
They are held back deliberately. Writing the reference host against the interpreter's port surfaced eight defects in it, three of which are still open. Publishing that surface now would turn every fix into a breaking change rather than an edit to something unpublished. A second host validates the port first.
Why this exists
The .NET ecosystem had no maintained, license-clean BPMN library. A survey of 88 C# repositories and 50 NuGet packages found one full engine under GPL-3.0-or-later, one interchange library shipping as a closed-source binary that throws off Windows, vendor clients that move .bpmn files without parsing them, and no BPMN object model published at all.
Full comparison, including when to use something else, is in the README.