settled-reach/wiki/concepts/relationship-states.md

title, description, slug, category, status, created, updated, concept_type, tags, decision_refs, cross_refs

title	description	slug	category	status	created	updated	concept_type	tags	decision_refs	cross_refs
Relationship States and Transitions	Five RelationshipState values, THE FRIEND contradiction arcs, KnowledgeState integration, and dialogue access tier filtering	relationship-states	concept	canonical	2026-02-12	2026-02-13	mechanical		D-041

Relationship States and Transitions

How RelationshipState (defined in server/src/knowledge/types.rs) evolves during gameplay, with specific patterns for THE FRIEND contradictions and KnowledgeState integration.

Canonical States

From server/src/knowledge/types.rs:

pub enum RelationshipState {
    Unknown,    // Teal #4a9ebb
    Known,      // Soft green #6bc9a6
    Friendly,   // Soft green #6bc9a6 (same color, different semantics)
    PersonOfInterest,  // Amber #e8c547
    Hostile,    // Red #d45d5d
}

Visual rendering: D-033 entity color system. The client maps these states to colors. The knowledge graph determines the state.

---

State Semantics

Unknown

What it means: No prior knowledge of this entity. First encounter.

Monologue tone: Observational, neutral. "Who's that?"

Dialogue availability: Public-tier only. No trust-gated content.

Color: Teal — visually distinct from all other states.

Typical duration: First 30 seconds to 2 minutes of gameplay (until first direct interaction or lattice query).

---

Known

What it means: Recognized, neutral-to-positive. Not a threat, not a close ally.

Monologue tone: Casual acknowledgment. "There's Drin. Maintenance tech."

Dialogue availability: Public + peer-tier (if appropriate). No insider/secret content yet.

Color: Soft green — "safe enough."

Typical entities: Coworkers (smuggler), routine contacts (detective), flat NPCs, bar regulars.

---

Friendly

What it means: Positive relationship, trusted. Emotional connection or reliable professional rapport.

Monologue tone: Warm, personal. "Good to see them. Always reliable."

Dialogue availability: Public + peer + insider-tier. Trust-gated content unlocks. Some secret-tier content if relationship deepens.

Color: Soft green (same as Known — the distinction is semantic, not visual).

Typical entities: THE FRIEND NPCs, close colleagues, trusted contacts.

Why same color as Known: Visual simplicity in early implementation. Future refinement could add subtle shader variation (warmth, pulse, saturation).

---

PersonOfInterest

What it means: Flagged. Something's wrong. Under observation or suspicion.

Monologue tone: Analytical, cautious. "{THE FRIEND}'s meeting someone I don't recognize. That's not normal."

Dialogue availability: Shifts. Trust-gated content may become unavailable. Confrontation options unlock.

Color: Amber — "pay attention."

Typical entities: NPCs caught in contradictions, suspects under investigation, people who've triggered tells.

THE FRIEND trigger: When THE FRIEND's contradiction is discovered, they transition from Friendly → PersonOfInterest. This is the emotional gut-punch moment.

---

Hostile

What it means: Character KNOWS there is danger. Threat confirmed.

Monologue tone: Alarm, threat assessment. "That's security. They're moving toward me."

Dialogue availability: Hostile-tier only (threats, demands, final warnings). All trust content locked.

Color: Red — "danger."

Typical entities: NPCs who've turned on the player, authority figures during a confrontation gone bad, exposed ring members cornered by the detective.

Rare: Most NPCs don't reach Hostile. It's the endgame state for failed social maneuvering.

---

Transition Paths

Standard Progression (No Contradiction)

Unknown → Known → Friendly

Triggers:

• Unknown → Known: First direct interaction OR lattice query identifies them.
• Known → Friendly: Repeated positive interactions, shared drinks at bar, successful cooperation, trust-building dialogue.

Example: Detective meets a bar regular. Unknown (first visit) → Known (second visit, exchanged names) → Friendly (third visit, regular offers unprompted gossip).

---

Investigation Progression (Detective)

Unknown → Known → PersonOfInterest → Hostile (if confrontation fails)

Triggers:

• Unknown → Known: Lattice query, case file match, first observation.
• Known → PersonOfInterest: Behavioral flags accumulate, tells observed, manifest discrepancy linked to this NPC.
• PersonOfInterest → Hostile: Confrontation attempt rejected, NPC realizes they're under investigation, escalation.

Example: Detective observes a cargo handler. Unknown (first sight) → Known (lattice query: "dock worker, logistics") → PersonOfInterest (observed in restricted corridor, evasive answers) → Hostile (confrontation: "I know you're involved. You need to cooperate." / handler: "Stay away from me.").

---

THE FRIEND Contradiction Arc (Smuggler's Perspective)

Friendly → PersonOfInterest → [resolution: Friendly-but-contaminated OR Hostile]

Phase 1: Friendly (baseline)

• {THE FRIEND} is the smuggler's trusted colleague.
• Monologue: fond, casual.
• Color: soft green.
• Dialogue: insider-tier, warm.

Phase 2: First Crack (still Friendly, but flags accumulating)

• Behavioral flags: lattice_checking,distracted.
• Monologue shifts slightly: "{THE FRIEND}'s been quiet lately."
• State unchanged (still Friendly), but EntityKnowledge.known_attributes["behavior_flags"] updates.

Phase 3: The Contradiction (Friendly → PersonOfInterest)

• Trigger: Direct observation of {THE FRIEND} meeting an unknown contact off-route.
• EntityKnowledge.known_attributes["contradiction_flagged"] = "meeting_unknown_contact".
• RelationshipState transitions to PersonOfInterest.
• Color shifts: soft green → amber.
• Monologue: "That wasn't anyone from our rotation. {THE FRIEND}, what are you doing?"
• Dialogue options change: confrontation unlocks, trust-tier content locks ({THE FRIEND} is evasive).

Phase 4: Post-Confrontation

• Path A (understanding): Smuggler confronts {THE FRIEND} gently. {THE FRIEND} confesses: trying to exit the ring to protect someone close to them. RelationshipState remains PersonOfInterest but monologue tone shifts to conflicted sympathy. Color stays amber (still a problem), but dialogue reflects empathy.
• Path B (betrayal): Smuggler reports {THE FRIEND} to ring leadership or applies harsh pressure. {THE FRIEND} turns defensive. RelationshipState → Hostile. Color → red. {THE FRIEND} avoids the smuggler, might actively obstruct.

THE FRIEND pattern: Friendly → PersonOfInterest is the emotional core. The player trusted {THE FRIEND}. Now {THE FRIEND} is amber. That color shift IS the narrative moment.

---

THE FRIEND Contradiction Arc (Detective's Perspective)

Friendly → PersonOfInterest → [resolution: Friendly-but-contaminated OR Known-distanced OR Hostile]

Phase 1: Friendly (baseline)

• {THE FRIEND} is the detective's institutional contact and social anchor.
• Monologue: professional warmth, relief.
• Color: soft green.
• Dialogue: peer-tier, cooperative, helpful.

Phase 2: Pattern Observation (still Friendly, but flags accumulating)

• Behavioral flags: avoidance_pattern ({THE FRIEND} leaves when a suspect arrives).
• Monologue: "That's the third time. {THE FRIEND} leaves when that person shows up."
• State unchanged (still Friendly), but EntityKnowledge.known_attributes["behavior_flags"] updates.

Phase 3: The Contradiction (Friendly → PersonOfInterest)

• Trigger: Detective asks {THE FRIEND} directly about their avoidance. {THE FRIEND} deflects unconvincingly.
• EntityKnowledge.known_attributes["contradiction_flagged"] = "avoidance_inconsistency".
• EntityKnowledge.known_attributes["secret_held"] = "unreported evidence" (detective's inference).
• RelationshipState transitions to PersonOfInterest.
• Color shifts: soft green → amber.
• Monologue: "They're not lying. But they're not telling me everything. {THE FRIEND}, what do you know?"
• Dialogue options change: pressing questions unlock, casual warmth diminishes.

Phase 4: Post-Confrontation

• Path A (loyalty test): Detective confronts {THE FRIEND} about concealment. {THE FRIEND} confesses: sitting on evidence to protect a third party. Detective can choose: report {THE FRIEND} (Hostile), use the information without reporting them (PersonOfInterest → Known, relationship damaged), or protect {THE FRIEND} and accept the information gap (PersonOfInterest → Friendly-but-contaminated).
• Path B (institutional): Detective reports {THE FRIEND} immediately. RelationshipState → Hostile. {THE FRIEND} is reprimanded or reassigned. Color → red. The detective loses their only local ally.

THE FRIEND pattern: The detective's trust in {THE FRIEND} is tested. Amber means "my contact is hiding something." The resolution determines whether the friendship survives.

---

Contradiction Patterns: Smuggler vs. Detective Paths

Both THE FRIEND NPCs follow the same structural arc, but the nature of the contradiction differs:

Dimension	{THE FRIEND} — Smuggler Path	{THE FRIEND} — Detective Path
Contradiction type	Spatial deviation (meeting unknown contact)	Behavioral avoidance (leaving when a suspect arrives)
Discovery method	Direct observation in restricted area	Pattern recognition over multiple visits
What they're hiding	Attempt to exit the ring (protect someone close)	Unreported evidence (protect a third party)
Sympathetic motivation	Personal protection (someone they care about)	Friendship loyalty (mutual third-party connection)
Third-party connection	{THE FRIEND}'s personal life	{THE FRIEND}'s social network
Color shift timing	Single observation event (immediate)	Third occurrence (cumulative)
Confrontation stakes	Ring security vs. personal loyalty	Institutional duty vs. personal loyalty
Resolution spectrum	Understanding ↔ Betrayal	Protect friend ↔ Report corruption

Common structure: Both contradictions involve a shared third party as the emotional anchor — someone both THE FRIEND NPCs are trying to protect, approached from opposite sides of the case.

---

KnowledgeState Integration

RelationshipState (social assessment) is orthogonal to KnowledgeState (logical validity).

Active (default)

What it means: The knowledge is currently believed true.

Effect on relationship: None directly. A Friendly NPC with Active knowledge remains Friendly.

Example: Smuggler's knowledge of {THE FRIEND} as "trusted colleague" is Active until the contradiction.

---

Contradicted

What it means: Conflicting information exists. Both the original belief and the contradiction receive this state.

Effect on relationship: This is the trigger for Friendly → PersonOfInterest.

When KnowledgeState becomes Contradicted, the system:

1. Sets EntityKnowledge.state = KnowledgeState::Contradicted on the conflicting knowledge entries.
2. Triggers a monologue event: "Wait, that doesn't match what I thought I knew."
3. Evaluates RelationshipState transition. If the contradicted knowledge is about a Friendly NPC, transition to PersonOfInterest.

Example: Smuggler's knowledge "{THE FRIEND} operates within ring protocol" contradicts with new observation "{THE FRIEND} meeting unauthorized contact." Both entries become Contradicted. Monologue fires. {THE FRIEND}'s RelationshipState → PersonOfInterest.

---

Stale

What it means: Knowledge has aged beyond the stale threshold (default 3600 ticks = 6 game-hours).

Effect on relationship: Degrades confidence but doesn't change relationship state. A Friendly NPC remains Friendly, but positional knowledge becomes unreliable.

Example: Smuggler last saw {THE FRIEND} at the hub 7 hours ago. last_known_position becomes Stale. Monologue: "{THE FRIEND} should be off-shift by now. Probably at the bar, but I haven't seen them."

---

Relationship State and Dialogue Selection

The dialogue system (D-028, D-035) uses RelationshipState as a filter:

Dialogue access tag	Unknown	Known	Friendly	PersonOfInterest	Hostile
public	✓	✓	✓	✓	✓
peer	✗	✓	✓	✗	✗
insider	✗	✗	✓	✗	✗
authority	✓ (if detective)	✓ (if detective)	✗	✓ (if detective)	✗
hostile	✗	✗	✗	✗	✓

Key insight: PersonOfInterest locks out peer and insider content. When THE FRIEND transitions to PersonOfInterest, trust-gated dialogue disappears. The NPC becomes guarded. This is mechanically expressed through access-tier filtering.

---

Monologue Tone Shifts per State

Unknown → Known

• Before: "Who's that?"
• After: "That's the maintenance tech."

Shift: Identification. Observer now has context.

---

Known → Friendly

• Before: "They're over there."
• After: "Good to see them. Always fixes things without making a fuss."

Shift: Warmth. Personal regard.

---

Friendly → PersonOfInterest (THE FRIEND)

• Before: "There's {THE FRIEND}. Good — I was starting to worry."
• After: "{THE FRIEND}'s here. But they've been acting strange. What's going on?"

Shift: Doubt contaminates warmth. The fond observation is now analytical.

---

PersonOfInterest → Hostile

• Before: "{THE FRIEND}'s avoiding me. Something's wrong."
• After: "{THE FRIEND} just signaled security. They've turned on me."

Shift: Assessment → alarm.

---

Implementation Notes for Content Authors

• Contradiction discovery sets EntityKnowledge.state = KnowledgeState::Contradicted AND triggers RelationshipState transition if applicable.
• Monologue lines should reference RelationshipState in prerequisites:

  prerequisite:
    relationship_state: PersonOfInterest
    subject: {npc_id}
  

• Dialogue lines filter on access tier, which is derived from RelationshipState + character type (smuggler/detective/NPC role).
• Color shifts are client-side rendering, but the knowledge graph determines the state. Content authors write to the state; the client handles the color.
• THE FRIEND arc requires:
  • Friendly baseline (relationship history)
  • Observable contradiction (spatial deviation or behavioral pattern)
  • contradiction_flagged attribute set
  • Monologue shift (analytical doubt)
  • Dialogue shift (confrontation options unlock, trust options lock)
  • Resolution paths (multiple endings based on player choice)

---

Total states: 5. Load-bearing transitions: Unknown → Known (universal), Known/Friendly → PersonOfInterest (THE FRIEND), PersonOfInterest → Hostile (confrontation failure). Other transitions exist but are less structurally critical.