Failure and recovery reference

Failure envelope

Agent and tool boundaries normalize failures into safe structured data rather than passing provider bodies downstream.

{
  "category": "dependency",
  "code": "provider_unavailable",
  "message": "The provider is temporarily unavailable.",
  "retryable": true,
  "stage": "understand",
  "attempt": 1,
  "maxAttempts": 3
}

Credentials, prompts, transcripts, drafts, private provider payloads, and stack traces are excluded from operator and model-facing envelopes.

Classification and action

Category	Typical examples	Automatic action
validation	malformed schema, unsupported source	terminal; surface correction
authorization	missing consent, wrong tenant, expired non-refreshable token	terminal; operator action
policy	budget, safety, or approval violation	terminal; preserve decision context
dependency	timeout, `429`, provider `5xx`	bounded retry when explicitly retryable
conflict	ETag mismatch, concurrent state change	read-back or transaction reconciliation
uncertain effect	claim expired without a receipt, ambiguous calendar provisioning	fail closed; operator reconciliation
internal	invariant or protocol failure	terminal and observable

Effect recovery states

Claim result	Meaning	Provider call allowed?
`execute`	caller owns a live claim	yes, once
`in_progress`	another delivery owns the claim	no
`already_applied`	original receipt exists	no; return original receipt identity
`uncertain`	lease expired without final proof	no; operator reconciliation required

Only the explicit Prove duplicate suppression control creates replay evidence. Ordinary duplicate delivery suppresses the provider call without creating a new replay record.

A visible failure is a valid terminal outcome. Harmonia never converts an unavailable provider, missing credential, unverifiable effect, or exhausted retry into simulated success.

Authority and safety

Observability

Deployment

Failure and recovery reference

Failure envelope

Classification and action

Recovery sequence

Effect recovery states

​Failure envelope

​Classification and action

​Recovery sequence

​Effect recovery states

Failure envelope

Classification and action

Recovery sequence

Effect recovery states