feat(storage): add portable session artifact gateway

tests/test_e10_integrated_perception.py

@@ -9,11 +9,18 @@ import time
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from types import SimpleNamespace
+from typing import cast
 
 import numpy as np
 import pytest
 
 import k1link.compute.integrated_perception as integrated_module
+from k1link.artifact_gateway import (
+    ArtifactGateway,
+    ArtifactManifest,
+    ArtifactMember,
+    ResolvedArtifact,
+)
 from k1link.compute.integrated_perception import (
     IntegratedPerceptionOverlayStore,
     _CuboidPresentationState,
@@ -227,6 +234,75 @@ def test_integrated_overlay_serializes_heavy_materialization_across_sessions(
     assert maximum_active == 1
 
 
+def test_integrated_overlay_uses_verified_central_cache_before_local_result_scan(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    for name in ("jobs", "results", "lidar-packs"):
+        (tmp_path / name).mkdir()
+    recording_id = "recording-1"
+    result_id = f"e10-integrated-perception-{'a' * 64}"
+    payload = b"RRF2central-overlay"
+    artifact_path = tmp_path / "artifact-cache" / "overlay.rrd"
+    artifact_path.parent.mkdir()
+    artifact_path.write_bytes(payload)
+    member = ArtifactMember(
+        role=f"integrated-overlay:{recording_id}",
+        media_type="application/vnd.rerun.rrd",
+        sha256=hashlib.sha256(payload).hexdigest(),
+        byte_length=len(payload),
+    )
+    manifest = ArtifactManifest(
+        manifest_id="b" * 64,
+        artifact_type="recorded-session",
+        subject_id="session-1",
+        created_at_utc="2026-07-30T00:00:00Z",
+        members=(member,),
+        metadata={"integrated-result-id": result_id},
+    )
+
+    class FakeGateway:
+        def resolve_role(self, namespace: str, key: str, role: str) -> ResolvedArtifact:
+            assert (namespace, key, role) == (
+                "sessions",
+                "session-1",
+                f"integrated-overlay:{recording_id}",
+            )
+            return ResolvedArtifact(
+                manifest=manifest,
+                member=member,
+                path=artifact_path,
+                cache_hit=False,
+                central_available=True,
+            )
+
+    store = IntegratedPerceptionOverlayStore(
+        jobs_root=tmp_path / "jobs",
+        results_root=tmp_path / "results",
+        lidar_packs_root=tmp_path / "lidar-packs",
+        cache_root=tmp_path / "cache",
+        ffmpeg_path=tmp_path / "ffmpeg",
+        artifact_gateway=cast(ArtifactGateway, FakeGateway()),
+    )
+    monkeypatch.setattr(
+        store,
+        "_latest_descriptor",
+        lambda _session_id: (_ for _ in ()).throw(
+            AssertionError("central cache hit must not scan local results")
+        ),
+    )
+
+    artifact = store.materialize(
+        "session-1",
+        application_id="nodedc_mission_core_recorded",
+        recording_id=recording_id,
+    )
+
+    assert artifact is not None
+    assert artifact.path == artifact_path
+    assert artifact.sha256 == member.sha256
+
+
 def test_e10_profile_pins_integrated_realtime_budget() -> None:
     _fusion, runner = _worker_modules()
     profile_path = (