# pg1-instrumented-metrics: Tasks

## T1: Percentile Methods on LatencyHistogram

**Files**: `tidal/src/db/metrics/histogram.rs`

Add `total_count()`, `percentile(p)`, and `render_percentile_gauges(name)` methods to `LatencyHistogram`. Add 7 unit tests covering: empty histogram, single observation, known distribution, beyond all bounds, total_count tracking, empty gauges render, format validation.

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --lib histogram --features metrics`

## T2: Per-Signal-Type Write Counters

**Files**: `tidal/src/db/metrics/mod.rs`, `tidal/src/db/signals.rs`

Add `signal_writes_by_type: DashMap<String, AtomicU64>` field to `MetricsState`. In `signal()`, after existing metrics block, increment the per-type counter (bounded at 256 entries). Update `render_prometheus()` to emit per-type counter lines.

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --lib --features metrics`

## T3: UserSignalTimestampMap

**Files**: `tidal/src/db/metrics/mod.rs`, `tidal/src/db/signals.rs`

Add `UserSignalTimestampMap` struct with `new()`, `record()`, `get()`, `evict_oldest()`. Add `user_last_signal` field to `MetricsState`. In `signal_with_context()`, record user timestamp before dispatch.

**Tests**: Unit tests for record/get/eviction in metrics module.

## T4: Personalization Staleness Histogram

**Files**: `tidal/src/db/metrics/mod.rs`, `tidal/src/db/query_ops.rs`

Add `personalization_staleness: LatencyHistogram` field to `MetricsState` with staleness-appropriate bounds. At the top of `retrieve()` and `search()`, compute and record staleness. Update `render_prometheus()` with staleness histogram + percentiles.

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --lib --features metrics`

## T5: Feedback-Loop Latency Histogram

**Files**: `tidal/src/db/metrics/mod.rs`, `tidal/src/db/query_ops.rs`

Add `feedback_loop_latency: LatencyHistogram` field to `MetricsState`. After result assembly in `retrieve()` and `search()`, check if user's signaled entity is in results (within 60s) and record loop latency. Update `render_prometheus()`.

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --lib --features metrics`

## T6: /diagnostics JSON Endpoint

**Files**: `tidal/src/db/metrics/mod.rs`, `tidal/src/db/http.rs`

Add `render_diagnostics()` method to `MetricsState` returning JSON with per-type counts, latency percentiles, staleness percentiles, feedback-loop percentiles. Add `/diagnostics` route to HTTP server (feature-gated).

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --lib --features metrics`

## T7: Integration Test

**Files**: `tidal/tests/pg1_instrumented_metrics.rs`

End-to-end test: open db with metrics feature, write signals with user context, run retrieve/search queries, verify Prometheus output contains new metric names and `/diagnostics` returns parseable JSON.

**Tests**: `cargo test --manifest-path tidal/Cargo.toml --test pg1_instrumented_metrics --features metrics,test-utils`