# 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 lives in `govoplan-workflow-engine` 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.
The versioned runtime DTOs and provider protocol live in
`govoplan_core.core.automation`; domain modules implement the protocol and
Workflow resolves providers through module capabilities rather than importing
their implementations.

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.

For external and asynchronous effects, providers must preserve the distinction
between:

1. requested intent;
2. approved intent;
3. dispatched command;
4. possibly executed but unconfirmed outcome;
5. confirmed observed effect;
6. reconciled, corrected, or compensated outcome.

An API timeout after dispatch is not a failed effect and must not be retried as
a fresh command. The actor context should retain the real identity/account,
represented function or party, delegation or power, and mandate/jurisdiction
references when applicable. Domain modules remain responsible for deciding
which of those references are required for their action.

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

The contract names these states explicitly as `ActionExecutionState`, alongside
`pending`, `running`, and `completed`. A provider returns observed effects even
for partial failures; the runner, not the provider, owns durable attempts,
recovery decisions, and workflow advancement.

## Boundary

Core may own stable DTOs, registry contracts, and generic audit/event hooks.
`govoplan-workflow-engine` owns 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.
