# Run Effect Contract

> Canonical path: `specs/automation/run-effect-contract.md`
> Status: living-spec
> Scope: common status, idempotency, attempt, effect, and error semantics shared by automation runs and service event deliveries.
>
> Related specs:
> - [`specs/architecture/service-actor-event-automation.md`](../architecture/service-actor-event-automation.md)
> - [`specs/service/service-event-delivery.md`](../service/service-event-delivery.md)
> - [`specs/schedule/schedule.md`](../schedule/schedule.md)

## 1. Purpose

AgentTeam has multiple durable ledgers that reserve work and record an effect. They
must share status, idempotency, attempt, effect, and error semantics without
collapsing their domain ownership into one table.

## 2. Contract fields

Ledgers that implement the contract expose equivalent meanings for:

```text
status              # running / succeeded / failed / skipped / duplicate where applicable
idempotency_key
attempt_count
attempted_at
completed_at
effect_kind         # message / task_discussion / automation_run / none
effect_ref
message_id          # when the effect is a transcript message
error_code
error_detail
```

## 3. Implementers

```text
AutomationRun
  owned by AgentTeam automation such as schedule

ServiceEventDelivery
  owned by service event delivery such as GitHub/Gitea pull request subscriptions
```

Direct service posts do not implement this contract because they are ordinary
message writes, not runs or event deliveries.

## 4. Idempotency and completion

A ledger reserves an idempotency key before the effect is written. Exactly one
successful effect may be associated with a reserved key. Retries update attempt
state; they must not create additional transcript messages for the same logical
occurrence or additional automation runs for the same logical occurrence.

Completion records both effect and error state. A successful ledger has a stable
effect reference, such as a message id, task-discussion entry id, or MeshX
automation run id. A failed ledger has a stable error code and detail suitable for
operator diagnostics and user-facing compatibility views.