feat(npu): add utilization digest tooling

tests/test_npu_utilization_digest.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "npu-utilization-digest.py"
+spec = importlib.util.spec_from_file_location("npu_utilization_digest", SCRIPT)
+assert spec and spec.loader
+digest = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = digest
+spec.loader.exec_module(digest)
+
+
+def test_positive_sysfs_delta_required_for_proof(tmp_path, monkeypatch):
+    busy = tmp_path / "busy"
+    busy.write_text("100")
+
+    def fake_health(service, url, timeout, gate="none", mode="health_only"):
+        return digest.ServiceRow(service=service, reachable=True, mode=mode, gate=gate), {"ok": True}
+
+    def fake_post(url, payload, timeout):
+        busy.write_text("100")
+        return 200, {"data": [{"embedding": [0.1, 0.2]}], "embedding_dim": 2, "npu_busy_delta_us": 7}
+
+    monkeypatch.setattr(digest, "health_row", fake_health)
+    row = digest.probe_embeddings(1, busy_path=busy, post_json=fake_post)
+    assert row.probe_ran is True
+    assert row.proof_ok is False
+    assert "no_positive_sysfs_delta" in row.warnings
+
+
+def test_embeddings_row_redacts_vectors(tmp_path):
+    row = digest.ServiceRow(
+        service="embeddings",
+        reachable=True,
+        probe_ran=True,
+        proof_ok=True,
+        calls=1,
+        items=1,
+        avg_ms=12.3,
+        npu_delta_us=5,
+        embedding_count=1,
+        embedding_dim=3,
+        mode="NPU",
+    )
+    summary = digest.build_summary([row], None, 5, "2026-06-05T14:20:00-07:00")
+    text = digest.render_text(summary, [row])
+    assert "embedding_count" not in text  # counts are intentionally terse in text
+    assert "0.1" not in text
+    out = digest.write_jsonl(summary, [row], tmp_path)
+    body = out.read_text()
+    assert "embedding" in body  # compact metadata key is okay
+    assert "[0.1" not in body
+    assert "embedding_dim" in body
+
+
+def test_classifier_dry_run_payload(tmp_path, monkeypatch):
+    busy = tmp_path / "busy"
+    busy.write_text("10")
+    seen = {}
+
+    def fake_health(service, url, timeout, gate="none", mode="health_only"):
+        return digest.ServiceRow(service=service, reachable=True, mode=mode, gate=gate), {"ok": True}
+
+    def fake_post(url, payload, timeout):
+        seen.update(payload)
+        busy.write_text("35")
+        return 200, {"labels": {"tool_needed": True, "duplicate": False}, "npu_busy_delta_us": 25}
+
+    monkeypatch.setattr(digest, "health_row", fake_health)
+    row = digest.probe_classifier(1, busy_path=busy, post_json=fake_post)
+    assert seen["options"]["dry_run"] is True
+    assert seen["options"]["include_evidence"] is False
+    assert row.escalate == 1
+    assert row.suppress == 0
+    assert row.proof_ok is True
+
+
+def test_doc_triage_allowed_root_compact(tmp_path):
+    row = digest.ServiceRow(
+        service="doc_triage",
+        reachable=True,
+        probe_ran=True,
+        proof_ok=True,
+        files=1,
+        avg_ms=9,
+        npu_delta_us=11,
+        allowed_roots_count=1,
+        mode="NPU-via-embedding-service",
+        gate="closed:private-root",
+    )
+    summary = digest.build_summary([row], None, 11, "2026-06-05T14:20:00-07:00")
+    text = digest.render_text(summary, [row])
+    assert "allowed_roots=1" in text
+    assert str(tmp_path) not in text
+
+
+def test_advisory_gateway_health_only(monkeypatch):
+    calls = []
+
+    def fake_get(url, timeout):
+        return 200, {"ok": True}
+
+    def fake_post(url, payload, timeout):
+        calls.append((url, payload))
+        return 200, {}
+
+    monkeypatch.setattr(digest, "http_get_json", fake_get)
+    monkeypatch.setattr(digest, "http_post_json", fake_post)
+    row, _ = digest.health_row("advisory_gateway", digest.ADVISORY_HEALTH_URL, 1, gate="closed:advisory-post")
+    assert row.reachable is True
+    assert row.probe_ran is False
+    assert row.mode == "health_only"
+    assert calls == []
+
+
+def test_genai_loaded_false_skips_default_smoke(monkeypatch):
+    def fake_health(service, url, timeout, gate="none", mode="health_only"):
+        return digest.ServiceRow(service=service, reachable=True, mode=mode), {"ok": True, "loaded": False}
+
+    monkeypatch.setattr(digest, "health_row", fake_health)
+    row = digest.probe_genai(1, include_smoke=False)
+    assert row.probe_ran is False
+    assert row.loaded is False
+    assert row.reason == "skipped_cold_load"
+    assert row.fallbacks == 1
+    assert "skipped_cold_load" in row.warnings
+
+
+def test_disabled_proof_smokes_count_as_fallbacks(monkeypatch):
+    def fake_health(service, url, timeout, gate="none", mode="health_only"):
+        return digest.ServiceRow(service=service, reachable=True, mode=mode, gate=gate), {"ok": True, "loaded": True}
+
+    monkeypatch.setattr(digest, "health_row", fake_health)
+    rows = [
+        digest.probe_whisper(1, include_smoke=False),
+        digest.probe_genai(1, include_smoke=False),
+        digest.probe_doc_triage(1, include_smoke=False),
+    ]
+    summary = digest.build_summary(rows, None, 0, "2026-06-05T14:20:00-07:00")
+    assert summary["fallbacks"] == 3
+    assert summary["warnings"] == {"skipped": 2, "smoke_disabled": 1}
+
+
+def test_jsonl_shape(tmp_path):
+    rows = [digest.ServiceRow(service="embeddings", reachable=True, probe_ran=True, proof_ok=True, npu_delta_us=1)]
+    summary = digest.build_summary(rows, None, 1, "2026-06-05T14:20:00-07:00")
+    path = digest.write_jsonl(summary, rows, tmp_path)
+    lines = [json.loads(line) for line in path.read_text().splitlines()]
+    assert lines[0]["type"] == "summary"
+    assert lines[1]["type"] == "service"
+    assert lines[1]["service"] == "embeddings"
+
+
+def test_exit_codes(monkeypatch):
+    rows = [digest.ServiceRow(service="embeddings", reachable=True, probe_ran=True, proof_ok=False, warnings=["no_positive_sysfs_delta"])]
+    summary = digest.build_summary(rows, None, 0, "2026-06-05T14:20:00-07:00")
+    monkeypatch.setattr(digest, "run", lambda args: (summary, rows))
+    assert digest.main(["--no-write"]) == 0
+    assert digest.main(["--no-write", "--strict-proof"]) == 2