collective-capability-runtime 1.0.0__py3-none-any.whl

ccr/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Collective Capability Runtime."""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

ccr/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Module entry point for ``python -m ccr``."""
+
+from __future__ import annotations
+
+from ccr.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ccr/adapters/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Verifier provider adapters."""
+
+from __future__ import annotations

ccr/adapters/base.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base verifier provider interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseVerifierProvider(ABC):
+    """Common interface for optional verifier providers."""
+
+    provider_name: str
+
+    @abstractmethod
+    def availability(self) -> dict[str, Any]:
+        """Return provider availability data."""
+
+    @abstractmethod
+    def plan_verify(
+        self, packet: dict[str, Any], *, profile: str, packet_path: str
+    ) -> dict[str, Any]:
+        """Return a dry-run verification plan."""
+
+    @abstractmethod
+    def execute_verify(
+        self,
+        packet: dict[str, Any],
+        *,
+        profile: str,
+        packet_path: str,
+        timeout_seconds: int,
+    ) -> dict[str, Any]:
+        """Execute verification only after explicit operator request."""
+
+    @abstractmethod
+    def normalize_report(self, report: dict[str, Any]) -> dict[str, Any]:
+        """Normalize a provider report into CCR structures."""

ccr/adapters/pic.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Optional PIC verifier provider adapter."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ccr.adapters.base import BaseVerifierProvider
+from ccr.ids import stable_id
+from ccr.io import json_file_name
+from ccr.packets.distill import packet_summary_text
+from ccr.time import now_iso
+
+PIC_PROFILES = {"development", "research", "controlled", "federated", "production", "adversarial"}
+
+
+class PicVerifierProvider(BaseVerifierProvider):
+    """PIC adapter with dry-run planning by default."""
+
+    provider_name = "pic"
+
+    def availability(self) -> dict[str, Any]:
+        """Return PIC availability without importing it as a hard dependency."""
+
+        executable = shutil.which("pic")
+        module_available = importlib.util.find_spec("percolation_inversion_compiler") is not None
+        return {
+            "available": bool(executable or module_available),
+            "executable": executable,
+            "module_available": module_available,
+            "provider": self.provider_name,
+        }
+
+    def plan_verify(
+        self, packet: dict[str, Any], *, profile: str, packet_path: str
+    ) -> dict[str, Any]:
+        """Build a PIC dry-run plan. The command is never executed here."""
+
+        if profile not in PIC_PROFILES:
+            raise ValueError(f"unknown PIC profile: {profile}")
+        text = packet_summary_text(packet)
+        argv = ["pic", "agent", "check", "--compact", "--text", text, "--profile", profile]
+        return {
+            "dry_run": True,
+            "expected_import_location": "reports/pic/",
+            "packet_id": packet.get("packet_id"),
+            "packet_path": packet_path,
+            "provider": self.provider_name,
+            "recommended_alternate_argv": ["pic", "packet", "inspect", "--packet", packet_path],
+            "verification_argv": argv,
+        }
+
+    def execute_verify(
+        self,
+        packet: dict[str, Any],
+        *,
+        profile: str,
+        packet_path: str,
+        timeout_seconds: int,
+    ) -> dict[str, Any]:
+        """Execute PIC through subprocess with no shell expansion."""
+
+        availability = self.availability()
+        executable = availability.get("executable")
+        if not executable:
+            return {
+                "availability": availability,
+                "error": (
+                    "PIC executable 'pic' is unavailable; install PIC or run dry-run planning."
+                ),
+                "ok": False,
+                "provider": self.provider_name,
+            }
+        plan = self.plan_verify(packet, profile=profile, packet_path=packet_path)
+        argv = [str(executable), *plan["verification_argv"][1:]]
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            check=False,
+            shell=False,
+            text=True,
+            timeout=timeout_seconds,
+        )
+        stdout_json: dict[str, Any] | None = None
+        try:
+            parsed = json.loads(completed.stdout)
+            if isinstance(parsed, dict):
+                stdout_json = parsed
+        except json.JSONDecodeError:
+            stdout_json = None
+        return {
+            "argv": argv,
+            "created_at": now_iso(),
+            "ok": completed.returncode == 0,
+            "packet_id": packet.get("packet_id"),
+            "packet_path": packet_path,
+            "profile": profile,
+            "provider": self.provider_name,
+            "returncode": completed.returncode,
+            "stderr": completed.stderr,
+            "stdout": completed.stdout,
+            "stdout_json": stdout_json,
+        }
+
+    def normalize_report(self, report: dict[str, Any]) -> dict[str, Any]:
+        """Normalize PIC-like report fields into CCR status and residual inputs."""
+
+        source = (
+            report.get("stdout_json") if isinstance(report.get("stdout_json"), dict) else report
+        )
+        if not isinstance(source, dict):
+            source = report
+        workflow_usable = bool(source.get("workflow_usable", False))
+        accepted = bool(source.get("accepted", workflow_usable))
+        settled = bool(source.get("settled", False))
+        candidate_only_reasons = _combine_lists(
+            source,
+            "candidate_only_reasons",
+            "candidate_only",
+        )
+        settled_blockers = _combine_lists(source, "settled_blockers", "blockers")
+        missing_obligations = _combine_lists(source, "missing_obligations")
+        cannot_promote_because = _combine_lists(source, "cannot_promote_because")
+        residuals = _combine_lists(source, "residuals", "residual_ledger")
+        safe_commands = _combine_lists(source, "safe_commands", "next_safe_actions")
+        reasons = _as_list(source.get("reasons", []))
+        blocking_residuals = [
+            item
+            for item in residuals
+            if isinstance(item, dict) and bool(item.get("blocking", False))
+        ]
+        status_blockers = (
+            candidate_only_reasons
+            + settled_blockers
+            + missing_obligations
+            + cannot_promote_because
+            + blocking_residuals
+        )
+        unsafe = any(
+            token in " ".join(str(item).lower() for item in reasons + settled_blockers)
+            for token in ("unsafe", "hazard", "authority", "malformed")
+        )
+        if not accepted:
+            ccr_status = "quarantined" if unsafe else "rejected"
+        elif settled and not status_blockers:
+            ccr_status = "checked"
+        elif status_blockers:
+            ccr_status = "provisional"
+        else:
+            ccr_status = "checked"
+
+        packet_id = source.get("packet_id", report.get("packet_id"))
+        profile = source.get("profile", report.get("profile", "development"))
+        import_id = stable_id("pic-import", report)
+        return {
+            "accepted": accepted,
+            "bottlenecks": _as_list(source.get("bottlenecks", [])),
+            "candidate_only_reasons": candidate_only_reasons,
+            "ccr_status": ccr_status,
+            "cannot_promote_because": cannot_promote_because,
+            "import_id": import_id,
+            "missing_obligations": missing_obligations,
+            "notes": (
+                "PIC accepted output imported as checked/provisional, not settled. "
+                "Final CCR settlement requires CCR gates."
+            ),
+            "packet_id": packet_id,
+            "phase_gap_vector": source.get("phase_gap_vector"),
+            "pic_profile": profile,
+            "pic_report_type": str(source.get("report_type", source.get("type", "PICReport"))),
+            "residuals": residuals,
+            "safe_commands": safe_commands,
+            "schema_version": "ccr.pic_import.v0.1",
+            "sdk_calls": _as_list(source.get("sdk_calls", [])),
+            "settled": settled,
+            "settled_blockers": settled_blockers,
+            "settled_candidate": bool(accepted and settled),
+            "workflow_usable": workflow_usable,
+        }
+
+
+def _as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _combine_lists(source: dict[str, Any], *keys: str) -> list[Any]:
+    values: list[Any] = []
+    for key in keys:
+        values.extend(_as_list(source.get(key)))
+    return values
+
+
+def report_output_path(root: Path, report_id: str) -> Path:
+    """Return PIC report output path."""
+
+    return root / "reports" / "pic" / json_file_name(report_id)

ccr/audit/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CCR repository audit."""
+
+from __future__ import annotations
+
+from ccr.audit.pic import audit_pic_compatibility
+from ccr.audit.release import audit_release
+from ccr.audit.repo import audit_repository
+
+__all__ = ["audit_pic_compatibility", "audit_release", "audit_repository"]

ccr/audit/pic.py

@@ -0,0 +1,384 @@
+# SPDX-License-Identifier: Apache-2.0
+"""PIC compatibility audit for the optional provider boundary."""
+
+from __future__ import annotations
+
+import importlib.metadata as importlib_metadata
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ccr.errors import CCRMissingError
+from ccr.ids import stable_id
+from ccr.providers.pic import PicProvider
+from ccr.residuals.model import build_residual
+from ccr.time import now_iso
+
+EXPECTED_PIC_COMMANDS = [
+    "pic agent check --compact",
+    "pic packet inspect",
+    "pic phase plan --compact",
+    "pic runtime collective-certify",
+]
+
+SUPPORTED_PIC_IMPORT_FIELDS = [
+    "accepted",
+    "workflow_usable",
+    "settled",
+    "candidate_only_reasons",
+    "settled_blockers",
+    "safe_commands",
+    "phase_gap_vector",
+    "bottlenecks",
+    "missing_obligations",
+    "residuals",
+    "cannot_promote_because",
+]
+
+PIC_ROUTE_TEXT = "python -m pip install percolation-inversion-compiler"
+
+
+def default_pic_root_candidates(ccr_root: Path) -> list[Path]:
+    """Return deterministic PIC source-root candidates for local compatibility checks."""
+
+    candidates = [
+        Path.home() / "percolation-inversion-compiler",
+        ccr_root.parent / "percolation-inversion-compiler",
+    ]
+    seen: set[str] = set()
+    unique: list[Path] = []
+    for candidate in candidates:
+        key = str(candidate.resolve()) if candidate.exists() else str(candidate)
+        if key not in seen:
+            unique.append(candidate)
+            seen.add(key)
+    return unique
+
+
+def resolve_pic_root(ccr_root: Path, explicit_pic_root: Path | None = None) -> Path:
+    """Resolve a PIC root or raise a CLI-ready missing-path error."""
+
+    if explicit_pic_root is not None:
+        pic_root = explicit_pic_root.expanduser()
+        if not pic_root.exists():
+            raise CCRMissingError(
+                f"PIC root does not exist: {pic_root}",
+                {
+                    "error": "pic root missing",
+                    "ok": False,
+                    "pic_root": str(pic_root),
+                    "schema_version": "ccr.pic_compat_audit.v1",
+                },
+            )
+        return pic_root
+    searched = default_pic_root_candidates(ccr_root)
+    for candidate in searched:
+        if candidate.exists():
+            return candidate
+    raise CCRMissingError(
+        "PIC root was not found in default search candidates.",
+        {
+            "error": "pic root missing",
+            "ok": False,
+            "searched": [str(path) for path in searched],
+            "schema_version": "ccr.pic_compat_audit.v1",
+        },
+    )
+
+
+def audit_pic_compatibility(ccr_root: Path, *, pic_root: Path | None = None) -> dict[str, Any]:
+    """Audit the CCR/PIC operational compatibility boundary."""
+
+    resolved_pic_root = resolve_pic_root(ccr_root, pic_root)
+    findings: list[dict[str, Any]] = []
+    pic_repo_version = _read_pyproject_version(resolved_pic_root / "pyproject.toml")
+    package_version = _installed_distribution_version("percolation-inversion-compiler")
+    pic_executable = shutil.which("pic")
+
+    if package_version is None:
+        findings.append(
+            _finding(
+                "provider_missing",
+                "python-package:percolation-inversion-compiler",
+                "medium",
+                False,
+                "PIC package is not installed in the active Python environment.",
+                repair_hint=PIC_ROUTE_TEXT,
+            )
+        )
+    if pic_executable is None:
+        findings.append(
+            _finding(
+                "provider_missing",
+                "cli:pic",
+                "medium",
+                False,
+                "PIC CLI executable is not available on PATH.",
+                repair_hint=PIC_ROUTE_TEXT,
+            )
+        )
+
+    _check_pic_source_tree(resolved_pic_root, findings)
+    _check_pic_repo_version(pic_repo_version, findings)
+    _check_provider_mapping(findings)
+    _check_non_claim_boundary(ccr_root, resolved_pic_root, findings)
+
+    blocking = [finding for finding in findings if finding["blocking"]]
+    return {
+        "accepted": not blocking,
+        "blocking_finding_count": len(blocking),
+        "created_at": now_iso(),
+        "expected_pic_commands": EXPECTED_PIC_COMMANDS,
+        "finding_count": len(findings),
+        "findings": findings,
+        "installed_package_version": package_version,
+        "ok": not blocking,
+        "pic_cli": {"available": pic_executable is not None, "path": pic_executable},
+        "pic_repo_version": pic_repo_version,
+        "pic_root": str(resolved_pic_root),
+        "report_id": stable_id(
+            "pic-compat-audit",
+            str(resolved_pic_root),
+            pic_repo_version,
+            package_version,
+            [finding["finding_id"] for finding in findings],
+        ),
+        "schema_version": "ccr.audit_report.v1",
+        "settled": False,
+        "supported_import_fields": SUPPORTED_PIC_IMPORT_FIELDS,
+    }
+
+
+def _check_pic_source_tree(pic_root: Path, findings: list[dict[str, Any]]) -> None:
+    required_files = {
+        "README.md": [
+            "percolation-inversion-compiler",
+            "pic agent check --compact",
+            "pic phase plan --compact",
+            "safe_commands",
+            "settled=false",
+        ],
+        "pyproject.toml": [
+            'name = "percolation-inversion-compiler"',
+            'pic = "percolation_inversion_compiler.cli:app"',
+        ],
+        "docs/porting.md": ["workflow_usable", "settled", "candidate-only"],
+        "docs/phase-acceleration.md": [
+            "phase_gap_vector",
+            "bottlenecks",
+            "cannot_promote_because",
+            "settled_blockers",
+        ],
+        "docs/v050-audit.md": ["Package version: `0.5.0`", "safe_commands"],
+        "examples/portability_conformance/phase_acceleration_plan.json": [
+            "PhaseAccelerationPlan",
+            "candidate_only_reasons",
+            "cannot_promote_because",
+            "settled_blockers",
+        ],
+    }
+    for relative, needles in required_files.items():
+        path = pic_root / relative
+        if not path.exists():
+            findings.append(
+                _finding(
+                    "missing-pic-source-file",
+                    relative,
+                    "high",
+                    True,
+                    f"PIC source tree does not contain {relative}.",
+                    repair_hint="Point --pic-root at a PIC v0.5.0-compatible source tree.",
+                )
+            )
+            continue
+        text = path.read_text(encoding="utf-8")
+        for needle in needles:
+            if needle not in text:
+                findings.append(
+                    _finding(
+                        "missing-pic-compat-marker",
+                        relative,
+                        "medium",
+                        True,
+                        f"PIC compatibility marker is missing: {needle}",
+                        repair_hint="Update the PIC root or compatibility matrix.",
+                    )
+                )
+
+
+def _check_pic_repo_version(version: str | None, findings: list[dict[str, Any]]) -> None:
+    if version is None:
+        findings.append(
+            _finding(
+                "missing-pic-version",
+                "pyproject.toml",
+                "high",
+                True,
+                "PIC pyproject.toml does not expose a package version.",
+                repair_hint="Use a PIC source root with explicit version metadata.",
+            )
+        )
+        return
+    if not version.startswith("0.5."):
+        findings.append(
+            _finding(
+                "unsupported-pic-version",
+                "pyproject.toml",
+                "medium",
+                False,
+                f"PIC source version is {version}; CCR v1 matrix targets PIC v0.5.x.",
+                repair_hint="Review INTEROP_PIC.md before relying on this PIC version.",
+            )
+        )
+
+
+def _check_provider_mapping(findings: list[dict[str, Any]]) -> None:
+    capabilities = PicProvider().capabilities()
+    commands = capabilities.get("expected_pic_commands", [])
+    fields = capabilities.get("supported_import_fields", [])
+    for command in EXPECTED_PIC_COMMANDS:
+        if command not in commands:
+            findings.append(
+                _finding(
+                    "provider-command-mapping-gap",
+                    "src/ccr/providers/pic.py",
+                    "high",
+                    True,
+                    f"PicProvider.capabilities() does not expose command: {command}",
+                    repair_hint="Expose the PIC command in PicProvider.capabilities().",
+                )
+            )
+    for field in SUPPORTED_PIC_IMPORT_FIELDS:
+        if field not in fields:
+            findings.append(
+                _finding(
+                    "provider-field-mapping-gap",
+                    "src/ccr/providers/pic.py",
+                    "high",
+                    True,
+                    f"PicProvider.capabilities() does not expose import field: {field}",
+                    repair_hint="Expose the field in PicProvider.capabilities().",
+                )
+            )
+
+
+def _check_non_claim_boundary(
+    ccr_root: Path, pic_root: Path, findings: list[dict[str, Any]]
+) -> None:
+    ccr_text = _read_texts(
+        ccr_root,
+        [
+            "INTEROP_PIC.md",
+            "SECURITY.md",
+            "README.md",
+            "SPEC.md",
+        ],
+    )
+    pic_text = _read_texts(
+        pic_root,
+        [
+            "README.md",
+            "docs/porting.md",
+            "docs/phase-acceleration.md",
+            "docs/v050-audit.md",
+        ],
+    )
+    required_ccr = [
+        "PIC output never settles CCR by itself",
+        "safe commands",
+        "not real ASI",
+        "ccr audit pic",
+    ]
+    required_pic = [
+        "accepted=true",
+        "settled=false",
+        "safe_commands",
+        "workflow_usable",
+    ]
+    for needle in required_ccr:
+        if needle not in ccr_text:
+            findings.append(
+                _finding(
+                    "missing-ccr-pic-boundary",
+                    "CCR docs",
+                    "high",
+                    True,
+                    f"CCR documentation does not preserve PIC boundary text: {needle}",
+                    repair_hint="Update README, SPEC, SECURITY, or INTEROP_PIC.md.",
+                )
+            )
+    for needle in required_pic:
+        if needle not in pic_text:
+            findings.append(
+                _finding(
+                    "missing-pic-boundary",
+                    "PIC docs",
+                    "medium",
+                    True,
+                    f"PIC documentation does not expose compatibility boundary text: {needle}",
+                    repair_hint="Review the supplied --pic-root for v0.5.0 compatibility.",
+                )
+            )
+
+
+def _read_texts(root: Path, relatives: list[str]) -> str:
+    chunks: list[str] = []
+    for relative in relatives:
+        path = root / relative
+        if path.exists():
+            chunks.append(path.read_text(encoding="utf-8"))
+    return "\n".join(chunks)
+
+
+def _installed_distribution_version(name: str) -> str | None:
+    try:
+        return importlib_metadata.version(name)
+    except importlib_metadata.PackageNotFoundError:
+        return None
+
+
+def _read_pyproject_version(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    match = re.search(r'^version\s*=\s*"([^"]+)"', path.read_text(encoding="utf-8"), re.M)
+    return match.group(1) if match else None
+
+
+def _finding(
+    kind: str,
+    location: str,
+    severity: str,
+    blocking: bool,
+    description: str,
+    *,
+    repair_hint: str,
+) -> dict[str, Any]:
+    finding_id = stable_id("finding", kind, location, description)
+    if kind == "provider_missing":
+        residual_kind = "provider_missing"
+    elif kind.startswith("missing"):
+        residual_kind = "missing_evidence"
+    else:
+        residual_kind = "other"
+    residual = build_residual(
+        kind=residual_kind,
+        description=description,
+        blocking=blocking,
+        object_type="runtime",
+        object_id=location,
+        severity=severity,
+        refs=[location],
+        source="ccr.audit.pic",
+        repair_hint=repair_hint,
+        extensions={"finding_id": finding_id, "finding_kind": kind},
+    )
+    return {
+        "blocking": blocking,
+        "description": description,
+        "finding_id": finding_id,
+        "kind": kind,
+        "location": location,
+        "residual_ready": residual,
+        "severity": severity,
+    }