DETERMINISTIC BLACKJACK LIVE COMPANION Application README / Operator Guide Aligned builds: CLI V9.2.18-UAT / GUI v15.10.59 Status: Frozen/replay/evidence workflow established; Personal + Stat-Watching post-commit reveal remains under live UAT. ------------------------------------------------------------------------ 1. WHAT THIS APPLICATION IS This is a research-oriented blackjack live-session companion and replay environment. It is not an automated casino player and it does not control the external blackjack site. The operator plays the external game and records what was actually observed. The application provides a deterministic reference policy, captures the observed card chronology and decisions, validates the session where possible, retains evidence, and supports post-session replay/counterfactual analysis. There are two user-facing applications: - Live Graphical Companion — used while a real/observed blackjack session is being played. - Historical Replay / Stats application — used after sessions to inspect journeys, Memory Lane/statistics and accumulated experimental comparisons. The CLI is the authoritative backend and evidence writer. The GUI is the visual/input layer over that backend. ------------------------------------------------------------------------ 2. STARTING THE APPLICATION Graphical live play From the GUI folder run: RUN_LIVE_GUI_UAT.bat This starts the graphical live companion while using the neighbouring CLI folder as the authoritative working/data location. Historical replay and statistics From the GUI folder run: RUN_REPLAY.bat This opens the historical graphical replay/statistics application. Direct text/keyboard CLI From the CLI folder run: RUN_CLI.bat The CLI and graphical live companion use the same authoritative output.txt and session_evidence repository. ------------------------------------------------------------------------ 3. MAIN CLI WORKFLOW The main menu provides: - L — LIVE SESSION - S — RUN SHUFFLE ROBUSTNESS - Q — QUIT Before a new formal live session, the application can also ask whether a PREAMBLE should be recorded. A preamble is used when useful observed play exists before the formal research session begins. It records that visible chronology without silently treating those hands as part of the formal session’s bankroll/W/L/P statistics. ------------------------------------------------------------------------ 4. LIVE PLAY MODES FROZEN Frozen mode exposes the established deterministic Frozen reference during live play. The application supplies the Frozen wager/action prompts and records whether the observed wager/action matches the reference. The Frozen architecture remains the principal deterministic reference and is not modified by later Stat-Watching behaviour. PERSONAL Personal mode is intended to capture the human player’s own decisions without showing the Frozen wager/action recommendation before the choice. The operator plays by personal judgement. The application can still calculate the hidden Frozen reference for comparison/evidence, but the recommendation is suppressed before the human commits the choice. Current UAT note: Personal mode is implemented and remains under live UAT, including the post-commit Stat-Watching interaction. Treat unexpected behaviour as something to retain/report rather than manually rewriting evidence. HYBRID Hybrid mode keeps the Frozen reference visible while allowing the operator to make a different wager/action. The observed journey is the operator’s Hybrid journey. It must not later be relabelled as though the operator actually followed Frozen. Post-session source-supported counterfactuals may replay Frozen and Casual from the captured source. ------------------------------------------------------------------------ 5. PERSONAL MODE — OPTIONAL STAT-WATCHING SECOND OPINION The newest Personal-mode feature deliberately avoids influencing the human’s original decision. The sequence is: 1. The human decides and commits the wager or play action. 2. The application compares that committed choice with the hidden Frozen reference. 3. If the human has overridden Frozen, the application may offer: - See Stat-Watching Casual’s wager? [Y/N] - See Stat-Watching Casual’s mindset? [Y/N] - or, for a play decision, the equivalent Stat-Watching action/mindset questions. 4. The reveal happens only after the human decision has been committed. This preserves the Personal decision as an independently made human choice. Stat-Watching Casual is not a learning AI. Its rules do not rewrite themselves because a previous double, hit, stand or wager won or lost. For example, it does not learn: “Last time I doubled this situation I lost, so I will refuse the double next time.” Instead it observes a frozen set of currently visible signals. ------------------------------------------------------------------------ 6. WHAT STAT-WATCHING CASUAL OBSERVES Stat-Watching Casual is an exploratory deterministic behavioural counterfactual. Its current observational style includes short-window information such as: - recent completed-hand W/L/P results; - recent visible card mix; - concentration of low cards; - relative lack or abundance of visible ten-value cards; - short win/loss streak information; - bankroll/trend information; - previously revealed dealer-hole-card observations where the relevant rule permits them. Its principal rolling recent-hand observation is limited rather than an unlimited memory. A history such as: W W L P W W does not become a learned sequence prediction. The active recent window rolls forward, older information falls away, and the outcome counts are only one ingredient in the frozen trend logic. Stat-Watching cannot use the current hidden dealer hole card or future cards. A wager is chosen before the current deal, so a current dealer-hole-card hunch cannot retroactively influence that wager. The policy remains deterministic: same legitimately visible state + same frozen rules = same recommendation. V9.2.17 BOUNDED FIVE-HAND WORKING MEMORY The recent visible evidence is deliberately treated as a small human-style working-memory faculty rather than exhaustive table analysis. The design principle is: NORMAL PLAY FIRST -> RECENT OBSERVATIONS SIT IN MEMORY -> ONLY AN UNUSUALLY CONSPICUOUS SIGNAL MAY OVERRIDE NORMAL INSTINCT Sometimes nothing catches the Stat-Watcher’s attention and normal play simply continues. This bounded memory remains available to the Stat-Watching reconstruction even when direct CLI liveplay does not display the recent cards/streaks on screen. The operator display and the simulated player’s permitted internal memory are separate interfaces. Authoritative cards/results entered through the CLI supply the legitimately visible evidence from which the later deterministic Stat-Watching state is reconstructed. Absence from the CLI operator display therefore does not mean absence from the Stat-Watcher’s bounded simulated memory. V9.2.17 deliberately makes the newest action overrides rare: - Hard 12-16 against dealer 4/5/6: the five-card-memory scarcity override requires ZERO 10-value cards among the five recently remembered visible cards before that observation is conspicuous enough to override normal play. - Double opportunity on 10/11: reluctance caused by recent 10-value concentration requires FOUR OR FIVE of the five recently remembered visible cards to be 10-value before the ordinary Double can be overridden in favour of the ordinary Hit. Seeing only a few recent 10-value cards therefore does not routinely cause the player to reject Double opportunities, and the hard 12-16 rule is not intended to make the player repeatedly overthink dealer high-card outcomes. OBSERVATION DOES NOT AUTOMATICALLY EQUAL ACTION. The pre-existing revealed dealer-hole-card hunch remains a separate frozen behaviour. These V9.2.17 additions do not turn Stat-Watching into an exhaustive card-analysis or card-counting engine. ------------------------------------------------------------------------ 7. RECENT-HAND HISTORY IN PERSONAL MODE Personal mode can offer access to recent table/session history. Recent-table-hand history is hidden by default. If requested, it is shown before the wager, so the request and information can legitimately be part of the human’s pre-wager decision context. The recent window is user-selectable from the previous 1 to 5 committed hands in the current session. Matching-hand/history information that depends on the current starting cards is available only after those starting cards are known and before the player action. This timing is deliberate: information must not be revealed after the decision it could have influenced. ------------------------------------------------------------------------ 8. PREAMBLE CAPTURE Choose preamble capture when there are observable hands before the intended formal Hand 1 and retaining that context is scientifically useful. A preamble: - has its own blackjack_preamble_.txt evidence report; - records observed hands/cards and observed shuffle boundaries; - may be Personal or Frozen; - can be linked to the following formal session; - is excluded from that formal session’s W/L/P, exposure, bankroll and ledger statistics; - can support a separately labelled PREAMBLE_START replay/counterfactual. Important boundary: A preamble is not a spare supply of cards to append to the end of an exhausted formal-start replay. A formal-start replay that exhausts its retained source must stop at source exhaustion. A PREAMBLE_START replay is a separate replay basis beginning at the first recorded preamble card. ------------------------------------------------------------------------ 9. RECORDING A HAND The live companion is designed to capture what is actually observed on the external blackjack game. The workflow records the initial player/dealer cards, subsequent player cards, dealer hole/draw cards when revealed, wager/action information, result and bankroll movement. Validation is used where the retained information makes validation possible. Important operating principles: - enter cards in the requested role/order; - record suits when requested; - record a visible shuffle when it actually occurs; - do not infer an unseen shuffle or shoe penetration; - enter the updated platform balance after the external game has settled the hand; - use the hand review/amendment path if an entry is known to be wrong; - never invent an unobserved card merely to make a result reconcile. The evidence system distinguishes a genuinely completed short journey (for example bankroll/table-minimum termination) from an evidence stream that is genuinely incomplete. Fewer than 30 hands does not automatically mean “partial.” ------------------------------------------------------------------------ 10. BANKROLL BASIS The programme can map the external platform balance onto a research-equivalent bankroll. The protected platform offset/depletion floor is session-specific. Research affordability for wagers, doubles and splits uses the research-equivalent bankroll rather than treating the protected offset as playable research capital. The session evidence records the platform basis and the research-equivalent start/final/peak/trough values. ------------------------------------------------------------------------ 11. SHUFFLES AND CARD CHRONOLOGY Only observed shuffle boundaries are recorded as observed shuffles. If no visible shuffle establishes the shoe origin, the application must not claim an absolute penetration percentage. It may report observational counts such as cards since the latest observed shuffle/start. The chronological card dataset is important evidence. Post-session replays consume the retained source according to their declared replay basis and must not invent cards after source exhaustion. ------------------------------------------------------------------------ 12. END OF SESSION At the end of a live session the application writes/updates: - cumulative output.txt; - a dedicated session_evidence\blackjack_live_session_.txt; - ledger/session statistics and retained audit information. The session evidence, rather than a later graphical interpretation, is the authority for what was actually captured. ------------------------------------------------------------------------ 13. POST-SESSION S ANALYSIS From the main CLI workflow, S runs the post-session shuffle/robustness analysis for the pending session when the required source is available. This creates: session_evidence\blackjack_shuffle_analysis_.txt and appends the relevant analysis to output.txt. The established post-session analysis includes source-bounded Frozen/Casual replay work and the exploratory Stat-Watching Casual analysis. The shuffle methods are deterministic research proxies. They must not be described as reproducing a proprietary casino shuffler. Source exhaustion remains a valid boundary: the engine does not fabricate extra cards merely to force a 30-hand result. ------------------------------------------------------------------------ 14. STAT-WATCHING: CHOSEN EXIT VS STAY COUNTERFACTUAL For source-supported Stat-Watching sessions, the experiment can retain two related outcomes: Chosen behavioural path The Stat-Watching personality is allowed to use its deterministic walk-away rule. Stay-at-table counterfactual The same Stat-Watching personality is replayed with the exit decision disabled. The stay version does not become Frozen. It keeps the same Stat-Watching wager, hunch and play style; only the walk-away trigger is disabled. This allows later comparison of whether the behavioural walk-away decision helped or hurt on the retained source. ------------------------------------------------------------------------ 15. HISTORICAL REPLAY / STATS CORNER RUN_REPLAY.bat opens the historical graphical application. It provides retained replay/Memory Lane/statistics views based on authoritative evidence rather than creating a separate GUI-local ledger. The Stat-Watching graph shows source-supported session outcomes such as: - chosen/walk-away final bankroll; - if-always-stayed final bankroll; - cumulative chosen-exit P/L; - cumulative stay P/L; - walk-away effect; - basis-matched Frozen comparison where evidence supports it. For readability, the design supports a maximum of five eligible Stat-Watching sessions per graph. Further groups are placed below as additional full-size graphs in the scrollable view rather than squeezing more bars into the original chart. A PRE session can carry a compact pre-hand count beneath its session label. Unavailable or non-source-supported sessions remain unavailable; the GUI must not manufacture a bar to make the sequence look complete. Session stories are evidence-grounded behavioural interpretations of what may have caught the simulated player’s attention. Their wording can vary naturally between journeys, but the underlying numeric evidence and implemented policy must not be altered merely to make a retrospective story more persuasive. GUI v15.10.59 also carries the final Recent Player Experience presentation in both Historical Replay and Live Gameplay. Beneath the existing W/L/P, wager and source marker, the row labelled "NUMBER PLAYER CARDS ON WIN" shows 3 for a winning hand completed with exactly three player cards, 4+ for a winning hand completed with four or more player cards, and — where that comparison is not applicable. This is a presentation/history aid only; it does not change wagering, action, replay or evidence logic. Live table spacing retains room for split hands while preserving the scrollable CLI instruction/transcript area. Story presentation introduced in GUI v15.10.44 adds the chosen-path profit/loss relative to the £100 research start in each story title and bolds explicit Hand X references for scanning. These are presentation-only changes: they do not change Stat-Watching behaviour, replay outcomes or retained evidence. ------------------------------------------------------------------------ 16. PUBLICATION PLATE WORKFLOW A completed session is not automatically a completed publication plate. The application maintains a publication/preflight workflow. Before plate creation, the required evidence must be present and readable. Normally required: - output.txt; - dedicated live-session report; - dedicated shuffle-analysis report; - session_evidence\Sessionplate_structure.zip; - immediately previous accepted Session plate for Session 2 onward. When applicable also provide: - linked preamble report; - dedicated observed-reconstruction correction/addendum. Session 1 exception Session 1 has no previous Session plate. Its absence must not trigger a missing-file stop, and a Session 0 plate must never be invented or requested. Sessionplate_structure.zip supplies structural/presentation precedent. The structural reference pack is presentation precedent only. Current-session evidence remains the scientific authority. Publication legibility is a hard presentation requirement. Dense tables, decimal points, currency symbols, percentages, footnotes and multi-column values must remain comfortably readable at normal full-plate viewing size. A final visual check must explicitly inspect for ambiguous decimals, cramped values, clipping, weak contrast and column misalignment. Legibility work must not alter, round, reinterpret or replace evidence. Universal supporting/reference plates use future-proof wording such as “Applies to all Session Scorecards” rather than a fixed current session range. The universal “How to Read the Session Scorecards” and separate “Shuffle Robustness Table — Field Guide” are explanatory publication aids and do not replace current-session evidence. ------------------------------------------------------------------------ 17. SESSION PLATE STRUCTURE REFERENCE session_evidence\Sessionplate_structure.zip is a permanent working reference, not an obsolete download ZIP. It contains the accepted structural guidance/reference plates used when a new plate is constructed. Broadly: - genuine observed preamble -> use the preamble/entry-context structural family; - no observed preamble -> use the no-preamble structural family; - genuinely new scenario -> preserve the accepted visual family while constructing an evidence-appropriate middle section. Reference plates must never donate their numbers, zeros, N/A values or session-specific claims to a new session. ------------------------------------------------------------------------ 18. IMPORTANT SCIENTIFIC BOUNDARIES The application is intentionally conservative about evidence. Do not: - invent missing cards; - infer an unseen shuffle; - extend an exhausted source with synthetic cards and call it observed; - copy a value from another session to fill a gap; - turn an N/A into zero; - treat a structural reference plate as scientific evidence for the current session; - describe Stat-Watching as an adaptive learner; - treat synthetic shuffle results as observed casino outcomes; - treat a Personal or Hybrid journey as Frozen merely because Frozen was calculated in parallel. Where evidence is unavailable, the correct result may be N/A, SOURCE_EXHAUSTED, or another explicit evidence boundary. ------------------------------------------------------------------------ 19. FILES THAT MATTER MOST CLI authoritative data output.txt Cumulative project/session ledger. session_evidence Dedicated live-session, shuffle, preamble, correction/addendum and plate-structure evidence. CLI Safety copies of cumulative output. CLI_audit Historical provenance, lineage, hashes, audits and workflow records. Preserve. GUI The currently aligned graphical/replay build for this README is GUI v15.10.59. The GUI folder should normally contain only the current accepted GUI package files, including: - BlackjackSessionReplay.jar - BlackjackSessionReplay.java - RUN_LIVE_GUI_UAT.bat - RUN_REPLAY.bat - current consolidated GUI UAT/release history - current release audit Do not create a second output.txt in the GUI folder. ------------------------------------------------------------------------ 20. CURRENT UAT POSITION The programme has multiple mature/retained layers, but not every newly added interaction has received the same amount of live UAT. In particular, the newest Personal-mode Stat-Watching post-commit reveal should presently be treated as UAT functionality. The intended invariant is already clear: Human decision first -> commit it -> optional Stat-Watching comparison afterwards. If live UAT exposes a discrepancy, preserve the session/evidence and correct the implementation rather than retrospectively pretending the interaction behaved as intended. The Frozen architecture, existing Casual counterfactual and Stat-Watching policy should remain isolated from one another unless an explicit future research change is deliberately designed and versioned. At V9.2.18 the Stat-Watching bounded-memory/rare-override behaviour remains the intended behavioural baseline inherited unchanged from V9.2.17. Do not continue adding interpretations merely because more table information could theoretically be analysed. Personal Mode remains the principal live-UAT area. Minor retrospective story/presentation wording may be audited separately from behavioural policy. If Personal-mode UAT exposes a significant functional problem, preserve the affected evidence and make the smallest explicit versioned correction rather than silently changing the frozen behavioural baseline. ------------------------------------------------------------------------ 21. QUICK START — FIRST PERSONAL SESSION 1. Ensure the latest CLI and GUI packages are extracted and the folders are clean. 2. Start RUN_LIVE_GUI_UAT.bat. 3. If there are relevant observed hands before formal Hand 1, decide whether to capture a preamble. 4. Start the formal session and select PERSONAL. 5. Make the wager using your own judgement. 6. If offered recent-hand history before wagering, request it only if you genuinely want to use it. 7. Enter the observed cards/results as the external game proceeds. 8. Make your own play decisions without seeing Frozen first. 9. If your committed choice differs from hidden Frozen, optionally view Stat-Watching’s recommendation and/or mindset after commitment. 10. Continue until the session reaches its legitimate endpoint. 11. Retain the generated live-session evidence. 12. Run S for the post-session analysis when appropriate. 13. Retain the dedicated shuffle-analysis evidence. 14. Complete the publication plate workflow before the next session where the plate gate requires it. 15. Use RUN_REPLAY.bat to inspect the retained journey and accumulated statistics. ------------------------------------------------------------------------ 22. FINAL OPERATOR PRINCIPLE Record what happened. Do not make the evidence look cleaner than reality. The value of the programme comes from keeping the observed human journey, Frozen reference, Casual counterfactual, Stat-Watching counterfactual, preamble context and synthetic robustness analyses clearly separated while allowing them to be compared on explicitly declared bases. That separation is what makes later replay, audit and comparison meaningful. ------------------------------------------------------------------------ END OF APPLICATION README