Metadata-Version: 2.4
Name: govoplan-workflow-engine
Version: 0.1.19
Summary: Headless, versioned workflow definition and execution engine for GovOPlaN.
Author: GovOPlaN
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: defusedxml<1,>=0.7
Requires-Dist: govoplan-core>=0.1.28

# GovOPlaN Workflow Engine

## Data-subject requests

Workflow Engine publishes `privacy.dsar.workflow_engine` for exact definition,
revision, instance, step, event, trigger, delivery, and wait references and for
structured instance authorization, work assignments, automation authority, and
minimized operator attribution. It never exports graphs/BPMN, inputs, context,
outputs, handoffs, events/configuration, authorization snapshots, errors,
replay keys, external references, hashes, or credentials. Owning service, case,
form, and other source modules locate and correct facts inside arbitrary
runtime payloads.

Subject-linked automation can be disabled and revoked, while exact terminal
delivery detail can be minimized idempotently without changing its replay key.
Definitions, instances, live work, assignments, transition and decision
events, waits, and institutional attribution require authorized review or
retention.

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

Headless workflow definition and execution services for GovOPlaN modules.

Workflow Engine owns the canonical BPMN/native graph model, immutable
definition revisions, runtime instances and evidence, migrations, validation,
execution adapters, dispatch, retries, and recovery. It intentionally provides
no primary navigation or visual editor. Modules can depend on runtime module ID
`workflow_engine` and the versioned `workflow.*` interfaces without installing
the optional `govoplan-workflow` editor.

The extraction preserves the existing `workflow_*` tables, Alembic revision
IDs, `/api/v1/workflow` routes, `workflow:*` permissions, instance IDs, and
audit references. See [the engine/editor split](docs/ENGINE_EDITOR_SPLIT.md)
for the ownership and compatibility policy.
See [the module concept](docs/CONCEPT.md) and
[BPMN interoperability contract](docs/BPMN_INTEROPERABILITY.md) for runtime
semantics and adapter boundaries.
See [durable runtime recovery](docs/DURABLE_RUNTIME_RECOVERY.md) for action,
worker, timer, and unknown-provider-outcome handling.

The optional `workflow_engine.service_launcher` capability lets Portal start an
authorized active workflow from an exact published Service revision. It resolves
tenant overrides before system baselines, pins the selected workflow revision,
records the Service and binding in trusted instance context, and safely replays
the same launch after an ambiguous response. Portal never accesses Workflow
Engine tables.

Active definitions reconcile durable API, one-time/interval schedule,
platform-event, and parent-workflow trigger registrations. A shared worker
claims due deliveries with scale-out-safe locking, rechecks the exact active
revision and automation authority, and starts instances idempotently. Duration,
deadline, and platform-event waits are persistent runtime state rather than
human handoffs; event filters and variable mappings are bounded JSON
expressions and never executable code. Cron remains an optional governed
scheduler-adapter concern.

External hand-off waits bind an immutable, revision-bearing domain reference
to a focused action URL and resume only from declared terminal platform events.
The runtime rechecks the provider's current authorization and resource revision
before continuing. Observational events are duplicate-safe, navigation alone
never completes work, and a missing optional projection remains visible without
changing the domain outcome.

Consequential module actions are staged in Core's durable recovery ledger
before provider dispatch. Conclusive effects commit with the Workflow
projection. Lost acknowledgements block continuation and expose evidence-based
**Effect confirmed** and **Effect absent** operator actions instead of a blind
retry. Instance workers, trigger deliveries, and timers are fenced across
hosts; linked Dataflow recovery states remain unresolved until Dataflow reports
a conclusive outcome.

## Checks

```bash
/mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
```
