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

Sprint 3: Know — Server Tasks

Goal: Player character can observe NPCs, track their knowledge, and interact with the environment through a working observation event pipeline.

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

Tickets

#	Title	Blocked by
#86	Core NPC components	—
#87	Relationship system	—
#88	Daily routine system	#25 (done)
#237	Tile-based A* pathfinding	#236 (done)
#238	NPC path following and movement	#237
#239	Observation event generator	—

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

Key Decisions

• decisions/content.md — D-024 (10-axis NPC model), D-034 (THE FRIEND pattern), D-035 (dialogue tag taxonomy)
• decisions/architecture.md — D-041 (Knowledge Graph), D-026 (simulation tiers), D-030 (testability), D-031 (time system)
• decisions/perception.md — D-011 (fog/perception), D-016 (internal monologue), D-017 (perception modes)

Notes

NPC foundation tickets (#86, #87, #88):

• #86 (Core NPC components): The Npc marker component and basic axes already exist in server/src/npc/mod.rs (Want, Secret, Relationships, ToleranceThreshold, DailyRoutine, InformationInventory, Contentment, plus supporting axes). This ticket extends those component definitions to match the full D-024 10-axis model with proper field types. DailyRoutine needs to become a structured schedule with time-based location transitions.
• #87 (Relationship system): The Relationships component exists as a stub. Implement the RelationshipGraph resource (per D-024) for NPC-to-NPC connections with trust/history metadata. Keep per-NPC relationship slots (3 key relationships) for Active-tier NPCs. This is separate from the KnowledgeGraph (what entities know) — this is what entities feel.
• #88 (Daily routine system): Build on SimulationTime (done in #25, server/src/simulation/time.rs). DailyRoutine component stores location schedule with day-phase transitions (Morning/Afternoon/Evening/Night per D-031). NPCs transition between locations at phase boundaries. Foundation for routine deviation detection (#243, Sprint 4+).

Pathfinding tickets (#237, #238):

• #237 (Pathfinding): A* pathfinding over the WalkabilityMap (done in #236, server/src/simulation/movement.rs). Use the pathfinding crate. NPCs request paths between positions; system returns tile sequences. Output: PathRequest event + ComputedPath component. This blocks routine execution — NPCs can't move between routine locations without pathfinding.
• #238 (Path following): Per-tick NPC position updates along computed paths. Separate from pathfinding computation. Smooth interpolation between tiles (fractional TilePosition or separate VisualPosition component). Movement speed parameter. This is the execution system that makes NPCs actually walk.

Observation pipeline (#239):

• #239 (Observation event generator): The mechanical heart of the game per Gestalt. Compares ObserverSnapshot against character KnowledgeGraph to generate ObservationEvents. Trigger types: routine deviation, absence detection, social anomaly, new information, contradiction. Character-specific — same NPC behavior generates different events for smuggler vs detective. Foundation for monologue generation (#119, Sprint 4+).
• Existing foundation: server/src/perception/observation.rs already emits DirectObservation and LeftLOS events. This ticket adds the interpretation layer — detecting meaningful observations like routine deviations, not just visibility changes.
• Integration points: Reads KnowledgeGraph (Sprint 2, done), reads DailyRoutine (this sprint, #88), emits to a new ObservationEventQueue resource.

Dependency Chain

#86 (NPC components) → #239 (needs NPC profiles to compare against)
#87 (relationships)  → standalone, feeds NPC generation pipeline (#92, Sprint 4+)
#88 (routines)       → #239 (routine deviation requires routine data)
#237 (pathfinding)   → #238 (path following) → #101 (routine execution, Sprint 4+)
#239 (observation)   → #119 (monologue generation, Sprint 4+)

#86, #87, #237 can start immediately. #88 and #239 depend on completions but not each other.

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

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