refactor: replace economy journal with single-file pending-wager wallet

1 files changed, 7 insertions, 6 deletions

diff --git a/internal/casino/core.go b/internal/casino/core.go
index a0ac1c8..4177094 100644
--- a/internal/casino/core.go
+++ b/internal/casino/core.go
@@ -116,7 +116,7 @@ func (c *tableCore[P]) refundAllLocked() []Event {
 		refund := chips + credits
 		if err != nil || refund <= 0 {
 			if err != nil {
-				events = append(events, c.private(name, "Shutdown refund could not be persisted; the stake is recorded for recovery."))
+				events = append(events, c.private(name, "Shutdown refund could not be persisted; the stake stays pending for the next startup."))
 			}
 			continue
 		}
@@ -131,11 +131,12 @@ func (c *tableCore[P]) refundAllLocked() []Event {
 // reports whether the settlement could NOT be made durable. It carries the
 // money-critical ordering shared by every table game (documented in
 // building_guide/concurrency.md): compute the payout, pay it via
-// PayStakeCover BEFORE announcing the win, and only then resolve the stakes
-// the settlement returned. On a persistence failure the stakes are left open
-// so recovery re-applies the owed payout and a shutdown refund never returns
-// them a second time; the caller must not announce a paid win and must not
-// run the player-wide ResolveStakes.
+// PayStakeCover BEFORE announcing the win (that one save both credits the
+// payout and removes the stakes it returns), and only then stand the hand
+// down. On a persistence failure the stakes stay pending, so a later shutdown
+// refund or startup recovery returns them exactly once — the payout was never
+// durable, so it can never be paid on top of the refund. The caller must not
+// announce a paid win and must not run the player-wide ResolveStakes.
 //
 // payoutErr is a payout-computation error (for example an overflowed
 // multiplier): it is treated exactly like a persistence failure so a