feat(perception): add diagnostic semantic SLAM replay

This commit is contained in:
DCCONSTRUCTIONS
2026-08-06 11:26:37 +03:00
parent b7a51e26e6
commit 8eaa3ab497
15 changed files with 4554 additions and 6 deletions
+272
View File
@@ -0,0 +1,272 @@
from __future__ import annotations
import hashlib
import json
import zipfile
from pathlib import Path
import numpy as np
import pytest
from fastapi import HTTPException
from fastapi.routing import APIRoute
from k1link.perception.semantic_slam_replay import (
PUBLICATION_STATUS,
SemanticSlamReplayResult,
)
from k1link.web import e47_semantic_slam_api as api
RESULT_ID = f"e47-semantic-slam-{'a' * 64}"
M4_RESULT_ID = f"m4-threat-replay-{'b' * 64}"
PNG_0 = b"\x89PNG\r\n\x1a\nsealed-mask-zero"
PNG_1 = b"\x89PNG\r\n\x1a\nsealed-mask-one"
def _endpoint(path: str, root: Path):
router = api.build_e47_semantic_slam_router(root_provider=lambda: root)
return next(
route.endpoint
for route in router.routes
if isinstance(route, APIRoute) and route.path == path
)
@pytest.fixture(autouse=True)
def _clear_api_caches() -> None:
api._read_semantic_result_cached.cache_clear()
api._read_point_ledger_cached.cache_clear()
yield
api._read_semantic_result_cached.cache_clear()
api._read_point_ledger_cached.cache_clear()
@pytest.fixture
def publication(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Path, Path]:
root = tmp_path / "semantic-slam-results"
result_root = root / RESULT_ID
result_root.mkdir(parents=True)
taxonomy = {
"schema_version": "missioncore.e47-semantic-taxonomy/v1",
"classes": [
{
"class_id": 0,
"label": "ambiguous",
"disposition": "ambiguous",
"color_rgb": [0, 0, 0],
},
{
"class_id": 1,
"label": "road",
"disposition": "labeled",
"color_rgb": [128, 64, 128],
},
],
}
taxonomy_payload = json.dumps(taxonomy, separators=(",", ":")).encode()
(result_root / "taxonomy.json").write_bytes(taxonomy_payload)
np.savez(
result_root / "semantic-points.npz",
frame_offsets=np.asarray([0, 4, 7], dtype=np.int64),
point_labels=np.asarray([1, 0, 0, 0, 0, 1, 1], dtype=np.uint8),
point_status_codes=np.asarray([3, 2, 1, 0, 2, 3, 3], dtype=np.uint8),
frame_source_point_counts=np.asarray([4, 3], dtype=np.int32),
frame_labeled_point_counts=np.asarray([1, 2], dtype=np.int32),
frame_ambiguous_point_counts=np.asarray([1, 1], dtype=np.int32),
frame_unprojected_point_counts=np.asarray([1, 0], dtype=np.int32),
frame_absent_point_counts=np.asarray([1, 0], dtype=np.int32),
)
with zipfile.ZipFile(result_root / "semantic-masks.zip", mode="w") as archive:
archive.writestr("semantic-masks/frame-000001.png", PNG_0)
archive.writestr("semantic-masks/frame-000002.png", PNG_1)
for name, payload in (
("manifest.json", b"fixture-manifest"),
("report.json", b"fixture-report"),
("semantic-observations.jsonl", b"fixture-observations\n"),
):
(result_root / name).write_bytes(payload)
metrics = {
"frames": {"total": 2, "mask_available": 2, "source_available": 2},
"points": {
"total": 7,
"projected": 5,
"labeled": 3,
"ambiguous": 2,
"unprojected": 1,
"absent": 1,
},
"observations": {
"total": 3,
"labeled": 1,
"ambiguous": 1,
"unprojected": 1,
"absent": 0,
},
"runtime": {"elapsed_ms": 10.0, "frames_per_second": 200.0},
}
identity = {
"profile_id": "ravnoves00-eomt-kb4-slam-shadow/v1",
"base_m4_result_id": M4_RESULT_ID,
"semantic_result_id": f"result-{'c' * 64}",
"geometry_result_id": f"m4-geometry-replay-{'d' * 64}",
"source_pack_id": "ravnoves00-source-pack/v1",
"calibration_content_sha256": "e" * 64,
"taxonomy_sha256": hashlib.sha256(taxonomy_payload).hexdigest(),
"semantic_provider": {
"provider_id": "eomt-cityscapes-semantic-control/v1",
"model_id": "tue-mps/eomt",
"model_revision": "f" * 40,
"model_weights_sha256": "1" * 64,
"preprocess_id": "raw-kb4-valid-fov-semantic/v1",
"role": "fixed-control-not-selected-production-provider",
},
"temporal_binding": {
"semantic_to_camera": "exact-sequence-and-session-time",
"camera_to_lidar": "accepted-e6-nearest-host-arrival-best-effort",
"clock_basis": "recorded-host-monotonic-arrival",
"maximum_lidar_camera_delta_ms": 100.0,
"maximum_pose_point_delta_ms": 100.0,
"physical_synchronization_proven": False,
},
"authority": {
"ground_truth": False,
"semantic_authority": "diagnostic-only",
"navigation_or_safety_accepted": False,
"actuation_allowed": False,
},
}
frozen = SemanticSlamReplayResult(
result_id=RESULT_ID,
result_root=result_root,
status=PUBLICATION_STATUS,
metrics=metrics,
report={
"status": PUBLICATION_STATUS,
"metrics": metrics,
"limitations": ["No independent semantic truth."],
},
manifest={
"result_id": RESULT_ID,
"created_at_utc": "2026-08-06T06:30:00.000Z",
"identity": identity,
},
)
monkeypatch.setattr(api, "_read_semantic_result_cached", lambda *_: frozen)
return root, result_root
def test_catalog_projects_exact_diagnostic_only_view(
publication: tuple[Path, Path],
) -> None:
root, _ = publication
list_results = _endpoint("/api/v1/laboratory/e47-semantic-slam/results", root)
catalog = list_results(limit=1)
assert catalog["schema_version"] == "missioncore.e47-semantic-slam-catalog/v1"
assert catalog["candidate_total"] == 1
assert catalog["invalid_total"] == 0
item = catalog["items"][0]
assert item["schema_version"] == "missioncore.e47-semantic-slam-view/v1"
assert item["result_id"] == RESULT_ID
assert item["status"] == "diagnostic-semantic-slam-shadow"
assert item["base_m4_result_id"] == M4_RESULT_ID
assert item["provider"]["provider_id"] == "eomt-cityscapes-semantic-control/v1"
assert item["temporal_binding"]["semantic_to_camera"] == (
"exact-sequence-and-session-time"
)
assert item["temporal_binding"]["physical_synchronization_proven"] is False
assert [entry["label"] for entry in item["taxonomy"]] == ["ambiguous", "road"]
assert item["acceptance"] == {
"artifact_contract_passed": True,
"frame_accounting_passed": True,
"point_accounting_passed": True,
"observation_binding_passed": True,
"temporal_binding_passed": True,
"independent_semantic_truth_passed": False,
"provider_promoted": False,
}
assert item["semantic_authority"] == "diagnostic-only"
assert item["navigation_or_safety_accepted"] is False
assert item["actuation_allowed"] is False
def test_timeline_chunk_preserves_point_index_space_and_unavailable_sentinel(
publication: tuple[Path, Path],
) -> None:
root, _ = publication
get_chunk = _endpoint(
"/api/v1/laboratory/e47-semantic-slam/results/{result_id}/timeline/chunk",
root,
)
chunk = get_chunk(RESULT_ID, start=0, count=2)
assert chunk["schema_version"] == "missioncore.e47-semantic-slam-chunk/v1"
assert chunk["frame_count"] == 2
assert chunk["next_sequence"] is None
first = chunk["frames"][0]
assert first == {
"schema_version": "missioncore.e47-semantic-slam-frame/v1",
"sequence": 0,
"source_point_count": 4,
"class_ids": [1, 0, -1, -1],
"status_codes": [3, 2, 1, 0],
"counts": {"labeled": 1, "ambiguous": 1, "unprojected": 1, "absent": 1},
}
assert chunk["frames"][1]["class_ids"] == [0, 1, 1]
def test_timeline_chunk_rejects_out_of_range_and_oversized_requests(
publication: tuple[Path, Path],
) -> None:
root, _ = publication
get_chunk = _endpoint(
"/api/v1/laboratory/e47-semantic-slam/results/{result_id}/timeline/chunk",
root,
)
with pytest.raises(HTTPException) as out_of_range:
get_chunk(RESULT_ID, start=2, count=1)
assert out_of_range.value.status_code == 404
with pytest.raises(HTTPException) as oversized:
get_chunk(RESULT_ID, start=0, count=25)
assert oversized.value.status_code == 422
def test_mask_endpoint_streams_exact_png_with_immutable_identity(
publication: tuple[Path, Path],
) -> None:
root, _ = publication
get_mask = _endpoint(
"/api/v1/laboratory/e47-semantic-slam/results/{result_id}/masks/{sequence}",
root,
)
response = get_mask(RESULT_ID, 1)
assert response.body == PNG_1
assert response.media_type == "image/png"
assert response.headers["cache-control"] == "private, max-age=31536000, immutable"
assert response.headers["etag"] == f'"{hashlib.sha256(PNG_1).hexdigest()}"'
assert response.headers["x-content-type-options"] == "nosniff"
def test_result_resolution_rejects_invalid_id_and_symlink(tmp_path: Path) -> None:
root = tmp_path / "results"
root.mkdir()
outside = tmp_path / RESULT_ID
outside.mkdir()
(root / RESULT_ID).symlink_to(outside, target_is_directory=True)
get_chunk = _endpoint(
"/api/v1/laboratory/e47-semantic-slam/results/{result_id}/timeline/chunk",
root,
)
with pytest.raises(HTTPException) as invalid:
get_chunk("../escape", start=0, count=1)
assert invalid.value.status_code == 404
with pytest.raises(HTTPException) as linked:
get_chunk(RESULT_ID, start=0, count=1)
assert linked.value.status_code == 404
+2 -1
View File
@@ -127,10 +127,11 @@ def test_product_registry_declares_every_advanced_evidence_source() -> None:
repository_root / "config" / "laboratories"
)
assert len(registry.definitions) == 32
assert len(registry.definitions) == 33
assert {item.work_id for item in registry.definitions} >= {
"e31-source-binding",
"e46j-raw-fisheye-realtime",
"e47-semantic-slam-shadow",
"l3-pointpillars-visual-audit",
"l31-pointpillars-ravnoves",
"l32-pointpillars-camera-review",
+9 -1
View File
@@ -94,8 +94,16 @@ def test_repository_registry_classifies_every_evidence_definition() -> None:
"e33-worker-shadow",
"e35-degradation-recovery",
"e46j-raw-fisheye-realtime",
"e47-semantic-slam-shadow",
}
assert all(row.lifecycle == "canonical" for row in execution.definitions)
by_work_id = {row.work_id: row for row in execution.definitions}
assert by_work_id["e47-semantic-slam-shadow"].lifecycle == "experimental"
assert by_work_id["e47-semantic-slam-shadow"].isolation == "bounded-adapter"
assert all(
row.lifecycle == "canonical"
for row in execution.definitions
if row.work_id != "e47-semantic-slam-shadow"
)
assert len(execution.definitions) + len(execution.legacy_work_ids) == len(
evidence.definitions
)
+306
View File
@@ -0,0 +1,306 @@
from __future__ import annotations
from dataclasses import replace
import numpy as np
import pytest
from k1link.perception.contracts import (
EvidenceBasis,
EvidenceCurrentness,
MetricGeometry,
ObstacleObservation,
)
from k1link.perception.geometry_math import ProjectedPointCloud
from k1link.perception.semantic_fusion import (
NO_SEMANTIC_CLASS_ID,
SemanticClassDefinition,
SemanticClassDisposition,
SemanticEvidenceAuthority,
SemanticEvidenceStatus,
SemanticFusionError,
SemanticMask,
fuse_semantic_diagnostics,
)
def _classes() -> tuple[SemanticClassDefinition, ...]:
return (
SemanticClassDefinition(1, "road"),
SemanticClassDefinition(2, "car"),
SemanticClassDefinition(
255,
"void / uncertain",
SemanticClassDisposition.AMBIGUOUS,
),
)
def _mask(*, source_id: str = "RAVNOVES00", frame_id: str = "frame-000014") -> SemanticMask:
return SemanticMask(
source_id=source_id,
frame_id=frame_id,
provider_id="semantic-provider/v1",
model_id="semantic-model/v1",
preprocess_id="raw-kb4-semantic/v1",
labels=np.asarray(
[
[1, 2, 255, 1],
[1, 1, 1, 1],
[1, 1, 1, 1],
],
dtype=np.uint8,
),
classes=_classes(),
)
def _projection() -> ProjectedPointCloud:
return ProjectedPointCloud(
pixels_xy=np.asarray(
[
[0.1, 0.1],
[1.2, 0.2],
[1.8, 0.8],
[2.1, 0.2],
[9.0, 9.0],
],
dtype=np.float64,
),
depths_m=np.asarray([2.0, 2.1, 2.2, 2.3, 2.4], dtype=np.float64),
source_indices=np.asarray([0, 1, 2, 3, 4], dtype=np.int64),
source_point_count=5,
camera_front_point_count=5,
)
def _geometry_observation(
*point_ids: int,
observation_id: str = "geometry-observation-1",
) -> ObstacleObservation:
return ObstacleObservation(
observation_id=observation_id,
occupancy_key=f"occupancy-{observation_id}",
source_id="RAVNOVES00",
frame_id="frame-000014",
evidence_time_ns=14_000_000_000,
basis=EvidenceBasis.LIDAR,
currentness=EvidenceCurrentness.CURRENT,
occupied_support=True,
source_point_ids=point_ids,
metric_geometry=MetricGeometry(
coordinate_frame="map",
centroid_xyz_m=(2.0, 0.0, 0.5),
range_m=2.0,
covariance_diagonal_m2=(0.1, 0.1, 0.1),
),
proposal_ids=(),
semantic_hint=None,
reason_codes=("qualified-lidar-points",),
)
def _camera_only_observation() -> ObstacleObservation:
return ObstacleObservation(
observation_id="camera-observation-1",
occupancy_key="occupancy-camera-observation-1",
source_id="RAVNOVES00",
frame_id="frame-000014",
evidence_time_ns=14_000_000_000,
basis=EvidenceBasis.CAMERA,
currentness=EvidenceCurrentness.CURRENT,
occupied_support=False,
source_point_ids=(),
metric_geometry=None,
proposal_ids=("proposal-1",),
semantic_hint=None,
reason_codes=("camera-only",),
)
def test_semantic_mask_is_strict_source_bound_uint8_and_immutable() -> None:
labels = np.asarray([[1, 2]], dtype=np.uint8)
semantic = SemanticMask(
source_id="RAVNOVES00",
frame_id="frame-000014",
provider_id="semantic-provider/v1",
model_id="semantic-model/v1",
preprocess_id="raw-kb4-semantic/v1",
labels=labels,
classes=_classes(),
)
labels[0, 0] = 2
assert semantic.labels.tolist() == [[1, 2]]
assert semantic.labels.flags.writeable is False
with pytest.raises(ValueError):
semantic.labels[0, 0] = 2
with pytest.raises(SemanticFusionError, match="uint8 HxW"):
replace(semantic, labels=np.asarray([[1, 2]], dtype=np.int64))
with pytest.raises(SemanticFusionError, match="undeclared"):
replace(semantic, labels=np.asarray([[1, 7]], dtype=np.uint8))
with pytest.raises(SemanticFusionError, match="unique"):
replace(
semantic,
classes=(SemanticClassDefinition(1, "road"), SemanticClassDefinition(1, "other")),
)
def test_mask_projection_keeps_absence_ambiguity_and_unprojected_separate() -> None:
result = fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(),
)
labels = result.point_labels
assert [labels.status_for(index) for index in range(5)] == [
SemanticEvidenceStatus.LABELED,
SemanticEvidenceStatus.LABELED,
SemanticEvidenceStatus.LABELED,
SemanticEvidenceStatus.AMBIGUOUS,
SemanticEvidenceStatus.UNPROJECTED,
]
assert [labels.class_id_for(index) for index in range(5)] == [1, 2, 2, 255, None]
assert [labels.label_for(index) for index in range(5)] == [
"road",
"car",
"car",
"void / uncertain",
None,
]
assert labels.class_ids.tolist() == [1, 2, 2, 255, NO_SEMANTIC_CLASS_ID]
assert labels.class_ids.flags.writeable is False
assert labels.status_codes.flags.writeable is False
assert result.authority is SemanticEvidenceAuthority.DIAGNOSTIC_ONLY
def test_observation_aggregation_is_detached_from_geometry_and_safety_authority() -> None:
observation = _geometry_observation(0, 1, 2, 4)
before = observation.to_dict()
result = fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(observation,),
)
evidence = result.observation_evidence[0]
assert observation.to_dict() == before
assert evidence.observation_id == observation.observation_id
assert evidence.occupancy_key == observation.occupancy_identity
assert evidence.status is SemanticEvidenceStatus.LABELED
assert evidence.dominant_class_id == 2
assert evidence.dominant_label == "car"
assert evidence.dominant_fraction_of_labeled == pytest.approx(2 / 3)
assert evidence.labeled_point_count == 3
assert evidence.unprojected_point_count == 1
assert evidence.semantic_coverage_fraction == pytest.approx(0.75)
assert evidence.authority is SemanticEvidenceAuthority.DIAGNOSTIC_ONLY
assert not hasattr(evidence, "occupied_support")
assert not hasattr(evidence, "motion")
assert not hasattr(evidence, "threat")
assert not hasattr(evidence, "actuation_allowed")
def test_tied_or_provider_ambiguous_labels_remain_ambiguous() -> None:
tied = _geometry_observation(0, 1, observation_id="geometry-tied")
provider_ambiguous = _geometry_observation(3, observation_id="geometry-void")
result = fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(tied, provider_ambiguous),
)
tie_evidence, void_evidence = result.observation_evidence
assert tie_evidence.status is SemanticEvidenceStatus.AMBIGUOUS
assert tie_evidence.reason_code == "semantic-label-majority-ambiguous"
assert tie_evidence.dominant_class_id is None
assert {item.label: item.point_count for item in tie_evidence.class_evidence} == {
"road": 1,
"car": 1,
}
assert void_evidence.status is SemanticEvidenceStatus.AMBIGUOUS
assert void_evidence.reason_code == "semantic-classes-ambiguous"
assert void_evidence.ambiguous_point_count == 1
assert void_evidence.class_evidence[0].disposition is SemanticClassDisposition.AMBIGUOUS
mixed = fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(_geometry_observation(1, 3, observation_id="geometry-mixed"),),
).observation_evidence[0]
assert mixed.status is SemanticEvidenceStatus.AMBIGUOUS
assert mixed.reason_code == "semantic-label-majority-ambiguous"
assert mixed.dominant_class_id is None
def test_missing_mask_and_pointless_geometry_have_distinct_outcomes() -> None:
observation = _geometry_observation(0, 1)
absent = fuse_semantic_diagnostics(
semantic_mask=None,
projected=_projection(),
observations=(observation,),
)
assert absent.mask_available is False
assert [absent.point_labels.status_for(index) for index in range(5)] == [
SemanticEvidenceStatus.ABSENT
] * 5
assert absent.observation_evidence[0].status is SemanticEvidenceStatus.ABSENT
assert absent.observation_evidence[0].absent_point_count == 2
unprojected = fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(_camera_only_observation(),),
)
evidence = unprojected.observation_evidence[0]
assert evidence.status is SemanticEvidenceStatus.UNPROJECTED
assert evidence.reason_code == "observation-has-no-source-points"
assert evidence.source_point_count == 0
def test_fusion_rejects_frame_escape_invalid_point_ids_and_duplicate_ownership() -> None:
observation = _geometry_observation(0)
with pytest.raises(SemanticFusionError, match="source frame"):
fuse_semantic_diagnostics(
semantic_mask=_mask(frame_id="frame-000015"),
projected=_projection(),
observations=(observation,),
)
with pytest.raises(SemanticFusionError, match="outside the source frame"):
fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(_geometry_observation(5),),
)
with pytest.raises(SemanticFusionError, match="duplicate observation ownership"):
fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=_projection(),
observations=(
observation,
_geometry_observation(0, observation_id="geometry-observation-2"),
),
)
with pytest.raises(SemanticFusionError, match="escaped their source frame"):
fuse_semantic_diagnostics(
semantic_mask=None,
projected=_projection(),
observations=(
observation,
replace(
_geometry_observation(1, observation_id="geometry-observation-2"),
frame_id="frame-000015",
),
),
)
def test_projection_validator_rejects_malformed_existing_contract_values() -> None:
malformed = replace(
_projection(),
source_indices=np.asarray([0, 1, 2, 3, 5], dtype=np.int64),
)
with pytest.raises(SemanticFusionError, match="outside the source frame"):
fuse_semantic_diagnostics(
semantic_mask=_mask(),
projected=malformed,
observations=(),
)
+506
View File
@@ -0,0 +1,506 @@
from __future__ import annotations
import hashlib
import io
import json
import tarfile
from dataclasses import dataclass, replace
from pathlib import Path
import numpy as np
import pytest
from PIL import Image
import k1link.perception.semantic_slam_replay as replay
from k1link.perception.contracts import (
EvidenceBasis,
EvidenceCurrentness,
MetricGeometry,
ObstacleObservation,
)
from k1link.perception.geometry import GeometryFrame, RecordedFrameTemporalBinding
from k1link.perception.geometry_math import Kb4ProjectionProfile
from k1link.perception.geometry_replay import GeometryReplayResult
from k1link.perception.semantic_fusion import (
SemanticClassDisposition,
SemanticEvidenceStatus,
)
from k1link.perception.threat_replay import ThreatReplayResult
def _canonical_json(value: object) -> bytes:
return json.dumps(
value,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
allow_nan=False,
).encode("utf-8")
def _sha256(path: Path) -> str:
return hashlib.sha256(path.read_bytes()).hexdigest()
def _write_jsonl(path: Path, rows: list[dict[str, object]]) -> None:
path.write_bytes(b"".join(_canonical_json(row) + b"\n" for row in rows))
def _png(labels: np.ndarray) -> bytes:
buffer = io.BytesIO()
Image.fromarray(labels, mode="L").save(buffer, format="PNG")
return buffer.getvalue()
@dataclass(frozen=True)
class _Store:
frame: GeometryFrame
lidar_delta_ms: float = 4.0
pose_delta_ms: float = 2.0
def frame_for_index(self, frame_index: int) -> GeometryFrame | None:
return self.frame if frame_index == 0 else None
def temporal_binding_for_index(self, frame_index: int) -> RecordedFrameTemporalBinding:
return RecordedFrameTemporalBinding(
frame_index=frame_index,
source_time_ns=(frame_index + 1) * 1_000_000_000,
source_available=frame_index == 0,
lidar_camera_delta_ms=self.lidar_delta_ms if frame_index == 0 else None,
pose_point_delta_ms=self.pose_delta_ms if frame_index == 0 else None,
)
def _observation() -> ObstacleObservation:
return ObstacleObservation(
observation_id="frame-000000:obstacle-0",
occupancy_key="frame-000000:obstacle-0",
source_id="RAVNOVES00",
frame_id="frame-000000",
evidence_time_ns=1,
basis=EvidenceBasis.FUSED,
currentness=EvidenceCurrentness.CURRENT,
occupied_support=True,
source_point_ids=(0, 1),
metric_geometry=MetricGeometry(
coordinate_frame="map",
centroid_xyz_m=(0.0, 0.0, 1.0),
range_m=1.0,
covariance_diagonal_m2=(0.0, 0.0, 0.0),
),
proposal_ids=("proposal-0",),
semantic_hint="car",
reason_codes=("current-test-support",),
)
def _fixture(tmp_path: Path) -> replay._AdmittedInputs:
source = tmp_path / "source"
source.mkdir()
profile_path = source / "profile.json"
profile_path.write_text('{"fixture":true}\n', encoding="utf-8")
authority = {
"ground_truth": False,
"physical_live": False,
"commands_enabled": False,
"actuation_allowed": False,
"navigation_or_safety_accepted": False,
"semantic_authority": "diagnostic-only",
}
fusion = {
"projection": "factory-kb4-current-increment/v1",
"point_index_space": "frame-local-source-point-id/v1",
"observation_aggregation": "dominant-labeled-majority-diagnostic/v1",
"unprojected_status": "unprojected",
"semantic_absence_means_free": False,
"semantic_can_create_obstacle": False,
"semantic_can_change_identity": False,
"semantic_can_change_metric_geometry": False,
"semantic_can_change_occupancy": False,
"semantic_can_change_motion": False,
"semantic_can_change_threat": False,
}
profile = replay._SemanticSlamProfile(
path=profile_path,
sha256=_sha256(profile_path),
profile_id="fixture-semantic-slam/v1",
source_id="RAVNOVES00",
session_id="fixture-session",
frame_count=2,
image_width=4,
image_height=4,
source_pack_id="fixture-source-pack",
source_pack_sha256="1" * 64,
calibration_sha256="2" * 64,
provider_id="fixture-semantic-provider/v1",
model_id="fixture-model",
model_revision="fixture-revision",
model_weights_sha256="3" * 64,
preprocess_id="fixture-preprocess/v1",
mask_metadata_schema_version="missioncore.panoptic-frame/v1",
mask_payload={
"media_type": "image/png",
"encoding": "uint8-class-id",
"width": 4,
"height": 4,
"sequence_binding": "sequence-0-to-frame-000001",
},
provider_role="fixed-control-not-selected-production-provider",
classes=(
replay._TaxonomyClass(
class_id=0,
label="outside_valid_fov",
disposition=SemanticClassDisposition.AMBIGUOUS,
color_rgb=(0, 0, 0),
),
replay._TaxonomyClass(
class_id=4,
label="car",
disposition=SemanticClassDisposition.LABELED,
color_rgb=(0, 0, 142),
),
),
fusion=fusion,
temporal_binding={
"semantic_to_camera": "exact-sequence-and-session-time",
"camera_to_lidar": "accepted-e6-nearest-host-arrival-best-effort",
"clock_basis": "recorded-host-monotonic-arrival",
"maximum_lidar_camera_delta_ms": 100.0,
"maximum_pose_point_delta_ms": 100.0,
"physical_synchronization_proven": False,
},
acceptance={
"full_frame_accounting_required": True,
"point_accounting_required": True,
"observation_binding_required": True,
"exact_mask_archive_required": True,
"independent_semantic_truth_required_for_provider_promotion": True,
},
authority=authority,
)
semantic_root = source / "semantic"
semantic_root.mkdir()
result_json = semantic_root / "result.json"
result_json.write_text('{"sealed":"fixture"}\n', encoding="utf-8")
masks = []
first = np.zeros((4, 4), dtype=np.uint8)
first[2, 2] = 4
masks.append(_png(first))
masks.append(_png(np.zeros((4, 4), dtype=np.uint8)))
mask_archive = semantic_root / "masks.tar.gz"
with tarfile.open(mask_archive, mode="w:gz") as archive:
directory = tarfile.TarInfo("semantic-masks")
directory.type = tarfile.DIRTYPE
archive.addfile(directory)
for sequence, payload in enumerate(masks, start=1):
member = tarfile.TarInfo(f"semantic-masks/frame-{sequence:06d}.png")
member.size = len(payload)
archive.addfile(member, io.BytesIO(payload))
semantic_frames = semantic_root / "frames.jsonl"
_write_jsonl(
semantic_frames,
[
{
"schema_version": "missioncore.panoptic-frame/v1",
"frame_index": 0,
"sequence": 1,
"session_seconds": 1.0,
"instances": [],
"semantic_classes": [
{
"id": 4,
"label": "car",
"pixels": 1,
"fraction_of_valid_fov": 0.0625,
}
],
},
{
"schema_version": "missioncore.panoptic-frame/v1",
"frame_index": 1,
"sequence": 2,
"session_seconds": 2.0,
"instances": [],
"semantic_classes": [],
},
],
)
semantic = replay._SemanticUpstream(
result_id="result-" + "4" * 64,
result_root=semantic_root,
result_manifest_sha256=_sha256(result_json),
frames_path=semantic_frames,
frames_sha256=_sha256(semantic_frames),
masks_path=mask_archive,
masks_sha256=_sha256(mask_archive),
created_at_utc="2026-08-06T00:00:00.000Z",
job_id="fixture-job",
input_sha256="5" * 64,
source_id="sensor.camera.right",
session_id="fixture-session",
calibration_sha256="2" * 64,
configuration_profile_sha256="6" * 64,
model_id="fixture-model",
model_revision="fixture-revision",
model_weights_sha256="3" * 64,
)
observation = _observation()
geometry_root = source / "geometry"
geometry_root.mkdir()
geometry_frames = geometry_root / "frames.jsonl"
_write_jsonl(
geometry_frames,
[
{
"schema_version": "missioncore.perception-geometry-replay-frame/v1",
"sequence": 0,
"frame_id": "frame-000000",
"source_available": True,
"observations": [observation.to_dict()],
},
{
"schema_version": "missioncore.perception-geometry-replay-frame/v1",
"sequence": 1,
"frame_id": "frame-000001",
"source_available": False,
"observations": [],
},
],
)
geometry_sha256 = _sha256(geometry_frames)
geometry = GeometryReplayResult(
result_id="m4-geometry-replay-" + "7" * 64,
result_root=geometry_root,
accepted=True,
metrics={"frames": {"total": 2}},
report={},
manifest={"identity": {"frames_sha256": geometry_sha256}},
)
threat_root = source / "threat"
threat_root.mkdir()
threat_frames = threat_root / "frames.jsonl"
_write_jsonl(threat_frames, [{"decision": "unchanged"}])
threat_sha256 = _sha256(threat_frames)
threat = ThreatReplayResult(
result_id="m4-threat-replay-" + "8" * 64,
result_root=threat_root,
accepted=True,
metrics={"frames": {"total": 2}},
report={},
manifest={"identity": {"frames_sha256": threat_sha256}},
)
transform = np.eye(4, dtype=np.float64)
frame = GeometryFrame(
frame_index=0,
points_map=np.asarray(((0.0, 0.0, 1.0), (100.0, 0.0, 1.0)), dtype=np.float64),
point_class=np.zeros(2, dtype=np.uint8),
sensor_position_map=np.zeros(3, dtype=np.float64),
sensor_orientation_xyzw=np.asarray((0.0, 0.0, 0.0, 1.0), dtype=np.float64),
projection=Kb4ProjectionProfile(
width=4,
height=4,
intrinsic_fx_fy_cx_cy=(2.0, 2.0, 2.0, 2.0),
distortion_kb4=(0.0, 0.0, 0.0, 0.0),
t_camera_from_lidar=transform,
),
surface_valid=True,
)
return replay._AdmittedInputs(
profile=profile,
semantic=semantic,
geometry=geometry,
threat=threat,
store=_Store(frame), # type: ignore[arg-type]
geometry_frames_path=geometry_frames,
geometry_frames_sha256=geometry_sha256,
threat_frames_path=threat_frames,
threat_frames_sha256=threat_sha256,
)
def _build(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> tuple[replay.SemanticSlamReplayResult, replay._AdmittedInputs]:
admitted = _fixture(tmp_path)
monkeypatch.setattr(replay, "_admit_inputs", lambda **_kwargs: admitted)
result = replay.build_semantic_slam_replay(
repository_root=tmp_path,
semantic_result_root=tmp_path,
threat_result_root=tmp_path,
geometry_result_root=tmp_path,
output_root=tmp_path / "output",
)
return result, admitted
def test_builder_is_idempotent_and_preserves_geometry_and_threat_ledgers(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
admitted = _fixture(tmp_path)
geometry_before = admitted.geometry_frames_path.read_bytes()
threat_before = admitted.threat_frames_path.read_bytes()
monkeypatch.setattr(replay, "_admit_inputs", lambda **_kwargs: admitted)
arguments = {
"repository_root": tmp_path,
"semantic_result_root": tmp_path,
"threat_result_root": tmp_path,
"geometry_result_root": tmp_path,
"output_root": tmp_path / "output",
}
first = replay.build_semantic_slam_replay(**arguments)
manifest_before = (first.result_root / replay.SEMANTIC_SLAM_MANIFEST_NAME).read_bytes()
second = replay.build_semantic_slam_replay(**arguments)
assert second.result_id == first.result_id
assert (second.result_root / replay.SEMANTIC_SLAM_MANIFEST_NAME).read_bytes() == manifest_before
assert admitted.geometry_frames_path.read_bytes() == geometry_before
assert admitted.threat_frames_path.read_bytes() == threat_before
identity = first.manifest["identity"]
assert identity["geometry_frames_sha256"] == hashlib.sha256(geometry_before).hexdigest()
assert identity["base_m4_frames_sha256"] == hashlib.sha256(threat_before).hexdigest()
def test_unprojected_source_point_is_uint8_zero_with_explicit_status(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
result, _ = _build(tmp_path, monkeypatch)
with np.load(
result.result_root / replay.SEMANTIC_SLAM_POINTS_NAME,
allow_pickle=False,
) as archive:
assert archive["point_labels"].dtype == np.uint8
assert archive["point_labels"].tolist() == [4, 0]
assert archive["point_status_codes"].tolist() == [
int(SemanticEvidenceStatus.LABELED),
int(SemanticEvidenceStatus.UNPROJECTED),
]
assert archive["point_projected"].tolist() == [1, 0]
rows = [
json.loads(line)
for line in (result.result_root / replay.SEMANTIC_SLAM_OBSERVATIONS_NAME)
.read_text("utf-8")
.splitlines()
]
assert rows[0]["observations"][0]["observation_id"] == _observation().observation_id
assert rows[0]["observations"][0]["status"] == "labeled"
assert rows[0]["observations"][0]["unprojected_point_count"] == 1
assert "threat" not in rows[0]["observations"][0]
assert rows[0]["source_time_ns"] == 1_000_000_000
assert rows[0]["temporal_binding"] == {
"semantic_to_camera": "exact-sequence-and-session-time",
"camera_to_lidar": "accepted-e6-nearest-host-arrival-best-effort",
"lidar_camera_delta_ms": 4.0,
"pose_point_delta_ms": 2.0,
"physical_synchronization_proven": False,
}
assert rows[1]["temporal_binding"]["lidar_camera_delta_ms"] is None
def test_reader_rejects_tampered_point_artifact(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
result, _ = _build(tmp_path, monkeypatch)
points = result.result_root / replay.SEMANTIC_SLAM_POINTS_NAME
points.write_bytes(points.read_bytes() + b"tamper")
with pytest.raises(replay.SemanticSlamReplayError, match="digest changed"):
replay.read_semantic_slam_replay_result(result.result_root)
def test_builder_rejects_semantic_and_source_pack_session_time_mismatch(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
admitted = _fixture(tmp_path)
rows = [
json.loads(line) for line in admitted.semantic.frames_path.read_text("utf-8").splitlines()
]
rows[1]["session_seconds"] = 2.001
_write_jsonl(admitted.semantic.frames_path, rows)
semantic = replace(
admitted.semantic,
frames_sha256=_sha256(admitted.semantic.frames_path),
)
monkeypatch.setattr(
replay,
"_admit_inputs",
lambda **_kwargs: replace(admitted, semantic=semantic),
)
with pytest.raises(replay.SemanticSlamReplayError, match="session time disagree"):
replay.build_semantic_slam_replay(
repository_root=tmp_path,
semantic_result_root=tmp_path,
threat_result_root=tmp_path,
geometry_result_root=tmp_path,
output_root=tmp_path / "output",
)
def test_builder_rejects_best_effort_delta_outside_admitted_bound(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
admitted = _fixture(tmp_path)
frame = admitted.store.frame_for_index(0)
assert frame is not None
monkeypatch.setattr(
replay,
"_admit_inputs",
lambda **_kwargs: replace(
admitted,
store=_Store(frame, lidar_delta_ms=100.001), # type: ignore[arg-type]
),
)
with pytest.raises(replay.SemanticSlamReplayError, match="delta exceeds"):
replay.build_semantic_slam_replay(
repository_root=tmp_path,
semantic_result_root=tmp_path,
threat_result_root=tmp_path,
geometry_result_root=tmp_path,
output_root=tmp_path / "output",
)
def test_reader_rejects_leaf_result_symlink(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
result, _ = _build(tmp_path, monkeypatch)
alias_parent = tmp_path / "alias"
alias_parent.mkdir()
alias = alias_parent / result.result_id
alias.symlink_to(result.result_root, target_is_directory=True)
with pytest.raises(replay.SemanticSlamReplayError, match="result root is invalid"):
replay.read_semantic_slam_replay_result(alias)
def test_builder_rejects_existing_destination_symlink(
tmp_path: Path,
monkeypatch: pytest.MonkeyPatch,
) -> None:
result, admitted = _build(tmp_path, monkeypatch)
monkeypatch.setattr(replay, "_admit_inputs", lambda **_kwargs: admitted)
second_output = tmp_path / "second-output"
second_output.mkdir()
(second_output / result.result_id).symlink_to(result.result_root, target_is_directory=True)
with pytest.raises(replay.SemanticSlamReplayError, match="destination cannot be a symlink"):
replay.build_semantic_slam_replay(
repository_root=tmp_path,
semantic_result_root=tmp_path,
threat_result_root=tmp_path,
geometry_result_root=tmp_path,
output_root=second_output,
)