x4d-devkit 0.16.0__tar.gz → 0.17.0__tar.gz

{x4d_devkit-0.16.0 → x4d_devkit-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.16.0
+Version: 0.17.0
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.24
 Requires-Dist: httpx>=0.27
+Requires-Dist: rfc8785==0.1.4
 Provides-Extra: converters
 Requires-Dist: nuscenes-devkit>=1.1.0; extra == "converters"
 Provides-Extra: inference
@@ -294,12 +295,12 @@ label_schema.projects.<project>.contract       # binding + full registry record
 label_schema.projects.<project>.class_catalog  # training/observed class catalog
 ```
 
-The deprecated per-project `classes`, `source`, and `schema_version` aliases
-remain in manifest v0.1 for existing consumers. New consumers must parse
-`contract` with `parse_project_label_schema_snapshot()` and treat
-`class_catalog` as non-authoritative observation metadata.
+Consumers must parse `contract` with
+`parse_project_label_schema_snapshot()`. `class_catalog` is
+non-authoritative observation metadata; there are no per-project
+`classes`, `source`, or `schema_version` aliases.
 
-This strict parser/view contract is introduced in x4d-devkit `0.16.0`.
+This strict parser/view contract is introduced in x4d-devkit `0.17.0`.
 Consumers tracking `main` should still record `get_build_info()["source"]` in
 training identity so an untagged development run remains reproducible by exact
 commit. Deployments that copy a source tree without its Git directory must set

{x4d_devkit-0.16.0 → x4d_devkit-0.17.0}/README.md

@@ -260,12 +260,12 @@ label_schema.projects.<project>.contract       # binding + full registry record
 label_schema.projects.<project>.class_catalog  # training/observed class catalog
 ```
 
-The deprecated per-project `classes`, `source`, and `schema_version` aliases
-remain in manifest v0.1 for existing consumers. New consumers must parse
-`contract` with `parse_project_label_schema_snapshot()` and treat
-`class_catalog` as non-authoritative observation metadata.
+Consumers must parse `contract` with
+`parse_project_label_schema_snapshot()`. `class_catalog` is
+non-authoritative observation metadata; there are no per-project
+`classes`, `source`, or `schema_version` aliases.
 
-This strict parser/view contract is introduced in x4d-devkit `0.16.0`.
+This strict parser/view contract is introduced in x4d-devkit `0.17.0`.
 Consumers tracking `main` should still record `get_build_info()["source"]` in
 training identity so an untagged development run remains reproducible by exact
 commit. Deployments that copy a source tree without its Git directory must set

{x4d_devkit-0.16.0 → x4d_devkit-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.16.0"
+version = "0.17.0"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"
@@ -24,7 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
-dependencies = ["numpy>=1.24", "httpx>=0.27"]
+dependencies = ["numpy>=1.24", "httpx>=0.27", "rfc8785==0.1.4"]
 
 [project.optional-dependencies]
 converters = ["nuscenes-devkit>=1.1.0"]

{x4d_devkit-0.16.0 → x4d_devkit-0.17.0}/tests/test_boundary.py

@@ -65,6 +65,7 @@ def test_top_level_exports_only_stable_sdk_surface():
         "Annotation",
         "AssetRef",
         "CalibratedSensor",
+        "ClipContractValidationError",
         "ClipLoader",
         "ClipMeta",
         "ClipWorkSessionManifest",
@@ -87,6 +88,7 @@ def test_top_level_exports_only_stable_sdk_surface():
         "get_build_info",
         "get_training_coordinate_contract",
         "materialize_work_session_clip",
+        "parse_clip_work_session",
         "validate_clip",
     }
     for name in (

{x4d_devkit-0.16.0 → x4d_devkit-0.17.0}/tests/test_box.py

@@ -21,7 +21,7 @@ class TestBoxConstruction:
         assert b.category == "car"
         assert b.score is None
         assert b.velocity is None
-        assert b.attributes == []
+        assert b.attributes == {}
         assert b.id is None
         assert b.geometry_type == "normal"
 
@@ -33,12 +33,12 @@ class TestBoxConstruction:
             category="car",
             score=0.85,
             velocity=[1.0, 0.5, 0.0],
-            attributes=["vehicle.moving"],
+            attributes={"vehicle.moving": True},
         )
         assert b.score == 0.85
         assert b.velocity.dtype == np.float64
         assert b.velocity.tolist() == [1.0, 0.5, 0.0]
-        assert b.attributes == ["vehicle.moving"]
+        assert b.attributes == {"vehicle.moving": True}
 
     def test_identity_and_geometry_type(self):
         b = Box(
@@ -135,14 +135,14 @@ class TestFromXyzlwhyawVxvy:
         b = Box.from_xyzlwhyaw_vxvy(
             [0, 0, 0, 4, 2, 1.5, 0, 0, 0], category="car",
         )
-        assert b.attributes == []
+        assert b.attributes == {}
 
     def test_attributes_passthrough(self):
         b = Box.from_xyzlwhyaw_vxvy(
             [0, 0, 0, 4, 2, 1.5, 0, 0, 0], category="car",
-            attributes=["vehicle.moving"],
+            attributes={"vehicle.moving": True},
         )
-        assert b.attributes == ["vehicle.moving"]
+        assert b.attributes == {"vehicle.moving": True}
 
     def test_identity_and_geometry_type_passthrough(self):
         b = Box.from_xyzlwhyaw_vxvy(
@@ -176,14 +176,21 @@ class TestFromXyzlwhyaw:
 
 class TestGeometryTypeFromAttributes:
     def test_normal_when_geometry_attribute_absent(self):
-        assert geometry_type_from_attributes(["vehicle.moving"]) == "normal"
+        assert geometry_type_from_attributes({"vehicle.moving": True}) == "normal"
 
     def test_front_only(self):
-        assert geometry_type_from_attributes(["geometry.front_only"]) == "front_only"
+        assert geometry_type_from_attributes({"geometry.front_only": True}) == "front_only"
 
     def test_rear_only(self):
-        assert geometry_type_from_attributes(["geometry.rear_only"]) == "rear_only"
+        assert geometry_type_from_attributes({"geometry.rear_only": True}) == "rear_only"
 
     def test_rejects_mutually_exclusive_geometry_attributes(self):
         with pytest.raises(ValueError, match="mutually exclusive"):
-            geometry_type_from_attributes(["geometry.front_only", "geometry.rear_only"])
+            geometry_type_from_attributes({
+                "geometry.front_only": True,
+                "geometry.rear_only": True,
+            })
+
+    def test_rejects_false_presence_flag(self):
+        with pytest.raises(ValueError, match="literal true"):
+            geometry_type_from_attributes({"geometry.front_only": False})

x4d_devkit-0.17.0/tests/test_contract_validation.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+import copy
+import json
+
+import pytest
+
+from tests.schema_contract_fixtures import schema_identity, schema_record
+from x4d_devkit.label_schema import parse_label_schema_record
+from x4d_devkit.validation.contract import (
+    ClipValidationContext,
+    validate_annotation_payload,
+    validate_clip_contract,
+)
+
+
+def _schema():
+    return parse_label_schema_record(schema_record())
+
+
+def _meta() -> dict:
+    return {
+        "clip_id": "clip-a",
+        "schema_version": "0.11",
+        "session_id": "session-a",
+        "vehicle_id": "vehicle-a",
+        "capture_time_utc": "2026-07-10T00:00:00Z",
+        "duration_s": 0.0,
+        "keyframe_count": 1,
+        "sweep_count": 0,
+        "annotation_source_channel": "lidar",
+        "ego_pose_frame_id": "base_link",
+        "sensors": {
+            "lidar": {
+                "modality": "lidar",
+                "frame_id": "base_link",
+                "point_format": {
+                    "fields": ["x", "y", "z", "intensity"],
+                    "types": ["float32", "float32", "float32", "float32"],
+                    "bytes_per_point": 16,
+                },
+            }
+        },
+        "label_schema": schema_identity(),
+    }
+
+
+def _sample() -> dict:
+    return {
+        "sample_token": "s0",
+        "clip_id": "clip-a",
+        "timestamp_us": 1,
+        "is_keyframe": True,
+        "prev": None,
+        "next": None,
+    }
+
+
+def _sample_data() -> dict:
+    return {
+        "sample_data_token": "sd0",
+        "sample_token": "s0",
+        "ego_pose_token": "ep0",
+        "calibrated_sensor_token": "cs0",
+        "channel": "lidar",
+        "file_path": "samples/lidar/1.bin",
+        "timestamp_us": 1,
+        "is_keyframe": True,
+        "width": None,
+        "height": None,
+        "prev": None,
+        "next": None,
+    }
+
+
+def _annotation(
+    *,
+    token: str = "a0",
+    sample_token: str = "s0",
+    instance_token: str = "i0",
+    category: str = "car",
+    attributes: dict | None = None,
+    prev: str | None = None,
+    next: str | None = None,
+) -> dict:
+    return {
+        "annotation_token": token,
+        "sample_token": sample_token,
+        "instance_token": instance_token,
+        "category": category,
+        "bbox_3d": {
+            "translation": {"x": 1.0, "y": 2.0, "z": 0.5},
+            "size": {"length": 4.0, "width": 2.0, "height": 1.5},
+            "rotation": {"qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0},
+        },
+        "num_lidar_pts": 5,
+        "velocity": None,
+        "attributes": attributes if attributes is not None else {"visibility": "1"},
+        "prev": prev,
+        "next": next,
+    }
+
+
+def _instance(
+    *,
+    token: str = "i0",
+    category: str = "car",
+    count: int = 1,
+    first: str = "a0",
+    last: str = "a0",
+) -> dict:
+    return {
+        "instance_token": token,
+        "category": category,
+        "num_annotations": count,
+        "first_annotation_token": first,
+        "last_annotation_token": last,
+    }
+
+
+def _context(
+    *,
+    annotations: list[dict] | None = None,
+    instances: list[dict] | None = None,
+    meta: dict | None = None,
+    sample_data: list[dict] | None = None,
+) -> ClipValidationContext:
+    anns = [_annotation()] if annotations is None else annotations
+    insts = [_instance()] if instances is None else instances
+    return ClipValidationContext(
+        clip_id="clip-a",
+        clip_schema_version="0.11",
+        label_schema=_schema(),
+        samples=[_sample()],
+        sample_data=[_sample_data()] if sample_data is None else sample_data,
+        annotations=anns,
+        instances=insts,
+        meta=_meta() if meta is None else meta,
+        annotation_frame_id="base_link",
+    )
+
+
+def _codes(report) -> set[str]:
+    return {issue.code for issue in report.issues}
+
+
+def test_valid_current_clip_contract_passes_and_serializes():
+    report = validate_clip_contract(_context())
+    assert report.ok
+    assert report.to_dict()["issue_count"] == 0
+    json.dumps(report.to_dict())
+
+
+@pytest.mark.parametrize(
+    ("mutation", "code"),
+    [
+        (lambda ann: ann.update(category="unknown"), "unknown_category"),
+        (lambda ann: ann.update(attributes=["vehicle.moving"]), "invalid_attributes_shape"),
+        (lambda ann: ann.update(attributes={"visibility": "1", "unknown": True}), "unknown_attribute"),
+        (lambda ann: ann.update(attributes={"visibility": "1", "truck.loaded": True}), "invalid_attribute_for_category"),
+        (lambda ann: ann.update(attributes={"visibility": "1", "vehicle.moving": False}), "invalid_attribute_value"),
+        (lambda ann: ann.update(attributes={}), "missing_required_attribute"),
+        (lambda ann: ann["bbox_3d"]["size"].update(length=-1.0), "invalid_bbox_size"),
+        (lambda ann: ann["bbox_3d"]["translation"].update(x=float("nan")), "non_finite_bbox_value"),
+        (lambda ann: ann["bbox_3d"]["rotation"].update(qw=2.0), "invalid_bbox_rotation"),
+        (lambda ann: ann.update(num_lidar_pts=True), "invalid_num_lidar_pts"),
+        (lambda ann: ann.update(velocity={"vx": 1.0, "vy": 0.0}), "invalid_velocity"),
+        (lambda ann: ann.update(sample_token="missing"), "sample_token_not_in_clip"),
+        (lambda ann: ann.update(instance_token=""), "missing_instance_token"),
+        (lambda ann: ann.update(prev=""), "invalid_annotation_shape"),
+        (lambda ann: ann.update(score=0.9), "invalid_annotation_shape"),
+    ],
+)
+def test_annotation_contract_reports_strict_issue_codes(mutation, code):
+    annotation = _annotation()
+    mutation(annotation)
+    report = validate_annotation_payload(
+        _context(),
+        annotations=[annotation],
+        instances=[_instance()],
+    )
+    assert code in _codes(report)
+
+
+@pytest.mark.parametrize(
+    "mutation",
+    [
+        lambda ann: ann["bbox_3d"]["translation"].update(extra=0.0),
+        lambda ann: ann["bbox_3d"]["size"].pop("height"),
+        lambda ann: ann["bbox_3d"]["rotation"].update(qx="0"),
+        lambda ann: ann.update(velocity={"vx": 0.0, "vy": 0.0, "vz": 0.0, "extra": 0.0}),
+    ],
+)
+def test_nested_geometry_and_velocity_require_exact_numeric_objects(mutation):
+    annotation = _annotation()
+    mutation(annotation)
+    assert not validate_annotation_payload(
+        _context(), annotations=[annotation], instances=[_instance()]
+    ).ok
+
+
+def test_multiple_enum_requires_sorted_unique_nonempty_values():
+    annotation = _annotation(
+        attributes={"visibility": "1", "vehicle.state_tags": ["turning", "stopped"]}
+    )
+    assert "invalid_attribute_value" in _codes(
+        validate_annotation_payload(_context(), annotations=[annotation], instances=[_instance()])
+    )
+
+
+def test_boolean_mutual_exclusion_uses_literal_true_presence():
+    annotation = _annotation(
+        category="truck",
+        attributes={"visibility": "1", "truck.empty": True, "truck.loaded": True},
+    )
+    instance = _instance(category="truck")
+    assert "mutually_exclusive_attributes" in _codes(
+        validate_annotation_payload(_context(), annotations=[annotation], instances=[instance])
+    )
+
+
+def test_instance_shape_tokens_counts_and_chain_are_exact():
+    first = _annotation(token="a0", next="a1")
+    second = _annotation(token="a1", sample_token="s1", prev="a0")
+    valid_instance = _instance(count=2, first="a0", last="a1")
+    context = _context()
+    context.samples[0]["next"] = "s1"
+    context.samples.append({
+        "sample_token": "s1",
+        "clip_id": "clip-a",
+        "timestamp_us": 2,
+        "is_keyframe": True,
+        "prev": "s0",
+        "next": None,
+    })
+    second_sample_data = _sample_data()
+    context.sample_data[0]["next"] = "sd1"
+    second_sample_data.update(
+        sample_data_token="sd1",
+        sample_token="s1",
+        timestamp_us=2,
+        file_path="samples/lidar/2.bin",
+        prev="sd0",
+    )
+    context.sample_data.append(second_sample_data)
+    assert validate_annotation_payload(
+        context, annotations=[first, second], instances=[valid_instance]
+    ).ok
+
+    broken = copy.deepcopy(valid_instance)
+    broken["extra"] = True
+    broken["last_annotation_token"] = "a0"
+    report = validate_annotation_payload(
+        context, annotations=[first, second], instances=[broken]
+    )
+    assert {"invalid_instance_shape", "broken_instance_chain"}.issubset(_codes(report))
+
+
+def test_instance_links_must_be_reciprocal_and_stay_in_one_instance():
+    first = _annotation(token="a0", next="a1")
+    second = _annotation(token="a1", instance_token="i1", prev=None)
+    report = validate_annotation_payload(
+        _context(),
+        annotations=[first, second],
+        instances=[_instance(), _instance(token="i1", first="a1", last="a1")],
+    )
+    assert "broken_instance_chain" in _codes(report)
+
+
+def test_draft_frame_scope_skips_final_clip_closure_only():
+    report = validate_annotation_payload(
+        _context(),
+        annotations=[_annotation()],
+        instances=[],
+        scope="frame",
+        phase="draft",
+    )
+    assert report.ok
+
+    bad = _annotation(category="unknown")
+    report = validate_annotation_payload(
+        _context(), annotations=[bad], instances=[], scope="frame", phase="draft"
+    )
+    assert "unknown_category" in _codes(report)
+
+
+def test_final_sensor_coverage_requires_every_declared_channel():
+    meta = _meta()
+    meta["sensors"]["cam_front"] = {"modality": "camera", "frame_id": "cam_front"}
+    report = validate_clip_contract(_context(meta=meta))
+    assert "incomplete_sensor_coverage" in _codes(report)
+
+
+def test_context_rejects_non_list_payloads_and_invalid_meta():
+    with pytest.raises(TypeError):
+        validate_annotation_payload(_context(), annotations=(), instances=[])
+    with pytest.raises(TypeError):
+        ClipValidationContext(
+            clip_id="clip-a",
+            clip_schema_version="0.11",
+            label_schema=_schema(),
+            samples=(),
+            meta=_meta(),
+        )
+
+    meta = _meta()
+    meta["topic_config_id"] = 1
+    assert "invalid_clip_meta" in _codes(validate_clip_contract(_context(meta=meta)))
+
+
+def test_context_identity_and_derived_frame_must_match():
+    meta = _meta()
+    meta["label_schema"]["fingerprint"] = "sha256:" + "0" * 64
+    report = validate_clip_contract(_context(meta=meta))
+    assert "label_schema_fingerprint_mismatch" in _codes(report)
+
+    context = _context()
+    object.__setattr__(context, "annotation_frame_id", "other")
+    assert "annotation_frame_mismatch" in _codes(validate_clip_contract(context))
+
+
+@pytest.mark.parametrize("status", ["draft", "deprecated"])
+def test_shared_contract_requires_active_label_schema_in_every_phase(status):
+    context = _context()
+    object.__setattr__(context, "label_schema", parse_label_schema_record(schema_record(status=status)))
+    for phase in ("draft", "final"):
+        assert "inactive_label_schema" in _codes(
+            validate_clip_contract(context, phase=phase)
+        )
+
+
+def test_instance_declared_chain_must_cover_disconnected_cycle():
+    context = _context()
+    samples = []
+    sample_data = []
+    annotations = []
+    for index in range(4):
+        samples.append({
+            "sample_token": f"s{index}",
+            "clip_id": "clip-a",
+            "timestamp_us": index + 1,
+            "is_keyframe": True,
+            "prev": f"s{index - 1}" if index else None,
+            "next": f"s{index + 1}" if index < 3 else None,
+        })
+        row = _sample_data()
+        row.update(
+            sample_data_token=f"sd{index}",
+            sample_token=f"s{index}",
+            timestamp_us=index + 1,
+            file_path=f"samples/lidar/{index + 1}.bin",
+            prev=f"sd{index - 1}" if index else None,
+            next=f"sd{index + 1}" if index < 3 else None,
+        )
+        sample_data.append(row)
+        annotations.append(
+            _annotation(
+                token=f"a{index}",
+                sample_token=f"s{index}",
+                prev=(None if index == 0 else "a0" if index == 1 else f"a{5 - index}"),
+                next=("a1" if index == 0 else None if index == 1 else f"a{5 - index}"),
+            )
+        )
+    object.__setattr__(context, "samples", samples)
+    object.__setattr__(context, "sample_data", sample_data)
+    report = validate_annotation_payload(
+        context,
+        annotations=annotations,
+        instances=[_instance(count=4, first="a0", last="a1")],
+    )
+    assert "broken_instance_chain" in _codes(report)
+
+
+def test_shared_contract_rejects_nonreciprocal_sample_data_chain():
+    context = _context()
+    context.samples[0]["next"] = "s1"
+    context.samples.append({
+        "sample_token": "s1",
+        "clip_id": "clip-a",
+        "timestamp_us": 2,
+        "is_keyframe": True,
+        "prev": "s0",
+        "next": None,
+    })
+    context.sample_data[0]["next"] = "sd1"
+    second = _sample_data()
+    second.update(
+        sample_data_token="sd1",
+        sample_token="s1",
+        timestamp_us=2,
+        file_path="samples/lidar/2.bin",
+        prev=None,
+    )
+    context.sample_data.append(second)
+    assert "sample_data_chain" in _codes(validate_clip_contract(context))
+
+
+def test_sample_chain_rejects_disconnected_cycle():
+    context = _context()
+    object.__setattr__(context, "samples", [
+        {"sample_token": "s0", "clip_id": "clip-a", "timestamp_us": 1, "is_keyframe": True, "prev": None, "next": "s1"},
+        {"sample_token": "s1", "clip_id": "clip-a", "timestamp_us": 2, "is_keyframe": True, "prev": "s0", "next": None},
+        {"sample_token": "s2", "clip_id": "clip-a", "timestamp_us": 3, "is_keyframe": True, "prev": "s3", "next": "s3"},
+        {"sample_token": "s3", "clip_id": "clip-a", "timestamp_us": 4, "is_keyframe": True, "prev": "s2", "next": "s2"},
+    ])
+    assert "broken_sample_chain" in _codes(validate_clip_contract(context))
+
+
+def test_invalid_scope_and_phase_are_rejected():
+    with pytest.raises(ValueError):
+        validate_annotation_payload(_context(), annotations=[], instances=[], scope="dataset")
+    with pytest.raises(ValueError):
+        validate_annotation_payload(_context(), annotations=[], instances=[], phase="publish")

x4d_devkit-0.17.0/tests/test_coordinate_frames.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from tests.current_clip_fixtures import write_current_clip
+from x4d_devkit.core.loader import CLIP_WORLD_FRAME_ID, ClipLoader
+
+
+@pytest.fixture()
+def loader(tmp_path):
+    clip = write_current_clip(
+        tmp_path / "coordinate-clip",
+        sample_count=2,
+        include_camera=True,
+        include_fused=True,
+    )
+    return ClipLoader(clip)
+
+
+def test_current_frame_ids_are_explicit_and_annotation_frame_is_derived(loader):
+    sd = loader.sample_data_for_channel("lidar_top")[0]
+    assert loader.ego_pose_frame_id == "base_link"
+    assert loader.annotation_source_channel == "fused"
+    assert loader.annotation_frame_id == "base_link"
+    assert loader.sensor_frame_id(sd) == "lidar_top"
+    assert CLIP_WORLD_FRAME_ID == "clip_world"
+
+
+def test_point_cloud_defaults_to_sensor_frame_and_preserves_payload(loader):
+    sd = loader.sample_data_for_channel("lidar_top")[0]
+    raw = loader.load_point_cloud(sd)
+    explicit = loader.load_point_cloud(sd, frame="lidar_top")
+    np.testing.assert_array_equal(raw, explicit)
+    np.testing.assert_allclose(raw[0], [1.0, 0.0, 0.0, 0.5])
+
+
+def test_point_cloud_transforms_to_ego_and_clip_world(loader):
+    first, second = loader.sample_data_for_channel("lidar_top")
+    first_ego = loader.load_point_cloud(first, frame="base_link")
+    first_world = loader.load_point_cloud(first, frame=CLIP_WORLD_FRAME_ID)
+    second_world = loader.load_point_cloud(second, frame=CLIP_WORLD_FRAME_ID)
+    np.testing.assert_allclose(first_ego[0, :3], [1.0, 0.0, 1.0])
+    np.testing.assert_allclose(first_world[0, :3], [1.0, 0.0, 1.0])
+    np.testing.assert_allclose(second_world[0, :3], [11.0, 0.0, 1.0])
+
+
+def test_annotations_transform_from_native_frame_to_world(loader):
+    first = loader.annotations_for_sample("sample-0")
+    second = loader.annotations_for_sample("sample-1")
+    first_world = loader.annotations_for_sample("sample-0", frame=CLIP_WORLD_FRAME_ID)
+    second_world = loader.annotations_for_sample("sample-1", frame=CLIP_WORLD_FRAME_ID)
+    assert first_world[0] is not first[0]
+    np.testing.assert_allclose(first_world[0].translation, [5.0, 3.0, 0.0])
+    np.testing.assert_allclose(second_world[0].translation, [10.0, 3.0, 0.0])
+    np.testing.assert_allclose(second[0].velocity, second_world[0].velocity)
+
+
+def test_static_and_dynamic_transform_round_trip(loader):
+    sd = loader.sample_data_for_channel("lidar_top")[1]
+    sensor_to_world = loader.get_transform("lidar_top", CLIP_WORLD_FRAME_ID, sd=sd)
+    world_to_sensor = loader.get_transform(CLIP_WORLD_FRAME_ID, "lidar_top", sd=sd)
+    points = np.array([[1.0, 2.0, 3.0]])
+    np.testing.assert_allclose(world_to_sensor.apply(sensor_to_world.apply(points)), points)
+
+
+@pytest.mark.parametrize("alias", ["sensor", "ego", "world"])
+def test_legacy_magic_frame_aliases_are_rejected(loader, alias):
+    sd = loader.sample_data_for_channel("lidar_top")[0]
+    with pytest.raises(ValueError, match="legacy magic aliases"):
+        loader.load_point_cloud(sd, frame=alias)
+
+
+def test_unknown_real_frame_is_rejected(loader):
+    with pytest.raises(KeyError):
+        loader.get_transform("lidar_top", "unknown_frame")
+
+
+def test_clip_world_requires_sample_data_for_dynamic_transform(loader):
+    with pytest.raises(ValueError, match="pass sd"):
+        loader.get_transform("lidar_top", CLIP_WORLD_FRAME_ID)