# govoplan-workflow Concept ## Purpose `govoplan-workflow-engine` is the headless process orchestration module. `govoplan-workflow` is its 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. Workflow coordinates those modules through stable contracts. Workflow is also the first home for GovOPlaN's action/effect automation layer. That layer must keep automated actions governed, previewable, idempotent, auditable, and recoverable. If action catalogues, schedules, rule execution, or cross-module automation grow beyond workflow ownership, the runner can later be split into a dedicated `govoplan-automation` module without changing the action/effect contracts. ## Ownership Workflow Engine owns: - workflow definitions and versions - workflow instances and current state - transitions, guards, and transition history - timers, deadlines, and wait states that belong to process execution - command plans and command execution records - retry/manual-intervention state for failed command handoffs - action/effect execution records for workflow-triggered automation - workflow audit/event emission - workflow diagram metadata Workflow owns visual authoring, catalogue, comparison, activation, inspection, override, and reset surfaces. It owns no process tables or transition runtime. The module does not own: - case records and case evidence - task queues and task completion semantics - form schemas or submissions - file storage, documents, mail, notifications, appointments, payments, ledgers, or records - external protocol adapters ## Workflow Model A workflow definition should contain: - definition id, version, tenant scope, status - states with labels, categories, and terminal markers - transitions with from/to states, required scopes, guards, and commands - input/output data schema references - timers and escalation rules - extension metadata for diagrams and operator UI Instances should contain: - instance id, tenant id, definition id/version - subject references such as `case_id` or `submission_id` - current state and previous state - process variables with strict redaction rules - transition history - pending commands and manual actions ## Core Contracts The module should integrate through: - module manifest metadata, route factories, permissions, and migrations - events such as `workflow.instance_started`, `workflow.transitioned`, `workflow.command_requested`, `workflow.command_failed`, and `workflow.instance_completed` - commands such as `workflow.start`, `workflow.transition`, `workflow.retry_command`, and `workflow.cancel` - capability lookups for domain commands, for example cases, tasks, templates, appointments, and payments - configuration-package fragments that install workflow definitions Command handoff must be explicit. A transition should record which module capability was requested, with input payload, result summary, and failure reason. The shared action/effect doctrine lives in `govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md`. ## Reference Journey Permit-to-payment MVP: 1. A form submission starts a workflow instance. 2. Workflow commands cases to create a case. 3. Workflow commands tasks to create an intake task. 4. Completion of the task transitions the instance to appointment proposal. 5. Appointment acceptance transitions to review/decision. 6. Workflow commands templates to generate a permit or decision. 7. Workflow commands payments/ledger handoff. 8. Workflow closes the case and emits evidence events. ## MVP Slice The first executable slice now provides: - a versioned, workflow-specific graphical node library - shared Core graph DTO and validation primitives also consumed by Dataflow - workflow constraints that permit loops while requiring one trigger and one or more outcomes - trigger, activity, review, decision, wait, module-action, Dataflow, and outcome nodes - API discovery and validation endpoints - revision-pinned, idempotent Workflow instances - persisted steps and append-only transition evidence - durable Dataflow handoff, progress reconciliation, output references, retries, cancellation, and warning/review paths - manual activity, review, and wait handoffs with comments and evidence - a worker capability with current-authorization rechecks - an operator dialog for starting, inspecting, and advancing instances - an owner-side Service launcher that starts an authorized active definition, retains the exact Service/binding provenance, and safely replays Portal calls - activation-bound API, one-time/interval schedule, platform-event, and parent-workflow trigger registrations with exact-revision dispatch - durable duration/deadline/event wait subscriptions and scale-out-safe claims - resumable external hand-offs with immutable references, focused action URLs, duplicate-safe observed events, terminal outcome ports, timeout paths, and a provider authorization/revision recheck before continuation - a separate transactional platform-event consumer with bounded JSON filters and variable mappings, idempotent delivery, and current-authority rechecks - Core recovery-ledger operations for module actions, including canonical request evidence, provider-dispatch checkpoints, and atomic local projection commits - explicit effect-confirmed/effect-absent reconciliation for unknown provider outcomes, with blind retries disabled - distributed execution fences for instance reconciliation, trigger delivery, and timer resumption - fail-closed propagation of unresolved Dataflow publication outcomes The next execution depth should provide: - static workflow definition registration from configuration packages - guard hooks implemented through capability calls - explicit blocked, retryable, quarantined, manual-required, and compensation-required states - dashboard summary provider - cron/calendar scheduling through a governed scheduler adapter ## Permissions Candidate scopes: - `workflow:definition:read` - `workflow:definition:write` - `workflow:instance:read` - `workflow:instance:start` - `workflow:instance:transition` - `workflow:instance:admin` State transitions may require both workflow scopes and domain-module permission checks for the command being executed. Workflow guard evaluation should consume access semantics through kernel capabilities instead of importing access internals: - `access.semanticDirectory` resolves identity, account, organization unit, function assignment, delegation, and role facts. - `access.explanation` records why a transition was allowed or denied in terms of identity/account/function/role/right provenance. Transitions that allow a person to act in place of another function holder must require an explicit acting context and must record both the real actor account and the represented account/function assignment in transition history and audit details. ## Data Model Sketch Current tables: - `workflow_definitions` - `workflow_definition_revisions` - `workflow_instances` - `workflow_instance_steps` - `workflow_instance_events` - `workflow_triggers` - `workflow_trigger_deliveries` - `workflow_wait_states` Future generic action execution may add: - `workflow_command_records` Definitions should be immutable by version after activation. Instances should reference the exact version used at start. ## WebUI Current route contribution: - `/workflow` The route combines the definition editor and a fixed run dialog showing current state, available transitions, failed handoffs, comments/evidence, immutable event history, and linked Dataflow results. It does not import Dataflow or other domain UI components. ## Tests Minimum tests: - core starts with workflow installed but cases/tasks/templates absent - workflow definition versioning is immutable after activation - transition guard denial is recorded and visible - command failure is retryable and does not partially advance state - events are emitted for start/transition/completion - configuration package can install a simple workflow definition ## Bounded Decisions - Native scheduling deliberately supports one-time and minimum-60-second interval triggers. Cron/calendar semantics belong to a future governed scheduler adapter rather than an unbounded expression evaluator in Engine. - Platform events contain sanitized lifecycle context, not raw instance variables. Definition mappings can select only bounded event fields; broader variable retention/redaction remains policy-controlled product depth.