Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

161 KB
Raw Blame
"""Model Hub usage metering: wire extraction and bounded persistence.

Two properties are under test. Extraction must read exactly what each protocol
reports and refuse everything else, because token counts are the one number in
the hub that a hostile upstream fully controls. Persistence must stay bounded and
must survive an older or corrupt file, because the ledger is a shipped on-disk
surface.

Gateway recording is covered in ``test_model_hub_l3.py``, next to the turn
settlement scaffolding it depends on.
"""

from __future__ import annotations

import asyncio
import io
import json
import logging
import os
import stat
import subprocess
import sys
import textwrap
import threading
import time
from dataclasses import replace
from datetime import date, datetime, timedelta, timezone
from pathlib import Path

import pytest

from config.v2_config import ModelHubModelConfig
from core.handlers.model_hub.identifiers import (
    USAGE_LEDGER_KEY_MAX_LENGTH,
    USAGE_LEDGER_VERBATIM_MAX_LENGTH,
    canonical_model_id,
    persisted_ledger_key,
    usage_ledger_key,
)
from core.handlers.model_hub.pricing import PriceTable
from core.handlers.model_hub.stream_wire import (
    PROTOCOL_STREAM_TAXONOMY,
    USAGE_REPORT_TOKEN_CEILING,
    ProtocolSSEState,
    ProtocolUsageReport,
    extract_protocol_usage,
    observe_buffered_protocol_response,
    observe_protocol_response,
)
from core.handlers.model_hub.usage import (
    USAGE_COUNTER_CEILING,
    USAGE_DEFAULT_WINDOW_DAYS,
    USAGE_MAX_ROWS,
    USAGE_PUBLISHED_COUNT_BOUND,
    USAGE_RETENTION_DAYS,
    BoundedUsageLedger,
    SourceIdentity,
    UsageCall,
    UsageWriter,
    local_usage_day,
)

NOW = datetime(2026, 7, 23, 12, 0, tzinfo=timezone.utc)


def _as_released(counts: dict) -> dict:
    """Totals of rows written before cache writes were metered: every report uncaptured."""

    return {
        **counts,
        "cache_write_input_tokens": 0,
        "cache_write_1h_input_tokens": 0,
        "cache_write_30m_input_tokens": 0,
        "cache_write_12h_input_tokens": 0,
        "cache_write_uncaptured_reports": counts["token_reports"],
        "cache_write_ttl_uncaptured_reports": 0,
    }


def _frame(document: dict) -> bytes:
    """Render one SSE frame the way the protocols that name events do.

    Anthropic and OpenAI Responses both send `event:` alongside the discriminator
    in the body, and both are required to match a terminal envelope. OpenAI Chat
    sends unnamed frames, which is exactly the shape a body without `type` gets.
    """

    named = f"event: {document['type']}\n".encode("utf-8") if "type" in document else b""
    return named + b"data: " + json.dumps(document).encode("utf-8") + b"\n\n"


def _frames(*documents: dict) -> tuple[bytes, ...]:
    return tuple(_frame(document) for document in documents)


def _observed(protocol: str, *documents: dict) -> ProtocolUsageReport | None:
    state = ProtocolSSEState(protocol)
    for frame in _frames(*documents):
        state.observe(frame)
    return state.usage


# --- Extraction: every protocol declares where it reports usage ---------------


def test_every_observed_protocol_declares_a_usage_location() -> None:
    """A new protocol cannot ship unmetered: the table demands the location."""

    for protocol, taxonomy in PROTOCOL_STREAM_TAXONOMY.items():
        usage = taxonomy.usage
        assert usage.container_paths, protocol
        assert usage.input_paths, protocol
        assert usage.output_paths, protocol
        assert usage.cached_input_paths, protocol


@pytest.mark.parametrize(
    ("protocol", "usage", "expected"),
    (
        (
            "anthropic",
            {
                "input_tokens": 12,
                "cache_read_input_tokens": 3,
                "cache_creation_input_tokens": 2,
                "output_tokens": 7,
            },
            ProtocolUsageReport(
                input_tokens=17,
                cached_input_tokens=3,
                output_tokens=7,
                cache_write_input_tokens=2,
            ),
        ),
        (
            "openai_responses",
            {
                "input_tokens": 12,
                "input_tokens_details": {"cached_tokens": 3},
                "output_tokens": 7,
            },
            ProtocolUsageReport(input_tokens=12, cached_input_tokens=3, output_tokens=7),
        ),
        (
            "openai_chat",
            {
                "prompt_tokens": 12,
                "prompt_tokens_details": {"cached_tokens": 3},
                "completion_tokens": 7,
            },
            ProtocolUsageReport(input_tokens=12, cached_input_tokens=3, output_tokens=7),
        ),
    ),
)
def test_buffered_projection_reads_usage_after_a_large_ignored_value(
    protocol: str,
    usage: dict[str, object],
    expected: ProtocolUsageReport,
) -> None:
    body = json.dumps(
        {"ignored": "x" * (2 * 1024 * 1024), "usage": usage},
        separators=(",", ":"),
    ).encode()

    observation = observe_buffered_protocol_response(protocol, io.BytesIO(body))

    assert observation.outcome == "served"
    assert observation.usage == expected


def test_anthropic_input_total_sums_the_cache_members() -> None:
    """Anthropic reports `input_tokens` net of cache, so input is the sum."""

    report = extract_protocol_usage(
        "anthropic",
        {
            "type": "message",
            "usage": {
                "input_tokens": 12,
                "cache_read_input_tokens": 900,
                "cache_creation_input_tokens": 88,
                "output_tokens": 40,
            },
        },
    )

    assert report == ProtocolUsageReport(
        input_tokens=1000,
        cached_input_tokens=900,
        output_tokens=40,
        cache_write_input_tokens=88,
    )


def test_anthropic_stream_keeps_the_largest_cumulative_report() -> None:
    """`message_delta` restates a running total, so the largest frame wins."""

    usage = _observed(
        "anthropic",
        {"type": "message_start", "message": {"usage": {"input_tokens": 1000, "output_tokens": 1}}},
        {"type": "content_block_delta", "delta": {"text": "hi"}},
        {"type": "message_delta", "usage": {"output_tokens": 40}},
        {"type": "message_delta", "usage": {"output_tokens": 250}},
        {"type": "message_stop"},
    )

    assert usage == ProtocolUsageReport(input_tokens=1000, output_tokens=250)


def test_a_replayed_usage_frame_cannot_double_count() -> None:
    """Merging by the larger value makes retries and duplicates harmless."""

    single = _observed(
        "openai_responses",
        {"type": "response.in_progress", "response": {"usage": {"input_tokens": 700, "output_tokens": 9}}},
    )
    replayed = _observed(
        "openai_responses",
        {"type": "response.in_progress", "response": {"usage": {"input_tokens": 700, "output_tokens": 9}}},
        {"type": "response.in_progress", "response": {"usage": {"input_tokens": 700, "output_tokens": 9}}},
    )

    assert single == replayed == ProtocolUsageReport(input_tokens=700, output_tokens=9)


def test_openai_responses_reports_cached_input_as_a_subset() -> None:
    """`input_tokens` already includes cached input, so it is never an addend."""

    usage = _observed(
        "openai_responses",
        {
            "type": "response.completed",
            "response": {
                "usage": {
                    "input_tokens": 5000,
                    "input_tokens_details": {"cached_tokens": 4096},
                    "output_tokens": 77,
                }
            },
        },
    )

    assert usage == ProtocolUsageReport(
        input_tokens=5000,
        cached_input_tokens=4096,
        output_tokens=77,
    )


def test_usage_on_the_terminal_frame_is_observed_before_settlement() -> None:
    """The frame that ends the stream is also the one that carries the report."""

    state = ProtocolSSEState("openai_responses")
    for frame in _frames(
        {"type": "response.completed", "response": {"usage": {"input_tokens": 30, "output_tokens": 4}}},
        {"type": "response.completed", "response": {"usage": {"input_tokens": 999999, "output_tokens": 4}}},
    ):
        state.observe(frame)

    assert state.terminal_outcome == "served"
    # The second frame arrives after settlement and is ignored entirely, so it
    # cannot inflate the report either.
    assert state.usage == ProtocolUsageReport(input_tokens=30, output_tokens=4)


def test_a_terminal_error_carries_the_tokens_reported_before_it() -> None:
    """Review 4959575659 finding 7: Anthropic bills input on `message_start`.

    The terminal observation is what the runtime turns into a bodyless outcome for
    resolver metering, so dropping the accumulated report there would lose tokens
    on exactly the streams that end badly.
    """

    state = ProtocolSSEState("anthropic")
    for frame in _frames(
        {
            "type": "message_start",
            "message": {"usage": {"input_tokens": 900, "cache_read_input_tokens": 128}},
        },
        {"type": "error", "error": {"type": "overloaded_error"}},
    ):
        state.observe(frame)

    observation = state.terminal_observation()
    assert observation is not None
    assert observation.outcome != "served"
    assert observation.usage == ProtocolUsageReport(
        input_tokens=1028,
        cached_input_tokens=128,
    )


def test_openai_chat_reports_usage_only_on_its_final_chunk() -> None:
    """Chat streaming carries usage on a dedicated chunk, then `[DONE]`."""

    state = ProtocolSSEState("openai_chat")
    state.observe(_frames({"choices": [{"delta": {"content": "hi"}}]})[0])
    assert state.usage is None

    state.observe(
        _frames(
            {
                "choices": [],
                "usage": {
                    "prompt_tokens": 610,
                    "prompt_tokens_details": {"cached_tokens": 512},
                    "completion_tokens": 22,
                },
            }
        )[0]
    )
    state.observe(b"data: [DONE]\n\n")

    assert state.terminal_outcome == "served"
    assert state.usage == ProtocolUsageReport(
        input_tokens=610,
        cached_input_tokens=512,
        output_tokens=22,
    )


def test_a_buffered_response_without_a_report_stays_unmetered() -> None:
    """A missing report is absent, never zero: the caller tracks the shortfall."""

    observation = observe_protocol_response(
        "openai_chat",
        streamed=False,
        data=json.dumps({"choices": [{"message": {"content": "hi"}}]}).encode("utf-8"),
    )

    assert observation.outcome == "served"
    assert observation.usage is None


def test_a_buffered_error_still_carries_the_tokens_it_billed() -> None:
    """A vendor that reported tokens billed us even when the turn failed."""

    observation = observe_protocol_response(
        "anthropic",
        streamed=False,
        data=json.dumps(
            {
                "error": {"type": "overloaded_error"},
                "usage": {"input_tokens": 41, "output_tokens": 0},
            }
        ).encode("utf-8"),
    )

    assert observation.outcome == "failed_terminal"
    assert observation.usage == ProtocolUsageReport(input_tokens=41)


@pytest.mark.parametrize(
    "reported",
    [
        pytest.param(-1, id="negative"),
        pytest.param(True, id="bool"),
        pytest.param("120", id="string"),
        pytest.param(12.5, id="float"),
        pytest.param(None, id="null"),
        pytest.param([120], id="list"),
        pytest.param(USAGE_REPORT_TOKEN_CEILING + 1, id="above-ceiling"),
    ],
)
def test_an_unusable_token_value_is_dropped_not_coerced(reported: object) -> None:
    """Only a bounded non-negative integer count is a token count."""

    report = extract_protocol_usage(
        "openai_chat",
        {"usage": {"prompt_tokens": reported, "completion_tokens": 7}},
    )

    assert report == ProtocolUsageReport(output_tokens=7)


def test_a_composed_input_total_cannot_exceed_our_own_ceiling() -> None:
    """The ceiling lives in our code, never in a total the response declares."""

    report = extract_protocol_usage(
        "anthropic",
        {
            "usage": {
                "input_tokens": USAGE_REPORT_TOKEN_CEILING,
                "cache_read_input_tokens": USAGE_REPORT_TOKEN_CEILING,
                "total_tokens": 3,
            }
        },
    )

    assert report is not None
    assert report.input_tokens == USAGE_REPORT_TOKEN_CEILING
    assert report.cached_input_tokens == USAGE_REPORT_TOKEN_CEILING


@pytest.mark.parametrize(
    "reported_input,reported_cached,expected_cached",
    [
        pytest.param(100, 4096, 100, id="cached-above-input"),
        pytest.param(0, 4096, 0, id="cached-without-input"),
        pytest.param(4096, 4096, 4096, id="fully-cached"),
    ],
)
def test_cached_input_never_exceeds_the_input_it_is_a_part_of(
    reported_input: int,
    reported_cached: int,
    expected_cached: int,
) -> None:
    """The subset the read contract promises is bounded by our own input count."""

    report = extract_protocol_usage(
        "openai_responses",
        {
            "usage": {
                "input_tokens": reported_input,
                "input_tokens_details": {"cached_tokens": reported_cached},
                "output_tokens": 7,
            }
        },
    )

    assert report == ProtocolUsageReport(
        input_tokens=reported_input,
        cached_input_tokens=expected_cached,
        output_tokens=7,
    )


def test_the_subset_holds_when_two_frames_each_win_one_field() -> None:
    """Per-field max can compose a cached count larger than its own input."""

    usage = _observed(
        "openai_responses",
        {
            "type": "response.in_progress",
            "response": {
                "usage": {
                    "input_tokens": 10,
                    "input_tokens_details": {"cached_tokens": 8},
                    "output_tokens": 1,
                }
            },
        },
        {
            "type": "response.completed",
            "response": {
                "usage": {
                    "input_tokens": 12,
                    "input_tokens_details": {"cached_tokens": 4096},
                    "output_tokens": 3,
                }
            },
        },
    )

    assert usage == ProtocolUsageReport(
        input_tokens=12,
        cached_input_tokens=12,
        output_tokens=3,
    )


@pytest.mark.parametrize(
    "payload",
    [
        pytest.param({"type": "ping"}, id="no-container"),
        pytest.param({"usage": "many"}, id="container-not-an-object"),
        pytest.param({"usage": {}}, id="empty-container"),
        pytest.param({"usage": {"unknown_tokens": 5}}, id="unknown-members-only"),
    ],
)
def test_a_document_with_no_readable_report_yields_none(payload: dict) -> None:
    assert extract_protocol_usage("openai_chat", payload) is None


# --- Persistence: bounded, credential-free, and safe to load -----------------


class _Clock:
    """The moment a write happens, which a test moves independently of `at`.

    They are the same clock read at two times, and the gap between them is the
    point: `at` is captured when a call ends, this is read when its row is
    persisted, and metering runs off the event loop in between.
    """

    def __init__(self, moment: datetime) -> None:
        self.moment = moment

    def __call__(self) -> datetime:
        return self.moment


def _ledger(tmp_path: Path, **kwargs) -> BoundedUsageLedger:
    kwargs.setdefault("now", _Clock(NOW + timedelta(hours=12)))
    return BoundedUsageLedger(tmp_path / "state" / "usage.json", **kwargs)


def test_records_fold_into_one_row_per_day_source_and_model(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)

    ledger.record(
        source_id="src_a",
        model_id="model-x",
        usage=ProtocolUsageReport(input_tokens=100, cached_input_tokens=40, output_tokens=7),
        at=NOW,
    )
    ledger.record(
        source_id="src_a",
        model_id="model-x",
        usage=ProtocolUsageReport(input_tokens=200, output_tokens=3),
        at=NOW + timedelta(hours=1),
    )

    rows = ledger.window(days=1, now=NOW + timedelta(hours=1))
    assert len(rows) == 1
    assert rows[0]["requests"] == 2
    assert rows[0]["token_reports"] == 2
    assert rows[0]["input_tokens"] == 300
    assert rows[0]["cached_input_tokens"] == 40
    assert rows[0]["output_tokens"] == 7 + 3
    assert rows[0]["last_metered_at"] == (NOW + timedelta(hours=1)).isoformat()


def test_a_turn_without_a_report_counts_the_request_only(tmp_path: Path) -> None:
    """`requests` is self-measured; a missing report must not read as zero usage."""

    ledger = _ledger(tmp_path)

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
    ledger.record(
        source_id="src_a",
        model_id="model-x",
        usage=ProtocolUsageReport(input_tokens=90),
        at=NOW,
    )

    totals = ledger.summary(days=7, now=NOW)["totals"]
    assert totals["requests"] == 2
    assert totals["token_reports"] == 1
    assert totals["input_tokens"] == 90


def test_summary_groups_by_source_then_model_and_orders_by_traffic(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)
    yesterday = NOW - timedelta(days=1)

    for _ in range(3):
        ledger.record(
            source_id="src_busy",
            model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=10),
            at=yesterday,
        )
    ledger.record(
        source_id="src_busy",
        model_id="model-y",
        usage=ProtocolUsageReport(input_tokens=5),
        at=NOW,
    )
    ledger.record(source_id="src_quiet", model_id="model-x", usage=None, at=NOW)

    summary = ledger.summary(days=7, now=NOW)

    assert summary["window_days"] == 7
    assert summary["to_day"] == local_usage_day(NOW).isoformat()
    assert summary["from_day"] == (local_usage_day(NOW) - timedelta(days=6)).isoformat()
    assert [source["source_id"] for source in summary["sources"]] == ["src_busy", "src_quiet"]
    assert [model["model_id"] for model in summary["sources"][0]["models"]] == [
        "model-x",
        "model-y",
    ]
    assert summary["sources"][0]["requests"] == 4
    assert summary["sources"][0]["input_tokens"] == 35
    assert [day["day"] for day in summary["days"]] == sorted(day["day"] for day in summary["days"])
    assert len(summary["days"]) == 2
    assert summary["totals"]["requests"] == 5


def test_summary_reports_a_day_range_even_when_it_carries_no_turn(tmp_path: Path) -> None:
    """Days are the window's frame; only days with data become entries."""

    summary = _ledger(tmp_path).summary(days=30, now=NOW)

    assert summary["days"] == []
    assert summary["sources"] == []
    assert summary["totals"]["requests"] == 0
    assert summary["from_day"] < summary["to_day"]


def test_modern_hourly_report_is_dense_and_keeps_source_model_identity(
    tmp_path: Path,
) -> None:
    """MH-USAGE-BACKEND-001: modern windows reconcile measured hourly usage."""

    ledger = _ledger(tmp_path, now=_Clock(NOW + timedelta(hours=3)))
    unicode_model = "模型🧪/e\u0301"
    ledger.record(
        source_id="src_a",
        model_id=unicode_model,
        usage=ProtocolUsageReport(input_tokens=100, cached_input_tokens=40, output_tokens=7),
        at=NOW,
    )
    ledger.record(
        source_id="src_b",
        model_id=unicode_model,
        usage=ProtocolUsageReport(input_tokens=12, output_tokens=3),
        at=NOW + timedelta(hours=1),
    )
    ledger.record(
        source_id="src_a",
        model_id="model-missing-report",
        usage=None,
        at=NOW + timedelta(hours=2),
    )
    ledger.record(
        source_id="src_a",
        model_id=unicode_model,
        usage=ProtocolUsageReport(input_tokens=999, output_tokens=1),
        at=NOW - timedelta(hours=48),
    )

    report = ledger.report(
        window="24h",
        now=NOW + timedelta(hours=3),
        identities=[
            SourceIdentity(source_id="src_a", label="same label", model_ids=[unicode_model]),
            SourceIdentity(source_id="src_b", label="same label", model_ids=[unicode_model]),
        ],
    )

    assert report["window_key"] == "24h"
    assert report["granularity"] == "hour"
    assert len(report["buckets"]) == 24
    assert report["buckets"] == sorted(report["buckets"], key=lambda bucket: bucket["start_at"])
    assert report["totals"] == {
        "requests": 3,
        "token_reports": 2,
        "input_tokens": 112,
        "cached_input_tokens": 40,
        "output_tokens": 10,
        "cache_write_input_tokens": 0,
        "cache_write_1h_input_tokens": 0,
        "cache_write_30m_input_tokens": 0,
        "cache_write_12h_input_tokens": 0,
        "cache_write_uncaptured_reports": 0,
        "cache_write_ttl_uncaptured_reports": 0,
    }
    measured = {
        (row["source_id"], row["model_id"]): row
        for bucket in report["buckets"]
        for row in bucket["rows"]
    }
    assert measured[("src_a", unicode_model)]["input_tokens"] == 100
    assert measured[("src_b", unicode_model)]["input_tokens"] == 12
    assert measured[("src_a", "model-missing-report")]["token_reports"] == 0
    assert {source["label"] for source in report["sources"]} == {"same label"}
    assert report["totals"]["input_tokens"] + report["totals"]["output_tokens"] == 122

    daily = ledger.report(
        window="60d",
        now=NOW + timedelta(hours=3),
        identities=[
            SourceIdentity(source_id="src_a", label="same label", model_ids=[unicode_model]),
            SourceIdentity(source_id="src_b", label="same label", model_ids=[unicode_model]),
        ],
    )
    assert daily["totals"]["requests"] == 4
    assert daily["totals"]["input_tokens"] == 1111
    assert len(daily["buckets"]) == 60


def test_usage_writer_never_coalesces_different_hours_before_persistence(tmp_path: Path) -> None:
    """MH-USAGE-BACKEND-002: queued calls retain distinct hourly identity."""

    async def exercise() -> dict:
        ledger = _ledger(tmp_path, now=_Clock(NOW + timedelta(hours=2)))
        writer = UsageWriter(ledger)
        writer.record(
            source_id="src_a",
            model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=2),
            at=NOW,
        )
        writer.record(
            source_id="src_a",
            model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=5),
            at=NOW + timedelta(hours=1),
        )
        assert len(writer._pending) == 2
        assert await writer.drain(timeout=5) == 0
        return ledger.report(window="24h", now=NOW + timedelta(hours=2))

    report = asyncio.run(exercise())
    nonempty = [bucket for bucket in report["buckets"] if bucket["rows"]]
    assert len(nonempty) == 2
    assert sum(bucket["rows"][0]["requests"] for bucket in nonempty) == 2
    assert sum(bucket["rows"][0]["token_reports"] for bucket in nonempty) == 2
    assert sum(bucket["rows"][0]["input_tokens"] for bucket in nonempty) == 7


@pytest.mark.parametrize("reported", [False, True])
def test_usage_writer_preserves_daily_owners_inside_one_utc_hour(
    tmp_path: Path, reported: bool,
) -> None:
    """MH-USAGE-BACKEND-007: queue folds retain both daily and hourly ownership."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 23, 18, 30, tzinfo=timezone.utc)
    calls = tuple(
        datetime(2026, 9, 23, 18, minute, tzinfo=timezone.utc)
        for minute in (13, 14, 20, 21)
    )
    usage = (
        ProtocolUsageReport(input_tokens=10, cached_input_tokens=3, output_tokens=2)
        if reported else None
    )

    async def exercise() -> None:
        queued = _ledger(tmp_path / "queued", now=_Clock(now))
        separate = _ledger(tmp_path / "separate", now=_Clock(now))
        writer = UsageWriter(queued)
        for at in calls:
            writer.record(source_id="src_a", model_id="model-x", usage=usage, at=at)
            separate.record(source_id="src_a", model_id="model-x", usage=usage, at=at)
        pending_rows = len(writer._pending)
        assert await writer.drain(timeout=5) == 0
        assert pending_rows == 2

        fresh = _ledger(tmp_path / "queued", now=_Clock(now))
        assert fresh.summary(days=1, now=now) == separate.summary(days=1, now=now)
        assert fresh.summary(days=1, now=now)["totals"]["requests"] == 2
        assert fresh.summary(days=7, now=now) == separate.summary(days=7, now=now)
        assert [day["requests"] for day in fresh.summary(days=7, now=now)["days"]] == [2, 2]
        for window in ("24h", "7d"):
            assert fresh.report(window=window, now=now) == separate.report(window=window, now=now)
        [bucket] = [
            bucket for bucket in fresh.report(window="24h", now=now)["buckets"]
            if bucket["rows"]
        ]
        assert bucket["rows"][0]["requests"] == 4

    try:
        os.environ["TZ"] = "Asia/Kathmandu"
        time.tzset()
        asyncio.run(exercise())
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_the_writer_reads_the_price_table_before_serving_and_tiers_every_call_at_record(
    tmp_path: Path,
) -> None:
    """MH-USAGE-BACKEND-010: the writer reads the price table once when built, before the loop serves.

    A price table parses the whole models.dev copy, so it is read when Model Hub's
    service is built at controller startup, never on the loop and never per call.
    Every call is then tiered when it is recorded, the first one included, and
    calls of one tier fold together.
    """

    catalog = {"openai": {"models": {"gpt-6-astra": {"cost": {
        "input": 10, "output": 50,
        "tiers": [{"input": 20, "output": 75, "tier": {"type": "context", "size": 272_000}}],
    }}}}}
    vendor_map = {"families": [{"prefix": "gpt-", "vendor_id": "openai"}]}
    reads: list[bool] = []

    def price_table() -> PriceTable:
        try:
            asyncio.get_running_loop()
            reads.append(True)
        except RuntimeError:
            reads.append(False)
        return PriceTable(catalog=catalog, vendor_map=vendor_map, overrides={}, price_table_date="2026-10-13")

    writer = UsageWriter(_ledger(tmp_path), price_table=price_table)
    assert reads == [False]

    async def exercise() -> None:
        for input_tokens in (100_000, 300_000, 100_000, 300_000, 300_000):
            writer.record(
                source_id="src_a", model_id="gpt-6-astra", usage=ProtocolUsageReport(input_tokens=input_tokens), at=NOW,
            )
        assert len(writer._pending) == 2
        assert await writer.drain(timeout=5) == 0

    asyncio.run(exercise())
    assert reads == [False]
    rows = json.loads(_ledger(tmp_path).path.read_text(encoding="utf-8"))
    assert [(row.get("context_tier", 0), row["requests"]) for row in rows] == [(0, 2), (272_000, 3)]


@pytest.mark.parametrize(
    ("capture_zone", "flush_zone", "switch_between_calls", "expected_days"),
    [
        ("UTC", "Asia/Kathmandu", False, {"2026-09-24": 18}),
        ("Asia/Kathmandu", "UTC", False, {"2026-09-24": 7, "2026-09-25": 11}),
        ("UTC", "Asia/Kathmandu", True, {"2026-09-24": 7, "2026-09-25": 11}),
        ("Asia/Kathmandu", "UTC", True, {"2026-09-24": 18}),
    ],
)
def test_queued_usage_keeps_capture_day_across_host_zone_change(
    tmp_path: Path,
    capture_zone: str,
    flush_zone: str,
    switch_between_calls: bool,
    expected_days: dict[str, int],
) -> None:
    """Queued/folded calls must keep the same daily owners as immediate writes.

    The existing midnight test keeps TZ fixed; it cannot catch recomputing the
    captured owner in fold keys, dataclass replacement, or delayed persistence.
    """

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 0, tzinfo=timezone.utc)

    async def exercise() -> None:
        immediate = _ledger(tmp_path / "immediate", now=_Clock(now))
        unfolded = _ledger(tmp_path / "unfolded", now=_Clock(now))
        queued = _ledger(tmp_path / "queued", now=_Clock(now))
        writer = UsageWriter(queued)
        calls = []
        keys = []
        for index, (minute, tokens) in enumerate(((14, 7), (45, 11))):
            if index and switch_between_calls:
                os.environ["TZ"] = flush_zone
                time.tzset()
            at = datetime(2026, 9, 24, 18, minute, tzinfo=timezone.utc)
            usage = ProtocolUsageReport(input_tokens=tokens)
            call = UsageCall(source_id="src_a", model_id="model-x", usage=usage, at=at)
            calls.append(call)
            keys.append(call.fold_key)
            immediate.record(source_id="src_a", model_id="model-x", usage=usage, at=at)
            writer.record(source_id="src_a", model_id="model-x", usage=usage, at=at)

        os.environ["TZ"] = flush_zone
        time.tzset()
        assert [replace(call).fold_key for call in calls] == keys
        assert len(writer._pending) == len(expected_days)
        unfolded.record_many([replace(call) for call in calls])
        assert await writer.drain(timeout=5) == 0

        expected_rows = json.loads(immediate.path.read_text(encoding="utf-8"))
        assert {row["day"]: row["input_tokens"] for row in expected_rows} == expected_days
        for ledger in (unfolded, queued):
            assert json.loads(ledger.path.read_text(encoding="utf-8")) == expected_rows
            fresh = BoundedUsageLedger(ledger.path, now=_Clock(now))
            for window in ("24h", "7d"):
                assert fresh.report(window=window, now=now) == immediate.report(window=window, now=now)
                assert fresh.report(window=window, now=now)["totals"]["input_tokens"] == 18

    try:
        os.environ["TZ"] = capture_zone
        time.tzset()
        asyncio.run(exercise())
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_queued_future_call_still_clamps_day_after_host_zone_change(tmp_path: Path) -> None:
    """Freezing normal owners must not bypass the existing future-call ceiling."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 24, 23, 30, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        call = UsageCall(
            source_id="src_a", model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=7), at=now + timedelta(days=2),
        )
        os.environ["TZ"] = "Asia/Kathmandu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.record_many([call])

        [row] = json.loads(ledger.path.read_text(encoding="utf-8"))
        assert row["day"] == "2026-09-25"
        assert row["last_metered_at"] == now.isoformat()
        assert row["hours"][0]["key"] == "2026-09-24T23:00:00+00:00"
        for window in ("24h", "7d"):
            assert ledger.report(window=window, now=now)["totals"]["input_tokens"] == 7
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


@pytest.mark.parametrize(
    ("future_minute", "owner_day"),
    [
        pytest.param(45, "2026-09-24", id="current-hour"),
        pytest.param(75, "2026-09-24", id="next-hour"),
        pytest.param(45, "2026-09-25", id="old-zone-current-hour"),
    ],
)
def test_future_hourly_evidence_is_incomplete_on_read_and_after_a_write(
    tmp_path: Path, future_minute: int, owner_day: str,
) -> None:
    """MH-USAGE-BACKEND-008: future evidence cannot masquerade as complete history.

    A current UTC slice still witnesses uncertain history when a timezone change
    leaves its old owner outside the local grid; same-zone fixtures missed this.
    """

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 24, 12, 15, tzinfo=timezone.utc)
    future = now.replace(minute=0) + timedelta(minutes=future_minute)
    counts = {
        "requests": 1, "token_reports": 1, "input_tokens": 10,
        "cached_input_tokens": 3, "output_tokens": 2,
    }
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(json.dumps([{
            "day": owner_day, "source_id": "src_future", "model_id": "model-x",
            **counts,
            "last_metered_at": future.isoformat(),
            "hourly_history_complete": True,
            "hours": [{
                "key": future.replace(minute=0).isoformat(), **counts,
                "last_metered_at": future.isoformat(),
            }],
        }]), encoding="utf-8")
        before = ledger.path.read_bytes()
        report = ledger.report(window="24h", now=now)
        assert ledger.path.read_bytes() == before
        assert report["totals"]["requests"] == 0
        if owner_day == "2026-09-24":
            assert all(
                bucket["history_complete"] == (bucket["start_at"][:10] != owner_day)
                for bucket in report["buckets"]
            )
            assert ledger.summary(days=1, now=now)["totals"] == _as_released(counts)
        else:
            assert all(not bucket["history_complete"] for bucket in report["buckets"])
            assert ledger.summary(days=1, now=now)["totals"]["requests"] == 0

        # A real call triggers persistence; read and write use the same policy.
        ledger.record(
            source_id="src_real", model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=5), at=now,
        )
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
        assert report["totals"]["requests"] == 1
        assert report["totals"]["input_tokens"] == 5
        assert any(not bucket["history_complete"] for bucket in report["buckets"])
        assert ledger.summary(days=1, now=now)["totals"]["requests"] == (
            2 if owner_day == "2026-09-24" else 1
        )
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_legacy_daily_rows_are_preserved_but_never_allocated_to_an_hour(
    tmp_path: Path,
) -> None:
    """MH-USAGE-BACKEND-003: released daily-only rows stay daily-only."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_legacy",
                    "model_id": "model-legacy",
                    "requests": 2,
                    "token_reports": 2,
                    "input_tokens": 10,
                    "cached_input_tokens": 3,
                    "output_tokens": 4,
                    "last_metered_at": NOW.isoformat(),
                }
            ]
        ),
        encoding="utf-8",
    )

    hourly = ledger.report(window="24h", now=NOW)
    daily = ledger.report(window="7d", now=NOW)

    assert hourly["totals"]["requests"] == 0
    assert all(not bucket["rows"] for bucket in hourly["buckets"])
    assert any(not bucket["history_complete"] for bucket in hourly["buckets"])
    assert daily["totals"]["requests"] == 2
    assert daily["totals"]["input_tokens"] == 10
    assert all(bucket["history_complete"] for bucket in daily["buckets"])


@pytest.mark.parametrize("requests", [0, 2])
@pytest.mark.parametrize("history_shape", ["retained", "expired", "legacy"])
def test_tokens_without_reports_never_become_complete_empty_hourly_history(
    tmp_path: Path, requests: int, history_shape: str,
) -> None:
    """Invalid counter relationships preserve daily counts but not hourly certainty."""

    now = NOW + timedelta(minutes=15)
    ledger = _ledger(tmp_path, now=_Clock(now))
    ledger.path.parent.mkdir(parents=True)
    counts = {
        "requests": requests, "token_reports": 0,
        "input_tokens": 7, "cached_input_tokens": 1, "output_tokens": 3,
    }
    start = now.replace(minute=0, second=0, microsecond=0)
    damaged = {
        "day": local_usage_day(now).isoformat(),
        "source_id": "src_corrupt", "model_id": "model-corrupt",
        **counts, "last_metered_at": now.isoformat(),
    }
    if history_shape != "legacy":
        damaged.update({
            "hours": (
                [{"key": start.isoformat(), **counts, "last_metered_at": now.isoformat()}]
                if history_shape == "retained" else []
            ),
            "hourly_expired_totals": counts if history_shape == "expired" else {key: 0 for key in counts},
            "hourly_expired_before": (start - timedelta(hours=24)).isoformat(),
            "hourly_history_complete": True,
        })
    ledger.path.write_text(json.dumps([damaged]), encoding="utf-8")

    hourly = ledger.report(window="24h", now=now)
    assert not hourly["buckets"][-1]["history_complete"]
    assert hourly["totals"]["input_tokens"] == 0
    assert ledger.summary(days=1, now=now)["totals"]["input_tokens"] == 7

    ledger.record(
        source_id="src_corrupt", model_id="model-corrupt",
        usage=ProtocolUsageReport(input_tokens=2, output_tokens=1),
        at=now,
    )
    reopened = _ledger(tmp_path).report(window="24h", now=now)
    assert not reopened["buckets"][-1]["history_complete"]
    assert reopened["totals"]["input_tokens"] == 2
    assert ledger.summary(days=1, now=now)["totals"]["input_tokens"] == 9


def test_corrupt_nested_hours_are_deduplicated_bounded_and_marked_unavailable(
    tmp_path: Path,
) -> None:
    """MH-USAGE-BACKEND-004: corrupt nested slices cannot overstate usage."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True)
    key = NOW.astimezone().replace(minute=0, second=0, microsecond=0).isoformat()
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_corrupt",
                    "model_id": "model-corrupt",
                    "requests": 2,
                    "token_reports": 2,
                    "input_tokens": 10,
                    "cached_input_tokens": 0,
                    "output_tokens": 2,
                    "last_metered_at": NOW.isoformat(),
                    "hourly_history_complete": True,
                    "hours": [
                        {
                            "key": key,
                            "requests": 2,
                            "token_reports": 2,
                            "input_tokens": 9,
                            "cached_input_tokens": 0,
                            "output_tokens": 1,
                        },
                        {
                            "key": key,
                            "requests": 2,
                            "token_reports": 2,
                            "input_tokens": 9,
                            "cached_input_tokens": 0,
                            "output_tokens": 1,
                        },
                    ],
                }
            ]
        ),
        encoding="utf-8",
    )

    report = ledger.report(window="24h", now=NOW)

    assert report["totals"]["requests"] == 0
    assert all(not bucket["rows"] for bucket in report["buckets"])
    assert any(not bucket["history_complete"] for bucket in report["buckets"])
    assert ledger.summary(days=1, now=NOW)["totals"]["requests"] == 2


@pytest.mark.parametrize(
    "hours",
    [
        [{"key": "2026-07-23T12:00", "requests": 1}],
        [
            {
                "key": "2026-07-23T12:00+00:00",
                "requests": 1,
                "token_reports": "one",
                "input_tokens": 4,
                "cached_input_tokens": 0,
                "output_tokens": 1,
            }
        ],
        [
            {
                "key": "2026-07-23T12:00+00:00",
                "requests": 1,
                "token_reports": 1,
                "input_tokens": 4,
                "cached_input_tokens": 5,
                "output_tokens": 1,
            }
        ],
    ],
)
def test_malformed_nested_hours_are_unavailable_without_inventing_usage(
    tmp_path: Path,
    hours: list[dict],
) -> None:
    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_corrupt",
                    "model_id": "model-corrupt",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 4,
                    "cached_input_tokens": 0,
                    "output_tokens": 1,
                    "last_metered_at": NOW.isoformat(),
                    "hourly_history_complete": True,
                    "hours": hours,
                }
            ]
        ),
        encoding="utf-8",
    )

    report = ledger.report(window="24h", now=NOW)

    assert report["totals"]["requests"] == 0
    assert all(not bucket["rows"] for bucket in report["buckets"])
    assert any(not bucket["history_complete"] for bucket in report["buckets"])
    assert ledger.summary(days=1, now=NOW)["totals"]["requests"] == 1


def test_recent_usage_without_its_hour_cannot_claim_complete_hourly_history(
    tmp_path: Path,
) -> None:
    """A complete flag is insufficient when the latest metered hour is absent."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 24, 12, 15, tzinfo=timezone.utc)
    counts = {
        "requests": 1,
        "token_reports": 1,
        "input_tokens": 4,
        "cached_input_tokens": 1,
        "output_tokens": 2,
    }
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps(
                [
                    {
                        "day": "2026-09-24",
                        "source_id": "src_missing_hour",
                        "model_id": "model-missing-hour",
                        **counts,
                        "last_metered_at": (now - timedelta(minutes=30)).isoformat(),
                        "hourly_history_complete": True,
                        "hours": [],
                    }
                ]
            ),
            encoding="utf-8",
        )

        report = ledger.report(window="24h", now=now)

        assert report["totals"]["requests"] == 0
        assert any(not bucket["history_complete"] for bucket in report["buckets"])
        assert ledger.summary(days=1, now=now)["totals"] == _as_released(counts)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_missing_in_horizon_hour_cannot_be_hidden_by_a_present_latest_hour(
    tmp_path: Path,
) -> None:
    """A present latest slice does not prove earlier same-day slices exist."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 24, 12, 15, tzinfo=timezone.utc)
    counts = {
        "requests": 2,
        "token_reports": 2,
        "input_tokens": 8,
        "cached_input_tokens": 2,
        "output_tokens": 4,
    }
    latest = now - timedelta(minutes=30)
    latest_key = latest.replace(minute=0, second=0, microsecond=0)
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps(
                [
                    {
                        "day": "2026-09-24",
                        "source_id": "src_missing_earlier",
                        "model_id": "model-missing-earlier",
                        **counts,
                        "last_metered_at": latest.isoformat(),
                        "hourly_history_complete": True,
                        "hours": [
                            {
                                "key": latest_key.isoformat(),
                                **{**counts, "requests": 1, "token_reports": 1,
                                   "input_tokens": 4, "cached_input_tokens": 1,
                                   "output_tokens": 2},
                                "last_metered_at": latest.isoformat(),
                            }
                        ],
                    }
                ]
            ),
            encoding="utf-8",
        )

        report = ledger.report(window="24h", now=now)

        assert report["totals"]["requests"] == 1
        assert any(
            row["requests"] == 1
            for bucket in report["buckets"]
            for row in bucket["rows"]
        )
        assert any(not bucket["history_complete"] for bucket in report["buckets"])
        assert ledger.summary(days=1, now=now)["totals"] == _as_released(counts)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_daily_midnight_uses_the_date_specific_local_offset() -> None:
    from core.handlers.model_hub.usage import _local_midnight

    previous_tz = os.environ.get("TZ")
    try:
        os.environ["TZ"] = "America/New_York"
        time.tzset()
        winter = _local_midnight(date(2026, 1, 15))
        summer = _local_midnight(date(2026, 7, 15))
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert winter.utcoffset() != summer.utcoffset()


def test_hourly_retention_expiry_does_not_poison_retained_hours(tmp_path: Path) -> None:
    """Expired slices outside the report horizon are not missing history."""

    previous_tz = os.environ.get("TZ")
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(NOW))
        ledger.record(
            source_id="src_expiry",
            model_id="model-expiry",
            usage=ProtocolUsageReport(input_tokens=25),
            at=NOW - timedelta(hours=25),
        )
        ledger.record(
            source_id="src_expiry",
            model_id="model-expiry",
            usage=ProtocolUsageReport(input_tokens=23),
            at=NOW - timedelta(hours=23),
        )
        hourly = ledger.report(window="24h", now=NOW)
        daily = ledger.report(window="7d", now=NOW)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert hourly["totals"]["requests"] == 1
    assert hourly["totals"]["input_tokens"] == 23
    assert all(bucket["history_complete"] for bucket in hourly["buckets"])
    assert daily["totals"]["requests"] == 2
    assert daily["totals"]["input_tokens"] == 48


def test_partial_oldest_day_reconciles_expired_and_retained_hours(
    tmp_path: Path,
) -> None:
    """A missing in-horizon slice cannot hide behind expired daily usage."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 23, 18, 30, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Asia/Kathmandu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps(
                [
                    {
                        "day": "2026-09-23",
                        "source_id": "src_partial-oldest",
                        "model_id": "model-partial-oldest",
                        "requests": 3,
                        "token_reports": 3,
                        "input_tokens": 30,
                        "cached_input_tokens": 0,
                        "output_tokens": 3,
                        "last_metered_at": "2026-09-23T17:20:00+00:00",
                        "hourly_history_complete": True,
                        "hourly_expired_totals": {
                            "requests": 1,
                            "token_reports": 1,
                            "input_tokens": 10,
                            "cached_input_tokens": 0,
                            "output_tokens": 1,
                        },
                        "hours": [
                            {
                                "key": "2026-09-23T17:00:00+00:00",
                                "requests": 1,
                                "token_reports": 1,
                                "input_tokens": 10,
                                "cached_input_tokens": 0,
                                "output_tokens": 1,
                                "last_metered_at": "2026-09-23T17:20:00+00:00",
                            }
                        ],
                    }
                ]
            ),
            encoding="utf-8",
        )
        report = ledger.report(window="24h", now=now)
        daily = ledger.summary(days=2, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 1
    assert daily["totals"]["requests"] == 3
    assert any(not bucket["history_complete"] for bucket in report["buckets"])


def test_hourly_boundaries_match_across_lord_howe_dst_transition(tmp_path: Path) -> None:
    """Hourly identity stays UTC-stable while Lord Howe displays a 30-minute jump."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 10, 4, 3, 15, tzinfo=timezone.utc)
    at = datetime(2026, 10, 3, 14, 45, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Australia/Lord_Howe"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.record(
            source_id="src_lord-howe",
            model_id="model-dst",
            usage=ProtocolUsageReport(input_tokens=1),
            at=at,
        )
        hourly = ledger.report(window="24h", now=now)
        daily = ledger.report(window="7d", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    populated = [bucket for bucket in hourly["buckets"] if bucket["rows"]]
    transition = next(
        bucket
        for bucket in hourly["buckets"]
        if bucket["start_at"] == "2026-10-04T01:30:00+10:30"
    )
    assert len(populated) == 1
    assert populated[0]["start_at"] == "2026-10-04T00:30:00+10:30"
    assert populated[0]["end_at"] == "2026-10-04T01:30:00+10:30"
    assert transition["end_at"] == "2026-10-04T03:00:00+11:00"
    assert hourly["totals"]["requests"] == 1
    assert daily["totals"]["requests"] == 1
    assert all(bucket["history_complete"] for bucket in hourly["buckets"])


def test_hourly_boundaries_display_non_dst_fractional_offset(tmp_path: Path) -> None:
    """UTC-hour identity remains stable in a non-DST fractional-offset zone."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 24, 12, 30, tzinfo=timezone.utc)
    at = datetime(2026, 9, 24, 11, 45, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Asia/Kathmandu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.record(
            source_id="src-kathmandu",
            model_id="model-fractional",
            usage=ProtocolUsageReport(input_tokens=1),
            at=at,
        )
        hourly = ledger.report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    populated = [bucket for bucket in hourly["buckets"] if bucket["rows"]]
    assert len(populated) == 1
    assert populated[0]["start_at"] == "2026-09-24T16:45:00+05:45"
    assert populated[0]["end_at"] == "2026-09-24T17:45:00+05:45"
    assert hourly["totals"]["requests"] == 1
    assert all(bucket["history_complete"] for bucket in hourly["buckets"])


def test_hourly_report_uses_utc_evidence_after_a_timezone_change(
    tmp_path: Path,
) -> None:
    """A stored hour remains reportable when the host timezone changes."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Pacific/Kiritimati"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.record(
            source_id="src-timezone-change",
            model_id="model-timezone-change",
            usage=ProtocolUsageReport(input_tokens=7),
            at=now - timedelta(hours=6),
        )

        os.environ["TZ"] = "Pacific/Honolulu"
        time.tzset()
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 1
    assert report["totals"]["input_tokens"] == 7
    [populated] = [bucket for bucket in report["buckets"] if bucket["rows"]]
    assert populated["rows"][0]["source_id"] == "src-timezone-change"
    assert all(bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize(
    ("old_zone", "new_zone"),
    [
        ("Pacific/Kiritimati", "Pacific/Honolulu"),
        ("Pacific/Honolulu", "Pacific/Kiritimati"),
    ],
)
@pytest.mark.parametrize("daily_only", [False, True])
@pytest.mark.parametrize("max_rows", [1, 4])
def test_timezone_change_preserves_recent_owners_across_a_write(
    tmp_path: Path, old_zone: str, new_zone: str, daily_only: bool, max_rows: int,
) -> None:
    """Recent UTC evidence survives writes at either local retention edge.

    Read-only timezone coverage missed the subsequent write deleting its owner.
    Released daily-only owners must also survive without inventing hourly counts.
    At capacity, an old owner label must not evict a more recently metered call.
    """

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = old_zone
        time.tzset()
        ledger = _ledger(tmp_path, retention_days=1, max_rows=max_rows, now=_Clock(now))
        ledger.record(
            source_id="src_old-zone", model_id="模型-β",
            usage=ProtocolUsageReport(input_tokens=7), at=now - timedelta(hours=6),
        )
        original = json.loads(ledger.path.read_text(encoding="utf-8"))[0]
        if daily_only:
            original = {
                key: value for key, value in original.items()
                if key != "hours" and not key.startswith("hourly_")
            }
            ledger.path.write_text(json.dumps([original]), encoding="utf-8")

        os.environ["TZ"] = new_zone
        time.tzset()
        reopened = _ledger(tmp_path, retention_days=1, max_rows=max_rows, now=_Clock(now))
        reopened.record(
            source_id="src_new-zone", model_id="模型-β",
            usage=ProtocolUsageReport(input_tokens=11), at=now,
        )
        persisted = json.loads(ledger.path.read_text(encoding="utf-8"))
        hourly = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
        bounded_hourly = _ledger(tmp_path, max_rows=1, now=_Clock(now)).report(
            window="24h", now=now,
        )
        daily = reopened.summary(days=1, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert daily["totals"]["input_tokens"] == 11
    assert bounded_hourly["totals"]["input_tokens"] == 11
    if max_rows == 1:
        assert [item["source_id"] for item in persisted] == ["src_new-zone"]
        assert hourly["totals"]["requests"] == 1
        assert hourly["totals"]["input_tokens"] == 11
        return
    old = next(item for item in persisted if item["source_id"] == "src_old-zone")
    assert old["day"] == original["day"]
    assert old["input_tokens"] == 7
    assert hourly["totals"]["requests"] == (1 if daily_only else 2)
    assert hourly["totals"]["input_tokens"] == (11 if daily_only else 18)
    if not daily_only:
        assert all(item["history_complete"] for item in hourly["buckets"])
    else:
        assert any(not item["history_complete"] for item in hourly["buckets"])


@pytest.mark.parametrize("new_zone", ["UTC", "Pacific/Honolulu", "Asia/Kathmandu"])
def test_legacy_latest_hour_remains_uncertain_after_timezone_change(
    tmp_path: Path, new_zone: str,
) -> None:
    """Local-owner overlap cannot erase uncertainty at the actual UTC call.

    The previous no-overlap test missed owners overlapping only later buckets.
    """

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    latest = datetime(2026, 9, 24, 12, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = new_zone
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps([{
                "day": "2026-09-25", "source_id": "src_legacy", "model_id": "model",
                "requests": 2, "token_reports": 2, "input_tokens": 7,
                "cached_input_tokens": 0, "output_tokens": 0,
                "last_metered_at": latest.isoformat(),
            }]),
            encoding="utf-8",
        )
        report = ledger.report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    [affected] = [
        bucket for bucket in report["buckets"]
        if datetime.fromisoformat(bucket["start_at"]) <= latest
        < datetime.fromisoformat(bucket["end_at"])
    ]
    assert affected["history_complete"] is False
    # Without the original zone, the other daily call cannot be placed either.
    assert all(not bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize("rewrite", [False, True])
def test_pruned_hours_do_not_become_complete_zero_after_clock_rollback(
    tmp_path: Path, rewrite: bool,
) -> None:
    """A previously pruned hour can re-enter the horizon without its counters.

    Forward-only retention tests never queried behind the persisted expiry bound.
    """

    previous_tz = os.environ.get("TZ")
    clock = _Clock(datetime(2026, 9, 24, 17, 30, tzinfo=timezone.utc))
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=clock)
        for hour in (12, 16):
            ledger.record(
                source_id="src_rollback", model_id="model",
                usage=ProtocolUsageReport(input_tokens=7),
                at=clock.moment.replace(hour=hour),
            )
        clock.moment = datetime(2026, 9, 25, 13, 30, tzinfo=timezone.utc)
        ledger.record(source_id="src_other", model_id="model", usage=None, at=clock.moment)
        forward = ledger.report(window="24h", now=clock.moment)
        assert all(bucket["history_complete"] for bucket in forward["buckets"])
        clock.moment -= timedelta(hours=2)
        if rewrite:
            ledger.record(source_id="src_new", model_id="model", usage=None, at=clock.moment)
        report = _ledger(tmp_path, now=clock).report(window="24h", now=clock.moment)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    [expired_bucket] = [
        bucket for bucket in report["buckets"]
        if bucket["start_at"] == "2026-09-24T12:00:00+00:00"
    ]
    assert expired_bucket["rows"] == []
    assert expired_bucket["history_complete"] is False


@pytest.mark.parametrize("boundary", [None, "invalid", "2026-09-24T12:30:00Z"])
def test_undated_expired_totals_cannot_claim_complete_hourly_history(
    tmp_path: Path, boundary: str | None,
) -> None:
    """Older or damaged expiry metadata cannot prove which hours were removed.

    Counter-only reconciliation missed an undated expired contribution, including
    when a valid duplicate is merged onto it during a subsequent write.
    """

    now = datetime(2026, 9, 25, 13, 30, tzinfo=timezone.utc)
    ledger = _ledger(tmp_path, now=_Clock(now))
    ledger.record(
        source_id="src_expiry", model_id="model",
        usage=ProtocolUsageReport(input_tokens=7), at=now - timedelta(hours=1),
    )
    [recent] = json.loads(ledger.path.read_text(encoding="utf-8"))
    expired = {
        **recent,
        "hours": [],
        "hourly_expired_totals": {
            key: recent[key] for key in (
                "requests", "token_reports", "input_tokens",
                "cached_input_tokens", "output_tokens",
            )
        },
        "hourly_expired_before": boundary,
        "last_metered_at": (now - timedelta(hours=25)).isoformat(),
    }
    ledger.path.write_text(json.dumps([expired, recent]), encoding="utf-8")
    before = ledger.report(window="24h", now=now)
    ledger.record(
        source_id="src_expiry", model_id="model",
        usage=ProtocolUsageReport(input_tokens=3), at=now,
    )
    after = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)

    assert before["totals"]["input_tokens"] == 7
    assert after["totals"]["input_tokens"] == 10
    assert ledger.summary(days=7, now=now)["totals"]["input_tokens"] == 17
    assert any(not bucket["history_complete"] for bucket in before["buckets"])
    assert any(not bucket["history_complete"] for bucket in after["buckets"])


def test_hourly_report_preserves_uncertainty_for_timezone_orphaned_daily_rows(
    tmp_path: Path,
) -> None:
    """A daily-only row outside the new local day cannot claim empty hours."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Pacific/Kiritimati"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps([{
                "day": "2026-09-25",
                "source_id": "src-timezone-orphan",
                "model_id": "model-timezone-orphan",
                "requests": 1,
                "token_reports": 1,
                "input_tokens": 7,
                "cached_input_tokens": 0,
                "output_tokens": 1,
                "last_metered_at": "2026-09-24T23:30:00+00:00",
            }]),
            encoding="utf-8",
        )

        os.environ["TZ"] = "Pacific/Honolulu"
        time.tzset()
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    assert all(not bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize(
    ("old_zone", "new_zone"),
    [
        ("Pacific/Kiritimati", "Pacific/Honolulu"),
        ("Pacific/Honolulu", "Pacific/Kiritimati"),
    ],
)
@pytest.mark.parametrize("timestamp", [None, "not-an-instant"])
@pytest.mark.parametrize("overlap", [False, True])
def test_timestampless_owner_days_use_a_conservative_utc_envelope(
    tmp_path: Path,
    old_zone: str,
    new_zone: str,
    timestamp: str | None,
    overlap: bool,
) -> None:
    """Unknown owner dates are selected only when their UTC envelope can overlap."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = old_zone
        time.tzset()
        owner_day = local_usage_day(now)
        if not overlap:
            owner_day -= timedelta(days=3)
        row = {
            "day": owner_day.isoformat(),
            "source_id": "src-unknown-time",
            "model_id": "model-unknown-time",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
        }
        if timestamp is not None:
            row["last_metered_at"] = timestamp
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        path.write_text(json.dumps([row]), encoding="utf-8")

        os.environ["TZ"] = new_zone
        time.tzset()
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    if overlap:
        assert any(not bucket["history_complete"] for bucket in report["buckets"])
    else:
        assert all(bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize(
    ("old_zone", "new_zone"),
    [
        ("Pacific/Kiritimati", "Pacific/Honolulu"),
        ("Pacific/Honolulu", "Pacific/Kiritimati"),
    ],
)
@pytest.mark.parametrize("timestamp", [None, "not-an-instant"])
@pytest.mark.parametrize("max_rows", [1, 4])
def test_timestampless_owner_survives_write_and_capacity_ranking(
    tmp_path: Path,
    old_zone: str,
    new_zone: str,
    timestamp: str | None,
    max_rows: int,
) -> None:
    """The shared envelope keeps unknown owners without outranking known calls."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = old_zone
        time.tzset()
        owner_day = local_usage_day(now)
        row = {
            "day": owner_day.isoformat(),
            "source_id": "src-old-zone",
            "model_id": "model-old-zone",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
        }
        if timestamp is not None:
            row["last_metered_at"] = timestamp
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        path.write_text(json.dumps([row]), encoding="utf-8")

        os.environ["TZ"] = new_zone
        time.tzset()
        ledger = _ledger(
            tmp_path,
            retention_days=1,
            max_rows=max_rows,
            now=_Clock(now),
        )
        ledger.record(
            source_id="src-new-zone",
            model_id="model-new-zone",
            usage=ProtocolUsageReport(input_tokens=11),
            at=now,
        )
        persisted = json.loads(path.read_text(encoding="utf-8"))
        hourly = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert any(row["source_id"] == "src-new-zone" for row in persisted)
    if max_rows == 1:
        assert [row["source_id"] for row in persisted] == ["src-new-zone"]
        assert all(not bucket["history_complete"] for bucket in hourly["buckets"])
    else:
        assert {row["source_id"] for row in persisted} == {
            "src-old-zone", "src-new-zone",
        }
        assert any(not bucket["history_complete"] for bucket in hourly["buckets"])


@pytest.mark.parametrize(
    ("old_zone", "new_zone"),
    [
        ("Pacific/Kiritimati", "Pacific/Honolulu"),
        ("Pacific/Honolulu", "Pacific/Kiritimati"),
    ],
)
@pytest.mark.parametrize("timestamp", [None, "not-an-instant"])
def test_timestampless_owner_outside_the_envelope_expires_on_write(
    tmp_path: Path,
    old_zone: str,
    new_zone: str,
    timestamp: str | None,
) -> None:
    """An unknown owner day outside the hourly envelope still expires normally."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = old_zone
        time.tzset()
        owner_day = local_usage_day(now) - timedelta(days=3)
        row = {
            "day": owner_day.isoformat(),
            "source_id": "src-expired-unknown-time",
            "model_id": "model-expired-unknown-time",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
        }
        if timestamp is not None:
            row["last_metered_at"] = timestamp
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        path.write_text(json.dumps([row]), encoding="utf-8")

        os.environ["TZ"] = new_zone
        time.tzset()
        ledger = _ledger(tmp_path, retention_days=1, now=_Clock(now))
        ledger.record(
            source_id="src-new-zone",
            model_id="model-new-zone",
            usage=ProtocolUsageReport(input_tokens=11),
            at=now,
        )
        persisted = json.loads(path.read_text(encoding="utf-8"))
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert [row["source_id"] for row in persisted] == ["src-new-zone"]


@pytest.mark.parametrize("timestamp", [None, "not-an-instant"])
def test_same_identity_merge_preserves_date_only_hourly_uncertainty(
    tmp_path: Path, timestamp: str | None,
) -> None:
    """A fresh call cannot turn an earlier timestamp-less owner into certainty."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        row = {
            "day": local_usage_day(now).isoformat(),
            "source_id": "src-merged",
            "model_id": "model-merged",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
        }
        if timestamp is not None:
            row["last_metered_at"] = timestamp
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        path.write_text(json.dumps([row]), encoding="utf-8")

        ledger = _ledger(tmp_path, now=_Clock(now))
        before = ledger.report(window="24h", now=now)
        before_incomplete = {
            bucket["start_at"]
            for bucket in before["buckets"]
            if not bucket["history_complete"]
        }
        ledger.record(
            source_id="src-merged",
            model_id="model-merged",
            usage=ProtocolUsageReport(input_tokens=3),
            at=now,
        )
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
        daily = ledger.summary(days=1, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["input_tokens"] == 3
    after_incomplete = {
        bucket["start_at"]
        for bucket in report["buckets"]
        if not bucket["history_complete"]
    }
    assert after_incomplete == before_incomplete
    assert daily["totals"]["input_tokens"] == 10


def test_delayed_exact_merge_does_not_age_out_legacy_hourly_uncertainty(
    tmp_path: Path,
) -> None:
    """A delayed exact call cannot narrow legacy mass at a later report time."""

    previous_tz = os.environ.get("TZ")
    write_now = datetime(2026, 9, 25, 22, 15, tzinfo=timezone.utc)
    captured_at = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    report_now = datetime(2026, 9, 26, 1, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        path.write_text(json.dumps([{
            "day": "2026-09-25",
            "source_id": "src-delayed-merge",
            "model_id": "model-delayed-merge",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
        }]), encoding="utf-8")

        ledger = _ledger(tmp_path, now=_Clock(write_now))
        before = ledger.report(window="24h", now=report_now)
        before_incomplete = {
            bucket["start_at"]
            for bucket in before["buckets"]
            if not bucket["history_complete"]
        }
        ledger.record(
            source_id="src-delayed-merge",
            model_id="model-delayed-merge",
            usage=ProtocolUsageReport(input_tokens=3),
            at=captured_at,
        )
        after = _ledger(tmp_path, now=_Clock(report_now)).report(
            window="24h",
            now=report_now,
        )
        daily = ledger.summary(days=2, now=report_now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    after_incomplete = {
        bucket["start_at"]
        for bucket in after["buckets"]
        if not bucket["history_complete"]
    }
    assert len(before_incomplete) == 24
    assert after_incomplete == before_incomplete
    assert after["totals"]["input_tokens"] == 0
    assert daily["totals"]["input_tokens"] == 10


@pytest.mark.parametrize("unknown_first", [False, True])
def test_duplicate_known_and_date_only_rows_preserve_hourly_uncertainty(
    tmp_path: Path, unknown_first: bool,
) -> None:
    """Duplicate-row coalescing cannot make unknown historical mass certain."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        owner_day = local_usage_day(now).isoformat()
        unknown = {
            "day": owner_day,
            "source_id": "src-duplicate-uncertainty",
            "model_id": "model-duplicate-uncertainty",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 0,
        }
        known = {
            **unknown,
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 3,
            "last_metered_at": now.isoformat(),
            "hours": [{
                "key": now.replace(minute=0, second=0, microsecond=0).isoformat(),
                "requests": 1,
                "token_reports": 1,
                "input_tokens": 3,
                "cached_input_tokens": 0,
                "output_tokens": 0,
                "last_metered_at": now.isoformat(),
            }],
            "hourly_expired_totals": {
                "requests": 0,
                "token_reports": 0,
                "input_tokens": 0,
                "cached_input_tokens": 0,
                "output_tokens": 0,
            },
            "hourly_history_complete": True,
        }
        path = tmp_path / "state" / "usage.json"
        path.parent.mkdir(parents=True)
        rows = [unknown, known] if unknown_first else [known, unknown]
        path.write_text(json.dumps(rows), encoding="utf-8")

        ledger = _ledger(tmp_path, now=_Clock(now))
        report = ledger.report(window="24h", now=now)
        incomplete = {
            bucket["start_at"]
            for bucket in report["buckets"]
            if not bucket["history_complete"]
        }

        assert len(incomplete) == 15
        assert report["totals"]["input_tokens"] == 3
        assert ledger.summary(days=1, now=now)["totals"]["input_tokens"] == 10
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


@pytest.mark.parametrize("owner_day", [date.min, date.max])
def test_timestampless_owner_day_extremes_do_not_overflow(
    tmp_path: Path, owner_day: date,
) -> None:
    """Envelope construction degrades safely at both representable date edges."""

    previous_tz = os.environ.get("TZ")
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps([{
                "day": owner_day.isoformat(),
                "source_id": "src-extreme",
                "model_id": "model-extreme",
                "requests": 1,
                "token_reports": 1,
                "input_tokens": 1,
                "cached_input_tokens": 0,
                "output_tokens": 0,
            }]),
            encoding="utf-8",
        )

        report = ledger.report(window="24h", now=now)
        ledger.record(
            source_id="src-new",
            model_id="model-new",
            usage=ProtocolUsageReport(input_tokens=2),
            at=now,
        )
        daily = ledger.summary(days=1, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    assert daily["totals"]["requests"] == 1


def test_timezone_orphaned_hourly_rows_reconcile_against_utc_slices(
    tmp_path: Path,
) -> None:
    """A local-day owner outside the current grid cannot hide a missing hour."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 0, 15, tzinfo=timezone.utc)
    counts = {
        "requests": 2,
        "token_reports": 2,
        "input_tokens": 20,
        "cached_input_tokens": 0,
        "output_tokens": 2,
    }
    try:
        os.environ["TZ"] = "Pacific/Kiritimati"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(
            json.dumps([{
                "day": "2026-09-25",
                "source_id": "src-timezone-orphan-hourly",
                "model_id": "model-timezone-orphan-hourly",
                **counts,
                "last_metered_at": "2026-09-24T23:15:00+00:00",
                "hourly_history_complete": True,
                "hourly_expired_totals": {
                    "requests": 0,
                    "token_reports": 0,
                    "input_tokens": 0,
                    "cached_input_tokens": 0,
                    "output_tokens": 0,
                },
                "hours": [{
                    "key": "2026-09-24T23:00:00+00:00",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 10,
                    "cached_input_tokens": 0,
                    "output_tokens": 1,
                    "last_metered_at": "2026-09-24T23:15:00+00:00",
                }],
            }]),
            encoding="utf-8",
        )

        os.environ["TZ"] = "Pacific/Honolulu"
        time.tzset()
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 1
    assert all(not bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize(
    ("zone", "now", "calls", "from_day", "to_day", "window_days"),
    [
        (
            "Asia/Kathmandu",
            datetime(2026, 9, 23, 18, 30, tzinfo=timezone.utc),
            (
                datetime(2026, 9, 23, 18, 14, tzinfo=timezone.utc),
                datetime(2026, 9, 23, 18, 20, tzinfo=timezone.utc),
            ),
            "2026-09-23", "2026-09-24", 2,
        ),
        (
            "Pacific/Chatham",
            datetime(2026, 9, 27, 10, 30, tzinfo=timezone.utc),
            (
                datetime(2026, 9, 26, 11, 5, tzinfo=timezone.utc),
                datetime(2026, 9, 26, 11, 20, tzinfo=timezone.utc),
            ),
            "2026-09-26", "2026-09-28", 3,
        ),
    ],
)
def test_hourly_report_joins_every_local_day_owner_across_midnight(
    tmp_path: Path,
    zone: str,
    now: datetime,
    calls: tuple[datetime, datetime],
    from_day: str,
    to_day: str,
    window_days: int,
) -> None:
    """MH-USAGE-BACKEND-006: one hour joins all daily owners across midnight/DST."""

    previous_tz = os.environ.get("TZ")
    try:
        os.environ["TZ"] = zone
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        for at in calls:
            ledger.record(
                source_id="src_midnight",
                model_id="model-midnight",
                usage=ProtocolUsageReport(input_tokens=10, cached_input_tokens=3, output_tokens=2),
                at=at,
            )
        # A fresh reader exercises the persisted keys, not an in-memory projection.
        report = _ledger(tmp_path, now=_Clock(now)).report(window="24h", now=now)
        daily = ledger.summary(days=7, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"] == daily["totals"]
    assert report["totals"]["requests"] == 2
    assert report["totals"]["input_tokens"] == 20
    assert report["from_day"] == from_day
    assert report["to_day"] == to_day
    assert report["window_days"] == window_days
    assert len(report["buckets"]) == 24
    assert all(bucket["history_complete"] for bucket in report["buckets"])
    [populated] = [bucket for bucket in report["buckets"] if bucket["rows"]]
    assert len(populated["rows"]) == 1
    assert populated["rows"][0]["requests"] == 2
    assert sum(day["requests"] for day in report["days"]) == 2
    for before, after in zip(report["buckets"], report["buckets"][1:]):
        assert before["end_at"] == after["start_at"]


def test_legacy_usage_after_local_midnight_marks_the_overlapping_hour_incomplete(
    tmp_path: Path,
) -> None:
    """Missing history belongs to every overlapping hour, not just its start date."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 23, 18, 30, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Asia/Kathmandu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(json.dumps([{
            "day": "2026-09-24",
            "source_id": "src_legacy",
            "model_id": "model-legacy",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 10,
            "cached_input_tokens": 0,
            "output_tokens": 2,
            "last_metered_at": now.isoformat(),
        }]), encoding="utf-8")
        report = ledger.report(window="24h", now=now)
        daily = ledger.summary(days=1, now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    assert daily["totals"]["requests"] == 1
    [incomplete] = [
        bucket for bucket in report["buckets"] if not bucket["history_complete"]
    ]
    assert incomplete["start_at"] == "2026-09-23T23:45:00+05:45"
    assert incomplete["end_at"] == "2026-09-24T00:15:00+05:45"


def test_expired_legacy_rows_do_not_reenter_hourly_history_after_timezone_change(
    tmp_path: Path,
) -> None:
    """A stale instant must win over a new host-zone day fallback."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 12, 0, tzinfo=timezone.utc)
    try:
        os.environ["TZ"] = "Pacific/Honolulu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(json.dumps([{
            "day": "2026-09-25",
            "source_id": "src-expired-legacy",
            "model_id": "model-expired-legacy",
            "requests": 1,
            "token_reports": 1,
            "input_tokens": 7,
            "cached_input_tokens": 0,
            "output_tokens": 1,
            "last_metered_at": "2026-09-24T10:00:00+00:00",
        }]), encoding="utf-8")

        report = ledger.report(window="24h", now=now)
        daily = ledger.report(window="7d", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 0
    assert all(bucket["history_complete"] for bucket in report["buckets"])
    assert daily["totals"]["requests"] == 1


def test_recent_hourly_evidence_survives_a_stale_daily_timestamp(
    tmp_path: Path,
) -> None:
    """A valid UTC slice remains authoritative when the daily recency is stale."""

    previous_tz = os.environ.get("TZ")
    now = datetime(2026, 9, 25, 12, 0, tzinfo=timezone.utc)
    counts = {
        "requests": 1,
        "token_reports": 1,
        "input_tokens": 7,
        "cached_input_tokens": 0,
        "output_tokens": 1,
    }
    try:
        os.environ["TZ"] = "Pacific/Honolulu"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(now))
        ledger.path.parent.mkdir(parents=True)
        ledger.path.write_text(json.dumps([{
            "day": "2026-09-25",
            "source_id": "src-recent-hour",
            "model_id": "model-recent-hour",
            **counts,
            "last_metered_at": "2026-09-24T10:00:00+00:00",
            "hourly_history_complete": True,
            "hourly_expired_totals": {
                "requests": 0,
                "token_reports": 0,
                "input_tokens": 0,
                "cached_input_tokens": 0,
                "output_tokens": 0,
            },
            "hours": [{
                "key": "2026-09-25T11:00:00+00:00",
                **counts,
                "last_metered_at": "2026-09-25T11:15:00+00:00",
            }],
        }]), encoding="utf-8")

        report = ledger.report(window="24h", now=now)
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()

    assert report["totals"]["requests"] == 1
    assert report["totals"]["input_tokens"] == 7
    assert all(bucket["history_complete"] for bucket in report["buckets"])


@pytest.mark.parametrize(
    "content",
    [
        pytest.param("not json", id="unreadable"),
        pytest.param('{"rows": []}', id="not-a-list"),
        pytest.param('[{"day": "not-a-day"}]', id="unusable-row"),
    ],
)
def test_degraded_ledger_history_is_not_published_as_complete_zero(
    tmp_path: Path,
    content: str,
) -> None:
    """A read failure makes the affected modern report buckets uncertain."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True)
    ledger.path.write_text(content, encoding="utf-8")

    daily = ledger.report(window="7d", now=NOW)
    hourly = ledger.report(window="24h", now=NOW)

    assert all(not bucket["history_complete"] for bucket in daily["buckets"])
    assert all(not bucket["history_complete"] for bucket in hourly["buckets"])


def test_degraded_ledger_history_survives_a_followup_write(tmp_path: Path) -> None:
    """A later write cannot turn discarded history into a complete zero."""

    now = NOW
    ledger = _ledger(tmp_path, now=_Clock(now))
    ledger.path.parent.mkdir(parents=True)
    ledger.path.write_text("not json", encoding="utf-8")

    ledger.record(
        source_id="src_after-degraded-read",
        model_id="model-after-degraded-read",
        usage=ProtocolUsageReport(input_tokens=7),
        at=now,
    )

    fresh = _ledger(tmp_path, now=_Clock(now))
    daily = fresh.report(window="7d", now=now)
    hourly = fresh.report(window="24h", now=now)
    persisted = json.loads(fresh.path.read_text(encoding="utf-8"))

    assert daily["totals"]["requests"] == 1
    assert hourly["totals"]["requests"] == 1
    assert all(not bucket["history_complete"] for bucket in daily["buckets"])
    assert all(not bucket["history_complete"] for bucket in hourly["buckets"])
    assert all(row["history_degraded"] is True for row in persisted)


@pytest.mark.parametrize("marked_first", [False, True])
def test_duplicate_rows_preserve_degradation_in_both_orders_and_after_write(
    tmp_path: Path, marked_first: bool,
) -> None:
    """Duplicate merge ORs the witness; single damaged-row tests miss its loss."""

    previous_tz = os.environ.get("TZ")
    try:
        os.environ["TZ"] = "UTC"
        time.tzset()
        ledger = _ledger(tmp_path, now=_Clock(NOW))
        ledger.record(
            source_id="src_a", model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=7), at=NOW,
        )
        [plain] = json.loads(ledger.path.read_text(encoding="utf-8"))
        marked = {**plain, "history_degraded": True}
        rows = [marked, plain] if marked_first else [plain, marked]
        ledger.path.write_text(json.dumps(rows), encoding="utf-8")

        for window in ("24h", "7d"):
            report = ledger.report(window=window, now=NOW)
            assert report["totals"]["input_tokens"] == 14
            assert all(not bucket["history_complete"] for bucket in report["buckets"])

        ledger.record(
            source_id="src_a", model_id="model-x",
            usage=ProtocolUsageReport(input_tokens=3), at=NOW,
        )
        fresh = _ledger(tmp_path, now=_Clock(NOW))
        for window in ("24h", "7d"):
            report = fresh.report(window=window, now=NOW)
            assert report["totals"]["input_tokens"] == 17
            assert all(not bucket["history_complete"] for bucket in report["buckets"])
        [persisted] = json.loads(fresh.path.read_text(encoding="utf-8"))
        assert persisted["history_degraded"] is True
    finally:
        if previous_tz is None:
            os.environ.pop("TZ", None)
        else:
            os.environ["TZ"] = previous_tz
        time.tzset()


def test_a_window_excludes_days_outside_it(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW - timedelta(days=5))
    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)

    assert len(ledger.window(days=30, now=NOW)) == 2
    assert len(ledger.window(days=2, now=NOW)) == 1


@pytest.mark.parametrize(
    "requested,expected",
    [
        pytest.param(0, 1, id="zero-clamps-up"),
        pytest.param(-7, 1, id="negative-clamps-up"),
        pytest.param(10_000, USAGE_RETENTION_DAYS, id="clamps-to-retention"),
    ],
)
def test_a_requested_window_is_clamped_to_what_is_retained(
    tmp_path: Path,
    requested: int,
    expected: int,
) -> None:
    assert _ledger(tmp_path).summary(days=requested, now=NOW)["window_days"] == expected


def test_retention_drops_rows_past_the_horizon(tmp_path: Path) -> None:
    clock = _Clock(NOW - timedelta(days=10))
    ledger = _ledger(tmp_path, retention_days=3, now=clock)

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=clock.moment)
    assert len(ledger.window(days=3, now=NOW - timedelta(days=10))) == 1

    # Writing under a later day is what advances the horizon.
    clock.moment = NOW
    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
    persisted = json.loads(ledger.path.read_text(encoding="utf-8"))
    assert [row["day"] for row in persisted] == [local_usage_day(NOW).isoformat()]


def test_the_row_cap_keeps_the_newest_rows(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path, max_rows=3)

    for index in range(6):
        ledger.record(
            source_id="src_a",
            model_id=f"model-{index}",
            usage=None,
            at=NOW,
        )

    persisted = json.loads(ledger.path.read_text(encoding="utf-8"))
    assert [row["model_id"] for row in persisted] == ["model-3", "model-4", "model-5"]


def test_the_row_cap_holds_when_reporting_a_file_that_overflows_it(
    tmp_path: Path, caplog: pytest.LogCaptureFixture
) -> None:
    """Review 5266689271: a file may hold more rows than the writer would emit.

    `max_rows` used to be applied in `_write` only, which bounds every file this
    ledger produces and no other one. A store that was corrupted, hand-edited, or
    written by a different version was read back whole, so the window it published
    was not bounded by anything the contract could name.

    The bound belongs on the reportable set rather than on the parse — see
    `test_the_row_cap_never_evicts_a_reportable_row_for_a_future_dated_one` for
    what applying it to raw rows costs.

    The stamps here are all in the past, which is what distinguishes this from
    `test_the_row_cap_ranks_an_unmeasurable_instant_as_the_least_recent`: the
    ordering can read every one of them, so it evicts by age.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    overflow = [
        {
            "day": local_usage_day(NOW).isoformat(),
            "source_id": "src_a",
            "model_id": f"model-{index:03d}",
            "requests": 1,
            "input_tokens": 1,
            "cached_input_tokens": 0,
            "output_tokens": 0,
            "last_metered_at": (NOW - timedelta(seconds=5 - index)).isoformat(),
        }
        for index in range(5)
    ]
    path.write_text(json.dumps(overflow), encoding="utf-8")

    ledger = BoundedUsageLedger(path, max_rows=3)
    with caplog.at_level(logging.WARNING):
        held = ledger.window(days=30, now=NOW)

    # The survivors are the ones `_write` would have kept, in the same order.
    assert [row["model_id"] for row in held] == ["model-002", "model-003", "model-004"]
    assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 3
    assert "over its capacity of 3" in caplog.text


def test_the_row_cap_never_evicts_a_reportable_row_for_a_future_dated_one(
    tmp_path: Path,
) -> None:
    """Review 5267029898: capacity applied before the date filter evicts backwards.

    `_recency` orders by day first, so a future-dated row outranks every real one.
    `_retained` was written for exactly this — a clock that jumps forward, is
    corrected, and leaves rows no read will ever report while they hold slots and
    evict live ones. Applying the capacity to rows straight out of the file put
    that defect back on the read path, ahead of the code that closes it: the
    future rows survived, `window` then filtered them, and a window holding real
    usage reported none of it.

    Filtering to the requested window first is what makes the eviction meaningful,
    because then every candidate is a row a reader can actually see.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    today = local_usage_day(NOW)
    rows = [
        {
            "day": (today + timedelta(days=ahead)).isoformat(),
            "source_id": "src_future",
            "model_id": f"model-{ahead}",
            "requests": 1,
            "input_tokens": 5,
            "cached_input_tokens": 0,
            "output_tokens": 0,
            "last_metered_at": (NOW + timedelta(days=ahead)).isoformat(),
        }
        for ahead in (1, 2, 3)
    ] + [
        {
            "day": today.isoformat(),
            "source_id": "src_real",
            "model_id": f"model-{index}",
            "requests": 1,
            "input_tokens": 100,
            "cached_input_tokens": 0,
            "output_tokens": 0,
            "last_metered_at": NOW.isoformat(),
        }
        for index in range(3)
    ]
    path.write_text(json.dumps(rows), encoding="utf-8")

    ledger = BoundedUsageLedger(path, max_rows=3)

    # The real rows are the only reportable ones, so they are the ones kept.
    assert [row["source_id"] for row in ledger.window(days=30, now=NOW)] == ["src_real"] * 3
    assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 300


def test_the_row_cap_ranks_an_unmeasurable_instant_as_the_least_recent(
    tmp_path: Path,
) -> None:
    """Review 5267204231: a future instant inside today survives the date filter.

    The date filter closed the future-*day* case; the second half of `_recency` is
    the instant, and a stamp later than the reading passes that filter untouched.
    A clock corrected backwards leaves exactly this behind, and the rows it leaves
    then outranked every real one and evicted live usage.

    Bounding the instant to the reading is the obvious remedy and is not enough:
    it makes those rows as recent as the reading, so they still outrank a row
    metered a minute earlier. Both halves are asserted here — the survivors, and
    the fact that a clamp would have kept the wrong ones.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    today = local_usage_day(NOW).isoformat()
    rows = [
        {
            "day": today,
            "source_id": "src_future",
            "model_id": f"model-{ahead}",
            "requests": 1,
            "input_tokens": 5,
            "cached_input_tokens": 0,
            "output_tokens": 0,
            "last_metered_at": (NOW + timedelta(hours=ahead)).isoformat(),
        }
        for ahead in (1, 2, 3)
    ] + [
        {
            "day": today,
            "source_id": "src_real",
            "model_id": f"model-{index}",
            "requests": 1,
            "input_tokens": 100,
            "cached_input_tokens": 0,
            "output_tokens": 0,
            # An hour old: still the most recent usage anyone metered, and still
            # older than what a clamp to `now` would hand the future rows.
            "last_metered_at": (NOW - timedelta(hours=1)).isoformat(),
        }
        for index in range(3)
    ]
    path.write_text(json.dumps(rows), encoding="utf-8")

    ledger = BoundedUsageLedger(path, max_rows=3)

    assert [row["source_id"] for row in ledger.window(days=30, now=NOW)] == ["src_real"] * 3
    assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 300


def test_an_unmeasurable_instant_costs_a_row_nothing_while_there_is_room(
    tmp_path: Path,
) -> None:
    """Ranking last is an eviction order, not a verdict on the row.

    Nothing about a stamp decides whether a row is reported: the day does that.
    So a future-stamped row inside the window is published like any other until
    the file is over capacity, and the counters it carries are its own.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-a",
                    "requests": 1,
                    "input_tokens": 42,
                    "cached_input_tokens": 0,
                    "output_tokens": 0,
                    "last_metered_at": (NOW + timedelta(days=9)).isoformat(),
                }
            ]
        ),
        encoding="utf-8",
    )

    ledger = BoundedUsageLedger(path, max_rows=3)

    assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 42


def test_a_merge_cannot_lift_a_published_count_over_the_declared_maximum(
    tmp_path: Path,
) -> None:
    """Review 5267029898: duplicates coalesce into one row, under one cap.

    `_counter` clears each stored counter against the ceiling, but their sum is
    not thereby cleared, and merging happens after. Enough duplicate-keyed rows
    therefore build a single row carrying more than any row may — and one row is
    one row, so the capacity that bounds the reportable set never sees it.

    How many duplicates a file holds is bounded by nothing, so this has to be
    answered on the merged value itself.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    duplicate = {
        "day": local_usage_day(NOW).isoformat(),
        "source_id": "src_a",
        "model_id": "model-x",
        "requests": 1,
        "input_tokens": USAGE_COUNTER_CEILING,
        "cached_input_tokens": 0,
        "output_tokens": 0,
        "last_metered_at": NOW.isoformat(),
    }
    path.write_text(
        json.dumps([dict(duplicate) for _ in range(USAGE_MAX_ROWS + 1)]), encoding="utf-8"
    )

    totals = BoundedUsageLedger(path).summary(days=30, now=NOW)["totals"]

    assert totals["input_tokens"] <= USAGE_PUBLISHED_COUNT_BOUND
    # Refused rather than reduced: the bucket is garbage, and the next call
    # recorded against it starts a row that means what it says.
    assert totals["input_tokens"] == 0


def test_no_file_can_make_a_published_count_exceed_the_declared_maximum(
    tmp_path: Path,
) -> None:
    """The contract's maximum has to bound the reader, not just the writer.

    `USAGE_PUBLISHED_COUNT_BOUND` is the product of the two capacities this file
    has. It is a real bound on what `summary` publishes only while both of them
    are enforced on the way *in*; each was once enforced at one door only, and
    each time the gap let a hand-edited store publish a count its own schema
    rejects. This drives the worst case directly — every row at the counter
    ceiling, more rows than the file may hold — so the product stays a promise the
    producer keeps rather than a description of its happy path.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    rows = USAGE_MAX_ROWS + 25
    path.write_text(
        json.dumps(
            [
                {
                    "day": (local_usage_day(NOW) - timedelta(days=index % 30)).isoformat(),
                    "source_id": "src_a",
                    "model_id": f"model-{index:04d}",
                    "requests": USAGE_COUNTER_CEILING,
                    "input_tokens": USAGE_COUNTER_CEILING,
                    "cached_input_tokens": USAGE_COUNTER_CEILING,
                    "output_tokens": USAGE_COUNTER_CEILING,
                    "last_metered_at": (NOW + timedelta(seconds=index)).isoformat(),
                }
                for index in range(rows)
            ]
        ),
        encoding="utf-8",
    )

    totals = BoundedUsageLedger(path).summary(days=30, now=NOW)["totals"]

    for key in ("requests", "input_tokens", "cached_input_tokens", "output_tokens"):
        assert totals[key] == USAGE_PUBLISHED_COUNT_BOUND, key
    # Tight, not merely safe: the worst admissible file reaches the bound exactly,
    # so the contract declares no range the producer cannot occupy.
    assert USAGE_PUBLISHED_COUNT_BOUND == USAGE_MAX_ROWS * USAGE_COUNTER_CEILING


def test_no_file_can_put_a_published_summary_outside_its_own_contract(
    tmp_path: Path,
) -> None:
    """Every published guarantee, asserted against one deliberately hostile file.

    Five rounds of review found the same shape five times: an invariant the write
    path enforces that the report path does not mirror. Each fix closed the door it
    was found at, and the next one was found at a door nobody had listed. Listing
    the doors is the part that kept failing, so this asserts the guarantees instead
    — the properties `usage-summary.schema.json` and the UI depend on — over a file
    carrying every corruption at once, and over more reportable rows than the
    capacity can hold, so the eviction runs rather than being skipped.
    """

    path = tmp_path / "state" / "usage.json"
    path.parent.mkdir(parents=True)
    today = local_usage_day(NOW)
    hostile: list[object] = []
    for index in range(USAGE_MAX_ROWS * 2):
        # Days on both sides of both edges: three ahead of today, thirty inside the
        # window, three behind it. Readable stamps on the first half, stamps no
        # clock has reached on the second.
        readable = index < USAGE_MAX_ROWS // 2
        hostile.append(
            {
                "day": (today - timedelta(days=(index % 36) - 3)).isoformat(),
                "source_id": f"src_{'past' if readable else 'ahead'}_{index % 7}",
                "model_id": f"model_{index % 11}",
                "requests": index,
                "token_reports": index * 3,  # breaks its subset
                "input_tokens": USAGE_COUNTER_CEILING - index,
                "cached_input_tokens": USAGE_COUNTER_CEILING,  # breaks its subset
                "output_tokens": -index,  # not a count
                "last_metered_at": (
                    NOW - timedelta(hours=index + 1)
                    if readable
                    else NOW + timedelta(hours=index)
                ).isoformat(),
            }
        )
    # Duplicate keys, so the merge builds counters no row in the file carried.
    # Taken from the unreadable half, because a merged row past the ceiling is
    # dropped on read and the readable family is what the eviction is asserted on.
    hostile.extend(hostile[USAGE_MAX_ROWS : USAGE_MAX_ROWS + 60])
    hostile.extend(["not a row", None, {"day": "2026-W34-2", "source_id": "s", "model_id": "m"}])
    path.write_text(json.dumps(hostile), encoding="utf-8")

    ledger = BoundedUsageLedger(path)
    rows = ledger.window(days=USAGE_DEFAULT_WINDOW_DAYS, now=NOW)
    report = ledger.summary(days=USAGE_DEFAULT_WINDOW_DAYS, now=NOW)

    assert len(rows) == USAGE_MAX_ROWS  # the capacity binds, so eviction ran
    assert all(report["from_day"] <= row["day"] <= report["to_day"] for row in rows)

    # Nothing whose recency the report can read loses its slot to something it
    # cannot read — the property the last two rounds of review both came back to.
    # Within a day, because the day is the first half of the order and evicting the
    # oldest one first is what retention is: a recent row outranks an older one
    # whatever either claims about the hour.
    survivors = {(row["day"], row["source_id"], row["model_id"]) for row in rows}
    readable = {
        (row["day"], row["source_id"], row["model_id"])
        for row in hostile[: USAGE_MAX_ROWS // 2]
        if report["from_day"] <= row["day"] <= report["to_day"]
    }
    assert readable
    outbid = {day for day, _, _ in readable - survivors}
    assert not [row for row in rows if row["day"] in outbid and "ahead" in row["source_id"]]

    counters = (
        "requests",
        "token_reports",
        "input_tokens",
        "cached_input_tokens",
        "output_tokens",
    )
    buckets = [report["totals"], *report["days"]]
    for source in report["sources"]:
        buckets.append(source)
        buckets.extend(source["models"])
    for bucket in buckets:
        for key in counters:
            assert 0 <= bucket[key] <= USAGE_PUBLISHED_COUNT_BOUND
        assert bucket["cached_input_tokens"] <= bucket["input_tokens"]
        assert bucket["token_reports"] <= bucket["requests"]

    # The three groupings are three views of one set, so they must agree.
    for key in counters:
        assert sum(day[key] for day in report["days"]) == report["totals"][key]
        assert sum(source[key] for source in report["sources"]) == report["totals"][key]
        assert (
            sum(model[key] for source in report["sources"] for model in source["models"])
            == report["totals"][key]
        )


def test_the_row_cap_evicts_the_least_recently_metered_row(tmp_path: Path) -> None:
    """Review 4959575659 finding 8: evicting by spelling starves a live model.

    `model-a` sorts first by key and last by recency. Evicting by key would drop
    the row that was just written, so every later call for that model would be
    recreated and immediately evicted again while stale rows survived.
    """

    ledger = _ledger(tmp_path, max_rows=2)
    for index, model_id in enumerate(("model-y", "model-z", "model-a")):
        ledger.record(
            source_id="src_a",
            model_id=model_id,
            usage=None,
            at=NOW + timedelta(minutes=index),
        )

    assert [row["model_id"] for row in ledger.window(days=30, now=NOW)] == [
        "model-a",
        "model-z",
    ]

    ledger.record(
        source_id="src_a",
        model_id="model-a",
        usage=None,
        at=NOW + timedelta(minutes=3),
    )

    rows = {row["model_id"]: row for row in ledger.window(days=30, now=NOW)}
    assert rows["model-a"]["requests"] == 2


def test_a_new_call_is_metered_whatever_recency_the_ledger_already_claims(
    tmp_path: Path,
) -> None:
    """Review 4964314764: a clock that ran ahead must not stop metering.

    Every shape a persisted row can use to outrank the present fills a ledger that
    is already at its cap: a day after today, an instant that has not happened, and
    both together. `_recency` evicts the least recently metered, so each of them
    ranks above the call being recorded right now, and none of them reports
    anything — `window` refuses a day it cannot place. Stating the property rather
    than the three shapes means a fourth spelling of "later than now" is covered
    without editing this test.
    """

    clock = _Clock(NOW)
    ledger = _ledger(tmp_path, max_rows=3, now=clock)
    ahead = NOW + timedelta(days=400)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(day).isoformat(),
                    "source_id": "src_a",
                    "model_id": f"model-{index}",
                    "requests": 1,
                    "token_reports": 0,
                    "input_tokens": 0,
                    "cached_input_tokens": 0,
                    "output_tokens": 0,
                    "last_metered_at": instant.isoformat(),
                }
                for index, (day, instant) in enumerate(
                    ((ahead, ahead), (NOW, ahead), (ahead, NOW))
                )
            ]
        ),
        encoding="utf-8",
    )

    ledger.record(source_id="src_a", model_id="model-new", usage=None, at=NOW)

    rows = {row["model_id"]: row for row in ledger.window(days=30, now=NOW)}
    assert rows["model-new"]["requests"] == 1
    assert all(
        datetime.fromisoformat(row["last_metered_at"]) <= clock.moment for row in rows.values()
    )


def test_a_write_never_rewrites_what_a_later_stamped_write_already_persisted(
    tmp_path: Path,
) -> None:
    """Review 4964520496: one call's stamp cannot bound the whole ledger.

    Metering runs off the event loop, so concurrent calls reach the lock in
    whatever order the executor ran them, not in stamp order. Seed one row of
    every shape a later-stamped write can leave behind — an instant this write
    has not reached, and a day it has not reached — then let the earlier-stamped
    write land on top of them. It contributes its own row and nothing else;
    stating that rather than listing the two shapes covers whatever a later write
    persists next.
    """

    clock = _Clock(NOW)
    ledger = _ledger(tmp_path, now=clock)
    for model_id, stamp in (
        ("model-later-instant", NOW + timedelta(minutes=5)),
        ("model-later-day", NOW + timedelta(days=1)),
    ):
        clock.moment = stamp
        ledger.record(source_id="src_a", model_id=model_id, usage=None, at=stamp)
    persisted = {row["model_id"]: row for row in json.loads(ledger.path.read_text("utf-8"))}

    # Captured before both of them, reaching the lock after both.
    ledger.record(source_id="src_a", model_id="model-earlier", usage=None, at=NOW)

    after = {row["model_id"]: row for row in json.loads(ledger.path.read_text("utf-8"))}
    assert {model_id: after.get(model_id) for model_id in persisted} == persisted
    assert after["model-earlier"]["requests"] == 1


@pytest.mark.parametrize(
    "content",
    [
        pytest.param("", id="empty"),
        pytest.param("not json", id="unparseable"),
        pytest.param('{"rows": []}', id="object-instead-of-list"),
        pytest.param("[1, 2, 3]", id="scalar-rows"),
        pytest.param('[{"source_id": "src_a"}]', id="row-missing-day"),
        pytest.param('[{"day": "not-a-day", "source_id": "s", "model_id": "m"}]', id="row-bad-day"),
    ],
)
def test_an_unreadable_ledger_degrades_to_empty_and_keeps_recording(
    tmp_path: Path,
    content: str,
) -> None:
    """A broken optional-feature file disables the feature; it never fails."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(content, encoding="utf-8")

    assert ledger.window(days=30, now=NOW) == []

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
    assert ledger.summary(days=30, now=NOW)["totals"]["requests"] == 1


def test_a_row_with_unusable_counters_loads_as_zero(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": -4,
                    "token_reports": True,
                    "input_tokens": "many",
                    "output_tokens": 1.5,
                }
            ]
        ),
        encoding="utf-8",
    )

    row = ledger.window(days=30, now=NOW)[0]
    assert row["requests"] == 0
    assert row["token_reports"] == 0
    assert row["input_tokens"] == 0
    assert row["cached_input_tokens"] == 0
    assert row["output_tokens"] == 0


@pytest.mark.parametrize(
    ("context_tier", "kept"),
    [
        pytest.param(0, True, id="base-spelled-out"),
        pytest.param(272_000, True, id="tier"),
        pytest.param(-1, False, id="negative"),
        pytest.param(True, False, id="bool"),
        pytest.param(1.5, False, id="float"),
        pytest.param("272000", False, id="text"),
        pytest.param(None, False, id="null"),
    ],
)
def test_a_row_whose_context_tier_is_not_a_size_is_dropped(
    tmp_path: Path, context_tier: object, kept: bool,
) -> None:
    """MH-USAGE-BACKEND-009: the context tier is part of a row's identity, so an unreadable one drops its row."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    row = {
        "day": local_usage_day(NOW).isoformat(),
        "source_id": "src_a",
        "model_id": "model-x",
        "requests": 1,
        "token_reports": 0,
        "input_tokens": 0,
        "cached_input_tokens": 0,
        "output_tokens": 0,
        "last_metered_at": NOW.isoformat(),
    }
    ledger.path.write_text(
        json.dumps([{**row, "model_id": "model-y"}, {**row, "context_tier": context_tier}]),
        encoding="utf-8",
    )

    held = {row["model_id"]: row.get("context_tier", 0) for row in ledger.window(days=30, now=NOW)}
    assert held == ({"model-x": context_tier, "model-y": 0} if kept else {"model-y": 0})


@pytest.mark.parametrize(
    "persisted",
    [
        pytest.param("yesterday", id="not-a-datetime"),
        pytest.param("2026-07-23", id="date-only"),
        pytest.param("", id="empty"),
        pytest.param(1753272000, id="epoch-number"),
    ],
)
def test_an_unparseable_instant_degrades_to_absent(tmp_path: Path, persisted: object) -> None:
    """The read surface promises a date-time, so a corrupt value never travels."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "last_metered_at": persisted,
                }
            ]
        ),
        encoding="utf-8",
    )

    row = ledger.window(days=30, now=NOW)[0]
    assert row["requests"] == 1
    assert row["last_metered_at"] is None


def test_the_later_instant_wins_even_when_its_text_sorts_first(tmp_path: Path) -> None:
    """Text order is not time order once two rows carry different offsets."""

    earlier = datetime(2026, 7, 23, 20, 0, tzinfo=timezone(timedelta(hours=8)))
    later = datetime(2026, 7, 23, 13, 0, tzinfo=timezone.utc)
    assert later.isoformat() < earlier.isoformat() and later > earlier

    ledger = _ledger(tmp_path)
    day = local_usage_day(NOW).isoformat()
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": day,
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "last_metered_at": earlier.isoformat(),
                },
                {
                    "day": day,
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "last_metered_at": later.isoformat(),
                },
            ]
        ),
        encoding="utf-8",
    )

    assert ledger.window(days=30, now=NOW)[0]["last_metered_at"] == later.isoformat()


def test_a_persisted_cached_count_above_its_input_is_repaired_on_read(tmp_path: Path) -> None:
    """The subset invariant is a read-surface promise, not only a wire check."""

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 120,
                    "cached_input_tokens": 900,
                    "output_tokens": 4,
                }
            ]
        ),
        encoding="utf-8",
    )

    row = ledger.window(days=30, now=NOW)[0]
    assert row["input_tokens"] == 120
    assert row["cached_input_tokens"] == 120


def test_a_persisted_report_count_above_its_requests_is_repaired_on_read(
    tmp_path: Path,
) -> None:
    """Review 4959575659 finding 9: coverage can be partial, never over 100%.

    `requests` is self-measured and `token_reports` counts a subset of it, so a
    corrupt file degrades into a smaller true statement rather than claiming more
    reports than there were calls.
    """

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 3,
                    "token_reports": 40,
                    "input_tokens": 120,
                    "cached_input_tokens": 8,
                    "output_tokens": 4,
                }
            ]
        ),
        encoding="utf-8",
    )

    assert ledger.summary(days=30, now=NOW)["totals"] == {
        "requests": 3,
        "token_reports": 3,
        "input_tokens": 120,
        "cached_input_tokens": 8,
        "output_tokens": 4,
        # A released row: its reports are repaired first, then all count as
        # uncaptured cache-write evidence.
        "cache_write_input_tokens": 0,
        "cache_write_1h_input_tokens": 0,
        "cache_write_30m_input_tokens": 0,
        "cache_write_12h_input_tokens": 0,
        "cache_write_uncaptured_reports": 3,
        "cache_write_ttl_uncaptured_reports": 0,
    }


def test_a_day_in_another_valid_iso_spelling_still_lands_in_its_window(
    tmp_path: Path,
) -> None:
    """Review 4960570946: the window compares days this module spelled.

    `date.fromisoformat` also reads `20260723` and `2026-W30-4`, and the window
    bounds are `YYYY-MM-DD` text. A row kept in the file's own spelling would
    therefore sort outside every window it belongs to and vanish from the tab —
    without even being counted as dropped, since it parsed perfectly well.
    """

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    day = local_usage_day(NOW)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": day.strftime("%Y%m%d"),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 4,
                    "cached_input_tokens": 0,
                    "output_tokens": 2,
                    "last_metered_at": NOW.isoformat(),
                }
            ]
        ),
        encoding="utf-8",
    )

    rows = ledger.window(days=30, now=NOW)

    assert [row["day"] for row in rows] == [day.isoformat()]
    assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 4


def test_every_decode_failure_degrades_the_ledger_instead_of_raising(
    tmp_path: Path,
    caplog: pytest.LogCaptureFixture,
) -> None:
    """Review 4960570946: degradation is by failure category, not by shape.

    `JSONDecodeError` is only one way a file fails to decode. Invalid UTF-8 and
    an integer past the digit limit both raise a plain `ValueError`, deep nesting
    raises `RecursionError`, and any of them escaping the ledger would fail the
    read route and then stop metering for good — the loud failure this
    degradation exists to prevent.
    """

    payloads = (
        b"\xff\xfe not utf-8",
        ("[" + "9" * 8000 + "]").encode("utf-8"),
        b"[" * 10_000 + b"0" + b"]" * 10_000,
    )
    for payload in payloads:
        ledger = _ledger(tmp_path)
        ledger.path.parent.mkdir(parents=True, exist_ok=True)
        ledger.path.write_bytes(payload)

        with caplog.at_level(logging.WARNING):
            assert ledger.window(days=30, now=NOW) == []

        assert any("unreadable" in record.message for record in caplog.records)
        caplog.clear()
        # Metering keeps working, and the next write replaces the broken file.
        ledger.record(
            source_id="src_a",
            model_id="model-x",
            usage=ProtocolUsageReport.of(
                input_tokens=4,
                cached_input_tokens=0,
                output_tokens=2,
            ),
            at=NOW,
        )
        assert ledger.summary(days=30, now=NOW)["totals"]["requests"] == 1


def test_a_persisted_instant_is_published_in_the_shape_the_schema_promises(
    tmp_path: Path,
) -> None:
    """Reviews 4960016618 and 4960570946: this module decides the spelling.

    `datetime.fromisoformat` accepts far more than RFC 3339 does — naive,
    space-separated, and, after an offset, seconds. Republishing the parsed value
    in the file's own offset only moved the problem, so the file now supplies the
    instant and the module supplies the spelling: UTC, hence `+00:00`, whatever
    was written. A naive value is still read in the local calendar the day
    buckets use.
    """

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    written = {
        "naive": "2026-07-23 12:00",
        # A valid `fromisoformat` spelling with an offset RFC 3339 cannot express.
        "second_bearing_offset": "2026-07-23T12:00:00+00:00:30",
    }
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": f"src_{key}",
                    "model_id": "model-x",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 4,
                    "cached_input_tokens": 0,
                    "output_tokens": 2,
                    "last_metered_at": value,
                }
                for key, value in written.items()
            ]
        ),
        encoding="utf-8",
    )

    published = {
        row["source_id"]: row["last_metered_at"] for row in ledger.window(days=30, now=NOW)
    }

    assert published["src_naive"] == (
        datetime(2026, 7, 23, 12, 0).astimezone(timezone.utc).isoformat()
    )
    assert published["src_second_bearing_offset"] == "2026-07-23T11:59:30+00:00"
    assert all(value.endswith("+00:00") for value in published.values())


def test_a_written_row_is_validated_the_same_way_a_persisted_one_is(
    tmp_path: Path,
) -> None:
    """One validation path: what this module writes, it could also have read."""

    ledger = _ledger(tmp_path)
    ledger.record(
        source_id="src_a",
        model_id="model-x",
        usage=ProtocolUsageReport(input_tokens=40, cached_input_tokens=12, output_tokens=7),
        at=NOW,
    )

    persisted = json.loads(ledger.path.read_text(encoding="utf-8"))
    assert persisted == ledger.window(days=30, now=NOW)


@pytest.mark.parametrize(
    "content",
    [
        pytest.param("not json", id="unparseable"),
        pytest.param('{"rows": []}', id="object-instead-of-list"),
        pytest.param('[{"day": "not-a-day", "source_id": "s", "model_id": "m"}]', id="bad-row"),
    ],
)
def test_rejecting_existing_ledger_state_is_warned_not_silent(
    tmp_path: Path,
    caplog: pytest.LogCaptureFixture,
    content: str,
) -> None:
    """Review 4959575659 finding 12: the next write erases what was rejected.

    Degrading to empty is the persisted-shape rule; doing it quietly would spend
    the last moment the old history was recoverable.
    """

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(content, encoding="utf-8")

    with caplog.at_level(logging.WARNING, logger="core.handlers.model_hub.usage"):
        assert ledger.window(days=30, now=NOW) == []

    assert [record.levelno for record in caplog.records] == [logging.WARNING]


def test_duplicate_persisted_rows_merge_instead_of_shadowing(tmp_path: Path) -> None:
    """An older file could hold the same key twice; both counts must survive."""

    ledger = _ledger(tmp_path)
    row = {
        "day": local_usage_day(NOW).isoformat(),
        "source_id": "src_a",
        "model_id": "model-x",
        "requests": 2,
        "token_reports": 2,
        "input_tokens": 50,
        "cached_input_tokens": 0,
        "output_tokens": 5,
    }
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(json.dumps([row, dict(row)]), encoding="utf-8")

    rows = ledger.window(days=30, now=NOW)
    assert len(rows) == 1
    assert rows[0]["requests"] == 4
    assert rows[0]["input_tokens"] == 100


def test_accumulated_counters_are_exact_past_the_per_report_ceiling(tmp_path: Path) -> None:
    """An aggregate is a sum, not a capped one.

    The per-report ceiling exists so one hostile response cannot poison the
    ledger; it says nothing about how much a user may spend across many honest
    ones. Reusing it on the sum truncated real usage: the totals card showed a
    figure that was the ceiling rather than the usage, and nothing on the page
    could tell the difference. Every level the summary publishes is checked,
    because each one accumulates separately and a clamp left on any of them
    reappears as the same silent lie.
    """

    ledger = _ledger(tmp_path)
    maximal = ProtocolUsageReport(input_tokens=USAGE_REPORT_TOKEN_CEILING)

    ledger.record(source_id="src_a", model_id="model-x", usage=maximal, at=NOW)
    ledger.record(source_id="src_a", model_id="model-x", usage=maximal, at=NOW)

    expected = 2 * USAGE_REPORT_TOKEN_CEILING
    summary = ledger.summary(days=30, now=NOW)
    assert summary["totals"]["input_tokens"] == expected
    assert summary["sources"][0]["input_tokens"] == expected
    assert summary["sources"][0]["models"][0]["input_tokens"] == expected
    assert summary["days"][0]["input_tokens"] == expected


def test_a_cached_input_share_survives_a_window_past_the_per_report_ceiling(
    tmp_path: Path,
) -> None:
    """The share is the reason a clamped aggregate could not stay hidden.

    Clamping input and its cached subset independently pinned both to the same
    ceiling, so the ratio converged on exactly 100% — a broken number wearing the
    appearance of perfect caching. The proportions here are a real week's:
    billions of input tokens at a cached share in the nineties.
    """

    ledger = _ledger(tmp_path)
    report = ProtocolUsageReport.of(
        input_tokens=500_000_000,
        cached_input_tokens=475_000_000,
        output_tokens=2_000_000,
    )
    for day in range(7):
        at = NOW - timedelta(days=day)
        for _ in range(2):
            ledger.record(source_id="src_a", model_id="model-x", usage=report, at=at)

    totals = ledger.summary(days=7, now=NOW)["totals"]
    assert totals["input_tokens"] == 14 * 500_000_000
    assert totals["cached_input_tokens"] == 14 * 475_000_000
    assert totals["cached_input_tokens"] < totals["input_tokens"]
    assert totals["cached_input_tokens"] / totals["input_tokens"] == pytest.approx(0.95)


def test_a_persisted_counter_past_the_representation_drops_its_row(
    tmp_path: Path,
) -> None:
    """The one bound this module keeps, and why it drops rather than saturates.

    A counter past 2**53 - 1 is not a count the file can hold, and no sum this
    module writes can reach it, so the probe has to come from a file nothing here
    would have produced. Saturating it would publish a number nobody spent — and
    saturating this row's input and cached-input together would publish it as a
    100% cached share, the exact artifact this ledger exists to not produce.
    """

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": "model-x",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": USAGE_COUNTER_CEILING * 4,
                    "cached_input_tokens": USAGE_COUNTER_CEILING * 4,
                    "output_tokens": 0,
                    "last_metered_at": NOW.isoformat(),
                }
            ]
        ),
        encoding="utf-8",
    )

    assert ledger.window(days=30, now=NOW) == []
    assert ledger.summary(days=30, now=NOW)["totals"] == _as_released(
        dict.fromkeys(("requests", "token_reports", "input_tokens", "cached_input_tokens", "output_tokens"), 0)
    )


def test_a_merge_the_file_cannot_hold_is_refused_by_every_surface(
    tmp_path: Path,
    caplog: pytest.LogCaptureFixture,
) -> None:
    """Where an exact merge outgrows the file, and what every surface does with it.

    Two duplicate-keyed rows are something only a corrupt or hand-merged file
    holds, and `_read` folds them exactly — so their sum can exceed what a counter
    is written and read back as, on a value that was admitted one row at a time.

    This once asserted that the summary published that sum anyway, which was
    coherent while the contract declared no maximum: an exact aggregate was the
    honest answer and nothing downstream claimed a range. Restoring a derived
    maximum changed what the producer owes. A merged counter is bounded by how
    many duplicates the file holds, which is bounded by nothing, so publishing one
    unreduced means publishing counts the contract rejects — `USAGE_MAX_ROWS`
    rows can only bound a total while each of them is itself bounded.

    So the row is refused, not reduced, and now every surface says the same thing.
    A sum of cleared addends is not itself cleared, and the one rule every door
    already applied — a magnitude no published document could carry is dropped,
    never saturated — is what makes the bound hold. It is also what heals the
    file: the bucket disappears rather than pinning at the ceiling, and the next
    call starts a row that means what it says.
    """

    half = USAGE_COUNTER_CEILING // 2 + 1
    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    duplicate = {
        "day": local_usage_day(NOW).isoformat(),
        "source_id": "src_a",
        "model_id": "model-x",
        "requests": 1,
        "token_reports": 1,
        "input_tokens": half,
        "cached_input_tokens": 0,
        "output_tokens": 0,
        "last_metered_at": NOW.isoformat(),
    }
    ledger.path.write_text(json.dumps([duplicate, dict(duplicate)]), encoding="utf-8")

    with caplog.at_level(logging.WARNING, logger="core.handlers.model_hub.usage"):
        assert ledger.summary(days=30, now=NOW)["totals"]["input_tokens"] == 0

    assert any(
        "merged counters outgrew what the file can carry" in record.message
        for record in caplog.records
    )
    assert 2 * half > USAGE_COUNTER_CEILING

    # Refusing the row on the way in is also what stops the batch that follows
    # from being swallowed. The fold used to land on the unusable bucket and go
    # down with it when `_write` refused the result; now the bucket is already
    # gone, so this call is recorded rather than lost.
    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)

    persisted = json.loads(ledger.path.read_text(encoding="utf-8"))
    assert [(row["requests"], row["input_tokens"]) for row in persisted] == [(1, 0)]

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
    totals = ledger.summary(days=30, now=NOW)["totals"]
    assert totals["requests"] == 2
    assert totals["input_tokens"] == 0


@pytest.mark.parametrize(
    "source_id,model_id",
    [
        pytest.param("", "model-x", id="empty-source"),
        pytest.param("src_a", "", id="empty-model"),
    ],
)
def test_an_unusable_identifier_is_never_persisted(
    tmp_path: Path,
    caplog: pytest.LogCaptureFixture,
    source_id: str,
    model_id: str,
) -> None:
    """Loud, not silent: a dropped turn is lost metering, not a tidy no-op.

    What reaches here is a caller that invented an identifier, not a config that
    holds an awkward one — the test below pins that boundary. A length is not a
    reason to drop a call, so the only refusals left are values carrying no
    identity at all.
    """

    ledger = _ledger(tmp_path)

    with caplog.at_level(logging.WARNING, logger="core.handlers.model_hub.usage"):
        ledger.record(source_id=source_id, model_id=model_id, usage=None, at=NOW)

    assert ledger.window(days=30, now=NOW) == []
    assert [record.levelno for record in caplog.records] == [logging.WARNING]


@pytest.mark.parametrize(
    "identifier",
    [
        pytest.param("model-x", id="ordinary"),
        pytest.param("  model-x  ", id="padded"),
        pytest.param("   ", id="padding-only"),
        pytest.param(
            "m" * USAGE_LEDGER_VERBATIM_MAX_LENGTH,
            id="at-the-ledger-verbatim-bound",
        ),
        pytest.param(
            "m" * (USAGE_LEDGER_VERBATIM_MAX_LENGTH + 1),
            id="one-past-the-ledger-verbatim-bound",
        ),
        pytest.param("m" * 256, id="at-the-former-admission-bound"),
        pytest.param("m" * 257, id="past-the-former-admission-bound"),
        pytest.param("m" * (USAGE_LEDGER_KEY_MAX_LENGTH * 4), id="far-past-it"),
        pytest.param("模型🧪/e\u0301" * 3000, id="long-unicode"),
        pytest.param("", id="empty"),
        pytest.param(None, id="not-text"),
    ],
)
def test_metering_can_key_exactly_the_identities_a_config_can_hold(identifier: object) -> None:
    """MH-USAGE-006: loading and metering do not reapply new-ID admission.

    This population covers ordinary, long, padded, and short blank historical
    text. It is not a proof over every loadable legacy value: long all-whitespace
    and unencodable historical IDs have known exceptions recorded in the
    identifier-boundary assessment.

    Keying the loaded value and the raw payload alike stops one model from occupying
    two rows. The length assertion is the review-4966041599 property: a key is either
    within the stable verbatim bound or exactly a folded key's length, never in
    between. A literal occupying the folded form is folded again on live derivation.
    The separate read path
    returns a derived key unchanged, so a row read back after a restart is the row
    that was written — the guarantee that used to be spelled as self-idempotence,
    which is what forced the fold to start too late.
    """

    try:
        loadable = ModelHubModelConfig.from_payload(
            {"id": identifier, "origin": "manual", "reasoning_efforts": []}
        ).id
    except ValueError:
        loadable = None

    key = usage_ledger_key(identifier)

    assert (key is None) == (loadable is None)
    if key is None:
        return
    assert (
        len(key) <= USAGE_LEDGER_VERBATIM_MAX_LENGTH
        or len(key) == USAGE_LEDGER_KEY_MAX_LENGTH
    )
    assert usage_ledger_key(loadable) == key
    assert persisted_ledger_key(key) == key


@pytest.mark.parametrize(
    "model_id",
    [
        pytest.param(
            "m" * USAGE_LEDGER_VERBATIM_MAX_LENGTH,
            id="at-the-ledger-verbatim-bound",
        ),
        pytest.param(
            "m" * (USAGE_LEDGER_VERBATIM_MAX_LENGTH + 1),
            id="one-past-the-ledger-verbatim-bound",
        ),
        pytest.param("m" * 256, id="at-the-former-admission-bound"),
        pytest.param("m" * 257, id="past-the-former-admission-bound"),
        pytest.param("m" * (USAGE_LEDGER_KEY_MAX_LENGTH * 4), id="far-past-it"),
        pytest.param("模型🧪/e\u0301" * 3000, id="long-unicode"),
    ],
)
def test_a_model_a_legacy_file_still_routes_accumulates_one_row_across_restarts(
    tmp_path: Path, model_id: str
) -> None:
    """MH-USAGE-006: an upgraded install must not look quieter than it is.

    Three separate ledgers over one file, because a key derived per process would
    give this model a fresh row on every restart — bounded away again by retention
    before it could ever add up. Two calls, one row, whatever the identifier's
    length.
    """

    _ledger(tmp_path).record(source_id="src_a", model_id=model_id, usage=None, at=NOW)
    _ledger(tmp_path).record(source_id="src_a", model_id=model_id, usage=None, at=NOW)

    rows = _ledger(tmp_path).window(days=30, now=NOW)

    assert [(row["model_id"], row["requests"]) for row in rows] == [
        (usage_ledger_key(model_id), 2)
    ]
    assert len(rows[0]["model_id"]) <= USAGE_LEDGER_KEY_MAX_LENGTH


def test_two_identities_sharing_a_bounded_head_are_metered_apart(tmp_path: Path) -> None:
    """MH-USAGE-006: the bound is a fold, and a fold that loses the tail merges rows.

    Truncation alone is the obvious way to bound a key and the wrong one: these two
    models differ only past the head a truncated key would keep, so one of them
    would be billed for the other's calls. What separates them is a digest of the
    whole identity, which no padding can collide with.
    """

    ledger = _ledger(tmp_path)
    head = "m" * (USAGE_LEDGER_KEY_MAX_LENGTH * 2)

    ledger.record(source_id="src_a", model_id=f"{head}-one", usage=None, at=NOW)
    ledger.record(source_id="src_a", model_id=f"{head}-two", usage=None, at=NOW)

    rows = ledger.window(days=30, now=NOW)

    assert len({row["model_id"] for row in rows}) == 2
    assert [row["requests"] for row in rows] == [1, 1]


def test_no_two_identities_a_config_holds_can_share_one_row(tmp_path: Path) -> None:
    """MH-USAGE-007: folded-looking live literals are not persisted-key reads.

    Every seed and two generations of its derived keys are admitted as distinct
    model identities. Live derivation, repeated reloads, aggregation, and full
    label joins must agree for this nonblank UTF-8 population. This is regression
    evidence, not a mathematical injectivity claim or a guarantee for malformed
    legacy text.
    """

    seeds = (
        "model-x",
        "m" * USAGE_LEDGER_VERBATIM_MAX_LENGTH,
        "m" * (USAGE_LEDGER_VERBATIM_MAX_LENGTH + 1),
        "n" * 256,
        "n" * 257,
        "z" * (USAGE_LEDGER_KEY_MAX_LENGTH * 3),
        "模型🧪/e\u0301" * 3000 + "-one",
        "模型🧪/e\u0301" * 3000 + "-two",
        "é",
        "e\u0301",
        "x" * 16385,
    )
    first_generation = {usage_ledger_key(seed) for seed in seeds}
    identities = sorted({
        *seeds, *first_generation, *(usage_ledger_key(key) for key in first_generation),
    })

    ledger = _ledger(tmp_path)
    for identity in identities:
        assert canonical_model_id(identity) == identity
        assert persisted_ledger_key(usage_ledger_key(identity)) == usage_ledger_key(identity)
        assert (
            ModelHubModelConfig.from_payload(
                {"id": identity, "origin": "manual", "reasoning_efforts": []}
            ).id
            == identity
        )
        ledger.record(source_id="src_a", model_id=identity, usage=None, at=NOW)

    rows = ledger.window(days=30, now=NOW)

    assert len({usage_ledger_key(identity) for identity in identities}) == len(identities)
    assert [row["requests"] for row in rows] == [1] * len(identities)
    original_keys = {row["model_id"] for row in rows}
    for expected_requests in (2, 3):
        ledger = _ledger(tmp_path)
        for identity in identities:
            ledger.record(source_id="src_a", model_id=identity, usage=None, at=NOW)
        rows = _ledger(tmp_path).window(days=30, now=NOW)
        assert {row["model_id"] for row in rows} == original_keys
        assert [row["requests"] for row in rows] == [expected_requests] * len(identities)
    summary = _ledger(tmp_path).summary(
        days=30, now=NOW,
        identities=[SourceIdentity(source_id="src_a", label="source", model_ids=identities)],
    )
    assert {model["model_id"]: model["label"] for model in summary["sources"][0]["models"]} == {
        usage_ledger_key(identity): identity for identity in identities
    }


@pytest.mark.parametrize(
    "key",
    [
        pytest.param(
            "m" * USAGE_LEDGER_VERBATIM_MAX_LENGTH,
            id="a-verbatim-key",
        ),
        pytest.param(
            usage_ledger_key("m" * (USAGE_LEDGER_VERBATIM_MAX_LENGTH + 1)),
            id="a-folded-key",
        ),
        pytest.param("m" * (USAGE_LEDGER_KEY_MAX_LENGTH + 1), id="one-past-every-derivable-key"),
        pytest.param("m" * (USAGE_LEDGER_KEY_MAX_LENGTH * 8), id="far-past-them"),
    ],
)
def test_a_row_is_read_back_exactly_when_its_key_is_one_a_write_could_derive(
    tmp_path: Path, key: str
) -> None:
    """MH-USAGE-007: reading a row is the direction that may refuse.

    A row is not a call — it is what an earlier write claims about calls — so a key
    no write of this ledger could have produced is a corrupt row, and refusing it
    loses a claim rather than a served call. That refusal is also what keeps a
    persisted row bounded, since the read path is where a hand-edited file arrives.
    """

    derivable = len(key) <= USAGE_LEDGER_KEY_MAX_LENGTH
    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": "src_a",
                    "model_id": key,
                    "requests": 1,
                }
            ]
        ),
        encoding="utf-8",
    )

    kept = [row["model_id"] for row in ledger.window(days=30, now=NOW)]

    assert kept == ([key] if derivable else [])


def test_the_ledger_file_is_owner_only(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)

    assert stat.S_IMODE(os.stat(ledger.path).st_mode) == 0o600


def test_a_record_leaves_no_temporary_file_behind(tmp_path: Path) -> None:
    ledger = _ledger(tmp_path)

    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)

    assert [entry.name for entry in ledger.path.parent.iterdir()] == [ledger.path.name]


@pytest.mark.skipif(
    os.name != "posix" or os.geteuid() == 0,
    reason="needs POSIX directory permissions, which root ignores",
)
def test_a_write_that_fails_leaves_neither_residue_nor_a_damaged_document(
    tmp_path: Path,
) -> None:
    """MH-USAGE-003, review 4965677908: a failed replacement must cost only that write.

    The recorder above this ledger swallows `OSError` so a full disk cannot break
    metering, which means nobody downstream ever sees what a failed write left
    behind. A ledger bounded to `max_rows` whose state directory gains one orphan
    per failure is not bounded, and a half-written document would lose the days
    already recorded — so the write either lands whole or changes nothing.

    The failure is a genuinely unwritable directory rather than a patched
    ``os.replace``: the swap moved out of this package into ``config.atomic_io``,
    and a test that reaches for the mechanism has to be rewritten every time the
    mechanism moves. A real ``OSError`` from the filesystem does not care where
    the temp file was going to be created.
    """

    ledger = _ledger(tmp_path)
    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
    recorded = ledger.path.read_bytes()

    directory = ledger.path.parent
    directory.chmod(0o500)
    try:
        with pytest.raises(OSError):
            ledger.record(source_id="src_b", model_id="model-y", usage=None, at=NOW)

        assert [entry.name for entry in directory.iterdir()] == [ledger.path.name]
        assert ledger.path.read_bytes() == recorded
    finally:
        directory.chmod(0o700)


def test_days_bucket_by_the_host_calendar_not_utc(tmp_path: Path) -> None:
    """Avibe is local-first, so a day boundary is the user's midnight."""

    moment = datetime(2026, 7, 23, 21, 30, tzinfo=timezone.utc)
    expected = datetime.fromtimestamp(moment.timestamp()).date()

    assert local_usage_day(moment) == expected

    ledger = _ledger(tmp_path)
    ledger.record(source_id="src_a", model_id="model-x", usage=None, at=moment)
    assert ledger.window(days=1, now=moment)[0]["day"] == expected.isoformat()


def test_one_local_day_holds_moments_from_two_utc_days(tmp_path: Path) -> None:
    """Bucketing must follow the host's calendar consistently, whatever it is."""

    ledger = _ledger(tmp_path)
    local_noon = datetime.combine(date(2026, 7, 23), datetime.min.time()).astimezone() + timedelta(hours=12)

    for offset in (timedelta(hours=-11), timedelta(hours=11)):
        ledger.record(source_id="src_a", model_id="model-x", usage=None, at=local_noon + offset)

    rows = ledger.window(days=1, now=local_noon)
    assert len(rows) == 1
    assert rows[0]["day"] == "2026-07-23"
    assert rows[0]["requests"] == 2


def _keying_populations(prefix: str) -> tuple[str, ...]:
    """One identity from each population `usage_ledger_key` can put a key in.

    A key is either the identity itself or a bounded head plus a digest of it, and
    which one depends on a length no caller of the ledger is asked about. Naming
    the populations here rather than a list of interesting strings is what makes a
    join test cover the fold without enumerating it.
    """

    def padded(length: int) -> str:
        return f"{prefix}{'a' * (length - len(prefix))}"

    return (
        padded(len(prefix) + 8),
        padded(USAGE_LEDGER_VERBATIM_MAX_LENGTH),
        padded(USAGE_LEDGER_VERBATIM_MAX_LENGTH + 1),
        padded(USAGE_LEDGER_KEY_MAX_LENGTH * 2),
    )


def test_a_label_reaches_the_row_of_every_identity_the_ledger_can_key(tmp_path: Path) -> None:
    """MH-USAGE-008, review 4966281026: a join is keyed the way its rows were.

    A label arrives as an identity and a row carries a key, and only this module
    knows that those differ. The version of the read that took an already-keyed
    mapping is what the rule looks like once it has leaked to a caller: the caller
    keyed its own map, looked a label up by `row["source_id"]`, and every identity
    the fold exists for silently reported no label at all while still existing —
    and never showed a rename either.

    Stated over the populations a key can be in rather than over the pair that
    exposed it, so an identity shape that becomes reachable later is covered here
    the moment it exists. The source IDs are `src_`-prefixed because config admits
    `src_[a-z0-9]{8,}` with no upper bound, so a folded Source key is reachable
    from a config that validates, not only from a legacy file.
    """

    sources = _keying_populations("src_")
    long_model = "模型🧪/e\u0301" * 3000
    folded_literal = usage_ledger_key(long_model)
    models = (*_keying_populations("model-"), long_model, folded_literal, usage_ledger_key(folded_literal))
    # The test is only the test while the seeds span both populations: an all-verbatim
    # set would pass against a read that never keyed anything.
    assert {identity == usage_ledger_key(identity) for identity in (*sources, *models)} == {
        True,
        False,
    }

    ledger = _ledger(tmp_path)
    for source_id in sources:
        for model_id in models:
            ledger.record(source_id=source_id, model_id=model_id, usage=None, at=NOW)
    ledger = _ledger(tmp_path)

    def summarize(naming: str) -> dict:
        return ledger.summary(
            days=30,
            now=NOW,
            identities=[
                SourceIdentity(source_id=source_id, label=f"{naming} {source_id}", model_ids=models)
                for source_id in sources
            ],
        )

    for naming in ("named", "renamed"):
        by_source = {source["source_id"]: source for source in summarize(naming)["sources"]}
        assert set(by_source) == {usage_ledger_key(identity) for identity in sources}
        for source_id in sources:
            source = by_source[usage_ledger_key(source_id)]
            assert source["label"] == f"{naming} {source_id}"
            by_model = {model["model_id"]: model for model in source["models"]}
            assert set(by_model) == {usage_ledger_key(identity) for identity in models}
            for model_id in models:
                assert by_model[usage_ledger_key(model_id)]["label"] == model_id


def test_a_label_no_config_still_holds_is_absent_rather_than_stale(tmp_path: Path) -> None:
    """MH-USAGE-008: the join is why a deleted Source reads as deleted.

    Persisting the label would freeze a copy of user-supplied text in a file this
    ledger keeps for two months. Joining it means a row whose identity config no
    longer holds publishes no label — which is the honest reading, since the usage
    happened and the thing that produced it is gone.
    """

    ledger = _ledger(tmp_path)
    ledger.record(source_id="src_gone0001", model_id="model-gone", usage=None, at=NOW)

    source = ledger.summary(days=30, now=NOW, identities=[])["sources"][0]

    assert source["label"] is None
    assert source["models"][0]["label"] is None


def test_a_model_label_is_scoped_to_the_source_it_was_metered_under(tmp_path: Path) -> None:
    """MH-USAGE-013, review 4967250750: a metered model's identity is the pair.

    A common model ID exists precisely so several Sources can offer it, so a label
    looked up by model ID alone answers for whichever Source happens to ask. A model
    removed from one Source therefore kept its label there for as long as any other
    Source still listed it, and a retained row read as though its own identity were
    still configured.

    Stated as the biconditional over every pair the ledger holds: a label is
    published exactly when config lists that model under that Source. Both
    directions are the test — a join that labels everything and one that labels
    nothing each satisfy only half — and the models span both key populations, so
    the scoping has to survive the fold as well as the verbatim case.
    """

    listing, withholding = "src_lists001", "src_hides001"
    models = _keying_populations("model-")
    ledger = _ledger(tmp_path)
    for source_id in (listing, withholding):
        for model_id in models:
            ledger.record(source_id=source_id, model_id=model_id, usage=None, at=NOW)

    summary = ledger.summary(
        days=30,
        now=NOW,
        identities=[
            SourceIdentity(source_id=listing, label="lists", model_ids=models),
            # Configured, so its own label is present: what config no longer holds is
            # only this Source's listing of these models.
            SourceIdentity(source_id=withholding, label="hides", model_ids=()),
        ],
    )

    assert {source["source_id"] for source in summary["sources"]} == {
        usage_ledger_key(listing),
        usage_ledger_key(withholding),
    }
    assert all(source["label"] is not None for source in summary["sources"])
    assert {
        (source["source_id"], model["model_id"]): model["label"]
        for source in summary["sources"]
        for model in source["models"]
    } == {
        (usage_ledger_key(source_id), usage_ledger_key(model_id)): (
            model_id if source_id == listing else None
        )
        for source_id in (listing, withholding)
        for model_id in models
    }


def test_an_instant_no_conversion_can_carry_never_stops_metering(tmp_path: Path) -> None:
    """MH-USAGE-014, review 4967250750: the conversion is the bound, not a year range.

    `datetime` conversion is not total. A value near either end of the representable
    range, offset far enough, leaves that range on the way to another zone and raises
    `OverflowError` — an `ArithmeticError`, so it passes straight through a handler
    written for bad data and out of the flush task, stopping metering for the rest of
    the process while the row that caused it stays on disk.

    Bounding the accepted years would leave a free parameter for the next value to
    probe, so the conversion itself is the bound: what this module carries is what its
    own conversions return. Persisted text degrades to absent; a caller's moment
    cannot be lost, so it dates the row by the only instant the module can measure.
    """

    uncarriable = ("0001-01-01T00:00:00+14:00", "9999-12-31T23:59:59.999999-14:00")
    # Seeds are only seeds while they still break the naive conversion, and the
    # exception is the finding: `ArithmeticError` is not what a bad-data handler
    # catches, so this raises out of every caller that only guarded `ValueError`.
    for spelling in uncarriable:
        with pytest.raises(ArithmeticError):
            datetime.fromisoformat(spelling).astimezone(timezone.utc)

    ledger = _ledger(tmp_path)
    ledger.path.parent.mkdir(parents=True, exist_ok=True)
    ledger.path.write_text(
        json.dumps(
            [
                {
                    "day": local_usage_day(NOW).isoformat(),
                    "source_id": f"src_carry{index:03d}",
                    "model_id": "model-carry",
                    "requests": 1,
                    "token_reports": 1,
                    "input_tokens": 5,
                    "cached_input_tokens": 0,
                    "output_tokens": 0,
                    "last_metered_at": spelling,
                }
                for index, spelling in enumerate(uncarriable)
            ]
        ),
        encoding="utf-8",
    )

    summary = ledger.summary(days=30, now=NOW)

    assert summary["totals"]["input_tokens"] == 5 * len(uncarriable)
    assert [source["last_metered_at"] for source in summary["sources"]] == [None] * len(uncarriable)

    # The other direction of the same door: a caller reports a call an upstream
    # already billed, so an uncarriable moment dates the row by the instant this
    # module measures rather than dropping the usage.
    live = BoundedUsageLedger(tmp_path / "live" / "usage.json")
    for hours in (14, -14):
        edge = datetime.min if hours > 0 else datetime.max
        live.record(
            source_id="src_carry999",
            model_id="model-carry",
            usage=None,
            at=edge.replace(tzinfo=timezone(timedelta(hours=hours))),
        )

    rows = live.window(days=2, now=datetime.now(timezone.utc))
    assert len(rows) == 1
    assert rows[0]["requests"] == len((14, -14))
    stamped = rows[0]["last_metered_at"]
    assert stamped is not None
    assert rows[0]["day"] == local_usage_day(datetime.fromisoformat(stamped)).isoformat()


# --- Ownership: one queue, bounded by identity, loud when it loses a batch -----


def test_the_write_queue_is_bounded_by_identities_not_by_arrival_rate(tmp_path: Path) -> None:
    """MH-USAGE-009, review 4966281026: a backlog bound traffic cannot move.

    The queue exists so a served turn never waits on a disk, which means whatever
    arrives while a flush is out has to go somewhere. Bounding it by a capacity
    would mean choosing rows to drop — losing exactly the billed usage this module
    exists to keep — and blocking the caller would stall a turn on a disk that is
    already failing. So it folds: calls heading for one row become one queued row
    as they arrive, and the backlog is bounded by the identities config holds
    rather than by how hard the hub is driven.

    Driven with the flush held open, because that is the only window in which a
    backlog exists at all. 512 calls over four identities leave four queued rows,
    and all 512 are still metered — a bound that dropped calls would pass the
    first assertion and fail the last.
    """

    async def exercise() -> None:
        ledger = _ledger(tmp_path)
        writer = UsageWriter(ledger)
        identities = (
            ("src_a", "model-x"),
            ("src_a", "model-y"),
            ("src_b", "model-x"),
            ("src_b", "model-y"),
        )
        fold = ledger.record_many
        batches: list[int] = []
        holding = threading.Event()
        release = threading.Event()

        def counting(calls) -> None:
            batches.append(len(calls))
            if len(batches) == 1:
                holding.set()
                assert release.wait(5)
            fold(calls)

        ledger.record_many = counting

        # One call opens a flush and holds it on the writing thread; everything
        # below therefore arrives while a write is out, which is the scenario.
        writer.record(source_id="src_a", model_id="model-x", usage=None, at=NOW)
        while not holding.is_set():
            await asyncio.sleep(0.01)

        for index in range(512):
            source_id, model_id = identities[index % len(identities)]
            writer.record(
                source_id=source_id,
                model_id=model_id,
                usage=ProtocolUsageReport(input_tokens=1, output_tokens=1),
                at=NOW,
            )

        assert len(writer._pending) == len(identities)
        # Calls, not rows: a backlog must not look like it shrank because the hub
        # got busier.
        assert writer.unpersisted == 512 + 1
        release.set()

        assert await writer.drain(timeout=5) == 0
        # One transaction for the held call, one for every call behind it.
        assert batches == [1, len(identities)]

        totals = ledger.summary(days=1, now=NOW)["totals"]
        assert totals["requests"] == 512 + 1
        assert totals["token_reports"] == 512
        assert totals["input_tokens"] == 512
        assert totals["output_tokens"] == 512

    asyncio.run(exercise())


def test_a_ledger_that_cannot_be_written_is_reported_once_per_outage(
    tmp_path: Path, caplog: pytest.LogCaptureFixture
) -> None:
    """MH-USAGE-009: metering that stopped must not look like a hub with nothing to say.

    A failed batch is lost by design — a ledger that cannot be reached must not
    hold up the turns it meters — but a read-only state directory then reads
    exactly like an idle hub, which is the one reading that makes this module's
    absence invisible. Both edges of the outage are logged and nothing in between,
    so the volume follows how often the ledger changes state rather than how long
    it stays broken.
    """

    async def exercise() -> None:
        ledger = _ledger(tmp_path)
        writer = UsageWriter(ledger)
        fold = ledger.record_many
        broken = True

        def refuse(calls) -> None:
            if broken:
                raise OSError("read-only file system")
            fold(calls)

        ledger.record_many = refuse

        with caplog.at_level(logging.WARNING, logger="core.handlers.model_hub.usage"):
            for attempt in range(3):
                await writer.record(
                    source_id="src_a", model_id=f"model-{attempt}", usage=None, at=NOW
                )
            outage = [record.getMessage() for record in caplog.records]

            broken = False
            await writer.record(source_id="src_a", model_id="model-back", usage=None, at=NOW)
            recovery = [record.getMessage() for record in caplog.records][len(outage) :]

        assert len(outage) == 1 and "dropping metered calls" in outage[0]
        assert len(recovery) == 1 and "recovered" in recovery[0]
        # The three lost batches really were lost; only the recovered one landed.
        assert ledger.summary(days=1, now=NOW)["totals"]["requests"] == 1

    asyncio.run(exercise())


def test_a_wedged_ledger_write_cannot_hold_the_process_open(tmp_path: Path) -> None:
    """MH-USAGE-015, review 4967250750: metering must be abandonable, not just bounded.

    Every wait this module makes a caller do is bounded, which is what keeps a served
    turn from depending on a disk. Shutdown is the case where a bound is not enough:
    the write is still running when the last bounded wait has already returned, so the
    only question left is whether the process may walk away from it. Metering is
    optional, so it must — a stop or a restart that waits on an unresponsive disk is
    the hub failing at something it never promised.

    Run as a real process because that is where the property lives. `atexit` hooks and
    non-daemon thread joins run after the interpreter has finished with `__main__`, so
    nothing observable in-process distinguishes a worker the runtime will abandon from
    one it will wait on forever.
    """

    child = textwrap.dedent(
        """
        import threading
        from core.handlers.model_hub.usage import _ledger_executor

        wedged = threading.Event()
        started = threading.Event()

        def never_returns():
            started.set()
            wedged.wait()

        _ledger_executor().submit(never_returns)
        assert started.wait(10), "the ledger write never started"
        print("wedged", flush=True)
        """
    )

    result = subprocess.run(
        [sys.executable, "-c", child],
        cwd=Path(__file__).resolve().parents[1],
        capture_output=True,
        text=True,
        # Generous next to the ~0s a walk-away costs, and finite because a hang is
        # the defect: `TimeoutExpired` here is the test's failure signal.
        timeout=60,
    )

    assert result.stdout.split() == ["wedged"], result.stderr
    assert result.returncode == 0, result.stderr