mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/source_discovery.py

@@ -0,0 +1,898 @@
+"""Strict structural evidence for host-owned source discovery.
+
+Search and capability receipts are untrusted host evidence.  This module does not claim the host
+ran a browser.  It deterministically binds every reported lane, query, source comparison, and
+refusal-recovery chain to one question and one proposal set without granting acquisition authority.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from itertools import pairwise
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256
+from mostlyright.data_harness.local_contracts import (
+    ContractError,
+    SourceProposal,
+    source_locator_identity,
+    validate_source_locator,
+)
+from mostlyright.data_harness.readers.contracts import ReaderError, identifier, semver
+from mostlyright.data_harness.readers.registry import TOOLBOX
+from mostlyright.data_harness.sources.contracts import FITNESS_DIMENSIONS, MAX_EVIDENCE
+
+SOURCE_DISCOVERY_REPORT_SCHEMA_VERSION = "local-source-discovery-report.v2"
+SOURCE_DISCOVERY_POLICY_VERSION = "multi-lane-source-discovery.v2"
+
+DISCOVERY_LANES = (
+    "registered_adapters",
+    "sealed_catalog",
+    "host_web_search",
+    "official_provider",
+    "user_supplied",
+)
+FITNESS_CRITERIA = tuple(sorted(FITNESS_DIMENSIONS))
+DISCOVERY_LANE_STATUSES = ("searched", "unavailable")
+DISCOVERY_CRITERION_RESULTS = ("fail", "pass", "unknown")
+DISCOVERY_FITNESS_DECISIONS = ("eligible", "rejected", "selected")
+DISCOVERY_RECOVERY_OUTCOMES = ("lawful_routes_exhausted", "recovered", "still_rejected")
+DISCOVERY_REJECTION_KINDS = ("fitness_failure", "typed_refusal")
+DISCOVERY_UNAVAILABLE_REASONS = {
+    "registered_adapters": ("no_registered_capability",),
+    "sealed_catalog": ("catalog_not_configured",),
+    "host_web_search": ("host_search_unavailable", "policy_prohibits_network"),
+    "official_provider": ("policy_prohibits_network", "provider_search_unavailable"),
+    "user_supplied": ("no_user_source_supplied",),
+}
+
+_LANE_STATUSES = frozenset(DISCOVERY_LANE_STATUSES)
+_CRITERION_RESULTS = frozenset(DISCOVERY_CRITERION_RESULTS)
+_FITNESS_DECISIONS = frozenset(DISCOVERY_FITNESS_DECISIONS)
+_RECOVERY_OUTCOMES = frozenset(DISCOVERY_RECOVERY_OUTCOMES)
+_REJECTION_KINDS = frozenset(DISCOVERY_REJECTION_KINDS)
+_IDENTIFIER = re.compile(r"^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$")
+_REFUSAL_CODE = re.compile(r"^[A-Z][A-Z0-9_]{1,127}$")
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _object(value: Any, path: str, fields: set[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ContractError(path, "TYPE", "must be an object")
+    if set(value) != fields:
+        raise ContractError(path, "FIELDS", f"must contain exactly {sorted(fields)!r}")
+    return value
+
+
+def _array(value: Any, path: str, *, maximum: int, nonempty: bool = False) -> list[Any]:
+    if not isinstance(value, list):
+        raise ContractError(path, "TYPE", "must be an array")
+    minimum = 1 if nonempty else 0
+    if not minimum <= len(value) <= maximum:
+        raise ContractError(path, "COLLECTION_LIMIT", f"must contain {minimum}..{maximum} items")
+    return value
+
+
+def _text(value: Any, path: str, *, maximum: int = 2_000) -> str:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise ContractError(path, "TEXT", f"must be non-empty text of at most {maximum} characters")
+    if value != value.strip():
+        raise ContractError(path, "NONCANONICAL_TEXT", "must not have surrounding whitespace")
+    if any(ord(character) < 0x20 and character not in {"\t", "\n", "\r"} for character in value):
+        raise ContractError(path, "CONTROL_CHARACTER", "contains a control character")
+    return value
+
+
+def _identifier(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if _IDENTIFIER.fullmatch(text) is None:
+        raise ContractError(path, "IDENTIFIER", "must be a lower-case identifier")
+    return text
+
+
+def _choice(value: Any, choices: frozenset[str], path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if text not in choices:
+        raise ContractError(path, "DISCOVERY_CHOICE", f"must be one of {sorted(choices)!r}")
+    return text
+
+
+def _sha256(value: Any, path: str) -> str:
+    text = _text(value, path, maximum=64)
+    if _SHA256.fullmatch(text) is None:
+        raise ContractError(path, "DIGEST", "must be a lower-case SHA-256 digest")
+    return text
+
+
+def _unique(values: tuple[str, ...], path: str) -> None:
+    if len(set(values)) != len(values):
+        raise ContractError(path, "DUPLICATE", "items must be unique")
+
+
+@dataclass(frozen=True)
+class DiscoveryQuery:
+    """One host query and the immutable host-tool receipt it reports."""
+
+    query: str
+    result_source_ids: tuple[str, ...]
+    search_receipt_sha256: str
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> DiscoveryQuery:
+        data = _object(value, path, {"query", "result_source_ids", "search_receipt_sha256"})
+        source_ids = tuple(
+            _identifier(item, f"{path}.result_source_ids[{index}]")
+            for index, item in enumerate(
+                _array(data["result_source_ids"], f"{path}.result_source_ids", maximum=64)
+            )
+        )
+        _unique(source_ids, f"{path}.result_source_ids")
+        return cls(
+            query=_text(data["query"], f"{path}.query"),
+            result_source_ids=source_ids,
+            search_receipt_sha256=_sha256(
+                data["search_receipt_sha256"], f"{path}.search_receipt_sha256"
+            ),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "query": self.query,
+            "result_source_ids": list(self.result_source_ids),
+            "search_receipt_sha256": self.search_receipt_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class DiscoveryLane:
+    """Reported availability and bounded query trace for one mandatory lane."""
+
+    lane: str
+    status: str
+    reason_code: str | None
+    capability_receipt_sha256: str
+    queries: tuple[DiscoveryQuery, ...]
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> DiscoveryLane:
+        data = _object(
+            value,
+            path,
+            {"lane", "status", "reason_code", "capability_receipt_sha256", "queries"},
+        )
+        lane = _choice(data["lane"], frozenset(DISCOVERY_LANES), f"{path}.lane")
+        status = _choice(data["status"], _LANE_STATUSES, f"{path}.status")
+        queries = tuple(
+            DiscoveryQuery.from_value(item, f"{path}.queries[{index}]")
+            for index, item in enumerate(_array(data["queries"], f"{path}.queries", maximum=32))
+        )
+        reason_value = data["reason_code"]
+        if status == "searched":
+            if reason_value is not None:
+                raise ContractError(
+                    f"{path}.reason_code",
+                    "DISCOVERY_STATE",
+                    "must be null when the lane was searched",
+                )
+            if not queries:
+                raise ContractError(
+                    f"{path}.queries",
+                    "DISCOVERY_STATE",
+                    "a searched lane must record at least one query",
+                )
+            reason_code = None
+        else:
+            reason_code = _choice(
+                reason_value,
+                frozenset(DISCOVERY_UNAVAILABLE_REASONS[lane]),
+                f"{path}.reason_code",
+            )
+            if queries:
+                raise ContractError(
+                    f"{path}.queries",
+                    "DISCOVERY_STATE",
+                    "an unavailable lane cannot claim queries",
+                )
+        return cls(
+            lane=lane,
+            status=status,
+            reason_code=reason_code,
+            capability_receipt_sha256=_sha256(
+                data["capability_receipt_sha256"], f"{path}.capability_receipt_sha256"
+            ),
+            queries=queries,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "lane": self.lane,
+            "status": self.status,
+            "reason_code": self.reason_code,
+            "capability_receipt_sha256": self.capability_receipt_sha256,
+            "queries": [item.to_dict() for item in self.queries],
+        }
+
+
+@dataclass(frozen=True)
+class ComparisonDimension:
+    """One lossless proposal-stage mapping to canonical source fitness evidence."""
+
+    dimension: str
+    outcome: str
+    summary: str
+    evidence_digests: tuple[str, ...]
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> ComparisonDimension:
+        data = _object(value, path, {"dimension", "outcome", "summary", "evidence_digests"})
+        evidence_digests = tuple(
+            _sha256(item, f"{path}.evidence_digests[{index}]")
+            for index, item in enumerate(
+                _array(
+                    data["evidence_digests"],
+                    f"{path}.evidence_digests",
+                    maximum=MAX_EVIDENCE,
+                    nonempty=True,
+                )
+            )
+        )
+        _unique(evidence_digests, f"{path}.evidence_digests")
+        return cls(
+            dimension=_choice(data["dimension"], frozenset(FITNESS_CRITERIA), f"{path}.dimension"),
+            outcome=_choice(data["outcome"], _CRITERION_RESULTS, f"{path}.outcome"),
+            summary=_text(data["summary"], f"{path}.summary", maximum=1_000),
+            evidence_digests=evidence_digests,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "dimension": self.dimension,
+            "outcome": self.outcome,
+            "summary": self.summary,
+            "evidence_digests": list(self.evidence_digests),
+        }
+
+
+@dataclass(frozen=True)
+class DiscoveryReaderPin:
+    """A certified Reader identity plus the digest of its complete sealed options."""
+
+    family_id: str
+    family_version: str
+    decode_options_digest: str
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> DiscoveryReaderPin:
+        data = _object(value, path, {"family_id", "family_version", "decode_options_digest"})
+        try:
+            family_id = identifier(data["family_id"], f"{path}.family_id")
+            family_version = semver(data["family_version"], f"{path}.family_version")
+        except ReaderError as error:
+            raise ContractError(
+                path,
+                "DISCOVERY_READER_PIN",
+                "must contain a canonical certified Reader identity",
+            ) from error
+        if (family_id, family_version) not in TOOLBOX.families():
+            raise ContractError(
+                path,
+                "DISCOVERY_READER_PIN",
+                "must resolve to an exact Reader coordinate in the certified Toolbox",
+            )
+        return cls(
+            family_id=family_id,
+            family_version=family_version,
+            decode_options_digest=_sha256(
+                data["decode_options_digest"], f"{path}.decode_options_digest"
+            ),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "family_id": self.family_id,
+            "family_version": self.family_version,
+            "decode_options_digest": self.decode_options_digest,
+        }
+
+
+@dataclass(frozen=True)
+class SourceComparison:
+    """A proposed source evaluated over every canonical fitness dimension."""
+
+    source_id: str
+    decision: str
+    rejection_kind: str | None
+    promoted_inspection_scope: RecoveryScope | None
+    promoted_inspection_receipt_sha256: str | None
+    dimensions: tuple[ComparisonDimension, ...]
+    rationale: str
+    recovery_attempt_ids: tuple[str, ...]
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> SourceComparison:
+        data = _object(
+            value,
+            path,
+            {
+                "source_id",
+                "decision",
+                "rejection_kind",
+                "promoted_inspection_scope",
+                "promoted_inspection_receipt_sha256",
+                "dimensions",
+                "rationale",
+                "recovery_attempt_ids",
+            },
+        )
+        dimensions = tuple(
+            ComparisonDimension.from_value(item, f"{path}.dimensions[{index}]")
+            for index, item in enumerate(
+                _array(
+                    data["dimensions"],
+                    f"{path}.dimensions",
+                    maximum=len(FITNESS_CRITERIA),
+                    nonempty=True,
+                )
+            )
+        )
+        dimension_names = tuple(item.dimension for item in dimensions)
+        _unique(dimension_names, f"{path}.dimensions")
+        if set(dimension_names) != set(FITNESS_CRITERIA):
+            raise ContractError(
+                f"{path}.dimensions",
+                "FITNESS_DIMENSIONS",
+                "must contain every canonical source fitness dimension exactly once",
+            )
+        attempt_ids = tuple(
+            _identifier(item, f"{path}.recovery_attempt_ids[{index}]")
+            for index, item in enumerate(
+                _array(data["recovery_attempt_ids"], f"{path}.recovery_attempt_ids", maximum=64)
+            )
+        )
+        _unique(attempt_ids, f"{path}.recovery_attempt_ids")
+        decision = _choice(data["decision"], _FITNESS_DECISIONS, f"{path}.decision")
+        rejection_value = data["rejection_kind"]
+        if decision == "rejected":
+            rejection_kind = _choice(rejection_value, _REJECTION_KINDS, f"{path}.rejection_kind")
+            if data["promoted_inspection_scope"] is not None:
+                raise ContractError(
+                    f"{path}.promoted_inspection_scope",
+                    "DISCOVERY_STATE",
+                    "must be null when the source is rejected",
+                )
+            promoted_inspection_scope = None
+            if data["promoted_inspection_receipt_sha256"] is not None:
+                raise ContractError(
+                    f"{path}.promoted_inspection_receipt_sha256",
+                    "DISCOVERY_STATE",
+                    "must be null when the source is rejected",
+                )
+            promoted_inspection_receipt_sha256 = None
+        else:
+            if rejection_value is not None:
+                raise ContractError(
+                    f"{path}.rejection_kind",
+                    "DISCOVERY_STATE",
+                    "must be null unless the source is rejected",
+                )
+            rejection_kind = None
+            if data["promoted_inspection_scope"] is None:
+                raise ContractError(
+                    f"{path}.promoted_inspection_scope",
+                    "DISCOVERY_PROMOTED_SCOPE_REQUIRED",
+                    "a retained source requires its exact inspected execution coordinate",
+                )
+            promoted_inspection_scope = RecoveryScope.from_value(
+                data["promoted_inspection_scope"], f"{path}.promoted_inspection_scope"
+            )
+            promoted_inspection_receipt_sha256 = _sha256(
+                data["promoted_inspection_receipt_sha256"],
+                f"{path}.promoted_inspection_receipt_sha256",
+            )
+        if rejection_kind == "typed_refusal" and not attempt_ids:
+            raise ContractError(
+                f"{path}.recovery_attempt_ids",
+                "DISCOVERY_REFUSAL_RECOVERY_REQUIRED",
+                "a typed refusal requires a changed-scope recovery chain",
+            )
+        if rejection_kind == "fitness_failure" and attempt_ids:
+            raise ContractError(
+                f"{path}.recovery_attempt_ids",
+                "DISCOVERY_REFUSAL_CLASSIFICATION",
+                "a fitness failure cannot carry typed-refusal recovery attempts",
+            )
+        return cls(
+            source_id=_identifier(data["source_id"], f"{path}.source_id"),
+            decision=decision,
+            rejection_kind=rejection_kind,
+            promoted_inspection_scope=promoted_inspection_scope,
+            promoted_inspection_receipt_sha256=promoted_inspection_receipt_sha256,
+            dimensions=dimensions,
+            rationale=_text(data["rationale"], f"{path}.rationale"),
+            recovery_attempt_ids=attempt_ids,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_id": self.source_id,
+            "decision": self.decision,
+            "rejection_kind": self.rejection_kind,
+            "promoted_inspection_scope": (
+                None
+                if self.promoted_inspection_scope is None
+                else self.promoted_inspection_scope.to_dict()
+            ),
+            "promoted_inspection_receipt_sha256": self.promoted_inspection_receipt_sha256,
+            "dimensions": [item.to_dict() for item in self.dimensions],
+            "rationale": self.rationale,
+            "recovery_attempt_ids": list(self.recovery_attempt_ids),
+        }
+
+
+@dataclass(frozen=True)
+class RecoveryScope:
+    """The exact execution coordinates on one side of a refusal retry."""
+
+    locator_kind: str
+    locator: str
+    reader_pin: DiscoveryReaderPin | None
+    data_format: str
+    host_platform: str
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> RecoveryScope:
+        data = _object(
+            value,
+            path,
+            {"locator_kind", "locator", "reader_pin", "data_format", "host_platform"},
+        )
+        reader_value = data["reader_pin"]
+        reader_pin = (
+            None
+            if reader_value is None
+            else DiscoveryReaderPin.from_value(reader_value, f"{path}.reader_pin")
+        )
+        locator_kind = _choice(
+            data["locator_kind"],
+            frozenset({"relative_path", "https_url", "artifact_reference"}),
+            f"{path}.locator_kind",
+        )
+        return cls(
+            locator_kind=locator_kind,
+            locator=validate_source_locator(data["locator"], locator_kind, f"{path}.locator"),
+            reader_pin=reader_pin,
+            data_format=_text(data["data_format"], f"{path}.data_format", maximum=64),
+            host_platform=_text(data["host_platform"], f"{path}.host_platform", maximum=256),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "locator_kind": self.locator_kind,
+            "locator": self.locator,
+            "reader_pin": None if self.reader_pin is None else self.reader_pin.to_dict(),
+            "data_format": self.data_format,
+            "host_platform": self.host_platform,
+        }
+
+
+@dataclass(frozen=True)
+class RecoveryAttempt:
+    """One refusal receipt and one exact replacement inspection receipt."""
+
+    attempt_id: str
+    source_id: str
+    refusal_code: str
+    refusal_receipt_sha256: str
+    refusal_scope: RecoveryScope
+    replacement_scope: RecoveryScope
+    replacement_receipt_sha256: str
+    outcome: str
+
+    @property
+    def changed_fields(self) -> tuple[str, ...]:
+        return tuple(
+            field
+            for field in (
+                "locator_kind",
+                "locator",
+                "reader_pin",
+                "data_format",
+                "host_platform",
+            )
+            if getattr(self.refusal_scope, field) != getattr(self.replacement_scope, field)
+        )
+
+    @classmethod
+    def from_value(cls, value: Any, path: str) -> RecoveryAttempt:
+        data = _object(
+            value,
+            path,
+            {
+                "attempt_id",
+                "source_id",
+                "refusal_code",
+                "refusal_receipt_sha256",
+                "refusal_scope",
+                "replacement_scope",
+                "replacement_receipt_sha256",
+                "outcome",
+            },
+        )
+        refusal_code = _text(data["refusal_code"], f"{path}.refusal_code", maximum=128)
+        if _REFUSAL_CODE.fullmatch(refusal_code) is None:
+            raise ContractError(
+                f"{path}.refusal_code",
+                "DISCOVERY_REFUSAL_CODE",
+                "must be a canonical upper-case refusal code",
+            )
+        attempt = cls(
+            attempt_id=_identifier(data["attempt_id"], f"{path}.attempt_id"),
+            source_id=_identifier(data["source_id"], f"{path}.source_id"),
+            refusal_code=refusal_code,
+            refusal_receipt_sha256=_sha256(
+                data["refusal_receipt_sha256"], f"{path}.refusal_receipt_sha256"
+            ),
+            refusal_scope=RecoveryScope.from_value(data["refusal_scope"], f"{path}.refusal_scope"),
+            replacement_scope=RecoveryScope.from_value(
+                data["replacement_scope"], f"{path}.replacement_scope"
+            ),
+            replacement_receipt_sha256=_sha256(
+                data["replacement_receipt_sha256"], f"{path}.replacement_receipt_sha256"
+            ),
+            outcome=_choice(data["outcome"], _RECOVERY_OUTCOMES, f"{path}.outcome"),
+        )
+        if not attempt.changed_fields:
+            raise ContractError(
+                f"{path}.replacement_scope",
+                "DISCOVERY_UNCHANGED_RECOVERY",
+                "must change at least one exact execution coordinate",
+            )
+        return attempt
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "attempt_id": self.attempt_id,
+            "source_id": self.source_id,
+            "refusal_code": self.refusal_code,
+            "refusal_receipt_sha256": self.refusal_receipt_sha256,
+            "refusal_scope": self.refusal_scope.to_dict(),
+            "replacement_scope": self.replacement_scope.to_dict(),
+            "replacement_receipt_sha256": self.replacement_receipt_sha256,
+            "outcome": self.outcome,
+        }
+
+
+@dataclass(frozen=True)
+class SourceDiscoveryReport:
+    """Canonical untrusted evidence that a host reports following the multi-lane policy."""
+
+    question_id: str
+    lanes: tuple[DiscoveryLane, ...]
+    comparisons: tuple[SourceComparison, ...]
+    recovery_attempts: tuple[RecoveryAttempt, ...]
+    schema_version: str = SOURCE_DISCOVERY_REPORT_SCHEMA_VERSION
+
+    @property
+    def canonical_bytes(self) -> bytes:
+        return canonical_json_bytes(self.to_dict())
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    @classmethod
+    def from_value(cls, value: Any) -> SourceDiscoveryReport:
+        path = "source_discovery"
+        data = _object(
+            value,
+            path,
+            {"schema_version", "question_id", "lanes", "comparisons", "recovery_attempts"},
+        )
+        version = _text(data["schema_version"], f"{path}.schema_version", maximum=64)
+        if version != SOURCE_DISCOVERY_REPORT_SCHEMA_VERSION:
+            raise ContractError(
+                f"{path}.schema_version",
+                "VERSION",
+                f"must be {SOURCE_DISCOVERY_REPORT_SCHEMA_VERSION!r}",
+            )
+        lanes = tuple(
+            DiscoveryLane.from_value(item, f"{path}.lanes[{index}]")
+            for index, item in enumerate(
+                _array(data["lanes"], f"{path}.lanes", maximum=len(DISCOVERY_LANES), nonempty=True)
+            )
+        )
+        lane_names = tuple(item.lane for item in lanes)
+        _unique(lane_names, f"{path}.lanes")
+        if set(lane_names) != set(DISCOVERY_LANES):
+            raise ContractError(
+                f"{path}.lanes",
+                "DISCOVERY_LANES_INCOMPLETE",
+                f"must account for exactly {list(DISCOVERY_LANES)!r}",
+            )
+        comparisons = tuple(
+            SourceComparison.from_value(item, f"{path}.comparisons[{index}]")
+            for index, item in enumerate(
+                _array(data["comparisons"], f"{path}.comparisons", maximum=64)
+            )
+        )
+        _unique(tuple(item.source_id for item in comparisons), f"{path}.comparisons")
+        recovery_attempts = tuple(
+            RecoveryAttempt.from_value(item, f"{path}.recovery_attempts[{index}]")
+            for index, item in enumerate(
+                _array(data["recovery_attempts"], f"{path}.recovery_attempts", maximum=64)
+            )
+        )
+        _unique(tuple(item.attempt_id for item in recovery_attempts), f"{path}.recovery_attempts")
+        return cls(
+            schema_version=version,
+            question_id=_identifier(data["question_id"], f"{path}.question_id"),
+            lanes=lanes,
+            comparisons=comparisons,
+            recovery_attempts=recovery_attempts,
+        )
+
+    def validate_against(
+        self,
+        *,
+        question_id: str,
+        proposals: tuple[SourceProposal, ...],
+        feasibility: str,
+        required_start: str,
+        required_end: str,
+    ) -> None:
+        if self.question_id != question_id:
+            raise ContractError(
+                "source_discovery.question_id",
+                "REFERENCE_MISMATCH",
+                "must reference question.question_id",
+            )
+        proposal_by_source = {item.source_id: item for item in proposals}
+        proposal_ids = set(proposal_by_source)
+        if {item.source_id for item in self.comparisons} != proposal_ids:
+            raise ContractError(
+                "source_discovery.comparisons",
+                "REFERENCE_MISMATCH",
+                "must compare every and only proposed source",
+            )
+        identities = tuple(
+            source_locator_identity(item.locator_kind, item.locator) for item in proposals
+        )
+        if len(set(identities)) != len(identities):
+            raise ContractError(
+                "source_proposals.locator",
+                "DISCOVERY_DUPLICATE_SOURCE",
+                "the same exact source locator cannot be proposed more than once",
+            )
+
+        discovered_ids: set[str] = set()
+        query_receipts_by_source: dict[str, set[str]] = {
+            source_id: set() for source_id in proposal_ids
+        }
+        for lane in self.lanes:
+            for query in lane.queries:
+                for source_id in query.result_source_ids:
+                    if source_id not in proposal_ids:
+                        raise ContractError(
+                            f"source_discovery.lanes.{lane.lane}.queries.result_source_ids",
+                            "REFERENCE_MISMATCH",
+                            "must reference a proposed source",
+                        )
+                    discovered_ids.add(source_id)
+                    query_receipts_by_source[source_id].add(query.search_receipt_sha256)
+        if discovered_ids != proposal_ids:
+            raise ContractError(
+                "source_discovery.lanes",
+                "DISCOVERY_UNDISCOVERED_PROPOSAL",
+                "every proposed source must appear in a searched lane query result",
+            )
+
+        attempt_by_id = {item.attempt_id: item for item in self.recovery_attempts}
+        referenced_attempts: set[str] = set()
+        for comparison in self.comparisons:
+            proposal = proposal_by_source[comparison.source_id]
+            if comparison.decision != proposal.fitness_decision:
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.decision",
+                    "DECISION_MISMATCH",
+                    "must match source_proposal.fitness_decision",
+                )
+            outcomes = {item.dimension: item.outcome for item in comparison.dimensions}
+            if comparison.decision == "selected" and set(outcomes.values()) != {"pass"}:
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions",
+                    "UNFIT_SELECTED",
+                    "a selected source requires every canonical fitness dimension to pass",
+                )
+            if comparison.rejection_kind == "fitness_failure" and "fail" not in outcomes.values():
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions",
+                    "DECISION_CRITERIA_MISMATCH",
+                    "a fitness-failure rejection must identify a failed fitness dimension",
+                )
+            if comparison.rejection_kind == "typed_refusal" and "fail" in outcomes.values():
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions",
+                    "DISCOVERY_REFUSAL_CLASSIFICATION",
+                    "a typed acquisition refusal cannot be represented as a fitness failure",
+                )
+            if comparison.decision == "eligible" and "fail" in outcomes.values():
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions",
+                    "DECISION_CRITERIA_MISMATCH",
+                    "an eligible source cannot have a failed fitness dimension",
+                )
+            allowed_rights = {
+                "approved": {"pass"},
+                "conditional": {"pass", "unknown"},
+                "unclear": {"unknown", "fail"},
+                "prohibited": {"fail"},
+            }[proposal.rights_status]
+            if outcomes["rights"] not in allowed_rights:
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions.rights",
+                    "DISCOVERY_CRITERIA_EVIDENCE_MISMATCH",
+                    "must agree with source_proposal.rights_status",
+                )
+            covers_required_history = (
+                proposal.historical_coverage.start_inclusive <= required_start
+                and proposal.historical_coverage.end_exclusive >= required_end
+            )
+            if outcomes["historical_coverage"] == "pass" and not covers_required_history:
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.dimensions."
+                    "historical_coverage",
+                    "DISCOVERY_CRITERIA_EVIDENCE_MISMATCH",
+                    "cannot pass when source coverage does not contain the required time range",
+                )
+
+            known_evidence = {
+                item.content_sha256 for item in proposal.evidence
+            } | query_receipts_by_source[comparison.source_id]
+            if comparison.promoted_inspection_receipt_sha256 is not None:
+                known_evidence.add(comparison.promoted_inspection_receipt_sha256)
+            attempts: list[RecoveryAttempt] = []
+            for attempt_id in comparison.recovery_attempt_ids:
+                attempt = attempt_by_id.get(attempt_id)
+                if attempt is None or attempt.source_id != comparison.source_id:
+                    raise ContractError(
+                        f"source_discovery.comparisons.{comparison.source_id}.recovery_attempt_ids",
+                        "REFERENCE_MISMATCH",
+                        "must reference recovery attempts for this source",
+                    )
+                attempts.append(attempt)
+                referenced_attempts.add(attempt_id)
+                known_evidence.update(
+                    {attempt.refusal_receipt_sha256, attempt.replacement_receipt_sha256}
+                )
+            for dimension in comparison.dimensions:
+                if not set(dimension.evidence_digests) <= known_evidence:
+                    raise ContractError(
+                        f"source_discovery.comparisons.{comparison.source_id}.dimensions."
+                        f"{dimension.dimension}.evidence_digests",
+                        "DISCOVERY_EVIDENCE_MISMATCH",
+                        "must cite proposal, search, or refusal-recovery evidence for this source",
+                    )
+            self._validate_recovery_chain(comparison, proposal, attempts)
+
+        if referenced_attempts != set(attempt_by_id):
+            raise ContractError(
+                "source_discovery.recovery_attempts",
+                "DISCOVERY_ORPHAN_RECOVERY",
+                "every recovery attempt must be ordered by exactly one source comparison",
+            )
+        selected = sum(item.fitness_decision == "selected" for item in proposals)
+        if feasibility in {"supportable", "supportable_with_limits"} and selected == 0:
+            raise ContractError(
+                "source_discovery.comparisons",
+                "DISCOVERY_FEASIBILITY_MISMATCH",
+                "a supportable decision requires at least one selected source",
+            )
+        if feasibility == "unsupported" and any(
+            item.fitness_decision != "rejected" for item in proposals
+        ):
+            raise ContractError(
+                "source_discovery.comparisons",
+                "UNSUPPORTED_NOT_EXHAUSTED",
+                "unsupported requires every compared source to be rejected",
+            )
+        if feasibility == "unsupported":
+            for comparison in self.comparisons:
+                if comparison.rejection_kind != "typed_refusal":
+                    continue
+                final_attempt = attempt_by_id[comparison.recovery_attempt_ids[-1]]
+                if final_attempt.outcome != "lawful_routes_exhausted":
+                    raise ContractError(
+                        f"source_discovery.recovery_attempts.{final_attempt.attempt_id}.outcome",
+                        "UNSUPPORTED_NOT_EXHAUSTED",
+                        "unsupported requires every typed-refusal chain to end "
+                        "lawful_routes_exhausted",
+                    )
+
+    @staticmethod
+    def _validate_recovery_chain(
+        comparison: SourceComparison,
+        proposal: SourceProposal,
+        attempts: list[RecoveryAttempt],
+    ) -> None:
+        retained = comparison.promoted_inspection_scope
+        if retained is not None and (
+            retained.locator_kind != proposal.locator_kind
+            or retained.locator != proposal.locator
+            or retained.data_format != proposal.data_format
+        ):
+            raise ContractError(
+                f"source_discovery.comparisons.{comparison.source_id}.promoted_inspection_scope",
+                "DISCOVERY_RECOVERY_BINDING",
+                "the promoted inspection coordinate must match the proposal locator and format",
+            )
+        for attempt in attempts[:-1]:
+            if attempt.outcome != "still_rejected":
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{attempt.attempt_id}.outcome",
+                    "DISCOVERY_RECOVERY_TERMINAL",
+                    "every non-final refusal retry must end still_rejected",
+                )
+        for previous, current in pairwise(attempts):
+            if previous.replacement_scope != current.refusal_scope:
+                raise ContractError(
+                    f"source_discovery.comparisons.{comparison.source_id}.recovery_attempt_ids",
+                    "DISCOVERY_RECOVERY_CHAIN",
+                    "each retry must begin at the exact replacement scope of the prior refusal",
+                )
+        if not attempts:
+            return
+        final = attempts[-1]
+        if comparison.decision in {"selected", "eligible"}:
+            if final.outcome != "recovered":
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{final.attempt_id}.outcome",
+                    "DISCOVERY_RECOVERY_OUTCOME",
+                    "a retained source requires its final refusal retry to recover",
+                )
+            if final.replacement_scope != comparison.promoted_inspection_scope:
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{final.attempt_id}.replacement_scope",
+                    "DISCOVERY_RECOVERY_BINDING",
+                    "a recovered replacement must match the exact promoted inspection coordinate",
+                )
+            if final.replacement_receipt_sha256 != comparison.promoted_inspection_receipt_sha256:
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{final.attempt_id}."
+                    "replacement_receipt_sha256",
+                    "DISCOVERY_RECOVERY_BINDING",
+                    "a recovered replacement receipt must be the promoted inspection receipt",
+                )
+        else:
+            first = attempts[0].refusal_scope
+            if (
+                first.locator_kind != proposal.locator_kind
+                or first.locator != proposal.locator
+                or first.data_format != proposal.data_format
+            ):
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{attempts[0].attempt_id}.refusal_scope",
+                    "DISCOVERY_RECOVERY_BINDING",
+                    "a rejected refusal chain must start at the proposed locator and format",
+                )
+            if final.outcome == "recovered":
+                raise ContractError(
+                    f"source_discovery.recovery_attempts.{final.attempt_id}.outcome",
+                    "DISCOVERY_RECOVERY_OUTCOME",
+                    "a rejected source cannot end its refusal chain as recovered",
+                )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "question_id": self.question_id,
+            "lanes": [item.to_dict() for item in self.lanes],
+            "comparisons": [item.to_dict() for item in self.comparisons],
+            "recovery_attempts": [item.to_dict() for item in self.recovery_attempts],
+        }
+
+
+def parse_source_discovery_report(value: Any) -> SourceDiscoveryReport:
+    """Parse untrusted discovery evidence without performing search or acquisition."""
+
+    return SourceDiscoveryReport.from_value(value)