cf-bootstrap-source-local 0.1.0__py3-none-any.whl

cf_bootstrap_source_local/resolver.py

@@ -0,0 +1,573 @@
+"""JSON-lines entry point for deterministic local artifact resolution."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import hashlib
+from cf_bootstrap_source_pypi.release_authority import canonical as release_canonical, operation_catalog, select as release_select, target_environment as release_environment
+
+from .artifacts import _safe_zip_name, _validate_record, native_authority, native_executable_sha256, validate_wheel, validate_native_wheel
+from .build import build
+from .inventory import dependency_closure, inventory, inventory_natives
+from .native import _platform, package_native
+from .model import PROTOCOL, REQUEST_SCHEMA, RESULT_SCHEMA, ResolverError, canonical_json, parse_request
+from .capabilities import discover
+from .profiles import load_catalog
+from packaging.requirements import Requirement
+from packaging.version import Version, InvalidVersion
+
+_FIELDS = {"jsonrpc", "protocol", "id", "method", "params"}
+
+
+def _stable_report(value: object) -> object:
+    if isinstance(value, dict):
+        return {key: _stable_report(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_stable_report(item) for item in value]
+    if isinstance(value, str) and value.startswith("file://"):
+        return "file://" + Path(value[7:]).name
+    return value
+
+
+def _response(identifier: object, **body: object) -> dict[str, object]:
+    return {"jsonrpc": "2.0", "protocol": PROTOCOL, "id": identifier, **body}
+
+
+def _package_transition_natives(natives_to_package: list[tuple], staging: Path, authority: dict[str, str]) -> list[dict[str, object]]:
+    """Repackage installed executables against one complete accepted authority set."""
+    return [
+        package_native(native, binary, staging, accepted_digest, authority)
+        for native, binary, accepted_digest in natives_to_package
+    ]
+
+
+def resolve(params: object) -> dict[str, object]:
+    plan, output = parse_request(params)
+    checkout = Path(plan["artifact_source"]["checkout_path"])
+    projects, source_digest, index_digest = inventory(checkout)
+    expected_source = os.environ.get("CF_TRANSITION_SOURCE_DIGEST")
+    if expected_source is not None and source_digest != expected_source:
+        raise ResolverError("SOURCE_AUTHORITY_DRIFT", "accepted checkout source authority changed")
+    return _resolve_v2(params, plan, output, checkout, projects, source_digest, index_digest)
+
+
+def _resolve_v2(params: object, plan: dict[str, object], output: Path, checkout: Path, projects: tuple, source_digest: str, index_digest: str) -> dict[str, object]:
+    if not isinstance(params, dict) or params.get("schema") != REQUEST_SCHEMA:
+        raise ResolverError("SCHEMA_INVALID", "v2 plan requires v2 resolution request")
+    catalog = load_catalog(checkout, str(plan["profile"]))
+    phase = params.get("phase") if isinstance(params, dict) else None
+    semantic_identity = None
+    release_catalog_path = checkout / "stonecastle/cogniflow/src/cogniflow/release-catalog.json"
+    # Profile transitions can also request a bootstrap phase from the target
+    # interpreter, which deliberately has no public launcher installed. Only
+    # the isolated bootstrap host can contribute launcher catalog evidence.
+    if phase == "bootstrap" and release_catalog_path.is_file():
+        # Bootstrap authority arrives via the launcher's private operation handoff.
+        release = operation_catalog(str(plan["profile"]), plan["artifact_source"])
+        if release_catalog_path.is_symlink() or release_catalog_path.read_bytes() != release_canonical(release):
+            raise ResolverError("SOURCE_AUTHORITY_DRIFT", "checkout catalog differs from launcher authority")
+        if release["release_version"] == "0.1.16" and any(
+            item["profile"] == plan["profile"] for item in release["profiles"]
+        ):
+            semantic_identity = release_select(release, str(plan["profile"]), target_environment=release_environment())
+            if semantic_identity["selection"]["profile_digest"] != "sha256:" + str(catalog["profile"]["sha256"]):
+                raise ResolverError("PROFILE_INVALID", "source catalog and indexed TriG profile differ")
+    capabilities = tuple(catalog["profile"]["capabilities"])
+    verification = catalog["profile"].get("post_install_verification_capability")
+    if phase == "post-handoff-verify":
+        try:
+            return _verify_v2(params, plan, output, checkout, projects, source_digest, index_digest)
+        except ResolverError:
+            raise
+        except Exception as error:
+            raise ResolverError("BOUND_BUNDLE_INVALID", "bound bundle validation failed") from error
+    natives = tuple(inventory_natives(checkout)) if phase == "bootstrap" else ()
+    # These are the executable host, not profile payload.  Keeping this list
+    # explicit prevents a profile catalog from producing a target that cannot
+    # accept handoff or resolve the post-handoff delta.
+    host_capabilities = {"urn:cf:service:ProfiledBootstrapInstallationHandoff", "urn:cf:service:ProfileInstallation"}
+    if phase == "bootstrap":
+        capabilities = tuple(item for item in capabilities if item in host_capabilities)
+    elif phase == "post-handoff":
+        capabilities = tuple(item for item in capabilities if item not in host_capabilities)
+    discovered = discover(checkout, projects, capabilities)
+    provider_map = {capability: discovered[capability] for capability in capabilities}
+    roots_set = {str(item["distribution"]) for item in provider_map.values()}
+    if phase == "bootstrap":
+        roots_set.update({"cf-runtime", "cf-service-client", "cf-install-services", "cf-bootstrap-instance", "cf-bootstrap-source-local"})
+    roots = tuple(sorted(roots_set))
+    selected, external = dependency_closure(projects, roots)
+    external = list(external)
+    if phase == "post-handoff" and not roots and not selected and not external:
+        return _resolve_v2_empty(plan, output, catalog, capabilities, verification, source_digest, index_digest, len(projects))
+    external_root = Path(str(params["external_wheelhouse_path"]))
+    if output.exists():
+        manifest_path = output / "artifact-set.json"
+        try:
+            raw = manifest_path.read_bytes()
+            artifact_set = json.loads(raw)
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ResolverError("OUTPUT_CONFLICT", "existing v2 artifact output is invalid") from error
+        if raw != canonical_json(artifact_set) or not isinstance(artifact_set, dict) or artifact_set.get("schema") != "cf.bootstrap.artifact-set.v2" or artifact_set.get("plan_digest") != "sha256:" + hashlib.sha256(canonical_json(plan)).hexdigest() or artifact_set.get("profile") != plan["profile"]:
+            raise ResolverError("OUTPUT_CONFLICT", "existing v2 artifact output is not bound to the requested plan")
+        selection = {"profile": artifact_set["profile"], "profile_digest": artifact_set["profile_digest"], "catalog_digest": artifact_set["catalog_digest"], "requested_capabilities": artifact_set["requested_capabilities"], "post_install_verification_capability": artifact_set.get("post_install_verification_capability"), "provider_roots": artifact_set["selected_roots"], "first_party_closure": artifact_set["selected_first_party"], "external_requirements": artifact_set["selected_external"], "target_environment": artifact_set["target_environment"]}
+        if artifact_set.get("selection_digest") != "sha256:" + hashlib.sha256(canonical_json(selection)).hexdigest() or not isinstance(artifact_set.get("artifacts"), list):
+            raise ResolverError("OUTPUT_CONFLICT", "existing v2 artifact selection is invalid")
+        evidence = {"inventory_count": len(projects), "selected_root_count": len(roots), "selected_first_party_count": len(selected), "built_first_party_count": 0, "unselected_build_count": 0, "native_selected": False}
+        if semantic_identity is not None:
+            evidence["semantic_selection"] = semantic_identity
+        return {"schema": RESULT_SCHEMA, "wheelhouse_path": str(output), "artifact_set": artifact_set, "selection": selection, "provider_map": provider_map, "evidence": evidence}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix="cf-bootstrap-source-local-v2-", dir=str(output.parent)))
+    publication = Path(tempfile.mkdtemp(prefix="cf-bootstrap-source-local-v2-publish-", dir=str(output.parent)))
+    try:
+        cache_root = Path(os.environ["CF_TRANSITION_CACHE_ROOT"]) if os.environ.get("CF_TRANSITION_CACHE_ROOT") and phase == "bootstrap" else None
+        cached: list[dict[str, object]] = []
+        missing = []
+        if cache_root is not None:
+            mcp_projects = [native for native in natives if native.normalized_name == "cf-service-mcp-server"]
+            if len(mcp_projects) != 1:
+                raise ResolverError("NATIVE_AUTHORITY_INVALID", "accepted native authority carrier is not unique")
+            mcp = mcp_projects[0]
+            carrier_name = f"{mcp.normalized_name.replace('-', '_')}-{mcp.version}-py3-none-{_platform()[1]}.whl"
+            carrier = cache_root / carrier_name
+            if carrier.is_symlink() or not carrier.is_file():
+                raise ResolverError("NATIVE_AUTHORITY_INVALID", "accepted native authority carrier is missing")
+            accepted_native_digests = native_authority(carrier, natives)
+            for project in selected:
+                candidates = sorted(path for path in cache_root.iterdir() if path.is_file() and not path.is_symlink() and path.name.casefold().startswith(project.normalized_name.replace("-", "_") + "-"))
+                if len(candidates) > 1:
+                    raise ResolverError("CACHE_INVALID", "request cache candidate is ambiguous")
+                if candidates:
+                    checked = validate_wheel(candidates[0], project)
+                    cached.append({"distribution": checked["distribution"], "normalized_distribution": checked["normalized_distribution"], "version": checked["version"], "filename": checked["filename"], "sha256": checked["sha256"], "size": checked["size_bytes"], "source_kind": "stonecastle-local", "source_project": checked["source_project"]})
+                    shutil.copy2(candidates[0], staging / candidates[0].name)
+                else:
+                    missing.append(project)
+            natives_to_build = []
+            natives_to_package = []
+            for native in natives:
+                expected_name = f"{native.normalized_name.replace('-', '_')}-{native.version}-py3-none-" + _platform()[1] + ".whl"
+                candidates = sorted(path for path in cache_root.iterdir() if path.is_file() and not path.is_symlink() and path.name.casefold() == expected_name)
+                if len(candidates) > 1:
+                    raise ResolverError("CACHE_INVALID", "request native cache candidate is ambiguous")
+                if candidates:
+                    checked = validate_native_wheel(candidates[0], native)
+                    if native_executable_sha256(candidates[0], native) != accepted_native_digests[native.normalized_name]:
+                        raise ResolverError("NATIVE_AUTHORITY_MISMATCH", "cached native executable differs from accepted bootstrap authority")
+                    cached.append({"distribution": checked["distribution"], "normalized_distribution": checked["normalized_distribution"], "version": checked["version"], "filename": checked["filename"], "sha256": checked["sha256"], "size": checked["size_bytes"], "source_kind": "stonecastle-local", "source_project": checked["source_project"], "artifact_kind": "native", "wheel_tags": checked["wheel_tags"], "executable": checked["executable"]})
+                    shutil.copy2(candidates[0], staging / candidates[0].name)
+                else:
+                    scripts = Path(str(plan["installation_root"])) / "environment" / ("Scripts" if os.name == "nt" else "bin")
+                    natives_to_package.append((native, scripts / (native.binary + _platform()[2]), accepted_native_digests[native.normalized_name]))
+        else:
+            missing = list(selected)
+            natives_to_build = list(natives)
+            natives_to_package = []
+        built = build(tuple(missing), staging, tuple(natives_to_build))
+        built.extend(_package_transition_natives(natives_to_package, staging, accepted_native_digests if cache_root is not None else {}))
+
+        artifacts = cached
+        for item in built:
+            wheel = staging / "wheels" / str(item["filename"])
+            wheel.replace(staging / str(item["filename"]))
+            record = {
+                "distribution": item["distribution"],
+                "normalized_distribution": item["normalized_distribution"],
+                "version": item["version"],
+                "filename": item["filename"],
+                "sha256": item["sha256"],
+                "size": item["size_bytes"],
+                "source_kind": "stonecastle-local",
+                "source_project": item["source_project"],
+            }
+            if item.get("artifact_kind") == "native":
+                record.update({"artifact_kind": "native", "wheel_tags": item["wheel_tags"], "executable": item["executable"]})
+            artifacts.append(record)
+        grouped_external: dict[str, list[Requirement]] = {}
+        for requirement in external:
+            try:
+                parsed_requirement = Requirement(requirement)
+            except Exception as error:
+                raise ResolverError("DEPENDENCY_INVALID", f"external requirement is not canonical PEP 508: {requirement}") from error
+            grouped_external.setdefault(parsed_requirement.name.replace("_", "-").lower(), []).append(parsed_requirement)
+        for normalized, requirements in sorted(grouped_external.items()):
+            candidates = sorted(path for path in external_root.iterdir() if path.is_file() and path.suffix == ".whl" and path.name.casefold().startswith(normalized.replace("-", "_") + "-") and not path.name.casefold().startswith("cf-"))
+            if len(candidates) != 1:
+                raise ResolverError("EXTERNAL_SOURCE_FORBIDDEN", f"no unique external wheel for {normalized}")
+            wheel = candidates[0]
+            checked = validate_external_wheel(wheel, requirements[0])
+            if any(Version(checked["version"]) not in requirement.specifier for requirement in requirements):
+                raise ResolverError("ARTIFACT_INVALID", f"external wheel does not satisfy all requirements for {normalized}")
+            shutil.copy2(wheel, staging / wheel.name)
+            artifacts.append(checked)
+        # Include bounded transitive candidates in the offline transaction;
+        # the pip report below is the authoritative selected subset.
+        from packaging.utils import parse_wheel_filename
+        selected_names = {str(item["normalized_distribution"]) for item in artifacts}
+        for wheel in sorted(external_root.glob("*.whl"), key=lambda item: item.name.casefold()):
+            try:
+                distribution, version, _, _ = parse_wheel_filename(wheel.name)
+            except Exception as error:
+                raise ResolverError("EXTERNAL_SOURCE_FORBIDDEN", "external wheel filename is invalid") from error
+            normalized = str(distribution).replace("_", "-").lower()
+            if normalized in selected_names or normalized.startswith("cf-"):
+                continue
+            checked = validate_external_wheel(wheel, Requirement(f"{distribution}=={version}"))
+            shutil.copy2(wheel, staging / wheel.name)
+            artifacts.append(checked)
+            selected_names.add(normalized)
+        report_path = staging / "pip-resolver-report.json"
+        local_wheels = [str(staging / str(item["filename"])) for item in artifacts if item["source_kind"] == "stonecastle-local"]
+        env = os.environ.copy()
+        env.update({"PIP_NO_INDEX": "1", "PIP_DISABLE_PIP_VERSION_CHECK": "1", "PIP_CONFIG_FILE": os.devnull, "PYTHONDONTWRITEBYTECODE": "1"})
+        env.pop("PYTHONPATH", None)
+        report_result = subprocess.run([sys.executable, "-m", "pip", "install", "--dry-run", "--report", str(report_path), "--no-index", "--find-links", str(staging), "--ignore-installed", *local_wheels], env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=120, check=False)
+        if report_result.returncode != 0:
+            raise ResolverError("EXTERNAL_RESOLUTION_FAILED", "offline pip resolver report failed")
+        report = json.loads(report_path.read_text(encoding="utf-8"))
+        if not isinstance(report, dict) or not isinstance(report.get("install"), list):
+            raise ResolverError("EXTERNAL_RESOLUTION_FAILED", "pip resolver report is invalid")
+        report_names = {str(item.get("metadata", {}).get("name", "")).casefold().replace("_", "-") for item in report["install"] if isinstance(item, dict)}
+        expected_names = {str(item["normalized_distribution"]) for item in artifacts}
+        if not report_names <= expected_names:
+            raise ResolverError("SELECTION_INVALID", "pip resolver selected an unexpected distribution")
+        artifacts = [item for item in artifacts if str(item["normalized_distribution"]) in report_names]
+        external = [f"{item['distribution']}=={item['version']}" for item in artifacts if item["source_kind"] == "external-wheelhouse"]
+        report_digest = hashlib.sha256(canonical_json(_stable_report(report))).hexdigest()
+        report_path.unlink()
+        profile_digest = "sha256:" + str(catalog["profile"]["sha256"])
+        target_environment = {"implementation_name": "cpython", "python_full_version": platform.python_version(), "python_version": platform.python_version(), "sys_platform": sys.platform, "platform_system": platform.system(), "platform_machine": platform.machine().lower(), "platform_python_implementation": platform.python_implementation()}
+        selection = {"profile": plan["profile"], "profile_digest": profile_digest, "catalog_digest": catalog["catalog_digest"], "requested_capabilities": list(capabilities), "post_install_verification_capability": verification, "provider_roots": list(roots), "first_party_closure": [item.normalized_name for item in selected], "external_requirements": list(external), "target_environment": target_environment}
+        selection_digest = "sha256:" + hashlib.sha256(canonical_json(selection)).hexdigest()
+        artifact_set = {"schema": "cf.bootstrap.artifact-set.v2", "source_mode": "local-repository", "plan_digest": "sha256:" + hashlib.sha256(canonical_json(plan)).hexdigest(), "profile": plan["profile"], "profile_digest": profile_digest, "catalog_digest": catalog["catalog_digest"], "requested_capabilities": list(capabilities), "post_install_verification_capability": verification, "selected_roots": list(roots), "selected_first_party": [item.normalized_name for item in selected], "selected_external": list(external), "selection_digest": selection_digest, "repository_source_digest": source_digest, "selected_source_digest": "sha256:" + hashlib.sha256(canonical_json([item.relative for item in selected])).hexdigest(), "index_digest": index_digest, "resolver": {"mode": "pip-dry-run-report", "pip_no_index": True, "report_sha256": report_digest}, "target_environment": selection["target_environment"], "artifacts": sorted(artifacts, key=lambda item: (item["normalized_distribution"], item["filename"]))}
+        # Keep all build homes, caches, reports, and source copies out of the
+        # immutable bundle. Only the verified selected wheels are published.
+        for item in artifact_set["artifacts"]:
+            source = staging / str(item["filename"])
+            if not source.is_file() or source.is_symlink():
+                raise ResolverError("ARTIFACT_INVALID", "selected artifact is not a regular file")
+            shutil.copy2(source, publication / str(item["filename"]))
+        (publication / "artifact-set.json").write_bytes(canonical_json(artifact_set))
+        expected = {"artifact-set.json", *(str(item["filename"]) for item in artifact_set["artifacts"])}
+        actual = {item.name for item in publication.iterdir()}
+        if actual != expected or any(not item.is_file() or item.is_symlink() for item in publication.iterdir()):
+            raise ResolverError("BUNDLE_CONTENT_INVALID", "published bundle inventory is not canonical")
+        publication.rename(output)
+        shutil.rmtree(staging, ignore_errors=True)
+    except ResolverError:
+        shutil.rmtree(staging, ignore_errors=True)
+        shutil.rmtree(publication, ignore_errors=True)
+        raise
+    except (OSError, RuntimeError) as error:
+        shutil.rmtree(staging, ignore_errors=True)
+        shutil.rmtree(publication, ignore_errors=True)
+        raise ResolverError("INTERNAL_ERROR", "v2 artifact publication failed") from error
+    evidence = {"inventory_count": len(projects), "selected_root_count": len(roots), "selected_first_party_count": len(selected), "built_first_party_count": len(selected), "unselected_build_count": 0, "native_selected": False}
+    if semantic_identity is not None:
+        evidence["semantic_selection"] = semantic_identity
+    return {"schema": RESULT_SCHEMA, "wheelhouse_path": str(output), "artifact_set": artifact_set, "selection": selection, "provider_map": provider_map, "evidence": evidence}
+
+
+def _resolve_v2_empty(plan: dict[str, object], output: Path, catalog: dict[str, object], capabilities: tuple, verification: object, source_digest: str, index_digest: str, inventory_count: int) -> dict[str, object]:
+    """Publish the canonical bundle for a profile with no post-handoff payload."""
+    profile_digest = "sha256:" + str(catalog["profile"]["sha256"])
+    target_environment = {"implementation_name": "cpython", "python_full_version": platform.python_version(), "python_version": platform.python_version(), "sys_platform": sys.platform, "platform_system": platform.system(), "platform_machine": platform.machine().lower(), "platform_python_implementation": platform.python_implementation()}
+    selection = {"profile": plan["profile"], "profile_digest": profile_digest, "catalog_digest": catalog["catalog_digest"], "requested_capabilities": list(capabilities), "post_install_verification_capability": verification, "provider_roots": [], "first_party_closure": [], "external_requirements": [], "target_environment": target_environment}
+    selection_digest = "sha256:" + hashlib.sha256(canonical_json(selection)).hexdigest()
+    artifact_set = {"schema": "cf.bootstrap.artifact-set.v2", "source_mode": "local-repository", "plan_digest": "sha256:" + hashlib.sha256(canonical_json(plan)).hexdigest(), "profile": plan["profile"], "profile_digest": profile_digest, "catalog_digest": catalog["catalog_digest"], "requested_capabilities": list(capabilities), "post_install_verification_capability": verification, "selected_roots": [], "selected_first_party": [], "selected_external": [], "selection_digest": selection_digest, "repository_source_digest": source_digest, "selected_source_digest": "sha256:" + hashlib.sha256(canonical_json([])).hexdigest(), "index_digest": index_digest, "resolver": {"mode": "empty-closure", "pip_no_index": True, "report_sha256": hashlib.sha256(canonical_json({"install": []})).hexdigest()}, "target_environment": target_environment, "artifacts": []}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if output.exists():
+        manifest_path = output / "artifact-set.json"
+        try:
+            raw = manifest_path.read_bytes()
+            existing = json.loads(raw)
+            entries = list(output.iterdir())
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ResolverError("OUTPUT_CONFLICT", "existing empty v2 artifact output is invalid") from error
+        if raw != canonical_json(existing) or existing != artifact_set or len(entries) != 1 or entries[0] != manifest_path or not manifest_path.is_file() or manifest_path.is_symlink():
+            raise ResolverError("OUTPUT_CONFLICT", "existing empty v2 artifact output is not canonical")
+        return {"schema": RESULT_SCHEMA, "wheelhouse_path": str(output), "artifact_set": artifact_set, "selection": selection, "provider_map": {}, "evidence": {"inventory_count": inventory_count, "selected_root_count": 0, "selected_first_party_count": 0, "built_first_party_count": 0, "unselected_build_count": 0, "native_selected": False}}
+    publication = Path(tempfile.mkdtemp(prefix="cf-bootstrap-source-local-v2-empty-", dir=str(output.parent)))
+    try:
+        (publication / "artifact-set.json").write_bytes(canonical_json(artifact_set))
+        publication.rename(output)
+    except (OSError, RuntimeError) as error:
+        shutil.rmtree(publication, ignore_errors=True)
+        raise ResolverError("INTERNAL_ERROR", "v2 artifact publication failed") from error
+    return {"schema": RESULT_SCHEMA, "wheelhouse_path": str(output), "artifact_set": artifact_set, "selection": selection, "provider_map": {}, "evidence": {"inventory_count": inventory_count, "selected_root_count": 0, "selected_first_party_count": 0, "built_first_party_count": 0, "unselected_build_count": 0, "native_selected": False}}
+
+
+def _verify_external_selection(bound: object, indexed: tuple, entries: list) -> None:
+    """Prove exact bound pins are equivalent to the indexed constraints."""
+    if not isinstance(bound, list) or any(not isinstance(item, str) for item in bound):
+        raise ResolverError("SELECTION_MISMATCH", "bound external selection is invalid")
+    requirements: dict[str, list[Requirement]] = {}
+    try:
+        for value in indexed:
+            requirement = Requirement(value)
+            normalized = requirement.name.replace("_", "-").lower()
+            requirements.setdefault(normalized, []).append(requirement)
+    except Exception as error:
+        raise ResolverError("SELECTION_MISMATCH", "indexed external selection is invalid") from error
+
+    pins: dict[str, tuple[Requirement, Version]] = {}
+    try:
+        for value in bound:
+            requirement = Requirement(value)
+            specifiers = list(requirement.specifier)
+            normalized = requirement.name.replace("_", "-").lower()
+            if str(requirement) != value or requirement.extras or requirement.marker is not None or requirement.url is not None or len(specifiers) != 1 or specifiers[0].operator != "==" or normalized in pins:
+                raise ValueError
+            pins[normalized] = (requirement, Version(specifiers[0].version))
+    except (InvalidVersion, ValueError) as error:
+        raise ResolverError("SELECTION_MISMATCH", "bound external selection is not canonical exact pins") from error
+    if set(pins) != set(requirements):
+        raise ResolverError("SELECTION_MISMATCH", "bound external selection is incomplete")
+
+    external_entries: dict[str, dict] = {}
+    for item in entries:
+        if isinstance(item, dict) and item.get("source_kind") == "external-wheelhouse":
+            normalized = item.get("normalized_distribution")
+            if not isinstance(normalized, str):
+                raise ResolverError("SELECTION_MISMATCH", "bound external artifact selection is invalid")
+            normalized = normalized.replace("_", "-").lower()
+            if normalized in external_entries:
+                raise ResolverError("SELECTION_MISMATCH", "bound external artifact selection is not unique")
+            external_entries[normalized] = item
+    if set(external_entries) != set(requirements):
+        raise ResolverError("SELECTION_MISMATCH", "bound external artifacts do not match the indexed selection")
+
+    for normalized, constraints in requirements.items():
+        requirement, version = pins[normalized]
+        entry = external_entries[normalized]
+        if requirement.name.replace("_", "-").lower() != normalized or str(entry.get("normalized_distribution")).replace("_", "-").lower() != normalized or str(entry.get("version")) != str(version) or any(version not in constraint.specifier for constraint in constraints):
+            raise ResolverError("SELECTION_MISMATCH", "bound external pin does not satisfy the indexed selection")
+
+
+def _verify_v2(params: object, plan: dict[str, object], output: Path, checkout: Path, projects: tuple, source_digest: str, index_digest: str) -> dict[str, object]:
+    """Replay an already published bundle without invoking a build tool."""
+    if not _link_free(output) or not output.is_dir() or output.is_symlink():
+        raise ResolverError("BOUND_BUNDLE_MISSING", "bound post-handoff bundle is missing")
+    manifest_path = output / "artifact-set.json"
+    try:
+        raw = manifest_path.read_bytes()
+        artifact_set = json.loads(raw)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound artifact manifest is invalid") from error
+    if raw != canonical_json(artifact_set) or not isinstance(artifact_set, dict):
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound artifact manifest is not canonical")
+    if artifact_set.get("schema") != "cf.bootstrap.artifact-set.v2" or artifact_set.get("plan_digest") != "sha256:" + hashlib.sha256(canonical_json(plan)).hexdigest():
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound artifact manifest is not plan-bound")
+    if artifact_set.get("repository_source_digest") != source_digest or artifact_set.get("index_digest") != index_digest:
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound source or index identity changed")
+    expected_bindings = {"bound_artifact_set_digest": "sha256:" + hashlib.sha256(canonical_json(artifact_set)).hexdigest(), "bound_selection_digest": artifact_set.get("selection_digest"), "bound_profile_digest": artifact_set.get("profile_digest"), "bound_catalog_digest": artifact_set.get("catalog_digest"), "bound_repository_source_digest": artifact_set.get("repository_source_digest"), "bound_index_digest": artifact_set.get("index_digest")}
+    if any(params.get(key) != value for key, value in expected_bindings.items()):
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound artifact identity does not match the receipt")
+    catalog = load_catalog(checkout, str(plan["profile"]))
+    host_capabilities = {"urn:cf:service:ProfiledBootstrapInstallationHandoff", "urn:cf:service:ProfileInstallation"}
+    capabilities = tuple(item for item in catalog["profile"]["capabilities"] if item not in host_capabilities)
+    discovered = discover(checkout, projects, capabilities)
+    provider_map = {capability: discovered[capability] for capability in capabilities}
+    roots = tuple(sorted({str(item["distribution"]) for item in provider_map.values()}))
+    selected, external = dependency_closure(projects, roots)
+    expected_selection = {
+        "profile": plan["profile"],
+        "profile_digest": "sha256:" + str(catalog["profile"]["sha256"]),
+        "catalog_digest": catalog["catalog_digest"],
+        "requested_capabilities": list(capabilities),
+        "post_install_verification_capability": catalog["profile"].get("post_install_verification_capability"),
+        "provider_roots": list(roots),
+        "first_party_closure": [item.normalized_name for item in selected],
+        "external_requirements": artifact_set.get("selected_external"),
+        "target_environment": artifact_set.get("target_environment"),
+    }
+    selection = {"profile": artifact_set.get("profile"), "profile_digest": artifact_set.get("profile_digest"), "catalog_digest": artifact_set.get("catalog_digest"), "requested_capabilities": artifact_set.get("requested_capabilities"), "post_install_verification_capability": artifact_set.get("post_install_verification_capability"), "provider_roots": artifact_set.get("selected_roots"), "first_party_closure": artifact_set.get("selected_first_party"), "external_requirements": artifact_set.get("selected_external"), "target_environment": artifact_set.get("target_environment")}
+    if selection != expected_selection:
+        raise ResolverError("SELECTION_MISMATCH", "bound selection does not match the indexed profile")
+    if artifact_set.get("selection_digest") != "sha256:" + hashlib.sha256(canonical_json(selection)).hexdigest():
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound selection digest is invalid")
+    entries = artifact_set.get("artifacts")
+    if not isinstance(entries, list) or (not entries and (selection["provider_roots"] or selection["first_party_closure"] or selection["external_requirements"])):
+        raise ResolverError("BOUND_BUNDLE_INVALID", "bound artifact list is invalid")
+    _verify_external_selection(selection["external_requirements"], external, entries)
+    expected_files = {"artifact-set.json"}
+    for item in entries:
+        try:
+            from packaging.utils import parse_wheel_filename
+            allowed = {"distribution", "normalized_distribution", "version", "filename", "sha256", "size", "source_kind"}
+            if isinstance(item, dict) and item.get("source_kind") == "stonecastle-local":
+                allowed.add("source_project")
+            if isinstance(item, dict) and item.get("artifact_kind") == "native":
+                allowed |= {"artifact_kind", "wheel_tags", "executable"}
+            if not isinstance(item, dict) or set(item) - allowed or not isinstance(item.get("filename"), str):
+                raise ResolverError("ARTIFACT_ENTRY_INVALID", "bound artifact entry is invalid")
+            required = {"distribution", "normalized_distribution", "version", "filename", "sha256", "size", "source_kind"}
+            if isinstance(item, dict) and item.get("source_kind") == "stonecastle-local":
+                required.add("source_project")
+            if not required.issubset(item):
+                raise ResolverError("ARTIFACT_ENTRY_INVALID", "bound artifact entry fields are incomplete")
+            distribution, filename_version, _, filename_tags = parse_wheel_filename(item["filename"])
+            if str(distribution).replace("_", "-").lower() != str(item["normalized_distribution"]).lower() or str(filename_version) != str(item["version"]):
+                raise ResolverError("ARTIFACT_METADATA_MISMATCH", "wheel filename does not match its artifact entry")
+            if item.get("source_kind") == "stonecastle-local":
+                if not any(project.normalized_name == str(item["normalized_distribution"]).lower() and project.relative == item["source_project"] for project in projects):
+                    raise ResolverError("ARTIFACT_PROVENANCE_INVALID", "first-party artifact provenance is invalid")
+            elif item.get("source_kind") != "external-wheelhouse":
+                raise ResolverError("ARTIFACT_PROVENANCE_INVALID", "artifact source kind is invalid")
+            filename = item["filename"]
+            wheel = output / filename
+            if wheel.is_symlink() or not wheel.is_file() or filename in expected_files or not _link_free(wheel) or wheel.resolve().parent != output.resolve():
+                raise ResolverError("WHEEL_MISSING_OR_UNSAFE", "bound wheel is missing or unsafe")
+            if wheel.stat().st_size != item.get("size") or hashlib.sha256(wheel.read_bytes()).hexdigest() != item.get("sha256"):
+                raise ResolverError("WHEEL_DIGEST_MISMATCH", "bound wheel bytes changed")
+            import zipfile
+        except ResolverError:
+            raise
+        except (OSError, TypeError, KeyError) as error:
+            raise ResolverError("ARTIFACT_ENTRY_INVALID", "bound artifact entry cannot be validated") from error
+        try:
+            with zipfile.ZipFile(wheel) as archive:
+                archive_names = archive.namelist()
+                if len(archive_names) != len(set(archive_names)) or len({name.casefold() for name in archive_names}) != len(archive_names) or any(not _safe_zip_name(name.rstrip("/")) for name in archive_names):
+                    raise ValueError
+                import stat
+                for info in archive.infolist():
+                    mode = (info.external_attr >> 16) & 0o170000
+                    if stat.S_ISLNK(mode) or stat.S_ISCHR(mode) or stat.S_ISBLK(mode) or stat.S_ISFIFO(mode) or (stat.S_ISDIR(mode) and not info.filename.endswith("/")):
+                        raise ValueError
+                records = [name for name in archive_names if name.endswith(".dist-info/RECORD")]
+                if len(records) != 1:
+                    raise ValueError
+                _validate_record(archive, [name for name in archive_names if not name.endswith("/")], records[0])
+                metadata_names = [name for name in archive_names if name.endswith(".dist-info/METADATA")]
+                wheel_names = [name for name in archive_names if name.endswith(".dist-info/WHEEL")]
+                if len(metadata_names) != 1 or len(wheel_names) != 1:
+                    raise ValueError
+                metadata = archive.read(metadata_names[0]).decode("utf-8")
+                fields = dict(line.split(": ", 1) for line in metadata.splitlines() if ": " in line and line.split(": ", 1)[0] in {"Name", "Version"})
+                tags = {line.split(":", 1)[1].strip() for line in archive.read(wheel_names[0]).decode("utf-8").splitlines() if line.startswith("Tag:")}
+                if fields.get("Name", "").replace("_", "-").lower() != str(item["normalized_distribution"]).lower() or fields.get("Version") != str(item["version"]) or tags != {str(tag) for tag in filename_tags}:
+                    raise ValueError
+        except (OSError, ValueError, zipfile.BadZipFile, UnicodeDecodeError) as error:
+            raise ResolverError("WHEEL_METADATA_INVALID", "bound wheel metadata or RECORD is invalid") from error
+        expected_files.add(wheel.name)
+    actual = {item.name for item in output.iterdir() if item.is_file()}
+    if actual != expected_files or any(item.is_dir() or item.is_symlink() for item in output.iterdir()):
+        raise ResolverError("BUNDLE_CONTENT_INVALID", "bound bundle contains unexpected entries")
+    return {"schema": RESULT_SCHEMA, "wheelhouse_path": str(output), "artifact_set": artifact_set, "selection": selection, "provider_map": provider_map, "evidence": {"verify_only": True, "unselected_build_count": 0, "native_selected": False}}
+
+
+def _link_free(path: Path) -> bool:
+    """Check every existing component, including Windows reparse points."""
+    import stat
+
+    current = path
+    components = []
+    while current != Path(current.anchor):
+        components.append(current)
+        current = current.parent
+    for component in reversed(components):
+        if component.is_symlink():
+            return False
+        if os.name == "nt" and component.exists():
+            try:
+                if os.lstat(component).st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT:
+                    return False
+            except OSError:
+                return False
+    return True
+
+
+def validate_external_wheel(path: Path, requirement: Requirement) -> dict[str, object]:
+    """Validate the bounded external source without importing its code."""
+    import stat
+    import zipfile
+    import re
+    from packaging.tags import sys_tags
+    from packaging.utils import parse_wheel_filename
+    raw = path.read_bytes()
+    if path.is_symlink() or not path.is_file() or path.suffix != ".whl" or path.name.casefold().startswith("cf-"):
+        raise ResolverError("EXTERNAL_SOURCE_FORBIDDEN", "external wheel is unsafe")
+    try:
+        end = raw.rfind(b"PK\x05\x06")
+        if end < 0 or end + 22 > len(raw) or end + 22 + int.from_bytes(raw[end + 20:end + 22], "little") != len(raw):
+            raise ValueError("malformed ZIP end record")
+        with zipfile.ZipFile(path) as archive:
+            names = archive.namelist()
+            if len(names) != len(set(names)) or len({name.casefold() for name in names}) != len(names) or any(not _safe_zip_name(name.rstrip("/")) for name in names):
+                raise ValueError("unsafe archive names")
+            payload_names = [name for name in names if not name.endswith("/")]
+            metadata_names = [name for name in archive.namelist() if name.endswith(".dist-info/METADATA")]
+            wheel_names = [name for name in archive.namelist() if name.endswith(".dist-info/WHEEL")]
+            record_names = [name for name in archive.namelist() if name.endswith(".dist-info/RECORD")]
+            if len(metadata_names) != 1 or len(wheel_names) != 1 or len(record_names) != 1:
+                raise ValueError
+            for info in archive.infolist():
+                mode = (info.external_attr >> 16) & 0o170000
+                if stat.S_ISLNK(mode) or stat.S_ISCHR(mode) or stat.S_ISBLK(mode) or stat.S_ISFIFO(mode) or (stat.S_ISDIR(mode) and not info.filename.endswith("/")):
+                    raise ValueError("unsafe archive entry")
+            _validate_record(archive, payload_names, record_names[0])
+            metadata = archive.read(metadata_names[0]).decode("utf-8")
+            wheel = archive.read(wheel_names[0]).decode("utf-8")
+            fields = dict(re.findall(r"^(Name|Version): (.+)$", metadata, re.MULTILINE))
+            _, filename_version, _, filename_tags = parse_wheel_filename(path.name)
+            wheel_tags = {line.split(":", 1)[1].strip() for line in wheel.splitlines() if line.startswith("Tag:")}
+            compatible = {str(tag) for tag in sys_tags()}
+    except (OSError, ValueError, zipfile.BadZipFile, UnicodeDecodeError) as error:
+        raise ResolverError("ARTIFACT_INVALID", "external wheel metadata is invalid") from error
+    normalized = re.sub(r"[-_.]+", "-", fields.get("Name", "")).lower()
+    try:
+        version = Version(fields.get("Version", ""))
+    except InvalidVersion as error:
+        raise ResolverError("ARTIFACT_INVALID", "external wheel version is invalid") from error
+    if normalized != requirement.name.replace("_", "-").lower() or not fields.get("Version") or version not in requirement.specifier or filename_version != version or {str(tag) for tag in filename_tags} != wheel_tags or not wheel_tags or not (wheel_tags & compatible) or any(name.endswith((".pth", "direct_url.json")) for name in names) or "Editable-Project-Location:" in metadata:
+        raise ResolverError("ARTIFACT_INVALID", "external wheel does not match requirement")
+    return {"distribution": fields["Name"], "normalized_distribution": normalized, "version": fields["Version"], "filename": path.name, "sha256": hashlib.sha256(raw).hexdigest(), "size": path.stat().st_size, "source_kind": "external-wheelhouse"}
+
+
+def handle(payload: object) -> dict[str, object]:
+    identifier = payload.get("id") if isinstance(payload, dict) else None
+    try:
+        if not isinstance(payload, dict):
+            raise ResolverError("INVALID_ENVELOPE", "request envelope must be an object")
+        unknown = set(payload) - _FIELDS
+        missing = _FIELDS - set(payload)
+        if unknown:
+            raise ResolverError("UNKNOWN_ENVELOPE_FIELD", "request envelope fields are invalid")
+        if missing:
+            raise ResolverError("INVALID_ENVELOPE", "request envelope is missing required fields")
+        if payload.get("jsonrpc") != "2.0" or not isinstance(payload.get("id"), (str, int)) or isinstance(payload.get("id"), bool):
+            raise ResolverError("INVALID_ENVELOPE", "request envelope identity is invalid")
+        if payload.get("protocol") != PROTOCOL:
+            raise ResolverError("PROTOCOL_VERSION_UNSUPPORTED", "unsupported resolver protocol version")
+        if payload.get("method") != "artifacts/resolve":
+            raise ResolverError("UNKNOWN_OPERATION", "unknown resolver operation")
+        return _response(identifier, result=resolve(payload.get("params")))
+    except ResolverError as error:
+        return _response(identifier, error={"code": error.code, "message": str(error)})
+    except Exception as error:
+        return _response(identifier, error={"code": "INTERNAL_ERROR", "message": f"resolver failed unexpectedly: {error}"})
+
+
+def main() -> int:
+    for line in sys.stdin:
+        try:
+            payload = json.loads(line)
+            response = handle(payload)
+        except json.JSONDecodeError:
+            response = _response(None, error={"code": "MALFORMED_JSON", "message": "request must be valid JSON"})
+        sys.stdout.write(canonical_json(response).decode())
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cf_bootstrap_source_local/semantics/package.trig

@@ -0,0 +1,13 @@
+@prefix cfpkg: <https://cogniflow.odea-project.org/cf#> .
+@prefix contribution: <urn:cf:contribution:> .
+@prefix pkg: <urn:cf:pkg:> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+pkg:cf_bootstrap_source_local {
+  pkg:cf_bootstrap_source_local a cfpkg:CfPackage ;
+    cfpkg:hasPackageManifest [ a cfpkg:PackageManifest ; cfpkg:hasDistributionName [ a cfpkg:DistributionName ; rdf:value "cf-bootstrap-source-local" ] ; cfpkg:hasPythonPackageName [ a cfpkg:PythonPackageName ; rdf:value "cf_bootstrap_source_local" ] ; cfpkg:hasPackageVersion [ a cfpkg:PackageVersion ; rdf:value "0.1.0" ] ; cfpkg:hasImplementationLanguage [ a cfpkg:ImplementationLanguage ; rdf:value "Python" ] ] ;
+    cfpkg:hasPackageRole [ a cfpkg:PackageRole ; rdf:value cfpkg:SpecificationPackageRole ] ;
+    cfpkg:hasPackageContribution contribution:adopted_package ;
+    skos:prefLabel "cf-bootstrap-source-local" ; skos:definition "An adopted Cogniflow package conforming to the basic package template." ; skos:scopeNote "Package semantics were restored through the package conformance repair service." ; skos:example "The installed package publishes its package.trig semantic source." .
+}

cf_bootstrap_source_local-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: cf-bootstrap-source-local
+Version: 0.1.0
+Summary: Offline deterministic Stonecastle local repository artifact resolver.
+Author: Cogniflow Maintainers
+License: GPL-3
+Requires-Python: >=3.11
+Requires-Dist: cf-bootstrap-source-pypi==0.1.16
+Requires-Dist: packaging<27,>=24
+Requires-Dist: rdflib<8,>=7
+Description-Content-Type: text/markdown
+
+# Local repository artifact resolver
+
+`cf-bootstrap-source-local` converts a Stonecastle source checkout into a verified, offline installation bundle. It is the artifact-source implementation used by Local Repository Mode.
+
+## Installation role
+
+The resolver validates the direct first-party project inventory and semantic-navigation index, loads the selected installation profile, reads its canonical `hasCapabilityRequest` relations from local TriG, and discovers matching service operations from indexed service semantics. This discovery is deliberately local because it runs before Fuseki or the production semantic graph exists.
+
+For the selected providers it computes the first-party dependency closure, validates bounded external wheels, builds non-editable wheels, packages declared native artifacts, and publishes an immutable `artifact-set.json` with source, index, profile, catalog, selection, artifact, and native-authority digests. Bootstrap and post-handoff phases are resolved separately so only required components enter each transaction.
+
+## Protocol and boundaries
+
+The console script implements `cf.bootstrap.artifact-resolver.v1` as one-request/one-response JSON lines. Principal inputs are a canonical bootstrap plan, phase, checkout path, artifact output root, and explicit external wheelhouse. Outputs are a canonical artifact-resolution result, provider map, selection evidence, and wheelhouse.
+
+The resolver never installs into the target, creates the instance environment, starts services, contacts a SPARQL endpoint, or mutates the checkout. Network access is not used for first-party resolution; external dependencies must already be present in the bounded wheelhouse. Target application belongs to `cf-bootstrap-instance`, while orchestration belongs to `cf-bootstrap-orchestrator`.