govoplan-core/docs/AUTOMATION_CONTRACTS.md

Automation Contracts

Core defines provider-neutral automation contracts. It does not own domain schedules, Workflow graphs, or Dataflow execution.

Invocation Envelope

AutomationInvocation classifies a start as manual, api, schedule, event, workflow, dependency, retry, or backfill. It carries opaque trigger and delivery references, event identity, correlation and causation IDs, scheduled time, requesting actor, and bounded metadata. Domain runs store this envelope with their immutable definition revision.

Current Authorization

An automated trigger must not persist a user session, bearer token, API key, or a snapshot of all current permissions. It stores:

• tenant, account, and membership IDs;
• an opaque authorization reference;
• the minimum scopes required by the pinned definition and output target.

At delivery time the optional auth.automationPrincipalProvider capability resolves current account, membership, role, group, function, and delegation state. It intersects current authorization with the stored grant. Missing, inactive, or reduced authorization blocks the delivery before effects occur.

Definition Governance

The optional policy.definitionGovernance capability evaluates view, edit, run, reuse, derive, and automate for system, tenant, group, and user definitions. A decision contains an ordered source path and effective limits. Derived definitions pin their source revision and hash and retain ancestor ceilings. Templates are reusable definitions and cannot run on their own.

Without Policy, domain modules use a conservative tenant-local fallback: local definitions remain viewable/editable and active complete flows may run; inheritance, reuse, derivation, and automation are unavailable.

Delivery Durability

Domain trigger implementations persist idempotent deliveries before running. emit_platform_event binds event delivery to the producer's SQLAlchemy transaction. When an enabled module provides platform.eventOutbox, the event is stored in that transaction and a dispatcher may retry it across restarts and workers. The Audit module provides the current SQL outbox implementation; the Celery govoplan.events.dispatch_outbox task drains it through the Dataflow event-ingestion capability and the local event bus.

The outbox capability remains optional so reduced module combinations can start. Without it, Core queues events on the SQLAlchemy transaction and publishes them to the process-local bus only after the outer commit. A rollback, including a nested savepoint rollback, discards the corresponding events. This fallback is suitable for local or non-critical reactions, but it is not a durable multi-worker automation source. Deployments that rely on event-triggered work must enable the outbox provider and run the events worker queue and periodic dispatcher.