Stage, Back Up, Swap Whole

        target.parent.mkdir(parents=True, exist_ok=True)
        staging = target.parent / f".avatars-stage-{uuid4().hex}"
        staging.mkdir()
        # Legacy guest defaults live directly in their soul root. Preserve
        # unrelated presets/On Air directories when activating that layout.
        if target == avatar_root(entry) and target.exists():
            for child in target.iterdir():
                if child.is_dir():
                    shutil.copytree(child, staging / child.name)
                elif child.suffix.lower() not in EXTENSIONS and child.name != "avatar-lineage.json":
                    shutil.copy2(child, staging / child.name)
        for frame, source in checked.items():
            shutil.copy2(source, staging / f"{frame}{source.suffix.lower()}")
            if digest(staging / f"{frame}{source.suffix.lower()}") != files[frame]["sha256"]:
                raise ValueError("Staged original verification failed")
        expected = revision(frame_files(staging))
        # Provenance travels with the set for public export policy, but is
        # deliberately not an image and never part of frame discovery.
        manifest["revision"] = expected
        atomic_write_text(staging / "avatar-lineage.json", json.dumps(manifest, indent=2))
        displaced = target.parent / f".avatars-old-{uuid4().hex}"
        receipt = {"request_id": request_id, "fingerprint": fingerprint, "status": "prepared", "soul_pk": body["soul_pk"], "channel": body["channel"], "name": body["name"], "previous_revision": previous, "revision": expected, "backup": str(backup), "target": str(target), "staging": str(staging), "displaced": str(displaced)}
        atomic_write_text(receipt_path, json.dumps(receipt, indent=2))
        return finish_publication(receipt, receipt_path)

def finish_publication(receipt: dict, receipt_path: Path) -> dict:
    """Resume a prepared activation after any crash between directory renames."""
    if receipt.get("mode") == "adopt":
        target, backup = Path(receipt["target"]), Path(receipt["backup"])
        if revision(frame_files(target)) != receipt["revision"]:
            raise ValueError("The legacy copies changed before adoption completed")
        atomic_write_text(target / "avatar-lineage.json", json.dumps(receipt["manifest"], indent=2))
        receipt["status"] = "applied"
        atomic_write_text(receipt_path, json.dumps(receipt, indent=2))
        atomic_write_text(backup / "receipt.json", json.dumps(receipt, indent=2))
        return receipt
    target, staging, displaced, backup = (Path(receipt[key]) for key in ("target", "staging", "displaced", "backup"))
    current = revision(frame_files(target)) if target.exists() else None
    if current != receipt["revision"]:
        if current is not None and current != receipt["previous_revision"]:
            raise ValueError("The interrupted publication conflicts with a newer live set")
        if not staging.exists() or revision(frame_files(staging)) != receipt["revision"]:
            if not target.exists() and displaced.exists():
                os.replace(displaced, target)
            raise ValueError("The prepared set is unavailable; the previous set was preserved")
        if target.exists():
            os.replace(target, displaced)
        os.replace(staging, target)
    if revision(frame_files(target)) != receipt["revision"]:
        raise ValueError("Installed image verification failed")
    receipt["status"] = "applied"
    atomic_write_text(receipt_path, json.dumps(receipt, indent=2))
    atomic_write_text(backup / "receipt.json", json.dumps(receipt, indent=2))
    if displaced.exists():
        shutil.rmtree(displaced)  # the verified previous tree remains in backup
    return receipt

def test_publication_preserves_backup_native_bytes_and_idempotency(authority):
    body, target, entries = authority
    receipt = studio.publish(body)
    assert (target / "default.png").read_bytes() == b"native candidate bytes"
    assert not (target / "default.jpg").exists()
    assert (Path(receipt["backup"]) / "previous/default.jpg").read_bytes() == b"original image bytes"
    assert studio.publish(body) == receipt
    manifest = json.loads((target / "avatar-lineage.json").read_text())
    assert manifest["owner"] == "cwkAvatars"
    assert manifest["role"] == "published-copy"
    assert manifest["collection_id"] == "collection"
    assert "path" not in manifest["frames"]["default"]
    with pytest.raises(ValueError):
        studio.publish({**body, "expected_revision": "different"})