# Phase 8: Robustness and Logging - Context

**Gathered:** 2026-03-23
**Status:** Ready for planning

<domain>
## Phase Boundary

Harden the driver for production use. Ensure it never crashes vrserver.exe, degrades gracefully when HID is unavailable, and logs meaningful events (state transitions, errors) without spamming raw values.

</domain>

<decisions>
## Implementation Decisions

### Graceful degradation (RBST-01)
- HID open failure already returns VRInitError_None (Phase 2) — verify this path is complete
- When HID is unavailable, proximity features silently disabled: no SetBoolProperty calls, no RunFrame polling
- Driver must still create named pipe and respond to status commands (reporting "HID: not connected")

### State-change logging (RBST-02)
- Log on-head/off-head transitions with DriverLog: `"Proximity: person_detected changed to %s"` (true/false)
- Log only on state CHANGE, not every RunFrame poll — use existing state-change guard pattern from Phase 3.1
- No raw value logging at default verbosity — that's already behind log_verbosity from Phase 7

### Error and warning logging (RBST-03)
- Maintain existing ad-hoc prefix convention (HID:, Pipe:, Proximity:, Config:) — consistent with 30+ existing log lines
- Log these events: HID open failure, calibration read failure, USB disconnect, USB reconnect, pipe creation failure
- Most of these are already logged — audit and fill gaps rather than rewriting

### Crash prevention (RBST-04)
- Null-check defensive guards at key boundaries (m_pHidDevice before use, pipe handle before operations)
- No SEH (__try/__except) or C++ exceptions — keep C-style error returns consistent with existing codebase
- Ensure reader thread catches all hid_read/hid_write failures without propagating
- Validate pipe command input (buffer bounds, null termination) before processing

### Claude's Discretion
- Exact placement of null guards (audit codebase to find gaps)
- Whether to add a "degraded mode" flag or just check HID state each RunFrame
- Log message wording and format details

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Requirements
- `.planning/REQUIREMENTS.md` — RBST-01 through RBST-04 define exact acceptance criteria

### Prior phase context
- `.planning/phases/07-configuration/07-CONTEXT.md` — log_verbosity flag design, VRSettings patterns
- `.planning/phases/04-hid-data-pipeline/04-CONTEXT.md` — HID reconnect loop design, reader thread architecture
- `.planning/phases/03.1-remove-virtual-tracker/03.1-CONTEXT.md` — State-change guard pattern (m_bProximity)

### Implementation reference
- `src/driver/device_provider.cpp` — Main driver logic, RunFrame, pipe handler, SetHmdProximity
- `src/hid/hid_device.cpp` — HID open/close, reader thread, reconnect loop, calibration read
- `src/hid/hid_device.h` — Connection state machine (0=closed, 1=open, 2=reconnecting)
- `src/hid/proximity_algorithm.cpp` — Algorithm with no external error surfaces

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `DriverLog()` — Already used at 30+ call sites, consistent pattern
- `m_connectionState` atomic — 3-state machine (closed/open/reconnecting) for HID status
- `m_bProximity` state-change guard — Prevents duplicate SetBoolProperty writes, reuse pattern for transition logging
- `m_logVerbose` flag — Phase 7 added this; raw value logging already gated behind it

### Established Patterns
- C-style error returns (no exceptions) — All HID operations return bool or check nullptr
- Lock-free atomics for cross-thread state (person_detected, connectionState, prox_distance)
- Mutex only for multi-field snapshot (CalibrationData)
- DriverLog with prefix convention: "HID:", "Pipe:", "Proximity:", "Config:"

### Integration Points
- `DeviceProvider::Init()` — HID init failure path (line 56-57, already has graceful continue)
- `DeviceProvider::RunFrame()` — Proximity polling, needs null guard on m_pHidDevice
- `HidDevice::ReaderThread()` — Main loop, reconnect handling, needs audit for uncaught failure paths
- `DeviceProvider::HandlePipeCommand()` — Command parsing, needs input validation audit

</code_context>

<specifics>
## Specific Ideas

No specific requirements — requirements (RBST-01 through RBST-04) are well-defined. This is a hardening pass: audit existing code, fill gaps in error handling and logging, verify graceful degradation path is complete.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 08-robustness-and-logging*
*Context gathered: 2026-03-23*