DETERMINISTIC BLACKJACK LIVE COMPANION

Application README / Operator Guide

PROJECT-CLOSE RELEASE ENVIRONMENT — 17 September 2026
CLI backend: V9.2.52
Historical Replay / Stats: v15.10.209
Live Graphical Companion embedded in the accepted GUI JAR: 15.10.140

Status:
PROJECT CLOSED / UAT COMPLETE / RELEASED / FROZEN.
CLI/evidence backend: V9.2.52 (publication-request text lock only; blackjack/research calculations unchanged).
Historical Replay v15.10.209 retains the accepted v15.10.198 presentation and repairs only the Replay → LIVE PLAY launcher route.
Live Graphical Companion remains the accepted embedded live implementation.
Quick Input reconstructed-card state-reset UAT: PASS / VERIFIED.

------------------------------------------------------------------------

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 and
counterfactual analysis.

There are two user-facing graphical applications:

- Live Graphical Companion — used while a real/observed blackjack session is
  being played.
- Historical Replay / Stats — 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 and replay layer over that authoritative CLI repository.

VERSION NOTE

The current GUI JAR contains Historical Replay v15.10.209 together with Live Graphical Companion v15.10.140. Replay → LIVE PLAY delegates to the same RUN_LIVE_GUI.bat route that is used for direct live launch, preserving the sibling CLI classpath/compile/cleanup lifecycle.

Replay-side work after the earlier release baseline was presentation/research
work only. The final Replay UAT confirmed normal-hand settlement visibility,
split-hand containment and child verdict visibility, and the pre-deal chip
presentation. These changes do not imply a change to the frozen CLI/backend
blackjack mechanism.

------------------------------------------------------------------------

2. STARTING THE APPLICATION

Graphical live play

From GUI\ run:

  RUN_LIVE_GUI.bat

This launches the released Live Graphical Companion entry point from
BlackjackSessionReplay.jar and uses the neighbouring CLI\ folder as the
authoritative working/data location.

Historical replay and statistics

From GUI\ run:

  RUN_REPLAY.bat

This launches BlackjackSessionReplay.jar and opens the historical graphical
replay/statistics application.

Direct text/keyboard CLI

From CLI\ run:

  RUN_CLI.bat

The release-audited V9.2.52 launcher performs the intended lifecycle:

  compile current source -> run CLI -> remove generated .class files on exit

The active CLI folder therefore does not need a permanent forest of loose
backend .class files.

------------------------------------------------------------------------

2A. POST-SESSION PUBLICATION HANDOFF

S generates the verified publication manifest, CHATGPT_SESSION_PUBLICATION_REQUEST.txt
and ChatGPT_SessionN_Publication_Handoff.zip. The request and ZIP are one inseparable
handoff and must be attached to ChatGPT together. The verified S manifest is the data
authority. Accepted plates and benchmark_visual.png are visual/publication authority
only. The publication request explicitly prohibits freeform redesign and requires the
established scorecard family plus applicable specialised component references.

------------------------------------------------------------------------

3. MAIN CLI WORKFLOW

The main menu provides:

- L — LIVE SESSION
- S — RUN SHUFFLE ROBUSTNESS / POST-SESSION ANALYSIS
- 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 Frozen wager/action prompts and records
whether the observed wager/action matches the reference.

Frozen remains the principal deterministic reference. Later behavioural or
AI layers do not rewrite Frozen.

PERSONAL

Personal mode captures the human player's own decisions without showing the
Frozen wager/action recommendation before the choice. The human commits first;
comparison/reveal may occur only afterwards where the implemented workflow
permits it.

Recent-table-hand history is hidden by default. When requested for wagering,
it is shown before the wager so it can legitimately form part of the human's
decision context. Matching-hand/history information dependent on the current
starting cards is available only after those starting cards are known and
before the play action.

Personal mode retains its established behavioural boundary. This preserves a clearly
marked area for person-specific presentation/decision-support refinement
without silently changing the frozen research architecture.

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 Frozen was actually
followed.

Post-session source-supported counterfactuals may replay Frozen and Casual
from the captured source.

------------------------------------------------------------------------

5. PERSONAL MODE — OPTIONAL STAT-WATCHING SECOND OPINION

The design avoids influencing the human's original decision.

Sequence:

1. Human decides and commits the wager or play action.
2. Application compares that committed choice with hidden Frozen.
3. Where applicable after an override, the application may offer the
   Stat-Watching Casual wager/action and/or mindset.
4. The reveal happens only after the human decision has been committed.

Stat-Watching Casual is not a learning AI. It does not change a future rule
because a previous double, hit, stand or wager won or lost.

It observes a frozen set of legitimately visible signals. Its rolling
short-window information may include recent W/L/P, visible-card mix,
ten-value/low-card concentration, short streaks, bankroll/trend information
and eligible previously revealed dealer-hole-card observations.

Its bounded recent-hand working memory is not an unlimited learned history.
The same legitimately visible state plus the same frozen rules produces the
same recommendation.

------------------------------------------------------------------------

6. PREAMBLE, CARD CHRONOLOGY AND SHUFFLES

A genuine preamble:

- has separate blackjack_preamble_<PREAMBLE_ID>.txt evidence;
- records observed hands/cards and observed shuffle boundaries;
- can be linked to the following formal session;
- is excluded from the formal session's W/L/P, exposure and bankroll
  statistics;
- can support a separately labelled PREAMBLE_START replay.

A preamble is not spare cards to append after an exhausted formal-start
replay. A formal-start replay that exhausts retained source must stop at
source exhaustion.

Only observed shuffle boundaries are recorded as observed shuffles. If no
visible shuffle establishes shoe origin, do not claim absolute penetration.
Do not infer unseen cards or an unseen shuffle.

------------------------------------------------------------------------

7. RECORDING AND EVIDENCE INTEGRITY

Record what was actually observed:

- initial player/dealer cards;
- subsequent player cards;
- dealer hole/draw cards when revealed;
- wagers/actions;
- result and bankroll movement;
- visible shuffle events;
- suits when known/requested.

Do not invent an unobserved card to force reconciliation.

Use the hand review/amendment route when an entry is known to be wrong.
Corrected evidence supersedes raw analytical output only to the explicitly
documented extent.

A legitimate declared AI_EXIT, BANKROLL/table-minimum, depletion or
behavioural exit can complete before 30 hands. Fewer than 30 hands therefore
does not automatically mean partial.

SOURCE_EXHAUSTED is an evidence boundary, not SOURCE-COMPLETE and not a
completed final P/L.

ZERO IS DATA. A displayed zero or N/A must be supported by the current
session; never copy it from another session or plate.

------------------------------------------------------------------------

8. 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 a protected offset as
playable research capital.

------------------------------------------------------------------------

9. END OF SESSION AND SELF-VERIFICATION

At the end of a live session the application writes/updates authoritative
session material including:

- CLI\output.txt
- CLI\session_evidence\blackjack_live_session_<SESSION_ID>.txt
- ledger/session statistics and retained audit information.

The retained session evidence, not a later graphical interpretation, is the
authority for what was captured.

The release design includes an end-of-session integrity gate that independently
cross-checks committed card count, cards since latest shuffle, sequential card
indices, hand count, W/L/P, exposure, bankroll path/final bankroll and related
session totals before third-party handover. Any discrepancy is a release/evidence
issue to investigate, not something to conceal through presentation.

------------------------------------------------------------------------

10. POST-SESSION S ANALYSIS

S performs the source-supported post-session shuffle/robustness analysis for
the pending session and creates:

  CLI\session_evidence\blackjack_shuffle_analysis_<SESSION_ID>.txt

Relevant analysis is also appended to output.txt.

Eligible S processing updates AIplayer.txt from authoritative/source-supported
completed-session evidence. The temporal boundary is strict:

  evidence through Session N -> available from Session N+1

The current verified V9.2.52 runtime reports:

  AIplayer.txt | evidence through Session 11 | available from Session 12

Shuffle methods are deterministic research proxies. Do not describe them as
reproducing a proprietary casino shuffler.

------------------------------------------------------------------------

11. STAT-WATCHING: CHOSEN EXIT VS STAY COUNTERFACTUAL

Where source-supported, two related outcomes may be retained:

Chosen behavioural path
  Stat-Watching may 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. Only the walk-away trigger is
disabled.

------------------------------------------------------------------------

12. ULTIMATE AI

Ultimate AI is a separate experimental decision layer. It does not replace or
modify Frozen.

It can weigh predeclared evidence layers including current-hand state,
legitimately visible short-term observations, completed-prior-session
repository evidence, bankroll/exposure context, eligible session similarity
and the Frozen recommendation.

Weak, isolated or conflicting signals defer to Frozen. Weighting/override
gates must be declared before the outcome they govern and must not be
retrospectively tuned.

AIplayer.txt is the cumulative repository. Current Session-12 readiness is
based on evidence through Session 11.

Ultimate AI is intentionally not exposed as an interactive live/replay player
in the current graphical comparison UI. That is a future controller-expansion
possibility, not a defect in the frozen current release.

------------------------------------------------------------------------

13. HISTORICAL REPLAY / STATS CORNER

RUN_REPLAY.bat opens Historical Replay v15.10.209.

It reads historical evidence from the authoritative CLI repository and does
not create a second GUI-local ledger.

Replay principles:

- source sequence/order is authoritative;
- no unsupported cards are invented after source exhaustion;
- blue source numbers represent source draw order;
- card pointer comparisons use source indices, not merely the visually
  rightmost card;
- an orange dealer-hole treatment identifies the dealer hole card;
- a known rank with unknown suit must remain unknown-suit rather than being
  assigned an invented suit.

Hybrid/Frozen replay uses two distinct concepts:

- publication Hybrid-detail counts are ACTION DECISION EVENTS anywhere within
  a hand and can exceed hand count;
- replay cumulative SAME/DIFFERENT counts are START-HAND card-state
  classifications.

Do not merge those two measures.

FINAL REPLAY PRESENTATION STATUS:
The v15.10.196 Replay layout passed final operator UAT. Normal settled hands
retain visible WIN/LOSS/PUSH space; split hands retain visible child verdicts;
dealer/player cards remain vertically contained; and pre-deal bankroll/on-table
chips are fully visible before dealing and disappear once dealing begins.

v15.10.196 additionally completes the accepted SAME-STATE ROBUSTNESS presentation:
the current-session panel reports MATCHING HAND OCCURRENCES for Frozen and Casual
and AVG P/L / MATCHED HAND for both controllers. The AVG P/L line was enlarged
slightly for readability only; its wording, values, evidence basis and controller
logic are unchanged.

The SAME STARTING STATE / H-N-L panels are descriptive research/presentation
context only. They do not alter the observed historical journey or controller
decisions.

------------------------------------------------------------------------

14. CURRENT GUI UAT ITEM — QUICK INPUT RESET

Before final third-party handover, verify the Live Graphical Companion's Quick
Input state after reconstructed-card entry.

Required behaviour:
Reconstructed cards used for one query/hand must not remain in Quick Input and
contaminate the next query/hand.

If the field persists incorrectly, make only the smallest GUI state-reset fix.
Do not change playability, evidence logic, Frozen/Stat/AI policy, cardstream,
settlement, Risk/Journey logic or accepted live-comment timing.

UAT RESULT: PASS / VERIFIED (14 September 2026). Reconstructed-card input was consumed cleanly and the workflow advanced to Result W/L/P without carrying reconstructed-card residue forward. No GUI code change was required after the successful verification.

------------------------------------------------------------------------

15. LIVE COMMENT / HYBRID NOTE PRINCIPLE

The primary requirement for in-play comments is that the operator can capture
a thought/comment at the correct moment without disrupting play.

Occasional overlap or imperfect operator classification between Reflection,
Prospective Intention, Other Criteria and similar categories is not an
evidence defect. Preserve the operator's chosen category and original text.

The accepted live-comment timing must not be changed merely to force cleaner
classification.

Historical Replay's major layout milestone was accepted at v15.10.196; subsequent targeted replay/presentation and provenance repairs continued through the current v15.10.209. Any later
presentation-only enhancement requires a new version and a new UAT cycle.

------------------------------------------------------------------------

16. PUBLICATION PLATE WORKFLOW

A completed session is not automatically a completed publication plate.

Current-session authoritative evidence supplies every current-session numeric
value. Previous accepted plates and benchmark_visual.png are presentation
precedent only.

Archetype selection is evidence-driven:

- COMPLETE-OBSERVED STANDARD — Session 7 canonical family.
- HYBRID / EVIDENCE-STATE STANDARD — Session 10 canonical family.
- create a third archetype only for a genuinely new evidence pattern.

Session 9 supplies the Hybrid-vs-Frozen analytical-detail module where
applicable; it is not the whole-plate archetype.

benchmark_visual.png is the editorial-finish visual benchmark only. It must
not donate numbers, zeros, N/A values or session-specific claims.

Publication gate:

  evidence PASS
  -> archetype selection PASS
  -> visual inheritance PASS
  -> numeric render audit PASS
  -> user visual acceptance

Freeze plate values into a pre-render verified manifest, render from that
manifest, then post-render audit every number and substantive label.

If a discrepancy is found, correct only the smallest affected segment and
re-audit. Confirm that unrelated evidence/layout was unchanged.

------------------------------------------------------------------------

17. RISK / JOURNEY INTERPRETATION

Risk and Journey are synthetic-reference profile scores. They are not
real-casino population percentiles, predictions or guarantees.

Scorecard values use the frozen/recovered programme equations. They must not
be reverse-engineered from a plate or invented to fill missing evidence.

------------------------------------------------------------------------

18. FILES THAT MATTER MOST

CLI\output.txt
  Cumulative project/session ledger.

CLI\AIplayer.txt
  Cumulative Ultimate-AI repository. Eligible completed Session N evidence
  becomes decision-available from Session N+1.

CLI\session_evidence\
  Dedicated live-session, shuffle, preamble, correction/addendum,
  publication/replay and plate-structure evidence.

CLI\backups\
  Safety copies of cumulative output.

CLI\docs_audit\
  Historical provenance, lineage, hashes, audits and workflow records.

CLI\tools\
  Separate audit/publication utilities.

GUI\BlackjackSessionReplay.jar
  Accepted graphical runtime containing Historical Replay and the embedded
  Live Graphical Companion.

Do not create another output.txt in GUI\.

------------------------------------------------------------------------

19. RELEASE / CHANGE CONTROL

The verified current CLI is V9.2.52.
The verified current Historical Replay / GUI JAR is v15.10.209, containing Live Graphical Companion v15.10.140.

Do not continue accumulating changes merely because an idea is interesting.
Classify new findings as:

- RELEASE-BLOCKING
- DOCUMENTATION
- FUTURE WORK

The applications are now frozen at project close. Any later functional or
presentation change requires a new version and a new UAT cycle.

When changing a frozen component:

- make the smallest possible correction;
- compile from the updated source;
- create a fresh replacement JAR/package where applicable;
- verify actual runtime version, not ZIP filename;
- keep loose .class files out of the clean GUI distribution;
- preserve evidence;
- record exactly what changed and confirm what did not change.

------------------------------------------------------------------------

20. FUTURE WORK — NON-EVIDENTIAL

Future-work concepts are retained as non-release research only:

1. Card Pointer & Source-Sequence Interpretation
   A supporting plate explaining blue source numbers, pointer drift, visually
   identical cards versus source alignment, dealer-hole marking, unknown
   suits and source exhaustion.

2. Practice Play / SME Sandbox
   A non-evidential practice environment that may replay an exact historical
   cardstream (with optional genuine preamble), let an SME make their own
   decisions, compare against supported controllers and optionally use
   declared shuffle methods/fixed seeds. It must never contaminate output.txt,
   session numbering, AIplayer.txt, accepted evidence, cumulative P/L or
   publication statistics.

3. Future Controller Expansion
   Potential interactive/live/replayable Stat-Watching and Ultimate-AI
   controllers. Their absence from the current live GUI is deliberate
   controller/evidence isolation, not an unfinished evidence defect.

4. Ultimate AI V2 — H/N/L Context Research
   Future/counterfactual research only; NOT implemented in the released engine.
   Ultimate AI V1 remains frozen. Any V2 study must preserve the temporal
   firewall, use only legitimately visible predecision evidence, exclude the
   current hidden dealer hole card until reveal, and validate any proposed
   H/N/L context layer independently before controller adoption.

------------------------------------------------------------------------

21. QUICK START — NEXT SESSION

1. Keep the verified CLI and GUI folders clean.
2. Start GUI\RUN_LIVE_GUI.bat for graphical live play, or CLI\RUN_CLI.bat
   for direct text/keyboard operation.
3. Decide whether a genuine preamble is required.
4. Select the intended live mode.
5. Record the observed session without inventing missing information.
6. Complete the legitimate journey endpoint.
7. Confirm the end-of-session integrity result/evidence.
8. Retain the dedicated live-session evidence.
9. Run S when appropriate.
10. Retain the shuffle-analysis evidence and AI repository update.
11. Complete the publication/evidence gate.
12. Use GUI\RUN_REPLAY.bat for historical inspection and accumulated stats.

For Session 12 specifically, Ultimate AI may use repository evidence through
Session 11; Session 12 evidence itself is not available to Session 12
decisions.

------------------------------------------------------------------------

22. FINAL OPERATOR PRINCIPLE

Record what happened.

Do not make the evidence look cleaner than reality.

Keep the observed human journey, Frozen reference, Fixed Casual
counterfactual, Stat-Watching counterfactual, Ultimate-AI layer, preamble
context and synthetic robustness analyses clearly separated while allowing
comparison only on explicitly declared bases.

That separation is what makes later replay, audit, publication and SME
handover meaningful.

------------------------------------------------------------------------

END OF APPLICATION README


DECISION PROVENANCE — IMPORTANT INTERPRETATION
----------------------------------------------
A value such as "Textbook / Frozen-Aligned: 23" counts the provenance of Frozen recommendations generated/displayed at decision events. It does not mean the observed Hybrid player followed Frozen 23 times. The separate Hybrid-vs-Frozen SAME/DIFFERENT comparison records whether the operator actually matched those recommendations. Decision-event count can exceed hand count because one hand may contain multiple action decisions.
