# Performance Data Model

This file expands the performance tables listed in `data-model.md`.

## Agent Profiles

- `id`
- `manager_id`
- `name`
- `agent_type`
- `provider`
- `model`
- `status`
- `created_at`
- `updated_at`

Agent profiles are managed-agent records. They let Performance group sessions,
score, token volume, and cost by the developer responsible for that agent.

## Agent Spans

- `id`
- `developer_id`
- `session_id`
- `task_id`
- `agent_profile_id`
- `span_type`
- `name`
- `status`
- `provider`
- `model`
- `input_tokens`
- `output_tokens`
- `cache_read_tokens`
- `cache_write_tokens`
- `total_tokens`
- `cost_usd`
- `telemetry_source`
- `cost_source`
- `verified`
- `raw_usage_hash`
- `source_event_id`
- `submitted_cost_usd`
- `cost_mismatch`
- `latency_ms`
- `created_at`

Agent spans store usage and performance counters only. Spans are parsed from
structured Claude/Codex/OpenAI harness, provider, proxy, or OTel payloads and
keep a SHA-256 hash of the raw payload for auditability. Do not store raw
prompts, model responses, or full telemetry payloads in these rows.

`cost_source = 'unknown'` means token counters are verified but the server cannot
produce a trusted cost. That can happen because no trusted pricing rule or
provider estimate exists, or because the source sent only an aggregate
`total_tokens` value without input/output/cache buckets. Performance rollups keep
those tokens as `unpricedTokens`; aggregate-only rows also roll up as
`splitUnknownTokens` so the UI can say `token split unknown` instead of implying
the model price itself is missing. Spend totals and cost-per-task use priced
spend only and surface unknown cost as a warning, not as free usage.
Codex local sync submits split `response.completed` usage counters only; if a
Codex source cannot provide the split counters, the companion should skip the
Codex usage event instead of creating an aggregate-only row.

## Derived Views

Performance trend, weekly operating pulse, and activity-grid data is derived
from `tasks`, `work_events`, `usage_events`, `agent_sessions`, and
`agent_spans`.

Daily grid rollups include completed tasks, work events, usage events, spans,
tokens, cost, and active developers. No separate dashboard state is stored.

Performance leaderboards, team scorecards, operating-target attainment,
managed-agent registry health, agent insight reports, spend allocation,
selectable developer profiles, manager drilldowns, review cards, per-developer
task ledgers, manager briefs, live monitors, alert triage, and action reports
are derived at read time from the same records.

They store no manager notes or recommendations as source-of-truth state.