settled-reach/docs/wiki/knowledge/fact-catalog.md

Knowledge Fact Catalog

Canonical FactIds for the v0.1 vertical slice. All facts follow the category.topic format defined in server/src/knowledge/types.rs.

Format

• FactId: String identifier (e.g., "contraband.ring_exists")
• Progression: Text descriptions at each KnowledgeConfidence level
• Mechanical Purpose: What this fact gates in dialogue, monologue, or investigation

---

Contraband Facts

contraband.ring_exists

Suspects: "Something's going on with the cargo schedules. Too many off-manifest deliveries." KnowsOf: "There's a smuggling operation running through the logistics hub." KnowsDetails: "The ring moves unlicensed lattice components during shift transitions. Voss manages the timing." Direct: N/A (abstract knowledge — never directly observed)

Mechanical Purpose: Gates investigation dialogue trees. Required for ring-specific monologue. The detective starts at Suspects and escalates. The smuggler (if playing the ring member path) starts at KnowsDetails.

---

contraband.lattice_components

Suspects: "That container's marked as standard components, but the mass is wrong." KnowsOf: "Unlicensed lattice components. Aftermarket mods that bypass Commission certification." KnowsDetails: "Medical-grade neural lattice replacements diverted from Syndic supply chains, plus enhanced capability mods." Direct: "I'm looking at a crate of lattice components right now. Serial numbers don't match any certified batch."

Mechanical Purpose: Contraband identification. Detective needs KnowsOf to correctly interpret manifest discrepancies. Smuggler needs KnowsDetails to handle cargo safely.

---

contraband.medical_grade

Suspects: "Some of this cargo doesn't feel like luxury goods." KnowsOf: "Medical-grade lattice replacements. For people whose lattices are degrading and who can't afford Syndic pricing." KnowsDetails: "The ring moves medical replacements for people locked out of the institutional system. It's not just profit — it's healthcare." Direct: N/A (conceptual understanding)

Mechanical Purpose: Moral complexity gate. Smuggler monologue shifts tone when this reaches KnowsDetails. Detective dialogue with humanitarian-focused NPCs requires KnowsOf.

---

contraband.severance_tech

Suspects: "Sealed containers Nils won't discuss. Heavier than lattice components." KnowsOf: "Severance equipment. Counter-surveillance tech. Illegal across most of the Reach." KnowsDetails: "Guardians of Severance supply chain. This isn't local — it's connected to something bigger." Direct: N/A (not directly visible in v0.1)

Mechanical Purpose: Contamination seed for storyteller expansion. The thing that makes the smuggler question how deep the ring goes.

---

contraband.supply_chain

Suspects: "The cargo doesn't originate on this station." KnowsOf: "Off-station coordinator manages incoming shipments. Someone named Sabel." KnowsDetails: "Supply chain: aftermarket manufacturers (Syndic-adjacent) -> freight networks -> Sabel (off-station) -> ring coordinator (Devra or Nils) -> local distribution." Direct: N/A (network knowledge)

Mechanical Purpose: Investigation depth. Detective at KnowsDetails can map the full chain. Smuggler at KnowsDetails understands their position in the network.

---

Location Facts

location.corridor_b7_restricted

Suspects: "Corridor B-7 should see foot traffic during shift change. It's empty." KnowsOf: "Maintenance corridor used for smuggling operations. Access requires hub clearance." KnowsDetails: "Corridor B-7 is between old and new prefab sections. Service hatch from break room. The ring routes shipments through here during shift transitions." Direct: "I'm in Corridor B-7 right now. Old construction smell, minimal Meridian coverage, no surveillance."

Mechanical Purpose: Spatial knowledge. Required for investigation progression (detective) and operational planning (smuggler). Direct confidence gates monologue about current surroundings.

---

location.smuggling_route

Suspects: "Cargo movements don't match the official routing." KnowsOf: "The ring uses a specific path: freight bay -> service corridor -> temporary storage -> bar district back room." KnowsDetails: "Timing is critical. The route only works during shift transition when patrol coverage thins. Lera provides the final handoff point." Direct: "Watching the route right now. Kosse moving a container through the service hatch."

Mechanical Purpose: Investigation mechanics. Detective needs KnowsOf to predict NPC movements. Smuggler needs KnowsDetails for operational participation.

---

location.surveillance_gaps

Suspects: "Some areas feel less monitored than others." KnowsOf: "Meridian coverage degrades in older sections. Maintenance corridors have minimal surveillance." KnowsDetails: "Corridor B-7, break room service hatch, bar back room — all Meridian dead spots. The ring exploits these systematically." Direct: "Checking my lattice overlay now. Zero Meridian signal in this section."

Mechanical Purpose: Stealth and observation mechanics. Detective's augmented lattice can detect coverage gaps (requires KnowsOf). Smuggler uses gaps operationally (requires KnowsDetails).

---

location.dead_drop_location

Suspects: "Kael leaves things in the break room locker area. Not his own locker." KnowsOf: "Locker 47 in the hub break room. Unofficial dead drop for small items." KnowsDetails: "Locker 47 is registered to a worker who transferred off-station 18 months ago. Never reassigned. The ring has used it ever since." Direct: "Locker 47 is open. There's a sealed packet inside."

Mechanical Purpose: Discovery mechanic. Detective can discover through observation (Suspects -> KnowsOf). Smuggler knows from background (starts at KnowsDetails).

---

Investigation Facts

investigation.manifest_discrepancy

Suspects: "Cargo manifests have inconsistencies. Weight doesn't match volume." KnowsOf: "Systematic manifest doctoring. Someone with freight scheduler access is altering records." KnowsDetails: "Maret Korr processes manifests. She's noticed the discrepancies but hasn't reported them. She's either complicit or terrified." Direct: "Comparing the manifest right now. Container 4471 — logged weight 240kg, actual weight closer to 310kg."

Mechanical Purpose: Core investigation mechanic. Detective's analytical lattice flags discrepancies at Suspects. Full understanding requires KnowsDetails. Smuggler knows Maret's position from background.

---

investigation.shift_mismatch

Suspects: "Night shift schedules don't align with freight volume." KnowsOf: "Voss adjusts shift schedules to create coverage gaps. Deliberate understaffing during high-risk windows." KnowsDetails: "Shift mismatches occur every third rotation. Coincides exactly with off-station shipment arrivals. Voss takes a cut." Direct: "Checking the current schedule. Night shift is short two workers — again."

Mechanical Purpose: Pattern recognition. Detective needs KnowsOf to connect schedule to smuggling. Smuggler knows the pattern operationally.

---

investigation.cargo_anomaly

Suspects: "That container sat in temporary storage for 18 hours. Standard procedure is 4-6 hours max." KnowsOf: "Delayed processing indicates off-manifest handling. Someone's buying time to repackage cargo." KnowsDetails: "Nils coordinates timing. Container arrives, sits in temp storage during shift A, gets repackaged during shift B transition, moves out during shift C startup." Direct: "Container 4471 has been sitting here for 14 hours. No movement orders logged."

Mechanical Purpose: Observation-based discovery. Detective builds case from Suspects upward. Smuggler knows the workflow (starts KnowsDetails).

---

investigation.evidence_collected

Suspects: N/A (binary fact — you either have evidence or you don't) KnowsOf: "I have documented manifest discrepancies, shift schedule anomalies, and witness testimony from Drin." KnowsDetails: "Full case file: manifest logs, Drin's testimony under pressure, Maret's reluctant cooperation, surveillance footage from observation gallery showing Corridor B-7 access." Direct: N/A (abstract accumulation)

Mechanical Purpose: Investigation state tracker. Gates confrontation dialogue. Detective-specific — smuggler doesn't collect evidence against themselves.

---

World Facts

world.commission_regulations

Suspects: "The Commission regulates lattice technology. That's why people want aftermarket mods." KnowsOf: "Commission certification is expensive and slow. Category 3 violation for unauthorized lattice modification carries fines and potential lattice restriction." KnowsDetails: "Commission monopoly prices most citizens out of enhanced capability. Medical-grade replacements require 6-12 month approval cycles. The black market exists because the legitimate system fails." Direct: N/A (regulatory knowledge)

Mechanical Purpose: Moral framing. Smuggler at KnowsDetails has ideological justification. Detective at KnowsDetails understands why the ring has community support.

---

world.syndic_supply_chain

Suspects: "The cargo originates from Syndic-controlled systems." KnowsOf: "Syndics manufacture medical-grade lattice components. Diverted shipments end up on the black market." KnowsDetails: "Specific Syndic: unclear, but the serial number patterns suggest two sources. The ring doesn't control the supply chain — they're downstream distributors." Direct: N/A (network knowledge)

Mechanical Purpose: Political context. Detective at KnowsDetails realizes the ring is small-scale. Smuggler at KnowsDetails understands their position in the larger economy.

---

world.sova_district_layout

Suspects: "The district is a mix of old and new construction." KnowsOf: "40-year-old prefab base with retrofitted partitions. Logistics hub, bar district, residential sections. Meridian coverage is uneven." KnowsDetails: "Older sections have hidden spaces between wall layers. Service corridors from original construction still exist but aren't on current maps. The ring exploits architectural legacy." Direct: "I'm looking at the district map overlay right now. Official layout vs. actual structure don't match in Section 3."

Mechanical Purpose: Navigation and investigation. Detective needs KnowsDetails to find hidden spaces. Smuggler starts with KnowsOf (knows layout from living here).

---

world.shift_schedule

Suspects: "Logistics hub runs three shifts: morning, day, night." KnowsOf: "Shift transitions are 30-minute windows with reduced oversight. Ring operations happen during transitions." KnowsDetails: "Shift A: 06:00-14:00. Shift B: 14:00-22:00. Shift C: 22:00-06:00. Transition windows: 13:30-14:30, 21:30-22:30, 05:30-06:30. Voss manages the schedule." Direct: "Current time: 21:45. Shift transition active. Observing movement patterns."

Mechanical Purpose: Temporal mechanics. Required for NPC routine prediction and investigation timing. Smuggler starts KnowsDetails. Detective learns through observation.

---

Relationship Facts

relationship.ring_membership

Suspects: "Kael's behavior suggests involvement in something off-book." KnowsOf: "Kael is a ring member. Mid-level, handles physical cargo." KnowsDetails: "Ring structure: Devra or Nils coordinate, Voss provides scheduling cover, Kael and Kosse handle cargo, Lera provides handoff point, Pell is wavering." Direct: "Watching Kael move a container right now. Ring operation in progress."

Mechanical Purpose: Social knowledge. Detective builds this through investigation. Smuggler knows from shared membership (if on that path) or observation.

---

relationship.kael_naia_connection

Suspects: "Kael mentions a partner. Someone named Naia." KnowsOf: "Kael's partner is Naia, a teacher. They're worried about Kael's late nights." KnowsDetails: "Naia confides in Sera Venn. Sera knows something is wrong but hasn't reported it. The worry is contaminating Kael's operational security." Direct: N/A (relationship knowledge)

Mechanical Purpose: Emotional leverage. Detective can use Naia as pressure point. Smuggler (if Kael's friend) must protect Naia from knowledge.

---

relationship.trust_network

Suspects: "People here know each other. Tight social bonds." KnowsOf: "The ring depends on trust networks: Kael trusts Nils (sibling), Lera trusts the regulars, Drin is compromised by debt to Harek." KnowsDetails: "Trust map: Kael <-> Nils (blood), Kael <-> Naia (partnership), Naia <-> Sera (friendship), Sera <-> Detective (professional/personal), Drin -> Harek (debt), Voss -> Devra/Nils (financial)." Direct: N/A (social network knowledge)

Mechanical Purpose: Social manipulation mechanics. Detective at KnowsDetails can exploit trust fractures. Smuggler at KnowsDetails knows whom to protect.

---

relationship.faction_allegiance

Suspects: "Some people here are Commission-aligned. Others resent the Commission." KnowsOf: "Sera is Commission. Torek Lintar is nominally Commission but lives here. The detective represents institutional authority. Everyone else is civilian." KnowsDetails: "Faction tensions: Commission (Sera, Torek, Detective) vs. ring (Kael, Nils, Kosse, Voss, Lera) vs. civilians (Naia, Maret, Drin, Resha). Drin is compromised between civilian and Commission." Direct: N/A (political knowledge)

Mechanical Purpose: Access tier logic. Explains why NPCs treat characters differently. Detective at KnowsDetails understands institutional barriers.

---

Progress Facts (Arc State Tracking)

progress.initial_suspicion

Suspects: "Something feels off about this place." KnowsOf: "There's a pattern here. Cargo discrepancies, nervous NPCs, evasive answers." KnowsDetails: "Smuggling operation confirmed. Now I need to identify the participants and build a case." Direct: N/A (meta-knowledge)

Mechanical Purpose: Detective arc state. Gates monologue tone shifts. Smuggler doesn't track this (they start knowing the operation exists).

---

progress.active_investigation

Suspects: N/A (binary — investigation is active or it isn't) KnowsOf: "I'm building a case. Evidence collected, witnesses identified, patterns mapped." KnowsDetails: "Case file: manifest logs, Drin testimony, Maret's reluctant cooperation, surveillance data, NPC behavioral analysis. Ready to escalate." Direct: N/A (meta-knowledge)

Mechanical Purpose: Detective arc state. Gates confrontation options. Changes NPC dialogue (they know they're being investigated).

---

progress.confrontation_ready

Suspects: N/A KnowsOf: "I have enough to confront specific NPCs. Kael, Voss, or Lera." KnowsDetails: "Full case built. Can confront the ring, turn an informant, or escalate to Commission enforcement." Direct: N/A (meta-knowledge)

Mechanical Purpose: Detective endgame gate. Smuggler equivalent: progress.operation_compromised (not listed here — detective-specific arc).

---

progress.arc_resolved

Suspects: N/A KnowsOf: N/A KnowsDetails: "The arc has concluded. Ring dismantled, informant turned, or operation escaped. Outcome determined." Direct: N/A (meta-knowledge)

Mechanical Purpose: Arc completion tracker. Used by storyteller to determine whether new modules can activate.

---

Usage Notes

• FactId strings must match exactly. "contraband.ring_exists" not "contraband.ring_exist" or "Ring Exists".
• Confidence levels are ordered: Suspects < KnowsOf < KnowsDetails < Direct. Use KnowledgeConfidence::decayed() for time-based degradation.
• Direct confidence is perception-system-managed. Content authors rarely set this manually — it's automatically assigned when an entity/location is in the observer's LOS.
• Abstract facts (e.g., contraband.ring_exists, world.commission_regulations) never reach Direct — they're conceptual, not observable.
• Spatial facts (e.g., location.corridor_b7_restricted) can reach Direct when the observer is physically present.
• Progression text is for content authoring reference, not runtime display. Monologue lines reference these facts as prerequisites; they don't display the progression text directly.

---

Total FactIds: 24 (5 contraband, 4 location, 4 investigation, 4 world, 4 relationship, 4 progress). Sufficient for v0.1 vertical slice. Expandable by adding new categories or topics within existing categories.