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)
• 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:

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