Mirrored from
/mnt/DATA/git/govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md. Origin:repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
Action, Effect, And Automation Layer
GovOPlaN needs an automation layer because administrative processes will not be only linear screen flows. Workflows, schedules, imports, connectors, policies, and external events all need to request governed actions without bypassing the same safety rules that apply to human users.
The first implementation should live in govoplan-workflow and core contracts.
Create a separate govoplan-automation module only if action planning,
schedulers, rule execution, or cross-module automation become too broad for
workflow ownership.
Layer Purpose
The automation layer should provide:
- a typed action catalogue
- a typed effect catalogue
- consequence preview before execution
- policy and permission checks
- idempotent execution
- audit and provenance records
- retry, quarantine, and manual exception handling
- system-actor execution without hiding responsibility
Automation is not a shortcut around module boundaries. It is a governed caller of module capabilities.
Action Definition
An ActionDefinition describes something a human or system actor can request.
Recommended fields:
action_key- owning module
- input schema
- actor requirements and required scopes
- required capabilities
- policy checks
- risk level
- reversibility class: reversible, compensatable, corrective-only, or irreversible
- expected effects
- idempotency key strategy
- audit event names
- preview provider
Examples:
- create a case from a form submission
- assign a task
- generate a document from a template
- send a postbox message
- send an email notification
- append evidence to records
- create a payment request
- call an external connector
Effect Definition
An EffectDefinition describes the expected and observed result of an action.
Recommended fields:
effect_key- affected module and resource references
- external system references where applicable
- created, changed, deleted, sent, notified, locked, or retained markers
- visibility and privacy classification
- audit event references
- rollback or compensation hints
- operator-facing explanation
Effects should be recorded even when execution fails partially. This makes manual recovery and audit review possible.
Execution Model
The runner should execute an action plan as follows:
- Resolve actor context: human, delegated actor, or system actor.
- Validate input schema.
- Resolve required module capabilities.
- Run permission and policy checks.
- Generate a consequence preview.
- Reserve or verify the idempotency key.
- Execute the owning module capability.
- Record observed effects.
- Emit events and audit records.
- Mark the command complete, retryable, quarantined, or requiring manual intervention.
The runner must never advance workflow state past a required side effect unless the action definition explicitly allows asynchronous completion and the pending state is visible.
Failure States
Automation should use explicit failure states:
blocked: policy, permission, missing capability, or invalid input prevents execution.retryable: transient transport, timeout, rate-limit, or lock conflict.quarantined: unexpected response, schema mismatch, unsafe partial result, or unknown external state.manual_required: human decision or correction is needed.compensation_required: a later action must correct an already observed side effect.
These states should be visible in workflow, task, and admin diagnostics.
Boundary
Core may own stable DTOs, registry contracts, and generic audit/event hooks.
govoplan-workflow should own the first runner because workflow is the first
module that coordinates cross-module process actions.
Domain modules own their own action providers. For example, templates own document generation actions, postbox owns postbox message actions, and connectors own external handoff actions.