DETERMINISTIC BLACKJACK LIVE COMPANION Application README / Operator Guide Aligned builds: CLI V9.2.15-UAT / GUI v15.10.39 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 CLI\output.txt and CLI\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 but the newest post-commit Stat-Watching interaction is still being exercised in live UAT. 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. ------------------------------------------------------------------------ 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 CLI\output.txt; - a dedicated CLI\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: CLI\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. ------------------------------------------------------------------------ 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. ------------------------------------------------------------------------ 17. SESSION PLATE STRUCTURE REFERENCE CLI\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 CLI\output.txt Cumulative project/session ledger. CLI\session_evidence\ Dedicated live-session, shuffle, preamble, correction/addendum and plate-structure evidence. CLI\backups\ Safety copies of cumulative output. CLI\docs_audit\ Historical provenance, lineage, hashes, audits and workflow records. Preserve. GUI 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. ------------------------------------------------------------------------ 21. QUICK START — FIRST PERSONAL SESSION 1. Ensure the latest CLI and GUI packages are extracted and the folders are clean. 2. Start GUI\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