cf-bootstrap-instance 0.1.8__py3-none-any.whl

cf_bootstrap_instance/provider.py

@@ -0,0 +1,671 @@
+"""External JSON-lines instance apply provider."""
+
+from __future__ import annotations
+
+import configparser
+import hashlib
+import json
+from email.parser import BytesParser
+import os
+import re
+from pathlib import Path
+import secrets
+import shutil
+import stat
+import tempfile
+import time
+import zipfile
+
+from .install import create_environment, install, prepare_launchers, remove_build_tools
+from .layout import atomic_write, read_marker, validate_root
+from .model import InstanceError, PROTOCOL, RESULT_SCHEMA, RESULT_SCHEMA_V2, canonical_json, digest, marker, marker_v2, parse_request
+from .verify import inventory
+
+
+def _lock(stream: object, acquire: bool) -> None:
+    if os.name == "nt":
+        import msvcrt
+        stream.seek(0)
+        msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK if acquire else msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl
+        fcntl.flock(stream.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB if acquire else fcntl.LOCK_UN)
+
+
+def _open_lock(path: Path) -> object:
+    """Open the persistent lock without following a path-level redirect."""
+    flags = os.O_RDWR | os.O_CREAT
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    try:
+        before = os.lstat(path)
+    except FileNotFoundError:
+        before = None
+    except OSError as error:
+        raise InstanceError("LOCK_INVALID", "lifecycle lock cannot be inspected") from error
+    if before is not None:
+        if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode) or _is_reparse(before):
+            raise InstanceError("LOCK_INVALID", "lifecycle lock is not a regular non-link file")
+        if os.name != "nt" and before.st_mode & 0o077:
+            raise InstanceError("LOCK_INVALID", "lifecycle lock permissions are too broad")
+    try:
+        descriptor = os.open(os.fspath(path), flags | nofollow, 0o600)
+    except OSError as error:
+        raise InstanceError("LOCK_INVALID", "lifecycle lock cannot be opened safely") from error
+    try:
+        after = os.fstat(descriptor)
+        current = os.lstat(path)
+        if not stat.S_ISREG(after.st_mode) or stat.S_ISLNK(current.st_mode) or not stat.S_ISREG(current.st_mode) or _is_reparse(current) or (after.st_dev, after.st_ino) != (current.st_dev, current.st_ino):
+            raise InstanceError("LOCK_INVALID", "lifecycle lock changed during safe open")
+        if os.name != "nt" and after.st_mode & 0o077:
+            raise InstanceError("LOCK_INVALID", "lifecycle lock permissions are too broad")
+        return os.fdopen(descriptor, "a+b")
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _is_reparse(value: os.stat_result) -> bool:
+    return os.name == "nt" and bool(getattr(value, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
+
+
+def _same_path(left: Path | str, right: Path | str) -> bool:
+    left_path = os.path.normcase(os.fspath(Path(left).resolve(strict=False)))
+    right_path = os.path.normcase(os.fspath(Path(right).resolve(strict=False)))
+    return left_path == right_path
+
+
+_SAFE_LAUNCHER_NAME = re.compile(r"[A-Za-z0-9._-]+\Z")
+
+
+def _safe_launcher_name(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or value != value.strip() or not _SAFE_LAUNCHER_NAME.fullmatch(value) or Path(value).name != value or value in {".", ".."}:
+        raise InstanceError("ARTIFACT_INVALID", f"{label} is unsafe")
+    return value
+
+
+def _regular(path: Path, label: str, directory: bool = False) -> None:
+    current = path
+    while current != Path(current.anchor):
+        try:
+            value = os.lstat(current)
+        except FileNotFoundError:
+            current = current.parent
+            continue
+        if stat.S_ISLNK(value.st_mode) or (os.name == "nt" and bool(getattr(value, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))):
+            raise InstanceError("ARTIFACT_INVALID", f"{label} contains a link or reparse point")
+        current = current.parent
+    if path.is_symlink() or not (path.is_dir() if directory else path.is_file()):
+        raise InstanceError("ARTIFACT_INVALID", f"{label} is missing or unsafe")
+    if os.name == "nt" and bool(getattr(path.lstat(), "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)):
+        raise InstanceError("ARTIFACT_INVALID", f"{label} is a reparse point")
+
+
+def _launcher_script_name(target_name: str) -> str:
+    return _safe_launcher_name(target_name, "launcher target") + (".exe" if os.name == "nt" else "")
+
+
+def _launcher_retained_name(target_name: str) -> str:
+    suffix = ".exe" if os.name == "nt" else ""
+    return f"launcher-{_safe_launcher_name(target_name, 'launcher target')}{suffix}"
+
+
+def _launcher_targets(wheelhouse: Path, artifacts: list[dict[str, object]]) -> list[str]:
+    targets: list[str] = []
+    seen: set[str] = set()
+    for item in artifacts:
+        wheel = wheelhouse / str(item["filename"])
+        try:
+            _regular(wheel, "recovery wheel")
+            with zipfile.ZipFile(wheel) as archive:
+                entry_points = [entry for entry in archive.namelist() if entry.endswith(".dist-info/entry_points.txt")]
+                if len(entry_points) > 1:
+                    raise ValueError("launcher metadata is incomplete")
+                if not entry_points:
+                    continue
+                parser = configparser.ConfigParser(interpolation=None)
+                parser.optionxform = str
+                parser.read_string(archive.read(entry_points[0]).decode("utf-8"))
+        except (OSError, UnicodeDecodeError, ValueError, zipfile.BadZipFile, KeyError, configparser.Error) as error:
+            raise InstanceError("ARTIFACT_INVALID", f"recovery launcher metadata is invalid: {wheel.name}") from error
+        if not parser.has_section("console_scripts"):
+            continue
+        for target_name, _target_value in parser.items("console_scripts", raw=True):
+            target_name = _safe_launcher_name(target_name, "recovery launcher target")
+            key = target_name.casefold()
+            if key in seen:
+                raise InstanceError("ARTIFACT_INVALID", "recovery launcher names are duplicated or invalid")
+            seen.add(key)
+            targets.append(target_name)
+    return sorted(targets)
+
+
+def _launcher_collision_keys(names: set[str]) -> set[str]:
+    return {name.casefold() for name in names}
+
+
+def _launcher_images(scripts: Path, target_names: list[str], wheel_names: set[str]) -> list[dict[str, object]]:
+    records: list[dict[str, object]] = []
+    retained_names: set[str] = set()
+    wheel_collision_names = _launcher_collision_keys(wheel_names)
+    for target_name in target_names:
+        retained_name = _launcher_retained_name(target_name)
+        retained_key = retained_name.casefold()
+        if retained_key in retained_names or retained_key in wheel_collision_names or retained_name == "recovery-manifest.json":
+            raise InstanceError("ARTIFACT_INVALID", "recovery launcher filenames collide")
+        source = scripts / _launcher_script_name(target_name)
+        if source.is_symlink() or not source.is_file():
+            raise InstanceError("ARTIFACT_INVALID", f"recovery launcher is missing: {source.name}")
+        stat_result = source.lstat()
+        if _is_reparse(stat_result):
+            raise InstanceError("ARTIFACT_INVALID", f"recovery launcher is unsafe: {source.name}")
+        data = source.read_bytes()
+        records.append({"target_launcher": target_name, "retained_filename": retained_name, "size": stat_result.st_size, "sha256": hashlib.sha256(data).hexdigest(), "mode": stat.S_IMODE(stat_result.st_mode)})
+        retained_names.add(retained_key)
+    return sorted(records, key=lambda item: (str(item["target_launcher"]), str(item["retained_filename"])))
+
+
+def _validate_launcher_images(bundle: Path, launcher_images: object, target_names: list[str], wheel_names: set[str]) -> list[dict[str, object]]:
+    if not isinstance(launcher_images, list):
+        raise InstanceError("ARTIFACT_INVALID", "recovery launcher metadata is invalid")
+    expected_targets = {name.casefold() for name in target_names}
+    wheel_collision_names = _launcher_collision_keys(wheel_names)
+    if len(launcher_images) != len(expected_targets):
+        raise InstanceError("ARTIFACT_INVALID", "recovery launcher metadata is incomplete")
+    records: list[dict[str, object]] = []
+    seen_targets: set[str] = set()
+    seen_retained: set[str] = set()
+    for raw in launcher_images:
+        if not isinstance(raw, dict) or set(raw) != {"target_launcher", "retained_filename", "size", "sha256", "mode"}:
+            raise InstanceError("ARTIFACT_INVALID", "recovery launcher metadata is invalid")
+        target = _safe_launcher_name(raw["target_launcher"], "launcher target")
+        retained = _safe_launcher_name(raw["retained_filename"], "retained launcher filename")
+        retained_key = retained.casefold()
+        if retained != _launcher_retained_name(target) or retained_key in wheel_collision_names or retained == "recovery-manifest.json":
+            raise InstanceError("ARTIFACT_INVALID", "recovery launcher filenames collide")
+        target_key = target.casefold()
+        if target_key in seen_targets or retained_key in seen_retained:
+            raise InstanceError("ARTIFACT_INVALID", "recovery launcher names are duplicated or invalid")
+        if target_key not in expected_targets:
+            raise InstanceError("ARTIFACT_INVALID", "recovery launcher names are outside the accepted set")
+        path = bundle / retained
+        _regular(path, "retained launcher image")
+        stat_result = path.lstat()
+        data = path.read_bytes()
+        if type(raw["size"]) is not int or type(raw["mode"]) is not int or raw["size"] != len(data) or raw["sha256"] != hashlib.sha256(data).hexdigest() or stat.S_IMODE(stat_result.st_mode) != raw["mode"]:
+            raise InstanceError("ARTIFACT_INVALID", "retained launcher image is invalid")
+        seen_targets.add(target_key)
+        seen_retained.add(retained_key)
+        records.append({"target_launcher": target, "retained_filename": retained, "size": raw["size"], "sha256": raw["sha256"], "mode": raw["mode"], "bundle": str(path)})
+    if seen_targets != expected_targets:
+        raise InstanceError("ARTIFACT_INVALID", "recovery launcher metadata is incomplete")
+    return sorted(records, key=lambda item: (str(item["target_launcher"]), str(item["retained_filename"])))
+
+
+_OPERATION_SCHEMA = "cf.bootstrap.instance-operation.v1"
+_OWNER_NAME = ".cogniflow-staging-owner.json"
+
+
+def _operation_path(root: Path) -> Path:
+    return root.parent / f".{root.name}.operation.json"
+
+
+def _operation_value(root: Path, staging: Path, plan_digest: str, artifact_digest: str) -> dict[str, str]:
+    return {"schema": _OPERATION_SCHEMA, "installation_root": str(root.resolve(strict=False)), "staging_root": str(staging.resolve(strict=False)), "operation_token": secrets.token_hex(32), "plan_digest": plan_digest, "artifact_set_digest": artifact_digest}
+
+
+def _safe_read(path: Path) -> tuple[dict[str, object], bytes]:
+    try:
+        before = os.lstat(path)
+        if not stat.S_ISREG(before.st_mode) or _is_reparse(before) or (os.name != "nt" and before.st_mode & 0o077):
+            raise InstanceError("CLEANUP_FAILED", "ownership record is not a regular file")
+        descriptor = os.open(os.fspath(path), os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+        try:
+            after = os.fstat(descriptor)
+            if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino) or not stat.S_ISREG(after.st_mode) or _is_reparse(after) or (os.name != "nt" and after.st_mode & 0o077):
+                raise InstanceError("CLEANUP_FAILED", "ownership record changed during read")
+            raw = os.read(descriptor, 1024 * 1024)
+        finally:
+            os.close(descriptor)
+        value = json.loads(raw)
+    except InstanceError:
+        raise
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise InstanceError("CLEANUP_FAILED", f"ownership record is unreadable: {type(error).__name__}: {error}") from error
+    if not isinstance(value, dict) or raw != canonical_json(value):
+        raise InstanceError("CLEANUP_FAILED", "ownership record is not canonical")
+    return value, raw
+
+
+def _safe_create(path: Path, data: bytes) -> None:
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(os.fspath(path), flags, 0o600)
+        try:
+            os.write(descriptor, data)
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    except FileExistsError as error:
+        raise InstanceError("CLEANUP_FAILED", "ownership record already exists") from error
+    except OSError as error:
+        raise InstanceError("CLEANUP_FAILED", "ownership record could not be created") from error
+
+
+def _safe_unlink(path: Path) -> None:
+    if not os.path.lexists(path):
+        return
+    _safe_read(path)
+    try:
+        path.unlink()
+    except OSError as error:
+        raise InstanceError("CLEANUP_FAILED", "ownership record could not be cleared") from error
+
+
+def _validate_operation(value: dict[str, object], root: Path, staging: Path | None, plan_digest: str, artifact_digest: str) -> Path:
+    expected_root = root.resolve(strict=False)
+    if set(value) != {"schema", "installation_root", "staging_root", "operation_token", "plan_digest", "artifact_set_digest"} or value.get("schema") != _OPERATION_SCHEMA or not _same_path(str(value["installation_root"]), expected_root) or value["plan_digest"] != plan_digest or value["artifact_set_digest"] != artifact_digest:
+        raise InstanceError("CLEANUP_FAILED", "ownership record is not bound to this operation")
+    token = value["operation_token"]
+    if not isinstance(token, str) or len(token) != 64 or any(char not in "0123456789abcdef" for char in token):
+        raise InstanceError("CLEANUP_FAILED", "ownership token is invalid")
+    recorded = Path(str(value["staging_root"]))
+    if not recorded.is_absolute() or not _same_path(recorded.parent, expected_root.parent) or not recorded.name.startswith(f".{root.name}.staging-") or (staging is not None and not _same_path(recorded, staging)):
+        raise InstanceError("CLEANUP_FAILED", "staging path is not bound to the final root")
+    return recorded
+
+
+def _validate_owner(staging: Path, value: dict[str, object], plan_digest: str, artifact_digest: str) -> None:
+    if staging.is_symlink() or not staging.is_dir() or _is_reparse(os.lstat(staging)):
+        raise InstanceError("CLEANUP_FAILED", "owned staging root is not a real directory")
+    owner, _ = _safe_read(staging / _OWNER_NAME)
+    if owner != value or owner["plan_digest"] != plan_digest or owner["artifact_set_digest"] != artifact_digest:
+        raise InstanceError("CLEANUP_FAILED", "staging owner marker does not match operation record")
+
+
+def _delete_owned(staging: Path, value: dict[str, object], plan_digest: str, artifact_digest: str) -> None:
+    _validate_owner(staging, value, plan_digest, artifact_digest)
+    _cleanup_staging(staging)
+
+
+def _recover_staging(root: Path, record_path: Path, plan_digest: str, artifact_digest: str) -> None:
+    lookalikes = list(root.parent.glob(f".{root.name}.staging-*"))
+    if not os.path.lexists(record_path):
+        if lookalikes:
+            raise InstanceError("CLEANUP_FAILED", "unowned staging lookalike exists")
+        return
+    record, _ = _safe_read(record_path)
+    staging = _validate_operation(record, root, None, plan_digest, artifact_digest)
+    marker_path = root / ".cogniflow-instance.json"
+    if root.exists():
+        if not marker_path.is_file():
+            raise InstanceError("CLEANUP_FAILED", "owned operation conflicts with an unbound root")
+        marker, _ = read_marker(marker_path)
+        if not _same_path(str(marker["installation_root"]), root) or marker["plan_digest"] != plan_digest or marker["artifact_set_digest"] != artifact_digest or os.path.lexists(staging):
+            raise InstanceError("CLEANUP_FAILED", "stale ownership record conflicts with final root")
+        _safe_unlink(record_path)
+        return
+    _delete_owned(staging, record, plan_digest, artifact_digest)
+    _safe_unlink(record_path)
+
+
+def _cleanup_staging(path: Path) -> None:
+    if not path.exists():
+        return
+    if os.environ.get("CF_BOOTSTRAP_TEST_CLEANUP_FAILURE") == "1":
+        raise InstanceError("CLEANUP_FAILED", "injected staging cleanup failure")
+    try:
+        shutil.rmtree(path)
+    except OSError as error:
+        raise InstanceError("CLEANUP_FAILED", "staging root could not be removed") from error
+
+
+def _test_abort(boundary: str) -> None:
+    if os.environ.get("CF_BOOTSTRAP_TEST_PAUSE_AT") == boundary:
+        ready = Path(os.environ["CF_BOOTSTRAP_TEST_PAUSE_FILE"])
+        ready.write_text("ready\n", encoding="utf-8")
+        release = ready.with_suffix(".release")
+        while not release.exists():
+            time.sleep(0.01)
+    if os.environ.get("CF_BOOTSTRAP_TEST_ABORT_AT") == boundary:
+        os._exit(97)
+    if os.environ.get("CF_BOOTSTRAP_TEST_FAIL_AT") == boundary:
+        raise InstanceError("TEST_FAILURE", "injected transaction failure")
+
+
+def _response(identifier: object, **body: object) -> dict[str, object]:
+    return {"jsonrpc": "2.0", "protocol": PROTOCOL, "id": identifier, **body}
+
+
+def _validate_wheelhouse_metadata(wheelhouse: Path, artifact_set: dict[str, object], mode: str) -> None:
+    manifest = wheelhouse / "artifact-set.json"
+    if manifest.is_symlink() or not manifest.is_file():
+        raise InstanceError("ARTIFACT_INVALID", "wheelhouse artifact-set.json is missing or unsafe")
+    try:
+        raw = manifest.read_bytes()
+        parsed = json.loads(raw)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise InstanceError("ARTIFACT_INVALID", "wheelhouse artifact-set.json is invalid") from error
+    if raw != canonical_json(parsed) or parsed != artifact_set:
+        raise InstanceError("ARTIFACT_INVALID", "wheelhouse artifact-set.json is not bound to the request")
+    expected_lines = [f"{item['normalized_distribution']}=={item['version']} --hash=sha256:{item['sha256']}" for item in artifact_set["artifacts"]]
+    if mode == "pypi":
+        lock = wheelhouse / "requirements.lock"
+        if lock.is_symlink() or not lock.is_file():
+            raise InstanceError("ARTIFACT_INVALID", "wheelhouse requirements.lock is missing or unsafe")
+        lock_bytes = lock.read_bytes()
+        if hashlib.sha256(lock_bytes).hexdigest() != artifact_set["lock_sha256"]:
+            raise InstanceError("ARTIFACT_INVALID", "requirements.lock hash does not match artifact set")
+        expected_lock = ("\n".join(expected_lines) + "\n").encode("utf-8")
+        if lock_bytes != expected_lock:
+            raise InstanceError("ARTIFACT_INVALID", "requirements.lock does not exactly match artifact set")
+
+
+def apply(params: object, *, recovery_authority: tuple[dict[str, object], dict[str, object], Path] | None = None) -> dict[str, object]:
+    plan, resolution, root = parse_request(params)
+    if plan.get("schema") == "cf.bootstrap.plan.v2":
+        return _apply_v2(plan, resolution, root)
+    artifact_set = resolution["artifact_set"]
+    wheelhouse = Path(str(resolution["wheelhouse_path"])).absolute()
+    source = plan["artifact_source"]
+    checkout = Path(source["checkout_path"]).absolute() if isinstance(source, dict) and source.get("mode") == "local-repository" else None
+    validate_root(root, checkout, wheelhouse, Path(plan["cogniflow_home"]))
+    if not wheelhouse.is_dir() or wheelhouse.is_symlink():
+        raise InstanceError("ARTIFACT_INVALID", "wheelhouse is not a real directory")
+    root.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = root.parent / f".{root.name}.lifecycle.lock"
+    record_path = _operation_path(root)
+    stream = None
+    acquired = False
+    staging: Path | None = None
+    owner_removed = False
+    try:
+        try:
+            stream = _open_lock(lock_path)
+            stream.seek(0, os.SEEK_END)
+            if stream.tell() == 0:
+                stream.write(b"0")
+                stream.flush()
+            _lock(stream, True)
+            acquired = True
+        except (OSError, BlockingIOError) as error:
+            raise InstanceError("INSTANCE_LOCKED", "instance lifecycle lock is held") from error
+        _recover_staging(root, record_path, digest(plan), digest(artifact_set))
+        marker_path = root / ".cogniflow-instance.json"
+        if root.exists() and not marker_path.is_file():
+            raise InstanceError("ROOT_CONFLICT", "existing installation root contains foreign files")
+        _validate_wheelhouse_metadata(wheelhouse, artifact_set, plan["artifact_source"]["mode"])
+        if root.exists() and marker_path.is_file():
+            current, _ = read_marker(marker_path)
+            if current["plan_digest"] != digest(plan):
+                raise InstanceError("PLAN_CONFLICT", "existing instance belongs to another plan")
+            if current["artifact_set_digest"] != digest(artifact_set):
+                raise InstanceError("ARTIFACT_SET_CONFLICT", "existing instance belongs to another artifact set")
+            environment = Path(str(current["environment_root"]))
+            executable = Path(str(current["python_executable"]))
+            if not _same_path(str(current["installation_root"]), root) or not _same_path(environment, root / "environment") or environment.is_symlink() or not _same_path(executable, environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")) or not executable.is_file():
+                raise InstanceError("VENV_INVALID", "existing instance is not root-bound")
+            installed = inventory(executable, environment, artifact_set, checkout)
+            if current["installed_distributions"] != installed:
+                raise InstanceError("VERIFY_FAILED", "existing marker inventory differs from target")
+            return {"schema": RESULT_SCHEMA, "status": "unchanged", "marker": str(marker_path), "installation_root": str(root), "environment_root": str(environment), "python_executable": str(executable), "installed_distributions": installed}
+        expected_wheels = {item["filename"] for item in artifact_set["artifacts"]}
+        allowed = expected_wheels | {"artifact-set.json"}
+        if plan["artifact_source"]["mode"] == "pypi":
+            allowed.add("requirements.lock")
+        children = list(wheelhouse.iterdir())
+        if any(child.is_symlink() or child.is_dir() for child in children) or {child.name for child in children} != allowed:
+            raise InstanceError("ARTIFACT_INVALID", "wheelhouse contains unexpected entries")
+        staging = Path(tempfile.mkdtemp(prefix=f".{root.name}.staging-", dir=root.parent))
+        try:
+            operation = _operation_value(root, staging, digest(plan), digest(artifact_set))
+            _safe_create(record_path, canonical_json(operation))
+            _safe_create(staging / _OWNER_NAME, canonical_json(operation))
+            _test_abort("staging")
+            environment = staging / "environment"
+            temp_dir = staging / "temp"
+            temp_dir.mkdir()
+            executable = create_environment(environment, temp_dir)
+            _test_abort("venv")
+            install(executable, wheelhouse, artifact_set, temp_dir)
+            _test_abort("install")
+            final_executable = root / "environment" / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+            prepare_launchers(executable, final_executable)
+            _test_abort("launchers")
+            remove_build_tools(executable)
+            installed = inventory(executable, environment, artifact_set, checkout)
+            _test_abort("verify")
+            _cleanup_staging(temp_dir)
+            (staging / "state").mkdir()
+            (staging / "logs").mkdir()
+            _test_abort("state")
+            if recovery_authority is None:
+                marker_value = marker(plan, artifact_set, root, root / "environment", final_executable, installed)
+            else:
+                accepted_plan, accepted_artifact_set, accepted_wheelhouse = recovery_authority
+                recovery_path, recovery_digest = _retain_recovery_bundle(staging, root, accepted_wheelhouse, accepted_artifact_set, accepted_plan, executable, final_executable)
+                marker_value = marker_v2(accepted_plan, accepted_artifact_set, root, root / "environment", final_executable, installed, recovery_path, recovery_digest)
+            atomic_write(staging / ".cogniflow-instance.json", canonical_json(marker_value))
+            _test_abort("marker")
+            validate_root(root, checkout, wheelhouse, Path(plan["cogniflow_home"]))
+            if root.exists():
+                raise InstanceError("ROOT_CONFLICT", "installation root appeared during publication")
+            _test_abort("before-rename")
+            _safe_unlink(staging / _OWNER_NAME)
+            owner_removed = True
+            staging.replace(root)
+            _test_abort("after-rename")
+            _safe_unlink(record_path)
+        finally:
+            if staging is not None and staging.exists():
+                if owner_removed:
+                    _cleanup_staging(staging)
+                    _safe_unlink(record_path)
+                else:
+                    _recover_staging(root, record_path, digest(plan), digest(artifact_set))
+        return {"schema": RESULT_SCHEMA, "status": "ready", "marker": str(marker_path), "installation_root": str(root), "environment_root": str(root / "environment"), "python_executable": str(final_executable), "installed_distributions": installed}
+    except InstanceError:
+        raise
+    except OSError as error:
+        raise InstanceError("PUBLISH_FAILED", "instance publication failed") from error
+    finally:
+        if acquired and stream is not None:
+            _lock(stream, False)
+        if stream is not None:
+            stream.close()
+
+
+def _minimum_recovery_artifacts(wheelhouse: Path, artifacts: list[object]) -> list[dict[str, object]]:
+    records = {str(item.get("normalized_distribution", "")).replace("_", "-"): item for item in artifacts if isinstance(item, dict)}
+    roots = {"cf-runtime", "cf-service-client", "cf-install-services", "cf-service-mcp-server", "cf-bootstrap-source-local"}
+    if not roots <= records.keys():
+        raise InstanceError("ARTIFACT_INVALID", "minimum service-plane roots are incomplete")
+    dependencies: dict[str, set[str]] = {}
+    for name, item in records.items():
+        wheel = wheelhouse / str(item["filename"])
+        try:
+            with zipfile.ZipFile(wheel) as archive:
+                metadata_names = [entry for entry in archive.namelist() if entry.endswith(".dist-info/METADATA")]
+                if len(metadata_names) != 1:
+                    raise ValueError("wheel metadata is incomplete")
+                metadata = BytesParser().parsebytes(archive.read(metadata_names[0]))
+        except (OSError, ValueError, zipfile.BadZipFile, KeyError) as error:
+            raise InstanceError("ARTIFACT_INVALID", f"recovery wheel metadata is invalid: {wheel.name}") from error
+        required = set()
+        for requirement in metadata.get_all("Requires-Dist", []):
+            dependency = re.split(r"[ (<>=!;\\[]", requirement, maxsplit=1)[0].lower().replace("_", "-").replace(".", "-")
+            if dependency in records:
+                required.add(dependency)
+        dependencies[name] = required
+    closure = set(roots)
+    pending = list(roots)
+    while pending:
+        for dependency in dependencies[pending.pop()]:
+            if dependency not in closure:
+                closure.add(dependency)
+                pending.append(dependency)
+    return sorted((records[name] for name in closure), key=lambda item: (str(item["normalized_distribution"]), str(item["filename"])))
+
+
+def _retain_recovery_bundle(content_root: Path, authority_root: Path, wheelhouse: Path, artifact_set: dict[str, object], plan: dict[str, object], staging_executable: Path, final_executable: Path) -> tuple[str, str]:
+    """Retain the bootstrap-host-selected minimum closure inside the instance."""
+    artifacts = artifact_set.get("artifacts")
+    if not isinstance(artifacts, list):
+        raise InstanceError("ARTIFACT_INVALID", "recovery artifact set is invalid")
+    selected = _minimum_recovery_artifacts(wheelhouse, artifacts)
+    launcher_targets = _launcher_targets(wheelhouse, selected)
+    scripts = staging_executable.parent
+    wheel_names = {str(item["filename"]) for item in selected}
+    launcher_images = _launcher_images(scripts, launcher_targets, wheel_names)
+    bundle = content_root / "state" / "minimum-service-plane"
+    bundle.mkdir(parents=True, exist_ok=True)
+    for item in selected:
+        source = wheelhouse / str(item["filename"])
+        if source.is_symlink() or not source.is_file() or source.stat().st_size != item["size"] or hashlib.sha256(source.read_bytes()).hexdigest() != item["sha256"]:
+            raise InstanceError("ARTIFACT_INVALID", f"recovery wheel validation failed: {source.name}")
+        destination = bundle / source.name
+        shutil.copy2(source, destination)
+        if destination.is_symlink() or destination.stat().st_size != item["size"] or hashlib.sha256(destination.read_bytes()).hexdigest() != item["sha256"]:
+            raise InstanceError("PUBLISH_FAILED", f"retained recovery wheel verification failed: {source.name}")
+        _test_abort("recovery-copy")
+    for item in launcher_images:
+        source = scripts / _launcher_script_name(str(item["target_launcher"]))
+        destination = bundle / str(item["retained_filename"])
+        shutil.copy2(source, destination)
+        if destination.is_symlink() or destination.stat().st_size != item["size"] or hashlib.sha256(destination.read_bytes()).hexdigest() != item["sha256"] or stat.S_IMODE(destination.lstat().st_mode) != item["mode"]:
+            raise InstanceError("PUBLISH_FAILED", f"retained launcher verification failed: {source.name}")
+        _test_abort("recovery-copy")
+    closure = sorted(str(item["normalized_distribution"]).replace("_", "-") for item in selected)
+    manifest = {"schema": "cf.bootstrap.minimum-service-recovery-manifest.v2", "instance_id": plan["instance_id"], "plan_digest": digest(plan), "artifact_set_digest": digest(artifact_set), "target_python": str(final_executable), "bootstrap_plan": plan, "recovery_distributions": closure, "artifacts": sorted(selected, key=lambda item: (item["normalized_distribution"], item["filename"])), "launcher_images": launcher_images}
+    manifest_path = bundle / "recovery-manifest.json"
+    atomic_write(manifest_path, canonical_json(manifest))
+    _test_abort("recovery-manifest")
+    published_path = authority_root / "state" / "minimum-service-plane" / "recovery-manifest.json"
+    return str(published_path), "sha256:" + hashlib.sha256(manifest_path.read_bytes()).hexdigest()
+
+
+def _validate_retained_authority(root: Path, marker_value: dict[str, object], plan: dict[str, object], artifact_set: dict[str, object], wheelhouse: Path) -> None:
+    recovery_path = Path(str(marker_value.get("recovery_manifest_path", "")))
+    expected_path = root / "state" / "minimum-service-plane" / "recovery-manifest.json"
+    if recovery_path != expected_path or recovery_path.is_symlink() or not recovery_path.is_file():
+        raise InstanceError("VERIFY_FAILED", "existing recovery authority is missing or unsafe")
+    raw = recovery_path.read_bytes()
+    if marker_value.get("recovery_manifest_digest") != "sha256:" + hashlib.sha256(raw).hexdigest():
+        raise InstanceError("VERIFY_FAILED", "existing recovery authority is tampered")
+    try:
+        retained = json.loads(raw)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        raise InstanceError("VERIFY_FAILED", "existing recovery authority is invalid") from error
+    selected = _minimum_recovery_artifacts(wheelhouse, artifact_set["artifacts"])
+    launcher_targets = _launcher_targets(wheelhouse, selected)
+    closure = sorted(str(item["normalized_distribution"]).replace("_", "-") for item in selected)
+    wheel_names = {str(item["filename"]) for item in selected}
+    launcher_images = _validate_launcher_images(recovery_path.parent, retained.get("launcher_images"), launcher_targets, wheel_names)
+    launcher_images = [{key: item[key] for key in ("target_launcher", "retained_filename", "size", "sha256", "mode")} for item in launcher_images]
+    expected = {"schema": "cf.bootstrap.minimum-service-recovery-manifest.v2", "instance_id": plan["instance_id"], "plan_digest": digest(plan), "artifact_set_digest": digest(artifact_set), "target_python": str(root / "environment" / ("Scripts/python.exe" if os.name == "nt" else "bin/python")), "bootstrap_plan": plan, "recovery_distributions": closure, "artifacts": sorted(selected, key=lambda item: (item["normalized_distribution"], item["filename"])), "launcher_images": launcher_images}
+    if raw != canonical_json(expected) or retained != expected:
+        raise InstanceError("VERIFY_FAILED", "existing recovery authority does not match the accepted closure")
+    expected_names = wheel_names | {str(item["retained_filename"]) for item in launcher_images} | {"recovery-manifest.json"}
+    children = list(recovery_path.parent.iterdir())
+    if {child.name for child in children} != expected_names or any(child.is_symlink() or not child.is_file() for child in children):
+        raise InstanceError("VERIFY_FAILED", "existing recovery bundle contains missing or foreign state")
+    for item in selected:
+        wheel = recovery_path.parent / str(item["filename"])
+        if wheel.stat().st_size != item["size"] or hashlib.sha256(wheel.read_bytes()).hexdigest() != item["sha256"]:
+            raise InstanceError("VERIFY_FAILED", f"retained recovery artifact is tampered: {wheel.name}")
+    handoff_path = root / ".cogniflow-profile-handoff.json"
+    if handoff_path.exists():
+        if handoff_path.is_symlink() or not handoff_path.is_file():
+            raise InstanceError("VERIFY_FAILED", "accepted handoff record is unsafe")
+        try:
+            handoff = json.loads(handoff_path.read_bytes())
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            raise InstanceError("VERIFY_FAILED", "accepted handoff record is invalid") from error
+        if not isinstance(handoff, dict) or handoff.get("schema") != "cf.bootstrap.accepted-handoff.v2" or handoff.get("record_digest") != digest({key: value for key, value in handoff.items() if key != "record_digest"}) or handoff.get("instance_id") != plan["instance_id"] or handoff.get("plan_digest") != digest(plan) or handoff.get("recovery_manifest_path") != str(recovery_path) or handoff.get("recovery_manifest_digest") != marker_value["recovery_manifest_digest"]:
+            raise InstanceError("VERIFY_FAILED", "accepted handoff record is not bound to retained authority")
+
+
+def _apply_v2(plan: dict[str, object], resolution: dict[str, object], root: Path) -> dict[str, object]:
+    """Run the hardened v1 installer with a lossless v2 validation boundary."""
+    artifact_set = resolution["artifact_set"]
+    wheelhouse = Path(str(resolution["wheelhouse_path"])).absolute()
+    source = plan["artifact_source"]
+    checkout = Path(str(source["checkout_path"])).absolute() if isinstance(source, dict) and source.get("mode") == "local-repository" else None
+    validate_root(root, checkout, wheelhouse, Path(str(plan["cogniflow_home"])))
+    if not wheelhouse.is_dir() or wheelhouse.is_symlink():
+        raise InstanceError("ARTIFACT_INVALID", "v2 wheelhouse is not a real directory")
+    marker_path = root / ".cogniflow-instance.json"
+    if root.exists() and marker_path.is_file():
+        current, _ = read_marker(marker_path)
+        if current.get("schema") != "cf.bootstrap.instance-marker.v2":
+            raise InstanceError("PLAN_CONFLICT", "existing instance is not a v2 target")
+        if current.get("plan_digest") != digest(plan):
+            raise InstanceError("PLAN_CONFLICT", "existing instance belongs to another plan")
+        if current.get("artifact_set_digest") != digest(artifact_set):
+            raise InstanceError("ARTIFACT_SET_CONFLICT", "existing instance belongs to another artifact set")
+        environment = Path(str(current["environment_root"]))
+        executable = Path(str(current["python_executable"]))
+        if environment.resolve() != root.resolve() / "environment" or executable.resolve() != environment.resolve() / ("Scripts/python.exe" if os.name == "nt" else "bin/python"):
+            raise InstanceError("VENV_INVALID", "existing v2 target is not root-bound")
+        installed = inventory(executable, environment, artifact_set, checkout)
+        if current.get("installed_distributions") != installed:
+            raise InstanceError("VERIFY_FAILED", "existing v2 marker inventory differs from target")
+        _validate_retained_authority(root, current, plan, artifact_set, wheelhouse)
+        return {"schema": RESULT_SCHEMA_V2, "status": "unchanged", "marker": str(marker_path), "installation_root": str(root), "environment_root": str(environment), "python_executable": str(executable), "installed_distributions": installed, "profile": plan["profile"], "selection_digest": artifact_set["selection_digest"]}
+    temporary = Path(tempfile.mkdtemp(prefix="cf-bootstrap-v2-install-", dir=str(wheelhouse.parent)))
+    try:
+        legacy_artifacts = []
+        for item in artifact_set["artifacts"]:
+            legacy = {key: item[key] for key in ("distribution", "normalized_distribution", "version", "filename", "sha256")}
+            legacy["size_bytes"] = item["size"]
+            if item["source_kind"] == "stonecastle-local":
+                legacy["source_project"] = item["source_project"]
+                if item.get("artifact_kind") == "native":
+                    legacy.update({key: item[key] for key in ("artifact_kind", "wheel_tags", "executable")})
+            else:
+                legacy["source_kind"] = "external-wheelhouse"
+            legacy_artifacts.append(legacy)
+            shutil.copy2(wheelhouse / item["filename"], temporary / item["filename"])
+        legacy_set = {"schema": "cf.bootstrap.artifact-set.v1", "source_mode": "local-repository", "source_digest": artifact_set["repository_source_digest"], "index_digest": artifact_set["index_digest"], "artifacts": legacy_artifacts}
+        (temporary / "artifact-set.json").write_bytes(canonical_json(legacy_set))
+        legacy_plan = {key: value for key, value in plan.items() if key != "profile"}
+        legacy_plan["schema"] = "cf.bootstrap.plan.v1"
+        legacy_resolution = {"schema": "cf.bootstrap.local-artifact-resolution.v1", "wheelhouse_path": str(temporary), "artifact_set": legacy_set}
+        result = apply({"schema": "cf.bootstrap.instance-apply.request.v1", "bootstrap_plan": legacy_plan, "artifact_resolution": legacy_resolution}, recovery_authority=(plan, artifact_set, wheelhouse))
+        marker_path = root / ".cogniflow-instance.json"
+        installed = result.get("installed_distributions", [])
+        executable = Path(str(result["python_executable"]))
+        environment = Path(str(result["environment_root"]))
+
+
+
+        return {"schema": RESULT_SCHEMA_V2, "status": result["status"], "marker": str(marker_path), "installation_root": str(root), "environment_root": str(environment), "python_executable": str(executable), "installed_distributions": installed, "profile": plan["profile"], "selection_digest": artifact_set["selection_digest"]}
+    finally:
+        shutil.rmtree(temporary, ignore_errors=True)
+
+
+def handle(payload: object) -> dict[str, object]:
+    identifier = payload.get("id") if isinstance(payload, dict) else None
+    try:
+        if not isinstance(payload, dict) or set(payload) != {"jsonrpc", "protocol", "id", "method", "params"} or payload.get("jsonrpc") != "2.0" or payload.get("protocol") != PROTOCOL or payload.get("method") != "instance/apply":
+            raise InstanceError("INVALID_ENVELOPE", "instance provider envelope is invalid")
+        return _response(identifier, result=apply(payload["params"]))
+    except InstanceError as error:
+        return _response(identifier, error={"code": error.code, "message": str(error), "details": error.details})
+    except Exception as error:
+        return _response(identifier, error={"code": "INTERNAL_ERROR", "message": "instance provider failed unexpectedly", "details": {"exception": type(error).__name__, "diagnostic": str(error)[:500]}})
+
+
+def main() -> int:
+    import sys
+    for line in sys.stdin:
+        try:
+            response = handle(json.loads(line))
+        except json.JSONDecodeError:
+            response = _response(None, error={"code": "MALFORMED_JSON", "message": "request must be valid JSON", "details": {}})
+        sys.stdout.write(canonical_json(response).decode())
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())