nexus-certify 0.1.0__py3-none-any.whl

nexus_certify-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: nexus-certify
+Version: 0.1.0
+Summary: Nexus Evidence Trust Core and Completion Core
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: PyGithub>=2.1.0
+
+# Nexus Core
+
+Nexus Core is the standalone Evidence-to-Claim Completion Certification implementation extracted from Nexus-new.
+
+Its truth authorities are Evidence Trust Core and Completion Core.
+
+## Scope
+
+- **Evidence Trust Core**: Ingestion, normalization, verification, and tamper detection of execution evidence.
+- **Completion Core**: ChangeSet certification, deterministic verification reduction, and disposition enforcement.
+
+It provides the standalone `nexus-certify` CLI and HTTP/deterministic runtime interfaces.
+
+## Local Golden Path
+
+An external Python Git repository can verify a committed or dirty change without
+running the HTTP service or hand-authoring protocol JSON:
+
+The public distribution identity is `nexus-certify`. Until the release gate
+publishes a versioned artifact, install the candidate source or locally built wheel
+in a development environment. After an authorized public release, the supported
+registry install command is `python -m pip install nexus-certify`.
+
+```bash
+nexus-certify init --base-ref main --allow 'src/**' --allow 'tests/**' \
+  --verifier python -m pytest -q
+nexus-certify doctor
+nexus-certify check
+```
+
+The local shell derives real Git object identities and the canonical manifest,
+runs the configured verifier, delegates the verdict to the existing generic Core
+adapter, and persists a verification receipt under `.nexus-core/receipts/`.
+`VERIFIED` remains distinct from `CERTIFIED`; the local receipt is not a
+Certification receipt or merge/release authority.
+
+See [Local Golden Path Contract](docs/LOCAL_GOLDEN_PATH.md) for the exact config,
+negative controls, receipt validation contract, and the not-yet-executed G4
+fresh-environment canary contract.
+
+For trusted same-repository GitHub `push` and `pull_request` events on self-hosted
+runners, see the [G2 GitHub Repository Golden Path](docs/GITHUB_REPOSITORY_CHECK.md).
+Fork PRs and GitHub-hosted runners are explicitly unsupported by that path.
+
+## Generic ChangeSet Verification (experimental)
+
+The loopback HTTP runtime also exposes a transport-neutral, non-GitHub verification seam for bounded consumers such as DevSpace or Open SWE:
+
+- `GET /v1/protocol/generic-verification` — authenticated protocol descriptor, JSON schemas, canonicalization rules, schema-bundle hash, and cross-language conformance vectors.
+- `POST /v1/changesets/verify` — deterministic `AcceptanceContract + ChangeSet + VerificationPlan + EvidenceBundle` verification. Certification is optional and occurs only when the caller supplies explicit policy facts.
+
+Generic revision identities are typed as `git-commit:<40-lowercase-hex>` or `git-tree:<40-lowercase-hex>`. An uncommitted managed change may therefore be verified against a deterministic Git tree without creating a commit first. The generic `diff_hash` binds a canonical source-tree-to-target-tree manifest instead of pretty-patch formatting.
+
+`verification=VERIFIED` does not imply `CERTIFIED`, Candidate acceptance, merge authorization, release, deployment, or production readiness. This interface does not select execution lanes, workers, models, routes, or workspaces.
+
+## Completion Evidence Applicability and Freshness Contract
+
+`product.completion` is an additive Completion Core capability that binds a
+completion claim to the exact source/artifact state it claims, then decides
+whether verification evidence actually applies to that final state. It is
+deterministic, model-independent, and advisory: the completion claim's
+`asserted_by` identity never confers authority, and certification remains with
+`product.kernel.certify`.
+
+It derives three explicit semantic states:
+
+- `CLAIMS_COMPLETE` — a completion claim is present, revision-bound to the
+  change set's `target_revision`, and covers every changed non-deleted path
+  with a claimed final content hash.
+- `VERIFICATION_APPLIES` — every required verifier has an evidence observation
+  that is bound to a changed path, observes the claimed final content hash
+  (freshness by content-hash comparison), and reports `PASS`.
+- `CLAIMS_VERIFIED` — the conjunction of the two states above with the existing
+  deterministic `verify()` reduction. A claim assertion can never substitute
+  for a physical observation.
+
+Per-verifier `EvidenceDisposition` values (`ACCEPTED`, `REJECTED_STALE`,
+`REJECTED_IRRELEVANT`, `REJECTED_MISSING`, `REJECTED_CONTRADICTORY`,
+`REJECTED_FAILED`) let Completion Core explain exactly which evidence was
+accepted, rejected, stale, missing, or contradictory. Original API:
+
+```python
+from product.completion import analyze_completion_evidence, validate_completion_evidence_analysis
+
+analysis = analyze_completion_evidence(claim, contract, change_set, plan, evidence)
+assert analysis.claims_verified         # all three states
+assert validate_completion_evidence_analysis(analysis, claim, contract, change_set, plan, evidence)
+```
+
+Freshness and execution ordering are derived from content hash comparison
+rather than wall-clock timestamps: an observation whose artifact content hash
+differs from the claimed final content hash predates a later mutation and is
+stale unless the hashes are equal (equivalence proven by the trusted hash
+machinery). See `tests/product/test_completion_evidence_applicability.py` for
+the `modify -> test PASS -> modify again` and irrelevant-verification
+regressions.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q tests/product
+uv run pytest -q tests/benchmark
+uv run ruff check product tests
+uv run nexus-certify --help
+```
+
+## Compatibility and Coexistence Boundary
+
+`nexus-core` and the current `nexus-legacy` package in `Nexus-new` have distinct package and console-script ownership:
+
+- Nexus Core is distributed as `nexus-certify` while continuing to own the
+  internal `product` Python package and `nexus-certify` console script.
+- `nexus-legacy` owns the `nexus` and `scripts` packages and the `nexus` console script.
+
+The current package definitions therefore no longer have the historical `product` namespace / `nexus-certify` console-script collision described by the previous README.
+
+Use separate virtual environments for normal development and testing because the repositories have different dependency sets and operational roles. That isolation is development hygiene, not a requirement caused by the retired namespace/script collision.

nexus_certify-0.1.0.dist-info/RECORD

@@ -0,0 +1,46 @@
+product/__init__.py,sha256=xvXwzejqwfCdfJTb_oGKMg2Ypn7RwXDfT0f-jtqwOSI,52
+product/ledger.py,sha256=yIcHlyjIlJxV3apS_s8HASr3FhbGs20rVyUYo_8O4xM,40419
+product/acquisition/__init__.py,sha256=jrzd7v51bgT6RAE2HblvT1E_eKYGh9H5FWADXZKxrUY,842
+product/acquisition/github.py,sha256=E3R9P0KGCF47eSo84unWebv2pGiSZMltE-2O8naS3Vo,15655
+product/adapters/__init__.py,sha256=1DkEAIRjlVpe_Fmxu9ErQ2I_anEzCVChFuWL5mQnKtM,39
+product/adapters/changeset_certification_v2.py,sha256=dRsTXxnwj6-8LaC0oI0RtEkv1aLLX5O87dgMwZk4ugM,36207
+product/adapters/generic_verification.py,sha256=lheYMpkFG1h9BpZSglaApvkZeXWMinxBkZgb02Y4YTc,16249
+product/adapters/github.py,sha256=J-8DrnrGXVIwvTkvHZEQ3Zx2xi3Pw1QuNJJc8IqpVv4,10347
+product/adapters/legacy.py,sha256=QPZL4vC7f6kSGZtDSjRdo3cheXikDrRxcJY4jrKRUn8,1171
+product/adapters/trusted.py,sha256=GsrcoY-6fgsScgnoM4o4kQJV2v6-dqA5Rsngr2rfQDA,21442
+product/benchmark/__init__.py,sha256=wHHb44gGX-f8EPOta1kf8vaElE1v58n_ZxzIHXvKH6Q,53846
+product/benchmark/tg7_shadow.py,sha256=gOZsEx1HKEQ1OrjgtGnvE9NHgZ2iCM0KB5wTtCETmMM,2103
+product/benchmark/tg7_shadow_kernel.py,sha256=MHEhcqRuxjLMPMjFoQDdyEGkofULYtasrAXGVvAVB2U,41400
+product/benchmark/tg9_value.py,sha256=BuBj91yUTE4g-8aeE0eOTPWKfW47r4A2pn0ykTznykg,45949
+product/certification/__init__.py,sha256=Yw0_X06jZCb1tZqw5DrppvkBmseAJl--tDPm5xhjGhY,2867
+product/certification/receipt.py,sha256=w4XabPii3lp_WnpPmZW_HWNvIF19icV2Uux1x7MmsxQ,19369
+product/clients/__init__.py,sha256=6W9lqbdUiKzHIxy0CiIWA6dkZg9IYVM_vR9F3Mg0oCs,566
+product/clients/cli.py,sha256=yB5G44JMO36aMEJQNSs4gewlvp1qDRfoqsm1vVNeIDg,14650
+product/clients/github_action.py,sha256=Z-kSnn5wVmLwEFbWB8uI94w-omwdxgI6ijRWubxnP78,11621
+product/clients/local_golden_path.py,sha256=s0s1_whFeSpRobJdwSmlMwy-5Amc78m9lvwUYx4NOdE,30499
+product/clients/mcp.py,sha256=RF5SiXgeTKelLv8Fj-oPUVkINR-ia1yoZfGHB29uS3o,5494
+product/completion/__init__.py,sha256=MVnB9S7AYfV8QXQ5Fb0ciLIQuv-sg3Ha7mTnKRw-_TU,23118
+product/evidence/__init__.py,sha256=sC0WF34FAH80ZTPAbTp9v-xTPk3lzjCZdEVVwoHUL_s,32660
+product/evidence/code_integrity.py,sha256=i_ThdcTonfpAAKaJRWXiwFneVEkYndRuxxRGpMSEkts,27894
+product/evidence/ingestion.py,sha256=0QkQrnpXDCftGysp8nSBew0cpnXgHQAc_Iyo2QoRoDU,96210
+product/execution/__init__.py,sha256=FNLS3FhyNqz5WCUSbp3J0iqwX2nsCxypdnRyA9-DzP0,1015
+product/execution/python_runner.py,sha256=D7VOqvvhL8KhkhIANk9S2TnQE2tQXUrXBzPv5pHLCMA,28918
+product/execution/profiles/__init__.py,sha256=ocOHYa4W4wgIYxU4QYizCVBohSb2IDHvhaqrcQim1mc,57
+product/execution/profiles/python-oci-pytest-v1.json,sha256=qj49XuuZ4SJy6Cwi5vLGeFA3Bsrp-RdYMHAwf5e-jaY,517
+product/execution/profiles/python-oci-pytest-v1.lock,sha256=5gPRsKszIciB84lrKUb2Rq2-EmL1uWSL2VV-cmILXZ8,1513
+product/kernel/__init__.py,sha256=zzX4Sy-6xuScQ1VKk6yfrT6nwgDMTb9h574gHYiVZiE,5336
+product/protocol/__init__.py,sha256=-t-ooUzNHtCXoosaR_WflCHVihdbfXIvsxsi8Ldl3qI,696
+product/protocol/compatibility_gate.py,sha256=8hLjxR0f2e9Ft5W2kQKEJPXZ3nnAOURagY7Sva627no,5579
+product/protocol/compatibility_gate_kernel.py,sha256=W-lKXq5kVoiJii4a7UmJItA4ictKgHglxYrdmnxgHtI,40525
+product/protocol/generic_verification.py,sha256=dCZfMpcGGNK99Vj8oH5G7WiEZi_TEvnctGJVR-T2III,31271
+product/runtime/__init__.py,sha256=UWP4zFdcVpvmr8fDs_uAV_qnOjnyWgsOFYLbOcnSslo,1512
+product/runtime/auth.py,sha256=yjXe0qyn7nT23q8lwFZCT31KOfnsb3hkLrHnAuGijKc,6349
+product/runtime/http.py,sha256=KM7XO80tyUMRvSGPEEpUk18chJsapcep-Q6hbpC2m4s,12947
+product/runtime/schemas.py,sha256=p8XCWMSBXzVJYXGortyMj14tnhc9XaTSh2sdpq636bo,12913
+product/runtime/service.py,sha256=Wj-xZYAVXwzyGP7Z-bTnKSHZR2eClbJC54K2qVYmgC4,30570
+product/verification/__init__.py,sha256=Bwle0QbMHveecHwjCjyFsOzOdypC9N5vWuvWQjA_fv8,8125
+nexus_certify-0.1.0.dist-info/METADATA,sha256=tyCv7OZwhWbQDxEmXPbsJk76IJWSZvaM5dMaaoZWqZ8,6579
+nexus_certify-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nexus_certify-0.1.0.dist-info/entry_points.txt,sha256=QxDwcmncZyvXBHYhJKpnA-Ki0Xbf6s0hxYXW6mbJva0,59
+nexus_certify-0.1.0.dist-info/top_level.txt,sha256=FrxW_86o3e_ivgRQnhtrp6bWvCG39Mq7aKsxCtzKFTQ,8
+nexus_certify-0.1.0.dist-info/RECORD,,

nexus_certify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nexus_certify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nexus-certify = product.clients.cli:main

nexus_certify-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+product

product/__init__.py

@@ -0,0 +1 @@
+"""Pure completion-certification product kernel."""

product/acquisition/__init__.py

@@ -0,0 +1,29 @@
+"""Credential-free acquisition ports for externally owned source systems.
+
+Acquisition is deliberately separate from :mod:`product.adapters`: ports are
+injected by the controller and return already-authorized, read-only data.
+"""
+
+from .github import (
+    AcquisitionError,
+    GitHubAcquisitionSnapshot,
+    GitHubPullRequestAcquisition,
+    GitHubPullRequestLocator,
+    GitHubReadPort,
+    acquire_github_pull_request,
+    acquire_pull_request,
+    load_github_acquisition_snapshot,
+    serialize_github_acquisition_snapshot,
+)
+
+__all__ = [
+    "AcquisitionError",
+    "GitHubAcquisitionSnapshot",
+    "GitHubPullRequestAcquisition",
+    "GitHubPullRequestLocator",
+    "GitHubReadPort",
+    "acquire_github_pull_request",
+    "acquire_pull_request",
+    "load_github_acquisition_snapshot",
+    "serialize_github_acquisition_snapshot",
+]

product/acquisition/github.py

@@ -0,0 +1,400 @@
+"""Injected, read-only GitHub pull-request acquisition.
+
+The port intentionally has no credential parameter and this module has no
+network client.  A controller-owned implementation performs authentication
+outside the product package and supplies one complete response per read.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Mapping, Protocol, runtime_checkable
+
+_SHA40 = re.compile(r"[0-9a-f]{40}\Z")
+_SHA256 = re.compile(r"sha256:[0-9a-f]{64}\Z")
+_NAME = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})?\Z")
+_UTC_RFC3339 = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\Z")
+_REQUIRED = frozenset({
+    "repository_owner",
+    "repository_name",
+    "pr_number",
+    "base_sha",
+    "head_sha",
+    "base_tree_sha",
+    "head_tree_sha",
+    "merge_base_policy",
+    "diff_bytes",
+    "diff_hash",
+    "changed_paths",
+    "deleted_paths",
+    "checks",
+    "pagination_complete",
+    "observed_at",
+    "freshness_cas",
+})
+
+
+class AcquisitionError(ValueError):
+    """A response cannot be admitted as an immutable acquisition snapshot."""
+
+
+class PermissionDenied(AcquisitionError):
+    """The injected port could not read the requested PR."""
+
+
+class AcquisitionDriftError(AcquisitionError):
+    """The two independent reads do not describe the same PR identity."""
+
+
+@dataclass(frozen=True)
+class GitHubPullRequestLocator:
+    repository_owner: str
+    repository_name: str
+    pr_number: int
+
+    def __post_init__(self) -> None:
+        for field in ("repository_owner", "repository_name"):
+            value = getattr(self, field)
+            if (
+                type(value) is not str
+                or not value
+                or value != value.strip()
+                or _NAME.fullmatch(value) is None
+            ):
+                raise AcquisitionError(f"{field} is not a normalized GitHub name")
+        if type(self.pr_number) is not int or self.pr_number <= 0:
+            raise AcquisitionError("pr_number must be a positive exact int")
+
+    @property
+    def locator_hash(self) -> str:
+        value = [self.repository_owner.lower(), self.repository_name.lower(), self.pr_number]
+        return (
+            "sha256:"
+            + hashlib.sha256(json.dumps(value, separators=(",", ":")).encode()).hexdigest()
+        )
+
+
+@runtime_checkable
+class GitHubReadPort(Protocol):
+    """Controller-provided authenticated read seam; credentials never cross it."""
+
+    def read_pull_request(self, locator: GitHubPullRequestLocator) -> Mapping[str, object]: ...
+
+
+def _sha(value: object, field: str) -> str:
+    if type(value) is not str or _SHA40.fullmatch(value) is None:
+        raise AcquisitionError(f"{field} must be lowercase 40-hex SHA")
+    return value
+
+
+def _hash(value: object, field: str) -> str:
+    if type(value) is not str or _SHA256.fullmatch(value) is None:
+        raise AcquisitionError(f"{field} must be sha256:<64 lowercase hex>")
+    return value
+
+
+def _paths(value: object, field: str, *, allow_empty: bool = True) -> tuple[str, ...]:
+    if not isinstance(value, (list, tuple)):
+        raise AcquisitionError(f"{field} must be a path list")
+    result = tuple(str(x) for x in value)
+    if not allow_empty and not result:
+        raise AcquisitionError(f"{field} must be non-empty")
+    if len(result) != len(set(result)):
+        raise AcquisitionError(f"{field} contains duplicate paths")
+    for path in result:
+        if (
+            type(path) is not str
+            or not path
+            or path != path.strip()
+            or path.startswith("/")
+            or "\\" in path
+            or any(part in {"", ".", ".."} for part in path.split("/"))
+        ):
+            raise AcquisitionError(f"{field} contains an invalid relative path")
+    return tuple(sorted(result))
+
+
+def _canonical(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def _freshness_cas_for(
+    owner: str,
+    repository: str,
+    pr_number: int,
+    base_sha: str,
+    head_sha: str,
+    base_tree_sha: str,
+    head_tree_sha: str,
+    merge_base_policy: str,
+    diff_hash: str,
+    changed_paths: tuple[str, ...],
+    deleted_paths: tuple[str, ...],
+    checks: tuple[tuple[str, str], ...],
+) -> str:
+    subject = {
+        "repository_owner": owner.lower(),
+        "repository_name": repository.lower(),
+        "pr_number": pr_number,
+        "base_sha": base_sha,
+        "head_sha": head_sha,
+        "base_tree_sha": base_tree_sha,
+        "head_tree_sha": head_tree_sha,
+        "merge_base_policy": merge_base_policy,
+        "diff_hash": diff_hash,
+        "changed_paths": list(changed_paths),
+        "deleted_paths": list(deleted_paths),
+        "checks": [list(item) for item in checks],
+    }
+    return "sha256:" + hashlib.sha256(_canonical(subject).encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class GitHubAcquisitionSnapshot:
+    repository_owner: str
+    repository_name: str
+    pr_number: int
+    base_sha: str
+    head_sha: str
+    base_tree_sha: str
+    head_tree_sha: str
+    merge_base_policy: str
+    diff_bytes: bytes
+    diff_hash: str
+    changed_paths: tuple[str, ...]
+    deleted_paths: tuple[str, ...]
+    checks: tuple[tuple[str, str], ...]
+    pagination_complete: bool
+    observed_at: str
+    freshness_cas: str
+    locator_hash: str
+
+    def __post_init__(self) -> None:
+        locator = GitHubPullRequestLocator(
+            self.repository_owner, self.repository_name, self.pr_number
+        )
+        for field in ("base_sha", "head_sha", "base_tree_sha", "head_tree_sha"):
+            _sha(getattr(self, field), field)
+        if self.base_sha == self.head_sha:
+            raise AcquisitionError("base_sha and head_sha must differ")
+        if self.merge_base_policy != "base_sha_exact":
+            raise AcquisitionError("merge_base_policy must be base_sha_exact")
+        if type(self.diff_bytes) is not bytes:
+            raise AcquisitionError("diff_bytes must be immutable bytes")
+        expected = "sha256:" + hashlib.sha256(self.diff_bytes).hexdigest()
+        if self.diff_hash != expected:
+            raise AcquisitionError("diff_hash does not match diff_bytes")
+        _hash(self.diff_hash, "diff_hash")
+        if self.changed_paths != tuple(sorted(self.changed_paths)):
+            raise AcquisitionError("changed_paths must be sorted")
+        if self.deleted_paths != tuple(sorted(self.deleted_paths)):
+            raise AcquisitionError("deleted_paths must be sorted")
+        _paths(self.changed_paths, "changed_paths", allow_empty=False)
+        _paths(self.deleted_paths, "deleted_paths")
+        if not set(self.deleted_paths).issubset(set(self.changed_paths)):
+            raise AcquisitionError("deleted_paths must be a subset of changed_paths")
+        if type(self.checks) is not tuple or any(
+            type(x) is not tuple or len(x) != 2 for x in self.checks
+        ):
+            raise AcquisitionError("checks must be (identity, digest) pairs")
+        if self.checks != tuple(sorted(self.checks)) or len({x[0] for x in self.checks}) != len(
+            self.checks
+        ):
+            raise AcquisitionError("checks must be sorted and have unique identities")
+        for identity, digest in self.checks:
+            if (
+                type(identity) is not str
+                or not identity
+                or identity != identity.strip()
+                or "\x00" in identity
+            ):
+                raise AcquisitionError("check identities must be normalized")
+            _hash(digest, "check digest")
+        if type(self.pagination_complete) is not bool or not self.pagination_complete:
+            raise AcquisitionError("pagination_complete must be true")
+        if type(self.observed_at) is not str or _UTC_RFC3339.fullmatch(self.observed_at) is None:
+            raise AcquisitionError("observed_at must be canonical UTC RFC3339 ending in Z")
+        try:
+            parsed = datetime.fromisoformat(self.observed_at[:-1])
+        except ValueError as exc:
+            raise AcquisitionError("observed_at must be a valid UTC RFC3339 timestamp") from exc
+        if parsed.tzinfo is not None:
+            raise AcquisitionError("observed_at must use canonical Z timezone")
+        expected_cas = _freshness_cas_for(
+            self.repository_owner,
+            self.repository_name,
+            self.pr_number,
+            self.base_sha,
+            self.head_sha,
+            self.base_tree_sha,
+            self.head_tree_sha,
+            self.merge_base_policy,
+            self.diff_hash,
+            self.changed_paths,
+            self.deleted_paths,
+            self.checks,
+        )
+        if self.freshness_cas != expected_cas:
+            raise AcquisitionError("freshness_cas does not match snapshot subject")
+        if self.locator_hash != locator.locator_hash:
+            raise AcquisitionError("locator_hash does not match locator")
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "repository_owner": self.repository_owner,
+            "repository_name": self.repository_name,
+            "pr_number": self.pr_number,
+            "base_sha": self.base_sha,
+            "head_sha": self.head_sha,
+            "base_tree_sha": self.base_tree_sha,
+            "head_tree_sha": self.head_tree_sha,
+            "merge_base_policy": self.merge_base_policy,
+            "diff_bytes": self.diff_bytes.hex(),
+            "diff_hash": self.diff_hash,
+            "changed_paths": list(self.changed_paths),
+            "deleted_paths": list(self.deleted_paths),
+            "checks": [list(x) for x in self.checks],
+            "pagination_complete": self.pagination_complete,
+            "observed_at": self.observed_at,
+            "freshness_cas": self.freshness_cas,
+            "locator_hash": self.locator_hash,
+        }
+
+
+def _parse(
+    raw: Mapping[str, object], locator: GitHubPullRequestLocator
+) -> GitHubAcquisitionSnapshot:
+    if not isinstance(raw, Mapping) or set(raw) != _REQUIRED:
+        raise AcquisitionError("response has an incomplete or substituted schema")
+    values = dict(raw)
+    if (
+        values["repository_owner"] != locator.repository_owner
+        or values["repository_name"] != locator.repository_name
+        or values["pr_number"] != locator.pr_number
+    ):
+        raise AcquisitionDriftError("response locator differs from requested locator")
+    diff_bytes = values["diff_bytes"]
+    if not isinstance(diff_bytes, bytes):
+        raise AcquisitionError("diff_bytes must be bytes from the read port")
+    checks = values["checks"]
+    if not isinstance(checks, (list, tuple)):
+        raise AcquisitionError("checks must be a list")
+    checks_tuple: tuple[tuple[str, str], ...] = tuple(
+        (str(x[0]), str(x[1]))
+        for x in checks
+        if isinstance(x, (list, tuple)) and len(x) == 2
+    )
+    changed_paths = values["changed_paths"]
+    changed_tuple = tuple(str(x) for x in changed_paths) if isinstance(changed_paths, (list, tuple)) else ()
+    deleted_paths = values["deleted_paths"]
+    deleted_tuple = tuple(str(x) for x in deleted_paths) if isinstance(deleted_paths, (list, tuple)) else ()
+    raw_pr = values["pr_number"]
+    pr_num = raw_pr if isinstance(raw_pr, int) else int(str(raw_pr))
+    return GitHubAcquisitionSnapshot(
+        repository_owner=str(values["repository_owner"]),
+        repository_name=str(values["repository_name"]),
+        pr_number=pr_num,
+        base_sha=str(values["base_sha"]),
+        head_sha=str(values["head_sha"]),
+        base_tree_sha=str(values["base_tree_sha"]),
+        head_tree_sha=str(values["head_tree_sha"]),
+        merge_base_policy=str(values["merge_base_policy"]),
+        diff_bytes=diff_bytes,
+        diff_hash=str(values["diff_hash"]),
+        changed_paths=changed_tuple,
+        deleted_paths=deleted_tuple,
+        checks=checks_tuple,
+        pagination_complete=bool(values["pagination_complete"]),
+        observed_at=str(values["observed_at"]),
+        freshness_cas=str(values["freshness_cas"]),
+        locator_hash=locator.locator_hash,
+    )
+
+
+def acquire_github_pull_request(
+    port: GitHubReadPort, locator: GitHubPullRequestLocator
+) -> GitHubAcquisitionSnapshot:
+    """Read twice and admit only convergent, complete, immutable identity."""
+    if not isinstance(locator, GitHubPullRequestLocator):
+        raise TypeError("locator must be GitHubPullRequestLocator")
+    try:
+        first = port.read_pull_request(locator)
+        second = port.read_pull_request(locator)
+    except PermissionError as exc:
+        raise PermissionDenied("GitHub read permission denied") from exc
+    left = _parse(first, locator)
+    right = _parse(second, locator)
+    if left != right:
+        raise AcquisitionDriftError("independent GitHub reads disagree")
+    return left
+
+
+def serialize_github_acquisition_snapshot(snapshot: GitHubAcquisitionSnapshot) -> dict[str, object]:
+    if type(snapshot) is not GitHubAcquisitionSnapshot:
+        raise TypeError("snapshot must be GitHubAcquisitionSnapshot")
+    return snapshot.to_dict()
+
+
+def load_github_acquisition_snapshot(payload: Mapping[str, object]) -> GitHubAcquisitionSnapshot:
+    if not isinstance(payload, Mapping):
+        raise TypeError("payload must be a mapping")
+    values = dict(payload)
+    try:
+        raw_diff = values["diff_bytes"]
+        diff_bytes = bytes.fromhex(str(raw_diff))
+        raw_checks = values["checks"]
+        checks_tuple: tuple[tuple[str, str], ...] = tuple(
+            (str(x[0]), str(x[1]))
+            for x in raw_checks
+            if isinstance(x, (list, tuple)) and len(x) == 2
+        ) if isinstance(raw_checks, (list, tuple)) else ()
+        raw_changed = values["changed_paths"]
+        changed_tuple = tuple(str(x) for x in raw_changed) if isinstance(raw_changed, (list, tuple)) else ()
+        raw_deleted = values["deleted_paths"]
+        deleted_tuple = tuple(str(x) for x in raw_deleted) if isinstance(raw_deleted, (list, tuple)) else ()
+        raw_pr = values["pr_number"]
+        pr_num = raw_pr if isinstance(raw_pr, int) else int(str(raw_pr))
+        return GitHubAcquisitionSnapshot(
+            repository_owner=str(values["repository_owner"]),
+            repository_name=str(values["repository_name"]),
+            pr_number=pr_num,
+            base_sha=str(values["base_sha"]),
+            head_sha=str(values["head_sha"]),
+            base_tree_sha=str(values["base_tree_sha"]),
+            head_tree_sha=str(values["head_tree_sha"]),
+            merge_base_policy=str(values["merge_base_policy"]),
+            diff_bytes=diff_bytes,
+            diff_hash=str(values["diff_hash"]),
+            changed_paths=changed_tuple,
+            deleted_paths=deleted_tuple,
+            checks=checks_tuple,
+            pagination_complete=bool(values["pagination_complete"]),
+            observed_at=str(values["observed_at"]),
+            freshness_cas=str(values["freshness_cas"]),
+            locator_hash=str(values["locator_hash"]),
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        raise AcquisitionError("malformed serialized acquisition snapshot") from exc
+
+
+GitHubPullRequestAcquisition = GitHubAcquisitionSnapshot
+acquire_pull_request = acquire_github_pull_request
+
+
+__all__ = [
+    "AcquisitionError",
+    "AcquisitionDriftError",
+    "GitHubAcquisitionSnapshot",
+    "GitHubPullRequestAcquisition",
+    "GitHubPullRequestLocator",
+    "GitHubReadPort",
+    "PermissionDenied",
+    "acquire_github_pull_request",
+    "acquire_pull_request",
+    "load_github_acquisition_snapshot",
+    "serialize_github_acquisition_snapshot",
+]

product/adapters/__init__.py

@@ -0,0 +1 @@
+"""External compatibility adapters."""