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

oopsie_data_tools/test/test_cli_config.py

@@ -0,0 +1,111 @@
+"""Tests for ``oopsie-data show-config`` (``cli.cmd_show_config``).
+
+The command is purely diagnostic: it prints the lookup chains, marks the entry that wins,
+and shows the credentials in effect. It must never raise on a missing or half-filled
+config — reporting that state is exactly what it is for.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from oopsie_data_tools import cli
+from oopsie_data_tools.utils import paths
+
+TOKEN = "hf_secrettokenvalue"
+
+
+@pytest.fixture
+def env(tmp_path, monkeypatch):
+    """Isolate both chains and the working directory; returns the credential dir."""
+    config_dir = tmp_path / "cfg"
+    config_dir.mkdir()
+    monkeypatch.setenv(paths.ENV_CONFIG_DIR, str(config_dir))
+    monkeypatch.delenv(paths.ENV_PROFILES_DIR, raising=False)
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+    monkeypatch.chdir(tmp_path)
+    return config_dir
+
+
+def _write_config(config_dir, lab_id="MyLab", token=TOKEN):
+    (config_dir / "contributor_config.yaml").write_text(
+        f"lab_id: {lab_id}\nhuggingface_token: {token}\n"
+    )
+
+
+def test_reports_active_config_and_masks_the_token(env, capsys):
+    _write_config(env)
+
+    assert cli.main(["show-config"]) == 0
+
+    out = capsys.readouterr().out
+    assert f"Reading:    {env / 'contributor_config.yaml'}" in out
+    assert "lab_id:     MyLab" in out
+    assert "OopsieData-Submissions/MyLab" in out
+    assert TOKEN not in out, "the token must not be printed in full by default"
+
+
+def test_show_token_reveals_it(env, capsys):
+    _write_config(env)
+
+    assert cli.main(["show-config", "--show-token"]) == 0
+    assert TOKEN in capsys.readouterr().out
+
+
+def test_env_token_is_reported_as_the_override(env, capsys, monkeypatch):
+    _write_config(env)
+    monkeypatch.setenv("HF_TOKEN", "hf_from_the_environment")
+
+    assert cli.main(["show-config", "--show-token"]) == 0
+
+    out = capsys.readouterr().out
+    assert "hf_from_the_environment" in out
+    assert "overrides the config" in out
+
+
+def test_missing_config_says_where_init_would_write(env, capsys, monkeypatch):
+    # Hide the checkout so the chain has no fallback, as for a pip install without a clone.
+    monkeypatch.setattr(paths, "_REPO_CONFIG_DIR", env / "no_such_checkout")
+
+    assert cli.main(["show-config"]) == 0
+
+    out = capsys.readouterr().out
+    assert "No config found" in out
+    assert str(env / "contributor_config.yaml") in out
+    assert "lab_id:     (not set)" in out
+
+
+def test_placeholder_config_is_reported_not_raised(env, capsys):
+    """read_contributor_config raises on this; the diagnostic command must not."""
+    _write_config(env, lab_id="your_lab_id")
+
+    assert cli.main(["show-config"]) == 0
+    assert "your_lab_id" in capsys.readouterr().out
+
+
+def test_project_local_profiles_are_listed(env, tmp_path, capsys):
+    profiles = tmp_path / "robot_profiles"
+    profiles.mkdir()
+    (profiles / "my_robot.yaml").write_text("policy_name: p\n")
+    _write_config(env)
+
+    assert cli.main(["show-config"]) == 0
+
+    out = capsys.readouterr().out
+    assert f"Reading:    {profiles}" in out
+    assert "profiles:   my_robot.yaml" in out
+    assert "1 profile\n" in out, "singular when there is exactly one"
+
+
+def test_chain_lists_each_directory_once(env, monkeypatch, tmp_path, capsys):
+    """From a checkout root, ./configs/robot_profiles and the repo's dir are the same path."""
+    checkout = tmp_path / "checkout"
+    (checkout / "configs" / paths.PROFILES_DIR_NAME).mkdir(parents=True)
+    monkeypatch.setattr(paths, "_REPO_CONFIG_DIR", checkout / "configs")
+    monkeypatch.chdir(checkout)
+
+    assert cli.main(["show-config"]) == 0
+
+    listed = capsys.readouterr().out.count(str(checkout / "configs" / paths.PROFILES_DIR_NAME))
+    assert listed == 2, f"expected one chain entry plus the 'Reading:' line, got {listed}"

oopsie_data_tools/test/test_cli_tools.py

@@ -0,0 +1,438 @@
+"""Tests for the three subcommands folded in from the old ``scripts/`` directory.
+
+``inspect``, ``restructure`` and ``submissions`` used to be standalone scripts that nothing
+tested and that a pip-installed user could not reach at all. They are subcommands now, so
+they get the same coverage as the rest of the CLI. Nothing here touches the network.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import h5py
+import pytest
+
+from oopsie_data_tools.cli import main
+from oopsie_data_tools.test.fixtures.make_valid import write_valid_episode
+from oopsie_data_tools.utils import hf_upload, restructure
+
+
+@pytest.fixture
+def info_log(caplog):
+    """caplog at INFO.
+
+    ``cli.main`` calls ``logging.basicConfig``, which is a no-op once pytest's logging
+    plugin has attached its handler, so the root logger stays at WARNING and every
+    ``logger.info`` line these commands emit as their *result* would be dropped.
+    """
+    caplog.set_level(logging.INFO)
+    return caplog
+
+
+# ── inspect ───────────────────────────────────────────────────────────────────
+
+
+def test_inspect_dumps_groups_datasets_and_attrs(tmp_path, capsys):
+    episode = write_valid_episode(tmp_path, "ep_a")
+
+    assert main(["inspect", str(episode)]) == 0
+
+    out = capsys.readouterr().out
+    assert "[group] /" in out
+    assert "observations/robot_states" in out
+    assert "[dataset]" in out
+    assert "'schema'" in out, "root attrs must be shown"
+
+
+def test_inspect_works_on_a_file_validate_would_reject(tmp_path, capsys):
+    """It is a structure dump, not a validator — that is the whole point of having it."""
+    broken = tmp_path / "broken.h5"
+    with h5py.File(broken, "w") as f:
+        f.attrs["schema"] = "something_else_entirely"
+        f.create_dataset("stray", data=[1, 2, 3])
+
+    assert main(["inspect", str(broken)]) == 0
+    assert "stray" in capsys.readouterr().out
+
+
+def test_inspect_reports_a_missing_file_rather_than_raising(tmp_path, caplog):
+    assert main(["inspect", str(tmp_path / "nope.h5")]) == 1
+    assert "Not a file" in caplog.text
+
+
+# ── restructure ───────────────────────────────────────────────────────────────
+
+
+def test_restructure_does_nothing_when_the_folder_is_small_enough(tmp_path, info_log):
+    write_valid_episode(tmp_path, "ep_a")
+
+    assert main(["restructure", "--source", str(tmp_path), "--yes"]) == 0
+
+    assert "No restructuring needed" in info_log.text
+    assert not (tmp_path.parent / f"{tmp_path.name}_restructured").exists()
+
+
+def test_restructure_copies_episodes_and_rewrites_video_paths(tmp_path, monkeypatch):
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 1)
+    source = tmp_path / "session"
+    source.mkdir()
+    write_valid_episode(source, "ep_a")
+    write_valid_episode(source, "ep_b")
+    output = tmp_path / "out"
+
+    assert main(
+        ["restructure", "--source", str(source), "--output", str(output), "--yes"]
+    ) == 0
+
+    # Source is untouched — this command must never be the thing that loses data.
+    assert (source / "ep_a.h5").exists()
+    assert (source / "ep_a_front.mp4").exists()
+
+    copies = sorted(output.rglob("*.h5"))
+    assert [p.name for p in copies] == ["ep_a.h5", "ep_b.h5"]
+    for h5_path in copies:
+        with h5py.File(h5_path, "r") as f:
+            stored = f["observations/video_paths/front"][()]
+        rel = stored.decode() if isinstance(stored, bytes) else stored
+        assert "/" not in rel, "videos are copied flat next to their episode"
+        assert (h5_path.parent / rel).is_file(), "the rewritten path must resolve"
+
+
+def test_unique_video_dest_separates_two_videos_that_want_the_same_name(tmp_path):
+    """Two distinct videos claiming one name must not collapse onto it.
+
+    This used to return the colliding name regardless, so the copy silently overwrote the
+    first episode's video. Exercised directly: ``restructure()`` collects HDF5 files from
+    the source root only, where stems are unique by construction, so this branch is
+    unreachable through the command and would otherwise never be tested.
+    """
+    used: dict[str, Path] = {}
+    first = tmp_path / "one" / "ep_front.mp4"
+    second = tmp_path / "two" / "ep_front.mp4"
+
+    a = restructure._unique_video_dest(first, "front", "ep", used)
+    b = restructure._unique_video_dest(second, "front", "ep", used)
+
+    assert a == "ep_front.mp4"
+    assert b != a, "a second, different video must not take the first one's name"
+    # Idempotent: re-asking for a video already registered returns the same name, so a
+    # caller may ask more than once per file without inventing new copies.
+    assert restructure._unique_video_dest(first, "front", "ep", used) == a
+
+
+def test_restructure_copies_a_shared_video_once(tmp_path, monkeypatch):
+    """Two episodes referencing one video share the copy rather than duplicating it."""
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 1)
+    source = tmp_path / "session"
+    source.mkdir()
+    write_valid_episode(source, "ep_a")
+    write_valid_episode(source, "ep_b")
+    # Point ep_b at ep_a's video, the way a re-annotated episode would.
+    with h5py.File(source / "ep_b.h5", "r+") as f:
+        del f["observations/video_paths/front"]
+        f["observations/video_paths"].create_dataset(
+            "front", data="ep_a_front.mp4", dtype=h5py.string_dtype(encoding="utf-8")
+        )
+    output = tmp_path / "out"
+
+    assert main(
+        ["restructure", "--source", str(source), "--output", str(output), "--yes"]
+    ) == 0
+
+    for h5_path in sorted(output.rglob("*.h5")):
+        with h5py.File(h5_path, "r") as f:
+            stored = f["observations/video_paths/front"][()]
+        rel = stored.decode() if isinstance(stored, bytes) else stored
+        assert (h5_path.parent / rel).is_file(), "every rewritten path must resolve"
+
+
+def test_restructure_splits_a_nested_oversized_directory(tmp_path, monkeypatch, info_log):
+    """Detection is recursive, so repair must be too.
+
+    This used to detect the nested directory, restructure the *root* instead, and report
+    success — leaving the upload just as blocked as before.
+    """
+    # Limit 2 puts the root exactly at the limit (one .h5 + one .mp4) while the nested
+    # directory is over it. This is the shape that used to misfire: the old code saw an
+    # oversized directory, then acted on the root because that is where it looked for
+    # episodes.
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 2)
+    source = tmp_path / "session"
+    nested = source / "day_two"
+    nested.mkdir(parents=True)
+    write_valid_episode(source, "ep_root")
+    write_valid_episode(nested, "ep_nested_a")
+    write_valid_episode(nested, "ep_nested_b")
+    output = tmp_path / "out"
+
+    assert restructure.oversized_dirs(source) == [(nested, 4)], "only the nested dir is over"
+
+    assert main(
+        ["restructure", "--source", str(source), "--output", str(output), "--yes"]
+    ) == 0
+
+    # The nested directory keeps its position in the tree and gains numbered subfolders.
+    nested_out = output / "day_two"
+    assert nested_out.is_dir()
+    assert sorted(p.name for p in nested_out.rglob("*.h5")) == [
+        "ep_nested_a.h5",
+        "ep_nested_b.h5",
+    ]
+    assert [p for p in nested_out.iterdir() if p.is_dir()], "the oversized dir is batched"
+
+    # The root was within the limit, so it is copied through rather than reorganised.
+    assert (output / "ep_root.h5").is_file(), "an in-limit root must not be restructured"
+
+    # Every episode in the output still resolves its own video.
+    for h5_path in output.rglob("*.h5"):
+        with h5py.File(h5_path, "r") as f:
+            stored = f["observations/video_paths/front"][()]
+        rel = stored.decode() if isinstance(stored, bytes) else stored
+        assert (h5_path.parent / rel).is_file(), f"{h5_path} lost its video"
+
+    # Nothing is left behind: the root episode is in the output exactly once.
+    assert len(list(output.rglob("ep_root.h5"))) == 1
+
+
+def test_restructure_copies_untouched_directories_through(tmp_path, monkeypatch):
+    """The output is a full copy, not just the episodes that needed splitting."""
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 2)
+    source = tmp_path / "session"
+    big = source / "big"
+    big.mkdir(parents=True)
+    write_valid_episode(big, "ep_a")
+    write_valid_episode(big, "ep_b")  # 4 files > limit of 2
+    small = source / "small"
+    small.mkdir()
+    write_valid_episode(small, "ep_small")
+    (source / "NOTES.md").write_text("keep me", encoding="utf-8")
+    output = tmp_path / "out"
+
+    assert main(
+        ["restructure", "--source", str(source), "--output", str(output), "--yes"]
+    ) == 0
+
+    assert (output / "NOTES.md").read_text(encoding="utf-8") == "keep me"
+    assert (output / "small" / "ep_small.h5").is_file(), "small dirs pass through as-is"
+    assert (output / "small" / "ep_small_front.mp4").is_file()
+    assert not list((output / "small").glob("0*")), "an in-limit dir must not be batched"
+    assert list((output / "big").glob("*/ep_a.h5")), "the oversized dir is batched"
+
+
+def test_restructure_refuses_an_output_inside_the_source(tmp_path, monkeypatch, caplog):
+    """Otherwise the pass-through copy would walk into its own output."""
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 1)
+    source = tmp_path / "session"
+    source.mkdir()
+    write_valid_episode(source, "ep_a")
+
+    assert main(
+        ["restructure", "--source", str(source), "--output", str(source / "out"), "--yes"]
+    ) == 1
+    assert "must not be inside the source" in caplog.text
+
+
+def test_restructure_reports_an_oversized_dir_it_cannot_split(tmp_path, monkeypatch, caplog):
+    """A videos-only folder cannot be batched by episode; say so rather than claiming success."""
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 1)
+    source = tmp_path / "session"
+    source.mkdir()
+    for i in range(3):
+        (source / f"clip{i}.mp4").write_bytes(b"x")
+
+    assert main(["restructure", "--source", str(source), "--yes"]) == 1
+    assert "nothing to split" in caplog.text
+
+
+def test_restructure_rejects_a_source_that_is_not_a_directory(tmp_path, caplog):
+    episode = write_valid_episode(tmp_path, "ep_a")
+    assert main(["restructure", "--source", str(episode), "--yes"]) == 1
+    assert "not a directory" in caplog.text.lower()
+
+
+def test_restructure_without_yes_aborts_on_anything_but_yes(tmp_path, monkeypatch, info_log):
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 0)
+    write_valid_episode(tmp_path, "ep_a")
+    monkeypatch.setattr("builtins.input", lambda _prompt: "y")
+
+    assert main(["restructure", "--source", str(tmp_path)]) == 0
+
+    assert "Aborted" in info_log.text
+    assert not (tmp_path.parent / f"{tmp_path.name}_restructured").exists()
+
+
+# ── upload --with-restructure ─────────────────────────────────────────────────
+
+
+def _oversized_session(tmp_path, monkeypatch, n=3):
+    """A session directory that trips the folder-size precheck.
+
+    BATCH_SIZE is scaled down alongside FILE_LIMIT. One batch holds BATCH_SIZE episodes
+    plus their videos, so a batch only ends up under the limit if the two are set in a
+    realistic ratio — at the shipped 500 / 10,000 it takes about twenty cameras per episode
+    to overflow a batch.
+    """
+    monkeypatch.setattr(restructure, "FILE_LIMIT", 2)
+    monkeypatch.setattr(restructure, "BATCH_SIZE", 1)
+    monkeypatch.setattr(hf_upload, "FILE_LIMIT", 2)
+    source = tmp_path / "samples"
+    source.mkdir()
+    for i in range(n):
+        write_valid_episode(source, f"ep_{i}")
+    return source
+
+
+def test_upload_aborts_on_an_oversized_folder_without_the_flag(tmp_path, monkeypatch, caplog):
+    source = _oversized_session(tmp_path, monkeypatch)
+
+    # No --skip-upload: the precheck only runs when something would actually be uploaded.
+    # It returns non-zero before any network call is reached.
+    assert main(["upload", "--path", str(source)]) == 1
+
+    assert "exceed" in caplog.text
+    assert "--with-restructure" in caplog.text, "point at the one-step fix"
+    assert not (tmp_path / "samples_restructured").exists()
+
+
+def test_upload_with_restructure_does_not_tell_you_to_restructure_by_hand(
+    tmp_path, monkeypatch, caplog
+):
+    """The manual instruction contradicts what the next line does."""
+    source = _oversized_session(tmp_path, monkeypatch)
+
+    assert main(["upload", "--path", str(source), "--with-restructure", "--skip-upload"]) == 0
+
+    assert "exceed" in caplog.text, "still say which directories were over"
+    assert "oopsie-data restructure --source" not in caplog.text
+
+
+def test_upload_with_restructure_uploads_the_restructured_copy(tmp_path, monkeypatch, info_log):
+    source = _oversized_session(tmp_path, monkeypatch)
+    uploaded = {}
+    monkeypatch.setattr(
+        "oopsie_data_tools.utils.hf_upload.resolve_hf_target", lambda: ("tok", "repo/x")
+    )
+    monkeypatch.setattr("oopsie_data_tools.utils.hf_upload.hf_login", lambda token: "someone")
+    monkeypatch.setattr("oopsie_data_tools.utils.hf_upload.ensure_repo", lambda api, repo: None)
+    monkeypatch.setattr(
+        "oopsie_data_tools.utils.hf_upload.upload_dataset",
+        lambda api, repo, d: uploaded.update(dir=d),
+    )
+    monkeypatch.setattr("huggingface_hub.HfApi", lambda token=None: object())
+
+    assert main(["upload", "--path", str(source), "--with-restructure"]) == 0
+
+    output = tmp_path / "samples_restructured"
+    assert uploaded["dir"] == str(output), "the copy is uploaded, not the original"
+    # The original is untouched, which is the whole contract of restructure.
+    assert sorted(p.name for p in source.glob("*.h5")) == ["ep_0.h5", "ep_1.h5", "ep_2.h5"]
+    assert list(output.glob("*/ep_0.h5")), "the copy is batched into subfolders"
+
+
+def test_upload_with_restructure_validates_the_copy_not_the_original(tmp_path, monkeypatch):
+    """Video paths are rewritten by the split, so validation must run on the copy."""
+    source = _oversized_session(tmp_path, monkeypatch)
+    validated = {}
+
+    def fake_validation(path, episode_id, log_path):
+        validated["path"] = path
+        return 0
+
+    monkeypatch.setattr("oopsie_data_tools.utils.hf_upload.run_validation", fake_validation)
+
+    assert main(["upload", "--path", str(source), "--with-restructure", "--skip-upload"]) == 0
+    assert validated["path"] == str(tmp_path / "samples_restructured")
+
+
+def test_upload_with_restructure_is_a_no_op_when_the_folder_is_fine(tmp_path, monkeypatch):
+    source = tmp_path / "samples"
+    source.mkdir()
+    write_valid_episode(source, "ep_a")
+
+    assert main(["upload", "--path", str(source), "--with-restructure", "--skip-upload"]) == 0
+    assert not (tmp_path / "samples_restructured").exists()
+
+
+def test_upload_with_restructure_aborts_if_the_layout_is_still_oversized(
+    tmp_path, monkeypatch, caplog
+):
+    """A videos-only directory cannot be split by episode; do not upload it anyway."""
+    source = _oversized_session(tmp_path, monkeypatch)
+    clips = source / "clips"
+    clips.mkdir()
+    for i in range(5):
+        (clips / f"c{i}.mp4").write_bytes(b"x")
+
+    assert main(["upload", "--path", str(source), "--with-restructure", "--skip-upload"]) == 1
+    assert "still over the file limit" in caplog.text
+
+
+# ── submissions ───────────────────────────────────────────────────────────────
+
+
+class _FakeApi:
+    def __init__(self, files=None):
+        self.files = files
+        self.token = None
+
+    def repo_info(self, repo_id, repo_type):
+        if self.files is None:
+            raise RuntimeError("404")
+        return {"id": repo_id}
+
+    def list_repo_files(self, repo_id, repo_type):
+        return self.files
+
+
+@pytest.fixture
+def fake_hf(monkeypatch):
+    """Patch HfApi at its import site inside query_submissions."""
+
+    def install(files):
+        api = _FakeApi(files)
+        monkeypatch.setattr("huggingface_hub.HfApi", lambda token=None: api)
+        return api
+
+    return install
+
+
+def test_submissions_counts_episodes_videos_and_folders(fake_hf, info_log):
+    fake_hf(["000/a.h5", "000/a_front.mp4", "500/b.hdf5", "README.md"])
+
+    assert main(["submissions"]) == 0
+
+    assert "Episodes (.h5): 2" in info_log.text
+    assert "Videos (.mp4):  1" in info_log.text
+    assert "Total files:    4" in info_log.text
+    assert "000" in info_log.text and "500" in info_log.text
+
+
+def test_submissions_treats_a_missing_repo_as_success(fake_hf, info_log):
+    """The repo is created on first upload, so 'not there yet' is not a failure."""
+    fake_hf(None)
+
+    assert main(["submissions"]) == 0
+    assert "created automatically on your first successful upload" in info_log.text
+
+
+def test_submissions_lab_id_flag_overrides_the_config(fake_hf, info_log):
+    fake_hf([])
+
+    assert main(["submissions", "--lab-id", "SomeOtherLab"]) == 0
+    assert "OopsieData-Submissions/SomeOtherLab" in info_log.text
+
+
+def test_submissions_prefers_the_env_token(monkeypatch):
+    """$HF_TOKEN overrides the config token, matching upload's precedence."""
+    seen = {}
+
+    def fake_api(token=None):
+        seen["token"] = token
+        return _FakeApi([])
+
+    monkeypatch.setenv("HF_TOKEN", "env-token")
+    monkeypatch.setattr("huggingface_hub.HfApi", fake_api)
+
+    assert hf_upload.query_submissions() == 0
+    assert seen["token"] == "env-token"

oopsie_data_tools/test/test_contributor_config.py

@@ -0,0 +1,38 @@
+"""Tests for the shared contributor-config reader (issue #20)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from oopsie_data_tools.utils.contributor_config import read_contributor_config
+
+
+def _write(tmp_path: Path, content: str) -> Path:
+    path = tmp_path / "contributor_config.yaml"
+    path.write_text(content)
+    return path
+
+
+def test_valid_config_returns_lab_and_token(tmp_path: Path) -> None:
+    path = _write(tmp_path, "lab_id: MyLab\nhuggingface_token: hf_abc\n")
+    assert read_contributor_config(path) == ("MyLab", "hf_abc")
+
+
+def test_blank_lab_id_gives_clear_error(tmp_path: Path) -> None:
+    # `lab_id:` parses to None; must not crash with `None.strip()` (the original #20 bug).
+    path = _write(tmp_path, "lab_id:\nhuggingface_token:\n")
+    with pytest.raises(RuntimeError, match="lab_id is not set"):
+        read_contributor_config(path)
+
+
+def test_placeholder_lab_id_rejected(tmp_path: Path) -> None:
+    path = _write(tmp_path, "lab_id: your_lab_id\n")
+    with pytest.raises(RuntimeError, match="placeholder"):
+        read_contributor_config(path)
+
+
+def test_missing_file_gives_clear_error(tmp_path: Path) -> None:
+    with pytest.raises(RuntimeError, match="not found"):
+        read_contributor_config(tmp_path / "does_not_exist.yaml")

oopsie_data_tools/test/test_conversion_utils_annotations.py

@@ -0,0 +1,75 @@
+"""``write_episode_annotations`` — the public API third-party converters write against.
+
+It is the one annotation writer that is not driven by the annotation tool, so it has its
+own argument shape and its own consistency rules. The rules changed in v2: the failure
+trio is no longer all-or-nothing, and ``outcome`` joined the numeric ``success``.
+"""
+
+from __future__ import annotations
+
+import json
+
+import h5py
+import pytest
+
+from oopsie_data_tools.utils.conversion_utils import write_episode_annotations
+
+
+def _write(tmp_path, **kwargs) -> dict:
+    path = tmp_path / "ep.h5"
+    with h5py.File(path, "w") as f:
+        write_episode_annotations(f, annotator_name="conv", **kwargs)
+    with h5py.File(path, "r") as f:
+        return dict(f["episode_annotations"]["conv"].attrs)
+
+
+def test_a_partial_taxonomy_is_accepted(tmp_path):
+    """v1 raised here; v2 lets a converter record whatever it actually knows."""
+    attrs = _write(tmp_path, success=0.0, severity="medium")
+
+    assert json.loads(attrs["taxonomy"])["severity"] == "medium"
+    assert attrs["episode_description"] == ""
+
+
+def test_outcome_defaults_to_the_coarse_reading_of_success(tmp_path):
+    assert json.loads(_write(tmp_path, success=1.0)["taxonomy"])["outcome"] == "success"
+    assert json.loads(_write(tmp_path, success=0.0)["taxonomy"])["outcome"] == "failure"
+
+
+def test_a_qualified_success_needs_an_explicit_outcome(tmp_path):
+    """The float alone cannot express the two qualified successes."""
+    attrs = _write(
+        tmp_path,
+        success=1.0,
+        outcome="success_side_effect",
+        side_effect_category=["collision"],
+        severity="low",
+    )
+    taxonomy = json.loads(attrs["taxonomy"])
+
+    assert taxonomy["outcome"] == "success_side_effect"
+    assert taxonomy["side_effect_category"] == ["collision"]
+    assert float(attrs["success"]) == 1.0
+
+
+def test_a_fractional_success_survives(tmp_path):
+    """The exact float is authoritative for magnitude, the slug only for the branch."""
+    attrs = _write(tmp_path, success=0.75, outcome="success_suboptimal")
+
+    assert float(attrs["success"]) == 0.75
+    assert json.loads(attrs["taxonomy"])["outcome"] == "success_suboptimal"
+
+
+def test_an_outcome_contradicting_the_success_float_is_rejected(tmp_path):
+    with pytest.raises(ValueError, match="disagrees with success"):
+        _write(tmp_path, success=1.0, outcome="failure")
+
+
+def test_an_unrecognized_outcome_is_rejected(tmp_path):
+    with pytest.raises(ValueError, match="outcome must be one of"):
+        _write(tmp_path, success=0.0, outcome="sort_of_worked")
+
+
+def test_success_out_of_range_is_rejected(tmp_path):
+    with pytest.raises(ValueError, match=r"success must be in \[0.0, 1.0\]"):
+        _write(tmp_path, success=1.5)