---
id: w8/m4/t001
title: Design + document the retention policy in docs/ADR023-usage-metering.md
worker: worker8
status: done
estimate: 30m
depends_on: []
---

## Objective

Decide and write down the retention policy: how many recent calendar months stay at hourly granularity (the "hot window") before being compacted into monthly aggregates, and the rationale (query needs vs storage growth).

## Context

- `docs/ADR023-usage-metering.md` currently documents `period=YYYY-MM` as open-ended historical lookback with no mention of granularity changing over time — this task adds that nuance honestly rather than silently changing behavior.
- `lego/backend/internal/store/migrations/0004_usage.up.sql` — the table this policy governs.
- No real usage data exists yet at scale; pick a defensible default (e.g. 3 months hot window) and make it env-tunable (t004) rather than hardcoded, so it can be revisited with real data later.

## Steps

1. Decide the hot-window length (recommend starting at 3 months — covers "this month + prior 2" which is the common historical-comparison range).
2. Document in `docs/ADR023-usage-metering.md`: what stays hourly, what becomes monthly, and that totals are preserved exactly across the boundary (compaction is a lossless sum, not a sample).
3. Note the env knob name that will control it (finalized in t004).

## Files

- `docs/ADR023-usage-metering.md`

## Acceptance criteria

- [ ] `docs/ADR023-usage-metering.md` states the hot-window default, the env knob that overrides it, and that historical period queries remain exact after compaction.

## Out of scope

- Implementing the compaction table/routine (t002/t003).
