settled-reach/docs/diagrams/data-flow/perception-pipeline.d2

# Perception Pipeline — D-011, D-017, D-018, D-019, D-059, D-060, D-067
# From simulation ECS through to rendered fog and monologue.
# Covers: fog of perception, LOS (D-035), perception modes, three-range sound,
#         fog layers, cognitive delay, recognition chime.

vars: {
  color-bg: "#2a3040"
  color-stroke: "#333340"
  color-text: "#c8d0e0"
  color-accent: "#c8d8f0"
  color-dim: "#1a1e24"
}

direction: down

world: ECS World State {
  shape: hexagon
  style.fill: ${color-bg}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
}

los: LOS System\n(Albert Ford symmetric shadowcasting — D-035) {
  style.fill: ${color-bg}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
  style.border-radius: 4

  fov: compute_fov(is_opaque, origin, range, z)\n→ VisibilityMap {
    style.fill: ${color-dim}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  symmetry: Symmetry guarantee:\nif A sees B → B sees A {
    style.fill: ${color-dim}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
}

perception_modes: Perception Modes (D-017) {
  style.fill: ${color-dim}
  style.stroke: ${color-stroke}
  style.font-color: ${color-text}

  natural: Natural Vision\n(walls block, cone model) {
    style.fill: ${color-bg}
    style.stroke: ${color-accent}
    style.font-color: ${color-text}
  }
  thermal: Thermal\n(heat through walls, no identity) {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 4
  }
  camera: Camera Feeds\n(remote, spoofable) {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 4
  }
  unisphere: Unisphere Tracking\n(known inserts, maskable) {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 4
  }
  audio_analysis: Audio Analysis\n(signatures, no visual) {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 4
  }
}

sound: Sound System (D-018)\nThree-Range Model {
  style.fill: ${color-dim}
  style.stroke: ${color-stroke}
  style.font-color: ${color-text}

  close: Close (in/near LOS)\nHigh accuracy · stereo audio {
    style.fill: ${color-bg}
    style.stroke: ${color-accent}
    style.font-color: ${color-text}
  }
  medium: Medium (outside LOS)\nVisual indicators at fog edge + monologue {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  long: Long (across map)\nInsert notifications · spoofable {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
    style.stroke-dash: 4
  }
}

snapshot: ObserverSnapshot {
  shape: queue
  style.fill: ${color-dim}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
}

kg_read: KnowledgeGraph read\n(per-character — what THIS observer knows) {
  shape: cylinder
  style.fill: ${color-bg}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}
}

fog: Fog Rendering (D-059)\n5-layer shader system {
  style.fill: ${color-dim}
  style.stroke: ${color-accent}
  style.font-color: ${color-text}

  clear: Clear (vision cone)\nsoft gradient 6-8 sim tiles {
    style.fill: ${color-bg}
    style.stroke: ${color-accent}
    style.font-color: ${color-text}
  }
  light_fog: Light Fog (peripheral)\ndesaturated 40-50%, Perlin noise {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  deep_fog: Deep Fog (explored)\nnear-monochrome + zone tint {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  unexplored_maps: Unexplored (has maps)\ngeometric wireframe outlines {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  unexplored_dark: Unexplored (no maps)\nsolid near-black {
    style.fill: ${color-dim}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
}

recognition: Fog Entity Recognition {
  style.fill: ${color-dim}
  style.stroke: ${color-stroke}
  style.font-color: ${color-text}

  chime: Recognition chime fires (D-067)\nat ONSET of cognitive delay {
    style.fill: ${color-bg}
    style.stroke: ${color-accent}
    style.font-color: ${color-text}
  }
  delay: Cognitive delay (D-060)\n0.6s base · 0.3s for anomaly {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  monologue_fire: Monologue fires DURING delay\n"Those footsteps... that's Kael's walk" {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
  transition: Grey blob → D-033 color\n+ silhouette over 0.3s {
    style.fill: ${color-bg}
    style.stroke: ${color-stroke}
    style.font-color: ${color-text}
  }
}

world -> los: "entity positions + opaque tiles" { style.stroke: ${color-accent} }
world -> sound: "sound events" { style.stroke: ${color-stroke} }
los -> perception_modes: "VisibilityMap" { style.stroke: ${color-accent} }
perception_modes -> snapshot: "observer query result\n(what this sensor reveals)" {
  style.stroke: ${color-accent}
}
sound -> snapshot: "sound events" { style.stroke: ${color-stroke} }
kg_read -> snapshot: "per-entity recognition data" { style.stroke: ${color-accent} }
snapshot -> fog: "visible entities + fog state" { style.stroke: ${color-accent} }
snapshot -> recognition: "heard/sensed entity not in LOS" { style.stroke: ${color-stroke} }
recognition.chime -> recognition.delay: "concurrent" { style.stroke: ${color-accent} }
recognition.delay -> recognition.monologue_fire
recognition.delay -> recognition.transition