settled-reach/decisions/questions.md

# Open Questions

Tracked questions awaiting discussion or resolution.

---

### Q-001: Game engine selection
- **Status:** Resolved → [D-020](architecture.md#d-020-engine-and-architecture-selection--godot-client--rust-simulation-via-subprocessipc)

### Q-002: Scope of v0.1 playable prototype
- **Status:** Map spec resolved ([D-014](scope.md#d-014-v01-map-specification)). 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](architecture.md#d-009-multiplayer---design-for-it-build-single-player-first)

### 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](architecture.md#d-031-time-system--game-clock-and-day-phases)

### 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](perception.md#d-067-recognition-chime-fires-at-onset-of-cognitive-delay)
- **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](architecture.md#d-041-knowledge-graph-data-model)
- **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](perception.md#d-035-symmetric-shadowcasting-albert-ford-selected-for-los-computation)
- **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](architecture.md#d-041-knowledge-graph-data-model)
- **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](perception.md#d-080-npc-to-npc-knowledge-propagation)
- **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](perception.md#d-083-contradiction-detection-pipeline)
- **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](content.md#d-084-dual-namespace-line-id-scheme--role-pool--instance-override)
- **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)*