oopsie-data-tools 0.2.0__py3-none-any.whl

oopsie_data_tools/test/test_credentials_location.py

@@ -0,0 +1,106 @@
+"""The contributor config holds a HuggingFace token, so where it lands matters.
+
+``configs/contributor_config.yaml`` used to be tracked by git *and* listed in .gitignore
+(which does nothing for an already-tracked file), while the wizard defaulted to writing
+there. These tests pin down the two halves of the fix.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from oopsie_data_tools import init_wizard
+from oopsie_data_tools.utils import contributor_config, paths
+
+# conftest._test_contributor_config rebinds the module attribute for the whole session, so
+# `contributor_config.read_contributor_config` resolves to a stub at call time. Bind the real
+# function here at import, which happens during collection, before that fixture runs.
+# Batch 5 switches conftest to monkeypatch, after which this can go back to a plain call.
+_real_read_contributor_config = contributor_config.read_contributor_config
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+@pytest.fixture
+def isolated(tmp_path, monkeypatch):
+    """No env override, a fake home, and an interactive stdin."""
+    monkeypatch.delenv(paths.ENV_CONFIG_DIR, raising=False)
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+    monkeypatch.setattr(init_wizard.sys.stdin, "isatty", lambda: True)
+    return tmp_path
+
+
+def test_config_file_is_not_tracked_by_git():
+    """A tracked file makes its .gitignore entry inert, which is how tokens got committed."""
+    tracked = subprocess.run(
+        ["git", "ls-files", "--error-unmatch", "configs/contributor_config.yaml"],
+        cwd=REPO_ROOT,
+        capture_output=True,
+    )
+    assert tracked.returncode != 0, (
+        "configs/contributor_config.yaml is tracked again. While tracked, .gitignore does "
+        "not apply to it and a contributor's HuggingFace token shows up in git status."
+    )
+
+
+def test_config_file_is_ignored():
+    ignored = subprocess.run(
+        ["git", "check-ignore", "configs/contributor_config.yaml"],
+        cwd=REPO_ROOT,
+        capture_output=True,
+    )
+    assert ignored.returncode == 0, "configs/contributor_config.yaml must stay gitignored"
+
+
+def test_wizard_defaults_away_from_the_checkout(isolated, monkeypatch):
+    """Pressing Enter must not put a token inside a git working tree."""
+    answers = iter([""])  # accept the default
+    monkeypatch.setattr("builtins.input", lambda *_: next(answers))
+
+    target = init_wizard.choose_target_dir()
+
+    assert target == paths.user_config_dir()
+    assert target != paths.repo_config_dir()
+
+
+def test_wizard_still_allows_the_checkout_when_asked(isolated, monkeypatch):
+    answers = iter(["2"])  # the second option is the checkout
+    monkeypatch.setattr("builtins.input", lambda *_: next(answers))
+
+    assert init_wizard.choose_target_dir() == paths.repo_config_dir()
+
+
+def test_wizard_uses_user_dir_when_not_interactive(isolated, monkeypatch):
+    monkeypatch.setattr(init_wizard.sys.stdin, "isatty", lambda: False)
+
+    assert init_wizard.choose_target_dir() == paths.user_config_dir()
+
+
+def test_reading_from_the_checkout_warns(tmp_path, monkeypatch, caplog):
+    """Existing clones still have a filled-in copy; point them at the user config dir."""
+    monkeypatch.setattr(contributor_config, "_warned_about_checkout_config", False)
+    repo_configs = tmp_path / "configs"
+    repo_configs.mkdir()
+    config = repo_configs / "contributor_config.yaml"
+    config.write_text("lab_id: MyLab\nhuggingface_token: hf_secret\n", encoding="utf-8")
+    monkeypatch.setattr(paths, "_REPO_CONFIG_DIR", repo_configs)
+
+    lab_id, token = _real_read_contributor_config(config)
+
+    assert (lab_id, token) == ("MyLab", "hf_secret"), "must still work, only warn"
+    assert "inside the repository working tree" in caplog.text
+    assert "oopsie-data init" in caplog.text
+    assert "hf_secret" not in caplog.text, "never log the token itself"
+
+
+def test_reading_from_the_user_dir_is_silent(tmp_path, monkeypatch, caplog):
+    monkeypatch.setattr(contributor_config, "_warned_about_checkout_config", False)
+    config = tmp_path / "contributor_config.yaml"
+    config.write_text("lab_id: MyLab\n", encoding="utf-8")
+
+    _real_read_contributor_config(config)
+
+    assert caplog.text == ""

oopsie_data_tools/test/test_diversity.py

@@ -0,0 +1,33 @@
+"""Tests for the attr-only diversity heuristics (issue #40)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import h5py
+
+from oopsie_data_tools.test.fixtures.make_valid import write_valid_episode
+from oopsie_data_tools.utils.validation.diversity import check_diversity
+
+
+def test_below_min_episodes_no_warning(tmp_path: Path) -> None:
+    for i in range(3):
+        write_valid_episode(tmp_path, stem=f"ep{i}")
+    assert check_diversity(str(tmp_path)) == []
+
+
+def test_identical_instructions_warns(tmp_path: Path) -> None:
+    # write_valid_episode uses a single fixed language_instruction for every episode.
+    for i in range(6):
+        write_valid_episode(tmp_path, stem=f"ep{i}")
+    warnings = check_diversity(str(tmp_path))
+    assert any("task diversity" in w.lower() for w in warnings)
+
+
+def test_diverse_instructions_no_task_warning(tmp_path: Path) -> None:
+    for i in range(6):
+        h5_path = write_valid_episode(tmp_path, stem=f"ep{i}")
+        with h5py.File(h5_path, "r+") as f:
+            f.attrs["language_instruction"] = f"task number {i}"
+    warnings = check_diversity(str(tmp_path))
+    assert not any("task diversity" in w.lower() for w in warnings)

oopsie_data_tools/test/test_episode_recorder.py

@@ -0,0 +1,335 @@
+"""Tests for EpisodeRecorder: buffering, validation, and HDF5 output."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+from oopsie_data_tools.annotation_tool.episode_recorder import (
+    EpisodeRecorder,
+    write_mp4,
+)
+from oopsie_data_tools.utils.robot_profile.robot_profile import RobotProfile
+
+
+def _profile(**overrides) -> RobotProfile:
+    defaults = dict(
+        policy_name="test_policy",
+        robot_name="test_robot",
+        is_biarm=False,
+        uses_mobile_base=False,
+        gripper_name="test_gripper",
+        control_freq=10,
+        camera_names=["left", "wrist"],
+        robot_state_keys=["joint_position", "gripper_position"],
+        robot_state_joint_names=["j1", "j2", "j3", "j4", "j5", "j6", "j7"],
+        action_space=["joint_velocity", "gripper_position"],
+        action_joint_names=["j1", "j2", "j3", "j4", "j5", "j6", "j7"],
+    )
+    defaults.update(overrides)
+    return RobotProfile(**defaults)
+
+
+def _obs(profile: RobotProfile) -> dict:
+    return {
+        "robot_state": {
+            "joint_position": np.zeros(7, dtype=np.float32),
+            "gripper_position": np.zeros(1, dtype=np.float32),
+        },
+        "image_observation": {
+            cam: np.zeros((64, 64, 3), dtype=np.uint8) for cam in profile.camera_names
+        },
+    }
+
+
+def _action(profile: RobotProfile) -> dict:
+    sizes = {
+        "joint_velocity": 7,
+        "joint_position": 7,
+        "gripper_position": 1,
+        "gripper_velocity": 1,
+    }
+    return {
+        k: np.zeros(sizes.get(k, 1), dtype=np.float32) for k in profile.action_space
+    }
+
+
+def _save_data(recorder: EpisodeRecorder, cam_names: list[str]) -> dict:
+    return {
+        "language_instruction": "pick up the cup",
+        "metadata": {
+            "episode_id": recorder.save_fname,
+            "operator_name": "tester",
+        },
+        "video_paths": {cam: f"/tmp/{cam}.mp4" for cam in cam_names},
+    }
+
+
+class TestEpisodeRecorderInit(unittest.TestCase):
+    def test_session_dir_created(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            recorder = EpisodeRecorder(robot_profile=_profile(), data_root_dir=tmp, operator_name="test_operator")
+            self.assertTrue(recorder.session_dir.is_dir())
+
+    def test_resume_session_name(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            recorder = EpisodeRecorder(
+                robot_profile=_profile(),
+                data_root_dir=tmp,
+                resume_session_name="my_session",
+                operator_name="test_operator",
+            )
+            self.assertEqual(recorder.session_name, "my_session")
+
+    def test_initial_num_steps_zero(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            recorder = EpisodeRecorder(robot_profile=_profile(), data_root_dir=tmp, operator_name="test_operator")
+            self.assertEqual(recorder.num_steps, 0)
+
+
+class TestEpisodeRecorderRecordStep(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.profile = _profile()
+        self.recorder = EpisodeRecorder(
+            robot_profile=self.profile, data_root_dir=self._tmp.name, operator_name="test_operator"
+        )
+        self.recorder.reset_episode_recorder()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_record_step_increments_count(self):
+        self.recorder.record_step(_obs(self.profile), _action(self.profile))
+        self.assertEqual(self.recorder.num_steps, 1)
+
+    def test_multiple_steps_accumulate(self):
+        for _ in range(5):
+            self.recorder.record_step(_obs(self.profile), _action(self.profile))
+        self.assertEqual(self.recorder.num_steps, 5)
+
+    def test_reset_clears_steps(self):
+        self.recorder.record_step(_obs(self.profile), _action(self.profile))
+        self.recorder.reset_episode_recorder()
+        self.assertEqual(self.recorder.num_steps, 0)
+
+    def test_rejects_non_dict_observation(self):
+        with self.assertRaises(ValueError):
+            self.recorder.record_step("not a dict", _action(self.profile))
+
+    def test_rejects_missing_robot_state_key(self):
+        obs = _obs(self.profile)
+        del obs["robot_state"]
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+    def test_rejects_missing_image_observation_key(self):
+        obs = _obs(self.profile)
+        del obs["image_observation"]
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+    def test_rejects_missing_camera(self):
+        obs = _obs(self.profile)
+        del obs["image_observation"]["left"]
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+    def test_rejects_missing_robot_state_component(self):
+        obs = _obs(self.profile)
+        del obs["robot_state"]["joint_position"]
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+    def test_rejects_empty_action(self):
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), {})
+
+    def test_rejects_unrecognized_action_key(self):
+        action = {**_action(self.profile), "bad_key": np.zeros(1)}
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_mismatched_action_keys(self):
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(
+                _obs(self.profile), {"joint_velocity": np.zeros(7)}
+            )
+
+    def test_rejects_none_action_values(self):
+        action = {k: None for k in self.profile.action_space}
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_non_dict_action(self):
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), np.zeros(8))
+
+
+class TestEpisodeRecorderSave(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.profile = _profile()
+        self.recorder = EpisodeRecorder(
+            robot_profile=self.profile, data_root_dir=self._tmp.name, operator_name="test_operator"
+        )
+        self.recorder.reset_episode_recorder()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def _record_n(self, n: int = 3) -> None:
+        for _ in range(n):
+            self.recorder.record_step(_obs(self.profile), _action(self.profile))
+
+    def test_save_returns_h5_path(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        self.assertIsInstance(h5_path, Path)
+        self.assertEqual(h5_path.suffix, ".h5")
+
+    def test_save_file_exists(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        self.assertTrue(h5_path.exists())
+
+    def test_save_h5_attrs(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        with h5py.File(h5_path, "r") as f:
+            self.assertEqual(f.attrs["language_instruction"], "pick up the cup")
+            self.assertEqual(f.attrs["schema"], "oopsiedata_format_v1")
+
+    def test_save_h5_observations_and_robot_states(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        with h5py.File(h5_path, "r") as f:
+            self.assertIn("observations", f)
+            self.assertIn("robot_states", f["observations"])
+            self.assertIn("joint_position", f["observations/robot_states"])
+
+    def test_save_h5_robot_state_timestep_count(self):
+        self._record_n(4)
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        with h5py.File(h5_path, "r") as f:
+            self.assertEqual(f["observations/robot_states/joint_position"].shape[0], 4)
+
+    def test_save_h5_actions_group(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        with h5py.File(h5_path, "r") as f:
+            self.assertIn("actions", f)
+
+    def test_save_raises_without_steps(self):
+        with self.assertRaises(ValueError):
+            self.recorder.save(_save_data(self.recorder, self.profile.camera_names))
+
+    def test_save_in_session_dir(self):
+        self._record_n()
+        h5_path = self.recorder.save(
+            _save_data(self.recorder, self.profile.camera_names)
+        )
+        self.assertEqual(h5_path.parent, self.recorder.session_dir)
+
+
+class TestWriteMp4Validation(unittest.TestCase):
+    def test_wrong_ndim_raises(self):
+        frames = np.zeros((64, 64, 3), dtype=np.uint8)  # missing time dimension
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(ValueError, msg="3-D array should raise"):
+                write_mp4(Path(tmp) / "out.mp4", frames, fps=10.0)
+
+    def test_wrong_channel_count_raises(self):
+        frames = np.zeros((4, 64, 64, 4), dtype=np.uint8)  # RGBA instead of RGB
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(ValueError, msg="RGBA frames should raise"):
+                write_mp4(Path(tmp) / "out.mp4", frames, fps=10.0)
+
+    def test_zero_frames_raises(self):
+        frames = np.zeros((0, 64, 64, 3), dtype=np.uint8)
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(ValueError, msg="zero-frame array should raise"):
+                write_mp4(Path(tmp) / "out.mp4", frames, fps=10.0)
+
+    def test_2d_array_raises(self):
+        frames = np.zeros((64, 64), dtype=np.uint8)
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(ValueError):
+                write_mp4(Path(tmp) / "out.mp4", frames, fps=10.0)
+
+
+class TestRecordStepActionBreaking(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.profile = _profile()
+        self.recorder = EpisodeRecorder(
+            robot_profile=self.profile, data_root_dir=self._tmp.name, operator_name="test_operator"
+        )
+        self.recorder.reset_episode_recorder()
+
+    def tearDown(self):
+        self._tmp.cleanup()
+
+    def test_rejects_partial_none_action_value(self):
+        """One None among otherwise valid keys should still raise."""
+        action = _action(self.profile)
+        first_key = next(iter(action))
+        action[first_key] = None
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_action_superset_of_profile(self):
+        """Extra valid action key beyond profile's action_space should raise."""
+        action = _action(self.profile)
+        action["cartesian_position"] = np.zeros(7, dtype=np.float32)
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_action_subset_of_profile(self):
+        """Providing only one of the required profile action keys should raise."""
+        action = {"joint_velocity": np.zeros(7, dtype=np.float32)}
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_action_with_wrong_but_valid_global_keys(self):
+        """Globally-valid keys that don't match the profile's action_space should raise."""
+        action = {
+            "cartesian_position": np.zeros(7, dtype=np.float32),
+            "gripper_position": np.zeros(1, dtype=np.float32),
+        }
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(_obs(self.profile), action)
+
+    def test_rejects_extra_camera_not_in_profile(self):
+        """image_observation with extra camera beyond profile is fine, but missing one raises."""
+        obs = _obs(self.profile)
+        del obs["image_observation"]["wrist"]
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+    def test_rejects_extra_robot_state_key_missing_required(self):
+        """robot_state with a different key than required should raise."""
+        obs = _obs(self.profile)
+        obs["robot_state"] = {"unexpected_key": np.zeros(7)}
+        with self.assertRaises(ValueError):
+            self.recorder.record_step(obs, _action(self.profile))
+
+
+if __name__ == "__main__":
+    unittest.main()

oopsie_data_tools/test/test_episode_video_paths.py

@@ -0,0 +1,173 @@
+"""How an episode records where its videos live.
+
+Paths are stored relative to the episode file so a session directory can be moved or
+uploaded from anywhere. That only holds if both sides of the relpath use the same base:
+measuring a resolved video against an unresolved directory used to store
+``../../../private/tmp/<session>/x.mp4`` for a video sitting right beside the episode,
+because /tmp is a symlink to /private/tmp on macOS. Such a path still resolves in place,
+so nothing failed — until the directory moved.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import h5py
+import numpy as np
+import pytest
+
+from oopsie_data_tools.annotation_tool.episode_recorder import EpisodeRecorder
+from oopsie_data_tools.utils.robot_profile.robot_profile import RobotProfile
+from oopsie_data_tools.utils.validation.validation_utils import validate_h5_file
+
+CAMERAS = ["left", "wrist"]
+
+
+def _profile() -> RobotProfile:
+    return RobotProfile(
+        policy_name="p",
+        robot_name="r",
+        is_biarm=False,
+        uses_mobile_base=False,
+        gripper_name="g",
+        control_freq=10,
+        camera_names=CAMERAS,
+        robot_state_keys=["joint_position", "gripper_position"],
+        robot_state_joint_names=["j1", "j2"],
+        action_space=["joint_position", "gripper_position"],
+        action_joint_names=["j1", "j2"],
+    )
+
+
+def _record_episode(data_root: Path) -> Path:
+    """Record a short episode into ``data_root``; returns the path to its .h5 file."""
+    profile = _profile()
+    recorder = EpisodeRecorder(
+        robot_profile=profile, data_root_dir=data_root, operator_name="op"
+    )
+    for _ in range(30):
+        recorder.record_step(
+            observation={
+                "robot_state": {
+                    "joint_position": np.zeros(2, dtype=np.float32),
+                    "gripper_position": np.zeros(1, dtype=np.float32),
+                },
+                "image_observation": {
+                    cam: np.zeros((240, 320, 3), dtype=np.uint8) for cam in CAMERAS
+                },
+            },
+            action={
+                "joint_position": np.zeros(2, dtype=np.float32),
+                "gripper_position": np.zeros(1, dtype=np.float32),
+            },
+        )
+    recorder.finish_rollout(instruction="pick up the block", success=1.0)
+    return next(Path(data_root).rglob("*.h5"))
+
+
+@pytest.fixture
+def episode(tmp_path) -> Path:
+    return _record_episode(tmp_path)
+
+
+@pytest.fixture
+def symlinked_episode(tmp_path) -> Path:
+    """An episode recorded through a symlinked data root.
+
+    This is what makes the surrounding tests mean anything off macOS. There, /tmp is a
+    symlink to /private/tmp, so pytest's tmp_path exposed the resolved/unresolved mismatch
+    for free; on Linux tmp_path is a real directory and every assertion here passes even
+    against the unfixed code. Putting the symlink in explicitly makes the regression
+    reproducible on any platform — which matters, because CI only runs Linux.
+
+    The link has to be *shallower than its target* to reproduce the fault. With both at
+    the same depth the stray ".." segments still resolve back to the right place and the
+    stored path comes out clean anyway; only when they overshoot the link's own parent —
+    exactly the shape of /tmp -> /private/tmp — does the broken path survive into the file.
+    """
+    real = tmp_path / "deep" / "deeper" / "real_root"
+    real.mkdir(parents=True)
+    link = tmp_path / "linked_root"
+    try:
+        link.symlink_to(real, target_is_directory=True)
+    except (OSError, NotImplementedError) as e:  # Windows without developer mode
+        pytest.skip(f"cannot create symlinks on this platform: {e}")
+    return _record_episode(link)
+
+
+def _stored_paths(h5_path: Path) -> dict[str, str]:
+    with h5py.File(h5_path, "r") as f:
+        group = f["observations/video_paths"]
+        return {cam: group[cam][()].decode("utf-8") for cam in group}
+
+
+def test_stored_paths_are_relative_and_point_at_the_videos(episode):
+    """Deliberately loose: any relative layout is fine as long as it resolves.
+
+    Pinning the exact string would freeze today's flat "<stem>_<cam>.mp4" layout and break
+    if videos ever move into a subdirectory, which is not what this is protecting.
+    """
+    stored = _stored_paths(episode)
+
+    assert set(stored) == set(CAMERAS)
+    for cam, rel in stored.items():
+        assert not Path(rel).is_absolute(), f"{cam} stored an absolute path: {rel!r}"
+        assert (episode.parent / rel).is_file(), f"{cam} path does not resolve: {rel!r}"
+
+
+def test_stored_paths_stay_inside_the_data_root(episode, tmp_path):
+    """The actual regression: a path must not leave the dataset and climb back in.
+
+    A video beside its episode was stored as "../../../private/tmp/<session>/x.mp4". That
+    resolves correctly in place, so nothing failed — it is only wrong because it encodes
+    the absolute location of the machine that recorded it. Subdirectories and sibling
+    directories inside the data root remain perfectly acceptable.
+    """
+    root = tmp_path.resolve()
+
+    for cam, rel in _stored_paths(episode).items():
+        resolved = (episode.parent / rel).resolve()
+        assert root in resolved.parents, (
+            f"{cam} stored {rel!r}, which escapes the data root {root} before returning. "
+            "Both sides of the relpath must use the same resolved base."
+        )
+
+
+def test_exactly_one_video_per_camera_is_written(episode):
+    """Two writers used to run over the same frames; only one should now."""
+    mp4s = sorted(p.name for p in episode.parent.glob("*.mp4"))
+
+    assert len(mp4s) == len(CAMERAS), f"expected one mp4 per camera, got {mp4s}"
+
+
+def test_the_session_directory_can_be_moved(episode, tmp_path):
+    """The reason paths are relative in the first place."""
+    destination = tmp_path / "relocated"
+    shutil.move(str(episode.parent), str(destination))
+    moved = next(destination.glob("*.h5"))
+
+    assert validate_h5_file(str(moved), strict_annotation_check=True)
+
+
+def test_a_symlinked_data_root_still_stores_portable_paths(symlinked_episode, tmp_path):
+    """The regression itself, reproducible on any platform.
+
+    Recording through a symlinked directory used to store a path that walked up to the
+    filesystem root and back down the resolved side of the link.
+    """
+    for cam, rel in _stored_paths(symlinked_episode).items():
+        assert not Path(rel).is_absolute(), f"{cam}: {rel!r}"
+        assert not rel.startswith("../"), (
+            f"{cam} stored {rel!r}: the relpath was measured against an unresolved base, "
+            "so it escapes the dataset and walks back in through the symlink target."
+        )
+        assert (symlinked_episode.parent / rel).is_file()
+
+
+def test_a_symlinked_session_can_also_be_moved(symlinked_episode, tmp_path):
+    destination = tmp_path / "relocated_from_symlink"
+    shutil.move(str(symlinked_episode.parent), str(destination))
+    moved = next(destination.glob("*.h5"))
+
+    assert validate_h5_file(str(moved), strict_annotation_check=True)