settled-reach/docs/sprints/sprint-7/server.md

# Sprint 7: Talk — Server Tasks

**Goal:** Complete interaction UI layer and activate basic dialogue system with NPC conversations.

**Branch:** `server`
**Agents:** Dudley (dev), Tyre (arch), Hoshe (QA)

## Carry-over from Sprint 6

None — all Sprint 6 server tickets completed.

## New Tickets

| # | Title | Blocked by |
|---|-------|------------|
| #423 | Cognitive delay system for fog recognition | — |
| #308 | Line pool format specification | — |
| #326 | YAML content loader — hot-reload for previewer | #308 |
| #442 | InteractionMemory KG schema design | — |
| #426 | ListeningFocus — eavesdrop positioning via stationary_ticks | — |

Use `db/connectors/ticket show <id>` for full details.

## Key Decisions

- `decisions/perception.md` — D-060 (cognitive delay), D-059 (fog entity visualization)
- `decisions/content.md` — D-028 (dialogue architecture), D-035 (tag taxonomy)
- `decisions/architecture.md` — D-041 (knowledge graph data model)
- `decisions/scope.md` — D-053 (movement stance system)

## Notes

### #423: Cognitive delay system for fog recognition
**What exists:**
- `server/src/perception/observation.rs` — observation event system
- `server/src/knowledge/events.rs` — KnowledgeEvent and KnowledgeEventQueue
- `server/src/knowledge/graph.rs` — KnowledgeGraph component with confidence tiers
- `server/src/perception/interpretation.rs` — entity recognition logic

**What the ticket needs:**
- New `CognitiveDelay` component to track pending recognition timers (entity_id, delay_until_tick, trigger_type)
- Recognition trigger types: normal (0.6s base), urgent (0.3s on observe_anomaly)
- System that drains cognitive delay queue and emits KnowledgeEvent when delay expires
- Integration point: observation.rs emits sound/perception events → cognitive delay system buffers them → emits delayed KnowledgeEvent after timer
- Client-facing: ObserverSnapshot receives pending_recognitions list (entity positions in fog without identity until delay expires)

**Integration points:**
- Blocks client #431 (fog entity visualization) — client needs pending_recognitions data
- Uses existing KnowledgeEvent pipeline
- Monologue system should fire DURING delay, not after (monologue IS the recognition per D-060)

**Gotchas:**
- Delay values are tunable constants — start with D-060 values (0.6s base, 0.3s urgent), expect playtesting adjustments
- Urgent context detection: observe_anomaly trigger from monologue system (already exists in server/src/simulation/monologue.rs)
- Must respect tick-based timing (10 ticks/sec per D-031) — 0.6s = 6 ticks delay

### #308: Line pool format specification
**What exists:**
- `content/` directory skeleton (created in Sprint 5, #385)
- `content/_schema/` — YAML schema definitions (#386)
- `content/global/enums/` — D-035 enum files (access, trust, situation, topic, mood)
- D-035 tag taxonomy in decisions/content.md
- D-028 dialogue architecture (4-layer filtering)

**What the ticket needs:**
- Formal specification document at `docs/architecture/line-pool-format.md`
- Define YAML structure for dialogue files (structural tags: id, text, role, access, trust, situation; selection tags: topic, mood, tags)
- Define YAML structure for monologue files (adds: character, trigger, prerequisite)
- File naming conventions: `dialogue.yaml`, `monologue-smuggler.yaml`, `monologue-detective.yaml`
- Directory structure: `content/campaigns/{campaign}/systems/{system}/{location}/dialogue.yaml`
- Tag validation rules (access is required list, trust is required enum, situation is optional list, etc.)
- ID format specification: `{template}_{d|m|e}_{###}` for machine-parseability

**Integration points:**
- Blocks #326 (YAML content loader needs this spec)
- References D-035 (tag taxonomy), D-028 (4-layer dialogue architecture), D-032 (separate monologue pools)
- Used by copy team for authoring

**Gotchas:**
- This is a specification document, not code — no Rust implementation in this ticket
- Must be clear enough for copy team (Mellanie, Paula) to author against
- Define how prerequisite maps to KG state (which confidence levels gate which lines)

### #326: YAML content loader — hot-reload for previewer
**What exists:**
- `server/src/content/` module directory (exists but minimal)
- Content directory structure (#385 done)
- YAML schema definitions (#386 done)
- `make validate-content` CLI (#392 done)

**What the ticket needs:**
- Rust system parsing dialogue.yaml and monologue.yaml files into in-memory LinePool structures
- LinePool struct: indexed by tags (BTreeMap for determinism per D-041)
- Hot-reload capability: watch content files, reload on change (for line previewer authoring workflow)
- Integration with existing content loading infrastructure
- Query API: `query_lines(access_tier, situation, topic, mood) -> Vec<Line>`
- Load at startup, reload on file change

**Integration points:**
- Blocked by #308 (needs format spec)
- Blocks line previewer workflow (deferred to future sprint, but hot-reload is the foundation)
- Blocks #305 (dialogue selection pipeline, future sprint)
- Uses existing content/ directory structure
- Must support D-028 4-layer filtering architecture

**Gotchas:**
- Use BTreeMap not HashMap (D-041 determinism requirement)
- Hot-reload is dev-only feature (not production runtime)
- File watching: use notify crate or simple timestamp polling
- Pool indexing strategy: pre-index by access tier (hard filter) for performance

### #442: InteractionMemory KG schema design
**What exists:**
- `server/src/knowledge/types.rs` — KnowledgeGraph, EntityKnowledge, FactKnowledge
- `server/src/knowledge/graph.rs` — knowledge update systems
- D-041 knowledge graph data model
- D-064 walk-away KG recording requirement

**What the ticket needs:**
- Design FactKnowledge schema extension for interaction tracking
- FactId format for interaction memory: `interaction_{entity_a}_{entity_b}_{timestamp}`
- Interaction state enum: Initiated, Completed, WalkedAway, Confrontation
- Metadata fields: conversation_topic, confrontation_flag, walk_away_tick, incomplete_flag
- Query patterns: "did I start talking to X?", "did I walk away mid-confrontation?", "when did I last talk to X?"
- Integration with dialogue system (future): dialogue start → emit Initiated fact, dialogue end → update to Completed, walk-away → update to WalkedAway

**Integration points:**
- Extends D-041 KnowledgeGraph FactKnowledge map
- Used by walk-away mechanic (#427, future sprint)
- Used by confrontation system (D-063, D-064)
- Queryable by monologue system (affects future dialogue triggers)

**Gotchas:**
- This is schema design, not full implementation — define the data structure and query API
- Document in `docs/architecture/interaction-memory-schema.md`
- Must align with D-041 BTreeMap<FactId, FactKnowledge> pattern
- Interaction memory is per-character (player character only for v0.1, NPCs in future)

### #426: ListeningFocus — eavesdrop positioning via stationary_ticks
**What exists:**
- `server/src/simulation/movement.rs` — Velocity, Position components, movement systems
- `server/src/simulation/stance.rs` — MovementStance component (Sprint/Walk/Careful/Crouch)
- D-053 stance system with stationary detection
- TilePresence component (posture layers)

**What the ticket needs:**
- New `ListeningFocus` component (stationary_ticks: u32, eavesdrop_target: Option<StableId>)
- System that increments stationary_ticks when Velocity is zero
- Eavesdrop threshold: 30 ticks (~3 seconds at 10 tps) of being stationary
- Integration with perception: when stationary_ticks > threshold AND in range of conversation → boost sound perception range
- Reset stationary_ticks to 0 on any movement

**Integration points:**
- Builds on D-053 stance system (Careful stance might reduce eavesdrop threshold)
- Uses existing sound propagation system (D-018 three-range sound model)
- Affects observation events (perception/observation.rs)

**Gotchas:**
- Eavesdrop is not automatic — requires deliberate positioning (player must stop moving)
- Stationary in Sprint stance doesn't trigger eavesdrop (too high-alert, not listening)
- Position must be within ~3-5 tiles of conversation source
- Sound propagation already exists; this ticket adds positioning bonus

## Dependency Chain

```
#308 (line pool spec) → #326 (YAML loader)
#423 (cognitive delay) → standalone, feeds client #431
#442 (InteractionMemory schema) → standalone, design document
#426 (ListeningFocus) → standalone, positioning mechanic
```

## PR Workflow

When ready to submit, create a PR with `tea` CLI. All flags are required to avoid TTY prompts:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(server): Sprint 7 — cognitive delay, line pool spec, YAML loader, interaction memory, eavesdrop" --description "See docs/sprints/sprint-7/server.md" --base main --head server
```