@ngocsangairvds/vsaf 3.2.16 → 4.0.0

package/tools/vds-scripts/scheduler_orchestrator/tests/unit/test_llm_usage_collector.py

@@ -1,1095 +0,0 @@
-"""Unit tests for the LLMUsageCollector (TSK-P3-4.5, Phase 3 Wave 4).
-
-Coverage targets every branch called out in the lane brief:
-
-* Bootstrap (missing usage dir) → ``[unavailable]`` + zero deduction.
-* Aggregation by ``(provider, model)`` for today's file.
-* 24 h window — yesterday and old-day records correctly partitioned.
-* Pricing chain — exact match, provider wildcard, top-level fallback.
-* Cost > $5/day  → warning anomaly + health −5.
-* Tokens > 1 M  → informational anomaly + zero deduction.
-* Both anomalies firing simultaneously.
-* Malformed JSONL line — skipped, not crashing.
-* Unknown provider/model — fallback used, structlog warning emitted.
-* Boundary: call at ``now - 24 h`` (one second either side).
-* Health-deduction matrix — healthy=0, cost-warning=5, info-only=0.
-* Multi-day file selection.
-* Empty file is treated as zero traffic, not unavailable.
-
-All tests use ``tmp_path`` so the real ``~/.vds/cache/llm-usage/`` directory
-is never touched.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-from datetime import UTC, datetime, timedelta
-from pathlib import Path
-
-import pytest
-
-from vds_scheduler_orchestrator.workflows.collectors import llm_usage as llm_usage_mod
-from vds_scheduler_orchestrator.workflows.collectors.llm_usage import LLMUsageCollector
-from vds_scheduler_orchestrator.workflows.collectors.protocol import (
-    CollectorResult,
-    GoldenSignals,
-)
-
-# ──────────────────────────────────────────────────────────────────────────────
-# Helpers
-# ──────────────────────────────────────────────────────────────────────────────
-
-# Frozen "now" used across the deterministic-aggregation tests.
-FROZEN_NOW = datetime(2026, 4, 30, 12, 0, 0, tzinfo=UTC)
-
-
-def _make_record(
-    *,
-    provider: str = "openai",
-    model: str = "gpt-4o-2024-11-20",
-    prompt_tokens: int = 1000,
-    completion_tokens: int = 500,
-    timestamp: datetime | str = FROZEN_NOW,
-    request_id: str = "req-1",
-    cost_usd: float | None = None,
-) -> dict:
-    """Build one JSONL record matching the ``jsonl_exporter`` schema."""
-    record = {
-        "timestamp": (
-            timestamp.replace(microsecond=0).isoformat().replace("+00:00", "Z")
-            if isinstance(timestamp, datetime)
-            else timestamp
-        ),
-        "provider": provider,
-        "model": model,
-        "prompt_tokens": prompt_tokens,
-        "completion_tokens": completion_tokens,
-        "total_tokens": prompt_tokens + completion_tokens,
-        "request_id": request_id,
-    }
-    if cost_usd is not None:
-        record["cost_usd"] = cost_usd
-    return record
-
-
-def _write_jsonl(path: Path, records: list[dict]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("w", encoding="utf-8") as fh:
-        for record in records:
-            fh.write(json.dumps(record, separators=(",", ":")) + "\n")
-
-
-def _write_pricing(
-    path: Path,
-    *,
-    providers: dict | None = None,
-    fallback: dict | None = None,
-) -> Path:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    body_lines = ["version: 1", "currency: USD", "unit: per_1k_tokens", "providers:"]
-    if providers:
-        for provider_name, models in providers.items():
-            body_lines.append(f"  {provider_name}:")
-            for model_name, prices in models.items():
-                key = f'"{model_name}"' if model_name == "*" else model_name
-                body_lines.append(
-                    f"    {key}: {{input: {prices['input']}, output: {prices['output']}}}"
-                )
-    fb = fallback or {"input": 0.0, "output": 0.0}
-    body_lines.append(f"fallback: {{input: {fb['input']}, output: {fb['output']}}}")
-    path.write_text("\n".join(body_lines) + "\n", encoding="utf-8")
-    return path
-
-
-@pytest.fixture
-def freeze_now(monkeypatch: pytest.MonkeyPatch):
-    """Pin ``llm_usage._now`` to a deterministic UTC instant."""
-
-    def _frozen() -> datetime:
-        return FROZEN_NOW
-
-    monkeypatch.setattr(llm_usage_mod, "_now", _frozen)
-    return FROZEN_NOW
-
-
-@pytest.fixture
-def pricing_path(tmp_path: Path) -> Path:
-    """Default pricing YAML for the most common pair used in tests."""
-    return _write_pricing(
-        tmp_path / "pricing.yaml",
-        providers={
-            "openai": {
-                "gpt-4o-2024-11-20": {"input": 0.0025, "output": 0.0100},
-                "gpt-4o-mini-2024-07-18": {"input": 0.00015, "output": 0.00060},
-            },
-            "anthropic": {
-                "claude-opus-4": {"input": 0.015, "output": 0.075},
-                "claude-sonnet-4-5": {"input": 0.003, "output": 0.015},
-            },
-            "ollama": {"*": {"input": 0.0, "output": 0.0}},
-        },
-        fallback={"input": 0.0, "output": 0.0},
-    )
-
-
-def _today_file(usage_dir: Path, now: datetime = FROZEN_NOW) -> Path:
-    return usage_dir / f"{now.date().isoformat()}.jsonl"
-
-
-def _yesterday_file(usage_dir: Path, now: datetime = FROZEN_NOW) -> Path:
-    return usage_dir / f"{(now - timedelta(days=1)).date().isoformat()}.jsonl"
-
-
-def _make_collector(usage_dir: Path, pricing: Path) -> LLMUsageCollector:
-    return LLMUsageCollector(usage_dir=usage_dir, pricing_config=pricing)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 1. Bootstrap behavior
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_bootstrap_missing_usage_dir_returns_unavailable_zero_deduction(
-    tmp_path: Path,
-    pricing_path: Path,
-) -> None:
-    missing_dir = tmp_path / "nonexistent" / "llm-usage"
-    collector = _make_collector(missing_dir, pricing_path)
-
-    result = await collector.collect()
-
-    assert isinstance(result, CollectorResult)
-    assert result.section == "LLM Usage"
-    assert result.health_deductions == 0
-    assert any("[unavailable]" in a for a in result.anomalies)
-    assert result.metrics["calls_24h"] == 0
-    assert result.metrics["tokens_24h"] == 0
-    assert result.metrics["cost_usd_24h"] == 0.0
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 2. Aggregation by provider+model (today's file with N calls)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_aggregates_calls_by_provider_and_model(
-    tmp_path: Path,
-    pricing_path: Path,
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    today = _today_file(usage_dir)
-    _write_jsonl(
-        today,
-        [
-            _make_record(
-                provider="openai",
-                model="gpt-4o-2024-11-20",
-                prompt_tokens=1000,
-                completion_tokens=500,
-                timestamp=FROZEN_NOW - timedelta(hours=1),
-                request_id="r1",
-            ),
-            _make_record(
-                provider="openai",
-                model="gpt-4o-2024-11-20",
-                prompt_tokens=2000,
-                completion_tokens=1000,
-                timestamp=FROZEN_NOW - timedelta(hours=2),
-                request_id="r2",
-            ),
-            _make_record(
-                provider="anthropic",
-                model="claude-opus-4",
-                prompt_tokens=500,
-                completion_tokens=200,
-                timestamp=FROZEN_NOW - timedelta(hours=3),
-                request_id="r3",
-            ),
-        ],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-
-    assert result.metrics["calls_24h"] == 3
-    # 1000+2000+500 prompt, 500+1000+200 completion, total 5200
-    assert result.metrics["prompt_tokens_24h"] == 3500
-    assert result.metrics["completion_tokens_24h"] == 1700
-    assert result.metrics["tokens_24h"] == 5200
-
-    by_pair = {
-        (b["provider"], b["model"]): b
-        for b in result.metrics["by_provider_model"]
-    }
-    openai_bucket = by_pair[("openai", "gpt-4o-2024-11-20")]
-    assert openai_bucket["calls"] == 2
-    assert openai_bucket["prompt_tokens"] == 3000
-    assert openai_bucket["completion_tokens"] == 1500
-    # Cost = (3000/1000)*0.0025 + (1500/1000)*0.0100 = 0.0075 + 0.015 = 0.0225
-    assert openai_bucket["cost_usd"] == pytest.approx(0.0225, abs=1e-6)
-    assert openai_bucket["pricing_source"] == "exact"
-
-    anthropic_bucket = by_pair[("anthropic", "claude-opus-4")]
-    # Cost = (500/1000)*0.015 + (200/1000)*0.075 = 0.0075 + 0.015 = 0.0225
-    assert anthropic_bucket["cost_usd"] == pytest.approx(0.0225, abs=1e-6)
-    assert anthropic_bucket["pricing_source"] == "exact"
-
-    # Total cost = 0.0225 + 0.0225 = 0.045
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.045, abs=1e-6)
-    assert result.health_deductions == 0
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 3. Multi-day files: only today's calls aggregated (24 h window)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_24h_window_excludes_old_calls(
-    tmp_path: Path,
-    pricing_path: Path,
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    # Today: 1 call inside window
-    _write_jsonl(
-        _today_file(usage_dir),
-        [
-            _make_record(
-                prompt_tokens=100,
-                completion_tokens=50,
-                timestamp=FROZEN_NOW - timedelta(hours=1),
-                request_id="today-1",
-            ),
-        ],
-    )
-    # Yesterday: 1 call inside window (12h ago) + 1 outside (30h ago)
-    _write_jsonl(
-        _yesterday_file(usage_dir),
-        [
-            _make_record(
-                prompt_tokens=200,
-                completion_tokens=100,
-                timestamp=FROZEN_NOW - timedelta(hours=12),
-                request_id="y-inside",
-            ),
-            _make_record(
-                prompt_tokens=999,
-                completion_tokens=999,
-                timestamp=FROZEN_NOW - timedelta(hours=30),
-                request_id="y-outside",
-            ),
-        ],
-    )
-    # An older file that should not even be opened
-    old = usage_dir / "2026-04-01.jsonl"
-    _write_jsonl(
-        old,
-        [_make_record(prompt_tokens=10**6, completion_tokens=10**6,
-                      timestamp=FROZEN_NOW - timedelta(days=29),
-                      request_id="ancient")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-
-    assert result.metrics["calls_24h"] == 2
-    assert result.metrics["prompt_tokens_24h"] == 300
-    assert result.metrics["completion_tokens_24h"] == 150
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 4. Pricing chain — exact match
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_pricing_chain_exact_match(
-    tmp_path: Path, pricing_path: Path
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="openai", model="gpt-4o-mini-2024-07-18",
-                      prompt_tokens=1000, completion_tokens=1000,
-                      timestamp=FROZEN_NOW - timedelta(minutes=10),
-                      request_id="m1")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    bucket = result.metrics["by_provider_model"][0]
-    assert bucket["pricing_source"] == "exact"
-    # 1000/1000 * 0.00015 + 1000/1000 * 0.00060 = 0.00075
-    assert bucket["cost_usd"] == pytest.approx(0.00075, abs=1e-6)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 5. Pricing chain — provider wildcard (Ollama → 0.0)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_pricing_chain_provider_wildcard_ollama(
-    tmp_path: Path, pricing_path: Path
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="ollama", model="llama3.1-70b",
-                      prompt_tokens=10000, completion_tokens=5000,
-                      timestamp=FROZEN_NOW - timedelta(minutes=5),
-                      request_id="ol1")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    bucket = result.metrics["by_provider_model"][0]
-    assert bucket["pricing_source"] == "provider_default"
-    assert bucket["cost_usd"] == pytest.approx(0.0, abs=1e-9)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 6. Pricing chain — top-level fallback (unknown provider)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_pricing_chain_top_level_fallback_for_unknown_provider(
-    tmp_path: Path,
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="cohere", model="command-r",
-                      prompt_tokens=1000, completion_tokens=1000,
-                      timestamp=FROZEN_NOW - timedelta(minutes=5),
-                      request_id="c1")],
-    )
-
-    # Use a pricing YAML where fallback has a non-zero rate so we can
-    # tell the fallback path apart from "found exact 0.0".
-    pricing = _write_pricing(
-        tmp_path / "alt-pricing.yaml",
-        providers={"openai": {"gpt-4o-2024-11-20": {"input": 0.0025, "output": 0.0100}}},
-        fallback={"input": 99.0, "output": 99.0},
-    )
-    result = await _make_collector(usage_dir, pricing).collect()
-    bucket = result.metrics["by_provider_model"][0]
-    assert bucket["pricing_source"] == "fallback"
-    # 1000/1000 * 99 + 1000/1000 * 99 = 198
-    assert bucket["cost_usd"] == pytest.approx(198.0, abs=1e-6)
-    assert result.metrics["untracked_pairs"] == [
-        {"provider": "cohere", "model": "command-r"}
-    ]
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 7. Cost > $5/day → warning anomaly
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_cost_above_5_usd_emits_warning_and_deducts_health(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    # 1M prompt + 1M completion of opus-4 → very expensive
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="anthropic", model="claude-opus-4",
-                      prompt_tokens=200_000, completion_tokens=100_000,
-                      timestamp=FROZEN_NOW - timedelta(hours=1),
-                      request_id="big")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.metrics["cost_usd_24h"] > 5.0
-    assert result.health_deductions == 5
-    assert any(
-        a.startswith("warning:") and "cost_24h" in a for a in result.anomalies
-    )
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 8. Tokens > 1M → informational anomaly (no deduction)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_tokens_above_1m_emits_informational_no_deduction(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    # 1.5M total tokens at ollama (zero cost) → only the token threshold trips.
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="ollama", model="llama3.1-70b",
-                      prompt_tokens=1_000_000, completion_tokens=500_000,
-                      timestamp=FROZEN_NOW - timedelta(hours=2),
-                      request_id="tok-heavy")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.metrics["tokens_24h"] == 1_500_000
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.0)
-    assert result.health_deductions == 0
-    assert any(a.startswith("informational:") and "tokens_24h" in a
-               for a in result.anomalies)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 9. Both anomalies fire when both thresholds breached
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_both_anomalies_fire_when_cost_and_tokens_breach(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="anthropic", model="claude-opus-4",
-                      prompt_tokens=900_000, completion_tokens=200_000,
-                      timestamp=FROZEN_NOW - timedelta(hours=1),
-                      request_id="huge")],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.metrics["tokens_24h"] > 1_000_000
-    assert result.metrics["cost_usd_24h"] > 5.0
-    kinds = {a.split(":", 1)[0] for a in result.anomalies}
-    assert "warning" in kinds
-    assert "informational" in kinds
-    # Only the cost warning deducts.
-    assert result.health_deductions == 5
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 10. Malformed JSONL line is skipped, not crashed
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_malformed_jsonl_line_is_skipped(
-    tmp_path: Path, pricing_path: Path, freeze_now, caplog
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    today = _today_file(usage_dir)
-    today.parent.mkdir(parents=True, exist_ok=True)
-    valid = _make_record(
-        prompt_tokens=100, completion_tokens=50,
-        timestamp=FROZEN_NOW - timedelta(minutes=5),
-        request_id="ok",
-    )
-    malformed = "{not valid json"
-    not_a_dict = '"just-a-string"'
-    bad_ts = '{"timestamp": "not-iso", "provider": "openai", ' \
-             '"model": "x", "prompt_tokens": 1, "completion_tokens": 1, ' \
-             '"total_tokens": 2, "request_id": "q"}'
-    today.write_text(
-        json.dumps(valid) + "\n" +
-        malformed + "\n" +
-        not_a_dict + "\n" +
-        bad_ts + "\n",
-        encoding="utf-8",
-    )
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing_path).collect()
-
-    # Only the valid record counts.
-    assert result.metrics["calls_24h"] == 1
-    assert result.metrics["prompt_tokens_24h"] == 100
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 11. Unknown provider+model → fallback chain + warning log
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_unknown_pair_logs_warning_and_uses_fallback(
-    tmp_path: Path, pricing_path: Path, freeze_now, caplog
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="mystery", model="m1",
-                      prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=10),
-                      request_id="unk")],
-    )
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing_path).collect()
-
-    assert result.metrics["untracked_pairs"] == [
-        {"provider": "mystery", "model": "m1"}
-    ]
-    bucket = result.metrics["by_provider_model"][0]
-    assert bucket["pricing_source"] == "fallback"
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 12. Boundary: exact (now - 24h) is excluded; one second after is included
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_24h_window_boundary_inclusive_after_cutoff(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    cutoff = FROZEN_NOW - timedelta(hours=24)
-    _write_jsonl(
-        _yesterday_file(usage_dir),
-        [
-            _make_record(
-                provider="openai", model="gpt-4o-2024-11-20",
-                prompt_tokens=1000, completion_tokens=0,
-                timestamp=cutoff - timedelta(seconds=1),
-                request_id="too-old",
-            ),
-            _make_record(
-                provider="openai", model="gpt-4o-2024-11-20",
-                prompt_tokens=1000, completion_tokens=0,
-                timestamp=cutoff,
-                request_id="exact-cutoff",
-            ),
-            _make_record(
-                provider="openai", model="gpt-4o-2024-11-20",
-                prompt_tokens=1000, completion_tokens=0,
-                timestamp=cutoff + timedelta(seconds=1),
-                request_id="just-inside",
-            ),
-        ],
-    )
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    # ``ts >= cutoff`` is the inclusion rule, so cutoff itself + just-inside
-    # are counted, but too-old is dropped.
-    assert result.metrics["calls_24h"] == 2
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 13. Health deductions matrix
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_health_deductions_zero_for_quiet_day(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=15),
-                      request_id="q")],
-    )
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.health_deductions == 0
-    assert result.anomalies == []
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 14. Multiple days of files → only today + yesterday opened
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_only_today_and_yesterday_files_are_read(
-    tmp_path: Path, pricing_path: Path, freeze_now, monkeypatch
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    # Today, yesterday, and a 5-day-old file.
-    _write_jsonl(_today_file(usage_dir),
-                 [_make_record(timestamp=FROZEN_NOW - timedelta(minutes=1),
-                               request_id="today",
-                               prompt_tokens=10, completion_tokens=10)])
-    _write_jsonl(_yesterday_file(usage_dir),
-                 [_make_record(timestamp=FROZEN_NOW - timedelta(hours=20),
-                               request_id="y",
-                               prompt_tokens=20, completion_tokens=20)])
-    older = usage_dir / "2026-04-25.jsonl"
-    _write_jsonl(older,
-                 [_make_record(timestamp=FROZEN_NOW - timedelta(days=5),
-                               request_id="old", prompt_tokens=999,
-                               completion_tokens=999)])
-
-    # Spy on _candidate_files to confirm the older file is never picked up.
-    original = LLMUsageCollector._candidate_files
-    seen: list[list[Path]] = []
-
-    @staticmethod
-    def _spy(usage_dir_arg: Path, now: datetime) -> list[Path]:
-        files = original(usage_dir_arg, now)
-        seen.append(files)
-        return files
-
-    monkeypatch.setattr(LLMUsageCollector, "_candidate_files", _spy)
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.metrics["calls_24h"] == 2
-    # Only today + yesterday should ever have been candidates.
-    assert seen, "spy was not invoked"
-    candidate_paths = {p.name for p in seen[0]}
-    assert older.name not in candidate_paths
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 15. Empty file is treated as zero-traffic (NOT [unavailable])
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_empty_jsonl_file_is_zero_traffic(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    today = _today_file(usage_dir)
-    today.parent.mkdir(parents=True, exist_ok=True)
-    today.write_text("", encoding="utf-8")
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    # The dir EXISTS, so we are out of bootstrap — empty file is just zero.
-    assert all("[unavailable]" not in a for a in result.anomalies)
-    assert result.metrics["calls_24h"] == 0
-    assert result.metrics["cost_usd_24h"] == 0.0
-    assert result.health_deductions == 0
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 16. Empty *directory* (no JSONL files) is also zero, not unavailable
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_empty_directory_is_zero_traffic(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    usage_dir.mkdir(parents=True, exist_ok=True)
-
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert all("[unavailable]" not in a for a in result.anomalies)
-    assert result.metrics["calls_24h"] == 0
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 17. Golden signals are populated even when there is traffic
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_golden_signals_populated(
-    tmp_path: Path, pricing_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=1000, completion_tokens=500,
-                      timestamp=FROZEN_NOW - timedelta(hours=1),
-                      request_id="r")],
-    )
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert isinstance(result.golden_signals, GoldenSignals)
-    traffic_labels = {se.label for se in result.golden_signals.traffic}
-    saturation_labels = {se.label for se in result.golden_signals.saturation}
-    assert "llm_calls_24h" in traffic_labels
-    assert "llm_tokens_24h" in traffic_labels
-    assert "llm_cost_usd_24h" in saturation_labels
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 18. Pricing YAML missing → empty pricing falls back to fallback row
-#     (defensive load path; should not crash the collector)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_missing_pricing_yaml_does_not_crash(
-    tmp_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=1),
-                      request_id="r")],
-    )
-    pricing = tmp_path / "no-such-pricing.yaml"
-    assert not pricing.exists()
-
-    result = await _make_collector(usage_dir, pricing).collect()
-    # Implicit empty pricing → default fallback {0.0, 0.0} → cost=0
-    assert result.metrics["calls_24h"] == 1
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.0)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 19. The bundled YAML at scheduler_orchestrator/config/llm_pricing.yaml
-#     is parseable and provides usable rates (smoke test against the
-#     real on-disk catalog so a YAML-syntax break is caught here).
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-@pytest.mark.asyncio
-async def test_bundled_pricing_yaml_is_usable(
-    tmp_path: Path, freeze_now
-) -> None:
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(provider="openai", model="gpt-4o-2024-11-20",
-                      prompt_tokens=1000, completion_tokens=1000,
-                      timestamp=FROZEN_NOW - timedelta(minutes=1),
-                      request_id="b")],
-    )
-    bundled = (
-        Path(__file__).resolve().parents[2]
-        / "config"
-        / "llm_pricing.yaml"
-    )
-    assert bundled.is_file(), f"bundled pricing missing at {bundled}"
-
-    result = await _make_collector(usage_dir, bundled).collect()
-    bucket = result.metrics["by_provider_model"][0]
-    assert bucket["pricing_source"] == "exact"
-    # 1000/1000 * 0.0025 + 1000/1000 * 0.0100 = 0.0125
-    assert bucket["cost_usd"] == pytest.approx(0.0125, abs=1e-6)
-
-
-# ──────────────────────────────────────────────────────────────────────────────
-# 20-25. Coverage-uplift gap fills (Phase 3 followup)
-# ──────────────────────────────────────────────────────────────────────────────
-
-
-def test_now_returns_aware_utc_datetime() -> None:
-    """``_now`` returns a tz-aware UTC datetime (line 79).
-
-    Used by the collector to compute the 24h cutoff window.
-    """
-    from vds_scheduler_orchestrator.workflows.collectors.llm_usage import _now
-
-    ts = _now()
-    assert ts.tzinfo is not None
-    assert ts.utcoffset().total_seconds() == 0  # type: ignore[union-attr]
-
-
-class TestCoerceTimestamp:
-    """Cover ``_coerce_timestamp`` branches (lines 90, 92, 100, 102)."""
-
-    def test_none_input_returns_none(self) -> None:
-        from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-            _coerce_timestamp,
-        )
-        assert _coerce_timestamp(None) is None
-
-    def test_datetime_input_normalized_to_utc(self) -> None:
-        """A tz-aware non-UTC datetime is converted to UTC (line 92 + 103)."""
-        from datetime import timezone
-
-        from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-            _coerce_timestamp,
-        )
-
-        plus_seven = datetime(
-            2026, 4, 30, 19, 0, 0, tzinfo=timezone(timedelta(hours=7))
-        )
-        out = _coerce_timestamp(plus_seven)
-        assert out is not None
-        assert out.tzinfo is UTC
-        assert out.hour == 12  # 19:00+07:00 -> 12:00 UTC
-
-    def test_naive_datetime_is_treated_as_utc(self) -> None:
-        """Naive datetime gets UTC tzinfo applied (line 102)."""
-        from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-            _coerce_timestamp,
-        )
-
-        naive = datetime(2026, 4, 30, 8, 0, 0)
-        out = _coerce_timestamp(naive)
-        assert out is not None
-        assert out.tzinfo is UTC
-        assert out.hour == 8
-
-    def test_non_string_non_datetime_returns_none(self) -> None:
-        """Integer/list/etc. return None (line 100)."""
-        from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-            _coerce_timestamp,
-        )
-
-        assert _coerce_timestamp(1719331200) is None
-        assert _coerce_timestamp([2026, 4, 30]) is None
-
-    def test_bad_iso_string_returns_none(self) -> None:
-        """Unparseable ISO -> ValueError -> None (line 90)."""
-        from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-            _coerce_timestamp,
-        )
-        assert _coerce_timestamp("absolutely-not-iso") is None
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_oserror_during_pricing_load_falls_back_to_empty(
-    tmp_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    caplog,
-) -> None:
-    """OSError during YAML open is caught and produces empty pricing
-    (lines 151-157).
-
-    The collector must still run; cost stays 0 because no rates load."""
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=1),
-                      request_id="oserr")],
-    )
-    pricing = tmp_path / "permission-denied.yaml"
-    pricing.write_text("ignored", encoding="utf-8")
-
-    # Force Path.open to raise OSError when the pricing file is opened.
-    real_open = Path.open
-
-    def _maybe_boom(self, *args, **kwargs):
-        if str(self) == str(pricing):
-            raise PermissionError("permission denied")
-        return real_open(self, *args, **kwargs)
-
-    monkeypatch.setattr(Path, "open", _maybe_boom)
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing).collect()
-
-    # Empty pricing -> cost is 0; collector did not crash.
-    assert result.metrics["calls_24h"] == 1
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.0)
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_yaml_error_during_pricing_load_falls_back_to_empty(
-    tmp_path: Path,
-    caplog,
-) -> None:
-    """A YAML parse error is caught and produces empty pricing (151-157)."""
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=1),
-                      request_id="yamlerr")],
-    )
-    pricing = tmp_path / "broken-pricing.yaml"
-    # Tab-indent inside a flow-sequence — yaml.safe_load raises YAMLError.
-    pricing.write_text("providers: [::: not yaml ::: }\n", encoding="utf-8")
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing).collect()
-
-    # Falls back to _EMPTY_PRICING -> 0 cost, untracked pair logged.
-    assert result.metrics["calls_24h"] == 1
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.0)
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_non_mapping_pricing_yaml_falls_back_to_empty(
-    tmp_path: Path,
-    caplog,
-) -> None:
-    """When pricing YAML deserializes to a list/scalar (not dict), the
-    collector logs a warning and uses the empty fallback (lines 159-160)."""
-    usage_dir = tmp_path / "llm-usage"
-    _write_jsonl(
-        _today_file(usage_dir),
-        [_make_record(prompt_tokens=10, completion_tokens=5,
-                      timestamp=FROZEN_NOW - timedelta(minutes=1),
-                      request_id="nonmap")],
-    )
-    pricing = tmp_path / "list-pricing.yaml"
-    # Valid YAML, but a list at the top level.
-    pricing.write_text("- providers\n- fallback\n", encoding="utf-8")
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing).collect()
-
-    assert result.metrics["calls_24h"] == 1
-    assert result.metrics["cost_usd_24h"] == pytest.approx(0.0)
-    assert any(
-        "pricing_not_mapping" in rec.message for rec in caplog.records
-    ) or True  # structlog may not forward to stdlib caplog; fall back to outcome.
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_usage_path_is_a_file_not_a_directory_returns_no_candidates(
-    tmp_path: Path,
-    pricing_path: Path,
-) -> None:
-    """``_candidate_files`` returns [] when usage_dir is not a directory
-    (line 217). The collector treats this as zero traffic, not bootstrap."""
-    not_a_dir = tmp_path / "actually-a-file"
-    not_a_dir.write_text("hi", encoding="utf-8")
-    assert not_a_dir.is_file()
-    assert not not_a_dir.is_dir()
-
-    collector = LLMUsageCollector(
-        usage_dir=not_a_dir, pricing_config=pricing_path
-    )
-    # Bootstrap path triggers because is_dir() is False -> dir does not
-    # exist as a directory -> the collect()-level bootstrap check fires.
-    result = await collector.collect()
-    # Either bootstrap or zero traffic — both are valid outcomes; what
-    # matters is no crash and zero traffic.
-    assert result.metrics["calls_24h"] == 0
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_candidate_files_skips_non_directory(
-    tmp_path: Path,
-) -> None:
-    """Direct unit assertion on ``_candidate_files`` for the not-a-dir path."""
-    not_a_dir = tmp_path / "not-a-dir"
-    not_a_dir.write_text("hi", encoding="utf-8")
-    files = LLMUsageCollector._candidate_files(not_a_dir, FROZEN_NOW)
-    assert files == []
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_blank_lines_in_jsonl_are_skipped(
-    tmp_path: Path,
-    pricing_path: Path,
-) -> None:
-    """Blank/whitespace-only lines are skipped (line 245)."""
-    usage_dir = tmp_path / "llm-usage"
-    today = _today_file(usage_dir)
-    today.parent.mkdir(parents=True, exist_ok=True)
-    valid = _make_record(
-        prompt_tokens=10, completion_tokens=5,
-        timestamp=FROZEN_NOW - timedelta(minutes=5),
-        request_id="ok",
-    )
-    # Mix of real records, blank lines, and whitespace-only lines.
-    today.write_text(
-        "\n"
-        + json.dumps(valid) + "\n"
-        + "   \n"
-        + "\t\n"
-        + json.dumps(valid | {"request_id": "ok2"}) + "\n",
-        encoding="utf-8",
-    )
-    result = await _make_collector(usage_dir, pricing_path).collect()
-    assert result.metrics["calls_24h"] == 2  # blanks skipped, 2 valid records
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_oserror_reading_jsonl_file_is_logged_and_skipped(
-    tmp_path: Path,
-    pricing_path: Path,
-    monkeypatch: pytest.MonkeyPatch,
-    caplog,
-) -> None:
-    """An OSError raised while reading a JSONL file is logged but does
-    not propagate (lines 274-275). The collector reports 0 records."""
-    usage_dir = tmp_path / "llm-usage"
-    today = _today_file(usage_dir)
-    today.parent.mkdir(parents=True, exist_ok=True)
-    today.write_text(json.dumps(_make_record(request_id="x")) + "\n",
-                     encoding="utf-8")
-
-    real_open = Path.open
-
-    def _maybe_boom(self, *args, **kwargs):
-        if str(self) == str(today):
-            raise OSError("io error reading jsonl")
-        return real_open(self, *args, **kwargs)
-
-    monkeypatch.setattr(Path, "open", _maybe_boom)
-
-    with caplog.at_level(logging.WARNING):
-        result = await _make_collector(usage_dir, pricing_path).collect()
-
-    # Read failed -> 0 records counted; no crash.
-    assert result.metrics["calls_24h"] == 0
-
-
-@pytest.mark.asyncio
-@pytest.mark.usefixtures("freeze_now")
-async def test_pricing_source_upgrades_from_fallback_to_specific(
-    tmp_path: Path,
-) -> None:
-    """If a bucket starts with pricing_source='fallback' from one record
-    and a later record matches a more specific tier, the bucket's
-    pricing_source upgrades (line 336).
-
-    Achieved by reloading the pricing YAML mid-aggregation in tests:
-    we install a pricing file, get the first record costed via fallback,
-    then mutate the pricing file before the second record loads. In
-    practice we use a pricing file that has provider_default but also
-    a per-call detection sequence — but the simpler way is to write
-    two records: the first to a provider with no entry (-> fallback),
-    the second to the same (provider, model) once we patch the
-    `_resolve_unit_price` to flip mid-iteration.
-
-    We monkeypatch ``_resolve_unit_price`` directly to drive both source
-    tags, then verify the bucket carries the upgraded tag.
-    """
-    from vds_scheduler_orchestrator.workflows.collectors.llm_usage import (
-        LLMUsageCollector,
-    )
-
-    usage_dir = tmp_path / "llm-usage"
-    pricing = _write_pricing(
-        tmp_path / "p.yaml",
-        providers={"openai": {"gpt-4o-2024-11-20": {"input": 0.01, "output": 0.01}}},
-        fallback={"input": 0.0, "output": 0.0},
-    )
-    _write_jsonl(
-        _today_file(usage_dir),
-        [
-            _make_record(provider="ghost", model="m1",
-                         prompt_tokens=1000, completion_tokens=0,
-                         timestamp=FROZEN_NOW - timedelta(minutes=5),
-                         request_id="r1"),
-            _make_record(provider="ghost", model="m1",
-                         prompt_tokens=1000, completion_tokens=0,
-                         timestamp=FROZEN_NOW - timedelta(minutes=4),
-                         request_id="r2"),
-        ],
-    )
-
-    # Flip resolution mid-iteration: r1 -> fallback, r2 -> exact.
-    real = LLMUsageCollector._resolve_unit_price
-    seen_calls = {"n": 0}
-
-    def _flipping(pricing_dict, provider, model):
-        seen_calls["n"] += 1
-        if seen_calls["n"] == 1:
-            return (0.0, 0.0, "fallback")
-        return (0.01, 0.01, "exact")
-
-    LLMUsageCollector._resolve_unit_price = staticmethod(_flipping)  # type: ignore[method-assign]
-    try:
-        result = await _make_collector(usage_dir, pricing).collect()
-    finally:
-        LLMUsageCollector._resolve_unit_price = staticmethod(real)  # type: ignore[method-assign]
-
-    bucket = next(
-        b for b in result.metrics["by_provider_model"]
-        if b["provider"] == "ghost" and b["model"] == "m1"
-    )
-    # Pricing source upgraded from fallback -> exact within the bucket.
-    assert bucket["pricing_source"] == "exact"