Inventory module recovery ledger adoption

2026-08-03 03:02:53 +02:00
parent e8f7e2c194
commit 9370f501a0
4 changed files with 292 additions and 0 deletions
@@ -0,0 +1,56 @@
+# 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`](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.