Skip to content

Releases

v0.5.0

Choose a tag to compare

@valence-works-codex valence-works-codex released this 25 Oct 04:56
021d2c5

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

Choose a tag to compare

@sfmskywalker sfmskywalker released this 21 Oct 20:06
d631ff7

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 IBpmnConditionEvaluator on BpmnHostSnapshot.Conditions, gated by the new BpmnHostCapabilities.ConditionEvaluation (not in Full). Each answer is recorded as a ConditionEvaluated diagnostic.
  • 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 on BpmnWorkCompletedRequest.ErrorCode with a call activity's Faulted outcome. The code survives on BpmnContinuation.Fault.ErrorCode when nothing catches it.
    • Error end events throw. An uncaught throw faults the scope with bpmn.error.thrown.
    • New diagnostics: ErrorThrown and ErrorCaught.
  • Condition expressions in the model (#68). BpmnSequenceFlow.ConditionExpression (BpmnConditionExpression) and the document's ExpressionLanguage are modeled and round-trip.
  • Error codes in interchange (#70). An errorRef resolves to the referenced <error>'s errorCode, or to its id when it has none. Error end events and errorRefs survive a round trip.
  • Concurrent work disambiguation (#60, ADR 0010). Hosts can echo StartWork.TokenId as WorkTokenId, 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.Build refuses 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 with bpmn.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 Failed answer 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 default reference is no longer also taken as an unconditional flow.
  • Errors (#72):
    • Coded catchers no longer catch uncoded or differently coded faults.
    • DispatchFailed and Cancelled reach 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 ConditionEvaluated diagnostic.
  • 1.5.0 adds the ErrorThrown and ErrorCaught diagnostics.

Older payloads read as before. A strict validator (additionalProperties: false) needs the regenerated schema.

Includes

All 0.3.1 fixes (#41, #44, #45).

v0.3.1

Choose a tag to compare

@elsa-control-code-review elsa-control-code-review released this 16 Oct 03:00
f98931d

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 stoppedHandle field. 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:type values now resolve correctly, including a prefixed bpmn:tFormalExpression, and the xsi prefix 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

Choose a tag to compare

@sfmskywalker sfmskywalker released this 14 Oct 18:18
bcf722e

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 StartWork answered Defer and 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 threw Unable to resolve the BPMN token for hosts that don't hand correlation back.
    • The interpreter now withdraws that evaluation's StartWork commands, along with their work records, and answers Complete or Fault straight away. Work activated and ended in the same instant is never started, and every other command keeps its order.
    • A terminate now also issues CancelWorkSubtree for 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 new BpmnInterpreter.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.

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 Fault continuation may carry a SignalEnclosingScope raised earlier in the same evaluation, and nothing else.
  • A caught error whose own path then faults now reports Propagated together with the Fault. Before, it reported Caught with a Defer.
  • 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

Choose a tag to compare

@sfmskywalker sfmskywalker released this 20 Aug 22:17
b9f1411

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, which BuildLiveWorkHandles collapses 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

Choose a tag to compare

@sfmskywalker sfmskywalker released this 09 Aug 02:00
222eb51

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

Choose a tag to compare

@sfmskywalker sfmskywalker released this 09 Aug 01:23
4130abd

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. Analyze and Read share one code path, so a dry run cannot disagree with the real one.
  • Constructible in code via BpmnProcessBuilder and BpmnDefinitionsBuilder, 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.