PTSIP 0.3.8b3__py3-none-win_amd64.whl

ptsip/dependency_review.py

@@ -0,0 +1,174 @@
+"""Bounded, read-only evidence packages for unresolved support-contract review."""
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from pathlib import Path
+import tokenize
+
+from .repository.snapshot import capture_snapshot, git_tracked_files
+from .storage.local_state import ptsip_home, repository_fingerprint
+
+
+def _serialized(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2)
+
+
+def _size(value: object) -> int:
+    return len(_serialized(value).encode("utf-8"))
+
+
+def _snippet(root: Path, path: str, line: int, kind: str) -> dict[str, object] | None:
+    candidate = root / path
+    if not candidate.resolve().is_relative_to(root) or candidate.is_symlink():
+        return None
+    try:
+        with tokenize.open(candidate) as source:
+            lines = source.read().splitlines()
+    except (OSError, UnicodeError, SyntaxError):
+        return None
+    if not 1 <= line <= len(lines):
+        return None
+    start = max(1, line - 3)
+    end = min(len(lines), start + 6)
+    selected = "\n".join(lines[start - 1:end])
+    return {
+        "path": path, "line": line, "start_line": start, "end_line": end,
+        "kind": kind, "text": selected[:1200], "truncated": len(selected) > 1200,
+    }
+
+
+def _callers(report: dict, item: dict, max_files: int) -> list[dict]:
+    source = item["dependency"]["source"]
+    candidates = item.get("callers")
+    if candidates is None:
+        candidates = [
+            {"path": edge["dependency"]["source"], "line": edge["dependency"].get("line"),
+             "evidence_id": edge["evidence_id"], "semantics": "OBSERVED_FILE_DEPENDENCY"}
+            for edge in report["items"] if edge["dependency"].get("resolved_path") == source
+        ]
+    selected, files = [], {source}
+    for caller in sorted(candidates, key=lambda value: (
+        value.get("path", ""), value.get("line") or 0, value.get("evidence_id", "")
+    )):
+        path = caller.get("path")
+        if not path or (path not in files and len(files) >= max_files):
+            continue
+        files.add(path)
+        selected.append({**{key: caller.get(key) for key in ("path", "line", "evidence_id")},
+                         "semantics": caller.get("semantics") or caller.get("kind")})
+        if len(selected) >= 4:
+            break
+    return selected
+
+
+def build_review_pack(
+    report: dict, *, max_items: int = 8, max_context_bytes_per_item: int = 12000,
+    max_source_files_per_item: int = 4,
+) -> dict:
+    """Select only REVIEW_REQUIRED items; never invoke an AI or assert authority."""
+    if max_items < 0 or max_context_bytes_per_item < 1 or max_source_files_per_item < 1:
+        raise ValueError("Review budgets require nonnegative max-items and positive byte/file caps")
+    if report.get("status") != "RAN":
+        raise ValueError("Review Pack requires stable analysis with a valid selected profile")
+    root = Path(report["repository"]["root"]).resolve()
+    eligible = sorted((item for item in report["items"] if item["actionability"] == "REVIEW_REQUIRED"),
+                      key=lambda item: item["evidence_id"])
+    reviews, deferred = [], []
+    for item in eligible:
+        if len(reviews) >= max_items:
+            deferred.append({"evidence_id": item["evidence_id"], "reason": "ITEM_BUDGET"})
+            continue
+        usage = deepcopy(item.get("usage", {}))
+        fallback = usage.pop("fallback", {"detected": False, "semantics": "NO_SYNTAX_EVIDENCE"})
+        callers = _callers(report, item, max_source_files_per_item)
+        review = {
+            "review_id": "review:" + item["evidence_id"], "evidence_id": item["evidence_id"],
+            "actionability": "REVIEW_REQUIRED", "reason": item["reason"],
+            "dependency": deepcopy(item["dependency"]), "component": deepcopy(item["component"]),
+            "target_component": item.get("target_component"),
+            "declaration": deepcopy(item.get("declaration", {})), "usage": usage,
+            "fallback": fallback, "callers": callers, "snippets": [],
+            "question": "What support contract governs this dependency, and is its fallback sufficient for that contract?",
+            "authority": "REVIEW_PROPOSAL_ONLY",
+        }
+        if _size(review) > max_context_bytes_per_item:
+            deferred.append({"evidence_id": item["evidence_id"], "reason": "BASE_EVIDENCE_EXCEEDS_BYTE_BUDGET"})
+            continue
+        source = item["dependency"]["source"]
+        references = [(source, item["dependency"].get("line"), "IMPORT")]
+        references += [(source, line, "GUARD") for line in usage.get("guard_lines", [])[:4]]
+        references += [(value.get("path", source), value.get("line"), "FALLBACK")
+                       for value in fallback.get("evidence", [])[:4]]
+        references += [(source, line, "USAGE") for line in usage.get("usage_lines", [])[:8]]
+        references += [(value["path"], value["line"], "INCOMING_FILE_DEPENDENCY") for value in callers]
+        files, seen = set(), set()
+        for path, line, kind in references:
+            if not isinstance(path, str) or not isinstance(line, int) or (path, line) in seen:
+                continue
+            if path not in files and len(files) >= max_source_files_per_item:
+                continue
+            seen.add((path, line))
+            snippet = _snippet(root, path, line, kind)
+            if snippet is None:
+                continue
+            review["snippets"].append(snippet)
+            if _size(review) > max_context_bytes_per_item:
+                review["snippets"].pop()
+            else:
+                files.add(path)
+        if not any(snippet["kind"] == "IMPORT" for snippet in review["snippets"]):
+            deferred.append({"evidence_id": item["evidence_id"],
+                             "reason": "IMPORT_CONTEXT_UNAVAILABLE_WITHIN_BUDGET"})
+            continue
+        reviews.append(review)
+    return {
+        "format": "ptsip-dependency-review-pack/v1", "repository": deepcopy(report["repository"]),
+        "component": report.get("component"), "snapshot": deepcopy(report.get("snapshot", {})),
+        "summary": {"review_required_total": len(eligible), "selected_for_review": len(reviews),
+                    "deferred": len(deferred), "ai_reviewed_items": 0},
+        "budget": {"only": ["REVIEW_REQUIRED"], "max_items": max_items,
+                   "max_context_bytes_per_item": max_context_bytes_per_item,
+                   "max_source_files_per_item": max_source_files_per_item,
+                   "byte_measure": "UTF-8 serialized standalone review object, ensure_ascii=false, indent=2, sort_keys=true"},
+        "reviews": reviews, "deferred": deferred,
+        "authority": "ADVISORY_ONLY", "conformance_evaluated": False,
+    }
+
+
+def write_review_pack(report: dict, output: str | Path | None = None, **budgets) -> tuple[dict, Path]:
+    root = Path(report["repository"]["root"]).resolve()
+    pack = build_review_pack(report, **budgets)
+    observed = capture_snapshot(root).as_dict()
+    expected = report.get("snapshot", {}).get("after", {})
+    identity = ("is_git", "head", "status_fingerprint", "tracked_content_fingerprint", "tracked_files")
+    if not expected or observed["observation_errors"] or any(observed[key] != expected.get(key) for key in identity):
+        raise RuntimeError("Repository changed after dependency analysis; regenerate the Review Pack")
+    data = json.dumps(pack, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n"
+    if output is None:
+        destination = (ptsip_home() / "dependency-reviews" / repository_fingerprint(root)
+                       / (hashlib.sha256(data.encode("utf-8")).hexdigest()[:20] + ".json")).resolve()
+        if destination.is_relative_to(root):
+            raise ValueError("Default Review Pack state must stay outside the Consumer Repository")
+    else:
+        destination = Path(output).expanduser().resolve()
+    if destination.suffix.lower() != ".json":
+        raise ValueError("Review Pack output must be a JSON report path")
+    if destination.is_relative_to(root):
+        tracked, errors = git_tracked_files(root)
+        if observed["is_git"] and errors:
+            raise RuntimeError("Cannot verify Review Pack output against tracked files")
+        protected = {str((root / rel).resolve()).casefold() for rel in tracked}
+        if str(destination).casefold() in protected:
+            raise ValueError("Review Pack output must not overwrite a tracked repository path")
+        if any(part in {".git", "src"} for part in destination.relative_to(root).parts):
+            raise ValueError("Review Pack output must not be written into source or Git state")
+    if destination.exists():
+        if destination.read_bytes() != data.encode("utf-8"):
+            raise FileExistsError("Review Pack output already exists; choose a new report path")
+        return pack, destination
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with destination.open("x", encoding="utf-8", newline="\n") as stream:
+        stream.write(data)
+    return pack, destination

ptsip/dependency_validation.py

@@ -0,0 +1,106 @@
+"""Advisory validation selection from declared ownership and observed imports."""
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import tomllib
+
+from .validation.components import partition_components, selector_matches_path
+from .validation.profile import validate_profile
+from .repository.snapshot import capture_snapshot, compare_snapshots
+
+
+def validation_plan(root, report, *, changed_paths=()):
+    before = capture_snapshot(root)
+    expected = report.get("snapshot", {}).get("after", {})
+    if any(before.as_dict()[key] != expected.get(key) for key in (
+            "head", "status_fingerprint", "tracked_content_fingerprint")):
+        return {"status": "BLOCKED", "reason": "STALE_ANALYSIS", "steps": []}
+    result = _validation_plan(root, report, changed_paths=changed_paths)
+    if not compare_snapshots(before, capture_snapshot(root)).stable:
+        return {"status": "BLOCKED", "reason": "SNAPSHOT_CHANGED", "steps": []}
+    return result
+
+
+def _validation_plan(root, report, *, changed_paths=()):
+    root = Path(root).resolve()
+    validation = validate_profile(root, report.get("profile_path"))
+    if not validation.valid or not validation.resolved_profile or report["status"] != "RAN":
+        return {"status": "BLOCKED", "reason": "VALID_PROFILE_AND_SNAPSHOT_REQUIRED", "steps": []}
+    payload = validation.resolved_profile.effective_payload
+    components = {item["id"]: item for item in payload["components"]}
+    partition = partition_components(root, list(components.values()))
+    owners = {item.path: item.component_id for item in partition.assignments}
+    changed = sorted(set(str(path).replace("\\", "/").removeprefix("./") for path in changed_paths))
+    if any(path not in owners for path in changed):
+        return {"status": "BLOCKED", "reason": "CHANGED_PATH_OWNERSHIP_REQUIRED", "steps": []}
+    affected = {owners[path] for path in changed}
+    if not changed:
+        affected = {item["component"]["id"] for item in report["items"]
+                    if item["actionability"] != "AUTO_RESOLVED"}
+    links = {(item["from"], item["to"]) for item in payload.get("relationships", [])
+             if item.get("type") == "VERIFIES"}
+    selected = {key for key, meta in components.items() if "VERIFICATION" in meta.get("roles", [])
+                and (key in affected or any((key, target) in links for target in affected)
+                     or any(selector_matches_path(path, pattern) for path in changed
+                            for pattern in meta.get("analysis_inputs", [])))}
+    tests = sorted(path for path, owner in owners.items() if owner in selected
+                   and Path(path).name.startswith("test_") and path.endswith(".py"))
+    runner_evidence = []
+    for item in report["items"]:
+        edge = item["dependency"]
+        if edge["source"] in tests and edge["target"] == "pytest":
+            runner_evidence.append(item["evidence_id"])
+    try:
+        project = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8-sig")).get("project", {})
+        if not isinstance(project, dict):
+            raise ValueError("Project metadata must be a table")
+        requirements = project.get("dependencies", [])
+        optional = project.get("optional-dependencies", {})
+        if not isinstance(requirements, list) or not isinstance(optional, dict):
+            raise ValueError("Dependency metadata has an invalid shape")
+        requirements = requirements + [value for group in optional.values() if isinstance(group, list) for value in group]
+        if any(isinstance(value, str) and re.match(r"^pytest(?:\s|[<>=!~\[;@]|$)", value.strip())
+               for value in requirements):
+            runner_evidence.append("manifest:pyproject.toml:pytest")
+    except (OSError, ValueError, TypeError):
+        pass
+    if not tests or not runner_evidence:
+        return {"status": "REVIEW_REQUIRED", "reason": "VERIFICATION_EXECUTION_EVIDENCE_REQUIRED",
+                "verification_components": sorted(selected), "steps": [], "authority": "ADVISORY_ONLY"}
+    graph = {}
+    for item in report["items"]:
+        edge = item["dependency"]
+        if edge.get("resolved_path"):
+            graph.setdefault(edge["source"], set()).add(edge["resolved_path"])
+    def reaches_change(path):
+        visited, pending = set(), [path]
+        while pending:
+            current = pending.pop()
+            if current in changed:
+                return True
+            if current not in visited:
+                visited.add(current)
+                pending.extend(graph.get(current, ()))
+        return False
+    focused = [path for path in tests if reaches_change(path)]
+    steps = []
+    if focused:
+        steps.append({"scope": "focused", "command": ["python", "-m", "pytest", *focused, "-q"],
+                      "run_when": "focused_change", "basis": "OBSERVED_IMPORT_REACHABILITY_OR_CHANGED_TEST"})
+    # Only collapse to a directory if every tracked test in it belongs to the
+    # selected verification components; never broaden to unrelated tests.
+    parents = sorted({str(Path(path).parent).replace("\\", "/") for path in tests})
+    targets = []
+    for parent in parents:
+        peers = [path for path in owners if path.startswith(parent + "/")
+                 and Path(path).name.startswith("test_") and path.endswith(".py")]
+        targets.extend([parent] if all(path in tests for path in peers)
+                       else [path for path in tests if str(Path(path).parent).replace("\\", "/") == parent])
+    steps.append({"scope": "component", "command": ["python", "-m", "pytest", *targets, "-q", "--maxfail=10"],
+                  "run_when": "batch_complete", "basis": "DECLARED_VERIFICATION_OWNERSHIP"})
+    return {"format": "ptsip-dependency-validation-plan/v1", "status": "PROPOSED",
+            "changed_paths": changed, "verification_components": sorted(selected),
+            "runner_evidence": sorted(runner_evidence), "steps": steps,
+            "authority": "ADVISORY_ONLY", "executed": False,
+            "checkpoint": "Run the repository-declared full regression and strict conform at a WU checkpoint"}

ptsip/doctor.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from .storage.local_state import ptsip_home
+
+
+def doctor(path: str | Path = ".") -> dict[str, object]:
+    target = Path(path).expanduser().resolve()
+    current_minor = (sys.version_info.major, sys.version_info.minor)
+    metadata_supported = current_minor >= (3, 11)
+    ci_verified = (3, 11) <= current_minor <= (3, 14)
+    github_cli = shutil.which("gh")
+    return {
+        "python": sys.version.split()[0],
+        "python_ok": metadata_supported,
+        "python_supported_by_metadata": metadata_supported,
+        "python_ci_verified": ci_verified,
+        "python_ci_verified_range": "3.11-3.14",
+        "python_support_note": (
+            "This interpreter is within the current CI-verified range."
+            if ci_verified
+            else "Package metadata allows this interpreter, but this minor version is outside the current CI matrix."
+        ),
+        "git": shutil.which("git"),
+        "github_cli": github_cli,
+        "github_issue_publish_available": github_cli is not None,
+        "target": str(target),
+        "target_exists": target.exists(),
+        "ptsip_home": str(ptsip_home()),
+    }

ptsip/engine_installation.py

@@ -0,0 +1,191 @@
+"""Read-only consumer diagnostics for the seven independently packaged engines.
+
+Installation is delegated to the authorized package-manager transaction.
+Presence or self-reported wheel provenance never grants runtime authority.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import re
+import sys
+import sysconfig
+from importlib import metadata, resources
+from pathlib import Path
+from typing import Any
+
+HOST_TARGETS = {
+    ("win32", "amd64"): "x86_64-pc-windows-msvc",
+    ("win32", "x86_64"): "x86_64-pc-windows-msvc",
+    ("linux", "x86_64"): "x86_64-unknown-linux-gnu",
+    ("darwin", "arm64"): "aarch64-apple-darwin",
+    ("darwin", "aarch64"): "aarch64-apple-darwin",
+}
+
+
+def _load(relative: str) -> dict[str, Any]:
+    resource = resources.files("ptsip").joinpath("engines", *relative.split("/"))
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _bundle(items: list[dict[str, Any]]) -> tuple[Any, dict[str, Any]] | None:
+    """A broken installed bundle must not fall back to another distribution."""
+    try:
+        distribution = metadata.distribution("PTSIP")
+    except metadata.PackageNotFoundError:
+        return None
+    text = distribution.read_text("ptsip-engines.json")
+    if text is None:
+        return None
+    try:
+        bundle = json.loads(text)
+        origins = bundle["engines"]
+        if (
+            bundle["schema_version"] != "ptsip-bundled-engine-origins/v1"
+            or bundle["package_version"] != distribution.version
+            or bundle["execution_authorized"] is not False
+            or set(origins) != {entry["kind"].lower() for entry in items}
+            or len(origins) != len(items)
+        ):
+            raise ValueError("incomplete or incompatible PTSIP engine bundle")
+        for entry in items:
+            origin = origins[entry["kind"].lower()]
+            if (
+                origin["schema_version"] != "ptsip-independent-wheel-origin/v1"
+                or origin["engine_id"] != entry["engine_id"]
+                or origin["engine_version"] != entry["version"]
+                or origin["execution_authorized"] is not False
+                or re.fullmatch(r"[0-9a-f]{40}", origin["source_sha"]) is None
+            ):
+                raise ValueError("PTSIP bundled engine identity differs")
+        return distribution, bundle
+    except (KeyError, TypeError, json.JSONDecodeError) as exc:
+        raise ValueError("PTSIP bundled engine metadata is invalid") from exc
+
+
+def inspect(
+    *,
+    index: dict[str, Any] | None = None,
+    plan: dict[str, Any] | None = None,
+    bindings: dict[str, dict[str, Any]] | None = None,
+    scripts: Path | None = None,
+    host_target: str | None = None,
+) -> dict[str, Any]:
+    index = index if index is not None else _load("index.json")
+    plan = plan if plan is not None else _load("contracts/installation-plan.json")
+    items = index["official_engine_entries"]
+    packages = {p["engine_id"]: p for p in plan["packages"]}
+    if (
+        len(items) != 7 or len(packages) != 7
+        or len({i["engine_id"] for i in items}) != 7
+        or set(packages) != {i["engine_id"] for i in items}
+        or set(plan["default_available_engine_ids"]) != set(packages)
+    ):
+        raise ValueError("official engine index or installation registry incomplete/ambiguous")
+    host_target = host_target or HOST_TARGETS.get(
+        (sys.platform, platform.machine().lower())
+    )
+    scripts = scripts or Path(sysconfig.get_path("scripts"))
+    bundled = _bundle(items)
+    entries: list[dict[str, Any]] = []
+    for entry in items:
+        kind, engine_id, version = entry["kind"], entry["engine_id"], entry["version"]
+        pkg = packages[engine_id]
+        package_name = "ptsip-engine-" + kind.lower()
+        if (
+            pkg["distribution"] != "INDEPENDENT_VERSIONED_NATIVE_WHEEL"
+            or pkg["package_distribution"] != package_name
+            or pkg["installation"] != "AUTO_INSTALL_AS_PTSIP_PACKAGE_DEPENDENCY"
+            or pkg["version"] != version
+            or pkg["permission_from_availability"] is not False
+        ):
+            raise ValueError("outdated or incompatible official engine installation contract")
+        b = bindings[kind] if bindings is not None else _load(
+            f"{kind.lower()}/execution-bindings.json"
+        )
+        candidates = b["bindings"]
+        if len(candidates) != 1:
+            raise ValueError("ambiguous registered engine executable")
+        binding = candidates[0]
+        if binding["entrypoint"] != package_name or binding["engine_id"] != engine_id or binding["engine_version"] != version:
+            raise ValueError("registered engine entrypoint mismatch")
+        row: dict[str, Any] = {
+            "engine": kind, "engine_id": engine_id, "expected_version": version,
+            "package": package_name, "host_target": host_target,
+            "status": "NOT_INSTALLED", "execution_authorized": False,
+        }
+        if host_target not in pkg["build_targets"]:
+            row["status"] = "UNSUPPORTED_HOST"
+            entries.append(row)
+            continue
+        if bundled is not None:
+            distribution, bundle = bundled
+            origin = bundle["engines"][kind.lower()]
+            row["package"] = "PTSIP"
+            row["package_version"] = distribution.version
+            row["installed_version"] = origin["engine_version"]
+        else:
+            try:
+                distribution = metadata.distribution(package_name)
+            except metadata.PackageNotFoundError:
+                entries.append(row)
+                continue
+            row["installed_version"] = distribution.version
+        if row["installed_version"] != version:
+            row["status"] = "VERSION_MISMATCH"
+            entries.append(row)
+            continue
+        extension = ".exe" if host_target and "windows" in host_target else ""
+        executable = scripts / (binding["entrypoint"] + extension)
+        if executable.is_symlink() or not executable.is_file():
+            row["status"] = "EXECUTABLE_MISSING_OR_UNTRUSTED_PATH"
+            entries.append(row)
+            continue
+        try:
+            if bundled is None:
+                origin_text = distribution.read_text("ptsip-origin.json")
+                origin = json.loads(origin_text or "")
+            if (
+                origin["engine_id"] != engine_id
+                or origin["engine_version"] != version
+                or origin["host_target"] != host_target
+                or origin["entrypoint"] != executable.name
+                or not isinstance(origin["source_sha"], str)
+                or len(origin["source_sha"]) != 40
+                or origin["binary_sha256"] != _sha256(executable)
+            ):
+                row["status"] = "ARTIFACT_IDENTITY_MISMATCH"
+            else:
+                row["status"] = "INSTALLED_UNATTESTED_RELEASE"
+                row["binary_sha256"] = origin["binary_sha256"]
+                row["source_sha"] = origin["source_sha"]
+        except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError):
+            row["status"] = "ORIGIN_PROOF_MISSING_OR_INVALID"
+        entries.append(row)
+    return {
+        "schema_version": "ptsip-official-engine-consumer-status/v1",
+        "host_target": host_target,
+        "distribution": "SINGLE_PROJECT_PLATFORM_BUNDLES" if bundled else "AUTO_INSTALLED_INDEPENDENT_PACKAGES_ONLY",
+        "entries": entries,
+        "all_installed": all(e["status"] == "INSTALLED_UNATTESTED_RELEASE" for e in entries),
+        "release_attested": False,
+        "execution_authorized": False,
+        "status": "AWAITING_OFFICIAL_RELEASE_ATTESTATION"
+        if all(e["status"] == "INSTALLED_UNATTESTED_RELEASE" for e in entries)
+        else "INCOMPLETE",
+    }
+
+
+def emit_status() -> tuple[dict[str, Any], int]:
+    payload = inspect()
+    return payload, 0 if payload["all_installed"] else 4