proofbundle 3.2.2__tar.gz → 3.2.3__tar.gz

{proofbundle-3.2.2/src/proofbundle.egg-info → proofbundle-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 3.2.2
+Version: 3.2.3
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -205,7 +205,7 @@ a preprint.
 | **K-Veritas** ([arXiv 2605.08586](https://arxiv.org/abs/2605.08586)) — nonrepudiable experimental results | the academic case for tamper-evident, execution-bound experiment reports | preprint | proofbundle is a released, offline, eval-shaped receipt for exactly this problem, not the only take on it |
 | **Attestable Audits** ([arXiv 2506.23706](https://arxiv.org/abs/2506.23706)) — TEE-verified safety audits | that the computation actually ran, inside a trusted enclave | preprint (research prototype) | a receipt proves authorship + integrity, **not** that the computation was correct — that needs a TEE or independent reproduction |
 | **BenchJack** ([arXiv 2605.12673](https://arxiv.org/abs/2605.12673)) — auditing agent benchmarks | whether the benchmark itself is gameable (reward-hacking) | preprint | a receipt over a gameable benchmark is honestly still just a receipt; it says nothing about whether the eval was well designed |
-| **Evaluation Cards** ([arXiv 2606.09809](https://arxiv.org/abs/2606.09809)) — reporting / interpretation layer | a structured, human-facing account of what a result means | preprint | a receipt can bind a card's integrity, not its quality |
+| **Evaluation Cards** ([arXiv 2606.09809](https://arxiv.org/abs/2606.09809)) — reporting / interpretation layer | a structured, human-facing account of what a result means | preprint | a receipt can bind a card's integrity (`evaluation_card_sha256`, EVAL_CLAIM.md), not its quality |
 | in-toto / Sigstore, SCITT / Rekor v2, OpenSSF Model Signing (stable standards / production) | artifact-provenance, public transparency, model-artifact signing | — | see [INTEROP.md](https://github.com/b7n0de/proofbundle/blob/main/INTEROP.md) for the honest tool-by-tool comparison |
 
 ## Cite this work
@@ -341,12 +341,17 @@ is anchored to external RFC 6962 vectors and a real Rekor proof, not just its ow
 by itself — it is the small, offline, standards-native receipt layer between them. Security policy:
 [SECURITY.md](https://github.com/b7n0de/proofbundle/blob/main/SECURITY.md).
 
-**Roadmap (stated honestly, all forward-looking):**
+**Roadmap (stated honestly, not yet built):**
 
 - A post-quantum *payload* signature (crypto-agility for the receipt itself) is on the roadmap; today the
   post-quantum coverage is witness-side ML-DSA-44 cosignatures only.
 - A CLI flag to select the content-root algorithm is still deferred (`jcs-sha256-v1` is the signed default).
-- **Preview:** a TEE-attestation bridge — see [docs/EXPERIMENTAL_ENCLAVE.md](https://github.com/b7n0de/proofbundle/blob/main/docs/EXPERIMENTAL_ENCLAVE.md).
+
+**Already shipped, preview/experimental maturity (not on the roadmap above — built, tested, install
+extra `[experimental]`, but API/wire-format may still change without deprecation):**
+
+- A TEE-attestation bridge (RATS/EAT, RFC 9334 + RFC 9711) that makes `assurance_level =
+  enclave_attested` independently verifiable — see [docs/EXPERIMENTAL_ENCLAVE.md](https://github.com/b7n0de/proofbundle/blob/main/docs/EXPERIMENTAL_ENCLAVE.md).
 
 ## Contributing
 

{proofbundle-3.2.2 → proofbundle-3.2.3}/README.md

@@ -151,7 +151,7 @@ a preprint.
 | **K-Veritas** ([arXiv 2605.08586](https://arxiv.org/abs/2605.08586)) — nonrepudiable experimental results | the academic case for tamper-evident, execution-bound experiment reports | preprint | proofbundle is a released, offline, eval-shaped receipt for exactly this problem, not the only take on it |
 | **Attestable Audits** ([arXiv 2506.23706](https://arxiv.org/abs/2506.23706)) — TEE-verified safety audits | that the computation actually ran, inside a trusted enclave | preprint (research prototype) | a receipt proves authorship + integrity, **not** that the computation was correct — that needs a TEE or independent reproduction |
 | **BenchJack** ([arXiv 2605.12673](https://arxiv.org/abs/2605.12673)) — auditing agent benchmarks | whether the benchmark itself is gameable (reward-hacking) | preprint | a receipt over a gameable benchmark is honestly still just a receipt; it says nothing about whether the eval was well designed |
-| **Evaluation Cards** ([arXiv 2606.09809](https://arxiv.org/abs/2606.09809)) — reporting / interpretation layer | a structured, human-facing account of what a result means | preprint | a receipt can bind a card's integrity, not its quality |
+| **Evaluation Cards** ([arXiv 2606.09809](https://arxiv.org/abs/2606.09809)) — reporting / interpretation layer | a structured, human-facing account of what a result means | preprint | a receipt can bind a card's integrity (`evaluation_card_sha256`, EVAL_CLAIM.md), not its quality |
 | in-toto / Sigstore, SCITT / Rekor v2, OpenSSF Model Signing (stable standards / production) | artifact-provenance, public transparency, model-artifact signing | — | see [INTEROP.md](https://github.com/b7n0de/proofbundle/blob/main/INTEROP.md) for the honest tool-by-tool comparison |
 
 ## Cite this work
@@ -287,12 +287,17 @@ is anchored to external RFC 6962 vectors and a real Rekor proof, not just its ow
 by itself — it is the small, offline, standards-native receipt layer between them. Security policy:
 [SECURITY.md](https://github.com/b7n0de/proofbundle/blob/main/SECURITY.md).
 
-**Roadmap (stated honestly, all forward-looking):**
+**Roadmap (stated honestly, not yet built):**
 
 - A post-quantum *payload* signature (crypto-agility for the receipt itself) is on the roadmap; today the
   post-quantum coverage is witness-side ML-DSA-44 cosignatures only.
 - A CLI flag to select the content-root algorithm is still deferred (`jcs-sha256-v1` is the signed default).
-- **Preview:** a TEE-attestation bridge — see [docs/EXPERIMENTAL_ENCLAVE.md](https://github.com/b7n0de/proofbundle/blob/main/docs/EXPERIMENTAL_ENCLAVE.md).
+
+**Already shipped, preview/experimental maturity (not on the roadmap above — built, tested, install
+extra `[experimental]`, but API/wire-format may still change without deprecation):**
+
+- A TEE-attestation bridge (RATS/EAT, RFC 9334 + RFC 9711) that makes `assurance_level =
+  enclave_attested` independently verifiable — see [docs/EXPERIMENTAL_ENCLAVE.md](https://github.com/b7n0de/proofbundle/blob/main/docs/EXPERIMENTAL_ENCLAVE.md).
 
 ## Contributing
 

{proofbundle-3.2.2 → proofbundle-3.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "3.2.2"
+version = "3.2.3"
 description = "Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT."
 readme = "README.md"
 requires-python = ">=3.10"

{proofbundle-3.2.2 → proofbundle-3.2.3}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "3.2.2"
+__version__ = "3.2.3"
 
 # The `proofbundle/v0.1` normative spec revision this build implements — kept in sync with the
 # `Revision:` line at the top of SPEC.md by tests/test_docs_truth.py (WP-B1, closes #28). Bump
@@ -44,6 +44,8 @@ __all__ = [
     "audit_challenge",
     "prereg_hash",
     "verify_prereg",
+    "evaluation_card_hash",
+    "verify_evaluation_card",
     "beacon_audit_challenge",
     "canonicalize_statement",
     "statement_content_root",
@@ -64,6 +66,15 @@ __all__ = [
     "verify_mldsa",
     "verify_slhdsa",
     "verify_hybrid",
+    "EvidenceLevel",
+    "classify_digest_evidence",
+    "classify_receiver_corroboration",
+    "evidence_ladder_summary",
+    "evidence_ladder_best",
+    "VerificationBudget",
+    "DEFAULT_BUDGET",
+    "BudgetExceeded",
+    "automation_summary",
     "VerificationResult",
     "Check",
     "ProofBundleError",
@@ -89,6 +100,8 @@ _LAZY = {
     "audit_challenge": ".persample",
     "prereg_hash": ".prereg",
     "verify_prereg": ".prereg",
+    "evaluation_card_hash": ".evalcard",
+    "verify_evaluation_card": ".evalcard",
     "beacon_audit_challenge": ".beacon",
     "canonicalize_statement": ".canonical",
     "statement_content_root": ".canonical",
@@ -109,6 +122,11 @@ _LAZY = {
     "verify_mldsa": ".pqsig",
     "verify_slhdsa": ".pqsig",
     "verify_hybrid": ".pqsig",
+    "EvidenceLevel": ".assurance", "classify_digest_evidence": ".assurance",
+    "classify_receiver_corroboration": ".assurance", "evidence_ladder_summary": ".assurance",
+    "evidence_ladder_best": ".assurance",
+    "VerificationBudget": ".budget", "DEFAULT_BUDGET": ".budget", "BudgetExceeded": ".budget",
+    "automation_summary": ".automation_verdict",
 }
 
 if TYPE_CHECKING:  # static analysers + IDEs see the real names/types; runtime stays lazy
@@ -129,7 +147,12 @@ if TYPE_CHECKING:  # static analysers + IDEs see the real names/types; runtime s
                           evaluate_renewal_policy, last_ats, renew_hashtree, renew_timestamp,
                           verify_sequence)
     from .pqsig import verify_hybrid, verify_mldsa, verify_slhdsa
+    from .assurance import (EvidenceLevel, classify_digest_evidence, classify_receiver_corroboration,
+                            evidence_ladder_best, evidence_ladder_summary)
+    from .budget import DEFAULT_BUDGET, BudgetExceeded, VerificationBudget
+    from .automation_verdict import automation_summary
     from .prereg import prereg_hash, verify_prereg
+    from .evalcard import evaluation_card_hash, verify_evaluation_card
     from .statuslist import verify_status_snapshot
     from .tlogproof import verify_tlog_proof
     from .merkle import verify_consistency, verify_inclusion

{proofbundle-3.2.2 → proofbundle-3.2.3}/src/proofbundle/_strict_json.py

@@ -49,7 +49,30 @@ def _reject_duplicate_keys(pairs: list) -> dict:
     return obj
 
 
-def loads_strict(text: Union[str, bytes]) -> Any:
+def _enforce_node_budget(obj: Any, json_nodes: int) -> None:
+    """Bounded iterative walk (crypto-review 2026-07-15): refuse a PARSED structure whose combined
+    dict-key + list-item count exceeds ``json_nodes`` — a wide-but-small-bytes document that slips under the
+    raw ``input_bytes`` cap. Aborts the moment the ceiling is passed, so it never walks the whole of an
+    over-budget document; the raw cap already bounds this walk's own worst case. Raises
+    :class:`proofbundle.budget.BudgetExceeded` (a ``ProofBundleError`` subclass), fail-closed."""
+    from .budget import BudgetExceeded  # noqa: PLC0415 - local import avoids an import cycle
+    count = 0
+    stack = [obj]
+    while stack:
+        cur = stack.pop()
+        if isinstance(cur, dict):
+            count += len(cur)
+            if count > json_nodes:
+                raise BudgetExceeded("json_nodes", count, json_nodes)
+            stack.extend(cur.values())
+        elif isinstance(cur, list):
+            count += len(cur)
+            if count > json_nodes:
+                raise BudgetExceeded("json_nodes", count, json_nodes)
+            stack.extend(cur)
+
+
+def loads_strict(text: Union[str, bytes], *, budget: Any = None) -> Any:
     """``json.loads`` that rejects duplicate object keys at any nesting depth.
 
     Raises :class:`BundleFormatError` for a duplicate key (fail-closed, clear message), maps
@@ -58,9 +81,24 @@ def loads_strict(text: Union[str, bytes]) -> Any:
     with more than ``sys.get_int_max_str_digits()`` digits (CWE-674 / CVE-2020-10735) to it too —
     never a raw traceback — mirroring :func:`proofbundle.bundle.load_bundle`. Ordinary JSON syntax
     errors keep raising ``ValueError`` (``json.JSONDecodeError``) so existing ``except (ValueError,
-    ...)`` handling at the call sites stays correct."""
+    ...)`` handling at the call sites stays correct.
+
+    DoS backstop (Finding 15b, crypto-review 2026-07-15): this is the ONE parse chokepoint every verify
+    path funnels through, so the resource caps live here rather than at each of ~10 call sites. The raw
+    ``text`` is refused BEFORE parsing when it exceeds ``budget.input_bytes`` (``json.loads`` cost scales
+    with input size, so an unbounded parse of a 50 MB envelope is a real pre-loop DoS the downstream
+    signature/list caps cannot reach), and the PARSED structure is refused when its combined dict-key +
+    list-item count exceeds ``budget.json_nodes``. Both raise :class:`proofbundle.budget.BudgetExceeded`
+    (a ``ProofBundleError`` subclass, so existing ``except (ProofBundleError, ...)`` sites treat it as
+    fail-closed malformed/over-limit input). ``budget`` defaults to ``DEFAULT_BUDGET``; pass a tighter one
+    to test the guard."""
+    from .budget import DEFAULT_BUDGET  # noqa: PLC0415 - local import avoids an import cycle
+    b = budget if budget is not None else DEFAULT_BUDGET
+    if len(text) > b.input_bytes:
+        from .budget import BudgetExceeded  # noqa: PLC0415
+        raise BudgetExceeded("input_bytes", len(text), b.input_bytes)
     try:
-        return json.loads(text, object_pairs_hook=_reject_duplicate_keys)
+        obj = json.loads(text, object_pairs_hook=_reject_duplicate_keys)
     except RecursionError as exc:
         raise BundleFormatError("JSON nesting is too deep") from exc
     except ValueError as exc:
@@ -70,3 +108,5 @@ def loads_strict(text: Union[str, bytes]) -> Any:
         if "integer string conversion" in str(exc):
             raise BundleFormatError("JSON integer literal is implausibly long (fail-closed)") from exc
         raise
+    _enforce_node_budget(obj, b.json_nodes)
+    return obj

{proofbundle-3.2.2 → proofbundle-3.2.3}/src/proofbundle/adapters/_provenance.py

@@ -14,6 +14,17 @@ Design notes (verified against framework source, 2026-07):
   - The hash is over the config's JSON, prefixed with a domain tag, hex sha256. It is provenance
     metadata (traceability), NOT a security commitment — it is not salted and reveals structure;
     it exists so two receipts from the same config are linkable and a changed config is visible.
+
+**Benchmark-hacking VISIBILITY (additive).** `run_attempts`/`aborted_runs`/`methodology_sha256`/
+`benchjack_audit_report_sha256` make retry/best-of-many patterns and the methodology behind a
+result *visible* in the signed claim. They are honest metadata, NEVER a cryptographic guarantee
+against a gamed benchmark — `eval_evidence_class` already separates `methodology` from
+`score_evidence` (a receipt never judges whether the suite is well designed), and THREAT_MODEL.md
+states the same boundary for benchmark-hacking explicitly (BenchJack, arXiv:2605.12673): crypto
+cannot prove benchmark truth, only that these numbers are what was signed. The two digest fields
+are plain sha256 references an auditor re-hashes by hand — same mechanism, same epistemic
+strength as `prereg_sha256`/`evaluation_card_sha256` (a match proves only "this is the document
+the issuer pointed at", never that the document is honest or complete).
 """
 
 from __future__ import annotations
@@ -48,11 +59,19 @@ def config_hash(config) -> Optional[str]:
 
 
 def add_provenance(provenance: dict, *, run_id=None, config=None, log_timestamp=None,
-                   config_hash_value: Optional[str] = None) -> dict:
+                   config_hash_value: Optional[str] = None,
+                   run_attempts: Optional[int] = None, aborted_runs: Optional[int] = None,
+                   methodology_sha256: Optional[str] = None,
+                   benchjack_audit_report_sha256: Optional[str] = None) -> dict:
     """Merge the standard traceability fields into a provenance dict, skipping absent ones.
 
     ``config_hash_value`` lets a caller pass a precomputed hash (e.g. over already-canonical
-    material) instead of a config object; otherwise ``config`` is hashed here."""
+    material) instead of a config object; otherwise ``config`` is hashed here.
+
+    ``run_attempts``/``aborted_runs`` (non-negative integers) and ``methodology_sha256``/
+    ``benchjack_audit_report_sha256`` (plain sha256 hex references) are additive VISIBILITY-only
+    fields for benchmark-hacking transparency — see the module docstring; they carry no
+    verification semantics here (no gate calls this a "guarantee")."""
     if run_id:
         provenance["run_id"] = str(run_id)
     if log_timestamp is not None:
@@ -60,4 +79,13 @@ def add_provenance(provenance: dict, *, run_id=None, config=None, log_timestamp=
     ch = config_hash_value if config_hash_value is not None else config_hash(config)
     if ch:
         provenance["config_hash"] = ch
+    for name, value in (("run_attempts", run_attempts), ("aborted_runs", aborted_runs)):
+        if value is not None:
+            if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+                raise ValueError(f"{name} must be a non-negative integer, got {value!r}")
+            provenance[name] = value
+    if methodology_sha256 is not None:
+        provenance["methodology_sha256"] = str(methodology_sha256)
+    if benchjack_audit_report_sha256 is not None:
+        provenance["benchjack_audit_report_sha256"] = str(benchjack_audit_report_sha256)
     return provenance

{proofbundle-3.2.2 → proofbundle-3.2.3}/src/proofbundle/anchors_markovian.py

@@ -57,6 +57,12 @@ def verify_markovian(proof: bytes, canonical_root: bytes, *, frozen: dict,
     # which wallet/merkle_root was committed; BundleFormatError keeps the never-raise contract)
     try:
         from ._strict_json import loads_strict  # noqa: PLC0415
+        from .budget import DEFAULT_BUDGET, BudgetExceeded  # noqa: PLC0415
+        # DoS (crypto-review 2026-07-15): cap the raw proof BEFORE .decode(), mirroring anchors_chia's
+        # len(proof) > _MAX_PROOF_BYTES guard (loads_strict caps the decoded str, but the decode itself is
+        # otherwise unbounded). BudgetExceeded is caught below and reported as a clean _fail, never raised.
+        if len(proof) > DEFAULT_BUDGET.input_bytes:
+            raise BudgetExceeded("input_bytes", len(proof), DEFAULT_BUDGET.input_bytes)
         env = loads_strict(proof.decode("utf-8"))
         if not isinstance(env, dict):
             raise ValueError("envelope is not a JSON object")

proofbundle-3.2.3/src/proofbundle/assurance.py

@@ -0,0 +1,201 @@
+"""EvidenceLevel — a uniform, orderable strength ladder over the digest-presence-only 'proven'/'bound'
+verify-time checks (2026-07 verify-layer hardening, Finding 03, additive/non-breaking).
+
+WURZEL: ``action_outcome_proven`` (decision.py), ``outcome_execution_proven`` (outcome.py), and the
+``evidence_bound`` shape check in decision.py all stop at "does a syntactically valid sha256 digest
+OBJECT exist at this field" (``_is_digest``) — a 64-hex string of AN ATTACKER'S CHOOSING satisfies it as
+readily as the digest of the real referenced artifact; none of them checks the digest against actual
+resolved bytes. ``decision.resolve_evidence_ref`` already exists to go further (it checks a digest against
+ACTUAL bytes an offline caller supplies), but no ``verify_*`` path ever calls it — the deeper evidence
+primitive is built, never wired.
+
+This module makes the STRENGTH of a 'proven'/'bound' claim explicit and orderable, WITHOUT changing the
+existing boolean ``*_proven``/``evidence_bound`` fields (they stay, unchanged, for backward compatibility)
+— each ``verify_*`` function gains ADDITIVE, more precise field(s) that classify a claim onto this ladder.
+"""
+from __future__ import annotations
+
+import enum
+import re
+from typing import Any, Callable, Optional
+
+__all__ = [
+    "EvidenceLevel", "EVIDENCE_LEVEL_NAMES", "classify_digest_evidence",
+    "classify_receiver_corroboration",
+    "evidence_ladder_summary", "evidence_ladder_best", "EFFECT_OBSERVED_NOT_IMPLEMENTED",
+]
+
+_SHA256_HEX = re.compile(r"^[0-9a-f]{64}$")
+
+
+class EvidenceLevel(enum.IntEnum):
+    """Ordered ladder from a bare claim to full effect observation (No-Overclaim, Finding 03). Higher is
+    strictly stronger; compare/sort with the plain ``int``/``IntEnum`` ordering."""
+
+    CLAIMED = 0                  # a value is asserted but not even shaped as a digest
+    REFERENCE_WELL_FORMED = 1    # a syntactically valid sha256 digest OBJECT is present (the old
+                                  # *_proven==True / evidence_bound==True bar — attacker-choosable content)
+    CONTENT_RESOLVED = 2         # the digest was checked against ACTUALLY RESOLVED bytes
+                                  # (mirrors decision.resolve_evidence_ref's content_root_ok)
+    RECEIPT_CRYPTO_VERIFIED = 3  # the resolved content is ITSELF a cryptographically verified receipt
+    POLICY_AUTHORIZED = 4        # a trust policy additionally authorizes the claim (signer/role pinned)
+    INDEPENDENTLY_ATTESTED = 5   # a THIRD PARTY (not the original claimant) attests the same content
+    EFFECT_OBSERVED = 6          # the real-world EFFECT itself was observed, not merely a receipt about it
+
+
+EVIDENCE_LEVEL_NAMES: tuple[str, ...] = tuple(level.name for level in EvidenceLevel)
+
+# EFFECT_OBSERVED is structurally UNREACHABLE from this module alone (Finding 16 — real-world effect
+# observation, e.g. a monitored side channel confirming the outcome actually happened in the world, not
+# merely that a receipt about it was signed/resolved). No verify_* path in this repo can compute it today.
+# Making that explicit here — rather than silently never emitting it — is itself the honest No-Fake point;
+# a caller grepping for "EFFECT_OBSERVED" finds this marker, not silence.
+#
+# Finding 16 UPDATE (receiver/observer corroboration, self-fixable part): the SELF-FIXABLE portion of
+# Finding 16 IS now built — outcome.py's optional `receiverRefs` + `classify_receiver_corroboration` below
+# make INDEPENDENTLY_ATTESTED (level 5, "a THIRD PARTY attests the same content") reachable when a
+# receiver/observer's own signed acknowledgement is resolved and verified as coming from a party distinct
+# from the executor. EFFECT_OBSERVED (level 6) stays UNREACHABLE even then — a signed receiver receipt is
+# still a RECEIPT ABOUT the effect, never a live-monitored observation of the real-world effect itself; that
+# is Finding 16's honestly-documented INHERENT limit (proofbundle cannot itself make a third-party system
+# sign anything — real-world side-channel monitoring is ecosystem adoption outside this repo).
+EFFECT_OBSERVED_NOT_IMPLEMENTED = (
+    "EvidenceLevel.EFFECT_OBSERVED is not reachable by any verify_* path in this repo (Finding 16's "
+    "self-fixable receiver-corroboration part now reaches INDEPENDENTLY_ATTESTED; EFFECT_OBSERVED itself "
+    "still needs a real-world effect-observation channel, which is an inherent, not-yet-built limit outside "
+    "proofbundle's own control) — TODO, tracked, not silently absent."
+)
+
+
+def _is_digest(obj: Any) -> bool:
+    return isinstance(obj, dict) and isinstance(obj.get("sha256"), str) and bool(_SHA256_HEX.match(obj["sha256"]))
+
+
+def classify_digest_evidence(digest_obj: Any, *, applicable: bool = True,
+                             evidence_resolver: Optional[Callable[[Any], bool]] = None) -> dict:
+    """Classify ONE digest-bound field (e.g. an ``effectDigest``, a ``decisionRef``, one
+    ``evidenceRefs[]`` entry) onto the :class:`EvidenceLevel` ladder. Never raises; a malformed input
+    classifies as ``CLAIMED``, it never crashes the caller.
+
+    ``applicable=False`` (e.g. ``status != 'executed'``) -> ``level=None`` (not applicable, mirrors the
+    existing ``*_proven=None`` convention: a non-applicable claim is not a WEAK claim, it is not a claim
+    at all).
+
+    ``evidence_resolver``, when supplied, is called with ``digest_obj`` and must return True iff the
+    digest was checked against the ACTUAL resolved bytes (mirrors ``resolve_evidence_ref``'s
+    ``content_root_ok``); on True the level reaches ``CONTENT_RESOLVED``, never higher —
+    ``RECEIPT_CRYPTO_VERIFIED``/``POLICY_AUTHORIZED``/``INDEPENDENTLY_ATTESTED`` are each a STRONGER claim
+    this classifier does not itself verify (conflating "checked against real bytes" with "the real bytes'
+    OWN signature was checked" would be exactly the kind of unearned strength bump No-Overclaim forbids).
+    A raising/exception-throwing ``evidence_resolver`` is treated as False (fail-closed: an exception is
+    not evidence, never silently promoted).
+    """
+    if not applicable:
+        return {"level": None, "level_name": None, "detail": "not applicable"}
+    if not _is_digest(digest_obj):
+        return {"level": EvidenceLevel.CLAIMED, "level_name": EvidenceLevel.CLAIMED.name,
+                "detail": "no well-formed sha256 digest object present"}
+    level = EvidenceLevel.REFERENCE_WELL_FORMED
+    detail = "a well-formed sha256 digest object is present (attacker-choosable content, not content-checked)"
+    if evidence_resolver is not None:
+        try:
+            resolved = bool(evidence_resolver(digest_obj))
+        except Exception:  # noqa: BLE001 - fail-closed: a raising resolver proves nothing
+            resolved = False
+        if resolved:
+            level = EvidenceLevel.CONTENT_RESOLVED
+            detail = "digest checked against actually-resolved content bytes"
+    return {"level": level, "level_name": level.name, "detail": detail}
+
+
+def classify_receiver_corroboration(digest_obj: Any, *, applicable: bool = True,
+                                    evidence_resolver: Optional[Callable[[Any], bool]] = None,
+                                    independent_attestation_resolver: Optional[Callable[[Any], bool]] = None,
+                                    executor_key_id: Optional[str] = None,
+                                    receiver_key_id: Optional[str] = None,
+                                    ) -> dict:
+    """Classify a receiver/observer corroboration ref (Finding 16, additive) ONE STEP BEYOND
+    :func:`classify_digest_evidence` — reaches ``EvidenceLevel.INDEPENDENTLY_ATTESTED`` when
+    ``independent_attestation_resolver`` confirms the referenced content is ITSELF a validly-signed
+    statement from a party DISTINCT from the original claimant (e.g. a receiver's or observer's own
+    DSSE-signed acknowledgement of an Action Outcome) — never merely a resolved digest, which is
+    :func:`classify_digest_evidence`'s own documented ceiling (its docstring: "RECEIPT_CRYPTO_VERIFIED /
+    POLICY_AUTHORIZED / INDEPENDENTLY_ATTESTED are each a STRONGER claim this classifier does not itself
+    verify").
+
+    The three-tier informal ladder a caller might reach for here — SELF_ASSERTED / DIGEST_REFERENCED /
+    RECEIVER_CORROBORATED — maps onto this module's EXISTING orderable :class:`EvidenceLevel` rather than
+    a new competing enum (CLAIMED/REFERENCE_WELL_FORMED ≈ SELF_ASSERTED/DIGEST_REFERENCED,
+    INDEPENDENTLY_ATTESTED ≈ RECEIVER_CORROBORATED — "a THIRD PARTY attests the same content" is exactly
+    what a receiver/observer corroboration IS).
+
+    Never raises: a raising ``independent_attestation_resolver`` is fail-closed (treated as False, the base
+    ``classify_digest_evidence`` level is kept — never silently promoted, mirrors the existing
+    ``evidence_resolver`` contract). The resolver is only ever consulted once the digest has ALREADY reached
+    at least ``CONTENT_RESOLVED`` — an attacker-choosable digest that was never resolved cannot be promoted
+    straight to INDEPENDENTLY_ATTESTED by a permissive attestation resolver alone.
+
+    STRUCTURAL independence (crypto-review, 2026-07-15): "INDEPENDENTLY_ATTESTED" means the corroborating
+    statement is from a party DISTINCT from the executor/claimant. proofbundle asserts this only when it can
+    PROVE it: a receiver reaches INDEPENDENTLY_ATTESTED ONLY IF BOTH ``executor_key_id`` AND
+    ``receiver_key_id`` are present AND they differ. An ABSENT ``executor_key_id`` blocks promotion just as
+    an absent/equal receiver key id does — the executor authors and signs its own outcome predicate and
+    ``executor.keyId`` is schema-optional, so a one-sided check (fire only when executor_key_id is supplied)
+    would be trivially evaded by simply omitting one's own keyId. Without knowing BOTH parties' key ids
+    proofbundle cannot show they differ, so it does not claim independence (fail-closed to the base level).
+
+    INHERENT limit (honestly not closed here): two DISTINCT key ids can still belong to the SAME real-world
+    principal (an executor using a second key it also controls). proofbundle cannot bind a key id to a
+    real-world identity on its own — that is exactly what the ``outcomeReceivers`` Trust Pack role provides
+    (``outcome.receiver_trusted_by_role``: a curated list of trusted, genuinely-independent receiver keys).
+    So key-id distinctness here is the STRUCTURAL floor; principal-level independence needs that out-of-band
+    trust binding."""
+    base = classify_digest_evidence(digest_obj, applicable=applicable, evidence_resolver=evidence_resolver)
+    if base["level"] is None or base["level"] < EvidenceLevel.CONTENT_RESOLVED or independent_attestation_resolver is None:
+        return base
+    # Provable distinctness: to ASSERT independence, BOTH key ids must be present, be STRINGS, AND differ.
+    # The isinstance(str) guards close a type-confusion evasion (crypto-review 2026-07-15): a non-str
+    # receiver_key_id (e.g. ["kid-exec"]) is `!= "kid-exec"` in Python, so a bare `==` distinctness check
+    # would read a wrapped copy of the executor's OWN id as "distinct". An absent/non-str/equal key id is
+    # self-corroboration that cannot be shown independent -> fail-closed, no promotion.
+    if not isinstance(executor_key_id, str) or not isinstance(receiver_key_id, str) or receiver_key_id == executor_key_id:
+        return {**base, "detail": base["detail"] + " (independence not provable: executor and receiver key "
+                "ids must both be present and differ; an absent/equal key id is self-corroboration — "
+                "principal-level independence for two distinct keys needs the outcomeReceivers trust role)"}
+    try:
+        attested = bool(independent_attestation_resolver(digest_obj))
+    except Exception:  # noqa: BLE001 - fail-closed: a raising resolver proves nothing
+        attested = False
+    if not attested:
+        return base
+    return {"level": EvidenceLevel.INDEPENDENTLY_ATTESTED,
+            "level_name": EvidenceLevel.INDEPENDENTLY_ATTESTED.name,
+            "detail": "the referenced content is itself a validly-signed statement from a party distinct "
+                      "from the original claimant (receiver/observer corroboration)"}
+
+
+def evidence_ladder_summary(*fields: dict) -> dict:
+    """Roll several :func:`classify_digest_evidence` results into ONE summary using AND semantics: a chain
+    of evidence is only as strong as its WEAKEST applicable link (e.g. ``decision.py``'s
+    ``evidenceRefs[]`` — ``evidence_bound`` is only meaningful when EVERY ref is bound). Non-applicable
+    (``level=None``) fields are ignored, never silently counted as CLAIMED. When no field is applicable,
+    returns ``level=None`` (mirrors the existing ``evidence_bound=None`` "nothing to bind" convention —
+    never a vacuous strong verdict over an empty set)."""
+    applicable = [f for f in fields if f.get("level") is not None]
+    if not applicable:
+        return {"level": None, "level_name": None, "fields": list(fields)}
+    weakest = min(applicable, key=lambda f: f["level"])
+    return {"level": weakest["level"], "level_name": weakest["level_name"], "fields": list(fields)}
+
+
+def evidence_ladder_best(*fields: dict) -> dict:
+    """Roll several :func:`classify_digest_evidence` results into ONE summary using OR semantics: only ONE
+    of several alternative digest fields needs to hold for the claim to be satisfied (e.g.
+    ``outcome.py``'s ``effectDigest`` OR ``actualActionDigest`` — the existing boolean
+    ``outcome_execution_proven`` is exactly this OR). Picks the STRONGEST applicable field. When no field
+    is applicable, returns ``level=None``."""
+    applicable = [f for f in fields if f.get("level") is not None]
+    if not applicable:
+        return {"level": None, "level_name": None, "fields": list(fields)}
+    strongest = max(applicable, key=lambda f: f["level"])
+    return {"level": strongest["level"], "level_name": strongest["level_name"], "fields": list(fields)}

proofbundle-3.2.3/src/proofbundle/automation_verdict.py

@@ -0,0 +1,101 @@
+"""automation_summary — a uniform, additive automation-safety verdict layered on top of any proofbundle
+``verify_*`` result dict (2026-07 verify-layer hardening, Finding 01).
+
+WURZEL: ``bundle.py::root_authenticity_summary`` already computes a ``safeForAutomation`` /
+``automationBlockers`` verdict for the core evidence bundle — it exists ONLY there. The other five
+receipt-chain predicates (``decision.py``, ``outcome.py``, ``trust_pack.py``, ``verification_summary.py``,
+``run_ledger.py``) each compute their OWN aggregate ``ok`` using an ``is not False`` pattern over their
+optional/not-applicable checks (documented, intentional: ``None`` = "not requested, passes"). That is the
+RIGHT default for ``ok`` (a caller who never asked for a policy check should not be told the receipt is
+somehow invalid) — but it is the WRONG bar for an AUTOMATION decision: a caller who filters on ``ok`` alone
+can walk away believing a receipt was policy-authorized when ``policy_ok`` was actually ``None``
+(never evaluated), because ``None is not False`` is ``True``.
+
+``automation_summary`` does NOT change any existing ``ok`` field (additive, no breaking default flip — see
+CHANGELOG "Unreleased" for the ONE deliberately-deferred breaking piece, the ``bundle.py`` CLI exit-code
+default). It computes a SEPARATE, stricter verdict: ``safeForAutomation`` is true only when policy IS
+``True`` (never merely "not False"), mirroring ``bundle.py``'s own ``policy_ok is True`` bar (P0-B, audit
+2026-07-13). Each of the five ``verify_*`` functions stashes this at ``result["automation"]`` — the old
+``result["ok"]`` field is untouched.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Sequence
+
+__all__ = ["automation_summary", "AUTOMATION_BLOCKER_REASONS"]
+
+# The human-legible reason for each automationBlockers enum value (mirrors bundle.py's
+# AUTOMATION_BLOCKER_REASONS — kept here, next to the blocker logic, so the two can never drift apart).
+AUTOMATION_BLOCKER_REASONS = {
+    "CRYPTO_NOT_OK": "The cryptographic (DSSE / threshold-signature) verdict is not true",
+    "STRUCTURE_NOT_OK": "The predicate structure did not fully validate",
+    "POLICY_NOT_EVALUATED": "No trust policy / authorization gate was evaluated for this predicate type",
+    "POLICY_FAILED": "The supplied trust policy / authorization gate was not satisfied",
+    "REFERENCES_NOT_RESOLVED": "One or more referenced/bound artifacts did not resolve (see the "
+                               "predicate's own *_ok / *_bound / *_intact fields for which)",
+}
+
+
+def _tri(result: Mapping[str, Any], key: Optional[str]) -> Optional[bool]:
+    if key is None:
+        return None
+    value = result.get(key)
+    return None if value is None else bool(value)
+
+
+def automation_summary(result: Mapping[str, Any], *, required_checks: Mapping[str, Any]) -> dict:
+    """Build a uniform automation-safety verdict from a ``verify_*`` result dict.
+
+    ``required_checks`` maps the four canonical automation dimensions to the ACTUAL field name(s) in
+    ``result`` that decide them for THIS predicate type (field names differ per ``verify_*`` function):
+
+      ``"crypto"``     -- str, the crypto/signature verdict field (e.g. ``"crypto_ok"``,
+                          ``"root_threshold_met"``).
+      ``"structure"``  -- str, the structural verdict field (e.g. ``"structure_ok"``).
+      ``"policy"``     -- str or ``None``. When a str, the field is treated the SAME way
+                          ``bundle.py::root_authenticity_summary`` treats ``policy_ok``: safe requires the
+                          field to be ``True`` EXACTLY (``is True``), never merely ``is not False`` --
+                          ``None`` (not evaluated) yields ``POLICY_NOT_EVALUATED``, never a silent pass.
+                          When ``None``, this predicate type carries no policy/authorization layer at all
+                          -- the policy dimension is reported ``None`` (not applicable) and never blocks
+                          ``safeForAutomation``.
+      ``"references"`` -- a sequence of field names whose values, when EXPLICITLY ``False``, mean a
+                          referenced/bound artifact did not resolve (e.g. ``decision_bound``,
+                          ``evidence_bound``, ``chain_intact``). ``None`` entries (not applicable / not
+                          requested) never block.
+
+    Returns ``{"cryptoValid", "structureValid", "policyAuthorized", "referencesResolved",
+    "safeForAutomation", "automationBlockers"}``. This function is PURE (no side effects on ``result``);
+    the caller is responsible for stashing the return value at ``result["automation"]``.
+    """
+    crypto_key = required_checks.get("crypto")
+    structure_key = required_checks.get("structure")
+    policy_key = required_checks.get("policy")
+    reference_keys: Sequence[str] = required_checks.get("references") or ()
+
+    crypto_ok = _tri(result, crypto_key)
+    structure_ok = _tri(result, structure_key)
+    policy_val = result.get(policy_key) if policy_key is not None else None
+    unresolved = [name for name in reference_keys if result.get(name) is False]
+
+    blockers: list[str] = []
+    if crypto_ok is not True:
+        blockers.append("CRYPTO_NOT_OK")
+    if structure_ok is not True:
+        blockers.append("STRUCTURE_NOT_OK")
+    if policy_key is not None:
+        if policy_val is None:
+            blockers.append("POLICY_NOT_EVALUATED")
+        elif policy_val is not True:
+            blockers.append("POLICY_FAILED")
+    if unresolved:
+        blockers.append("REFERENCES_NOT_RESOLVED")
+
+    return {
+        "cryptoValid": crypto_ok,
+        "structureValid": structure_ok,
+        "policyAuthorized": None if policy_key is None else (policy_val is True),
+        "referencesResolved": None if not reference_keys else not unresolved,
+        "safeForAutomation": not blockers,
+        "automationBlockers": blockers,
+    }