Skip to content

Commit ad8cc59

Browse files
committed
docs(reorg): reconcile the guidance list with the corrected failure model
The Guidance section still carried both claims the rest of the note had already dropped: that every step before the commit point is safe to re-enter, and that the phase marker was a mistake protecting an impossible failure. Rule 1 now asks which of atomic, compensatable, or recoverable applies per store, because 'safe to re-enter' assumed each step either happens or does not, and the shard-walking UTXO commit does not honour that. Rule 2 keeps its point about mechanisms for impossible failures and drops the example, which was not one: a checkpoint can retain a UTXO commit whose undo record was lost with the journal, and a durable boundary is a way to detect it.
1 parent 739ffa2 commit ad8cc59

1 file changed

Lines changed: 11 additions & 5 deletions

File tree

docs/solutions/architecture-patterns/node-reorg-execution-design.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -173,11 +173,17 @@ hash and height where it wedged.
173173
## Guidance
174174

175175
1. **Name the commit point before writing any of it.** Which single mutation
176-
decides that the disconnect happened? Everything before it must be safe to
177-
re-enter; everything after is cleanup.
178-
2. **Do not add a mechanism whose failure mode cannot occur.** The phase marker
179-
here was that mistake — it protects boundaries in a store whose partial
180-
states never persist.
176+
decides that the disconnect happened? Everything after it is cleanup.
177+
Everything before it must be atomic, compensatable, or recoverable, and you
178+
must say which for each store. "Safe to re-enter" was the earlier wording and
179+
it was wishful: it assumed each step either happens or does not, which the
180+
shard-walking UTXO commit does not honour.
181+
2. **Do not add a mechanism whose failure mode cannot occur, and do not assume a
182+
failure mode cannot occur because one store is in RAM.** The phase marker was
183+
called a mistake on that reasoning. It is not settled: a checkpoint can
184+
retain a UTXO commit whose undo record was lost with the journal, and a
185+
durable boundary is one way to detect that. Decide it with the recovery
186+
protocol.
181187
3. **A trait default that returns success is a silent-corruption path.** When a
182188
consumer must participate in rollback, make the default refuse. See
183189
`IndexError::UnsupportedRollback`.

0 commit comments

Comments
 (0)