govoplan-workflow-engine/docs/ENGINE_EDITOR_SPLIT.md

# 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.