feat: Design metrics data model and storage schema

[charliewwdev]

Define the schema for metric samples (metric_name, value, unit, timestamp, labels). Choose a time-series-friendly storage strategy (e.g. InfluxDB, TimescaleDB, or in-memory ring buffer for MVP).

---

Generated by OpenDev AI

Storage strategy: in-memory ring buffer (MVP)

Chose a fixed-capacity ring buffer over InfluxDB/TimescaleDB because the agent-runtime has no time-series infrastructure dependency and the volume at MVP scale fits in memory. The MetricStore interface is deliberately narrow so a TimescaleDB or InfluxDB adapter can be swapped behind the same API later.

Schema

• metric_name — dot-separated hierarchical name (e.g. agent.task.duration_ms)
• value — number, validated finite (no NaN/Infinity)
• unit — closed enum via Zod; forces callers to pick from well-known units so dashboards can render correctly without guessing
• timestamp — Date, defaults to Date.now() on record() so callers rarely need to supply it
• labels — flat Record<string,string>, Prometheus-style; enables slicing by agent_type, workspace_id, environment, etc.

Ring buffer

• O(1) writes, O(n) reads, bounded memory regardless of ingest rate
• Default capacity 50 000 samples (~3.5 MB at ~70 bytes/sample)
• Oldest entries are silently dropped when full — acceptable for operational metrics

MetricStore

• record() — validates input with Zod then pushes to buffer
• query() — filter by name, time range, labels; returns newest-first
• aggregate() — avg/min/max/sum/count/p95/p99 over a filtered window

Tests cover ring buffer wraparound, overwrite behaviour, all query filters, all aggregate functions including percentiles, and Zod validation rejection.