feat: extract headless workflow engine
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
# 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
|
||||
|
||||
1. Define Engine-owned capability and contribution DTOs in Core-neutral
|
||||
contracts while preserving existing `workflow.*` interface names.
|
||||
2. Create `govoplan-workflow-engine` and move backend code, tests, migrations,
|
||||
and runtime workers without changing table names or API paths.
|
||||
3. Transfer migration ownership without replaying the existing chain. Test both
|
||||
upgrades and fresh installs with Engine alone.
|
||||
4. Keep a compatibility facade in `govoplan-workflow` for one release line;
|
||||
make it depend on `workflow_engine` and retain only WebUI/editor code.
|
||||
5. Update Core workers and consuming modules to resolve Engine capabilities.
|
||||
6. Add module contributions, immutable baselines, override/update/reset, and
|
||||
configuration-package support.
|
||||
7. 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.
|
||||
Reference in New Issue
Block a user