settled-reach/server/src/perception/observer/mod.rs

//! Observer visibility query system (#112)
//!
//! Two-stage pipeline:
//! 1. compute_visibility_geometry — FOV + vision cone → VisibilityGeometry resource
//! 2. compute_observer_snapshot — entity filtering + knowledge overlay → ObserverSnapshot
//!
//! D-017 perception modes swap the geometry producer via PerceptionQuery trait.

use bevy_ecs::prelude::*;
use std::collections::HashSet;

use crate::bridge::types::*;
use crate::knowledge::types::KnowledgeState;
use crate::knowledge::{EntityRegistry, KnowledgeGraph, StableId};
use crate::perception::query::{ActivePerceptionMode, VisibilityGeometry};
use crate::perception::vision_cone::Facing;
use crate::simulation::interaction::NearbyInteractionBuffer;
use crate::simulation::inventory::{CarriedBy, InventorySlot, ItemName};
use crate::simulation::monologue::MonologueBuffer;
use crate::simulation::movement::{PlayerCharacter, TilePosition, WalkabilityMap};
use crate::simulation::stance::Stance;
use crate::simulation::time::SimulationTime;

/// Compute visibility geometry using the active perception mode.
/// Stage 1 of the observer pipeline: FOV + vision cone → VisibilityGeometry.
///
/// System ordering: after validate_movement, before compute_observer_snapshot.
pub fn compute_visibility_geometry(
    walkability: Res<WalkabilityMap>,
    mode: Res<ActivePerceptionMode>,
    observer_query: Query<(&TilePosition, Option<&Facing>), With<PlayerCharacter>>,
    mut geometry: ResMut<VisibilityGeometry>,
) {
    let Ok((observer_pos, facing_opt)) = observer_query.single() else {
        return;
    };

    let facing = facing_opt
        .map(|f| f.0)
        .unwrap_or(FacingDirection::default());

    *geometry = mode.0.compute_geometry(observer_pos, facing, &walkability);
}

/// Assemble observer snapshot from precomputed geometry and entity state.
/// Stage 2 of the observer pipeline: entity filtering + knowledge overlay → snapshot.
///
/// System ordering: after compute_visibility_geometry + compute_nearby_interactions,
/// before advance_tick.
#[allow(clippy::type_complexity)]
pub fn compute_observer_snapshot(
    time: Res<SimulationTime>,
    geometry: Res<VisibilityGeometry>,
    registry: Res<EntityRegistry>,
    mut observer_query: Query<
        (Entity, &TilePosition, Option<&Facing>, &KnowledgeGraph, &mut NearbyInteractionBuffer, &mut MonologueBuffer, Option<&Stance>, Option<&CharacterArchetype>),
        With<PlayerCharacter>,
    >,
    all_entities: Query<(
        Entity,
        &TilePosition,
        Option<&PlayerCharacter>,
        Option<&crate::npc::Npc>,
    )>,
    inventory_items: Query<(Entity, &CarriedBy, &ItemName, &InventorySlot)>,
    mut buffer: ResMut<SnapshotBuffer>,
) {
    let Ok((observer_entity, _observer_pos, facing_opt, observer_kg, mut interaction_buffer, mut monologue_buffer, stance_opt, archetype_opt)) =
        observer_query.single_mut()
    else {
        return;
    };

    let facing = facing_opt
        .map(|f| f.0)
        .unwrap_or(FacingDirection::default());

    let archetype = archetype_opt.copied().unwrap_or_default();

    // Collect player inventory (D-065 info boundary: only own items)
    let player_inventory = registry
        .to_stable(observer_entity)
        .map(|player_sid| {
            crate::simulation::inventory::collect_inventory_for(
                player_sid,
                &inventory_items,
                &registry,
            )
        })
        .unwrap_or_default();

    let (mut entities, visible_ids) =
        filter_visible_entities(&geometry, &registry, observer_kg, &all_entities);

    collect_remembered_entities(
        observer_kg,
        &visible_ids,
        &geometry.visible_positions,
        geometry.observer_z,
        time.tick,
        &mut entities,
    );

    let game_time = GameTime {
        day: time.day(),
        time_of_day: time.time_of_day_minutes(),
        day_phase: time.day_phase(),
        tick_rate: time.tick_rate,
    };

    // Take interactions and apply Phase 2 verb filter (D-057, #422)
    let mut nearby_interactions = interaction_buffer.take();
    apply_phase2_verb_filter(&mut nearby_interactions, observer_kg, archetype);

    tracing::trace!(
        "compute_observer_snapshot: tick={}, visible={}, remembered={}, tiles={}",
        time.tick,
        visible_ids.len(),
        entities.len() - visible_ids.len(),
        geometry.visible_tiles.len(),
    );

    let current_monologue = monologue_buffer.take();

    buffer.snapshot = Some(ObserverSnapshot {
        version: crate::bridge::types::PROTOCOL_VERSION,
        tick: time.tick,
        game_time,
        player_facing: facing,
        player_stance: stance_opt.map(|s| s.0).unwrap_or_default(),
        player_inventory,
        entities,
        visible_tiles: geometry.visible_tiles.clone(),
        nearby_interactions,
        current_monologue,
    });
}

/// Filter entities by visibility using precomputed geometry.
/// Returns (visible entities, set of visible wire IDs).
#[allow(clippy::type_complexity)]
fn filter_visible_entities(
    geometry: &VisibilityGeometry,
    registry: &EntityRegistry,
    observer_kg: &KnowledgeGraph,
    all_entities: &Query<(
        Entity,
        &TilePosition,
        Option<&PlayerCharacter>,
        Option<&crate::npc::Npc>,
    )>,
) -> (Vec<VisibleEntity>, HashSet<u64>) {
    let mut entities = Vec::new();
    let mut visible_ids: HashSet<u64> = HashSet::new();

    for (entity, pos, is_player, is_npc) in all_entities.iter() {
        if pos.z != geometry.observer_z {
            continue;
        }
        if !geometry.visible_positions.contains(&(pos.x, pos.y)) {
            continue;
        }

        let (rx, ry, rz) = pos.to_render_coords();
        let kind = if is_player.is_some() {
            EntityKind::Player
        } else if is_npc.is_some() {
            EntityKind::Npc
        } else {
            EntityKind::Object
        };

        let sector = geometry
            .sector_lookup
            .get(&(pos.x, pos.y))
            .copied()
            .unwrap_or(VisibilitySector::Peripheral);

        let relationship = if is_player.is_some() {
            RelationshipState::Known // Self
        } else if let Some(stable_id) = registry.to_stable(entity) {
            observer_kg.relationship_with(&stable_id)
        } else {
            RelationshipState::Unknown
        };

        // Fallback to Entity::to_bits() is intentional for per-frame systems:
        // panicking would crash the server every tick. The error log makes this
        // loud enough to catch in testing while keeping the server alive.
        let wire_id = registry
            .to_stable(entity)
            .map(|sid| sid.0)
            .unwrap_or_else(|| {
                tracing::error!(?entity, "entity visible but not in EntityRegistry");
                entity.to_bits()
            });
        visible_ids.insert(wire_id);
        entities.push(VisibleEntity {
            entity_id: wire_id,
            x: rx,
            y: ry,
            z: rz,
            kind,
            visibility: sector,
            relationship,
            observation: EntityVisibility::Visible,
        });
    }

    (entities, visible_ids)
}

/// Collect remembered entities from the knowledge graph — entities the observer
/// knows about but can't currently see. Filters out: already-visible entities,
/// entities without known positions, wrong z-level, visible-tile ghosts, and
/// transient Direct-confidence inconsistencies.
fn collect_remembered_entities(
    observer_kg: &KnowledgeGraph,
    visible_ids: &HashSet<u64>,
    visible_positions: &HashSet<(i32, i32)>,
    observer_z: i32,
    current_tick: u64,
    entities: &mut Vec<VisibleEntity>,
) {
    for (stable_id, knowledge) in observer_kg.known_entities_iter() {
        if visible_ids.contains(&stable_id.0) {
            continue;
        }

        let Some(position) = knowledge.last_known_position else {
            continue;
        };

        if position.z != observer_z {
            continue;
        }

        // Tile is visible but entity isn't there — player knows it moved
        if visible_positions.contains(&(position.x, position.y)) {
            continue;
        }

        // Direct confidence = should be in LOS; skip transient inconsistency
        if knowledge.confidence == KnowledgeConfidence::Direct {
            continue;
        }

        let (rx, ry, rz) = position.to_render_coords();
        debug_assert!(
            knowledge.last_observed_tick <= current_tick,
            "last_observed_tick {} > current tick {}",
            knowledge.last_observed_tick,
            current_tick,
        );
        let age_ticks = current_tick.saturating_sub(knowledge.last_observed_tick);

        entities.push(VisibleEntity {
            entity_id: stable_id.0,
            x: rx,
            y: ry,
            z: rz,
            kind: EntityKind::Npc,
            visibility: VisibilitySector::Forward,
            relationship: knowledge.relationship,
            observation: EntityVisibility::Remembered {
                confidence: knowledge.confidence,
                age_ticks,
            },
        });
    }
}

/// Phase 2 verb filter: KG-gated observer-side verb processing (#422, D-057).
///
/// Runs after Phase 1 (simulation-level verb computation) and applies:
/// 1. POI priority flips (D-060) — ExamineNpc above Talk for POI entities
/// 2. Confront injection — adds Confront verb for NPCs when KnowsDetails+
/// 3. Contradiction marking — sets contradicted flag when entity knowledge is Contradicted
/// 4. Archetype label relabeling — smuggler/detective see different labels for same verb
///
/// Phase boundary: Phase 1 (interaction.rs) determines verb availability from
/// ObjectType + proximity. Phase 2 (here) reads the observer's KnowledgeGraph
/// to filter, augment, and relabel. This separation keeps D-010 principle 1
/// (info boundary) clean — simulation doesn't know what the observer knows.
fn apply_phase2_verb_filter(
    interactions: &mut [NearbyInteraction],
    observer_kg: &KnowledgeGraph,
    archetype: CharacterArchetype,
) {
    for interaction in interactions.iter_mut() {
        let stable_id = StableId(interaction.entity_id);
        let knowledge = observer_kg.entity_knowledge(&stable_id);

        // --- Contradiction marking ---
        // If observer's knowledge of this entity is Contradicted, mark the
        // interaction. Client renders a visual indicator (D-041).
        if let Some(k) = knowledge {
            if k.state == KnowledgeState::Contradicted {
                interaction.contradicted = true;
            }
        }

        // --- NPC-specific Phase 2 ---
        if interaction.entity_type == EntityKind::Npc {
            let relationship = observer_kg.relationship_with(&stable_id);

            // POI priority flip (D-060): Observe first, Talk second
            if relationship == RelationshipState::PersonOfInterest {
                for verb in &mut interaction.verbs {
                    match verb.kind {
                        VerbKind::ExamineNpc => verb.priority = 1,
                        VerbKind::Talk => verb.priority = 2,
                        _ => {}
                    }
                }
            }

            // Confront injection: available when observer has KnowsDetails+
            // on this NPC and is at close range (distance ≤ 2).
            if interaction.distance <= 2 {
                let has_details = knowledge
                    .map(|k| k.confidence >= KnowledgeConfidence::KnowsDetails)
                    .unwrap_or(false);

                if has_details {
                    // Priority 3 = after Talk/ExamineNpc in normal case,
                    // after ExamineNpc/Talk in POI case. Always the escalation option.
                    interaction.verbs.push(VerbOption {
                        kind: VerbKind::Confront,
                        label: "Confront".into(),
                        priority: 3,
                        available: true,
                    });
                }
            }
        }

        // --- Archetype label relabeling ---
        // Phase 2 swaps verb labels based on character archetype.
        // The VerbKind stays the same (same handler), only the display label changes.
        // This implements D-057: "Character differentiation via Phase 2 observer
        // filter, not separate verb systems."
        for verb in &mut interaction.verbs {
            if let Some(label) = archetype_verb_label(archetype, interaction.object_type, verb.kind) {
                verb.label = label.into();
            }
        }

        // Re-sort after priority changes and verb additions
        interaction.verbs.sort_by_key(|v| (v.priority, v.kind as u8));
    }
}

/// Archetype-specific verb label overrides (#422, D-057).
///
/// Returns a replacement label for the given (archetype, object_type, verb_kind)
/// combination, or None to keep the Phase 1 default label.
///
/// v0.1: Container verbs differ by archetype. Other object types keep defaults.
/// Add match arms here for future archetype-specific labels.
fn archetype_verb_label(
    archetype: CharacterArchetype,
    object_type: Option<ObjectType>,
    kind: VerbKind,
) -> Option<&'static str> {
    match (archetype, object_type, kind) {
        // Smuggler: Container verbs — physical manipulation vocabulary
        (CharacterArchetype::Smuggler, Some(ObjectType::Container), VerbKind::Open) => Some("Move"),
        (CharacterArchetype::Smuggler, Some(ObjectType::Container), VerbKind::Search) => Some("Stash"),

        // Detective: Container verbs — investigation vocabulary
        (CharacterArchetype::Detective, Some(ObjectType::Container), VerbKind::Open) => Some("Scan"),
        (CharacterArchetype::Detective, Some(ObjectType::Container), VerbKind::Search) => Some("Flag"),

        // All other combinations: keep Phase 1 default label
        _ => None,
    }
}

#[cfg(test)]
mod tests;