govoplan/docs/RECOVERY_LEDGER_ADOPTION.md

Recovery Ledger Adoption

The Core recovery ledger is a platform primitive, not automatic protection for module-owned effects. The canonical, machine-checked inventory is recovery-operation-inventory.json.

Classification Rules

• Use atomic only when every mutation commits in one database transaction and no external effect occurs.
• Use compensation when every completed effect has a bounded, verifiable inverse action. A best-effort delete is not proof of compensation.
• Use snapshot_restore only with fresh, signed backup evidence that covers all affected state services at one recovery point.
• Use forward_recovery for provider acceptance, queue publication, cursor advancement, and other effects that may be resumable but cannot safely be undone.
• Use irreversible for approved purge or destruction where no automated recovery is claimed.

One feature may cross more than one boundary. Module installation is compensatable before schema migration, forward-only after migration starts, and snapshot-restorable for an approved destructive retirement. Mail submission is forward recovery because losing the response after provider acceptance must not cause an automatic resend.

Adoption Order

1. Campaign build is the reference implementation for a database plus object storage operation. Its operation reserves a build-specific object prefix, persists request and precondition evidence before writes, records the final object manifest, and verifies database/object state before success.
2. Campaign delivery and Mail provider effects adopt outcome-unknown semantics without weakening their existing provider-specific idempotency records.
3. Files applies the same contract to uploads, purge, integrity reconciliation, and writable connector synchronization.
4. Connectors, Dataflow, and Workflow Engine consume the contract at their registry/capability boundaries so optional providers remain optional.
5. Core module lifecycle uses the ledger in addition to, not instead of, signed deployment and backup evidence.

Every fenced operation uses a process incarnation and distributed lease. A stale process cannot append a checkpoint or report success. An expired operation is claimed for recovery through an explicit takeover that preserves the prior fence in the checkpoint chain; it is never resumed as a normal retry.

Operator Contract

Ops lists non-terminal and manual-intervention operations. Operators must verify the checkpoint chain before trusting evidence, distinguish outcome_unknown from rejection, and use the owning module's documented reconciliation action. No evidence payload may contain credentials or resolved secrets.

The parent adoption issue remains open until all inventory rows are adopted and the module matrix proves crash, retry, stale-fence, tamper, and optional-module behavior for each consequential path.