govoplan-core/docs/ACTION_EFFECT_AUTOMATION_LAYER.md

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:

1. Resolve actor context: human, delegated actor, or system actor.
2. Validate input schema.
3. Resolve required module capabilities.
4. Run permission and policy checks.
5. Generate a consequence preview.
6. Reserve or verify the idempotency key.
7. Execute the owning module capability.
8. Record observed effects.
9. Emit events and audit records.
10. 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.