1 files changed, 22 insertions, 27 deletions

diff --git a/internal/casino/types.go b/internal/casino/types.go
index 980769c..a5e1415 100644
--- a/internal/casino/types.go
+++ b/internal/casino/types.go
@@ -191,44 +191,39 @@ type Wager struct {
 	Total   int
 	Chips   int
 	Credits int
-	// ID is the wallet's opaque handle for the journaled stake record:
-	// table settlements pay through PayStakeCover with the hand's stake
-	// IDs so the journal can prove which wager a settlement returns.
+	// ID is the wallet's opaque handle for the committed stake. Table
+	// settlements pass the hand's stake IDs to PayStakeCover so the wallet
+	// removes exactly the stakes the payout returns.
 	ID string
 }
 
 type Wallet interface {
-	// Wager debits the stake durably. ErrInsufficientFunds is a normal
-	// rejected bet; ErrWalletPersistence means the debit could not be made
-	// durable and the game must not proceed as if the bet succeeded.
+	// Wager debits the stake and records it as pending. ErrInsufficientFunds
+	// is a normal rejected bet; ErrWalletPersistence means the debit could
+	// not be made durable and the game must not proceed as if it succeeded.
 	Wager(amount int) (Wager, error)
-	// PayCredits pays a settlement durably, returning an error when the
-	// credit could not be persisted (the game must not report a win that
-	// is not durable). The journaled record carries no stake linkage:
-	// recovery treats it as resolving the round (a slots payout is
-	// winnings only; the stake was consumed by playing the round).
+	// PayCredits pays winnings durably, returning an error when the credit
+	// could not be persisted (the game must not report a win that is not
+	// durable). The payout carries no stake linkage: the stake was consumed
+	// by playing the round, so the game resolves it separately.
 	PayCredits(amount int) error
 	// PayStakeCover pays a settlement whose amount INCLUDES the return of
 	// the listed stake wager IDs (a table hand pays back its stake inside
-	// the payout). When the payout cannot be made durable, the open
-	// journal record still proves those stakes were returned inside it, so
-	// a shutdown refund must not return them a second time and recovery
-	// re-applies the owed payout instead.
+	// the payout). The credit and the removal of those stakes are one
+	// durable step, so a failed settlement leaves the stakes pending —
+	// refunded at the next startup, never paid on top of the refund.
 	PayStakeCover(amount int, stakeIDs []string) error
-	// ResolveStakes marks every outstanding stake for this player as
-	// settled: the round resolved (won, lost, pushed, or forfeited), so
-	// startup recovery must no longer refund it. A stake whose wager
-	// record remains open at restart is refunded by recovery.
+	// ResolveStakes consumes every pending stake for this player: the round
+	// resolved as a loss, a forfeit, or an unlinked payout, so the stakes
+	// must not be refunded.
 	ResolveStakes()
-	// ResolveStake settles ONE outstanding stake by wallet handle (a
-	// single hand paid or lost while a sibling hand's payout is still in
-	// flight): its return is proven, so it must never be refunded.
+	// ResolveStake consumes ONE pending stake by wallet handle (a single
+	// hand paid or lost while a sibling hand's round is still in flight).
 	ResolveStake(stakeID string)
-	// RefundOutstanding returns every outstanding stake to the player
-	// (chips as chips, credits through the durable payout path) and
-	// resolves the stakes. It reports the amounts returned. An error
-	// means the refund could not be made durable: the stakes remain open
-	// and startup recovery completes the refund.
+	// RefundOutstanding returns every pending stake to the player (chips as
+	// chips, credits as credits) and clears the ledger. An error means the
+	// refund could not be made durable: nothing was returned and the stakes
+	// remain pending for a later attempt or startup recovery.
 	RefundOutstanding() (chips, credits int, err error)
 }