diff --git a/README.md b/README.md index bcd8cda..baff117 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,10 @@ **Repository type:** module (platform). -`govoplan-workflow` owns process orchestration for GovOPlaN. +`govoplan-workflow` currently owns process orchestration and its editor for +GovOPlaN. The accepted target separates the headless runtime into +`govoplan-workflow-engine`, while this module remains the optional authoring and +inspection interface. The module should execute configurable state machines and command handoffs between modules without importing their implementations. It coordinates cases, @@ -52,3 +55,5 @@ operation providers are implemented. See [docs/CONCEPT.md](docs/CONCEPT.md) for the complete module concept. See [docs/BPMN_INTEROPERABILITY.md](docs/BPMN_INTEROPERABILITY.md) for the notation, conformance, and adapter boundary. +See [docs/ENGINE_EDITOR_SPLIT.md](docs/ENGINE_EDITOR_SPLIT.md) for the accepted +runtime/editor extraction and module-owned workflow baseline model. diff --git a/docs/CONCEPT.md b/docs/CONCEPT.md index 16d0f2d..24148ae 100644 --- a/docs/CONCEPT.md +++ b/docs/CONCEPT.md @@ -2,9 +2,10 @@ ## Purpose -`govoplan-workflow` is the process orchestration module. It turns a configured -administrative procedure into state transitions, guards, commands, timers, and -operator-visible progress. +The current `govoplan-workflow` package is the process orchestration module. The +accepted target moves definition/runtime ownership to the headless +`govoplan-workflow-engine` module and keeps `govoplan-workflow` as the optional +authoring and inspection surface. See `ENGINE_EDITOR_SPLIT.md`. Workflow does not own business records. A case, task, file, appointment, template, payment, or postbox message remains owned by its domain module. @@ -193,8 +194,6 @@ Minimum tests: ## Open Decisions -- Whether to implement BPMN import later or keep a GovOPlaN-native JSON model. -- How much visual workflow editing belongs in the first WebUI. - Whether long-running timers use Celery beat, a module scheduler, or an ops scheduler abstraction. - How workflow variables are redacted and retained. diff --git a/docs/ENGINE_EDITOR_SPLIT.md b/docs/ENGINE_EDITOR_SPLIT.md new file mode 100644 index 0000000..24d1024 --- /dev/null +++ b/docs/ENGINE_EDITOR_SPLIT.md @@ -0,0 +1,120 @@ +# 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.