Record the engine/UI seam as an architectural decision #34

New issue

Closed

opened 2026-08-12 17:44:52 +00:00 by rosa · 0 comments

rosa commented

2026-08-12 17:44:52 +00:00

Owner

Parent

#27

What to build

An architectural decision record for the shape three games now share: a game
separates a value-returning engine, which owns the rules and answers in payouts,
from a UI, which owns the terminal and the bankroll and holds no rules of its
own. The engine's alternate constructor — a fixed wheel, a scripted sequence of
dice — is the determinism seam that makes the rules testable.

Blackjack established it, roulette followed it, craps makes three. Poker is next
in line and currently has no engine to split at all, so the next person to reach
for this should find a decision rather than three examples to infer from.

Worth capturing: why the randomness lives inside the engine rather than being
supplied by the caller, why the engine never touches the bankroll, and how this
sits with the existing decision to take the wager up front — the engine can
report what a position returns precisely because the money already left.

Acceptance criteria

A decision record exists for the engine/UI seam, following the existing
record's format and numbering
It names the alternate constructor as the determinism seam
It states the consequences, including what it costs
It relates the seam to the take-the-wager-up-front decision rather than
restating it
It describes the pattern as it stands, without narrating which game got
there first as justification

Blocked by

## Parent #27 ## What to build An architectural decision record for the shape three games now share: a game separates a value-returning engine, which owns the rules and answers in payouts, from a UI, which owns the terminal and the bankroll and holds no rules of its own. The engine's alternate constructor — a fixed wheel, a scripted sequence of dice — is the determinism seam that makes the rules testable. Blackjack established it, roulette followed it, craps makes three. Poker is next in line and currently has no engine to split at all, so the next person to reach for this should find a decision rather than three examples to infer from. Worth capturing: why the randomness lives inside the engine rather than being supplied by the caller, why the engine never touches the bankroll, and how this sits with the existing decision to take the wager up front — the engine can report what a position returns precisely because the money already left. ## Acceptance criteria - [ ] A decision record exists for the engine/UI seam, following the existing record's format and numbering - [ ] It names the alternate constructor as the determinism seam - [ ] It states the consequences, including what it costs - [ ] It relates the seam to the take-the-wager-up-front decision rather than restating it - [ ] It describes the pattern as it stands, without narrating which game got there first as justification ## Blocked by - #31

rosa added the

ready-for-agent

label

2026-08-12 17:45:22 +00:00

rosa closed this issue

2026-08-14 02:35:59 +00:00

rosa referenced this issue from a commit

2026-08-14 03:02:02 +00:00

docs: record the engine/UI seam as a decision