pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/dev_sources.py

@@ -0,0 +1,1638 @@
+from __future__ import annotations
+
+import ast
+import os
+import shutil
+import tomllib
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pz_core.project_sources import resolve_sources_manifest_path
+from pz_core.runtime.errors import PzError
+
+from .dev_bindings import (
+    BINDING_CONFLICT_CODE,
+    LinkMutation,
+    commit_binding_projection,
+    discard_staged_projection,
+    plan_binding_projection,
+    plan_binding_removals,
+    rollback_binding_projection,
+    stage_binding_projection,
+)
+from .dev_git import BaseBranch, DevGitService, GitBranchPlan, PreparedBranch
+from .dev_manifest import (
+    DevBinding,
+    DevManifest,
+    DevRepo,
+    load_dev_manifest,
+    manifest_bytes,
+    validate_dev_manifest,
+)
+from .naming import derive_default_local_app_slug
+from .official_dev_sources import ResolvedSource, resolve_source_locator
+from .project_state import (
+    _normalize_business_app_id,
+    _run_git_ref_check,
+    _validate_business_app_git_ref,
+)
+
+
+_OWNER = "pz_core.authoring.dev_sources"
+_TRANSACTION_FAILED = "PZ_DEV_TRANSACTION_FAILED"
+_REQUEST_INVALID = "PZ_DEV_REQUEST_INVALID"
+_MANIFEST_MISSING = "PZ_DEV_MANIFEST_MISSING"
+_SOURCE_CONFLICT = "PZ_DEV_SOURCE_CONFLICT"
+_SOURCE_NOT_GIT = "PZ_DEV_SOURCE_NOT_GIT"
+_SOURCE_LAYOUT_INVALID = "PZ_DEV_SOURCE_LAYOUT_INVALID"
+_OS_REPLACE = os.replace
+
+Operation = Literal["add", "link", "branch", "init", "update", "remove", "unlink"]
+
+
+@dataclass(frozen=True, slots=True)
+class AddDevSourceRequest:
+    project_dir: Path
+    locators: tuple[str, ...]
+    base_branch: BaseBranch = "develop"
+
+
+@dataclass(frozen=True, slots=True)
+class BranchDevSourceRequest:
+    project_dir: Path
+    locator: str
+    base_branch: BaseBranch = "develop"
+
+
+@dataclass(frozen=True, slots=True)
+class InitDevSourcesRequest:
+    project_dir: Path
+    app_name: str | None = None
+    locators: tuple[str, ...] = ("pz",)
+    base_branch: BaseBranch = "develop"
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateDevSourceRequest:
+    project_dir: Path
+    locator: str
+
+
+@dataclass(frozen=True, slots=True)
+class RemoveDevSourceRequest:
+    project_dir: Path
+    binding: str
+    delete_checkout: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class DevTransactionResult:
+    operation: Operation
+    project_dir: Path
+    business_branch: str
+    base_branch: BaseBranch
+    repo_keys: tuple[str, ...]
+    checkouts: tuple[Path, ...]
+    bindings: tuple[str, ...]
+    links: tuple[Path, ...]
+    updated: bool | None = None
+    upstream: str | None = None
+    checkout_deleted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class _RepoIntent:
+    repo_key: str
+    source: str
+    checkout: Path
+
+
+@dataclass(frozen=True, slots=True)
+class _PreparedRepo:
+    intent: _RepoIntent
+    branch: PreparedBranch
+
+
+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 _new_git_service() -> DevGitService:
+    return DevGitService()
+
+
+def _transaction_phase(_name: str) -> None:
+    return None
+
+
+def _inject_fault(_name: str) -> None:
+    return None
+
+
+def _atomic_replace(source: Path, destination: Path) -> None:
+    _OS_REPLACE(source, destination)
+
+
+def _fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _project_root(value: object, *, action: str) -> Path:
+    if not isinstance(value, Path):
+        raise _error(
+            _REQUEST_INVALID,
+            "project_dir must be a pathlib.Path.",
+            action=action,
+        )
+    project_dir = value.expanduser().resolve(strict=False)
+    if not project_dir.is_dir():
+        raise _error(
+            _REQUEST_INVALID,
+            f"project directory does not exist: {project_dir}",
+            action=action,
+        )
+    apps_root = project_dir / "apps"
+    if apps_root.is_symlink() or not apps_root.is_dir():
+        raise _error(
+            _REQUEST_INVALID,
+            f"project apps directory must be a real directory: {apps_root}",
+            action=action,
+        )
+    return project_dir
+
+
+def _base_branch(value: object, *, action: str) -> BaseBranch:
+    if value not in {"develop", "main"}:
+        raise _error(
+            _REQUEST_INVALID,
+            "base branch must be develop or main.",
+            action=action,
+        )
+    return value  # type: ignore[return-value]
+
+
+def _locators(values: object, *, action: str) -> tuple[str, ...]:
+    if not isinstance(values, tuple) or not values:
+        raise _error(
+            _REQUEST_INVALID,
+            "at least one source locator is required.",
+            action=action,
+        )
+    normalized: list[str] = []
+    for value in values:
+        if not isinstance(value, str) or not value.strip():
+            raise _error(
+                _REQUEST_INVALID,
+                "source locators must be non-empty strings.",
+                action=action,
+            )
+        candidate = value.strip()
+        if candidate not in normalized:
+            normalized.append(candidate)
+    return tuple(normalized)
+
+
+def _business_manifest(
+    project_dir: Path,
+    manifest: DevManifest | None,
+    *,
+    app_name: str | None,
+    action: str,
+) -> DevManifest:
+    if manifest is not None:
+        business_app_id = _normalize_business_app_id(
+            manifest.business_app_id,
+            action=action,
+        )
+        if app_name is not None:
+            requested = _normalize_business_app_id(app_name, action=action)
+            if requested != business_app_id:
+                raise _error(
+                    "PZ_DEV_BUSINESS_APP_ID_INVALID",
+                    "business app id is already persisted and cannot be changed.",
+                    action=action,
+                )
+    else:
+        candidate = app_name or derive_default_local_app_slug(project_dir)
+        business_app_id = _normalize_business_app_id(candidate, action=action)
+    _validate_business_app_git_ref(
+        business_app_id,
+        action=action,
+        git_ref_runner=_run_git_ref_check,
+    )
+    if manifest is not None:
+        return manifest
+    return DevManifest(
+        schema_version=5,
+        business_app_id=business_app_id,
+        repos={},
+        bindings={},
+    )
+
+
+def _read_manifest_snapshot(path: Path) -> bytes | None:
+    if not path.exists() and not path.is_symlink():
+        return None
+    if path.is_symlink() or not path.is_file():
+        raise _error(
+            "PZ_DEV_MANIFEST_INVALID",
+            "dev manifest must be a real file.",
+            action="load_dev_transaction",
+        )
+    try:
+        return path.read_bytes()
+    except OSError as exc:
+        raise _error(
+            "PZ_DEV_MANIFEST_INVALID",
+            "dev manifest could not be read.",
+            action="load_dev_transaction",
+            detail=str(exc),
+        ) from exc
+
+
+def _resolved_binding(source: ResolvedSource) -> tuple[str, DevBinding]:
+    kind = source.binding_kind
+    subpath = source.subpath
+    link_name = source.link_name
+    expected_app_id = source.expected_app_id
+    if source.pending_layout:
+        kind = "directory"
+        subpath = PurePosixPath(".")
+        expected_app_id = None
+    if kind not in {"directory", "app"}:
+        raise _error(
+            _SOURCE_LAYOUT_INVALID,
+            "source locator did not resolve to a bindable layout.",
+            action="resolve_dev_transaction",
+            detail=source.locator,
+        )
+    binding_key = expected_app_id if kind == "app" else link_name
+    if not binding_key:
+        raise _error(
+            _SOURCE_LAYOUT_INVALID,
+            "source locator did not resolve a binding identity.",
+            action="resolve_dev_transaction",
+            detail=source.locator,
+        )
+    if source.source_kind == "git":
+        binding_source = source.clone_source
+        repo_key = source.repo_key
+    else:
+        binding_source = str(Path(source.clone_source).expanduser().resolve())
+        repo_key = None
+    return binding_key, DevBinding(
+        kind=kind,
+        source_kind=source.source_kind,
+        repo_key=repo_key,
+        source=binding_source,
+        link=PurePosixPath("apps") / link_name,
+        subpath=subpath,
+    )
+
+
+def _build_desired_manifest(
+    project_dir: Path,
+    before: DevManifest,
+    resolved_sources: Sequence[ResolvedSource],
+    *,
+    operation: Operation,
+    base_branch: BaseBranch,
+    action: str,
+) -> tuple[DevManifest, tuple[_RepoIntent, ...], tuple[str, ...]]:
+    repos = dict(before.repos)
+    bindings = dict(before.bindings)
+    intents: dict[str, _RepoIntent] = {}
+    selected_bindings: list[str] = []
+
+    for source in resolved_sources:
+        if source.source_kind == "git":
+            repo_key = source.repo_key
+            if not repo_key:
+                raise _error(
+                    _SOURCE_LAYOUT_INVALID,
+                    "Git source locator did not resolve a repo key.",
+                    action=action,
+                    detail=source.locator,
+                )
+            existing_repo = repos.get(repo_key)
+            if (
+                existing_repo is not None
+                and existing_repo.source != source.clone_source
+            ):
+                raise _error(
+                    _SOURCE_CONFLICT,
+                    f"repo key is already bound to a different source: {repo_key}",
+                    action=action,
+                    detail=(
+                        f"existing={existing_repo.source}; desired={source.clone_source}"
+                    ),
+                )
+            previous_intent = intents.get(repo_key)
+            if (
+                previous_intent is not None
+                and previous_intent.source != source.clone_source
+            ):
+                raise _error(
+                    _SOURCE_CONFLICT,
+                    f"source locators disagree for repo key: {repo_key}",
+                    action=action,
+                )
+            checkout_posix = PurePosixPath("apps/.sources") / repo_key
+            repos[repo_key] = DevRepo(
+                source=source.clone_source,
+                checkout=checkout_posix,
+                base_branch=base_branch,
+                branch=before.business_app_id,
+            )
+            intents.setdefault(
+                repo_key,
+                _RepoIntent(
+                    repo_key=repo_key,
+                    source=source.clone_source,
+                    checkout=project_dir / Path(*checkout_posix.parts),
+                ),
+            )
+        elif operation == "branch":
+            raise _error(
+                _SOURCE_NOT_GIT,
+                "branch preparation requires a Git-backed source.",
+                action=action,
+                detail=source.locator,
+            )
+
+        if operation == "branch":
+            continue
+        if source.bootstrap:
+            continue
+        binding_key, binding = _resolved_binding(source)
+        previous_binding = bindings.get(binding_key)
+        if previous_binding is not None and previous_binding != binding:
+            previous_link = previous_binding.link
+            if previous_link != binding.link:
+                raise _error(
+                    _SOURCE_CONFLICT,
+                    f"binding identity is already exposed at another link: {binding_key}",
+                    action=action,
+                    detail=f"existing={previous_link}; desired={binding.link}",
+                )
+        bindings[binding_key] = binding
+        if binding_key not in selected_bindings:
+            selected_bindings.append(binding_key)
+
+    desired = DevManifest(
+        schema_version=5,
+        business_app_id=before.business_app_id,
+        repos=repos,
+        bindings=bindings,
+    )
+    validate_dev_manifest(project_dir, desired)
+    return desired, tuple(intents.values()), tuple(selected_bindings)
+
+
+def _binding_base(
+    project_dir: Path,
+    manifest: DevManifest,
+    binding: DevBinding,
+) -> Path:
+    if binding.source_kind == "link":
+        return Path(binding.source)
+    assert binding.repo_key is not None
+    repo = manifest.repos[binding.repo_key]
+    return project_dir / Path(*repo.checkout.parts)
+
+
+def _binding_target(
+    project_dir: Path,
+    manifest: DevManifest,
+    binding: DevBinding,
+) -> Path:
+    base = _binding_base(project_dir, manifest, binding)
+    if binding.subpath == PurePosixPath("."):
+        return base
+    return base / Path(*binding.subpath.parts)
+
+
+def _layout_error(message: str, *, locator: str, detail: str) -> PzError:
+    return _error(
+        _SOURCE_LAYOUT_INVALID,
+        message,
+        action="validate_dev_source_layout",
+        detail=f"locator={locator}; {detail}",
+    )
+
+
+def _static_apps_py_app_id(path: Path) -> str | None:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    except (OSError, UnicodeError, SyntaxError):
+        return None
+    class_ids: dict[str, str] = {}
+    for statement in tree.body:
+        if not isinstance(statement, ast.ClassDef):
+            continue
+        for field in statement.body:
+            targets: tuple[ast.expr, ...]
+            value: ast.expr | None
+            if isinstance(field, ast.Assign):
+                targets = tuple(field.targets)
+                value = field.value
+            elif isinstance(field, ast.AnnAssign):
+                targets = (field.target,)
+                value = field.value
+            else:
+                continue
+            if not any(
+                isinstance(target, ast.Name) and target.id == "id" for target in targets
+            ):
+                continue
+            if (
+                isinstance(value, ast.Constant)
+                and isinstance(value.value, str)
+                and value.value.isidentifier()
+            ):
+                class_ids[statement.name] = value.value
+            break
+    for statement in tree.body:
+        if not isinstance(statement, ast.Assign):
+            continue
+        if not any(
+            isinstance(target, ast.Name) and target.id == "app"
+            for target in statement.targets
+        ):
+            continue
+        value = statement.value
+        if (
+            isinstance(value, ast.Call)
+            and isinstance(value.func, ast.Name)
+            and value.func.id in class_ids
+        ):
+            return class_ids[value.func.id]
+    return None
+
+
+def _formal_leaf(path: Path) -> str | None:
+    pyproject = path / "pyproject.toml"
+    if not pyproject.is_file():
+        return 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
+    distribution = project.get("name")
+    if not isinstance(distribution, str) or not distribution.strip():
+        return None
+    app_id = distribution.strip().replace("-", "_")
+    apps_py = path / app_id / "apps.py"
+    if _static_apps_py_app_id(apps_py) != app_id:
+        return None
+    return app_id
+
+
+def _has_formal_top_level_leaf(root: Path) -> bool:
+    for child in sorted(root.iterdir(), key=lambda item: item.name):
+        if child.name.startswith(".") or child.is_symlink() or not child.is_dir():
+            continue
+        if _formal_leaf(child) is not None:
+            return True
+    return False
+
+
+def _validate_source_layout(
+    source: ResolvedSource,
+    *,
+    source_root: Path,
+) -> None:
+    subpath = PurePosixPath(".") if source.pending_layout else source.subpath
+    target = (
+        source_root
+        if subpath == PurePosixPath(".")
+        else source_root / Path(*subpath.parts)
+    )
+    try:
+        source_realpath = source_root.resolve(strict=True)
+        target_realpath = target.resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise _layout_error(
+            "source layout target is missing or broken.",
+            locator=source.locator,
+            detail=str(exc),
+        ) from exc
+    if not source_realpath.is_dir() or not target_realpath.is_dir():
+        raise _layout_error(
+            "source layout target must be a directory.",
+            locator=source.locator,
+            detail=str(target),
+        )
+    if not target_realpath.is_relative_to(source_realpath):
+        raise _layout_error(
+            "source layout target escapes its source root.",
+            locator=source.locator,
+            detail=str(target_realpath),
+        )
+    if source.pending_layout:
+        if not _has_formal_top_level_leaf(target_realpath):
+            raise _layout_error(
+                "Git source contains no formal top-level minimal app.",
+                locator=source.locator,
+                detail=str(target_realpath),
+            )
+        return
+    if source.binding_kind != "app":
+        return
+    expected_app_id = source.expected_app_id
+    discovered_app_id = _formal_leaf(target_realpath)
+    if not expected_app_id or discovered_app_id != expected_app_id:
+        raise _layout_error(
+            "app source does not match its declared app id.",
+            locator=source.locator,
+            detail=(
+                f"expected={expected_app_id!r}; discovered={discovered_app_id!r}; "
+                f"path={target_realpath}"
+            ),
+        )
+
+
+def _preflight_paths(project_dir: Path, manifest_path: Path) -> None:
+    sources_root = manifest_path.parent
+    if sources_root.is_symlink():
+        raise _error(
+            _REQUEST_INVALID,
+            "managed source root cannot be a symbolic link.",
+            action="preflight_dev_transaction",
+            detail=str(sources_root),
+        )
+    if sources_root.exists() and not sources_root.is_dir():
+        raise _error(
+            _REQUEST_INVALID,
+            "managed source root must be a directory.",
+            action="preflight_dev_transaction",
+            detail=str(sources_root),
+        )
+    if manifest_path.is_symlink():
+        raise _error(
+            "PZ_DEV_MANIFEST_INVALID",
+            "dev manifest cannot be a symbolic link.",
+            action="preflight_dev_transaction",
+        )
+    project_realpath = project_dir.resolve(strict=True)
+    apps_realpath = (project_dir / "apps").resolve(strict=True)
+    if not apps_realpath.is_relative_to(project_realpath):
+        raise _error(
+            _REQUEST_INVALID,
+            "apps directory escapes the project root.",
+            action="preflight_dev_transaction",
+        )
+
+
+def _preflight_projection(
+    project_dir: Path,
+    before: DevManifest,
+    desired: DevManifest,
+) -> None:
+    plan_binding_projection(project_dir, before, before)
+    before_links = {
+        project_dir / Path(*binding.link.parts) for binding in before.bindings.values()
+    }
+    for binding in desired.bindings.values():
+        final_path = project_dir / Path(*binding.link.parts)
+        if final_path not in before_links and os.path.lexists(final_path):
+            raise _error(
+                BINDING_CONFLICT_CODE,
+                f"binding destination is occupied by an unmanaged path: {final_path}",
+                action="preflight_dev_transaction",
+            )
+
+    partial_bindings = dict(before.bindings)
+    for key, binding in desired.bindings.items():
+        target = _binding_target(project_dir, desired, binding)
+        try:
+            available = target.resolve(strict=True).is_dir()
+        except (OSError, RuntimeError):
+            available = False
+        if available:
+            partial_bindings[key] = binding
+    partial = DevManifest(
+        schema_version=5,
+        business_app_id=desired.business_app_id,
+        repos=desired.repos,
+        bindings=partial_bindings,
+    )
+    validate_dev_manifest(project_dir, partial)
+    plan_binding_projection(project_dir, before, partial)
+
+
+def _git_plan(
+    project_dir: Path,
+    intent: _RepoIntent,
+    *,
+    business_branch: str,
+    base_branch: BaseBranch,
+    transaction_id: str,
+) -> GitBranchPlan:
+    return GitBranchPlan(
+        project_dir=project_dir,
+        repo_key=intent.repo_key,
+        source=intent.source,
+        checkout=intent.checkout,
+        business_branch=business_branch,
+        transaction_id=transaction_id,
+        base_branch=base_branch,
+    )
+
+
+def _prepared_source_root(
+    source: ResolvedSource,
+    prepared: Mapping[str, _PreparedRepo],
+) -> Path:
+    if source.source_kind == "link":
+        return Path(source.clone_source).expanduser().resolve()
+    assert source.repo_key is not None
+    return prepared[source.repo_key].branch.checkout
+
+
+def _shadow_manifest(
+    desired: DevManifest,
+    prepared: Mapping[str, _PreparedRepo],
+) -> tuple[DevManifest, frozenset[Path]]:
+    bindings: dict[str, DevBinding] = {}
+    staged_final_paths: set[Path] = set()
+    for key, binding in desired.bindings.items():
+        if binding.source_kind != "git" or binding.repo_key is None:
+            bindings[key] = binding
+            continue
+        prepared_repo = prepared.get(binding.repo_key)
+        if prepared_repo is None or not prepared_repo.branch.new_clone:
+            bindings[key] = binding
+            continue
+        bindings[key] = DevBinding(
+            kind=binding.kind,
+            source_kind="link",
+            repo_key=None,
+            source=str(prepared_repo.branch.checkout.resolve(strict=True)),
+            link=binding.link,
+            subpath=binding.subpath,
+        )
+        staged_final_paths.add(Path(*binding.link.parts))
+    return (
+        DevManifest(
+            schema_version=5,
+            business_app_id=desired.business_app_id,
+            repos=desired.repos,
+            bindings=bindings,
+        ),
+        frozenset(staged_final_paths),
+    )
+
+
+def _final_relative_target(
+    project_dir: Path,
+    desired: DevManifest,
+    mutation: LinkMutation,
+) -> str:
+    binding = next(
+        binding
+        for binding in desired.bindings.values()
+        if project_dir / Path(*binding.link.parts) == mutation.final_path
+    )
+    target = _binding_target(project_dir, desired, binding)
+    return Path(os.path.relpath(target, start=mutation.final_path.parent)).as_posix()
+
+
+def _final_link_mutations(
+    project_dir: Path,
+    desired: DevManifest,
+    shadow_mutations: Sequence[LinkMutation],
+    staged_final_paths: frozenset[Path],
+) -> tuple[LinkMutation, ...]:
+    mutations: list[LinkMutation] = []
+    for mutation in shadow_mutations:
+        relative_final = mutation.final_path.relative_to(project_dir)
+        if relative_final not in staged_final_paths:
+            mutations.append(mutation)
+            continue
+        relative_target = _final_relative_target(project_dir, desired, mutation)
+        mutations.append(
+            LinkMutation(
+                final_path=mutation.final_path,
+                staged_path=mutation.staged_path,
+                relative_target=relative_target,
+                previous_target=mutation.previous_target,
+            )
+        )
+    return tuple(mutations)
+
+
+def _retarget_staged_links(
+    shadow_mutations: Sequence[LinkMutation],
+    final_mutations: Sequence[LinkMutation],
+) -> None:
+    pairs = tuple(zip(shadow_mutations, final_mutations, strict=True))
+    try:
+        for shadow, final in pairs:
+            if shadow.relative_target == final.relative_target:
+                continue
+            if (
+                not shadow.staged_path.is_symlink()
+                or os.readlink(shadow.staged_path) != shadow.relative_target
+            ):
+                raise _error(
+                    "PZ_DEV_BINDING_INVALID_PROJECTION",
+                    "staged binding changed before final-target conversion.",
+                    action="stage_dev_transaction",
+                    detail=str(shadow.staged_path),
+                )
+            shadow.staged_path.unlink()
+            os.symlink(
+                final.relative_target,
+                final.staged_path,
+                target_is_directory=True,
+            )
+    except BaseException as original:
+        cleanup_failures: list[Exception] = []
+        for shadow, final in reversed(pairs):
+            path = shadow.staged_path
+            if not path.is_symlink():
+                continue
+            try:
+                actual = os.readlink(path)
+                if actual not in {shadow.relative_target, final.relative_target}:
+                    raise RuntimeError(f"staged binding changed concurrently: {path}")
+                path.unlink()
+            except Exception as exc:
+                cleanup_failures.append(exc)
+        if cleanup_failures:
+            raise RuntimeError(
+                "staged binding retarget cleanup failed: "
+                + "; ".join(str(failure) for failure in cleanup_failures)
+            ) from original
+        raise
+
+
+def _write_staged_manifest(path: Path, payload: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+
+
+def _discard_staged_manifest(path: Path, expected: bytes) -> None:
+    if not path.exists() and not path.is_symlink():
+        return
+    if path.is_symlink() or not path.is_file() or path.read_bytes() != expected:
+        raise RuntimeError(f"staged manifest identity changed: {path}")
+    path.unlink()
+
+
+def _prepared_identity_matches(path: Path, prepared: PreparedBranch) -> bool:
+    if path.is_symlink() or not path.is_dir():
+        return False
+    if prepared.clone_device is None or prepared.clone_inode is None:
+        return False
+    stat = path.stat(follow_symlinks=False)
+    return stat.st_dev == prepared.clone_device and stat.st_ino == prepared.clone_inode
+
+
+def _restore_manifest(
+    manifest_path: Path,
+    *,
+    before_bytes: bytes | None,
+    desired_bytes: bytes,
+    transaction_id: str,
+) -> None:
+    if not manifest_path.exists() or manifest_path.is_symlink():
+        if before_bytes is None and not manifest_path.is_symlink():
+            return
+        raise RuntimeError("manifest disappeared or changed type during rollback")
+    current = manifest_path.read_bytes()
+    if current == before_bytes:
+        return
+    if current != desired_bytes:
+        raise RuntimeError("manifest bytes changed concurrently before rollback")
+    if before_bytes is None:
+        manifest_path.unlink()
+        _fsync_directory(manifest_path.parent)
+        return
+    restore_path = manifest_path.with_name(
+        f".{manifest_path.name}.{transaction_id}.restore"
+    )
+    _write_staged_manifest(restore_path, before_bytes)
+    try:
+        _OS_REPLACE(restore_path, manifest_path)
+        _fsync_directory(manifest_path.parent)
+    finally:
+        _discard_staged_manifest(restore_path, before_bytes)
+
+
+def _committed_link_mutations(
+    mutations: Sequence[LinkMutation],
+) -> tuple[LinkMutation, ...]:
+    committed: list[LinkMutation] = []
+    for mutation in mutations:
+        if mutation.final_path.is_symlink():
+            actual = os.readlink(mutation.final_path)
+            if actual == mutation.relative_target:
+                committed.append(mutation)
+                continue
+            if (
+                mutation.previous_target is not None
+                and actual == mutation.previous_target
+            ):
+                continue
+            raise RuntimeError(f"binding changed concurrently: {mutation.final_path}")
+        if (
+            not os.path.lexists(mutation.final_path)
+            and mutation.previous_target is None
+        ):
+            continue
+        raise RuntimeError(
+            f"binding changed type during rollback: {mutation.final_path}"
+        )
+    return tuple(committed)
+
+
+def _restore_new_checkout(prepared: _PreparedRepo) -> None:
+    branch = prepared.branch
+    if not branch.new_clone:
+        return
+    staged = branch.checkout
+    final = prepared.intent.checkout
+    staged_matches = _prepared_identity_matches(staged, branch)
+    final_matches = _prepared_identity_matches(final, branch)
+    if staged_matches and not os.path.lexists(final):
+        return
+    if final_matches and not os.path.lexists(staged):
+        staged.parent.mkdir(parents=True, exist_ok=True)
+        _OS_REPLACE(final, staged)
+        return
+    if not os.path.lexists(staged) and not os.path.lexists(final):
+        return
+    raise RuntimeError(
+        f"prepared checkout identity changed: {prepared.intent.repo_key}"
+    )
+
+
+def _cleanup_transaction_paths(
+    project_dir: Path,
+    *,
+    transaction_id: str,
+    staged_manifest: Path | None,
+    desired_bytes: bytes,
+    mutations: Sequence[LinkMutation],
+    sources_root_existed: bool,
+) -> None:
+    discard_staged_projection(mutations)
+    if staged_manifest is not None:
+        _discard_staged_manifest(staged_manifest, desired_bytes)
+    sources_root = project_dir / "apps" / ".sources"
+    transaction_root = sources_root / ".transactions" / transaction_id
+    transactions_root = transaction_root.parent
+    try:
+        transaction_root.rmdir()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        if transaction_root.exists() and any(transaction_root.iterdir()):
+            raise
+    try:
+        transactions_root.rmdir()
+    except (FileNotFoundError, OSError):
+        pass
+    if not sources_root_existed:
+        try:
+            sources_root.rmdir()
+        except (FileNotFoundError, OSError):
+            pass
+
+
+def _rollback_transaction(
+    project_dir: Path,
+    *,
+    manifest_path: Path,
+    before_bytes: bytes | None,
+    desired_bytes: bytes,
+    prepared_repos: Sequence[_PreparedRepo],
+    git_service: DevGitService | None,
+    mutations: Sequence[LinkMutation],
+    links_commit_attempted: bool,
+    staged_manifest: Path | None,
+    manifest_replace_attempted: bool,
+    transaction_id: str,
+    sources_root_existed: bool,
+) -> tuple[Exception, ...]:
+    failures: list[Exception] = []
+    if manifest_replace_attempted:
+        try:
+            _restore_manifest(
+                manifest_path,
+                before_bytes=before_bytes,
+                desired_bytes=desired_bytes,
+                transaction_id=transaction_id,
+            )
+        except Exception as exc:
+            failures.append(exc)
+    if links_commit_attempted:
+        try:
+            committed = _committed_link_mutations(mutations)
+            if committed:
+                rollback_binding_projection(committed)
+        except Exception as exc:
+            failures.append(exc)
+    for prepared in reversed(tuple(prepared_repos)):
+        try:
+            _restore_new_checkout(prepared)
+        except Exception as exc:
+            failures.append(exc)
+    if git_service is not None:
+        for prepared in reversed(tuple(prepared_repos)):
+            try:
+                git_service.rollback(prepared.branch)
+            except Exception as exc:
+                failures.append(exc)
+    try:
+        _cleanup_transaction_paths(
+            project_dir,
+            transaction_id=transaction_id,
+            staged_manifest=staged_manifest,
+            desired_bytes=desired_bytes,
+            mutations=mutations,
+            sources_root_existed=sources_root_existed,
+        )
+    except Exception as exc:
+        failures.append(exc)
+    return tuple(failures)
+
+
+def _failure_detail(
+    original: BaseException,
+    *,
+    phase: str,
+    rollback_failures: Sequence[Exception],
+) -> str:
+    root = f"{original.__class__.__name__}: {original}"
+    if rollback_failures:
+        rollback = "failed: " + "; ".join(
+            f"{failure.__class__.__name__}: {failure}" for failure in rollback_failures
+        )
+    else:
+        rollback = "ok"
+    return f"phase={phase}; cause={root}; rollback={rollback}"
+
+
+def _verify_manifest_snapshot(
+    path: Path, expected: bytes | None, *, action: str
+) -> None:
+    if _read_manifest_snapshot(path) != expected:
+        raise _error(
+            "PZ_DEV_MANIFEST_CHANGED",
+            "dev manifest changed after transaction preflight.",
+            action=action,
+        )
+
+
+def _execute_transaction(
+    *,
+    operation: Operation,
+    project_dir_value: object,
+    locator_values: object,
+    base_branch_value: object,
+    app_name: str | None,
+    action: str,
+) -> DevTransactionResult:
+    project_dir = _project_root(project_dir_value, action=action)
+    base_branch = _base_branch(base_branch_value, action=action)
+    locators = _locators(locator_values, action=action)
+    manifest_path = resolve_sources_manifest_path(project_dir)
+    transaction_id = f"pz-{uuid.uuid4().hex}"
+    sources_root_existed = manifest_path.parent.exists()
+    before_bytes: bytes | None = None
+    desired_bytes = b""
+    git_service: DevGitService | None = None
+    prepared_repos: list[_PreparedRepo] = []
+    mutations: tuple[LinkMutation, ...] = ()
+    links_commit_attempted = False
+    staged_manifest: Path | None = None
+    manifest_replace_attempted = False
+    phase = "load"
+
+    try:
+        _transaction_phase(phase)
+        before_bytes = _read_manifest_snapshot(manifest_path)
+        loaded = load_dev_manifest(project_dir)
+        if loaded is None and operation != "init":
+            raise _error(
+                _MANIFEST_MISSING,
+                "dev manifest is missing; run pz dev init first.",
+                action=action,
+            )
+        before = _business_manifest(
+            project_dir,
+            loaded,
+            app_name=app_name,
+            action=action,
+        )
+        if _read_manifest_snapshot(manifest_path) != before_bytes:
+            raise _error(
+                "PZ_DEV_MANIFEST_INVALID",
+                "dev manifest changed while it was being loaded.",
+                action=action,
+            )
+
+        phase = "resolve"
+        _transaction_phase(phase)
+        resolved_sources = tuple(
+            resolve_source_locator(locator, project_dir=project_dir, action=action)
+            for locator in locators
+        )
+        desired, intents, selected_bindings = _build_desired_manifest(
+            project_dir,
+            before,
+            resolved_sources,
+            operation=operation,
+            base_branch=base_branch,
+            action=action,
+        )
+        desired_bytes = manifest_bytes(desired)
+
+        phase = "preflight"
+        _transaction_phase(phase)
+        _preflight_paths(project_dir, manifest_path)
+        _preflight_projection(project_dir, before, desired)
+        for source in resolved_sources:
+            if source.source_kind == "link":
+                _validate_source_layout(
+                    source,
+                    source_root=Path(source.clone_source).expanduser().resolve(),
+                )
+                continue
+            assert source.repo_key is not None
+            intent = next(item for item in intents if item.repo_key == source.repo_key)
+            if intent.checkout.exists():
+                _validate_source_layout(source, source_root=intent.checkout)
+        plans = tuple(
+            _git_plan(
+                project_dir,
+                intent,
+                business_branch=before.business_app_id,
+                base_branch=base_branch,
+                transaction_id=transaction_id,
+            )
+            for intent in intents
+        )
+        if plans:
+            git_service = _new_git_service()
+            for plan in plans:
+                git_service.preflight_existing(plan)
+
+        phase = "git_prepare"
+        _transaction_phase(phase)
+        if git_service is not None:
+            for intent, plan in zip(intents, plans, strict=True):
+                prepared = _PreparedRepo(
+                    intent=intent, branch=git_service.prepare(plan)
+                )
+                prepared_repos.append(prepared)
+                if prepared.branch.new_clone:
+                    _inject_fault("after_clone")
+                _inject_fault("after_branch")
+        prepared_by_key = {
+            prepared.intent.repo_key: prepared for prepared in prepared_repos
+        }
+
+        phase = "layout"
+        _transaction_phase(phase)
+        for source in resolved_sources:
+            _validate_source_layout(
+                source,
+                source_root=_prepared_source_root(source, prepared_by_key),
+            )
+        _inject_fault("layout")
+
+        phase = "stage"
+        _transaction_phase(phase)
+        if desired_bytes != before_bytes:
+            staged_manifest = manifest_path.with_name(
+                f".{manifest_path.name}.{transaction_id}.tmp"
+            )
+            _write_staged_manifest(staged_manifest, desired_bytes)
+        shadow, staged_final_paths = _shadow_manifest(desired, prepared_by_key)
+        shadow_mutations = plan_binding_projection(project_dir, before, shadow)
+        mutations = _final_link_mutations(
+            project_dir,
+            desired,
+            shadow_mutations,
+            staged_final_paths,
+        )
+        stage_binding_projection(shadow_mutations)
+        _retarget_staged_links(
+            shadow_mutations,
+            mutations,
+        )
+        _inject_fault("stage")
+
+        phase = "place"
+        _transaction_phase(phase)
+        _verify_manifest_snapshot(manifest_path, before_bytes, action=action)
+        for prepared in prepared_repos:
+            if not prepared.branch.new_clone:
+                continue
+            final = prepared.intent.checkout
+            if os.path.lexists(final):
+                raise _error(
+                    BINDING_CONFLICT_CODE,
+                    f"Git checkout destination became occupied: {final}",
+                    action=action,
+                )
+            _atomic_replace(prepared.branch.checkout, final)
+            _inject_fault("place")
+
+        phase = "links"
+        _transaction_phase(phase)
+        _verify_manifest_snapshot(manifest_path, before_bytes, action=action)
+        links_commit_attempted = True
+        commit_binding_projection(mutations)
+        _inject_fault("links")
+
+        phase = "manifest"
+        _transaction_phase(phase)
+        if staged_manifest is not None:
+            _verify_manifest_snapshot(manifest_path, before_bytes, action=action)
+            manifest_replace_attempted = True
+            _atomic_replace(staged_manifest, manifest_path)
+            _fsync_directory(manifest_path.parent)
+        _inject_fault("manifest")
+
+        phase = "cleanup"
+        _transaction_phase(phase)
+        _cleanup_transaction_paths(
+            project_dir,
+            transaction_id=transaction_id,
+            staged_manifest=staged_manifest,
+            desired_bytes=desired_bytes,
+            mutations=mutations,
+            sources_root_existed=sources_root_existed,
+        )
+        return DevTransactionResult(
+            operation=operation,
+            project_dir=project_dir,
+            business_branch=before.business_app_id,
+            base_branch=base_branch,
+            repo_keys=tuple(intent.repo_key for intent in intents),
+            checkouts=tuple(intent.checkout for intent in intents),
+            bindings=selected_bindings,
+            links=tuple(mutation.final_path for mutation in mutations),
+        )
+    except BaseException as original:
+        rollback_failures = _rollback_transaction(
+            project_dir,
+            manifest_path=manifest_path,
+            before_bytes=before_bytes,
+            desired_bytes=desired_bytes,
+            prepared_repos=prepared_repos,
+            git_service=git_service,
+            mutations=mutations,
+            links_commit_attempted=links_commit_attempted,
+            staged_manifest=staged_manifest,
+            manifest_replace_attempted=manifest_replace_attempted,
+            transaction_id=transaction_id,
+            sources_root_existed=sources_root_existed,
+        )
+        if isinstance(original, PzError) and not rollback_failures:
+            raise
+        wrapped = _error(
+            _TRANSACTION_FAILED,
+            "dev source transaction failed.",
+            action=action,
+            detail=_failure_detail(
+                original,
+                phase=phase,
+                rollback_failures=rollback_failures,
+            ),
+        )
+        raise wrapped from original
+
+
+def add_dev_source(request: AddDevSourceRequest) -> DevTransactionResult:
+    if not isinstance(request, AddDevSourceRequest):
+        raise _error(
+            _REQUEST_INVALID,
+            "add_dev_source requires an AddDevSourceRequest.",
+            action="add_dev_source",
+        )
+    return _execute_transaction(
+        operation="add",
+        project_dir_value=request.project_dir,
+        locator_values=request.locators,
+        base_branch_value=request.base_branch,
+        app_name=None,
+        action="add_dev_source",
+    )
+
+
+def branch_dev_source(request: BranchDevSourceRequest) -> DevTransactionResult:
+    if not isinstance(request, BranchDevSourceRequest):
+        raise _error(
+            _REQUEST_INVALID,
+            "branch_dev_source requires a BranchDevSourceRequest.",
+            action="branch_dev_source",
+        )
+    project_dir = _project_root(request.project_dir, action="branch_dev_source")
+    locator = _locators((request.locator,), action="branch_dev_source")[0]
+    manifest = load_dev_manifest(project_dir)
+    if manifest is not None:
+        repo_key = _repo_key_for_locator(
+            project_dir,
+            manifest,
+            locator,
+            action="branch_dev_source",
+        )
+        checkout = project_dir / Path(*manifest.repos[repo_key].checkout.parts)
+        if checkout.is_symlink():
+            raise _error(
+                "PZ_DEV_SHARED_CHECKOUT_READ_ONLY",
+                "Shared checkout is externally owned and read-only to PZ authoring commands.",
+                action="branch_dev_source",
+                detail=repo_key,
+            )
+    return _execute_transaction(
+        operation="branch",
+        project_dir_value=project_dir,
+        locator_values=(locator,),
+        base_branch_value=request.base_branch,
+        app_name=None,
+        action="branch_dev_source",
+    )
+
+
+def initialize_dev_sources(request: InitDevSourcesRequest) -> DevTransactionResult:
+    if not isinstance(request, InitDevSourcesRequest):
+        raise _error(
+            _REQUEST_INVALID,
+            "initialize_dev_sources requires an InitDevSourcesRequest.",
+            action="initialize_dev_sources",
+        )
+    return _execute_transaction(
+        operation="init",
+        project_dir_value=request.project_dir,
+        locator_values=request.locators,
+        base_branch_value=request.base_branch,
+        app_name=request.app_name,
+        action="initialize_dev_sources",
+    )
+
+
+def _repo_key_for_locator(
+    project_dir: Path,
+    manifest: DevManifest,
+    locator: str,
+    *,
+    action: str,
+) -> str:
+    if locator in manifest.repos:
+        return locator
+    binding = manifest.bindings.get(locator)
+    if binding is not None:
+        if binding.source_kind != "git" or binding.repo_key is None:
+            raise _error(
+                _SOURCE_NOT_GIT,
+                "development source is not Git-backed.",
+                action=action,
+                detail=locator,
+            )
+        return binding.repo_key
+    resolved = resolve_source_locator(locator, project_dir=project_dir, action=action)
+    if (
+        resolved.source_kind != "git"
+        or resolved.repo_key is None
+        or resolved.repo_key not in manifest.repos
+    ):
+        raise _error(
+            _SOURCE_NOT_GIT,
+            "development source is not a managed Git checkout.",
+            action=action,
+            detail=locator,
+        )
+    return resolved.repo_key
+
+
+def update_dev_source(request: UpdateDevSourceRequest) -> DevTransactionResult:
+    if not isinstance(request, UpdateDevSourceRequest):
+        raise _error(
+            _REQUEST_INVALID,
+            "update_dev_source requires an UpdateDevSourceRequest.",
+            action="update_dev_source",
+        )
+    action = "update_dev_source"
+    project_dir = _project_root(request.project_dir, action=action)
+    locator = _locators((request.locator,), action=action)[0]
+    manifest = load_dev_manifest(project_dir)
+    if manifest is None:
+        raise _error(
+            _MANIFEST_MISSING,
+            "dev manifest is missing; run pz dev init first.",
+            action=action,
+        )
+    repo_key = _repo_key_for_locator(
+        project_dir,
+        manifest,
+        locator,
+        action=action,
+    )
+    repo = manifest.repos[repo_key]
+    checkout = project_dir / Path(*repo.checkout.parts)
+    if checkout.is_symlink():
+        raise _error(
+            "PZ_DEV_SHARED_CHECKOUT_READ_ONLY",
+            "Shared checkout is externally owned and read-only to PZ authoring commands.",
+            action=action,
+            detail=repo_key,
+        )
+    service = _new_git_service()
+    update = service.update(checkout, expected_branch=manifest.business_app_id)
+    repo_bindings = tuple(
+        key
+        for key, binding in sorted(manifest.bindings.items())
+        if binding.repo_key == repo_key
+    )
+    return DevTransactionResult(
+        operation="update",
+        project_dir=project_dir,
+        business_branch=manifest.business_app_id,
+        base_branch=repo.base_branch,
+        repo_keys=(repo_key,),
+        checkouts=(checkout,),
+        bindings=repo_bindings,
+        links=(),
+        updated=update.updated,
+        upstream=update.upstream,
+    )
+
+
+def _checkout_delete_safety(
+    project_dir: Path,
+    manifest: DevManifest,
+    *,
+    repo_key: str,
+    action: str,
+) -> tuple[DevGitService, Path]:
+    if any(binding.repo_key == repo_key for binding in manifest.bindings.values()):
+        raise _error(
+            "PZ_DEV_CHECKOUT_DELETE_UNSAFE",
+            "checkout still has managed bindings.",
+            action=action,
+            detail=repo_key,
+        )
+    repo = manifest.repos[repo_key]
+    checkout = project_dir / Path(*repo.checkout.parts)
+    service = _new_git_service()
+    if checkout.is_symlink():
+        return service, checkout
+    try:
+        service.preflight_delete(
+            checkout,
+            expected_branch=manifest.business_app_id,
+        )
+    except PzError as exc:
+        raise _error(
+            "PZ_DEV_CHECKOUT_DELETE_UNSAFE",
+            "checkout does not satisfy the deletion safety contract.",
+            action=action,
+            detail=f"repo={repo_key}; reason={exc.code}",
+        ) from exc
+    return service, checkout
+
+
+def _quarantine_checkout(
+    project_dir: Path,
+    checkout: Path,
+    *,
+    transaction_id: str,
+    repo_key: str,
+) -> Path:
+    sources_root = project_dir / "apps" / ".sources"
+    trash_root = sources_root / ".trash" / transaction_id
+    for component in (sources_root, sources_root / ".trash", trash_root):
+        if component.is_symlink():
+            raise RuntimeError("checkout quarantine path contains a symbolic link")
+    trash_root.mkdir(parents=True, exist_ok=False)
+    quarantine = trash_root / repo_key
+    _OS_REPLACE(checkout, quarantine)
+    _fsync_directory(sources_root)
+    return quarantine
+
+
+def _cleanup_quarantine(path: Path) -> None:
+    try:
+        if path.is_symlink():
+            path.unlink()
+        else:
+            shutil.rmtree(path)
+        path.parent.rmdir()
+        path.parent.parent.rmdir()
+    except OSError:
+        # The checkout is already atomically detached from managed state. A later
+        # cleanup may remove the owner-only hidden quarantine.
+        return
+
+
+def remove_dev_source(request: RemoveDevSourceRequest) -> DevTransactionResult:
+    if not isinstance(request, RemoveDevSourceRequest):
+        raise _error(
+            _REQUEST_INVALID,
+            "remove_dev_source requires a RemoveDevSourceRequest.",
+            action="remove_dev_source",
+        )
+    action = "remove_dev_source"
+    project_dir = _project_root(request.project_dir, action=action)
+    binding_key = _locators((request.binding,), action=action)[0]
+    manifest_path = resolve_sources_manifest_path(project_dir)
+    before_bytes = _read_manifest_snapshot(manifest_path)
+    before = load_dev_manifest(project_dir)
+    if before is None or before_bytes is None:
+        raise _error(
+            _MANIFEST_MISSING,
+            "dev manifest is missing; run pz dev init first.",
+            action=action,
+        )
+    binding = before.bindings.get(binding_key)
+    if binding is None:
+        raise _error(
+            "PZ_DEV_BINDING_MISSING",
+            f"managed binding does not exist: {binding_key}",
+            action=action,
+        )
+
+    repos = dict(before.repos)
+    bindings = dict(before.bindings)
+    bindings.pop(binding_key)
+    repo_key = binding.repo_key
+    if request.delete_checkout:
+        if binding.source_kind != "git" or repo_key is None:
+            raise _error(
+                "PZ_DEV_CHECKOUT_DELETE_UNSAFE",
+                "direct-link bindings do not own a managed checkout.",
+                action=action,
+            )
+        if any(candidate.repo_key == repo_key for candidate in bindings.values()):
+            raise _error(
+                "PZ_DEV_CHECKOUT_DELETE_UNSAFE",
+                "checkout still has managed bindings.",
+                action=action,
+                detail=repo_key,
+            )
+        repos.pop(repo_key)
+    desired = DevManifest(
+        schema_version=5,
+        business_app_id=before.business_app_id,
+        repos=repos,
+        bindings=bindings,
+    )
+    validate_dev_manifest(project_dir, desired)
+    removals = plan_binding_removals(project_dir, before, desired)
+    desired_bytes = manifest_bytes(desired)
+    transaction_id = f"pz-{uuid.uuid4().hex}"
+    staged_manifest = manifest_path.with_name(
+        f".{manifest_path.name}.{transaction_id}.tmp"
+    )
+    delete_checkout: Path | None = None
+    if request.delete_checkout:
+        assert repo_key is not None
+        safety_manifest = DevManifest(
+            schema_version=5,
+            business_app_id=before.business_app_id,
+            repos=before.repos,
+            bindings=bindings,
+        )
+        _, delete_checkout = _checkout_delete_safety(
+            project_dir,
+            safety_manifest,
+            repo_key=repo_key,
+            action=action,
+        )
+
+    links_committed = False
+    manifest_committed = False
+    quarantine: Path | None = None
+    try:
+        _write_staged_manifest(staged_manifest, desired_bytes)
+        if _read_manifest_snapshot(manifest_path) != before_bytes:
+            raise _error(
+                "PZ_DEV_MANIFEST_INVALID",
+                "dev manifest changed before binding removal.",
+                action=action,
+            )
+        commit_binding_projection((), removals)
+        links_committed = True
+        _atomic_replace(staged_manifest, manifest_path)
+        _fsync_directory(manifest_path.parent)
+        manifest_committed = True
+        if delete_checkout is not None:
+            assert repo_key is not None
+            quarantine = _quarantine_checkout(
+                project_dir,
+                delete_checkout,
+                transaction_id=transaction_id,
+                repo_key=repo_key,
+            )
+    except BaseException as original:
+        failures: list[Exception] = []
+        if quarantine is not None and delete_checkout is not None:
+            try:
+                _OS_REPLACE(quarantine, delete_checkout)
+            except Exception as exc:
+                failures.append(exc)
+        if manifest_committed:
+            try:
+                _restore_manifest(
+                    manifest_path,
+                    before_bytes=before_bytes,
+                    desired_bytes=desired_bytes,
+                    transaction_id=transaction_id,
+                )
+            except Exception as exc:
+                failures.append(exc)
+        if links_committed:
+            try:
+                rollback_binding_projection((), removals)
+            except Exception as exc:
+                failures.append(exc)
+        staged_manifest.unlink(missing_ok=True)
+        if isinstance(original, PzError) and not failures:
+            raise
+        raise _error(
+            _TRANSACTION_FAILED,
+            "dev source removal transaction failed.",
+            action=action,
+            detail=_failure_detail(
+                original,
+                phase="remove",
+                rollback_failures=failures,
+            ),
+        ) from original
+    finally:
+        staged_manifest.unlink(missing_ok=True)
+
+    if quarantine is not None:
+        _cleanup_quarantine(quarantine)
+    link_path = project_dir / Path(*binding.link.parts)
+    checkout_paths = (
+        ()
+        if repo_key is None
+        else (project_dir / Path(*before.repos[repo_key].checkout.parts),)
+    )
+    return DevTransactionResult(
+        operation="remove",
+        project_dir=project_dir,
+        business_branch=before.business_app_id,
+        base_branch=(
+            before.repos[repo_key].base_branch if repo_key is not None else "develop"
+        ),
+        repo_keys=() if repo_key is None else (repo_key,),
+        checkouts=checkout_paths,
+        bindings=(binding_key,),
+        links=(link_path,),
+        checkout_deleted=delete_checkout is not None,
+    )
+
+
+__all__ = [
+    "AddDevSourceRequest",
+    "BranchDevSourceRequest",
+    "DevTransactionResult",
+    "InitDevSourcesRequest",
+    "RemoveDevSourceRequest",
+    "UpdateDevSourceRequest",
+    "add_dev_source",
+    "branch_dev_source",
+    "initialize_dev_sources",
+    "remove_dev_source",
+    "update_dev_source",
+]