settled-reach/decisions/questions-architecture.md

Open Questions — Architecture

Technical foundation questions: engine, protocols, data structures, performance, save/load.

---

Q-001: Game engine selection

• Status: Resolved → D-020

Q-006: Multiplayer or single-player only?

• Status: Resolved → D-009

Q-009: Time system

• Status: Resolved → D-031

Q-018: Shadowcasting algorithm selection

• Status: Resolved → D-035
• Question: Which line-of-sight algorithm should be used? Symmetric shadowcasting (Albert Ford) vs recursive shadowcasting. Both are proven but differ in symmetry properties (symmetric: if A sees B, then B sees A) and implementation complexity. Requires benchmarking at 150x150 map scale with 30 entities to validate performance within 100ms tick budget.
• Context: D-011 mandates LOS shadowcasting for fog of perception. Architecture review identified this as unspecified (audit section 2.2). Critical for Sprint 2 perception pipeline.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-019: Entity ID stability strategy

• Status: Partially resolved → D-041
• Resolution: Server-side: StableEntityId component + EntityRegistry resource provides bidirectional StableId(u64) <-> Entity mapping. StableId assigned once at entity spawn, never changes, persists across save/load. Knowledge graphs reference StableId, not bevy Entity. Client-side mapping (Godot StableId -> scene node lifecycle) remains open.
• Remaining: Client-side entity lifecycle management, scene node mapping strategy.
• Date partially resolved: 2026-02-11
• Assigned to: Tyre, Dudley (client-side portion)
• Source: Knowledge Graph & Information Boundaries Workshop

Q-020: Multi-entity collision resolution

• Status: Open
• Question: When two NPCs attempt to move to the same tile on the same tick, what is the resolution policy? Options: first-write-wins (deterministic with system ordering), both fail (conservative), priority-based (e.g., player > NPC, Active tier > Background tier).
• Context: D-012 defines tile collision. WalkabilityMap exists (server/src/simulation/movement.rs) but handles single-entity validation. Architecture review identified multi-entity collision as unspecified.
• Assigned to: Gestalt, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-021: Tick budget overflow policy

• Status: Open
• Question: When a simulation tick exceeds the 100ms budget, what happens? Options: (1) slow down real-time and preserve determinism (tick completes fully before next), (2) skip ticks and break determinism, (3) cap work per tick and defer to next tick. Must align with D-010 principle 4 (deterministic simulation).
• Context: D-026 defines 100ms tick budget for Active tier at 10 tps. Architecture review consensus recommendation proposes "slow real-time, don't skip ticks." Needs formal decision.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-022: NPC pathfinding cache eviction

• Status: Open
• Question: With 80 Active-tier NPCs each caching ~3 pathfinding routes, the cache holds ~240 paths. What is the eviction policy? LRU? Time-based expiration? Fixed size per NPC? How are paths invalidated when walkability changes (doors lock, areas become restricted)?
• Context: Architecture review identified pathfinding as MEDIUM gap (audit section 2.2). Cache management needs specification regardless of algorithm choice.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-023: Debug visualization scope

• Status: Open
• Question: What information should the debug overlay display? Candidates: LOS rays, pathfinding waypoints, vision cones, information boundary tags (who knows what), tick timing breakdown, spatial partition grid cells. Dev-only tool, or accessible for mod development?
• Context: Architecture review (Troblum) identifies debug visualization as missing operational infrastructure. Needed for debugging perception system, information boundaries, and performance issues.
• Assigned to: Tyre, Stig
• Source: Architecture Review Audit 2026-02-11

Q-029: Save file format design

• Status: Open
• Question: What should the long-term save file format look like? Key considerations:
  1. Versioning and migration: How do saves survive across game versions? Schema evolution strategy (field additions, renames, removals). Should saves embed a version number and run migrations on load?
  2. Compression: Raw MessagePack vs compressed (zstd, lz4)? Tradeoff between save/load speed and file size. SaveStateV1 is already MessagePack — does that carry forward?
  3. Integrity: Checksums or signatures to detect corruption? CRC32 header?
  4. Metadata header: Should the file have a readable header (game version, save date, play time, character name) that the loading screen can read without deserializing the full save?
  5. Determinism: D-010 requires deterministic simulation. Can saves capture enough state to resume deterministically, or is approximate resume acceptable?
  6. Modding: Should the format be documented for mod authors? Does it need extension points?
  7. Cloud sync: Any considerations for Steam Cloud or similar? File size limits?
• Context: Sprint 19 implements a quick-and-dirty save format (D-085 per-game directories, MessagePack serialization from SaveStateV1). This question tracks the thorough design pass for production quality.
• Assigned to: Tyre, Dudley
• Source: Team Leader directive (Sprint 19 planning)

Q-030: Seed configuration schema

• Status: Open
• Question: What artifact records all randomizer decisions at game start? The wiki-review workshop proposed a seed-state.yaml capturing: world seed, character selection, pool draws (Tier 1 modules, FRIEND selection, contraband variant), template assignments, NPC trait rolls, triangle configurations, and entanglement pattern. Ticket #394 (seed configuration schema design) exists but the design is open.
• Assigned to: Tyre, Gestalt
• Source: Wiki Review Workshop + v0.1 Content Scoping Workshop

Q-046: Departure schedule model — departure windows as generator output for docked vessels

• Status: Resolved → D-108 (MobileChunk Specification)
• Resolution: scheduled_departure: Option<SimTick> in Docked state is mandatory generator output. Vessels without departure schedules are an error state. The Docked struct must include docked_since: SimTick and scheduled_departure: Option<SimTick> — these fields must be added at implementation time (absent from Tyre's Round 4 canonical struct).
• Date resolved: 2026-02-27
• Source: Generator Architecture Workshop (#562)
• Assigned to: Tyre + Miri

Q-059: PlatformInfo full interface scope

• Status: Resolved → D-141
• Question: What properties should PlatformInfo expose beyond power state, memory, and file paths?
• Resolution: 23 properties across 7 categories (power, memory, CPU, GPU, platform identity, display, locale), 1 signal (power_profile_changed), 2 methods (refresh_memory, get_diagnostics). Researched Unity SystemInfo, Unreal FPlatformMisc, SDL3. Skip: GPU VRAM (not available in Godot), CPU frequency, audio devices (AudioManager owns that), network connectivity (single-player), VM detection. Add properties only when a ticket needs them — no stubs. get_diagnostics() returns flat Dictionary for bug reports.
• Date raised: 2026-03-13
• Date resolved: 2026-03-13
• Assigned to: Tyre
• Source: Sprint 26 client work (#646, #659)

---

13 questions (7 resolved, 1 partially resolved, 5 open). Last updated: 2026-03-13.