pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/dev_bindings.py

@@ -0,0 +1,916 @@
+from __future__ import annotations
+
+import os
+import tomllib
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from pz_core.authoring.dev_manifest import (
+    DevBinding,
+    DevManifest,
+    DevRepo,
+    validate_dev_manifest,
+)
+from pz_core.runtime.errors import PzError
+
+
+BINDING_CONFLICT_CODE = "PZ_DEV_BINDING_CONFLICT"
+BINDING_OVERLAP_CODE = "PZ_DEV_BINDING_OVERLAP"
+BINDING_SOURCE_CONFLICT_CODE = "PZ_DEV_BINDING_SOURCE_CONFLICT"
+BINDING_INVALID_PROJECTION_CODE = "PZ_DEV_BINDING_INVALID_PROJECTION"
+_OWNER = "pz_core.authoring.dev_bindings"
+_RESOLUTION_ERRORS = (OSError, RuntimeError)
+
+
+@dataclass(frozen=True, slots=True)
+class LinkMutation:
+    final_path: Path
+    staged_path: Path
+    relative_target: str
+    previous_target: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class LinkRemoval:
+    final_path: Path
+    previous_target: str
+    expected_target: Path
+
+
+@dataclass(frozen=True, slots=True)
+class _Projection:
+    key: str
+    binding: DevBinding
+    final_path: Path
+    target_path: Path
+    target_realpath: Path
+    base_realpath: Path
+    relative_target: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Preflight:
+    before: Mapping[Path, _Projection]
+    after: Mapping[Path, _Projection]
+
+
+def _error(
+    code: str, message: str, *, action: str, detail: str | None = None
+) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="dev",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def _lexists(path: Path) -> bool:
+    return os.path.lexists(path)
+
+
+def _paths_overlap(first: Path, second: Path) -> bool:
+    return first == second or first in second.parents or second in first.parents
+
+
+def _join_posix(base: Path, child: PurePosixPath) -> Path:
+    if child == PurePosixPath("."):
+        return base
+    return base / Path(*child.parts)
+
+
+def _declared_source_path(
+    project_dir: Path,
+    binding: DevBinding,
+    repos: Mapping[str, DevRepo],
+) -> Path | None:
+    if binding.source_kind == "git":
+        if not binding.repo_key:
+            return None
+        repo = repos.get(binding.repo_key)
+        if repo is None:
+            return None
+        base = project_dir / Path(*repo.checkout.parts)
+    elif binding.source_kind == "link":
+        base = Path(binding.source)
+    else:
+        return None
+    return _join_posix(base, binding.subpath).resolve(strict=False)
+
+
+def _check_granularity_overlap(
+    project_dir: Path,
+    before: DevManifest,
+    after: DevManifest,
+) -> None:
+    desired_bindings = sorted(after.bindings.items())
+    for index, (first_key, first) in enumerate(desired_bindings):
+        for second_key, second in desired_bindings[index + 1 :]:
+            if first.kind == second.kind:
+                continue
+            first_source = _declared_source_path(project_dir, first, after.repos)
+            second_source = _declared_source_path(project_dir, second, after.repos)
+            if (
+                first_source is None
+                or second_source is None
+                or not _paths_overlap(first_source, second_source)
+            ):
+                continue
+            raise _error(
+                BINDING_OVERLAP_CODE,
+                "directory and app bindings cannot expose overlapping sources",
+                action="plan_binding_projection",
+                detail=(
+                    f"desired={first_key}:{first_source}; "
+                    f"desired={second_key}:{second_source}"
+                ),
+            )
+
+    for before_key, existing in sorted(before.bindings.items()):
+        for after_key, desired in desired_bindings:
+            if existing.kind == desired.kind:
+                continue
+            existing_source = _declared_source_path(project_dir, existing, before.repos)
+            desired_source = _declared_source_path(project_dir, desired, after.repos)
+            if (
+                existing_source is None
+                or desired_source is None
+                or not _paths_overlap(existing_source, desired_source)
+            ):
+                continue
+            raise _error(
+                BINDING_OVERLAP_CODE,
+                "directory and app bindings cannot expose overlapping sources",
+                action="plan_binding_projection",
+                detail=(
+                    f"before={before_key}:{existing_source}; "
+                    f"after={after_key}:{desired_source}"
+                ),
+            )
+
+
+def _projection(
+    project_dir: Path,
+    key: str,
+    binding: DevBinding,
+    repos: Mapping[str, DevRepo],
+    *,
+    action: str,
+) -> _Projection:
+    final_path = project_dir / Path(*binding.link.parts)
+    try:
+        parent_realpath = final_path.parent.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding parent does not exist: {final_path.parent}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if not final_path.parent.is_dir() or not parent_realpath.is_relative_to(
+        project_dir
+    ):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding parent escapes the project or is not a directory: {final_path.parent}",
+            action=action,
+        )
+
+    if binding.source_kind == "git":
+        assert binding.repo_key is not None
+        repo = repos[binding.repo_key]
+        base = project_dir / Path(*repo.checkout.parts)
+    else:
+        base = Path(binding.source)
+    target_path = _join_posix(base, binding.subpath)
+    try:
+        base_realpath = base.resolve(strict=True)
+        target_realpath = target_path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding source target is missing or broken: {target_path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if not base_realpath.is_dir() or not target_realpath.is_dir():
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding source target must be a directory: {target_path}",
+            action=action,
+        )
+    if not target_realpath.is_relative_to(base_realpath):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding source target escapes its declared source root: {target_path}",
+            action=action,
+            detail=f"source_root={base_realpath}; resolved_target={target_realpath}",
+        )
+
+    relative_target = Path(
+        os.path.relpath(target_path, start=final_path.parent)
+    ).as_posix()
+    if Path(relative_target).is_absolute() or "\\" in relative_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding target is not a POSIX relative path: {relative_target}",
+            action=action,
+        )
+    return _Projection(
+        key=key,
+        binding=binding,
+        final_path=final_path,
+        target_path=target_path,
+        target_realpath=target_realpath,
+        base_realpath=base_realpath,
+        relative_target=relative_target,
+    )
+
+
+def _projections(
+    project_dir: Path,
+    manifest: DevManifest,
+    *,
+    action: str,
+) -> dict[Path, _Projection]:
+    result: dict[Path, _Projection] = {}
+    for key, binding in sorted(manifest.bindings.items()):
+        item = _projection(
+            project_dir,
+            key,
+            binding,
+            manifest.repos,
+            action=action,
+        )
+        result[item.final_path] = item
+    return result
+
+
+def _verify_exact_link(
+    projection: _Projection,
+    *,
+    action: str,
+    code: str = BINDING_INVALID_PROJECTION_CODE,
+) -> str:
+    path = projection.final_path
+    if not path.is_symlink():
+        state = "missing" if not _lexists(path) else "not a symbolic link"
+        raise _error(
+            code,
+            f"managed binding is {state}: {path}",
+            action=action,
+        )
+    try:
+        stored_target = os.readlink(path)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            code,
+            f"cannot read managed binding: {path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if (
+        Path(stored_target).is_absolute()
+        or "\\" in stored_target
+        or stored_target != projection.relative_target
+    ):
+        raise _error(
+            code,
+            f"managed binding has an unexpected stored target: {path}",
+            action=action,
+            detail=(
+                f"expected={projection.relative_target!r}; actual={stored_target!r}"
+            ),
+        )
+    try:
+        actual_realpath = path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            code,
+            f"managed binding is broken: {path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if actual_realpath != projection.target_realpath:
+        raise _error(
+            code,
+            f"managed binding resolves to the wrong source: {path}",
+            action=action,
+            detail=(f"expected={projection.target_realpath}; actual={actual_realpath}"),
+        )
+    return stored_target
+
+
+def _distribution_name(pyproject: Path) -> str | None:
+    try:
+        payload = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return None
+    name = project.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    return name.strip().replace("-", "_")
+
+
+def _record_tree_distributions(
+    source_root: Path,
+    distributions: dict[str, set[Path]],
+) -> None:
+    for raw_root, dirnames, filenames in os.walk(source_root, followlinks=False):
+        dirnames[:] = [name for name in dirnames if not name.startswith(".")]
+        if "pyproject.toml" not in filenames:
+            continue
+        root = Path(raw_root)
+        distribution = _distribution_name(root / "pyproject.toml")
+        if distribution is not None:
+            distributions.setdefault(distribution, set()).add(root.resolve(strict=True))
+
+
+def _visible_sources(
+    project_dir: Path,
+    managed_paths: set[Path],
+) -> tuple[dict[str, set[Path]], set[Path]]:
+    apps_root = project_dir / "apps"
+    distributions: dict[str, set[Path]] = {}
+    link_targets: set[Path] = set()
+    if not apps_root.is_dir():
+        return distributions, link_targets
+
+    for raw_root, dirnames, filenames in os.walk(apps_root, followlinks=False):
+        root = Path(raw_root)
+        if root == apps_root / ".sources" or (apps_root / ".sources") in root.parents:
+            dirnames[:] = []
+            continue
+        if root in managed_paths or any(
+            managed in root.parents for managed in managed_paths
+        ):
+            dirnames[:] = []
+            continue
+
+        retained: list[str] = []
+        for dirname in dirnames:
+            child = root / dirname
+            if dirname.startswith(".") or child in managed_paths:
+                continue
+            if child.is_symlink():
+                try:
+                    target = child.resolve(strict=True)
+                except _RESOLUTION_ERRORS:
+                    pass
+                else:
+                    link_targets.add(target)
+                    if target.is_dir():
+                        _record_tree_distributions(target, distributions)
+                continue
+            retained.append(dirname)
+        dirnames[:] = retained
+
+        if "pyproject.toml" not in filenames:
+            continue
+        distribution = _distribution_name(root / "pyproject.toml")
+        if distribution is None:
+            continue
+        distributions.setdefault(distribution, set()).add(root.resolve(strict=True))
+    return distributions, link_targets
+
+
+def _source_identities(projection: _Projection) -> tuple[tuple[str, Path], ...]:
+    if projection.binding.kind == "app":
+        return ((projection.key, projection.target_realpath),)
+    distributions: dict[str, set[Path]] = {}
+    _record_tree_distributions(projection.target_realpath, distributions)
+    return tuple(
+        (app_id, root)
+        for app_id, roots in sorted(distributions.items())
+        for root in sorted(roots)
+    )
+
+
+def _check_source_conflicts(
+    project_dir: Path,
+    before: Mapping[Path, _Projection],
+    after: Mapping[Path, _Projection],
+    *,
+    action: str,
+) -> None:
+    distributions, link_targets = _visible_sources(project_dir, set(before))
+    for projection in after.values():
+        for link_target in link_targets:
+            if _paths_overlap(link_target, projection.target_realpath):
+                raise _error(
+                    BINDING_SOURCE_CONFLICT_CODE,
+                    f"binding source is already exposed by another link: {projection.key}",
+                    action=action,
+                    detail=(
+                        f"source={projection.target_realpath}; "
+                        f"existing_link_target={link_target}"
+                    ),
+                )
+        for app_id, expected_root in _source_identities(projection):
+            existing_roots = distributions.get(app_id, set())
+            if not existing_roots:
+                continue
+            raise _error(
+                BINDING_SOURCE_CONFLICT_CODE,
+                f"app id is already exposed by a local source: {app_id}",
+                action=action,
+                detail=(
+                    f"expected={expected_root}; "
+                    f"existing={', '.join(str(path) for path in sorted(existing_roots))}"
+                ),
+            )
+
+
+def _preflight(
+    project_dir: Path,
+    before: DevManifest,
+    after: DevManifest,
+    *,
+    action: str,
+) -> _Preflight:
+    project_root = project_dir.expanduser().resolve(strict=False)
+    try:
+        validate_dev_manifest(project_root, before)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "current manifest resolves through a broken source path",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    try:
+        _check_granularity_overlap(project_root, before, after)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "binding overlap check encountered a broken source path",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    try:
+        validate_dev_manifest(project_root, after)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "desired manifest resolves through a broken source path",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    before_projections = _projections(project_root, before, action=action)
+    after_projections = _projections(project_root, after, action=action)
+
+    for projection in before_projections.values():
+        _verify_exact_link(projection, action=action)
+
+    for final_path, projection in after_projections.items():
+        existing = before_projections.get(final_path)
+        if existing is not None:
+            continue
+        if _lexists(final_path):
+            raise _error(
+                BINDING_CONFLICT_CODE,
+                f"binding destination is occupied by an unmanaged path: {final_path}",
+                action=action,
+                detail=f"desired_source={projection.target_realpath}",
+            )
+
+    _check_source_conflicts(
+        project_root,
+        before_projections,
+        after_projections,
+        action=action,
+    )
+    return _Preflight(before=before_projections, after=after_projections)
+
+
+def _staged_path(final_path: Path) -> Path:
+    while True:
+        candidate = final_path.with_name(
+            f".{final_path.name}.pz-link-{uuid.uuid4().hex}"
+        )
+        if not _lexists(candidate):
+            return candidate
+
+
+def plan_binding_projection(
+    project_dir: Path,
+    before: DevManifest,
+    after: DevManifest,
+) -> tuple[LinkMutation, ...]:
+    checked = _preflight(
+        project_dir,
+        before,
+        after,
+        action="plan_binding_projection",
+    )
+    mutations: list[LinkMutation] = []
+    for final_path, desired in sorted(checked.after.items()):
+        previous = checked.before.get(final_path)
+        if previous is not None:
+            previous_target = previous.relative_target
+            if (
+                previous.relative_target == desired.relative_target
+                and previous.target_realpath == desired.target_realpath
+            ):
+                continue
+        else:
+            previous_target = None
+        mutations.append(
+            LinkMutation(
+                final_path=final_path,
+                staged_path=_staged_path(final_path),
+                relative_target=desired.relative_target,
+                previous_target=previous_target,
+            )
+        )
+    return tuple(mutations)
+
+
+def plan_binding_removals(
+    project_dir: Path,
+    before: DevManifest,
+    after: DevManifest,
+) -> tuple[LinkRemoval, ...]:
+    checked = _preflight(
+        project_dir,
+        before,
+        after,
+        action="plan_binding_removals",
+    )
+    removals: list[LinkRemoval] = []
+    for final_path, existing in sorted(checked.before.items()):
+        if final_path in checked.after:
+            continue
+        removals.append(
+            LinkRemoval(
+                final_path=final_path,
+                previous_target=existing.relative_target,
+                expected_target=existing.target_realpath,
+            )
+        )
+    return tuple(removals)
+
+
+def _verify_mutation_before_stage(mutation: LinkMutation) -> None:
+    if mutation.staged_path.parent != mutation.final_path.parent:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "staged binding must be a sibling of its final path",
+            action="stage_binding_projection",
+            detail=f"final={mutation.final_path}; staged={mutation.staged_path}",
+        )
+    if Path(mutation.relative_target).is_absolute() or "\\" in mutation.relative_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "staged binding target must be a POSIX relative path",
+            action="stage_binding_projection",
+            detail=mutation.relative_target,
+        )
+    if _lexists(mutation.staged_path):
+        raise _error(
+            BINDING_CONFLICT_CODE,
+            f"staged binding path is occupied: {mutation.staged_path}",
+            action="stage_binding_projection",
+        )
+    if mutation.previous_target is None:
+        if _lexists(mutation.final_path):
+            raise _error(
+                BINDING_CONFLICT_CODE,
+                f"binding destination became occupied: {mutation.final_path}",
+                action="stage_binding_projection",
+            )
+    elif (
+        not mutation.final_path.is_symlink()
+        or os.readlink(mutation.final_path) != mutation.previous_target
+    ):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding changed after planning: {mutation.final_path}",
+            action="stage_binding_projection",
+        )
+    target = mutation.final_path.parent / mutation.relative_target
+    try:
+        target_realpath = target.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding target changed after planning: {target}",
+            action="stage_binding_projection",
+            detail=str(exc),
+        ) from exc
+    if not target_realpath.is_dir():
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"binding target is not a directory: {target}",
+            action="stage_binding_projection",
+        )
+
+
+def _unlink_exact_link(path: Path, relative_target: str) -> None:
+    if not path.is_symlink() or os.readlink(path) != relative_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"refusing to unlink an unverified symbolic link: {path}",
+            action="discard_staged_projection",
+        )
+    path.unlink()
+
+
+def discard_staged_projection(mutations: Sequence[LinkMutation]) -> None:
+    for mutation in reversed(tuple(mutations)):
+        if not _lexists(mutation.staged_path):
+            continue
+        _unlink_exact_link(mutation.staged_path, mutation.relative_target)
+
+
+def stage_binding_projection(mutations: Sequence[LinkMutation]) -> None:
+    ordered = tuple(mutations)
+    for mutation in ordered:
+        _verify_mutation_before_stage(mutation)
+    staged: list[LinkMutation] = []
+    try:
+        for mutation in ordered:
+            os.symlink(
+                mutation.relative_target,
+                mutation.staged_path,
+                target_is_directory=True,
+            )
+            staged.append(mutation)
+    except BaseException:
+        discard_staged_projection(staged)
+        raise
+
+
+def _verify_staged(mutation: LinkMutation, *, action: str) -> None:
+    if not mutation.staged_path.is_symlink():
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"staged binding is missing: {mutation.staged_path}",
+            action=action,
+        )
+    if os.readlink(mutation.staged_path) != mutation.relative_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"staged binding target changed: {mutation.staged_path}",
+            action=action,
+        )
+    try:
+        expected = (mutation.final_path.parent / mutation.relative_target).resolve(
+            strict=True
+        )
+        actual = mutation.staged_path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"staged binding is broken: {mutation.staged_path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if actual != expected:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"staged binding resolves to the wrong target: {mutation.staged_path}",
+            action=action,
+        )
+
+
+def _verify_mutation_destination(mutation: LinkMutation, *, action: str) -> None:
+    if mutation.previous_target is None:
+        if _lexists(mutation.final_path):
+            raise _error(
+                BINDING_CONFLICT_CODE,
+                f"binding destination became occupied: {mutation.final_path}",
+                action=action,
+            )
+        return
+    if (
+        not mutation.final_path.is_symlink()
+        or os.readlink(mutation.final_path) != mutation.previous_target
+    ):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding changed after staging: {mutation.final_path}",
+            action=action,
+        )
+    try:
+        mutation.final_path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding became broken: {mutation.final_path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+
+
+def _verify_removal(removal: LinkRemoval, *, action: str) -> None:
+    if not removal.final_path.is_symlink():
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding cannot be safely removed: {removal.final_path}",
+            action=action,
+        )
+    stored = os.readlink(removal.final_path)
+    if Path(stored).is_absolute() or stored != removal.previous_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding target changed before removal: {removal.final_path}",
+            action=action,
+        )
+    try:
+        resolved = removal.final_path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding became broken before removal: {removal.final_path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if resolved != removal.expected_target:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"managed binding resolves to the wrong source: {removal.final_path}",
+            action=action,
+        )
+
+
+def _replacement_link(path: Path, relative_target: str) -> None:
+    staged = _staged_path(path)
+    try:
+        os.symlink(relative_target, staged, target_is_directory=True)
+        os.replace(staged, path)
+    finally:
+        if _lexists(staged):
+            _unlink_exact_link(staged, relative_target)
+
+
+def _verify_committed_mutation(mutation: LinkMutation, *, action: str) -> None:
+    if (
+        not mutation.final_path.is_symlink()
+        or os.readlink(mutation.final_path) != mutation.relative_target
+    ):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"committed binding changed before rollback: {mutation.final_path}",
+            action=action,
+        )
+    try:
+        expected = (mutation.final_path.parent / mutation.relative_target).resolve(
+            strict=True
+        )
+        actual = mutation.final_path.resolve(strict=True)
+    except _RESOLUTION_ERRORS as exc:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"committed binding is broken: {mutation.final_path}",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if actual != expected:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            f"committed binding resolves to the wrong source: {mutation.final_path}",
+            action=action,
+        )
+
+
+def _restore_mutation(mutation: LinkMutation, *, action: str) -> None:
+    _verify_committed_mutation(mutation, action=action)
+    if mutation.previous_target is None:
+        mutation.final_path.unlink()
+    else:
+        _replacement_link(mutation.final_path, mutation.previous_target)
+
+
+def _restore_removal(removal: LinkRemoval, *, action: str) -> None:
+    if _lexists(removal.final_path):
+        raise _error(
+            BINDING_CONFLICT_CODE,
+            f"removed binding destination became occupied: {removal.final_path}",
+            action=action,
+        )
+    _replacement_link(removal.final_path, removal.previous_target)
+    _verify_removal(removal, action=action)
+
+
+def _rollback_completed(
+    mutations: Sequence[LinkMutation],
+    removals: Sequence[LinkRemoval],
+    *,
+    action: str,
+) -> None:
+    failures: list[Exception] = []
+    for mutation in reversed(tuple(mutations)):
+        try:
+            _restore_mutation(mutation, action=action)
+        except Exception as exc:  # pragma: no cover - emergency diagnostic path
+            failures.append(exc)
+    for removal in reversed(tuple(removals)):
+        try:
+            _restore_removal(removal, action=action)
+        except Exception as exc:  # pragma: no cover - emergency diagnostic path
+            failures.append(exc)
+    if failures:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "binding rollback could not restore the exact previous projection",
+            action=action,
+            detail="; ".join(str(failure) for failure in failures),
+        )
+
+
+def commit_binding_projection(
+    mutations: Sequence[LinkMutation],
+    removals: Sequence[LinkRemoval] = (),
+) -> None:
+    ordered_mutations = tuple(mutations)
+    ordered_removals = tuple(removals)
+    mutation_paths = {mutation.final_path for mutation in ordered_mutations}
+    removal_paths = {removal.final_path for removal in ordered_removals}
+    if len(mutation_paths) != len(ordered_mutations) or len(removal_paths) != len(
+        ordered_removals
+    ):
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "binding commit plan contains duplicate final paths",
+            action="commit_binding_projection",
+        )
+    if mutation_paths & removal_paths:
+        raise _error(
+            BINDING_INVALID_PROJECTION_CODE,
+            "binding commit plan cannot mutate and remove the same path",
+            action="commit_binding_projection",
+        )
+
+    for removal in ordered_removals:
+        _verify_removal(removal, action="commit_binding_projection")
+    for mutation in ordered_mutations:
+        _verify_staged(mutation, action="commit_binding_projection")
+        _verify_mutation_destination(mutation, action="commit_binding_projection")
+
+    completed_removals: list[LinkRemoval] = []
+    completed_mutations: list[LinkMutation] = []
+    try:
+        for removal in ordered_removals:
+            removal.final_path.unlink()
+            completed_removals.append(removal)
+        for mutation in ordered_mutations:
+            os.replace(mutation.staged_path, mutation.final_path)
+            completed_mutations.append(mutation)
+    except BaseException as original:
+        try:
+            _rollback_completed(
+                completed_mutations,
+                completed_removals,
+                action="commit_binding_projection",
+            )
+        except Exception as rollback_error:
+            raise rollback_error from original
+        finally:
+            discard_staged_projection(ordered_mutations)
+        raise
+
+
+def rollback_binding_projection(
+    mutations: Sequence[LinkMutation],
+    removals: Sequence[LinkRemoval] = (),
+) -> None:
+    ordered_mutations = tuple(mutations)
+    ordered_removals = tuple(removals)
+    for mutation in ordered_mutations:
+        _verify_committed_mutation(mutation, action="rollback_binding_projection")
+    for removal in ordered_removals:
+        if _lexists(removal.final_path):
+            raise _error(
+                BINDING_CONFLICT_CODE,
+                f"removed binding destination became occupied: {removal.final_path}",
+                action="rollback_binding_projection",
+            )
+    _rollback_completed(
+        ordered_mutations,
+        ordered_removals,
+        action="rollback_binding_projection",
+    )
+
+
+__all__ = [
+    "BINDING_CONFLICT_CODE",
+    "BINDING_INVALID_PROJECTION_CODE",
+    "BINDING_OVERLAP_CODE",
+    "BINDING_SOURCE_CONFLICT_CODE",
+    "LinkMutation",
+    "LinkRemoval",
+    "commit_binding_projection",
+    "discard_staged_projection",
+    "plan_binding_projection",
+    "plan_binding_removals",
+    "rollback_binding_projection",
+    "stage_binding_projection",
+]