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)

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-031: Combined content style guide

• Status: Open
• Question: Should the project have a single combined content style guide merging Paula's tier templates, Mellanie's voice conventions, Gestalt's mechanical constraints, and Miri's regional guide? The wiki-review workshop proposed this as a deliverable but it was never authored. What format, who owns it, and does it block content authoring?
• Assigned to: Mellanie, Paula
• Source: Wiki Review Workshop R2

Q-032: Cultural ingredients menu

• Status: Open
• Question: Should world generation use a 6-category cultural ingredients menu (Heritage Roots, Settlement Motivation, Economic Function, Philosophical Alignment, Corporate/Faction Presence, Drift Stage) where each culture is composed by selecting from ingredient lists? The lead approved the "ingredients menu" model over fixed cultural taxonomies. Full specification needed: category definitions, ingredient lists per category, composition rules, absence-as-signal mechanics.
• Assigned to: Miri, Gestalt
• Source: Wiki Review Workshop R4, lead interview

Q-033: Three-system NPC architecture

• Status: Open
• Question: Should NPCs be formally composed from 9 thematic patterns (FRIEND, MIRROR, ANCHOR, GHOST, CATALYST, THRESHOLD, REMNANT, SYSTEM, NOBODY) x 6 functional motivations (HANDLER, WITNESS, TURNCOAT, CIVILIAN, OPERATOR, SKEPTIC)? D-024 defines 10 axes + combat but predates this refined system. The wiki-review workshop produced a full composition matrix with drama ratings and forbidden combinations. Does this supersede D-024 or extend it?
• Assigned to: Gestalt, Paula
• Source: Wiki Review Workshop R4

Q-034: PC archetypes

• Status: Open
• Question: Should the full game support 8 fluid PC archetypes (Smuggler, Detective, Engineer, Diplomat, Medic, Scholar, Soldier, Merchant) with transition mechanics where archetype shifts during play based on player behavior? The lead approved 8 archetypes with fluid transitions as a game mechanic. v0.1 ships smuggler + detective only (D-027). Full archetype spec, transition triggers, and "vulnerable window" mechanics are undesigned. NOTE: The character-creation-game-setup workshop (Q-011) will address this — coordinate.
• Assigned to: Nigel, Gestalt
• Source: Wiki Review Workshop R4, lead interview

Q-035: Sacred/Profane/Middle Kingdom framework

• Status: Open
• Question: Should all game systems map to a Sacred/Profane/Middle Kingdom architectural framework? The lead approved this model where Sacred = what the system protects, Profane = what threatens it, Middle Kingdom = where the player navigates. The wiki-review workshop produced a full mapping table covering information, social, economic, spatial, temporal, and narrative systems. Needs formal specification and validation against current architecture.
• Assigned to: Gore, Gestalt
• Source: Wiki Review Workshop R4, lead interview

Q-036: District skeleton as generator output

• Status: Open
• Question: For the 300-world model, should the district skeleton (social sites, NPC slots, triangle templates, economic function, access topology) be the atomic output unit of the world generator? D-025 defines social sites as the atomic template unit for hand-authoring. The generator model reframes the district as a composed output from ingredient inputs. How does this interact with D-025?
• Assigned to: Tyre, Gestalt
• Source: Wiki Review Workshop R4

Q-037: Generator development pipeline

• Status: Open
• Question: Should content production follow a 6-phase generator pipeline (Ingredient Authoring, Template Authoring, Generator Development, Validation Development, Generation + Review, Hand-Elevation)? The wiki-review workshop proposed this as the production model for 300 worlds. SI mapped a release path (v0.1 hand-authored, v0.2-0.5 template expansion, v0.6-0.10 generator development, pre-v1.0 validation). Needs scope assessment and sprint planning integration.
• Assigned to: SI, Tyre
• Source: Wiki Review Workshop R4

Q-038: Authored content estimate at 300-world scale

• Status: Open
• Question: What is the irreducible authored content volume for 300 worlds? The wiki-review workshop estimated ~1,600-2,800 hours of hand-authoring for generator inputs (ingredient definitions, template specifications, validation rules, hand-elevation passes). How does this compare to the 20-district hand-authoring model it replaced? Is this estimate still valid given subsequent architectural decisions?
• Assigned to: Mellanie, SI
• Source: Wiki Review Workshop R4

Q-039: Gate topology generation

• Status: Open
• Question: How should the world generator produce gate (wormhole) network topology for 300 worlds? The wiki-review workshop proposed: gate connectivity = Sacred (what connects), which worlds connect = Profane (what separates), accessible world count = Middle Kingdom (where the player navigates). Small-world network properties, hub-and-spoke vs mesh topology, and Sacred/Profane constraints on gate placement are all unresolved. D-012 covers chunk-based map architecture but predates the 300-world model.
• Assigned to: Tyre, Nigel
• Source: Wiki Review Workshop R4

Q-040: Gate dual-use topology — freight and commuter on shared span gate infrastructure

• Status: Resolved → D-093 (gate cluster zone spec), D-095 (span gate dual-use windows)
• Question: System span gates serve both freight and commuter traffic (one gate per system). How does this work physically? Is it one gate aperture with scheduling (freight window vs. passenger window), or parallel lanes (separate apertures for freight and passenger flows)? What does the gate facility look like from the inside — a single large bay or divided infrastructure?
• Layout implication: Affects the gate cluster spatial design in the Transit District — the gate cluster must accommodate both freight staging and passenger throughflow, possibly at different times of day.
• Assigned to: Miri
• Source: Station District Layout Workshop (#153), Round 2. Surfaced by lead correction to Miri's S-02 (commuter transit ≠ second external gate).
• Cross-reference: D-036 (Sova setting), Q-036 (district skeleton as generator output)

Q-041: Interstellar travel mechanics — horizon stations and gate architecture

• Status: Resolved → D-095 (horizon stations: alien-built, 4–8 apertures, Oort-cloud, "The Ring"; sequential hop travel)
• Question: A system needs MORE than one horizon gate for multi-hop connectivity (one gate allows only 1:1 connections). Lead proposal (Round 3): Horizon stations — orbital installations at Oort-cloud distance, partially or wholly understood ancient alien technology, self-maintaining (Mass Effect relay/Citadel analog). Each horizon station holds a FIXED number of active and inactive horizon gates. Some systems may only have one hop to an orbital customs station with no direct planet-side span gate access. Remaining questions: How many gates per horizon station? What determines which gates are active vs. inactive? Is the travel instantaneous or traversal-based? What is "The Ring" (the orbital horizon station) like as a physical space?
• Assigned to: Miri
• Source: Station District Layout Workshop (#153), Round 2. Lead correction in Round 3: single-gate-per-system model insufficient for multi-hop travel; horizon station model proposed.
• Cross-reference: D-036 (Sova setting), Q-039 (gate topology generation), Q-040 (gate dual-use topology)

Q-042: Intra-system transport networks — passenger vs. freight, vehicles and modes

• Status: Partially resolved → D-095 (span gates at star/planetary level; horizon stations at Oort distance). Intra-system hab-to-hab transit remains open.
• Question: How do people and goods move within a star system (between orbital stations, planetary surfaces, and other in-system facilities)? Are there two separate networks (passenger transport and freight transport) or one shared network? What are the vehicle types and transit modes? How does intra-system transit interact with the span gate at the system's hub station?
• Assigned to: Miri
• Source: Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking.
• Cross-reference: D-036 (Sova setting), Q-043 (station internal transit)

Q-043: Station internal transit — intra-station transport system between districts

• Status: Resolved → D-095 (The Loop: 6-district tram, 4-minute Residential Core → Transit District; transit platform is bar-side encounter node)
• Question: What is the intra-station transport system on Station Sova? How do workers commute between districts (e.g., Residential Core → Transit District)? Is it a train, tram, shuttle, or pressurised corridor? What is the travel time and frequency? Where does the transit stop sit within the Transit District — gate-cluster-adjacent (workers arrive near freight operations) or bar-side-adjacent (workers arrive near their social space)?
• Layout implication for #153: The Transit District must include an internal transit stop. Its position within the district affects NPC traffic patterns and the district entry topology. This is the active T-03b question for Round 2/3 of the Station District Layout Workshop.
• Assigned to: Miri
• Source: Station District Layout Workshop (#153), Round 2. Arose from lead correction: commuter transit = internal station transit, not a second external gate.
• Cross-reference: D-036 (Sova setting), Q-042 (intra-system transport networks), S-02 revision

Q-044: Gate-train integration — do transport vehicles use gates directly or transfer on each side

• Status: Resolved → D-093/D-095 (gates are pedestrian/cargo-only; passengers transfer via gate concourse → transition corridor → transit platform; no direct gate-to-tram connection)
• Question: If trains or shuttles are the intra-system or intra-station transit mode, do they use the span gate directly (a train enters the gate and exits at the destination, carriages and all)? Or are the gates pedestrian/cargo-only, requiring passengers and freight to transfer to separate transport on each side? What does this imply for gate terminal design — does it need platforms, or just processing space?
• Assigned to: Miri
• Source: Station District Layout Workshop (#153), Round 2. Flagged by lead as transport lore requiring formal tracking.
• Cross-reference: Q-040 (gate dual-use topology), Q-043 (station internal transit)

---

44 questions (11 resolved, 2 partially resolved, 31 open). Last updated: 2026-02-25 (Q-040, Q-041, Q-043, Q-044 resolved; Q-042 partially resolved — Station District Layout Workshop #153 Round 3)