settled-reach/decisions/questions.md

Open Questions

Tracked questions awaiting discussion or resolution.

---

Q-001: Game engine selection

• Status: Resolved → D-020

Q-002: Scope of v0.1 playable prototype

• Status: Map spec resolved (D-014). Remaining: mechanics, characters, interactions for minimum playable build.
• Assigned to: Full team

Q-003: Art direction / presentation style

• Status: Further resolved for v0.1 via Content Gap Analysis Workshop. Araminta's v0.1 Visual Grammar proposal covers: entity color palette (D-033), zone-specific color palettes (3 zones with hex values), fog rendering (4 states), monologue presentation spec, insert dual-character variants. Long-term art direction beyond v0.1 remains open.
• Remaining: Long-term art direction, sprite replacement timeline, full visual identity.
• Assigned to: Araminta (lead)

Q-004: One campaign spanning all eras or separate era scenarios?

• Status: Not yet discussed
• Context: Gore raised that Commonwealth Era and Void Era play very differently. Prototype focuses on pre-Starflyer War era.
• Assigned to: Gore, Miri to lead discussion

Q-005: Scale for prototype - locations, characters, factions

• Status: Partially scoped
• Early signal: Institute/Armstrong City hub, ~10-20 characters, Guardians + institutional + political factions
• Assigned to: Gestalt, Tyre, Miri

Q-006: Multiplayer or single-player only?

• Status: Resolved → D-009

Q-007: Target platform(s)

• Status: Not yet discussed
• Context: Team Leader has Linux background (Fedora). Cross-platform considerations?
• Assigned to: Tyre

Q-008: Licensing / distribution model

• Status: Not yet discussed
• Question: Open source? Free? Commercial? This affects engine choice and asset decisions.
• Assigned to: Team Leader

Q-009: Time system

• Status: Resolved → D-031

Q-010: Storyteller AI design

• Status: Not yet discussed
• Question: How does the Rimworld-style storyteller work? What are the pacing rules? How much structural randomness vs dramatic randomness?
• Assigned to: Gestalt, Nigel

Q-011: Character selection and playable characters

• Status: Not yet discussed
• Question: Which characters are playable in the prototype? How different are their starting positions? Can you play canon characters or only original ones?
• Assigned to: Miri, Paula

Q-012: Generation expansion method for dialogue

• Status: Open
• Question: How does the 4x generation expansion pass work? LLM-based, template-based, or rule-based? Affects how base lines are authored — LLM needs style-strong anchors; rules need substitution patterns.
• Assigned to: Gestalt, Mellanie
• Source: Content Gap Analysis Workshop (Mellanie R2)

Q-013: Line previewer temporal progression

• Status: Open
• Question: How does the line previewer (#193) handle THE FRIEND's multi-visit contradiction arc? Needs sequence mode to simulate interaction progression over multiple encounters.
• Assigned to: Gestalt, Dudley
• Source: Content Gap Analysis Workshop (Mellanie R2)

Q-014: Audio timing with monologue chime

• Status: Resolved → D-067
• Resolution: Chime fires at ONSET of cognitive delay, not completion. 300-400ms duration, overlapping delay start. Chime is "unresolved" — opens a question, doesn't answer one. Sequence: hear/sense → chime plays → 0.6s delay begins → monologue text during delay → blob transitions to D-033 color → recognition complete.
• Date resolved: 2026-02-16

Q-015: Generation expansion for THE FRIEND content

• Status: Open
• Question: Does the 4x generation expansion apply to THE FRIEND's custom lines, or are all ~70-100 lines per FRIEND hand-authored? Recommendation: no expansion on FRIEND lines — risk of flattening hand-crafted voice.
• Assigned to: Mellanie, Gestalt
• Source: Content Gap Analysis Workshop (Ozzie R2, Gestalt R2)

Q-016: Knowledge hierarchy for monologue prerequisites

• Status: Resolved → D-041
• Resolution: 4-level hierarchy: Suspects < KnowsOf < KnowsDetails < Direct. Suspects = "something's off", gates initial investigation and vague monologue. KnowsOf = "X is involved in Y", gates topic-specific dialogue and peer-tier access. KnowsDetails = actionable detail, gates confrontation and secret-tier dialogue. Direct = currently in LOS, provides live position data. Maps to D-028 access tiers and D-035 prerequisite tags.
• Date resolved: 2026-02-11
• Source: Knowledge Graph & Information Boundaries Workshop

Q-017: Triangle pressure threshold

• Status: Open
• Question: Triangles need a numeric pressure value that increases based on events. When it crosses a threshold, confrontation situation activates. What events increase pressure? What's the threshold?
• Assigned to: Gestalt, Paula
• Source: Content Gap Analysis Workshop (Gestalt R2)

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-024: Gossip propagation timing

• Status: Resolved → D-080
• Resolution: Knowledge transfer occurs via a separate transfer_npc_knowledge Bevy system running after(run_npc_conversations). Transfer fires once per conversation at conversation start (immediate during conversation, not queued). Rate: 1–3 facts drawn by recency. Trust-tier gated. See D-080 for full specification.
• Closed by: Knowledge Flow & NPC Information Boundaries Workshop — unanimous. 2026-02-24.
• Source: Knowledge Graph & Information Boundaries Workshop (Gestalt Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2.

Q-025: Knowledge graph cap and eviction strategy

• Status: Resolved — no cap or eviction needed for v0.1/v0.2. Re-evaluation trigger: Active NPC count > 200 OR KG memory exceeds 50 MB.
• Question: At what point does an NPC's knowledge graph need entry eviction? What is the eviction policy?
• Resolution (2026-02-24, confirmed by Knowledge Flow workshop): Current analysis: ~14 KB per Active NPC KG (50 entities + 20 facts, D-041 budget). 80 Active NPCs = ~1.1 MB. 2,000 Background NPCs at 10 entries = ~5 MB. Total ~6 MB. With gossip propagation shipping in Sprint 17 (D-080, 1–3 facts per conversation): estimated ~12 MB peak at current NPC counts. Neither re-evaluation condition expected before v0.3. The existing decay system (decay_knowledge in knowledge/events.rs) downgrades confidence and marks entries Stale but does not remove them — correct behavior (preserves "I used to know X" for narrative). If eviction becomes necessary, simplest policy: on each decay pass, if entities.len() > MAX_ENTITIES, remove Stale entries with lowest last_updated_tick. BTreeMap makes this O(N).
• Closed by: Knowledge Flow & NPC Information Boundaries Workshop — Tyre, Gestalt, Dudley confirmed; Paula non-objection noted. 2026-02-24.
• Source: Knowledge Graph & Information Boundaries Workshop (Dudley Round 1, section 8.3). Architecture audit 2026-02-23. Workshop confirmation 2026-02-24.

Q-026: Contradiction detection algorithm

• Status: Resolved → D-083
• Resolution: Event-driven detection at KG write time in observe_entity(), using ContradictionClaim struct. Location contradiction is automatic (Sprint 17): position comparison + time window (CONTRADICTION_WINDOW_TICKS = 600). Attribute and fact contradiction are content-authored (Sprint 18). Both ToldBy and DirectObservation entries receive Contradicted state (epistemic neutrality). ContradictionDetected event → monologue with resolved display names → relationship shift → AnomalyMarker via existing pipeline.
• Closed by: Knowledge Flow & NPC Information Boundaries Workshop — unanimous on architecture. 2026-02-24.
• Source: Knowledge Graph & Information Boundaries Workshop (Gestalt/Paula Round 1); resolved in Knowledge Flow & NPC Information Boundaries Workshop Round 2.

Q-027: Fast-travel system design

• Status: Open
• Question: How does inter-system travel work in production gameplay? The current hub teleport (Home key, #501) is scoped as Gauntlet-only dev tool. Production travel must be diegetic and respect asymmetric information. Proposed flow: player goes to local gate → warps to system gate → interacts with target menu → jumps to destination system gate. Key constraints:
  1. Region gating: fast-travel only available from safe or fast-travel-enabled regions. If you rented transport to reach a remote location (e.g. mountain colony), you must return the transport to civilization first — this can be a skip-travel interaction but must happen in-world.
  2. Asymmetric information: NPCs observe arrivals and departures. Travel choices leak information (who saw you leave, who sees you arrive, what transport was used).
  3. Home key in production: at most, Home could prompt "Do you want to fast-travel to the system hub?" if in a safe/enabled region — never instant teleport.
  4. Transport types: walking, rented vehicle, public transit, gate network — each with different information exposure profiles.
• Context: #501 implemented instant Home key teleport gated behind gauntlet_mode. Re-scoped to Gauntlet-only after design review. Production fast-travel needs separate design and implementation.
• Assigned to: Gestalt, Paula, Tyre
• Source: Sprint 10 PR review discussion (2026-02-19)

Q-028: Collision-resistant line IDs for auto-generated NPCs

• Status: Resolved → D-084
• Resolution: The collision problem is mostly already solved by the role-pool architecture: dock-worker_d_### lines are shared content for all instances of the role, not per-instance IDs. A true collision (two distinct authored lines sharing the same ID) cannot occur with one file per role. For the edge case of authored instance-specific content, a role-slug + zero-padded generation counter suffix produces dock-worker-07_d_001. Counter is seeded-deterministic. No schema change, no migration. Hand-authored NPCs unchanged.
• Closed by: Gestalt (Sprint 18, #544). 2026-02-25.
• Ticket: #544
• Assigned to: Gestalt, Tyre
• Source: Sprint 16 PR #59 review discussion (2026-02-23)

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)

---

29 questions (7 resolved, 1 partially resolved, 21 open). Last updated: 2026-02-25 (Q-029 added)