feat(lab): seal M4.8R3 occupancy shadows

tests/test_m48r3_static_occupancy_api.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from k1link.laboratory.m48r3_static_occupancy_shadow import (
+    M48R3StaticOccupancyShadowResult,
+)
+from k1link.web import m48r3_static_occupancy_api as api
+
+
+def test_m48r3_api_projects_result_cases_and_provenance_timeline(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    result_id = "m48r3-static-occupancy-shadow-" + "0" * 64
+    root = tmp_path / "results"
+    result_root = root / result_id
+    result_root.mkdir(parents=True)
+    for name in (
+        "manifest.json",
+        "report.json",
+        "cases.jsonl",
+        "worker-result.json",
+        "frames.jsonl",
+        "frame-diff.jsonl",
+    ):
+        (result_root / name).write_text("{}\n", encoding="utf-8")
+    sealed = M48R3StaticOccupancyShadowResult(
+        result_id=result_id,
+        result_root=result_root,
+        manifest={"created_at_utc": "2026-08-26T00:00:00Z", "accepted": True},
+        report={
+            "profile": {"id": "profile"},
+            "metrics": {"frames": {"candidate_delivered": 4489}},
+            "gates": {"complete_frame_accounting": True},
+            "decision": {"state": "accepted-bounded-worker-shadow"},
+            "limitations": ["replay only"],
+            "authority": {"mode": "replay-simulated"},
+        },
+        cases=({"anchor_id": "anchor", "source_sequence": 1855},),
+    )
+
+    class Timeline:
+        source_times_ns = tuple(range(4489))
+        profile = SimpleNamespace(session_id="20260720T065719Z_viewer_live")
+
+        def metadata(self) -> dict[str, object]:
+            return {
+                "schema_version": "missioncore.recorded-spatial-evidence-timeline/v1",
+                "result_id": result_id,
+                "occupancy_provenance_delivery": (
+                    "baseline-versus-additive-component-diff"
+                ),
+            }
+
+        def chunk_json(self, *, start_sequence: int, frame_count: int) -> bytes:
+            return json.dumps(
+                {"start_sequence": start_sequence, "frame_count": frame_count}
+            ).encode()
+
+        def camera_point_overlay_json(self, *, sequence: int) -> bytes:
+            return json.dumps({"sequence": sequence}).encode()
+
+    monkeypatch.setattr(api, "_read_result_cached", lambda *_args: sealed)
+    monkeypatch.setattr(api, "_read_timeline_cached", lambda *_args: Timeline())
+    app = FastAPI()
+    app.include_router(
+        api.build_m48r3_static_occupancy_router(
+            root_provider=lambda: root,
+            repository_root_provider=lambda: tmp_path,
+        )
+    )
+    client = TestClient(app)
+
+    catalog = client.get("/api/v1/laboratory/m48r3/static-occupancy/results")
+    assert catalog.status_code == 200
+    assert catalog.json()["items"][0]["result_id"] == result_id
+    result = client.get(f"/api/v1/laboratory/m48r3/static-occupancy/{result_id}")
+    assert result.status_code == 200
+    assert result.json()["accepted"] is True
+    cases = client.get(f"/api/v1/laboratory/m48r3/static-occupancy/{result_id}/cases")
+    assert cases.status_code == 200
+    assert cases.json()["cases"][0]["source_sequence"] == 1855
+    timeline = client.get(
+        f"/api/v1/laboratory/m48r3/static-occupancy/{result_id}/timeline"
+    )
+    assert timeline.status_code == 200
+    assert timeline.json()["occupancy_provenance_delivery"] == (
+        "baseline-versus-additive-component-diff"
+    )
+    chunk = client.get(
+        f"/api/v1/laboratory/m48r3/static-occupancy/{result_id}/timeline/chunk",
+        params={"start": 1855, "count": 1},
+    )
+    assert chunk.status_code == 200
+    assert chunk.json() == {"start_sequence": 1855, "frame_count": 1}
+    assert (
+        client.get("/api/v1/laboratory/m48r3/static-occupancy/not-a-result").status_code
+        == 404
+    )

tests/test_m48r3_static_occupancy_shadow.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from k1link.laboratory.m48r3_static_occupancy_shadow import (
+    FRAME_EVIDENCE_SCHEMA,
+    compare_m48r3_frame_ledgers,
+)
+
+
+def _component(component_id: str, cells: list[tuple[int, int, int]]) -> dict[str, object]:
+    return {
+        "component_id": component_id,
+        "cells": [{"x": x, "y": y, "z": z} for x, y, z in cells],
+    }
+
+
+def _row(
+    sequence: int,
+    occupied: list[dict[str, object]],
+    *,
+    unknown: list[dict[str, object]] | None = None,
+) -> dict[str, object]:
+    return {
+        "schema_version": FRAME_EVIDENCE_SCHEMA,
+        "source_envelope": {"sequence": sequence},
+        "delivery": {
+            "obstacle_map": {
+                "occupied": occupied,
+                "unknown": unknown or [],
+                "free_space_claimed": False,
+            }
+        },
+    }
+
+
+def _write(path: Path, rows: list[dict[str, object]]) -> None:
+    path.write_text(
+        "".join(
+            json.dumps(row, sort_keys=True, separators=(",", ":")) + "\n"
+            for row in rows
+        ),
+        "utf-8",
+    )
+
+
+def test_streaming_diff_preserves_gaps_and_marks_additive_components(tmp_path: Path) -> None:
+    baseline = tmp_path / "baseline.jsonl"
+    candidate = tmp_path / "candidate.jsonl"
+    _write(
+        baseline,
+        [
+            _row(0, [_component("base-0", [(0, 0, 0)])]),
+            _row(1, [_component("base-1", [(10, 0, 0)])]),
+        ],
+    )
+    _write(
+        candidate,
+        [
+            _row(0, [_component("mixed-0", [(0, 0, 0), (1, 0, 0)])]),
+            _row(
+                1,
+                [_component("base-1", [(10, 0, 0)])],
+                unknown=[_component("step-1", [(20, 0, 0)])],
+            ),
+        ],
+    )
+
+    result = compare_m48r3_frame_ledgers(
+        baseline,
+        candidate,
+        selected_sequences={1},
+        expected_frames=2,
+    )
+
+    assert result.frame_count == 2
+    assert result.baseline_cell_total == 2
+    assert result.candidate_cell_total == 4
+    assert result.added_cell_total == 2
+    assert result.lost_cell_total == 0
+    assert result.mean_cell_growth_fraction == 1.0
+    assert result.mean_component_growth_fraction == 0.5
+    assert result.diff_rows[0]["component_provenance"] == {"mixed-0": "mixed"}
+    assert result.diff_rows[1]["component_provenance"] == {
+        "step-1": "additive-low-step"
+    }
+    assert result.diff_rows[0]["added_cells"] == [[1, 0, 0]]
+    assert set(result.selected_candidate_rows) == {1}
+