feat: extract headless workflow engine

docs/BPMN_INTEROPERABILITY.md

@@ -0,0 +1,84 @@
+# Native BPMN Graph
+
+GovOPlaN uses BPMN 2.0 as Workflow's canonical graph language while keeping
+notation support distinct from executable runtime support.
+
+## Current Contract
+
+- The native Workflow graph stores BPMN element and flow types, process
+  membership, containment, geometry, properties, and preserved extension
+  content. There is one editor and one graph representation.
+- BPMN XML import maps standard elements and BPMN DI into the native graph.
+  Export deterministically renders XML and DI from the current graph. The
+  normalized XML artifact, its hash, and the native profile version are pinned
+  with every immutable revision.
+- No browser-side BPMN modeler is required. The WebUI uses the same graph
+  surface and shared controls as the rest of GovOPlaN.
+- `GET /api/v1/workflow/bpmn/profile` publishes all installed, versioned
+  conformance profiles.
+- `POST /api/v1/workflow/bpmn/inspect` safely parses bounded BPMN 2.0 XML,
+  inventories every BPMN model element, detects duplicate IDs and selected
+  dangling references, and classifies elements as interchange-only, natively
+  mappable, or natively executable.
+- `POST /api/v1/workflow/bpmn/compile` imports a bounded BPMN document into the
+  canonical native graph.
+- `POST /api/v1/workflow/bpmn/render` exports a native graph as normalized BPMN
+  XML with BPMN DI geometry.
+- `GET /api/v1/workflow/definitions/{id}/revisions/{revision}/bpmn` returns
+  the exact pinned document and its current availability/conformance
+  assessment.
+- XML entities, DTD-based expansion, oversized documents, and malformed roots
+  are rejected.
+
+Inspection is not XML Schema validation and does not claim that every editable
+BPMN construct can be executed. Notation and interchange remain available when
+the native runtime cannot activate the document.
+
+## Built-In Profiles
+
+- `govoplan.native.bpmn@1.0.0` is the canonical graph and interchange profile.
+  It maps the supported BPMN vocabulary into native nodes and edges. Activation
+  separately validates whether every execution semantic is implemented.
+- `govoplan.native.linear@1.0.0` and `bpmn.interchange@1.0.0` remain registered
+  for historical revision compatibility; new editor revisions use the native
+  BPMN profile.
+
+Gateways, subprocesses, event definitions, transactions, compensation,
+collaboration, and choreography remain editable and exportable even when their
+token or lifecycle semantics are not yet implemented.
+
+## Execution Boundary
+
+Adding a BPMN shape is not equivalent to implementing its token semantics,
+event subscriptions, compensation, transactions, choreography, or conformance
+behavior. Each executable mapping therefore needs:
+
+1. an explicit native semantic mapping;
+2. validation rules and lifecycle behavior;
+3. resumability and idempotency tests;
+4. migration and round-trip fixtures;
+5. a declared fallback when the installed runtime cannot execute it.
+
+Unsupported execution constructs remain visible in the native graph, but
+activation remains blocked until an execution adapter declares support.
+
+## Adapter Boundary
+
+Adapter packages register through the
+`govoplan.workflow.bpmn_adapters` Python entry-point group. Workflow discovers
+them without importing a concrete module. An adapter publishes a stable ID,
+version, runtime kind, conformance statement, supported elements and event
+definitions, operational requirements, validation, and canonical graph
+materialization.
+
+Revisions pin the exact adapter version. If that version is unavailable after
+an installation change, the document remains readable and exportable but
+cannot activate. External-engine adapters must still materialize lifecycle,
+handoff, retry, cancellation, and audit evidence through the canonical
+Workflow instance contract; a remote engine's private state is not the
+platform record.
+
+The conformance fixtures under `tests/fixtures/bpmn` cover processes,
+collaboration, choreography, events, transactions, compensation, and data
+elements. Every fixture must import and export through the native graph without
+losing modeled nodes or flows; activation has its own narrower test matrix.