# pg1-instrumented-metrics: QA Plan

## Unit Tests

### histogram.rs (T1)
- `percentile_empty_returns_none` -- percentile on empty histogram returns None
- `percentile_single_observation` -- single obs returns correct percentile
- `percentile_known_distribution` -- 3 observations, verify p50/p99 match expected
- `percentile_beyond_all_bounds` -- observation above max bound still tracked
- `total_count_tracks_observations` -- total_count increments correctly
- `render_percentile_gauges_empty` -- empty histogram produces empty string
- `render_percentile_gauges_format` -- gauges contain correct metric names and values

### metrics/mod.rs (T2, T3, T6)
- `user_signal_timestamp_map_record_get` -- record and retrieve a timestamp
- `user_signal_timestamp_map_eviction` -- map evicts when over capacity
- `user_signal_timestamp_map_cap_respected` -- map never exceeds cap
- `render_diagnostics_valid_json` -- render_diagnostics returns parseable JSON
- `signal_writes_by_type_increment` -- per-type counter increments correctly

## Integration Tests

### pg1_instrumented_metrics.rs (T7)
- `prometheus_contains_percentile_gauges` -- /metrics output includes p50/p95/p99 gauge lines for signal write, retrieve, and search latencies
- `prometheus_contains_per_type_counters` -- /metrics output includes `tidaldb_signal_writes_by_type{signal_type="view"}` after writing view signals
- `prometheus_contains_staleness_histogram` -- /metrics output includes `tidaldb_personalization_staleness_us` after user query
- `diagnostics_endpoint_returns_json` -- /diagnostics returns HTTP 200 with valid JSON containing expected keys

## Non-Functional Verification

- All new code is behind `#[cfg(feature = "metrics")]` -- verify `cargo check` passes without the feature flag
- No new dependencies added to Cargo.toml
- Existing test suite (1345 lib tests) still passes after changes

## Exit Criteria

1. All unit tests pass: `cargo test --manifest-path tidal/Cargo.toml --lib --features metrics`
2. Integration test passes: `cargo test --manifest-path tidal/Cargo.toml --test pg1_instrumented_metrics --features metrics,test-utils`
3. No regressions: full lib test suite passes
4. Clippy clean: `cargo clippy --manifest-path tidal/Cargo.toml -- -D warnings`
5. Format clean: `cargo fmt --manifest-path tidal/Cargo.toml --check`