python-ddd-framework 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

python_ddd_framework/background_workers/execution.py

@@ -10,10 +10,10 @@ from uuid import uuid4
 from dishka import AsyncContainer, Scope
 
 from ..application_services.errors import ApplicationInvocationRejectedError
-from ..application_services.invocation import _InvocationRuntime
 from ..authorization import CurrentUser
 from ..background_execution.lifecycle import _TaskExecution
 from ..invocation import BackgroundSystemCaller
+from ..invocation.runtime import _InvocationRuntime
 from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME
 from .contracts import BackgroundWorkerContext, BackgroundWorkerDefinition
 

python_ddd_framework/background_workers/runtime.py

@@ -9,7 +9,6 @@ from collections.abc import Mapping
 from dishka import AsyncContainer
 
 from ..application.build_spec import _ApplicationBuildSpec
-from ..application_services.invocation import _InvocationRuntime
 from ..background_execution import (
     BackgroundExecutionMode,
     BackgroundJobOptions,
@@ -27,6 +26,7 @@ from ..background_execution.processes import _ProcessSlot
 from ..background_jobs import BackgroundJobCatalog
 from ..errors.lifecycle import ApplicationRuntimeError
 from ..invocation import BackgroundSystemCaller
+from ..invocation.runtime import _InvocationRuntime
 from ..lifecycle import RuntimeParticipant, ShutdownReason
 from .catalog import BackgroundWorkerCatalog
 from .contracts import BackgroundExecutionOptions, BackgroundExecutionProfile
@@ -46,7 +46,6 @@ class _BackgroundCoordinator:
                 raise _BackgroundExecutionStartFailure(original_error=error) from error
 
         async def stop(reason: ShutdownReason) -> tuple[BaseException, ...]:
-            await self.stop()
             return ()
 
         async def wait() -> ApplicationRuntimeError:
@@ -62,6 +61,8 @@ class _BackgroundCoordinator:
             prepare=prepare,
             start=start,
             stop=stop,
+            quiesce=self.quiesce,
+            drain=self.stop,
             failure=lambda: wait() if self.has_runtime_failure_source else None,
         )
 
@@ -242,6 +243,14 @@ class _BackgroundCoordinator:
             return slot.request(key, start)
         return self._tasks[key].request(start)
 
+    def quiesce(self) -> None:
+        self._started = False
+        for key, task in self._tasks.items():
+            if key in self._local:
+                task.quiesce()
+        for slot in self._slots.values():
+            slot.quiesce()
+
     async def stop(self) -> None:
         # 即使启动前的预占或 Module 初始化失败，也必须释放已取得的位置。
         operations = [task.shutdown() for key, task in self._tasks.items() if key in self._local]

python_ddd_framework/caching/unit_of_work.py

@@ -21,6 +21,7 @@ class _CachePending:
     async def after_commit(self) -> None:
         failures: list[Exception] = []
         try:
+            # 普通错误继续后项，取消立即传播；逐项 await 保留尚未发送命令的边界。
             for _, apply in self.writes.values():
                 try:
                     await apply()
@@ -40,7 +41,4 @@ class _CacheLifecycleFactory:
 
 
 def _pending(work: UnitOfWork) -> _CachePending:
-    for lifecycle in work._lifecycles:
-        if isinstance(lifecycle, _CachePending):
-            return lifecycle
-    raise RuntimeError("Caching lifecycle is not configured for this UnitOfWork")
+    return work._lifecycle(_CachePending)

python_ddd_framework/cli/project.py

@@ -18,6 +18,16 @@ from .errors import CommandError
 
 HOST_ENTRY_POINT_GROUP = "python_ddd_framework.hosts"
 MODULE_ENTRY_POINT_GROUP = "python_ddd_framework.modules"
+_PROJECT_ENVIRONMENT_OVERRIDES = (
+    "VIRTUAL_ENV",
+    "PYTHONPATH",
+    "PYTHONHOME",
+    "UV_PROJECT_ENVIRONMENT",
+    "UV_PROJECT",
+    "UV_WORKING_DIR",
+    "UV_WORKING_DIRECTORY",
+    "UV_PYTHON",
+)
 
 
 def read_project(path: Path) -> dict[str, Any]:
@@ -117,15 +127,6 @@ class Project:
 def project_environment() -> dict[str, str]:
     # 父进程可能来自 ROS、uv tool 或另一个项目；后端环境由本项目声明和 uv 选择。
     environment = dict(os.environ)
-    for key in (
-        "VIRTUAL_ENV",
-        "PYTHONPATH",
-        "PYTHONHOME",
-        "UV_PROJECT_ENVIRONMENT",
-        "UV_PROJECT",
-        "UV_WORKING_DIR",
-        "UV_WORKING_DIRECTORY",
-        "UV_PYTHON",
-    ):
+    for key in _PROJECT_ENVIRONMENT_OVERRIDES:
         environment.pop(key, None)
     return environment

python_ddd_framework/developer_kit/generation.py

@@ -26,6 +26,7 @@ from ..cli import ENVIRONMENT_VARIABLE
 from ..cli.errors import CommandError
 from ..cli.project import Project, project_environment, read_project
 from .project_metadata import add_module_metadata
+from .publication import _ModulePublication
 from .source import framework_source
 from .wiring import add_dependency
 
@@ -41,8 +42,11 @@ def _name(value: str) -> tuple[str, str]:
     return package, "".join(part.capitalize() for part in package.split("_"))
 
 
-def _render(template: str, context: dict[str, Any]) -> Path:
-    staging = Path(tempfile.mkdtemp(prefix="python-ddd-framework-generation-"))
+def _render(template: str, context: dict[str, Any], *, staging: Path | None = None) -> Path:
+    if staging is None:
+        staging = Path(tempfile.mkdtemp(prefix="python-ddd-framework-generation-"))
+    else:
+        staging.mkdir()
     root = resources.files(__package__).joinpath("templates").joinpath(template)
     with resources.as_file(root) as template_path:
         # Cookiecutter 用相对路径加载；安装目录较深时先复制到短 staging，避免 Windows MAX_PATH。
@@ -152,6 +156,26 @@ def new_project(
 def add_module(name: str, dry_run: bool, *, template: Literal["basic", "ddd"] = "ddd") -> None:
     package, class_prefix = _name(name)
     project = Project.current()
+    if dry_run:
+        _add_module(project, package, class_prefix, template, None)
+    else:
+        with _ModulePublication(project.root, package, template) as publication:
+            _add_module(project, package, class_prefix, template, publication)
+
+
+def _add_module(
+    project: Project,
+    package: str,
+    class_prefix: str,
+    template: Literal["basic", "ddd"],
+    publication: _ModulePublication | None,
+) -> None:
+    destination = project.root / "src" / "modules" / package
+    if destination.exists() or destination.is_symlink():
+        raise CommandError(
+            f"Module destination already exists: {destination}; review retained operations in "
+            f"{project.root / '.python-ddd-framework' / 'generation'}"
+        )
     application = project.host("application").load()(environment="development")
     if not isinstance(application, Application):
         raise CommandError("The application entry point must return Application")
@@ -166,11 +190,8 @@ def add_module(name: str, dry_run: bool, *, template: Literal["basic", "ddd"] =
         raise CommandError(
             "Startup Module source must belong to the current project's src directory"
         )
-    modules = project.root / "src" / "modules"
-    destination = modules / package
-    if destination.exists():
-        raise CommandError(f"Module destination already exists: {destination}")
-    source = source_path.read_text(encoding="utf-8")
+    source_bytes = source_path.read_bytes()
+    source = source_bytes.decode("utf-8")
     updated = source
     entries = (
         ((f"modules.{package}.module", class_prefix + "Module"),)
@@ -187,18 +208,19 @@ def add_module(name: str, dry_run: bool, *, template: Literal["basic", "ddd"] =
     for import_path, class_name in entries:
         updated = add_dependency(updated, startup.__name__, import_path, class_name)
     metadata_path = project.root / "pyproject.toml"
-    metadata_source = metadata_path.read_text(encoding="utf-8")
+    metadata_bytes = metadata_path.read_bytes()
+    metadata_source = metadata_bytes.decode("utf-8")
     alias_path, alias_class = entries[0 if template == "basic" else 1]
     updated_metadata = add_module_metadata(metadata_source, package, f"{alias_path}:{alias_class}")
     ast.parse(updated)
-    if dry_run:
+    if publication is None:
         print(
             f"Would add {destination}, wire modules into {source_path} and update {metadata_path}"
         )
         return
     context = {"module_name": package, "class_prefix": class_prefix}
     if template == "ddd":
-        from ..fastapi.application_services import _operation_id, _service_path
+        from ..fastapi.service_routes import _operation_id, _service_path
 
         # HTTP 身份由正式约定推导；basic 不读取或生成传输层配置。
         http_identity = type(class_prefix + "ApplicationService", (), {})
@@ -206,30 +228,18 @@ def add_module(name: str, dry_run: bool, *, template: Literal["basic", "ddd"] =
             http_service_path=_service_path("", http_identity),
             http_operation_prefix=_operation_id(http_identity, ""),
         )
-    staged = _render(
-        "basic" if template == "basic" else "module",
-        context,
-    )
-    # 先验证全部新文件和接线；已有 startup 文件仅在内容仍等于读取快照时替换。
-    if (
-        source_path.read_text(encoding="utf-8") != source
-        or metadata_path.read_text(encoding="utf-8") != metadata_source
-    ):
-        raise CommandError("Startup source changed during generation; retry after reviewing it")
-    modules.mkdir(exist_ok=True)
-    if not modules.joinpath("__init__.py").exists():
-        modules.joinpath("__init__.py").touch()
-    shutil.copytree(staged, destination)
-    with tempfile.NamedTemporaryFile(
-        mode="w", encoding="utf-8", dir=source_path.parent, delete=False
-    ) as pending:
-        pending.write(updated)
-    Path(pending.name).replace(source_path)
-    metadata_path.write_text(updated_metadata, encoding="utf-8")
-    subprocess.run(
-        ["uv", "sync", "--directory", str(project.root)],
-        cwd=project.root,
-        env=project_environment(),
-        check=True,
-    )
+    with publication.step("render"):
+        staged = _render(
+            "basic" if template == "basic" else "module", context, staging=publication.rendering
+        )
+    with publication.step("prepare"):
+        publication.prepare(
+            staged,
+            (
+                ("startup", source_path, source_bytes, updated.encode("utf-8")),
+                ("metadata", metadata_path, metadata_bytes, updated_metadata.encode("utf-8")),
+            ),
+        )
+    publication.publish(staged)
+    publication.sync()
     print(f"Added {package}; staging retained at {staged}")

python_ddd_framework/developer_kit/publication.py

@@ -0,0 +1,442 @@
+"""一次模块生成的发布现场；记录事实并指导手动恢复，不自动补偿。"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata as metadata
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from types import TracebackType
+from typing import Literal
+from uuid import uuid4
+
+from filelock import FileLock, Timeout
+
+from ..cli.errors import CommandError
+from ..cli.project import _PROJECT_ENVIRONMENT_OVERRIDES, project_environment
+
+
+def _digest(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def _content(path: Path) -> bytes | None:
+    if path.is_symlink() or path.is_junction():
+        raise CommandError(f"Refusing linked publication target: {path}")
+    return path.read_bytes() if path.exists() else None
+
+
+def _tree(root: Path) -> dict[str, str]:
+    if root.is_symlink() or root.is_junction() or not root.is_dir():
+        raise CommandError(f"Expected an ordinary module directory: {root}")
+    result: dict[str, str] = {}
+    directories = [root]
+    # iterdir 的读取错误必须传播；不能把无法枚举的目录当作已完整核对的空目录。
+    while directories:
+        for path in sorted(directories.pop().iterdir()):
+            if path.is_symlink() or path.is_junction():
+                raise CommandError(f"Unexpected link in module directory: {path}")
+            if path.is_dir():
+                result[path.relative_to(root).as_posix()] = "directory"
+                directories.append(path)
+            else:
+                result[path.relative_to(root).as_posix()] = _digest(path.read_bytes())
+    return result
+
+
+@dataclass(frozen=True)
+class _FileChange:
+    name: str
+    target: Path
+    original: bytes | None
+    proposed: bytes
+    pending: Path
+
+
+class _ModulePublication:
+    def __init__(self, root: Path, package: str, template: Literal["basic", "ddd"]) -> None:
+        self.root = root.resolve()
+        self.operation_id = uuid4().hex
+        self.recovery_root = self.root / ".python-ddd-framework" / "generation"
+        self.recovery = self.recovery_root / self.operation_id
+        self.rendering = Path(tempfile.gettempdir()) / f"pddd-add-{self.operation_id}"
+        self.destination = self.root / "src" / "modules" / package
+        self.pending = self.destination.with_name(f".pddd-{self.operation_id}")
+        self.template = template
+        self._lock = FileLock(
+            self.recovery_root.parent / "generation.lock",
+            timeout=0,
+            fallback_to_soft=False,
+            preserve_lock_file=True,
+        )
+        self._changes: tuple[_FileChange, ...] = ()
+        self._module_files: dict[str, str] = {}
+        self._current_step = "prepare"
+
+    def __enter__(self) -> _ModulePublication:
+        try:
+            self._lock.acquire()
+        except Timeout as error:
+            raise CommandError(
+                f"Another module generation owns {self.root}; inspect {self.recovery_root}"
+            ) from error
+        try:
+            print(f"Module recovery files: {self.recovery}", flush=True)
+            self.recovery.mkdir(parents=True)
+            self._write_json(
+                "operation.json",
+                {
+                    "operation_id": self.operation_id,
+                    "project_root": str(self.root),
+                    "distribution": "python-ddd-framework",
+                    "version": metadata.version("python-ddd-framework"),
+                    "template": self.template,
+                    "rendering": str(self.rendering),
+                    "destination": str(self.destination),
+                    "pending_module": str(self.pending),
+                },
+            )
+            self.recovery.joinpath("RECOVERY.md").write_text(
+                _RECOVERY.replace("<RECOVERY_PATH>", repr(self.recovery.as_posix())),
+                encoding="utf-8",
+            )
+        except BaseException:
+            self._lock.release()
+            print(f"Preparation failed; retained files: {self.recovery}", file=sys.stderr)
+            raise
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:
+            if exc is not None:
+                self._report_failure(exc)
+        finally:
+            self._lock.release()
+
+    def _write_json(self, name: str, value: object) -> None:
+        # 计划只写一次；写入失败留下原片段，不能带着不完整计划开始发布。
+        with self.recovery.joinpath(name).open("x", encoding="utf-8") as stream:
+            json.dump(value, stream, ensure_ascii=True, indent=2)
+            stream.write("\n")
+
+    def _record(self, step: str, state: str, *, returncode: int | None = None) -> None:
+        with self.recovery.joinpath("steps.jsonl").open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps({"step": step, "state": state, "returncode": returncode}))
+            stream.write("\n")
+
+    @contextmanager
+    def step(self, name: str) -> Iterator[None]:
+        self._current_step = name
+        self._record(name, "started")
+        yield
+        self._record(name, "completed")
+
+    def prepare(self, staged: Path, changes: tuple[tuple[str, Path, bytes, bytes], ...]) -> None:
+        modules = self.destination.parent
+        if modules.is_symlink() or modules.is_junction():
+            raise CommandError(f"Refusing linked modules directory: {modules}")
+        marker = modules / "__init__.py"
+        marker_original = _content(marker)
+        marker_change = (
+            (("package_marker", marker, marker_original, marker_original or b""),)
+            if all(path != marker for _, path, _, _ in changes)
+            else ()
+        )
+        self._changes = tuple(
+            _FileChange(
+                name,
+                path,
+                original,
+                proposed,
+                path.with_name(f".pddd-{self.operation_id}-{name}"),
+            )
+            for name, path, original, proposed in (
+                *marker_change,
+                *changes,
+            )
+        )
+        self._module_files = _tree(staged)
+        originals = self.recovery / "original"
+        proposed = self.recovery / "proposed"
+        originals.mkdir()
+        proposed.mkdir()
+        files: list[dict[str, object]] = []
+        for change in self._changes:
+            original = originals / change.name
+            generated = proposed / change.name
+            if change.original is not None:
+                original.write_bytes(change.original)
+            generated.write_bytes(change.proposed)
+            files.append(
+                {
+                    "step": change.name,
+                    "target": str(change.target),
+                    "pending": str(change.pending),
+                    "original": str(original) if change.original is not None else None,
+                    "original_sha256": (
+                        _digest(change.original) if change.original is not None else None
+                    ),
+                    "proposed": str(generated),
+                    "proposed_sha256": _digest(change.proposed),
+                }
+            )
+        self._write_json(
+            "plan.json",
+            {
+                "module_source": str(staged),
+                "module_target": str(self.destination),
+                "module_pending": str(self.pending),
+                "module_files": self._module_files,
+                "modules_directory": str(modules),
+                "modules_directory_existed": modules.exists(),
+                "files": files,
+                "publish_order": ["module", *(change.name for change in self._changes)],
+                "sync_command": ["uv", "sync", "--directory", str(self.root)],
+                # 保存完整策略，重试前才出现的覆盖也必须清理；不保存环境变量值。
+                "sync_environment_unset": _PROJECT_ENVIRONMENT_OVERRIDES,
+                "sync_log": str(self.recovery / "uv-sync.log"),
+            },
+        )
+        self._check_originals()
+
+    def _check_originals(self) -> None:
+        modules = self.destination.parent
+        if modules.is_symlink() or modules.is_junction():
+            raise CommandError(f"Modules directory changed to a link: {modules}")
+        if self.destination.exists() or self.destination.is_symlink():
+            raise CommandError(f"Module destination already exists: {self.destination}")
+        for change in self._changes:
+            if _content(change.target) != change.original:
+                raise CommandError(f"Content changed during generation: {change.target}")
+
+    def publish(self, staged: Path) -> None:
+        with self.step("local_copy"):
+            self._check_originals()
+            self.destination.parent.mkdir(exist_ok=True)
+            shutil.copytree(staged, self.pending)
+            for change in self._changes:
+                # 包标记用独占创建；原有文件的待发布副本与目标处于同一文件系统。
+                if change.name == "package_marker":
+                    continue
+                with change.pending.open("xb") as stream:
+                    stream.write(change.proposed)
+                shutil.copymode(change.target, change.pending)
+            if _tree(self.pending) != self._module_files:
+                raise CommandError(f"Incomplete module copy: {self.pending}")
+        with self.step("module"):
+            self._check_originals()
+            self.pending.rename(self.destination)
+        for change in self._changes:
+            with self.step(change.name):
+                if _content(change.target) != change.original:
+                    raise CommandError(f"Content changed during generation: {change.target}")
+                if change.name == "package_marker":
+                    if change.original is None:
+                        with change.target.open("xb") as stream:
+                            stream.write(change.proposed)
+                else:
+                    if _content(change.pending) != change.proposed:
+                        raise CommandError(f"Pending content changed: {change.pending}")
+                    change.pending.replace(change.target)
+        with self.step("files_published"):
+            if self.file_states() != dict.fromkeys(
+                ("module", *(change.name for change in self._changes)), "published"
+            ):
+                raise CommandError("Published files no longer match the generation plan")
+
+    def sync(self) -> None:
+        command = ["uv", "sync", "--directory", str(self.root)]
+        self._current_step = "sync"
+        self._record("sync", "started")
+        with self.recovery.joinpath("uv-sync.log").open("xb") as log:
+            result = subprocess.run(
+                command,
+                cwd=self.root,
+                env=project_environment(),
+                stdout=log,
+                stderr=subprocess.STDOUT,
+                check=False,
+            )
+        self._record(
+            "sync",
+            "completed" if result.returncode == 0 else "failed",
+            returncode=result.returncode,
+        )
+        result.check_returncode()
+
+    def file_states(self) -> dict[str, str]:
+        """日志可能停在写后记录之前，诊断必须重新读取磁盘内容。"""
+        if not self._changes:
+            return {"publication": "not_started"}
+        states: dict[str, str] = {}
+        try:
+            self.destination.lstat()
+        except FileNotFoundError:
+            states["module"] = "not_published"
+        except OSError:
+            states["module"] = "unknown/conflict"
+        else:
+            try:
+                states["module"] = (
+                    "published"
+                    if _tree(self.destination) == self._module_files
+                    else "unknown/conflict"
+                )
+            except (OSError, CommandError):
+                states["module"] = "unknown/conflict"
+        for change in self._changes:
+            try:
+                content = _content(change.target)
+                states[change.name] = (
+                    "published"
+                    if content == change.proposed
+                    else "not_published"
+                    if content == change.original
+                    else "unknown/conflict"
+                )
+            except (OSError, CommandError):
+                states[change.name] = "unknown/conflict"
+        return states
+
+    def _report_failure(self, error: BaseException) -> None:
+        try:
+            self._record(
+                self._current_step,
+                "interrupted" if isinstance(error, KeyboardInterrupt) else "failed",
+            )
+        except OSError as record_error:
+            print(
+                f"Could not record failure ({type(record_error).__name__}); inspect disk contents.",
+                file=sys.stderr,
+            )
+        print(
+            f"Module generation stopped at {self._current_step}; "
+            f"disk state: {self.file_states()}.\n"
+            f"All remaining files are retained. Review {self.recovery / 'RECOVERY.md'}; "
+            f"rendering: {self.rendering}.\n"
+            "After confirming all published contents, use the isolated uv sync retry "
+            "in RECOVERY.md.",
+            file=sys.stderr,
+            flush=True,
+        )
+
+
+_RECOVERY = """# Manual module recovery
+
+Keep this directory and every path recorded in operation.json / plan.json.
+No rollback or cleanup was performed. Stop other generators, editors and uv processes
+before inspecting or changing the project. The generator lock does not lock editors.
+
+## Inspect first
+
+operation.json identifies the backend, CLI/template version and rendering location.
+plan.json records exact original/proposed copies, SHA-256 digests, module directory
+entries, pending paths, prior directory/marker existence and publication order.
+It also records the sync command and the environment overrides to clear for that command.
+steps.jsonl records intent before each action and completion afterwards; a missing or
+partial final line does not prove the action failed. uv-sync.log contains install output.
+A complete plan is required before publication. If plan.json is missing or unreadable,
+stop recovery and inspect retained copies and actual targets; do not infer that nothing
+was written. Retain any partial preparation files.
+
+Save this read-only inspection outside the project, then run `python -I <inspection-file>`
+with Python 3.12 or newer:
+
+```python
+import hashlib, json
+from pathlib import Path
+recovery = Path(<RECOVERY_PATH>)
+plan = json.loads((recovery / "plan.json").read_text(encoding="utf-8"))
+for item in plan["files"]:
+    path = Path(item["target"])
+    linked = path.is_symlink() or path.is_junction()
+    actual = None
+    if path.is_file() and not linked:
+        actual = hashlib.sha256(path.read_bytes()).hexdigest()
+    state = "UNKNOWN - inspect before editing"
+    if not linked and (path.is_file() or not path.exists()):
+        if actual == item["proposed_sha256"]:
+            state = "published"
+        elif actual == item["original_sha256"]:
+            state = "original"
+    print(item["step"], path, state, "actual:", actual)
+module = Path(plan["module_target"])
+actual = {}
+directories = [module] if module.is_dir() else []
+while directories:
+    for path in directories.pop().iterdir():
+        if path.is_symlink() or path.is_junction():
+            value = "UNKNOWN LINK"
+        elif path.is_dir():
+            value = "directory"
+            directories.append(path)
+        else:
+            value = hashlib.sha256(path.read_bytes()).hexdigest()
+        actual[path.relative_to(module).as_posix()] = value
+print("module missing:", not module.exists())
+print("module root is linked:", module.is_symlink() or module.is_junction())
+for key in actual.keys() | plan["module_files"].keys():
+    if actual.get(key) != plan["module_files"].get(key):
+        print("module difference:", key)
+print("Inspect all links and unknown files manually; never overwrite them.")
+```
+
+## Choose and perform each step manually
+
+1. Compare the complete module tree (including extra files, directories and links)
+   with module_files and module_source. A matching target is already published.
+   If absent, review the complete staged copy before manually copying to that absent
+   target. Stop on partial content, any link, extra file or differing digest.
+2. Inspect files in publish_order: package_marker, startup, metadata. An unchanged
+   original marker is retained. Create a missing marker only when recorded as absent.
+   For startup / metadata, continue only while target equals original_sha256; use
+   the proposed copy named in plan.json. For a manual rollback, restore the original
+   copy only while target equals proposed_sha256. Verify the copy's digest as well.
+   Prepare a complete sibling file, recheck the target, then replace that one file.
+   Any different content is a conflict: review the diff and decide what to keep.
+3. Leave generated modules, markers, pending files and recovery directories in place.
+   Removing or moving any path is a separate explicit decision. Do not rerun add module
+   to repair a partially published operation or overwrite an existing destination.
+4. Once every target matches the proposed contents, use the isolated sync retry below.
+   A missing success record means installation is unconfirmed. uv may already have
+   changed uv.lock or the environment; neither is automatically rolled back.
+
+Single-file replacement is not a transaction across files. External edits can race
+with checks; this record does not promise power-loss durability or automatic recovery.
+
+## Retry installation independently
+
+Save this script outside the project, then run `python -I <retry-file>` with Python 3.12
+or newer. It runs only uv sync in the recorded backend. The -I option isolates Python
+from external Python settings; the script clears the same overrides as the CLI from
+the child environment, including overrides added after generation. The current shell
+environment is preserved. No framework import or working backend environment is needed.
+Check the process exit status and output; the original operation records remain unchanged.
+
+```python
+import json, os, subprocess
+from pathlib import Path
+recovery = Path(<RECOVERY_PATH>)
+operation = json.loads((recovery / "operation.json").read_text(encoding="utf-8"))
+plan = json.loads((recovery / "plan.json").read_text(encoding="utf-8"))
+environment = dict(os.environ)
+for key in plan["sync_environment_unset"]:
+    environment.pop(key, None)
+result = subprocess.run(
+    plan["sync_command"], cwd=operation["project_root"], env=environment, check=False
+)
+raise SystemExit(result.returncode)
+```
+"""