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

Sprint 17: Tell — Server Tasks

Goal: NPCs volunteer information unprompted and express personality through delivery; the player can read time and orientation at a glance from the insert HUD; POI infrastructure lands on the server.

Branch: server Agents: Dudley (simulation), Tyre (arch), Hoshe (QA)

Carry-over from Sprint 16

None. Sprint 16 server was 100% complete (4/4 done).

New Tickets

#	Title	Blocked by
#172	Layer 4: Unprompted disclosure	—
#173	Trait modifier system	—
#232	Create protocol versioning scheme	—
#148	POI data model	—
#149	POI discovery system	#148

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

Pre-Sprint Workshop

The Knowledge Flow & NPC Boundaries workshop runs before this sprint starts. Brief at docs/workshops/knowledge-flow-npc-boundaries/workshop-brief.md. Topics 1-3 directly inform #172 and #173:

• Topic 1: Knowledge grant mechanism — how dialogue grants facts to player KG
• Topic 2: NPC-to-NPC knowledge propagation (resolves Q-024)
• Topic 3: Unprompted disclosure design — how tell_state.rs connects to NPC KG

Wait for workshop decisions before starting #172. #148, #149, #232, and #173 can start in parallel.

Key Decisions

• decisions/content.md — D-028 (dialogue architecture, four relational layers), D-024 (NPC 10 axes), D-035 (tag taxonomy)
• decisions/architecture.md — D-041 (knowledge graph data model), D-010 (information boundaries), D-020 (engine architecture)
• decisions/perception.md — D-033 (entity color from relationship)

Open Questions to Resolve Early

• Q-024: Gossip propagation timing — Resolved by workshop. Feeds #172 implementation.
• Q-026: Contradiction detection — Resolved by workshop. Not directly Sprint 17, but workshop output constrains #172 design.

Notes

#172 — Layer 4: Unprompted disclosure

What exists: server/src/npc/tell_state.rs derives tell state from NPC axis values (Secret, ToleranceThreshold, Contentment, MoodState, Relationships). The TellState component tracks willingness to volunteer info. server/src/simulation/dialogue.rs has the D-028 four-layer pipeline (Layer 1: access tier, Layer 2: situation, Layer 3: trust-gated gossip). Layer 4 is unimplemented.

What to deliver: A system that checks NPC TellState + KnowledgeGraph to select information the NPC wants to volunteer. This is NOT player-initiated — the NPC decides to speak based on mood, trust, and what they know. Workshop Topic 3 will define the trigger conditions and candidate selection algorithm.

Key gap from audit: tell_state.rs does NOT query the NPC's own KnowledgeGraph. NPCs currently operate on ground truth. Workshop Topic 4 (NPC boundaries) will determine the minimum retrofit scope. At minimum, #172 needs tell_state.rs to read &KnowledgeGraph to know what the NPC can share.

Integration: Uses knowledge_grant on dialogue lines to give player new facts. Workshop Topic 1 defines the grant schema.

#173 — Trait modifier system

What exists: server/src/npc/mod.rs defines NPC components including personality axes per D-024. server/src/content/line_pool.rs has the IndexedDialogueLine struct with mood and tag fields. No trait-based line transformation exists.

What to deliver: A system where NPC personality traits reshape HOW lines are delivered, not per-trait scripts. Base lines exist in the pool; traits modify selection weight, delivery mood, or text variants. Workshop Topic 3 will clarify whether traits also affect WHAT is disclosed (filtering) or just delivery.

Gotcha: This must compose with Layer 3 (trust-gated, shipped Sprint 16) and Layer 4 (#172). Trait modifiers should operate as a scoring pass on the already-filtered candidate set, not as a separate filtering stage.

#232 — Create protocol versioning scheme

What exists: server/src/bridge/types.rs defines ObserverSnapshot and all message types. client/scripts/protocol/protocol.gd deserializes them. No version field exists on any message. MessagePack encoding per D-020.

What to deliver: Version field in protocol messages, compatibility checking, migration strategy. This is infrastructure — no gameplay change.

Standalone: No dependencies on other sprint tickets or workshop output.

#148 — POI data model

What exists: No POI system exists. The KnowledgeGraph has BTreeMap<FactId, FactKnowledge> for non-entity facts, but POIs are a new domain combining spatial position + knowledge.

What to deliver: PointOfInterest component with name, location, category, discovery source, visibility rules. This is an ECS component on map entities (bars, terminals, corridors, etc.). POIs feed into the minimap (#151, future) and insert HUD (#263, client Sprint 17).

Design question: Do POIs integrate with the knowledge graph as FactId entries (e.g., poi.the_last_shift), as entity knowledge via StableId, or as a separate system? Workshop Topic 1 touches this — POI discovery as knowledge flow.

#149 — POI discovery system

What exists: Nothing. Depends on #148 POI data model.

What to deliver: System for learning POIs via: character background (starting knowledge), NPC tips (dialogue grants), research (terminal interaction), physical discovery (walking into a location). Each discovery source maps to a KnowledgeSource variant and confidence level.

Integration: This IS knowledge flow — uses the same KnowledgeEventQueue pattern. New KnowledgeEventType variant for POI discovery. Connects to the grant mechanism (Workshop Topic 1).

Dependency Chain

#148 (POI data model) → #149 (POI discovery)
#172 (Unprompted disclosure) → blocked by workshop output
#173 (Trait modifiers) → standalone, parallel
#232 (Protocol versioning) → standalone, parallel

PR Workflow

When ready to submit, create a PR with tea CLI:

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(server): sprint 17 description" --description "body" --base main --head server