docs/STATE.md

Game State Machine

Deterministic rules the server enforces per session. Derived from PLAN §4 and §6.3. The model never decides act transitions — the server does, from these rules.

Session state object

{
  "session_id": "uuid",
  "turn": 0,
  "act": 1,
  "tones_seen_count": {},    // tone id -> times Lily has emitted it (tones_seen = its keys)
  "lexicon": {},             // tone id -> { guess: str, confidence: "red|amber|teal|green" }
  "notes_unlocked": [],      // note ids, in unlock order
  "empathy": 0,              // rises on caring/personal player questions (see below)
  "finale_played": false
}

• lexicon_size = count of lexicon entries with a non-empty guess.
• A tone is "active" this turn if its act_active <= act (see data/tones.json).
• Per-act tone cap (ACT_TONE_CAP in app/game.py): Lily's reply is trimmed to at most {Act I: 3, Act II: 5, Act III: 7} tones, so early phrases stay short and decodable. The prompt also asks for the matching count per act.
• empathy rises by 1 on any turn whose message hits a caring cue (EMPATHY_CUES) or a personal-question cue (PERSONAL_CUES) — heuristic in app/game.py, upgradable to Nemotron (Phase 6). Gates the empathy evidence notes.

Tone activation tiers (PLAN 6.3; Act I widened for learnability)

Tier	Active from	Tones	Count active
Act I start	act 1	◈ ◉ △ ∿ ♭ ♮ ← — ∎ □	10
Transition + Act II	act 2	+ ◇ ▽ ⌒ ≈ ▣ ◫ ♯ →	18
Act III	act 3	+ ◻ ↝ ≋ ↑ ↓ ∅	24

(In tones.json: act_active is 1, 2, or 3. time_now (∿) and act_stay (←) were promoted from Act II to Act I so Lily has enough vocabulary to be coherent early — she can ground feeling in the present and express intent ("you / stay / now"). The total still reaches 18 by Act II and 24 by Act III, so the later gates are unchanged.)

Act transitions

Evaluated after each turn. Forward-only; never regress.

Act I → Act II when BOTH:

• lexicon_size >= 5 (at least 5 lexicon entries — PLAN 4.2), AND
• at least max(5, len(ACT1_TONES) - 3) Act-I tones have been seen ≥ 2× (currently 7 of 10). Relaxed from "every Act-I tone twice" so widening Act I vocabulary doesn't stall progression; a couple of rarely-used tones are tolerated.

Act II → Act III when BOTH:

• len(tones_seen) >= 18 (18 of 27 tones seen — PLAN 4.3), AND
• note N07 (travel fund + passport) is unlocked.

Finale — within Act III, when len(tones_seen) == 27 AND N10 unlocked: the server may trigger the ending sequence (special: "finale"), set finale_played = true. After that, normal input is closed; the ending plays out (PLAN 4.5).

Note unlocks (see data/notes.json) — 15 notes

Re-evaluated every turn (act >= note.act always required):

• threshold notes unlock when lexicon_size >= unlock_value.
• topic notes unlock when the turn's topic_signal == note.unlock_value. Signals: music, university, relationship, family, travel. The family and travel signals also have server-side keyword fallbacks (FAMILY_CUES, TRAVEL_CUES) when the model misses them.
• empathy notes unlock when empathy >= unlock_value — the vulnerable backstory (friend's statement, mother's voicemail, wellbeing slip, the reconstructed evening), gated behind the detective showing care. Thresholds: N15=2, N12=3, N13=4, N14=5.
• N10 requires every tone seen (len(tones_seen) == 27, per PLAN 7.3) — special-cased.

Each note also carries found (investigation provenance, shown on the card), an optional hint ({tone_id, text} surfaced in the lexicon once that tone is heard — evidence helps decode the language), and summary/order (the "Her Story" tab assembles found summaries into a narrative, sequenced by order).

Atmosphere coupling (Phase 7)

Act drives the UI color temperature (Tailwind CSS vars on body[data-act]):

• Act I — warm cream / amber. Act II — gray-amber. Act III — near-monochrome cold.

Note: ambient background music was removed by design — only the tones make sound. The PLAN 6.5 "music EQ shift per act" no longer applies; color temperature is the remaining act-coupled atmosphere (Phase 7.2).