Workflow Engine And Workflow Editor Split

Decision

Split the current module into two installable modules:

govoplan-workflow-engine (runtime module ID workflow_engine) is the headless definition and execution platform available to all modules.
govoplan-workflow remains the optional authoring, inspection, catalogue, diff, override, and reset WebUI.

Other modules depend on Workflow Engine capabilities, never on the Workflow editor package. Workflow depends on Workflow Engine.

This is a packaging and ownership split, not a second workflow model. BPMN 2.0 and the existing native graph remain the canonical language and use the same versioned contracts.

Existing Versioning

Workflow definitions are already versioned:

workflow_definitions.current_revision identifies the latest graph revision.
workflow_definitions.active_revision selects the revision used for new instances.
workflow_definition_revisions stores immutable graph content, hashes, node library versions, execution mode, pinned View revision, BPMN XML/hash, and execution-adapter profile/version.
Graph changes create a new revision and return an active definition to draft; metadata-only changes do not create graph revisions.
Updates use expected_revision optimistic concurrency.
Instances pin definition_revision_id; later edits or module upgrades cannot mutate running or historical instances.
Derived definitions record source definition, source revision/hash, actor, Policy decision, scope, and effective ancestor limits.

The missing model is a durable module-owned baseline and local override/reset relationship.

Workflow Engine Ownership

Workflow Engine owns:

definition, immutable revision, instance, step, event, command, timer, and execution-record persistence and migrations
definition CRUD/activation/derivation APIs and headless read APIs
Workflow graph/BPMN schemas, validation, import/export, and conformance
node-library and execution-adapter registries
instance start/transition/cancel/retry/reconciliation services
runtime worker, event/API/schedule/parent dispatch, idempotency, and recovery
definition governance capability integration and audit/event emission
configuration-package workflow fragments
module-contributed standard definition discovery and reconciliation

It contributes no primary navigation or full editor. A module can install and run its workflows when the editor is absent.

Workflow Editor Ownership

Workflow owns:

the Workflow workspace and visual BPMN/graph editor
definition/revision catalogue, preview, diff, validation, and activation UI
instance inspection and operator controls built on Engine APIs
derivation and governed override UX
module-standard update comparison and reset-to-standard UX
reusable embedded editor/inspector components for other module surfaces

The editor never owns workflow tables or executes transitions directly.

Module-Contributed Definitions

Modules announce standard workflows through a versioned Engine contribution contract or a module-owned configuration-package fragment. A contribution has:

origin module ID/version, stable definition key, contribution schema version, and content hash
graph plus BPMN representation, node-library/profile requirements, and execution mode
default scope, start/reuse/automation ceilings, required capabilities, and Policy metadata
upgrade compatibility and optional migration diagnostics

Engine reconciles contributions idempotently after module discovery. The module-provided baseline is immutable. A module update may add a new baseline revision, but it never rewrites a running instance or silently replaces a local override.

Override And Reset

Editing a system/module standard creates a local override derived from a pinned baseline revision. The UI may present this as editing the effective definition, but the canonical baseline remains available.

View is always possible when the caller can read the definition.
Edit/derive is controlled by Policy and scope ceilings.
An upstream baseline update is shown as an available update with a three-way diff; it is not merged silently.
Reset archives the local override and selects the latest permitted baseline.
Historical overrides, baselines, and instances remain addressable for audit.
A tenant/group/user override cannot loosen inherited restrictions.

Compatibility And Extraction Order

Define Engine-owned capability and contribution DTOs in Core-neutral contracts while preserving existing workflow.* interface names.
Create govoplan-workflow-engine and move backend code, tests, migrations, and runtime workers without changing table names or API paths.
Transfer migration ownership without replaying the existing chain. Test both upgrades and fresh installs with Engine alone.
Keep a compatibility facade in govoplan-workflow for one release line; make it depend on workflow_engine and retain only WebUI/editor code.
Update Core workers and consuming modules to resolve Engine capabilities.
Add module contributions, immutable baselines, override/update/reset, and configuration-package support.
Remove compatibility imports only under the platform compatibility policy.

The extraction must preserve existing definition IDs, revision IDs, active revision selection, instance foreign keys, idempotency keys, API routes, and audit references.

Implemented Boundary

The split is implemented in the govoplan-workflow-engine repository. Engine owns the unchanged migration chain and /api/v1/workflow API, retains the existing workflow:* permission namespace through an explicit manifest compatibility field, and exposes headless runtime and contribution capabilities. govoplan-workflow now has a hard dependency on runtime module ID workflow_engine, contributes only its WebUI/navigation/editor contract, and keeps one release line of govoplan_workflow.backend import facades.

Module manifests can announce versioned workflow baselines. Reconciliation is idempotent, records module/schema/hash provenance, keeps a newly supplied baseline revision inactive when an older revision is active, and fails closed when required capabilities or interfaces are absent. Baselines are immutable; editing derives a pinned local override, and reset archives that override without removing revision or instance history.

6.3 KiB Raw Blame History