60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
# 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.
|