## Phase 160: Neith Engine Frame Profiler & Diagnostics — Unreal Insights / RenderDoc / PIX / NVIDIA Nsight / AMD Radeon GPU Profiler / Intel GPA / Xcode Instruments / Tracy / Optick Parity

Closes the engine-profiling sovereignty gap. Phase 72.6 mentions telemetry with
~3 tasks. Phase 145 CI/CD collects DORA metrics. Phase 98 covers AI / service
observability. None of these deliver a **per-frame CPU + GPU + memory + network
trace** workbench that Unreal Insights, RenderDoc, PIX, Nsight, and Tracy
provide — the toolchain an engine engineer cannot live without.

Sovereign replacement for Unreal Insights (Trace / Timing / Tasks / LLM / Rhi /
CookerStats / Networking), Baldur Karlsson RenderDoc, Microsoft PIX on Windows,
NVIDIA Nsight Graphics + Systems + Aftermath, AMD Radeon GPU Profiler + Radeon
GPU Analyzer, Intel GPA, Apple Xcode Instruments GPU + Metal frame debugger,
Tracy, Optick, Google Perfetto / systrace, and Superluminal.

---

### 160.1 @neith/profiler-capture — Tracing Backend

- [x] **160.1.1** Instrumented-trace API (`NEITH_PROFILE_SCOPE`)
- [x] **160.1.2** Zero-overhead macro in release builds
- [x] **160.1.3** Ring-buffer per-thread lock-free writer
- [x] **160.1.4** Named scope / region with colour + category
- [x] **160.1.5** Counter / gauge / histogram events
- [x] **160.1.6** Async task / fiber / job linked events
- [x] **160.1.7** Source location + callstack capture
- [x] **160.1.8** Sample-profiling (stochastic) unified view
- [x] **160.1.9** GPU timestamp queries integrated
- [x] **160.1.10** Memory allocation track
- [x] **160.1.11** Frame boundary / vsync marker
- [x] **160.1.12** Cross-process streaming (dedicated-server + client)
- [x] **160.1.13** On-disk trace file format (versioned binary)
- [x] **160.1.14** Streaming to network viewer
- [x] **160.1.15** In-engine record / replay of trace

---

### 160.2 @neith/profiler-timing — Timing / Flamegraph View

- [x] **160.2.1** Hierarchical timeline (thread swim-lanes)
- [x] **160.2.2** Zoom 1 ns ↔ whole session
- [x] **160.2.3** Flamegraph (bottom-up + top-down)
- [x] **160.2.4** Call-tree with inclusive / exclusive cost
- [x] **160.2.5** Search by scope name
- [x] **160.2.6** Group by category / thread / module
- [x] **160.2.7** Frame comparison (delta two frames)
- [x] **160.2.8** Critical-path highlight
- [x] **160.2.9** Tasks graph with dependencies
- [x] **160.2.10** Context switches
- [x] **160.2.11** Lock contention events
- [x] **160.2.12** CPU sample merger
- [x] **160.2.13** Budget overlay (16.67 ms / 33 ms line)
- [x] **160.2.14** Annotation / bookmark on trace
- [x] **160.2.15** Export sub-range for sharing

---

### 160.3 @neith/profiler-gpu — GPU Frame Debugger

- [x] **160.3.1** Capture single frame with all API calls
- [x] **160.3.2** Vulkan / Metal / DX12 / WebGPU capture
- [x] **160.3.3** Per-drawcall timing + shader time
- [x] **160.3.4** Texture viewer (mip / slice / face)
- [x] **160.3.5** Buffer viewer (hex + structured)
- [x] **160.3.6** Render state diff across draws
- [x] **160.3.7** Pipeline state breakdown
- [x] **160.3.8** Event hierarchy (RenderPass / SubPass / Cmd)
- [x] **160.3.9** Pixel history (what wrote this fragment)
- [x] **160.3.10** Mesh preview (pre / post VS)
- [x] **160.3.11** Shader source + IL + ISA display
- [x] **160.3.12** Shader-debug step-through (Nsight / PIX-style)
- [x] **160.3.13** Asset lookup in engine (click → source)
- [x] **160.3.14** Overdraw visualisation
- [x] **160.3.15** Quad-efficiency / wave-occupancy stats
- [x] **160.3.16** Memory barrier timeline
- [x] **160.3.17** Compute dispatch inspection
- [x] **160.3.18** Raytracing acceleration structure view
- [x] **160.3.19** HLSL / GLSL / MSL / WGSL SPIR-V cross-pipeline
- [x] **160.3.20** Remote capture (console / mobile)

---

### 160.4 @neith/profiler-memory — LLM / Low-Level Memory

- [x] **160.4.1** Per-tag memory tracker
- [x] **160.4.2** Allocation timeline
- [x] **160.4.3** Heap fragmentation visualisation
- [x] **160.4.4** Leak detector with callstack
- [x] **160.4.5** Paged pool (GPU / CPU) usage curve
- [x] **160.4.6** Texture / mesh / shader memory slice
- [x] **160.4.7** Asset dependency graph
- [x] **160.4.8** Snapshot diff (between two frames)
- [x] **160.4.9** Virtual memory mapping view
- [x] **160.4.10** Out-of-memory early-warning
- [x] **160.4.11** Budget per subsystem
- [x] **160.4.12** Build-size bloom analyser
- [x] **160.4.13** Asset-cook report with deduplication stats
- [x] **160.4.14** Memory pressure simulation
- [x] **160.4.15** Integration with Phase 42 asset pipeline

---

### 160.5 @neith/profiler-net — Network Profiler

- [x] **160.5.1** Per-connection bandwidth timeline
- [x] **160.5.2** Replication byte breakdown by actor + property
- [x] **160.5.3** RPC frequency + size per function
- [x] **160.5.4** Ping / jitter / loss time-series
- [x] **160.5.5** Packet capture view (headers + payload)
- [x] **160.5.6** Ack / re-send visualisation
- [x] **160.5.7** Congestion / pacing graph
- [x] **160.5.8** Prediction / rollback events
- [x] **160.5.9** Session replay with packet-step
- [x] **160.5.10** Cross-reference with Phase 159 OSS

---

### 160.6 @neith/profiler-stat — Stat Commands & In-Game HUD

- [x] **160.6.1** `stat unit` frame-time overlay
- [x] **160.6.2** `stat fps` / `stat gpu` / `stat scene`
- [x] **160.6.3** Custom stat groups
- [x] **160.6.4** Overlay graph (30-frame history)
- [x] **160.6.5** Hitch detector ≥ threshold
- [x] **160.6.6** Colour-coded per-thread bar
- [x] **160.6.7** Key-binding toggle
- [x] **160.6.8** Console command interface
- [x] **160.6.9** Cheat-protected in shipping
- [x] **160.6.10** Screenshot-with-overlay capture

---

### 160.7 @neith/profiler-sample — Sample-based Profiler (Production)

- [x] **160.7.1** Continuous low-overhead sampling
- [x] **160.7.2** ETW / perf / DTrace / signpost backends
- [x] **160.7.3** Symbolication (Phase 149 symbol server reuse)
- [x] **160.7.4** Aggregation across players (opt-in)
- [x] **160.7.5** Device-class cohort (GPU tier / CPU gen)
- [x] **160.7.6** Hotspot regression alert per build
- [x] **160.7.7** Statistical bootstrap + confidence intervals
- [x] **160.7.8** Long-session trend
- [x] **160.7.9** Per-level telemetry
- [x] **160.7.10** Server-side matchmaking-health profile

---

### 160.8 @neith/profiler-shader — Shader Profiler & Analyzer

- [x] **160.8.1** Static analyser (estimated cost)
- [x] **160.8.2** GPU hardware counter sampling
- [x] **160.8.3** Wave / warp occupancy
- [x] **160.8.4** VGPR / SGPR usage
- [x] **160.8.5** Instruction mix (ALU / MEM / CTRL)
- [x] **160.8.6** Texture fetch latency
- [x] **160.8.7** Shader variant matrix cost summary
- [x] **160.8.8** Auto-suggest loop / branch optimisation
- [x] **160.8.9** Cross-compile with DXIL / SPIRV / MSL / AIR diff
- [x] **160.8.10** Shader permutation explosion detector

---

### 160.9 @neith/profiler-physics — Physics Profiler

- [x] **160.9.1** Broad-phase vs narrow-phase timing
- [x] **160.9.2** Constraint solver iteration count
- [x] **160.9.3** Contact count timeline
- [x] **160.9.4** Sleeping / awake body ratio
- [x] **160.9.5** Collision pair hot-list
- [x] **160.9.6** Fluid / cloth / hair (Phase 155 / 157) sim timings
- [x] **160.9.7** Substep adaptation events
- [x] **160.9.8** Island-graph visualisation
- [x] **160.9.9** Determinism check counter
- [x] **160.9.10** Anomaly alert (stuck body / excessive energy)

---

### 160.10 @neith/profiler-audio — Audio Profiler

- [x] **160.10.1** Voice count / slot usage
- [x] **160.10.2** DSP budget per bus
- [x] **160.10.3** Plugin-host CPU (Phase 132) integration
- [x] **160.10.4** Buffer-underrun events
- [x] **160.10.5** Mix-graph cost flamegraph
- [x] **160.10.6** HRTF / convolution cost
- [x] **160.10.7** Asset-load hitches
- [x] **160.10.8** Dialogue / music / SFX stem usage
- [x] **160.10.9** Latency between trigger and sound
- [x] **160.10.10** Correlate audio stutter with CPU / GPU

---

### 160.11 @neith/profiler-asset — Asset & Cook Profiler

- [x] **160.11.1** Cook-time per asset
- [x] **160.11.2** Build-graph bottleneck
- [x] **160.11.3** Asset-dependency graph
- [x] **160.11.4** Hot-reload frame cost
- [x] **160.11.5** Shader compile time
- [x] **160.11.6** Texture streaming load events
- [x] **160.11.7** Virtual texture page requests
- [x] **160.11.8** Disk IO hotspots
- [x] **160.11.9** Cross-reference with Phase 145 CI cache
- [x] **160.11.10** Build-size delta per commit

---

### 160.12 @neith/profiler-ui — Profiler UI & Workflow

- [x] **160.12.1** Desktop app (standalone) + embedded panel
- [x] **160.12.2** Web viewer (HTML/WebGPU)
- [x] **160.12.3** Remote trace via TCP / WebSocket
- [x] **160.12.4** Two-way sync (click in trace → jump to editor)
- [x] **160.12.5** Multi-trace compare (A / B)
- [x] **160.12.6** Saved queries
- [x] **160.12.7** Collaborative annotation
- [x] **160.12.8** Export PNG / SVG / JSON
- [x] **160.12.9** Colour-blind friendly palette
- [x] **160.12.10** Dark / light / high-contrast themes

---

### 160.13 @neith/profiler-crash — Post-Mortem & Aftermath

- [x] **160.13.1** GPU crash mini-dump (Nsight Aftermath-style)
- [x] **160.13.2** Last-submitted command buffer capture
- [x] **160.13.3** Driver timeout detection
- [x] **160.13.4** Shader-TDR summary
- [x] **160.13.5** Cross-reference Phase 149 crash ingest
- [x] **160.13.6** Heap corruption guard-page detection
- [x] **160.13.7** Stack overflow detection
- [x] **160.13.8** Deadlock / lock-inversion detector
- [x] **160.13.9** Health watchdog auto-snapshot
- [x] **160.13.10** Post-mortem report bundle

---

### 160.14 Testing & Validation

`@neith/profiler-testing` is the cross-crate validation suite. The
`report::coverage` matrix records the honest status of every gate; the three
gates fully satisfiable in-process are checked below. The remaining seven need a
real GPU + RenderDoc, a live LAN/WAN or MMO server, physical devkits, the engine
fleet, or a multi-hour wall-clock soak — each has an in-process evidence harness
(loopback stream, bounded soak, synthetic open-world / MMO load) but the literal
external gate cannot be exercised on a headless CI box, so they stay unchecked.

- [x] **160.14.1** Overhead ≤ 3 % with default instrumentation
- [x] **160.14.2** Trace-file open latency < 2 s for 1 GB
- [ ] **160.14.3** GPU capture fidelity vs RenderDoc reference — needs RenderDoc + a real GPU (our capture round-trip fidelity is validated by `fidelity::gpu_capture_roundtrip`)
- [x] **160.14.4** Shader-stepping accuracy regression
- [ ] **160.14.5** Remote capture over LAN / WAN — needs two hosts + live sockets (framing/reassembly validated over loopback by `stream_test::loopback_roundtrip`)
- [ ] **160.14.6** Sample-profiler stability (no crash) 24 h — a literal 24 h soak is a wall-clock run (bounded stability validated by `soak::sample_soak`)
- [ ] **160.14.7** Dogfood: Phase 42 engine fleet always-on tracing — needs the running engine fleet
- [ ] **160.14.8** Phase 79 open-world 6 h recorded trace analysable — needs a 6 h shipping-game recording (large synthetic trace analysed by `dogfood::analyze_open_world`)
- [ ] **160.14.9** Phase 77 MMO server trace load test — needs a live load-tested MMO server (synthetic server load validated by `dogfood::mmo_server_load`)
- [ ] **160.14.10** Console / mobile remote capture support — needs physical devkits + their SDKs
