Transactions and Compensation

Many business operations are not safe as one opaque tool call. A payment, booking, CRM mutation, or account change may need validation, approval, commit, reconciliation, and a compensating action.

AIP models those stages explicitly so every connector follows the same lifecycle.

Execution Modes

Mode	Meaning
execute	Perform the operation normally
dry_run	Validate or simulate without intended side effects
plan	Produce a durable plan bound to exact input and policy
commit	Execute a previously created plan
compensate	Run the declared compensating operation
reconcile	Resolve a provider outcome that is currently unknown
rollback_not_supported	State explicitly that reversal is unavailable

The capability contract declares which modes exist and the fidelity of a dry run. Schema-only validation is not equivalent to a provider simulation.

Plan and Commit

A transaction plan binds:

• transaction, plan, action, and capability ids;
• the canonical input hash and optional snapshot;
• the requesting principal and trusted identity context;
• predicted side effects;
• approval and compensation contracts;
• creation and expiration timestamps.

Commit must reference the plan id. The runtime rejects a commit when the input, capability, identity, policy, expiration, or transaction binding no longer matches. This prevents a valid approval for one operation from authorizing a different mutation.

Commit Ownership

Only one action may acquire commit ownership for a plan. Storage must provide an atomic claim with fencing so two workers cannot both perform the provider mutation after a timeout or restart.

An idempotency record and a transaction claim solve related but different problems: the first deduplicates a caller request; the second owns the business commit.

Unknown Outcomes

The most dangerous failure occurs when the provider may have committed but its response was lost. AIP records this as outcome_unknown and retains the provider operation reference.

The runtime must then:

1. stop automatic commit retry;
2. query or reconcile the provider using its operation id;
3. record the definitive outcome;
4. only then decide whether retry or compensation is allowed.

Treating an unknown outcome as a normal temporary error can duplicate a payment, message, or booking.

Compensation

Compensation is a new governed operation that attempts to offset a committed side effect. It is not database rollback across independent systems.

The capability contract declares one of four modes:

• not_required;
• supported with a compensating capability;
• best_effort;
• rollback_not_supported.

Compensation may have its own approval, idempotency, and failure behavior. The receipt chain should link it to the action being compensated.

Transaction States

The wire model includes planned, prepared, committing, committed, compensating, compensated, requires-human, cancelled, rollback_not_supported, failed, outcome_unknown, reconciling, and reconciled states. Operators should query the transaction view rather than infer transaction state from the action result alone.

Design Checklist

• Use a stable provider operation id when the provider offers one.
• Require idempotency for commit and compensation where supported.
• Persist plan, approval, commit claim, provider reference, result, and receipts atomically at their ownership boundaries.
• Never advertise dry_run as full simulation unless the provider executes the same validation path without commit.
• Do not promise rollback for an irreversible provider operation.
• Reconcile unknown outcomes before retrying.