fix: keep uncertain payout append from double-paying on recovery

1 files changed, 9 insertions, 0 deletions

diff --git a/building_guide/concurrency.md b/building_guide/concurrency.md
index 74bbdc7..081952f 100644
--- a/building_guide/concurrency.md
+++ b/building_guide/concurrency.md
@@ -163,6 +163,15 @@ wallet degrades safely:
   chip stake is not returned in kind on top of credits that already
   returned it). If the character save fails too, no evidence exists and
   the open wager record drives the ordinary refund-on-lost-state recovery.
+  The same save records the attempted payout record's ID in the character
+  file's `open_payouts` evidence list. A failed append is not proof that no
+  record was written — a failed rollback (the truncate, or the sync that
+  would make the truncation durable) can leave the record bytes behind, and
+  a retry can leave bytes from an earlier attempt even when the final error
+  is definite. Recording the ID means a surviving open payout is settled by
+  recovery from the file evidence instead of being re-applied (a
+  double-pay); when no record survived, the stale ID is pruned at the next
+  startup.
 - A journal that cannot be fully READ (oversized or unreadable line) or
   that contains a malformed record with later records present aborts
   recovery and compaction entirely: records are preserved verbatim for