feat(server): Sprint 3 Know — NPC model, pathfinding, routines, observation events #14

2026-02-12T17:53:41+01:00

jpmschweitzer commented

2026-02-12 17:53:41 +01:00

Summary

Sprint 3 server implementation — 8 tickets delivering the NPC data model depth, pathfinding, daily routines, multi-entity sync, and observation event pipeline.

#86 Structured NPC data model — typed enums and integer types replacing stub string/f32 fields (D-010 determinism)
#87 Global RelationshipGraph resource — BTreeMap with tuple key (subject, target) for prefix queries and reverse lookups
#237 A* pathfinding — PathRequest/ComputedPath/PathBlocked components using pathfinding crate with cardinal-neighbor A* and manhattan heuristic
#238 NPC path following — MovementSpeed throttling, per-tick path advancement creating MoveIntent
#341 IPC error handling — DeserializationWithDump/MutexPoisoned variants, hex dump logging, graceful error classification
#88 Daily routine system — NpcPlugin with PreviousDayPhase resource, check_phase_transition issuing PathRequests at day-phase boundaries
#84 Multiple entity sync — 3 distinct NPCs (dock worker, field tech, guard) with full component bundles and relationship edges
#239 Observation event generator — RoutineDeviation, Absence, NewEntity triggers comparing visible snapshot against NPC routines and knowledge state

New files (5)

File	Ticket
`server/src/npc/relationships.rs`	#87
`server/src/npc/routine.rs`	#88
`server/src/simulation/pathfinding.rs`	#237
`server/src/simulation/path_follow.rs`	#238
`server/src/perception/interpretation.rs`	#239

System ordering (final)

receive_bridge_inputs → process_player_input → compute_paths → follow_paths
→ validate_movement → compute_observer_snapshot → emit_observation_events
→ generate_observation_events → process_knowledge_events → decay_knowledge
→ send_bridge_snapshot → cleanup_path_blocked → advance_tick
→ check_phase_transition

Test plan

152 tests passing (132 unit + 20 integration)
Zero compiler warnings
Clippy clean (no new warnings)
Manual smoke test with Godot client — 3 NPCs visible, pathfinding at phase transitions, observation events logged

🤖 Generated with Claude Code

## Summary Sprint 3 server implementation — 8 tickets delivering the NPC data model depth, pathfinding, daily routines, multi-entity sync, and observation event pipeline. - **#86** Structured NPC data model — typed enums and integer types replacing stub string/f32 fields (D-010 determinism) - **#87** Global RelationshipGraph resource — BTreeMap with tuple key `(subject, target)` for prefix queries and reverse lookups - **#237** A* pathfinding — PathRequest/ComputedPath/PathBlocked components using `pathfinding` crate with cardinal-neighbor A* and manhattan heuristic - **#238** NPC path following — MovementSpeed throttling, per-tick path advancement creating MoveIntent - **#341** IPC error handling — DeserializationWithDump/MutexPoisoned variants, hex dump logging, graceful error classification - **#88** Daily routine system — NpcPlugin with PreviousDayPhase resource, check_phase_transition issuing PathRequests at day-phase boundaries - **#84** Multiple entity sync — 3 distinct NPCs (dock worker, field tech, guard) with full component bundles and relationship edges - **#239** Observation event generator — RoutineDeviation, Absence, NewEntity triggers comparing visible snapshot against NPC routines and knowledge state ### New files (5) | File | Ticket | |------|--------| | `server/src/npc/relationships.rs` | #87 | | `server/src/npc/routine.rs` | #88 | | `server/src/simulation/pathfinding.rs` | #237 | | `server/src/simulation/path_follow.rs` | #238 | | `server/src/perception/interpretation.rs` | #239 | ### System ordering (final) ``` receive_bridge_inputs → process_player_input → compute_paths → follow_paths → validate_movement → compute_observer_snapshot → emit_observation_events → generate_observation_events → process_knowledge_events → decay_knowledge → send_bridge_snapshot → cleanup_path_blocked → advance_tick → check_phase_transition ``` ## Test plan - [x] 152 tests passing (132 unit + 20 integration) - [x] Zero compiler warnings - [x] Clippy clean (no new warnings) - [ ] Manual smoke test with Godot client — 3 NPCs visible, pathfinding at phase transitions, observation events logged 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jpmschweitzer added 6 commits 2026-02-12 17:53:41 +01:00

feat(npc): add structured NPC data model, relationships, and daily routines 3c04a0c568

Implements tickets #86, #87, #88 for Sprint 3:
- Replace stub string/f32 NPC fields with typed enums and integer
  types for D-010 determinism (WantKind, SecretSeverity, Skill, etc.)
- Add RelationshipGraph global resource with BTreeMap<(StableId,
  StableId), RelationshipEdge> for efficient prefix queries
- Add DailyRoutine with phase-based RoutineEntry and PreviousDayPhase
  resource for detecting day-phase transitions
- Create NpcPlugin that initializes relationship graph, day-phase
  tracking, and registers check_phase_transition system

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(simulation): add A* pathfinding and NPC path following f899624103

Implements tickets #237 and #238 for Sprint 3:
- Add pathfinding crate dependency for A* algorithm
- PathRequest component triggers compute_paths system which uses
  cardinal-neighbor A* with manhattan distance heuristic
- ComputedPath component with step navigation (next_step, advance,
  is_complete) and PathBlocked marker for no-route cases
- MovementSpeed component throttles NPC movement (ticks_per_step)
- follow_paths system advances NPCs along computed paths, creating
  MoveIntent per step; cleanup_path_blocked removes markers after
  one tick
- System ordering: input → compute_paths → follow_paths →
  validate_movement → cleanup_path_blocked → advance_tick

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(bridge): add error variants and diagnostic logging for IPC f186cec264

Implements ticket #341 for Sprint 3:
- Add DeserializationWithDump and MutexPoisoned variants to BridgeError
- Replace .expect("mutex poisoned") with graceful error propagation
  in LocalBridge and TcpBridge (4 locations)
- Log first 256 bytes as hex dump on deserialization failure for
  debugging malformed payloads
- Classify errors in receive_bridge_inputs: BrokenPipe/ConnectionReset
  → clean shutdown, MutexPoisoned → shutdown, DeserializationWithDump
  → skip frame (recoverable)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(simulation): spawn 3 NPCs with full component bundles 0b599ed662

Implements ticket #84 for Sprint 3:
- Replace single bare NPC with 3 distinct NPCs: dock worker (16,13)
  with full 4-phase routine and MovementSpeed(2), field tech (14,18)
  with partial routine, stationary guard (18,14) with no routine
- Register all entities (player + 3 NPCs) in EntityRegistry
- Populate RelationshipGraph with colleague and rival edges
- Add NpcPlugin to app for routine system registration
- Add multi-entity visibility tests: 3 NPCs in LOS all visible,
  NPC behind wall excluded from snapshot

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat(perception): add observation event generator 9c3c32e854

Implements ticket #239 for Sprint 3:
- ObservationTrigger enum: RoutineDeviation (NPC not at expected
  routine location), Absence (expected location visible but NPC
  missing), NewEntity (unknown entity in LOS)
- ObservationEventQueue resource with push/drain/len/is_empty
- generate_observation_events system runs after emit_observation_events
  but before process_knowledge_events so it can compare current
  snapshot against previous-tick knowledge state
- Populate PerceptionPlugin with ObservationEventQueue resource and
  system registration with correct ordering constraints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore(meta): update changelog 03884164b3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jpmschweitzer commented

2026-02-12 18:13:41 +01:00

Dual-Agent Review: server -> main

Hoshe (Code Quality): APPROVE

Well-tested, production-ready code. 33 new tests, all passing. Integer types for determinism, proper error handling, no security concerns. Four minor suggestions (field validation, defensive assertions) — none are blockers.

#	File	Severity	Issue
1	`simulation/path_follow.rs:~60`	suggestion	MovementSpeed counter mutates unnecessarily on final step
2	`npc/mod.rs:~12-77`	suggestion	Public component fields lack validation of documented ranges (1-10, 0-100)
3	`perception/interpretation.rs:~90-105`	suggestion	Full knowledge graph iteration every tick — fine for 15 NPCs, add threshold assert
4	`simulation/pathfinding.rs:~85-90`	suggestion	manhattan_distance returning u32::MAX on z-mismatch — add comment for future z-level work

Tyre (Architecture): REQUEST_CHANGES

#	File	Severity	Issue
1	`npc/relationships.rs`	critical	Global RelationshipGraph resource doesn't respect information boundaries (D-009/D-010). Add a TODO comment acknowledging this as a v0.1 limitation needing per-observer projection for MP.
2	`npc/mod.rs:27-28`	critical	`check_phase_transition` runs `.after(advance_tick)` — PathRequests issued after `compute_paths` already ran this frame, causing a one-frame delay before NPCs start moving. Fix: change ordering to `.before(pathfinding::compute_paths)` so PathRequests are picked up same frame.
3	`perception/interpretation.rs:69-72`	critical	Comment says "runs after knowledge events are processed" but actual ordering (PerceptionPlugin) is `.before(process_knowledge_events)`. The behavior is correct — you WANT to check against previous tick's knowledge to detect NewEntity. Fix the comment to match reality.
4	`simulation/pathfinding.rs`	warning	Cardinal-only (4-dir) movement — document as deliberate v0.1 choice
5	`perception/interpretation.rs:~150-185`	warning	Absence detection iterates all known NPCs every tick — scales poorly past v0.1
6	`main.rs:~59-175`	warning	Hardcoded test NPCs in production binary — consider feature flag or examples/
7	`Cargo.toml`	suggestion	Pin `pathfinding = "4.11"` for determinism guarantees

Verdict: CHANGES REQUESTED

Three fixes needed before merge:

Add TODO comment on RelationshipGraph about MP boundary limitation
Fix routine system ordering: .before(compute_paths) instead of .after(advance_tick)
Fix stale comment in interpretation.rs to match actual (correct) ordering

## Dual-Agent Review: server -> main ### Hoshe (Code Quality): APPROVE Well-tested, production-ready code. 33 new tests, all passing. Integer types for determinism, proper error handling, no security concerns. Four minor suggestions (field validation, defensive assertions) — none are blockers. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `simulation/path_follow.rs:~60` | suggestion | MovementSpeed counter mutates unnecessarily on final step | | 2 | `npc/mod.rs:~12-77` | suggestion | Public component fields lack validation of documented ranges (1-10, 0-100) | | 3 | `perception/interpretation.rs:~90-105` | suggestion | Full knowledge graph iteration every tick — fine for 15 NPCs, add threshold assert | | 4 | `simulation/pathfinding.rs:~85-90` | suggestion | manhattan_distance returning u32::MAX on z-mismatch — add comment for future z-level work | ### Tyre (Architecture): REQUEST_CHANGES | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `npc/relationships.rs` | critical | Global RelationshipGraph resource doesn't respect information boundaries (D-009/D-010). Add a TODO comment acknowledging this as a v0.1 limitation needing per-observer projection for MP. | | 2 | `npc/mod.rs:27-28` | critical | `check_phase_transition` runs `.after(advance_tick)` — PathRequests issued after `compute_paths` already ran this frame, causing a one-frame delay before NPCs start moving. Fix: change ordering to `.before(pathfinding::compute_paths)` so PathRequests are picked up same frame. | | 3 | `perception/interpretation.rs:69-72` | critical | Comment says "runs after knowledge events are processed" but actual ordering (PerceptionPlugin) is `.before(process_knowledge_events)`. The behavior is correct — you WANT to check against previous tick's knowledge to detect NewEntity. Fix the comment to match reality. | | 4 | `simulation/pathfinding.rs` | warning | Cardinal-only (4-dir) movement — document as deliberate v0.1 choice | | 5 | `perception/interpretation.rs:~150-185` | warning | Absence detection iterates all known NPCs every tick — scales poorly past v0.1 | | 6 | `main.rs:~59-175` | warning | Hardcoded test NPCs in production binary — consider feature flag or examples/ | | 7 | `Cargo.toml` | suggestion | Pin `pathfinding = "4.11"` for determinism guarantees | ### Verdict: CHANGES REQUESTED Three fixes needed before merge: 1. Add TODO comment on RelationshipGraph about MP boundary limitation 2. Fix routine system ordering: `.before(compute_paths)` instead of `.after(advance_tick)` 3. Fix stale comment in interpretation.rs to match actual (correct) ordering

jpmschweitzer referenced this issue from a commit

2026-02-12 18:18:22 +01:00

fix(server): address PR #14 review — ordering, docs, version pin

jpmschweitzer added 3 commits 2026-02-12 18:18:22 +01:00

fix(server): address PR #14 review — ordering, docs, version pin 2fd16f08b0

- Fix NpcPlugin system ordering: .before(compute_paths) instead of
  .after(advance_tick) so PathRequests are picked up same frame
- Fix stale doc comment in interpretation.rs: system runs BEFORE
  knowledge events, not after
- Add TODO(v0.2) on RelationshipGraph about information boundary
  limitation for multiplayer
- Document cardinal-only movement as deliberate v0.1 choice
- Add comment on manhattan_distance u32::MAX fallback for cross-z
- Pin pathfinding crate to 4.11

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(server): fix clippy warnings from Rust 1.93 ad653cffc3

- Use #[derive(Default)] + #[default] instead of manual Default impls
  for FacingDirection, KnowledgeState, RelationshipState, EntityVisibility
- Replace manual modulo check with .is_multiple_of()
- Collapse nested if in shadowcast symmetry check

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore(meta): update changelog 526696206e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jpmschweitzer commented

2026-02-12 18:18:29 +01:00

Addressed all review feedback:

Tyre critical (3/3):

Added TODO(v0.2) on RelationshipGraph about information boundary limitation for multiplayer
Fixed NpcPlugin system ordering: .before(compute_paths) instead of .after(advance_tick) — PathRequests now picked up same frame
Fixed stale doc comment in interpretation.rs — system runs BEFORE knowledge events, not after

Tyre warnings/suggestions (3/3):
4. Documented cardinal-only movement as deliberate v0.1 choice in pathfinding.rs
7. Pinned pathfinding crate to 4.11

Hoshe suggestions (1/1):
4. Added comment on manhattan_distance u32::MAX fallback for cross-z-level

Bonus: Fixed 6 clippy warnings from Rust 1.93 (derivable_impls, is_multiple_of, collapsible_if).

All 152 tests pass, clippy clean.

Addressed all review feedback: **Tyre critical (3/3):** 1. Added TODO(v0.2) on RelationshipGraph about information boundary limitation for multiplayer 2. Fixed NpcPlugin system ordering: `.before(compute_paths)` instead of `.after(advance_tick)` — PathRequests now picked up same frame 3. Fixed stale doc comment in interpretation.rs — system runs BEFORE knowledge events, not after **Tyre warnings/suggestions (3/3):** 4. Documented cardinal-only movement as deliberate v0.1 choice in pathfinding.rs 7. Pinned pathfinding crate to 4.11 **Hoshe suggestions (1/1):** 4. Added comment on manhattan_distance u32::MAX fallback for cross-z-level **Bonus:** Fixed 6 clippy warnings from Rust 1.93 (derivable_impls, is_multiple_of, collapsible_if). All 152 tests pass, clippy clean.

jpmschweitzer added 1 commit 2026-02-12 18:20:37 +01:00

Merge remote-tracking branch 'origin/main' into server c83d129703