bedrockplus 0.1.0.dev1__py3-none-win_amd64.whl

bedrockplus/_assets/tools/bppack.py

@@ -0,0 +1,1865 @@
+#!/usr/bin/env python3
+"""Build and validate deterministic BedrockPlus .bppack archives.
+
+This tool intentionally uses only the Python standard library.  It is the
+reference implementation of the package-level checks described by the v1
+format specification; loading native or Python code is a separate runtime
+responsibility.
+"""
+
+from __future__ import annotations
+
+import argparse
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import sys
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import uuid
+from typing import Any, BinaryIO, Iterable, Iterator
+import unicodedata
+import zipfile
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+FORMAT_VERSION = 1
+INTEGRITY_PATH = "integrity.json"
+MANIFEST_PATH = "manifest.json"
+CHUNK_SIZE = 1024 * 1024
+FIXED_ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+MAX_JSON_DEPTH = 64
+CACHE_LEASE_FILENAME = ".bedrockplus-runtime.lock"
+
+SEMVER_NUMBER = r"(?:0|[1-9][0-9]*)"
+SEMVER_PRERELEASE_IDENTIFIER = (
+    r"(?:0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)"
+)
+SEMVER_PATTERN = (
+    rf"{SEMVER_NUMBER}\.{SEMVER_NUMBER}\.{SEMVER_NUMBER}"
+    rf"(?:-{SEMVER_PRERELEASE_IDENTIFIER}"
+    rf"(?:\.{SEMVER_PRERELEASE_IDENTIFIER})*)?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+)
+SEMVER_RE = re.compile(rf"^{SEMVER_PATTERN}$")
+DEPENDENCY_RANGE_RE = re.compile(
+    rf"^(?:\*|(?:>=|<=|>|<|=)?{SEMVER_PATTERN}"
+    rf"(?:,(?:>=|<=|>|<|=)?{SEMVER_PATTERN})*)$"
+)
+PLUGIN_ID_RE = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+PYTHON_CLASS_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+WINDOWS_RESERVED_NAMES = {
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    "conin$",
+    "conout$",
+    *(f"com{number}" for number in range(1, 10)),
+    *(f"lpt{number}" for number in range(1, 10)),
+    # Win32 also treats the ISO-8859-1 superscript digits as DOS-device
+    # suffixes. They remain reserved even though the package format permits
+    # Unicode paths.
+    *(f"com{number}" for number in ("¹", "²", "³")),
+    *(f"lpt{number}" for number in ("¹", "²", "³")),
+}
+REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+
+@dataclass(frozen=True)
+class PackLimits:
+    max_archive_size: int = 512 * 1024 * 1024
+    max_files: int = 4096
+    max_file_size: int = 256 * 1024 * 1024
+    max_total_size: int = 512 * 1024 * 1024
+    max_manifest_size: int = 128 * 1024
+    max_integrity_size: int = 2 * 1024 * 1024
+    max_compression_ratio: int = 200
+    ratio_check_min_size: int = 1024 * 1024
+    max_path_bytes: int = 1024
+    max_segment_bytes: int = 255
+
+
+DEFAULT_LIMITS = PackLimits()
+
+
+@dataclass(frozen=True)
+class SourceSnapshot:
+    path: Path
+    device: int
+    inode: int
+    mode: int
+    size: int
+    modified_ns: int
+    file_attributes: int
+
+
+@dataclass(frozen=True)
+class ArchiveInspection:
+    result: dict[str, Any]
+    manifest: dict[str, Any]
+    entries: dict[str, zipfile.ZipInfo]
+    expected_digests: dict[str, str]
+
+
+class PackValidationError(ValueError):
+    """A validation failure with a stable code suitable for structured logs."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+    def as_dict(self) -> dict[str, str | bool]:
+        return {"valid": False, "code": self.code, "message": str(self)}
+
+
+def _fail(code: str, message: str) -> None:
+    raise PackValidationError(code, message)
+
+
+def _is_plain_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _object_without_duplicate_keys(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            _fail("JSON_DUPLICATE_KEY", f"JSON object contains duplicate key {key!r}")
+        result[key] = value
+    return result
+
+
+def _parse_json_integer(raw_value: str) -> int:
+    if len(raw_value.lstrip("-")) > 19:
+        _fail("JSON_NUMBER_RANGE", "JSON integer exceeds the signed 64-bit range")
+    value = int(raw_value)
+    if not -(2**63) <= value <= 2**63 - 1:
+        _fail("JSON_NUMBER_RANGE", "JSON integer exceeds the signed 64-bit range")
+    return value
+
+
+def _reject_json_float(raw_value: str) -> None:
+    _fail("JSON_NUMBER_TYPE", f"Floating-point JSON number is not allowed: {raw_value}")
+
+
+def _validate_decoded_json(value: Any, label: str) -> None:
+    pending: list[tuple[Any, int]] = [(value, 0)]
+    while pending:
+        current, depth = pending.pop()
+        if depth > MAX_JSON_DEPTH:
+            _fail("JSON_NESTING", f"{label} exceeds the maximum JSON nesting depth")
+        if isinstance(current, str):
+            try:
+                current.encode("utf-8")
+            except UnicodeEncodeError:
+                _fail("JSON_INVALID_UNICODE", f"{label} contains an invalid Unicode string")
+            if any(ord(character) < 0x20 or ord(character) == 0x7F for character in current):
+                _fail("JSON_CONTROL_CHARACTER", f"{label} contains a control character")
+        elif isinstance(current, list):
+            pending.extend((item, depth + 1) for item in current)
+        elif isinstance(current, dict):
+            for key, item in current.items():
+                pending.append((key, depth + 1))
+                pending.append((item, depth + 1))
+
+
+def _decode_json(data: bytes, label: str) -> Any:
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as error:
+        _fail("JSON_NOT_UTF8", f"{label} is not valid UTF-8: {error}")
+
+    try:
+        value = json.loads(
+            text,
+            object_pairs_hook=_object_without_duplicate_keys,
+            parse_int=_parse_json_integer,
+            parse_float=_reject_json_float,
+            parse_constant=lambda constant: _fail(
+                "JSON_INVALID", f"{label} contains non-standard value {constant}"
+            ),
+        )
+        _validate_decoded_json(value, label)
+        return value
+    except PackValidationError:
+        raise
+    except json.JSONDecodeError as error:
+        _fail(
+            "JSON_INVALID",
+            f"{label} is not valid JSON at line {error.lineno}, column {error.colno}",
+        )
+    except (ValueError, RecursionError) as error:
+        _fail("JSON_INVALID", f"{label} could not be parsed safely: {error}")
+
+
+def _canonical_json(value: Any) -> bytes:
+    return (
+        json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
+    ).encode("utf-8")
+
+
+def _check_object_keys(
+    value: object,
+    *,
+    required: set[str],
+    optional: set[str],
+    label: str,
+) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        _fail("MANIFEST_TYPE", f"{label} must be a JSON object")
+    missing = sorted(required - value.keys())
+    if missing:
+        _fail("MANIFEST_REQUIRED_FIELD", f"{label} is missing: {', '.join(missing)}")
+    unknown = sorted(value.keys() - required - optional)
+    if unknown:
+        _fail("MANIFEST_UNKNOWN_FIELD", f"{label} has unknown field(s): {', '.join(unknown)}")
+    return value
+
+
+def _require_string(
+    value: object,
+    label: str,
+    *,
+    minimum: int = 1,
+    maximum: int,
+) -> str:
+    if not isinstance(value, str) or not minimum <= len(value) <= maximum:
+        _fail(
+            "MANIFEST_TYPE",
+            f"{label} must be a string with {minimum}..{maximum} characters",
+        )
+    try:
+        value.encode("utf-8")
+    except UnicodeEncodeError:
+        _fail("MANIFEST_INVALID_UNICODE", f"{label} contains invalid Unicode")
+    if any(ord(character) < 0x20 or ord(character) == 0x7F for character in value):
+        _fail("MANIFEST_CONTROL_CHARACTER", f"{label} contains a control character")
+    return value
+
+
+def validate_package_path(path: str, limits: PackLimits = DEFAULT_LIMITS) -> str:
+    """Validate one canonical, relative POSIX path stored in a package."""
+
+    if not isinstance(path, str) or not path:
+        _fail("PATH_EMPTY", "Package path must be a non-empty string")
+    if "\\" in path:
+        _fail("PATH_BACKSLASH", f"Package path must use '/' separators: {path!r}")
+    if path.startswith("/") or re.match(r"^[A-Za-z]:", path):
+        _fail("PATH_ABSOLUTE", f"Absolute or drive-qualified path is forbidden: {path!r}")
+    try:
+        encoded_path = path.encode("utf-8")
+    except UnicodeEncodeError:
+        _fail("PATH_INVALID_UNICODE", f"Package path contains invalid Unicode: {path!r}")
+    if len(encoded_path) > limits.max_path_bytes:
+        _fail("PATH_TOO_LONG", f"Package path is too long: {path!r}")
+
+    parts = path.split("/")
+    for part in parts:
+        if part in {"", ".", ".."}:
+            _fail("PATH_TRAVERSAL", f"Empty, '.' or '..' path segment is forbidden: {path!r}")
+        if unicodedata.normalize("NFC", part) != part:
+            _fail("PATH_NOT_NFC", f"Package path must use Unicode NFC form: {path!r}")
+        # The complete-path encoding above already proves every segment can be
+        # represented as strict UTF-8.
+        if len(part.encode("utf-8")) > limits.max_segment_bytes:
+            _fail("PATH_SEGMENT_TOO_LONG", f"Package path segment is too long: {part!r}")
+        if any(ord(character) < 0x20 or ord(character) == 0x7F for character in part):
+            _fail("PATH_CONTROL_CHARACTER", f"Control character in package path: {path!r}")
+        if ":" in part:
+            _fail("PATH_ALTERNATE_DATA_STREAM", f"':' is forbidden in package paths: {path!r}")
+        if any(character in '<>"|?*' for character in part):
+            _fail(
+                "PATH_WINDOWS_ILLEGAL_CHARACTER",
+                f"Windows-illegal character in package path: {path!r}",
+            )
+        if part.endswith((" ", ".")):
+            _fail("PATH_WINDOWS_AMBIGUOUS", f"Trailing dot or space is forbidden: {path!r}")
+        base_name = part.split(".", 1)[0].casefold()
+        if base_name in WINDOWS_RESERVED_NAMES:
+            _fail("PATH_WINDOWS_RESERVED", f"Reserved Windows name in package path: {path!r}")
+
+    return path
+
+
+def _collision_key(path: str) -> str:
+    return unicodedata.normalize("NFC", path).casefold()
+
+
+def _plugin_id_uses_reserved_windows_name(plugin_id: str) -> bool:
+    """IDs become directory names, so apply Windows basename semantics."""
+
+    return plugin_id.split(".", 1)[0].casefold() in WINDOWS_RESERVED_NAMES
+
+
+def _validate_manifest(manifest: object, package_paths: set[str]) -> dict[str, Any]:
+    value = _check_object_keys(
+        manifest,
+        required={"format_version", "id", "name", "version", "api_version", "runtime"},
+        optional={"description", "authors", "license", "dependencies", "packs"},
+        label="manifest",
+    )
+
+    if not _is_plain_int(value["format_version"]) or value["format_version"] != FORMAT_VERSION:
+        _fail("MANIFEST_FORMAT_VERSION", f"format_version must be {FORMAT_VERSION}")
+
+    plugin_id = _require_string(value["id"], "id", maximum=64)
+    if not PLUGIN_ID_RE.fullmatch(plugin_id):
+        _fail(
+            "MANIFEST_PLUGIN_ID",
+            "id must be lowercase and contain only letters, digits, '.', '_' or '-' separators",
+        )
+    if _plugin_id_uses_reserved_windows_name(plugin_id):
+        _fail(
+            "MANIFEST_PLUGIN_ID_RESERVED",
+            f"Plugin id cannot become a reserved Windows directory name: {plugin_id!r}",
+        )
+    _require_string(value["name"], "name", maximum=80)
+
+    version = _require_string(value["version"], "version", maximum=128)
+    if not SEMVER_RE.fullmatch(version):
+        _fail("MANIFEST_VERSION", "version must be a complete Semantic Version")
+
+    if not _is_plain_int(value["api_version"]) or value["api_version"] != 1:
+        _fail("MANIFEST_API_VERSION", "api_version must be 1")
+
+    if "description" in value:
+        _require_string(value["description"], "description", minimum=0, maximum=500)
+    if "license" in value:
+        _require_string(value["license"], "license", maximum=100)
+    if "authors" in value:
+        authors = value["authors"]
+        if not isinstance(authors, list) or not 1 <= len(authors) <= 32:
+            _fail("MANIFEST_AUTHORS", "authors must contain 1..32 strings")
+        seen_authors: set[str] = set()
+        for index, author in enumerate(authors):
+            checked_author = _require_string(author, f"authors[{index}]", maximum=100)
+            if checked_author in seen_authors:
+                _fail("MANIFEST_AUTHORS", f"Duplicate author: {checked_author}")
+            seen_authors.add(checked_author)
+
+    runtime = _check_object_keys(
+        value["runtime"],
+        required={"type", "entrypoint"},
+        optional={"entry_class", "python", "platform", "abi"},
+        label="runtime",
+    )
+    runtime_type = runtime["type"]
+    if runtime_type == "python":
+        expected = {"type", "entrypoint", "entry_class", "python"}
+        if set(runtime) != expected:
+            _fail(
+                "MANIFEST_RUNTIME_FIELDS",
+                "Python runtime requires exactly: type, entrypoint, entry_class, python",
+            )
+        entrypoint = _require_string(runtime["entrypoint"], "runtime.entrypoint", maximum=240)
+        validate_package_path(entrypoint)
+        if not entrypoint.startswith("python/") or not entrypoint.endswith(".py"):
+            _fail(
+                "MANIFEST_ENTRYPOINT",
+                "Python entrypoint must be a .py file below python/",
+            )
+        entry_class = _require_string(runtime["entry_class"], "runtime.entry_class", maximum=200)
+        if not PYTHON_CLASS_RE.fullmatch(entry_class):
+            _fail("MANIFEST_ENTRY_CLASS", "entry_class must be a dotted Python identifier")
+        if runtime["python"] != "3.13":
+            _fail("MANIFEST_PYTHON_VERSION", "The v1 Python runtime must be '3.13'")
+    elif runtime_type == "cpp":
+        expected = {"type", "entrypoint", "platform", "abi"}
+        if set(runtime) != expected:
+            _fail(
+                "MANIFEST_RUNTIME_FIELDS",
+                "C++ runtime requires exactly: type, entrypoint, platform, abi",
+            )
+        entrypoint = _require_string(runtime["entrypoint"], "runtime.entrypoint", maximum=240)
+        validate_package_path(entrypoint)
+        if not entrypoint.startswith("native/windows-x64/") or not entrypoint.endswith(".dll"):
+            _fail(
+                "MANIFEST_ENTRYPOINT",
+                "C++ entrypoint must be a .dll below native/windows-x64/",
+            )
+        if runtime["platform"] != "windows-x64":
+            _fail("MANIFEST_PLATFORM", "The v1 native platform must be 'windows-x64'")
+        if not _is_plain_int(runtime["abi"]) or runtime["abi"] != 1:
+            _fail("MANIFEST_ABI", "The v1 native ABI must be 1")
+    else:
+        _fail("MANIFEST_RUNTIME_TYPE", "runtime.type must be 'python' or 'cpp'")
+
+    if entrypoint not in package_paths:
+        _fail("MANIFEST_ENTRYPOINT_MISSING", f"Runtime entrypoint is absent: {entrypoint}")
+
+    dependencies = value.get("dependencies", [])
+    if not isinstance(dependencies, list) or len(dependencies) > 128:
+        _fail("MANIFEST_DEPENDENCIES", "dependencies must be an array of at most 128 entries")
+    dependency_ids: set[str] = set()
+    for index, dependency_value in enumerate(dependencies):
+        dependency = _check_object_keys(
+            dependency_value,
+            required={"id", "version"},
+            optional={"optional"},
+            label=f"dependencies[{index}]",
+        )
+        dependency_id = _require_string(
+            dependency["id"], f"dependencies[{index}].id", maximum=64
+        )
+        if not PLUGIN_ID_RE.fullmatch(dependency_id):
+            _fail("MANIFEST_DEPENDENCY_ID", f"Invalid dependency id: {dependency_id!r}")
+        if _plugin_id_uses_reserved_windows_name(dependency_id):
+            _fail(
+                "MANIFEST_DEPENDENCY_ID",
+                f"Dependency id uses a reserved Windows directory name: {dependency_id!r}",
+            )
+        if dependency_id == plugin_id:
+            _fail("MANIFEST_DEPENDENCY_SELF", "A plugin cannot depend on itself")
+        if dependency_id in dependency_ids:
+            _fail("MANIFEST_DEPENDENCY_DUPLICATE", f"Duplicate dependency: {dependency_id}")
+        dependency_ids.add(dependency_id)
+        dependency_range = _require_string(
+            dependency["version"], f"dependencies[{index}].version", maximum=300
+        )
+        if not DEPENDENCY_RANGE_RE.fullmatch(dependency_range):
+            _fail(
+                "MANIFEST_DEPENDENCY_VERSION",
+                "Dependency version must be '*' or comma-separated SemVer comparators",
+            )
+        if "optional" in dependency and not isinstance(dependency["optional"], bool):
+            _fail("MANIFEST_DEPENDENCY_OPTIONAL", "dependency.optional must be boolean")
+
+    packs = value.get("packs", [])
+    if not isinstance(packs, list) or len(packs) > 128:
+        _fail("MANIFEST_PACKS", "packs must be an array of at most 128 entries")
+    pack_roots: list[str] = []
+    pack_keys: set[str] = set()
+    for index, pack_value in enumerate(packs):
+        pack = _check_object_keys(
+            pack_value,
+            required={"type", "path"},
+            optional=set(),
+            label=f"packs[{index}]",
+        )
+        pack_type = pack["type"]
+        if pack_type not in {"behavior", "resource"}:
+            _fail("MANIFEST_PACK_TYPE", "pack.type must be 'behavior' or 'resource'")
+        pack_path = _require_string(pack["path"], f"packs[{index}].path", maximum=240)
+        validate_package_path(pack_path)
+        prefix = f"packs/{pack_type}/"
+        if not pack_path.startswith(prefix) or pack_path == prefix[:-1]:
+            _fail(
+                "MANIFEST_PACK_PATH",
+                f"{pack_type} pack path must be below {prefix}",
+            )
+        key = _collision_key(pack_path)
+        if key in pack_keys:
+            _fail("MANIFEST_PACK_DUPLICATE", f"Duplicate pack path: {pack_path}")
+        if any(
+            key.startswith(f"{existing}/") or existing.startswith(f"{key}/")
+            for existing in pack_roots
+        ):
+            _fail(
+                "MANIFEST_PACK_OVERLAP",
+                f"Bundled pack roots must not overlap: {pack_path}",
+            )
+        pack_keys.add(key)
+        pack_roots.append(key)
+        pack_manifest = f"{pack_path}/manifest.json"
+        if pack_manifest not in package_paths:
+            _fail("MANIFEST_PACK_MISSING", f"Bundled pack manifest is absent: {pack_manifest}")
+
+    for path in package_paths:
+        path_key = _collision_key(path)
+        if (path_key == "packs" or path_key.startswith("packs/")) and not any(
+            path_key == root or path_key.startswith(f"{root}/")
+            for root in pack_roots
+        ):
+            _fail("MANIFEST_PACK_UNDECLARED", f"File belongs to no declared pack: {path}")
+
+    return value
+
+
+def _read_entry_limited(
+    archive: zipfile.ZipFile,
+    info: zipfile.ZipInfo,
+    maximum: int,
+) -> bytes:
+    if info.file_size > maximum:
+        _fail("ENTRY_TOO_LARGE", f"{info.filename} exceeds its size limit")
+    try:
+        with archive.open(info, "r") as stream:
+            data = stream.read(maximum + 1)
+            if len(data) > maximum:
+                _fail("ENTRY_TOO_LARGE", f"{info.filename} exceeds its size limit")
+            return data
+    except (OSError, RuntimeError, zipfile.BadZipFile) as error:
+        _fail("ZIP_READ_FAILED", f"Cannot read {info.filename}: {error}")
+
+
+def _hash_archive_entry(archive: zipfile.ZipFile, info: zipfile.ZipInfo) -> str:
+    digest = hashlib.sha256()
+    actual_size = 0
+    try:
+        with archive.open(info, "r") as stream:
+            while True:
+                block = stream.read(CHUNK_SIZE)
+                if not block:
+                    break
+                actual_size += len(block)
+                if actual_size > info.file_size:
+                    _fail("ZIP_SIZE_MISMATCH", f"Expanded size exceeds metadata: {info.filename}")
+                digest.update(block)
+    except (OSError, RuntimeError, zipfile.BadZipFile) as error:
+        _fail("ZIP_READ_FAILED", f"Cannot verify {info.filename}: {error}")
+    if actual_size != info.file_size:
+        _fail("ZIP_SIZE_MISMATCH", f"Expanded size differs from metadata: {info.filename}")
+    return digest.hexdigest()
+
+
+def _validate_integrity(value: object, expected_paths: set[str]) -> dict[str, str]:
+    integrity = _check_object_keys(
+        value,
+        required={"format_version", "algorithm", "files"},
+        optional=set(),
+        label="integrity",
+    )
+    if not _is_plain_int(integrity["format_version"]) or integrity["format_version"] != 1:
+        _fail("INTEGRITY_FORMAT_VERSION", "integrity format_version must be 1")
+    if integrity["algorithm"] != "sha256":
+        _fail("INTEGRITY_ALGORITHM", "integrity algorithm must be 'sha256'")
+    files = integrity["files"]
+    if not isinstance(files, dict):
+        _fail("INTEGRITY_TYPE", "integrity.files must be an object")
+
+    actual_paths = set(files)
+    if actual_paths != expected_paths:
+        missing = sorted(expected_paths - actual_paths)
+        extra = sorted(actual_paths - expected_paths)
+        details: list[str] = []
+        if missing:
+            details.append(f"missing {missing}")
+        if extra:
+            details.append(f"extra {extra}")
+        _fail("INTEGRITY_FILE_SET", "Integrity file set differs from archive: " + "; ".join(details))
+
+    result: dict[str, str] = {}
+    for path, digest in files.items():
+        validate_package_path(path)
+        if not isinstance(digest, str) or not SHA256_RE.fullmatch(digest):
+            _fail("INTEGRITY_DIGEST", f"Invalid SHA-256 for {path}")
+        result[path] = digest
+    return result
+
+
+def _inspect_archive(
+    archive: zipfile.ZipFile,
+    archive_sha256: str,
+    limits: PackLimits,
+) -> ArchiveInspection:
+    if archive.comment:
+        _fail("ZIP_COMMENT", "Archive comments are not allowed")
+    infos = archive.infolist()
+    if not infos:
+        _fail("ZIP_EMPTY", "Package archive is empty")
+    if len(infos) > limits.max_files:
+        _fail("ZIP_FILE_COUNT", f"Package contains more than {limits.max_files} files")
+
+    by_name: dict[str, zipfile.ZipInfo] = {}
+    collision_names: dict[str, str] = {}
+    total_size = 0
+    for info in infos:
+        path = validate_package_path(info.filename, limits)
+        if info.is_dir() or path.endswith("/"):
+            _fail("ZIP_DIRECTORY_ENTRY", f"Directory entries are forbidden: {path}")
+        if path in by_name:
+            _fail("ZIP_DUPLICATE_PATH", f"Duplicate archive path: {path}")
+        collision = _collision_key(path)
+        if collision in collision_names:
+            _fail(
+                "ZIP_CASE_COLLISION",
+                f"Windows path collision: {collision_names[collision]!r} and {path!r}",
+            )
+        collision_names[collision] = path
+        by_name[path] = info
+
+        if any(ord(character) >= 128 for character in path) and not (info.flag_bits & 0x800):
+            _fail("ZIP_FILENAME_ENCODING", f"Non-ASCII path is not marked UTF-8: {path}")
+        if info.flag_bits & 0x1:
+            _fail("ZIP_ENCRYPTED", f"Encrypted archive entry is forbidden: {path}")
+        if info.compress_type not in {zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED}:
+            _fail("ZIP_COMPRESSION", f"Unsupported compression method for {path}")
+
+        unix_mode = (info.external_attr >> 16) & 0xFFFF
+        file_type = stat.S_IFMT(unix_mode)
+        if file_type not in {0, stat.S_IFREG}:
+            _fail("ZIP_SPECIAL_FILE", f"Links and special files are forbidden: {path}")
+        if info.file_size > limits.max_file_size:
+            _fail("ZIP_FILE_TOO_LARGE", f"Expanded file exceeds limit: {path}")
+        total_size += info.file_size
+        if total_size > limits.max_total_size:
+            _fail("ZIP_TOTAL_TOO_LARGE", "Total expanded package size exceeds limit")
+        if info.file_size >= limits.ratio_check_min_size:
+            if info.compress_size == 0:
+                _fail("ZIP_COMPRESSION_RATIO", f"Invalid compression ratio: {path}")
+            ratio = info.file_size / info.compress_size
+            if ratio > limits.max_compression_ratio:
+                _fail(
+                    "ZIP_COMPRESSION_RATIO",
+                    f"Compression ratio exceeds {limits.max_compression_ratio}:1: {path}",
+                )
+
+    if MANIFEST_PATH not in by_name:
+        _fail("MANIFEST_MISSING", "Package has no root manifest.json")
+    if INTEGRITY_PATH not in by_name:
+        _fail("INTEGRITY_MISSING", "Package has no root integrity.json")
+
+    manifest = _decode_json(
+        _read_entry_limited(archive, by_name[MANIFEST_PATH], limits.max_manifest_size),
+        MANIFEST_PATH,
+    )
+    package_paths = set(by_name) - {INTEGRITY_PATH}
+    validated_manifest = _validate_manifest(manifest, package_paths)
+    integrity = _decode_json(
+        _read_entry_limited(archive, by_name[INTEGRITY_PATH], limits.max_integrity_size),
+        INTEGRITY_PATH,
+    )
+    expected_digests = _validate_integrity(integrity, package_paths)
+    for path in sorted(package_paths):
+        actual_digest = _hash_archive_entry(archive, by_name[path])
+        if actual_digest != expected_digests[path]:
+            _fail("INTEGRITY_MISMATCH", f"SHA-256 mismatch for {path}")
+
+    return ArchiveInspection(
+        result={
+            "valid": True,
+            "format_version": FORMAT_VERSION,
+            "id": validated_manifest["id"],
+            "name": validated_manifest["name"],
+            "version": validated_manifest["version"],
+            "runtime": validated_manifest["runtime"]["type"],
+            "files": len(by_name),
+            "expanded_size": total_size,
+            "sha256": archive_sha256,
+        },
+        manifest=validated_manifest,
+        entries=by_name,
+        expected_digests=expected_digests,
+    )
+
+
+def _same_open_file(before: os.stat_result, opened: os.stat_result) -> bool:
+    return (
+        before.st_dev == opened.st_dev
+        and before.st_ino == opened.st_ino
+        and before.st_size == opened.st_size
+        and before.st_mtime_ns == opened.st_mtime_ns
+        and getattr(before, "st_file_attributes", 0)
+        == getattr(opened, "st_file_attributes", 0)
+    )
+
+
+@contextmanager
+def _open_package_archive(
+    package: Path,
+    limits: PackLimits,
+) -> Iterator[tuple[zipfile.ZipFile, ArchiveInspection]]:
+    if package.suffix.casefold() != ".bppack":
+        _fail("PACKAGE_EXTENSION", "Package filename must end in .bppack")
+    try:
+        before = package.lstat()
+    except OSError as error:
+        _fail("PACKAGE_NOT_READABLE", f"Cannot inspect package: {error}")
+    if not stat.S_ISREG(before.st_mode) or stat.S_ISLNK(before.st_mode) or _is_reparse_point(before):
+        _fail("PACKAGE_LINK", "Package must be a regular, non-reparse file")
+    if before.st_size > limits.max_archive_size:
+        _fail("PACKAGE_TOO_LARGE", "Compressed package exceeds the archive size limit")
+
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(package, flags)
+        stream = os.fdopen(descriptor, "rb")
+    except OSError as error:
+        _fail("PACKAGE_NOT_READABLE", f"Cannot open package: {error}")
+    try:
+        opened = os.fstat(stream.fileno())
+        if not stat.S_ISREG(opened.st_mode) or _is_reparse_point(opened) or not _same_open_file(before, opened):
+            _fail("PACKAGE_CHANGED", "Package changed or became a reparse point while opening")
+        archive_sha256 = _hash_stream(stream)
+        stream.seek(0)
+        with zipfile.ZipFile(stream, "r") as archive:
+            inspection = _inspect_archive(archive, archive_sha256, limits)
+            yield archive, inspection
+        after = os.fstat(stream.fileno())
+        if not _same_open_file(opened, after):
+            _fail("PACKAGE_CHANGED", "Package changed while it was being read")
+    except PackValidationError:
+        raise
+    except (OSError, RuntimeError, zipfile.BadZipFile, zipfile.LargeZipFile) as error:
+        _fail("ZIP_INVALID", f"Invalid ZIP archive: {error}")
+    finally:
+        stream.close()
+
+
+def validate_package(
+    package_path: str | os.PathLike[str],
+    limits: PackLimits = DEFAULT_LIMITS,
+) -> dict[str, Any]:
+    """Fully validate and hash one held, non-reparse .bppack file."""
+
+    with _open_package_archive(Path(package_path), limits) as (_, inspection):
+        return dict(inspection.result)
+
+
+def _is_reparse_point(file_stat: os.stat_result) -> bool:
+    return bool(getattr(file_stat, "st_file_attributes", 0) & REPARSE_POINT)
+
+
+def _source_snapshot(path: Path, file_stat: os.stat_result) -> SourceSnapshot:
+    return SourceSnapshot(
+        path=path,
+        device=file_stat.st_dev,
+        inode=file_stat.st_ino,
+        mode=file_stat.st_mode,
+        size=file_stat.st_size,
+        modified_ns=file_stat.st_mtime_ns,
+        file_attributes=getattr(file_stat, "st_file_attributes", 0),
+    )
+
+
+def _snapshot_matches(snapshot: SourceSnapshot, file_stat: os.stat_result) -> bool:
+    return (
+        snapshot.device == file_stat.st_dev
+        and snapshot.inode == file_stat.st_ino
+        and snapshot.mode == file_stat.st_mode
+        and snapshot.size == file_stat.st_size
+        and snapshot.modified_ns == file_stat.st_mtime_ns
+        and snapshot.file_attributes == getattr(file_stat, "st_file_attributes", 0)
+    )
+
+
+def _scan_source(
+    root: Path,
+    limits: PackLimits,
+) -> dict[str, SourceSnapshot]:
+    files: dict[str, SourceSnapshot] = {}
+    collisions: dict[str, str] = {}
+    total_size = 0
+    scanned_entries = 0
+
+    try:
+        root_stat = root.lstat()
+    except OSError as error:
+        _fail("SOURCE_READ_FAILED", f"Cannot inspect source root {root}: {error}")
+    if not stat.S_ISDIR(root_stat.st_mode) or _is_reparse_point(root_stat):
+        _fail("SOURCE_LINK", "The package source root must be a regular directory")
+
+    def visit(
+        directory: Path,
+        relative_parts: tuple[str, ...],
+        expected_directory: SourceSnapshot,
+    ) -> None:
+        nonlocal total_size, scanned_entries
+        try:
+            before = directory.lstat()
+            if not _snapshot_matches(expected_directory, before):
+                _fail("SOURCE_CHANGED", f"Source directory changed: {directory}")
+            if not stat.S_ISDIR(before.st_mode) or _is_reparse_point(before):
+                _fail("SOURCE_LINK", f"Source directory became a reparse point: {directory}")
+            entries = []
+            with os.scandir(directory) as scan:
+                for item in scan:
+                    scanned_entries += 1
+                    if scanned_entries > limits.max_files * 2:
+                        _fail("SOURCE_ENTRY_COUNT", "Source contains too many files and directories")
+                    entries.append(item)
+            entries.sort(key=lambda item: item.name.casefold())
+        except OSError as error:
+            _fail("SOURCE_READ_FAILED", f"Cannot scan {directory}: {error}")
+        try:
+            for entry in entries:
+                relative = "/".join((*relative_parts, entry.name))
+                validate_package_path(relative, limits)
+                try:
+                    entry_path = Path(entry.path)
+                    entry_stat = entry_path.lstat()
+                except OSError as error:
+                    _fail("SOURCE_READ_FAILED", f"Cannot inspect {entry.path}: {error}")
+                if stat.S_ISLNK(entry_stat.st_mode) or _is_reparse_point(entry_stat):
+                    _fail("SOURCE_LINK", f"Links and reparse points are forbidden: {relative}")
+                if stat.S_ISDIR(entry_stat.st_mode):
+                    # Python creates these beside sources during local testing.
+                    # They are interpreter-specific generated artifacts, never
+                    # plugin source, and can otherwise carry stale code into a
+                    # package after its manifest version changes.
+                    if entry.name == "__pycache__":
+                        continue
+                    visit(
+                        entry_path,
+                        (*relative_parts, entry.name),
+                        _source_snapshot(entry_path, entry_stat),
+                    )
+                    continue
+                if not stat.S_ISREG(entry_stat.st_mode):
+                    _fail("SOURCE_SPECIAL_FILE", f"Special source file is forbidden: {relative}")
+                if entry.name.endswith((".pyc", ".pyo")):
+                    continue
+                if entry_stat.st_nlink != 1:
+                    _fail("SOURCE_LINK", f"Multiply linked source file is forbidden: {relative}")
+                if relative == INTEGRITY_PATH:
+                    continue  # Generated from the current payload on every build.
+                collision = _collision_key(relative)
+                if collision == _collision_key(INTEGRITY_PATH):
+                    _fail(
+                        "SOURCE_RESERVED_PATH",
+                        f"Path collides with generated {INTEGRITY_PATH}: {relative}",
+                    )
+                if collision in collisions:
+                    _fail(
+                        "SOURCE_CASE_COLLISION",
+                        f"Windows path collision: {collisions[collision]!r} and {relative!r}",
+                    )
+                collisions[collision] = relative
+                if entry_stat.st_size > limits.max_file_size:
+                    _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {relative}")
+                total_size += entry_stat.st_size
+                if total_size > limits.max_total_size:
+                    _fail("SOURCE_TOTAL_TOO_LARGE", "Source tree exceeds total size limit")
+                files[relative] = _source_snapshot(entry_path, entry_stat)
+                if len(files) + 1 > limits.max_files:  # + generated integrity.json
+                    _fail("SOURCE_FILE_COUNT", f"Source contains more than {limits.max_files - 1} files")
+        finally:
+            entries.clear()
+        try:
+            after = directory.lstat()
+        except OSError as error:
+            _fail("SOURCE_CHANGED", f"Source directory disappeared: {directory}: {error}")
+        if not _snapshot_matches(expected_directory, after):
+            _fail("SOURCE_CHANGED", f"Source directory changed while scanning: {directory}")
+
+    visit(root, (), _source_snapshot(root, root_stat))
+    return files
+
+
+def _hash_stream(stream: BinaryIO) -> str:
+    digest = hashlib.sha256()
+    while True:
+        block = stream.read(CHUNK_SIZE)
+        if not block:
+            break
+        digest.update(block)
+    return digest.hexdigest()
+
+
+@contextmanager
+def _open_verified_source(source: SourceSnapshot) -> Iterator[tuple[BinaryIO, int]]:
+    """Open one regular source file without accepting a link-swap race."""
+
+    path = source.path
+    try:
+        before = path.lstat()
+    except OSError as error:
+        _fail("SOURCE_READ_FAILED", f"Cannot inspect {path}: {error}")
+    if stat.S_ISLNK(before.st_mode) or _is_reparse_point(before):
+        _fail("SOURCE_LINK", f"Source became a link or reparse point: {path}")
+    if not stat.S_ISREG(before.st_mode):
+        _fail("SOURCE_SPECIAL_FILE", f"Source is not a regular file: {path}")
+    if not _snapshot_matches(source, before):
+        _fail("SOURCE_CHANGED", f"Source changed since it was scanned: {path}")
+
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as error:
+        _fail("SOURCE_READ_FAILED", f"Cannot open {path}: {error}")
+
+    stream = os.fdopen(descriptor, "rb")
+    try:
+        opened = os.fstat(stream.fileno())
+        if not stat.S_ISREG(opened.st_mode) or _is_reparse_point(opened):
+            _fail("SOURCE_SPECIAL_FILE", f"Opened source is not a regular file: {path}")
+        if (before.st_dev, before.st_ino) != (opened.st_dev, opened.st_ino):
+            _fail("SOURCE_CHANGED", f"Source changed while it was opened: {path}")
+        if (before.st_size, before.st_mtime_ns) != (opened.st_size, opened.st_mtime_ns):
+            _fail("SOURCE_CHANGED", f"Source changed while it was opened: {path}")
+        yield stream, opened.st_size
+        after = os.fstat(stream.fileno())
+        if (opened.st_size, opened.st_mtime_ns) != (after.st_size, after.st_mtime_ns):
+            _fail("SOURCE_CHANGED", f"Source changed while it was being read: {path}")
+    finally:
+        stream.close()
+
+
+def _read_source_limited(source: SourceSnapshot, maximum: int) -> bytes:
+    with _open_verified_source(source) as (stream, expected_size):
+        if expected_size > maximum:
+            _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {source.path}")
+        data = stream.read(maximum + 1)
+        if len(data) != expected_size or len(data) > maximum:
+            _fail("SOURCE_CHANGED", f"Source size changed while reading: {source.path}")
+        return data
+
+
+def _hash_source_path(source: SourceSnapshot, maximum: int) -> str:
+    with _open_verified_source(source) as (stream, expected_size):
+        if expected_size > maximum:
+            _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {source.path}")
+        digest = hashlib.sha256()
+        actual_size = 0
+        while True:
+            block = stream.read(CHUNK_SIZE)
+            if not block:
+                break
+            actual_size += len(block)
+            if actual_size > maximum:
+                _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {source.path}")
+            digest.update(block)
+        if actual_size != expected_size:
+            _fail("SOURCE_CHANGED", f"Source size changed while hashing: {source.path}")
+        return digest.hexdigest()
+
+
+def _hash_path(path: Path) -> str:
+    try:
+        with path.open("rb") as stream:
+            return _hash_stream(stream)
+    except OSError as error:
+        _fail("FILE_READ_FAILED", f"Cannot hash {path}: {error}")
+
+
+def _zip_info(path: str) -> zipfile.ZipInfo:
+    info = zipfile.ZipInfo(path, date_time=FIXED_ZIP_TIMESTAMP)
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.create_system = 3
+    info.external_attr = (stat.S_IFREG | 0o644) << 16
+    info.internal_attr = 0
+    return info
+
+
+def _write_bytes(archive: zipfile.ZipFile, path: str, data: bytes) -> None:
+    with archive.open(_zip_info(path), "w") as destination:
+        destination.write(data)
+
+
+def _write_file(
+    archive: zipfile.ZipFile,
+    path: str,
+    source: SourceSnapshot,
+    maximum: int,
+) -> None:
+    try:
+        with _open_verified_source(source) as (input_stream, expected_size), archive.open(
+            _zip_info(path), "w"
+        ) as output_stream:
+            if expected_size > maximum:
+                _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {path}")
+            actual_size = 0
+            while True:
+                block = input_stream.read(CHUNK_SIZE)
+                if not block:
+                    break
+                actual_size += len(block)
+                if actual_size > maximum:
+                    _fail("SOURCE_FILE_TOO_LARGE", f"Source file exceeds limit: {path}")
+                output_stream.write(block)
+            if actual_size != expected_size:
+                _fail("SOURCE_CHANGED", f"Source size changed while packaging: {path}")
+    except OSError as error:
+        _fail("SOURCE_READ_FAILED", f"Cannot package {source.path}: {error}")
+
+
+def _path_is_within(path: Path, directory: Path) -> bool:
+    try:
+        path.relative_to(directory)
+        return True
+    except ValueError:
+        return False
+
+
+def _ensure_private_directory_tree(path: Path) -> Path:
+    """Create a local directory tree without accepting reparse-point components."""
+
+    absolute = path.absolute()
+    parts = absolute.parts
+    if not parts:
+        _fail("INSTALL_CACHE_PATH", "Install cache path is empty")
+    current = Path(parts[0])
+    for part in parts[1:]:
+        current /= part
+        try:
+            current_stat = current.lstat()
+        except FileNotFoundError:
+            try:
+                current.mkdir()
+                current_stat = current.lstat()
+            except OSError as error:
+                _fail("INSTALL_CACHE_CREATE", f"Cannot create cache directory {current}: {error}")
+        except OSError as error:
+            _fail("INSTALL_CACHE_INSPECT", f"Cannot inspect cache directory {current}: {error}")
+        if not stat.S_ISDIR(current_stat.st_mode) or _is_reparse_point(current_stat):
+            _fail(
+                "INSTALL_CACHE_REPARSE",
+                f"Install cache component must be a regular directory: {current}",
+            )
+    return absolute
+
+
+def _remove_staging_directory(staging: Path, cache_root: Path) -> None:
+    if not staging.exists():
+        return
+    if staging.parent != cache_root or not staging.name.startswith(".staging-"):
+        _fail("INSTALL_STAGING_BOUNDARY", "Refusing to remove staging outside the cache root")
+    try:
+        staging_stat = staging.lstat()
+        if not stat.S_ISDIR(staging_stat.st_mode) or _is_reparse_point(staging_stat):
+            _fail("INSTALL_STAGING_REPARSE", "Refusing to remove a reparse staging path")
+        shutil.rmtree(staging)
+    except PackValidationError:
+        raise
+    except OSError as error:
+        _fail("INSTALL_STAGING_CLEANUP", f"Cannot remove install staging directory: {error}")
+
+
+def _prune_inactive_plugin_sets(
+    sets_root: Path,
+    active_set: Path,
+    emit: Any,
+    warnings: list[dict[str, Any]],
+) -> list[str]:
+    """Remove inactive immutable run sets without touching persistent plugin data."""
+
+    removed: list[str] = []
+    for candidate in sorted(sets_root.iterdir(), key=lambda path: path.name):
+        if candidate == active_set:
+            continue
+        try:
+            metadata = candidate.lstat()
+            if (
+                not SHA256_RE.fullmatch(candidate.name)
+                or not stat.S_ISDIR(metadata.st_mode)
+                or candidate.is_symlink()
+                or _is_reparse_point(metadata)
+            ):
+                warning = {"code": "BPP-INBOX-CACHE-IGNORED", "path": str(candidate)}
+                warnings.append(warning)
+                emit("warning", warning["code"],
+                     "Unknown or unsafe cache entry was not removed", path=str(candidate))
+                continue
+            try:
+                # A running server owns this per-set lease. Once an inactive
+                # set can be leased, no cooperating runtime can newly select it
+                # because current.json already points at active_set.
+                with _cache_install_lease(candidate):
+                    pass
+            except PackValidationError as error:
+                warning = {"code": "BPP-INBOX-CACHE-IN-USE", "path": str(candidate)}
+                warnings.append(warning)
+                emit("warning", warning["code"],
+                     "Inactive plugin cache is still in use and was preserved",
+                     path=str(candidate), error=str(error))
+                continue
+            safe = True
+            pending = [candidate]
+            while pending and safe:
+                directory = pending.pop()
+                with os.scandir(directory) as entries:
+                    for entry in entries:
+                        entry_stat = entry.stat(follow_symlinks=False)
+                        if entry.is_symlink() or _is_reparse_point(entry_stat):
+                            safe = False
+                            break
+                        if stat.S_ISDIR(entry_stat.st_mode):
+                            pending.append(Path(entry.path))
+                        elif not stat.S_ISREG(entry_stat.st_mode):
+                            safe = False
+                            break
+            if not safe:
+                warning = {"code": "BPP-INBOX-CACHE-UNSAFE", "path": str(candidate)}
+                warnings.append(warning)
+                emit("warning", warning["code"],
+                     "Unsafe inactive cache was not removed", path=str(candidate))
+                continue
+            shutil.rmtree(candidate)
+            removed.append(candidate.name)
+            emit("info", "BPP-INBOX-CACHE-PRUNED",
+                 "Removed inactive plugin cache", set_id=candidate.name)
+        except OSError as error:
+            warning = {"code": "BPP-INBOX-CACHE-PRUNE-FAILED", "path": str(candidate)}
+            warnings.append(warning)
+            emit("warning", warning["code"],
+                 "Inactive plugin cache could not be removed", path=str(candidate), error=str(error))
+    return removed
+
+
+@contextmanager
+def _cache_install_lease(cache_root: Path) -> Iterator[None]:
+    """Exclude a running BedrockPlus runtime and concurrent installers."""
+
+    path = cache_root / CACHE_LEASE_FILENAME
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOINHERIT", 0)
+    try:
+        descriptor = os.open(path, flags, 0o600)
+        stream = os.fdopen(descriptor, "r+b", buffering=0)
+    except OSError as error:
+        _fail("INSTALL_CACHE_IN_USE", f"Cannot open package-cache lease: {error}")
+
+    locked = False
+    try:
+        before = path.lstat()
+        opened = os.fstat(stream.fileno())
+        if (
+            not stat.S_ISREG(before.st_mode)
+            or stat.S_ISLNK(before.st_mode)
+            or _is_reparse_point(before)
+            or before.st_nlink != 1
+            or not stat.S_ISREG(opened.st_mode)
+            or _is_reparse_point(opened)
+            or opened.st_nlink != 1
+            or not _same_open_file(before, opened)
+        ):
+            _fail("INSTALL_CACHE_LEASE", "Package-cache lease is not a safe regular file")
+        stream.seek(0)
+        try:
+            if os.name == "nt":
+                msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                fcntl.flock(stream.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            locked = True
+        except OSError as error:
+            _fail(
+                "INSTALL_CACHE_IN_USE",
+                f"Package cache is in use by another BedrockPlus runtime or installer: {error}",
+            )
+        yield
+    finally:
+        if locked:
+            try:
+                stream.seek(0)
+                if os.name == "nt":
+                    msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(stream.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        stream.close()
+
+
+def _extract_verified_entry(
+    archive: zipfile.ZipFile,
+    info: zipfile.ZipInfo,
+    destination: Path,
+    expected_digest: str | None,
+) -> None:
+    try:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        parent_stat = destination.parent.lstat()
+        if not stat.S_ISDIR(parent_stat.st_mode) or _is_reparse_point(parent_stat):
+            _fail("INSTALL_PARENT_REPARSE", f"Unsafe extraction parent: {destination.parent}")
+        flags = (
+            os.O_WRONLY
+            | os.O_CREAT
+            | os.O_EXCL
+            | getattr(os, "O_BINARY", 0)
+            | getattr(os, "O_NOFOLLOW", 0)
+        )
+        descriptor = os.open(destination, flags, 0o600)
+        digest = hashlib.sha256()
+        actual_size = 0
+        with os.fdopen(descriptor, "wb") as output, archive.open(info, "r") as source:
+            while True:
+                block = source.read(CHUNK_SIZE)
+                if not block:
+                    break
+                actual_size += len(block)
+                if actual_size > info.file_size:
+                    _fail("ZIP_SIZE_MISMATCH", f"Expanded size exceeds metadata: {info.filename}")
+                output.write(block)
+                digest.update(block)
+            output.flush()
+            os.fsync(output.fileno())
+        if actual_size != info.file_size:
+            _fail("ZIP_SIZE_MISMATCH", f"Expanded size differs from metadata: {info.filename}")
+        if expected_digest is not None and digest.hexdigest() != expected_digest:
+            _fail("INTEGRITY_MISMATCH", f"SHA-256 changed while extracting {info.filename}")
+        extracted_stat = destination.lstat()
+        if not stat.S_ISREG(extracted_stat.st_mode) or _is_reparse_point(extracted_stat):
+            _fail("INSTALL_OUTPUT_TYPE", f"Extracted path is not a regular file: {info.filename}")
+    except PackValidationError:
+        raise
+    except (OSError, RuntimeError, zipfile.BadZipFile) as error:
+        _fail("INSTALL_EXTRACT", f"Cannot extract {info.filename}: {error}")
+
+
+@contextmanager
+def _open_verified_installed_file(path: Path) -> Iterator[tuple[BinaryIO, int]]:
+    """Open one cache file without accepting a final link/reparse swap."""
+
+    try:
+        before = path.lstat()
+    except OSError as error:
+        _fail("INSTALL_TARGET_TAMPERED", f"Cannot inspect installed file {path}: {error}")
+    if (
+        not stat.S_ISREG(before.st_mode)
+        or stat.S_ISLNK(before.st_mode)
+        or _is_reparse_point(before)
+        or before.st_nlink != 1
+    ):
+        _fail("INSTALL_TARGET_TAMPERED", f"Installed path is not a regular file: {path}")
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+        stream = os.fdopen(descriptor, "rb")
+    except OSError as error:
+        _fail("INSTALL_TARGET_TAMPERED", f"Cannot open installed file {path}: {error}")
+    try:
+        opened = os.fstat(stream.fileno())
+        if (
+            not stat.S_ISREG(opened.st_mode)
+            or _is_reparse_point(opened)
+            or opened.st_nlink != 1
+            or not _same_open_file(before, opened)
+        ):
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed file changed while opening: {path}")
+        yield stream, opened.st_size
+        after = os.fstat(stream.fileno())
+        if after.st_nlink != 1 or not _same_open_file(opened, after):
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed file changed while reading: {path}")
+    finally:
+        stream.close()
+
+
+def _read_verified_installed_file(path: Path, maximum: int) -> bytes:
+    with _open_verified_installed_file(path) as (stream, expected_size):
+        if expected_size > maximum:
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed metadata is too large: {path}")
+        data = stream.read(maximum + 1)
+        if len(data) != expected_size or len(data) > maximum:
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed metadata changed: {path}")
+        return data
+
+
+def _hash_verified_installed_file(path: Path) -> str:
+    with _open_verified_installed_file(path) as (stream, expected_size):
+        digest = hashlib.sha256()
+        actual_size = 0
+        while True:
+            block = stream.read(CHUNK_SIZE)
+            if not block:
+                break
+            actual_size += len(block)
+            if actual_size > expected_size:
+                _fail("INSTALL_TARGET_TAMPERED", f"Installed file grew while hashing: {path}")
+            digest.update(block)
+        if actual_size != expected_size:
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed file size changed: {path}")
+        return digest.hexdigest()
+
+
+def _read_install_record(target: Path) -> tuple[dict[str, Any], bytes] | None:
+    record_path = target / "install.json"
+    try:
+        record_bytes = _read_verified_installed_file(record_path, 2 * 1024 * 1024)
+        record = _decode_json(record_bytes, "install.json")
+        return (record, record_bytes) if isinstance(record, dict) else None
+    except (OSError, PackValidationError):
+        return None
+
+
+def _verify_existing_install(
+    target: Path,
+    expected_record: dict[str, Any],
+    existing_record: dict[str, Any],
+    existing_record_bytes: bytes,
+    max_integrity_size: int,
+) -> None:
+    """Revalidate all immutable cache content before reporting reuse."""
+
+    try:
+        target_stat = target.lstat()
+    except OSError as error:
+        _fail("INSTALL_TARGET_TAMPERED", f"Cannot inspect install target {target}: {error}")
+    if not stat.S_ISDIR(target_stat.st_mode) or _is_reparse_point(target_stat):
+        _fail("INSTALL_TARGET_TAMPERED", f"Install target is not a regular directory: {target}")
+
+    canonical_record = _canonical_json(expected_record)
+    if existing_record != expected_record or existing_record_bytes != canonical_record:
+        _fail("INSTALL_TARGET_TAMPERED", "Existing install record differs from package metadata")
+
+    archive_files = expected_record.get("files")
+    integrity = expected_record.get("integrity")
+    if not isinstance(archive_files, list) or not isinstance(integrity, dict):
+        _fail("INSTALL_TARGET_TAMPERED", "Existing install record has an invalid file index")
+    if set(archive_files) != {*integrity, INTEGRITY_PATH}:
+        _fail("INSTALL_TARGET_TAMPERED", "Existing install record has an inconsistent integrity index")
+
+    expected_files = {"install.json", *(f"payload/{path}" for path in archive_files)}
+    expected_directories = {"payload"}
+    for relative in expected_files:
+        parts = relative.split("/")
+        for length in range(1, len(parts)):
+            expected_directories.add("/".join(parts[:length]))
+
+    actual_files: set[str] = set()
+    actual_directories: set[str] = set()
+
+    def visit(directory: Path, relative: str) -> None:
+        try:
+            directory_stat = directory.lstat()
+            if not stat.S_ISDIR(directory_stat.st_mode) or _is_reparse_point(directory_stat):
+                _fail("INSTALL_TARGET_TAMPERED", f"Unsafe installed directory: {directory}")
+            entries = list(os.scandir(directory))
+        except PackValidationError:
+            raise
+        except OSError as error:
+            _fail("INSTALL_TARGET_TAMPERED", f"Cannot scan installed directory {directory}: {error}")
+        for entry in entries:
+            child_relative = f"{relative}/{entry.name}" if relative else entry.name
+            child = Path(entry.path)
+            try:
+                child_stat = child.lstat()
+            except OSError as error:
+                _fail("INSTALL_TARGET_TAMPERED", f"Cannot inspect installed path {child}: {error}")
+            if stat.S_ISLNK(child_stat.st_mode) or _is_reparse_point(child_stat):
+                _fail("INSTALL_TARGET_TAMPERED", f"Installed cache contains a link: {child}")
+            if stat.S_ISDIR(child_stat.st_mode):
+                actual_directories.add(child_relative)
+                visit(child, child_relative)
+            elif stat.S_ISREG(child_stat.st_mode):
+                actual_files.add(child_relative)
+            else:
+                _fail("INSTALL_TARGET_TAMPERED", f"Installed cache contains a special file: {child}")
+
+    visit(target, "")
+    if actual_files != expected_files or actual_directories != expected_directories:
+        _fail("INSTALL_TARGET_TAMPERED", "Existing install contains missing or unexpected paths")
+
+    payload = target / "payload"
+    for relative, expected_digest in integrity.items():
+        path = payload.joinpath(*relative.split("/"))
+        if _hash_verified_installed_file(path) != expected_digest:
+            _fail("INSTALL_TARGET_TAMPERED", f"Installed payload hash differs: {relative}")
+    expected_integrity = _canonical_json(
+        {
+            "format_version": 1,
+            "algorithm": "sha256",
+            "files": dict(sorted(integrity.items())),
+        }
+    )
+    actual_integrity = _read_verified_installed_file(
+        payload / INTEGRITY_PATH,
+        max_integrity_size,
+    )
+    if actual_integrity != expected_integrity:
+        _fail("INSTALL_TARGET_TAMPERED", "Installed integrity.json differs from package metadata")
+    if _read_verified_installed_file(target / "install.json", 2 * 1024 * 1024) != canonical_record:
+        _fail("INSTALL_TARGET_TAMPERED", "Install record changed during cache verification")
+
+
+def _install_package_locked(
+    package_path: str | os.PathLike[str],
+    cache_root: Path,
+    *,
+    limits: PackLimits = DEFAULT_LIMITS,
+) -> dict[str, Any]:
+    """Validate, stage, and atomically activate one immutable package payload."""
+
+    package = Path(package_path)
+    try:
+        staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=cache_root))
+    except OSError as error:
+        _fail("INSTALL_STAGING_CREATE", f"Cannot create install staging directory: {error}")
+
+    activated = False
+    try:
+        payload = staging / "payload"
+        payload.mkdir()
+        with _open_package_archive(package, limits) as (archive, inspection):
+            for archive_path in sorted(inspection.entries):
+                info = inspection.entries[archive_path]
+                destination = payload.joinpath(*archive_path.split("/"))
+                if not _path_is_within(destination, payload):
+                    _fail("INSTALL_PATH_ESCAPE", f"Extraction path escaped staging: {archive_path}")
+                _extract_verified_entry(
+                    archive,
+                    info,
+                    destination,
+                    inspection.expected_digests.get(archive_path),
+                )
+
+            runtime = inspection.manifest["runtime"]
+            record = {
+                "format_version": 1,
+                "id": inspection.result["id"],
+                "name": inspection.result["name"],
+                "version": inspection.result["version"],
+                "api_version": inspection.manifest["api_version"],
+                "runtime": runtime,
+                "dependencies": inspection.manifest.get("dependencies", []),
+                "packs": inspection.manifest.get("packs", []),
+                "package_sha256": inspection.result["sha256"],
+                "files": sorted(inspection.entries),
+                "integrity": dict(sorted(inspection.expected_digests.items())),
+            }
+            record_path = staging / "install.json"
+            with record_path.open("xb") as record_stream:
+                record_stream.write(_canonical_json(record))
+                record_stream.flush()
+                os.fsync(record_stream.fileno())
+
+        installed_root = _ensure_private_directory_tree(cache_root / "installed")
+        plugin_root = _ensure_private_directory_tree(installed_root / record["id"])
+        target = plugin_root / f"{record['version']}-{record['package_sha256']}"
+        reused = False
+        try:
+            os.rename(staging, target)
+            activated = True
+        except FileExistsError:
+            existing = _read_install_record(target)
+            if existing is None or existing[0].get("package_sha256") != record["package_sha256"]:
+                _fail("INSTALL_TARGET_CONFLICT", f"Install target already exists with other content: {target}")
+            _verify_existing_install(
+                target,
+                record,
+                existing[0],
+                existing[1],
+                limits.max_integrity_size,
+            )
+            reused = True
+
+        result = dict(inspection.result)
+        result.update(
+            {
+                "installed": True,
+                "reused": reused,
+                "installed_path": str(target),
+                "entrypoint": str(target / "payload" / Path(runtime["entrypoint"])),
+            }
+        )
+        return result
+    finally:
+        if not activated and staging.exists():
+            _remove_staging_directory(staging, cache_root)
+
+
+def install_package(
+    package_path: str | os.PathLike[str],
+    cache_directory: str | os.PathLike[str],
+    *,
+    limits: PackLimits = DEFAULT_LIMITS,
+) -> dict[str, Any]:
+    """Validate and atomically install one package under an exclusive cache lease."""
+
+    cache_root = _ensure_private_directory_tree(Path(cache_directory))
+    with _cache_install_lease(cache_root):
+        return _install_package_locked(package_path, cache_root, limits=limits)
+
+
+def sync_inbox(
+    inbox_directory: str | os.PathLike[str],
+    cache_directory: str | os.PathLike[str],
+    *,
+    limits: PackLimits = DEFAULT_LIMITS,
+    maximum_plugins: int = 128,
+    maximum_expanded_bytes: int = 2 * 1024 * 1024 * 1024,
+) -> dict[str, Any]:
+    """Prepare one complete plugin set; never run package code or alter the inbox.
+
+    The returned cache_path is directly consumable by PluginOrchestrator.
+    current.json is published only after the entire set has been validated and
+    installed. Old run sets remain available for an already-running server.
+    """
+    inbox = Path(os.path.abspath(inbox_directory))
+    cache = Path(os.path.abspath(cache_directory))
+    if _path_is_within(cache, inbox) or _path_is_within(inbox, cache):
+        _fail("INBOX_CACHE_OVERLAP", "Inbox and internal cache must be separate directory trees")
+    if maximum_plugins < 1 or maximum_plugins > 128 or maximum_expanded_bytes < 1:
+        _fail("INBOX_LIMITS", "Invalid inbox limits")
+    cache = _ensure_private_directory_tree(cache)
+    now = datetime.now(timezone.utc)
+    log_root = _ensure_private_directory_tree(cache / "logs" / now.strftime("%Y-%m-%d"))
+    log_path = log_root / f"inbox-{now.strftime('%H-%M-%S')}-{uuid.uuid4().hex}.jsonl"
+    warnings: list[dict[str, Any]] = []
+    with log_path.open("x", encoding="utf-8", newline="\n") as log:
+        source_staging: Path | None = None
+        def emit(level: str, code: str, message: str, **fields: Any) -> None:
+            record = {"timestamp": datetime.now(timezone.utc).isoformat(),
+                      "level": level, "code": code, "message": message, **fields}
+            log.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+            log.flush()
+
+        try:
+            emit("info", "BPP-INBOX-START", "Preparing plugin inbox", path=str(inbox))
+            # Inspect every existing parent without creating anything in the inbox.
+            for directory in [*reversed(inbox.parents), inbox]:
+                metadata = directory.lstat()
+                if not stat.S_ISDIR(metadata.st_mode) or _is_reparse_point(metadata) or directory.is_symlink():
+                    _fail("INBOX_UNSAFE_PATH", f"Inbox path is not a regular directory: {directory}")
+            packages: list[Path] = []
+            names: set[str] = set()
+            entries: list[Path] = []
+            for entry in inbox.iterdir():
+                entries.append(entry)
+                if len(entries) > 4096:
+                    _fail("INBOX_TOO_MANY_ENTRIES", "Inbox exceeds the directory-entry limit")
+            for entry in sorted(entries, key=lambda path: path.name.casefold()):
+                metadata = entry.lstat()
+                if _is_reparse_point(metadata) or entry.is_symlink():
+                    _fail("INBOX_UNSAFE_PACKAGE", f"Inbox entries cannot be links: {entry}")
+                folder = stat.S_ISDIR(metadata.st_mode)
+                if (folder and not (entry / MANIFEST_PATH).exists()) or (
+                        not folder and entry.suffix.casefold() != ".bppack"):
+                    warning = {"code": "BPP-INBOX-IGNORED", "path": str(entry)}
+                    warnings.append(warning)
+                    emit("warning", warning["code"], "Expected .bppack or a plugin folder with manifest.json", path=str(entry))
+                    continue
+                if not folder and (not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1):
+                    _fail("INBOX_UNSAFE_PACKAGE", f"Package must be a regular single-link file: {entry}")
+                if entry.name.casefold() in names:
+                    _fail("INBOX_NAME_COLLISION", "Package filenames collide ignoring case")
+                names.add(entry.name.casefold())
+                packages.append(entry)
+                if len(packages) > maximum_plugins:
+                    _fail("INBOX_TOO_MANY_PLUGINS", "Inbox exceeds the plugin-count limit")
+
+            with _cache_install_lease(cache):
+                package_sources: dict[str, Path] = {}
+                selected: list[dict[str, Any]] = []
+                ids: set[str] = set()
+                total = 0
+                for package in packages:
+                    if package.is_dir():
+                        if source_staging is None:
+                            source_staging = Path(tempfile.mkdtemp(prefix=".staging-sources-", dir=cache))
+                        archive = source_staging / f"{len(package_sources)}.bppack"
+                        validated = build_package(package, archive, limits=limits)
+                        package_sources[package.name] = archive
+                        emit("info", "BPP-INBOX-FOLDER", "Plugin folder snapshotted without executing code", path=str(package))
+                    else:
+                        validated = validate_package(package, limits)
+                        package_sources[package.name] = package
+                    if validated["id"] in ids:
+                        _fail("INBOX_DUPLICATE_ID", f"More than one package declares {validated['id']}")
+                    ids.add(validated["id"])
+                    total += validated["expanded_size"]
+                    if total > maximum_expanded_bytes:
+                        _fail("INBOX_TOTAL_SIZE", "Inbox exceeds the expanded-size limit")
+                    selected.append({"id": validated["id"], "version": validated["version"],
+                                     "sha256": validated["sha256"], "package": package.name})
+                    emit("info", "BPP-INBOX-VALIDATED", "Plugin package validated",
+                         plugin_id=validated["id"], version=validated["version"], sha256=validated["sha256"])
+                selected.sort(key=lambda item: item["id"])
+                # Format 2 run sets retain exact package snapshots for automatic
+                # bundled-pack binding. The changed identity migrates safely from
+                # older immutable sets instead of editing them in place.
+                selection = {"format_version": 2, "plugins": selected}
+                selection_bytes = _canonical_json(selection)
+                set_id = hashlib.sha256(selection_bytes).hexdigest()
+                sets = _ensure_private_directory_tree(cache / "sets")
+                target = sets / set_id
+                reused = target.exists()
+                staging: Path | None = None
+                try:
+                    if reused:
+                        _ensure_private_directory_tree(target)
+                        if _read_verified_installed_file(target / "selection.json", 128 * 1024) != selection_bytes:
+                            _fail("INBOX_SET_TAMPERED", "Cached plugin selection differs from its identity")
+                    # Always prepare in a new tree. A source package changing
+                    # during this operation must never mutate a published set.
+                    staging = Path(tempfile.mkdtemp(prefix=".staging-inbox-", dir=cache))
+                    prepared = staging
+                    with _cache_install_lease(prepared):
+                        installed = _ensure_private_directory_tree(prepared / "installed")
+                        snapshots = _ensure_private_directory_tree(prepared / "packages")
+                        for expected in selected:
+                            # Retain the exact validated archive in the immutable
+                            # run set. Folder-form plugins therefore have the same
+                            # downstream pack-preparation input as .bppack files.
+                            snapshot = snapshots / f"{expected['id']}.bppack"
+                            shutil.copyfile(package_sources[expected["package"]], snapshot)
+                            snapshotted = validate_package(snapshot, limits)
+                            if any(snapshotted[key] != expected[key] for key in ("id", "version", "sha256")):
+                                _fail("INBOX_CHANGED", "A package changed while its run-set snapshot was created")
+                            result = _install_package_locked(snapshot, prepared, limits=limits)
+                            if any(result[key] != expected[key] for key in ("id", "version", "sha256")):
+                                _fail("INBOX_CHANGED", "A package changed between validation and installation")
+                            source_after = validate_package(package_sources[expected["package"]], limits)
+                            if any(source_after[key] != expected[key] for key in ("id", "version", "sha256")):
+                                _fail("INBOX_CHANGED", "A package changed while the prepared set was built")
+                            plugin_root = installed / expected["id"]
+                            if len(list(plugin_root.iterdir())) != 1:
+                                _fail("INBOX_SET_TAMPERED", "A plugin has unexpected cached versions")
+                            emit("info", "BPP-INBOX-INSTALLED", "Plugin ready in prepared set", plugin_id=expected["id"])
+                        with (prepared / "selection.json").open("xb") as output:
+                            output.write(selection_bytes)
+                            output.flush()
+                            os.fsync(output.fileno())
+                    if reused:
+                        # Compare against records derived from the fresh archive,
+                        # not against self-reported hashes in the old cache.
+                        # Use the same lease held by the plugin runtime.
+                        with _cache_install_lease(target):
+                            old_installed = target / "installed"
+                            old_snapshots = target / "packages"
+                            if not old_installed.is_dir() or not old_snapshots.is_dir():
+                                _fail("INBOX_SET_TAMPERED", "Cached installed or package-snapshot directory is missing")
+                            _ensure_private_directory_tree(old_installed)
+                            _ensure_private_directory_tree(old_snapshots)
+                            if {path.name for path in old_installed.iterdir()} != ids:
+                                _fail("INBOX_SET_TAMPERED", "Cached plugin set has missing or unexpected plugin IDs")
+                            if {path.name for path in old_snapshots.iterdir()} != {f"{plugin_id}.bppack" for plugin_id in ids}:
+                                _fail("INBOX_SET_TAMPERED", "Cached package snapshots are missing or unexpected")
+                            for expected in selected:
+                                old_plugin = old_installed / expected["id"]
+                                _ensure_private_directory_tree(old_plugin)
+                                version_name = f"{expected['version']}-{expected['sha256']}"
+                                if {path.name for path in old_plugin.iterdir()} != {version_name}:
+                                    _fail("INBOX_SET_TAMPERED", "Cached plugin versions differ from selection")
+                                fresh = _read_install_record(installed / expected["id"] / version_name)
+                                old = _read_install_record(old_plugin / version_name)
+                                if fresh is None or old is None:
+                                    _fail("INBOX_SET_TAMPERED", "Cannot verify cached install record")
+                                _verify_existing_install(old_plugin / version_name, fresh[0], old[0], old[1], limits.max_integrity_size)
+                                cached_package = validate_package(old_snapshots / f"{expected['id']}.bppack", limits)
+                                if any(cached_package[key] != expected[key] for key in ("id", "version", "sha256")):
+                                    _fail("INBOX_SET_TAMPERED", "Cached package snapshot identity differs")
+                    else:
+                        os.rename(staging, target)
+                        staging = None
+
+                    active = {"format_version": 1, "set_id": set_id, "relative_cache": f"sets/{set_id}"}
+                    current = cache / "current.json"
+                    if current.exists() or current.is_symlink():
+                        # Never replace a reparse point or a multiply linked file.
+                        _read_verified_installed_file(current, 4096)
+                    temporary = cache / f".current-{uuid.uuid4().hex}.json"
+                    try:
+                        with temporary.open("xb") as output:
+                            output.write(_canonical_json(active))
+                            output.flush()
+                            os.fsync(output.fileno())
+                        os.replace(temporary, current)
+                    finally:
+                        if temporary.exists():
+                            temporary.unlink()
+                    pruned_sets = _prune_inactive_plugin_sets(sets, target, emit, warnings)
+                    emit("info", "BPP-INBOX-READY", "Complete plugin set published",
+                         set_id=set_id, plugin_count=len(selected), pruned_sets=len(pruned_sets))
+                    return {"ready": True, "set_id": set_id, "cache_path": str(target),
+                            "package_paths": [str(target / "packages" / f"{item['id']}.bppack") for item in selected],
+                            "plugins": selected, "reused": reused, "warnings": warnings,
+                            "pruned_sets": pruned_sets, "log_path": str(log_path)}
+                finally:
+                    if staging is not None:
+                        _remove_staging_directory(staging, cache)
+        except PackValidationError as error:
+            emit("error", error.code, str(error))
+            raise
+        except OSError as error:
+            emit("error", "INBOX_IO", str(error))
+            _fail("INBOX_IO", f"Could not prepare plugin inbox: {error}")
+        finally:
+            if source_staging is not None:
+                _remove_staging_directory(source_staging, cache)
+
+
+def build_package(
+    source_directory: str | os.PathLike[str],
+    output_path: str | os.PathLike[str],
+    *,
+    overwrite: bool = False,
+    limits: PackLimits = DEFAULT_LIMITS,
+) -> dict[str, Any]:
+    """Build, atomically publish, and revalidate a deterministic .bppack."""
+
+    source_argument = Path(source_directory).absolute()
+    try:
+        source_stat = source_argument.lstat()
+    except OSError as error:
+        _fail("SOURCE_NOT_DIRECTORY", f"Cannot inspect package source: {error}")
+    if stat.S_ISLNK(source_stat.st_mode) or _is_reparse_point(source_stat):
+        _fail("SOURCE_LINK", "The package source root cannot be a link or reparse point")
+    source = source_argument.resolve()
+    output = Path(output_path).resolve()
+    if not source.is_dir():
+        _fail("SOURCE_NOT_DIRECTORY", f"Package source is not a directory: {source}")
+    if output.suffix.casefold() != ".bppack":
+        _fail("PACKAGE_EXTENSION", "Output filename must end in .bppack")
+    if _path_is_within(output, source):
+        _fail("OUTPUT_INSIDE_SOURCE", "Output package must not be placed inside its source tree")
+    if output.exists() and not overwrite:
+        _fail("OUTPUT_EXISTS", f"Output already exists (use --force): {output}")
+
+    files = _scan_source(source, limits)
+    if MANIFEST_PATH not in files:
+        _fail("MANIFEST_MISSING", "Package source has no root manifest.json")
+    manifest_bytes = _read_source_limited(
+        files[MANIFEST_PATH], limits.max_manifest_size
+    )
+    manifest = _decode_json(manifest_bytes, MANIFEST_PATH)
+    _validate_manifest(manifest, set(files))
+    canonical_manifest = _canonical_json(manifest)
+    if len(canonical_manifest) > limits.max_manifest_size:
+        _fail("ENTRY_TOO_LARGE", "Canonical manifest.json exceeds its size limit")
+
+    digests: dict[str, str] = {}
+    for path in sorted(files):
+        if path == MANIFEST_PATH:
+            digests[path] = hashlib.sha256(canonical_manifest).hexdigest()
+        else:
+            digests[path] = _hash_source_path(files[path], limits.max_file_size)
+    integrity = {
+        "format_version": 1,
+        "algorithm": "sha256",
+        "files": digests,
+    }
+    integrity_bytes = _canonical_json(integrity)
+    if len(integrity_bytes) > limits.max_integrity_size:
+        _fail("ENTRY_TOO_LARGE", "Generated integrity.json exceeds its size limit")
+
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary_name = tempfile.mkstemp(
+            prefix=f".{output.name}.", suffix=".bppack", dir=output.parent
+        )
+        os.close(descriptor)
+    except OSError as error:
+        _fail("OUTPUT_CREATE_FAILED", f"Cannot create output staging file: {error}")
+
+    temporary = Path(temporary_name)
+    try:
+        try:
+            with zipfile.ZipFile(
+                temporary,
+                "w",
+                compression=zipfile.ZIP_DEFLATED,
+                compresslevel=9,
+                allowZip64=False,
+            ) as archive:
+                for path in sorted((*files.keys(), INTEGRITY_PATH)):
+                    if path == MANIFEST_PATH:
+                        _write_bytes(archive, path, canonical_manifest)
+                    elif path == INTEGRITY_PATH:
+                        _write_bytes(archive, path, integrity_bytes)
+                    else:
+                        _write_file(
+                            archive,
+                            path,
+                            files[path],
+                            limits.max_file_size,
+                        )
+        except (OSError, zipfile.LargeZipFile) as error:
+            _fail("OUTPUT_WRITE_FAILED", f"Cannot write package: {error}")
+
+        if _scan_source(source, limits) != files:
+            _fail("SOURCE_CHANGED", "Package source changed while the archive was built")
+        result = validate_package(temporary, limits)
+        try:
+            if output.exists() and not overwrite:
+                _fail("OUTPUT_EXISTS", f"Output appeared while building: {output}")
+            os.replace(temporary, output)
+        except OSError as error:
+            _fail("OUTPUT_PUBLISH_FAILED", f"Cannot publish package: {error}")
+    finally:
+        if temporary.exists():
+            try:
+                temporary.unlink()
+            except OSError:
+                pass
+
+    result["path"] = str(output)
+    return result
+
+
+def _human_size(value: int) -> str:
+    size = float(value)
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if size < 1024 or unit == "GiB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{value} B"
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bppack",
+        description="Build and validate BedrockPlus plugin packages",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    build = subparsers.add_parser("build", help="build a deterministic package")
+    build.add_argument("source", help="package payload directory")
+    build.add_argument("output", help="output .bppack path")
+    build.add_argument("--force", action="store_true", help="replace an existing output")
+    build.add_argument("--json", action="store_true", help="print structured JSON")
+
+    validate = subparsers.add_parser("validate", help="validate an existing package")
+    validate.add_argument("package", help="input .bppack path")
+    validate.add_argument("--json", action="store_true", help="print structured JSON")
+
+    install = subparsers.add_parser(
+        "install", help="validate and atomically install a package into an internal cache"
+    )
+    install.add_argument("package", help="input .bppack path")
+    install.add_argument("cache", help="private BedrockPlus package-cache directory")
+    install.add_argument("--json", action="store_true", help="print structured JSON")
+    sync = subparsers.add_parser("sync", help="prepare a complete plugins/ inbox for the native/Python runtime")
+    sync.add_argument("inbox", help="directory where the operator drops .bppack files")
+    sync.add_argument("cache", help="private BedrockPlus run-set cache (outside the inbox)")
+    sync.add_argument("--json", action="store_true", help="print structured JSON")
+    return parser
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    arguments = _create_parser().parse_args(list(argv) if argv is not None else None)
+    try:
+        if arguments.command == "build":
+            result = build_package(arguments.source, arguments.output, overwrite=arguments.force)
+        elif arguments.command == "validate":
+            result = validate_package(arguments.package)
+        elif arguments.command == "sync":
+            result = sync_inbox(arguments.inbox, arguments.cache)
+        else:
+            result = install_package(arguments.package, arguments.cache)
+    except PackValidationError as error:
+        if getattr(arguments, "json", False):
+            print(json.dumps(error.as_dict(), ensure_ascii=False, sort_keys=True))
+        else:
+            print(f"ERROR [{error.code}] {error}", file=sys.stderr)
+        return 2
+
+    if arguments.json:
+        print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    elif arguments.command == "build":
+        print(
+            f"Built {result['id']} {result['version']} -> {result['path']} "
+            f"({result['sha256']})"
+        )
+    elif arguments.command == "validate":
+        print(
+            f"VALID {result['id']} {result['version']} "
+            f"({result['runtime']}, {result['files']} files, "
+            f"{_human_size(result['expanded_size'])})"
+        )
+    elif arguments.command == "sync":
+        print(f"Ready: {len(result['plugins'])} plugins -> {result['cache_path']}")
+        print(f"Validation log: {result['log_path']}")
+    else:
+        action = "Reused" if result["reused"] else "Installed"
+        print(
+            f"{action} {result['id']} {result['version']} -> "
+            f"{result['installed_path']}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())