proofbundle 3.2.3__tar.gz → 3.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proofbundle
-Version: 3.2.3
+Version: 3.3.0
 Summary: Emit and verify portable cryptographic evidence bundles, offline: Ed25519 + RFC 6962 Merkle + optional SD-JWT.
 Author: Konrad Gruszka
 License: MIT
@@ -72,7 +72,7 @@ Merkle, one file, no server, no network.
 [![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](https://github.com/b7n0de/proofbundle/blob/main/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21230467.svg)](https://doi.org/10.5281/zenodo.21230467)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21110642.svg)](https://doi.org/10.5281/zenodo.21110642)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](https://github.com/b7n0de/proofbundle/blob/main/scripts/mutation_check.py)
 [![PyPI attestations](https://img.shields.io/badge/PyPI-PEP_740_attested-D6248A.svg)](https://pypi.org/project/proofbundle/#files)
@@ -211,9 +211,11 @@ a preprint.
 ## Cite this work
 
 If proofbundle helped your evaluation pipeline, please cite it. Machine-readable metadata is in
-[`CITATION.cff`](https://github.com/b7n0de/proofbundle/blob/main/CITATION.cff); the archival record and
-concept DOI are on Zenodo ([10.5281/zenodo.21230467](https://doi.org/10.5281/zenodo.21230467)), and the
-current design write-up is the Technical Note linked from [b7n0de.com/proofbundle](https://b7n0de.com/proofbundle).
+[`CITATION.cff`](https://github.com/b7n0de/proofbundle/blob/main/CITATION.cff). The archival software record
+is on Zenodo under concept DOI [10.5281/zenodo.21110642](https://doi.org/10.5281/zenodo.21110642); the
+Technical Note (design write-up) under concept DOI
+[10.5281/zenodo.21230466](https://doi.org/10.5281/zenodo.21230466), also linked from
+[b7n0de.com/proofbundle](https://b7n0de.com/proofbundle).
 
 ## Post-quantum posture (honest, two layers)
 

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

@@ -18,7 +18,7 @@ Merkle, one file, no server, no network.
 [![PyPI](https://img.shields.io/pypi/v/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![Python](https://img.shields.io/pypi/pyversions/proofbundle.svg)](https://pypi.org/project/proofbundle/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-D6248A.svg)](https://github.com/b7n0de/proofbundle/blob/main/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21230467.svg)](https://doi.org/10.5281/zenodo.21230467)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21110642.svg)](https://doi.org/10.5281/zenodo.21110642)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Mutation tested](https://img.shields.io/badge/tests-mutation_gated-D6248A.svg)](https://github.com/b7n0de/proofbundle/blob/main/scripts/mutation_check.py)
 [![PyPI attestations](https://img.shields.io/badge/PyPI-PEP_740_attested-D6248A.svg)](https://pypi.org/project/proofbundle/#files)
@@ -157,9 +157,11 @@ a preprint.
 ## Cite this work
 
 If proofbundle helped your evaluation pipeline, please cite it. Machine-readable metadata is in
-[`CITATION.cff`](https://github.com/b7n0de/proofbundle/blob/main/CITATION.cff); the archival record and
-concept DOI are on Zenodo ([10.5281/zenodo.21230467](https://doi.org/10.5281/zenodo.21230467)), and the
-current design write-up is the Technical Note linked from [b7n0de.com/proofbundle](https://b7n0de.com/proofbundle).
+[`CITATION.cff`](https://github.com/b7n0de/proofbundle/blob/main/CITATION.cff). The archival software record
+is on Zenodo under concept DOI [10.5281/zenodo.21110642](https://doi.org/10.5281/zenodo.21110642); the
+Technical Note (design write-up) under concept DOI
+[10.5281/zenodo.21230466](https://doi.org/10.5281/zenodo.21230466), also linked from
+[b7n0de.com/proofbundle](https://b7n0de.com/proofbundle).
 
 ## Post-quantum posture (honest, two layers)
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proofbundle"
-version = "3.2.3"
+version = "3.3.0"
 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.3 → proofbundle-3.3.0}/src/proofbundle/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "3.2.3"
+__version__ = "3.3.0"
 
 # 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

{proofbundle-3.2.3 → proofbundle-3.3.0}/src/proofbundle/automation_verdict.py

@@ -33,6 +33,12 @@ AUTOMATION_BLOCKER_REASONS = {
     "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)",
+    # relation/v0.1 (EXPERIMENTAL): raised by the DECISION verify path when the trust
+    # policy's relations section is violated (the outcome-path policy gate is a documented
+    # follow-up — verify_outcome_receipt has no policy parameter today) (a named relation did not resolve, or an attached,
+    # verified successor supersedes the receipt under rejectSuperseded). LIVE, not dormant.
+    "LINEAGE_REQUIREMENT_FAILED": "The trust policy's lineage requirement was not met (relations "
+                                  "section: unresolved required relation or superseded receipt)",
 }
 
 

{proofbundle-3.2.3 → proofbundle-3.3.0}/src/proofbundle/cli.py

@@ -1207,6 +1207,39 @@ def _cmd_decision_emit(args: argparse.Namespace) -> int:
     return 0
 
 
+def _load_related(paths, pub: bytes) -> tuple[dict, list[str]]:
+    """relation/v0.1 (--with-related): load DSSE envelopes of RELATED receipts, verify each one
+    STANDALONE under the SAME relying-party key, and key it by its content root. Same-key is the
+    honest v0.1 CLI contract (it matches the strictest relationSigner policy value); per-target
+    keys are a documented follow-up. A file that fails to load is a usage error (exit 2 at the
+    caller) — an envelope that loads but does NOT verify is kept with verified=False, so an
+    attached-but-wrong target FAILS lineage instead of vanishing."""
+    from . import anchors as _anchors_mod  # noqa: PLC0415
+    from . import dsse as _dsse  # noqa: PLC0415
+    related: dict = {}
+    errs: list[str] = []
+    for path in paths or []:
+        try:
+            with open(path, encoding="utf-8") as handle:
+                env = loads_strict(handle.read())   # WP-C1: duplicate keys rejected
+            body = _dsse.load_payload(env)
+            root_hex = _anchors_mod.statement_content_root(body).hex()
+            # L3-audit fix: inside the try so a malformed-envelope error names the offending file too.
+            verified = bool(_dsse.verify_envelope(env, pub, payload_type="application/vnd.in-toto+json"))
+        except (ProofBundleError, OSError, ValueError) as exc:
+            errs.append(f"cannot read --with-related {path}: {exc}")
+            continue
+        rels = None
+        try:
+            stmt = loads_strict(body.decode("utf-8"))
+            if isinstance(stmt, dict) and isinstance(stmt.get("predicate"), dict):
+                rels = stmt["predicate"].get("relationships")
+        except (ProofBundleError, ValueError):
+            rels = None
+        related[root_hex] = {"verified": verified, "relationships": rels}
+    return related, errs
+
+
 def _cmd_decision_verify(args: argparse.Namespace) -> int:
     import base64  # noqa: PLC0415
     from .decision import verify_decision_receipt  # noqa: PLC0415
@@ -1246,10 +1279,16 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
                 merged = dict(pol_trust)
                 merged.update(rp_trust or {})
                 rp_trust = merged
+        related, rel_errs = _load_related(getattr(args, "with_related", None), pub)
+        if rel_errs:
+            for e in rel_errs:
+                print(f"ERROR: {e}", file=sys.stderr)
+            return 2
         result = verify_decision_receipt(env, pub, strict=args.strict, expected_audience=args.aud,
                                          expected_nonce=args.nonce, policy=policy, anchors=anchors,
                                          rp_trust=rp_trust,
-                                         require_derived_subject=args.require_derived_subject)
+                                         require_derived_subject=args.require_derived_subject,
+                                         related=related or None)
     except (ProofBundleError, OSError, ValueError) as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 2
@@ -1265,7 +1304,7 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
             # Findings 01/03 (crypto-review X2): the uniform automation verdict + EvidenceLevel ladder are
             # part of the library result; a pipeline doing `... --json | jq .automation.safeForAutomation`
             # must not get null (indistinguishable from a real "not evaluated"). Emit them here too.
-            "automation", "evidence_levels", "warnings", "errors",
+            "automation", "evidence_levels", "lineage", "warnings", "errors",
         ) if k in result}
         print(json.dumps(report, indent=2, default=str))
     else:
@@ -1315,6 +1354,11 @@ def _cmd_decision_verify(args: argparse.Namespace) -> int:
     # signal — fail-closed, never a silent exit 0 (fix-review Finding 3). None = no anchor supplied.
     if result["anchors_ok"] is False:
         return 1
+    # relation/v0.1: a REQUESTED lineage check (edges present or --with-related supplied) that FAILs
+    # (cycle, depth, malformed ancestor, attached-but-unverified target) is a tamper/structure signal —
+    # fail-closed exit 2, never a silent exit 0. DECLARED_UNRESOLVED stays exit 0 (declared-only is honest).
+    if isinstance(result.get("lineage"), dict) and result["lineage"].get("lineage") == "FAIL":
+        return 2
     if result["policy_ok"] is False:
         return 3
     return 0
@@ -1422,11 +1466,16 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
         with open(args.envelope, encoding="utf-8") as handle:
             env = loads_strict(handle.read())   # WP-C1: duplicate keys rejected
         pub = base64.b64decode(args.pub)
+        related, rel_errs = _load_related(getattr(args, "with_related", None), pub)
+        if rel_errs:
+            for e in rel_errs:
+                print(f"ERROR: {e}", file=sys.stderr)
+            return 2
         result = verify_outcome_receipt(
             env, pub, strict=args.strict,
             expected_decision_ref=args.expected_decision_ref, decision_maker_id=args.decision_maker_id,
             expected_audience=args.aud, expected_nonce=args.nonce,
-            require_derived_subject=args.require_derived_subject)
+            require_derived_subject=args.require_derived_subject, related=related or None)
     except (ProofBundleError, OSError, ValueError) as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 2
@@ -1439,7 +1488,7 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
             # is not silently blind to them (a jq filter on an absent key is indistinguishable from a real
             # None). executor_role_trusted/receiver_* are None unless the caller supplied a trust_pack.
             "automation", "evidence_levels", "executor_role_trusted", "receiver_bound", "receiver_role_trusted",
-            "warnings", "errors",
+            "lineage", "warnings", "errors",
         ) if k in result}
         print(json.dumps(report, indent=2, default=str))
     else:
@@ -1481,6 +1530,10 @@ def _cmd_outcome_verify(args: argparse.Namespace) -> int:
     # fail-closed binding as --aud/--nonce — an EXTERNAL_ATTESTED subject then must not exit 0.
     if result["subject_derived_ok"] is False:
         return 2
+    # relation/v0.1 (adversarial-review finding, 2026-07-16): mirror of the decision-verify gate —
+    # a REQUESTED lineage check (--with-related / edges present) that FAILs must never exit 0.
+    if isinstance(result.get("lineage"), dict) and result["lineage"].get("lineage") == "FAIL":
+        return 2
     return 0
 
 
@@ -1983,6 +2036,12 @@ def build_parser() -> argparse.ArgumentParser:
     d_verify.add_argument("--bitcoin-header", action="append", default=None, metavar="HEIGHT:MERKLEROOT_HEX",
                           help="WP-A1: a relying-party-supplied Bitcoin block header (internal byte order) "
                                "that confirms an OpenTimestamps statement anchor — frozen is never trusted")
+    d_verify.add_argument("--with-related", dest="with_related", action="append", default=None, metavar="PATH",
+                          help="relation/v0.1 (EXPERIMENTAL): attach a RELATED receipt's DSSE envelope for "
+                               "offline lineage resolution (repeatable). Each target is verified standalone "
+                               "under the SAME --pub (same-key contract); an attached target that does not "
+                               "verify FAILS lineage — relationship declared by issuer, not a statement of "
+                               "correctness")
     d_verify.add_argument("--require-derived-subject", dest="require_derived_subject", action="store_true",
                           help="Finding 05: fail closed (exit 2) unless the Statement subject is a DERIVED "
                                "commitment to the predicate (subject_binding.classify_subject) — rejects a "
@@ -2027,6 +2086,9 @@ def build_parser() -> argparse.ArgumentParser:
     o_verify.add_argument("--strict", action="store_true", help="enforce strict-v0.1 required fields")
     o_verify.add_argument("--aud", default=None, help="expected audience (checks validity.audience against replay)")
     o_verify.add_argument("--nonce", default=None, help="expected nonce (checks validity.nonce against replay)")
+    o_verify.add_argument("--with-related", dest="with_related", action="append", default=None, metavar="PATH",
+                          help="relation/v0.1 (EXPERIMENTAL): attach a RELATED receipt's DSSE envelope for "
+                               "offline lineage resolution (repeatable; same-key contract as decision verify)")
     o_verify.add_argument("--require-derived-subject", dest="require_derived_subject", action="store_true",
                           help="Finding 05: fail closed (exit 2) unless the Statement subject is a DERIVED "
                                "commitment to the predicate (subject_binding.classify_subject) — rejects a "

{proofbundle-3.2.3 → proofbundle-3.3.0}/src/proofbundle/decision.py

@@ -48,7 +48,7 @@ _REQUIRED_STRICT = _REQUIRED_ALWAYS + ("notChecked", "decisionChangeConditions",
 # prereg anchor) are referenced indirectly via `evidenceRefs`. An `anchors` field inside the predicate is
 # therefore a fail-closed unknown-field error.
 _OPTIONAL = ("recordedAt", "delegationRefs", "actionOutcome", "traceContext", "validity",
-             "notChecked", "decisionChangeConditions", "privacy")
+             "notChecked", "decisionChangeConditions", "privacy", "relationships")
 _ALLOWED_TOP = set(_REQUIRED_ALWAYS) | set(_OPTIONAL)
 
 # Time-bearing paths that, if present, MUST be RFC3339-Z.
@@ -254,6 +254,16 @@ def validate_decision_predicate(predicate: Any, *, strict: bool = False) -> list
     elif strict and isinstance(priv, dict) and not isinstance(priv.get("rawInputsIncluded"), bool):
         errors.append("privacy.rawInputsIncluded (boolean) is required in strict mode")
 
+    # relationships (optional, relation/v0.1 EXPERIMENTAL): typed, SIGNED lineage edges to earlier
+    # receipts — inside the predicate so the existing DSSE signature covers them (unlike detached
+    # `anchors`). Edge closure/enums/digest shape are enforced by relation.validate_relationships
+    # (fail-closed, incl. per-edge additionalProperties:false), so the block is NOT walked by the
+    # generic nested-closure below.
+    if "relationships" in predicate:
+        from .relation import validate_relationships
+        errors.extend(f"relationships: {e}" if not e.startswith("relationships") else e
+                      for e in validate_relationships(predicate.get("relationships")))
+
     # Nested schema closure (Finding 04): additionalProperties:false at the TOP level does not, by itself,
     # close these nested objects — an undeclared key inside decision/policyBoundary/proposedAction/
     # decisionMaker/evidenceRefs[] (and their sub-objects) previously rode along silently.
@@ -395,6 +405,9 @@ def _empty_result() -> dict:
         # (assurance.classify_digest_evidence) computed at the end of verify — never gate anything on
         # these two here, the old ok/*_proven/evidence_bound fields above are UNCHANGED for compat.
         "automation": None, "evidence_levels": None,
+        # relation/v0.1 (EXPERIMENTAL, additive): lineage verdict over the predicate's OPTIONAL
+        # relationships edges — None until computed over AUTHENTICATED bytes; never gates `ok`.
+        "lineage": None, "lineage_requirement_failed": None, "lineage_ok": None,
         "warnings": [], "errors": [],
     }
 
@@ -403,7 +416,8 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
                             expected_audience: str | None = None, expected_nonce: str | None = None,
                             policy: dict | None = None, anchors: list | None = None,
                             rp_trust: dict | None = None, require_derived_subject: bool = False,
-                            evidence_resolver: Callable[[dict], bool] | None = None) -> dict:
+                            evidence_resolver: Callable[[dict], bool] | None = None,
+                            related: dict | None = None) -> dict:
     """Verify a DSSE-signed Decision Receipt. Crypto first, then structure over the EXACT signed bytes (never
     re-serialized). Returns the snake_case structured result; each check independent, non-applicable = None.
 
@@ -535,6 +549,33 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
             "actionOutcome.outcomeRef": _outcome_level,
             "evidenceRefs": _evref_levels,
         }
+
+        # relation/v0.1 (EXPERIMENTAL, additive): evaluate the OPTIONAL relationships edges against
+        # caller-attached targets (`related`, offline — the CLI's --with-related). Computed ONLY over
+        # authenticated bytes (this block), NEVER feeds `ok`/crypto (lattice monotonicity); a lineage
+        # FAIL surfaces via errors[] and the policy layer, not by flipping the crypto verdict.
+        if "relationships" in predicate or related:
+            from . import anchors as _anchors_for_rel  # noqa: PLC0415
+            from .relation import successor_warning, verify_relationship_edges  # noqa: PLC0415
+            try:
+                _subject_hex = _anchors_for_rel.statement_content_root(body).hex()
+            except Exception:
+                _subject_hex = None
+            r["lineage"] = verify_relationship_edges(
+                predicate.get("relationships"), related, subject_hex=_subject_hex)
+            # Advisory by default; the policy's reject_superseded turns it into a blocker below.
+            _sw = successor_warning(predicate.get("relationships"), related, subject_hex=_subject_hex)
+            r["lineage"]["supersededByAttached"] = _sw
+            if _sw:
+                r["warnings"].append(f"lineage: {_sw}")
+            if r["lineage"]["lineage"] == "FAIL":
+                r["errors"].extend(r["lineage"]["errors"] or ["relation: lineage verification FAILED"])
+            # No-Fake (6-Linsen-Audit L2, 2026-07-16): a REQUESTED lineage check that FAILs must be
+            # visible in the aggregate `ok` and `automation` — like every other error category in this
+            # result — not only at the CLI exit code. lineage_ok is False ONLY on FAIL (DECLARED_UNRESOLVED
+            # and NOT_EVALUATED are honest non-fails, stay None). This tightens the verdict downward; it
+            # NEVER lifts it (crypto_ok is untouched, lattice monotonicity preserved).
+            r["lineage_ok"] = False if r["lineage"]["lineage"] == "FAIL" else None
         # 3.1.2 fail-closed fix (audit 2026-07-13, sibling of the eval-path F4 hardening and the decision
         # template/expiry gates): a relying party who supplies expected_audience/expected_nonce is ASKING for
         # RFC-9901-§7.3-style replay/audience binding. If the receipt carries NO validity object (or a
@@ -662,6 +703,27 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
                     "decision_receipt.trusted_decision_makers) — POLICY: OK then proves integrity by an "
                     "UNKNOWN signer. Pin the expected decision-maker key(s).")
 
+    # relation/v0.1 policy gate (relations section, LIVE): a violation fails policy_ok (exit-3 class)
+    # and raises the dedicated automation blocker LINEAGE_REQUIREMENT_FAILED below — it NEVER touches
+    # the crypto verdict (lattice monotonicity). require_relation_resolution is conditional on
+    # presence: a named relation that appears as an edge MUST be VERIFIED (attached + standalone-
+    # verified); an absent relation is no violation.
+    if policy is not None and isinstance(policy.get("relations"), dict) and r["crypto_ok"]:
+        _rel_pol = policy["relations"]
+        _lin = r.get("lineage") or {}
+        _viol = []
+        _req = _rel_pol.get("require_relation_resolution") or []
+        for _e in (_lin.get("edges") or []):
+            if _e.get("relation") in _req and _e.get("resolution") != "VERIFIED":
+                _viol.append(f"relation {_e.get('relation')!r} must resolve (target attached and "
+                             f"verified), got {_e.get('resolution')}")
+        if _rel_pol.get("reject_superseded") and _lin.get("supersededByAttached"):
+            _viol.append(f"reject_superseded: {_lin['supersededByAttached']}")
+        if _viol:
+            r["policy_ok"] = False
+            r["lineage_requirement_failed"] = True
+            r["errors"].extend("LINEAGE_REQUIREMENT_FAILED: " + v for v in _viol)
+
     # Aggregate verdict: authenticated AND well-structured AND no applicable trust check FAILED.
     # None means not-applicable (passes); only an explicit False fails the aggregate.
     r["ok"] = bool(
@@ -669,13 +731,22 @@ def verify_decision_receipt(envelope: dict, public_key: bytes, *, strict: bool =
         and r["policy_ok"] is not False and r["signer_trusted"] is not False
         and r["audience_ok"] is not False and r["nonce_ok"] is not False
         and r["evidence_bound"] is not False and r["anchors_ok"] is not False
-        and r["subject_derived_ok"] is not False)
+        and r["subject_derived_ok"] is not False and r["lineage_ok"] is not False)
 
     # Finding 01 (additive): the STRICTER automation-safety verdict — policy_ok must be True, never merely
     # "not False" — never changes `ok` above.
     from .automation_verdict import automation_summary  # noqa: PLC0415
     r["automation"] = automation_summary(r, required_checks={
         "crypto": "crypto_ok", "structure": "structure_ok", "policy": "policy_ok",
-        "references": ["evidence_bound", "audience_ok", "nonce_ok", "anchors_ok", "subject_derived_ok"],
+        "references": ["evidence_bound", "audience_ok", "nonce_ok", "anchors_ok", "subject_derived_ok",
+                       "lineage_ok"],
     })
+    # relation/v0.1: the dedicated blocker name (LIVE, not dormant) — POLICY_FAILED already fires via
+    # policy_ok=False above; this names the REASON so a consumer can distinguish a lineage gate from
+    # any other policy failure. Only ever ADDS a blocker (never turns safeForAutomation true).
+    if r.get("lineage_requirement_failed") and isinstance(r.get("automation"), dict):
+        blockers = r["automation"].setdefault("automationBlockers", [])
+        if "LINEAGE_REQUIREMENT_FAILED" not in blockers:
+            blockers.append("LINEAGE_REQUIREMENT_FAILED")
+        r["automation"]["safeForAutomation"] = False
     return r

{proofbundle-3.2.3 → proofbundle-3.3.0}/src/proofbundle/outcome.py

@@ -45,7 +45,10 @@ _OPTIONAL = ("actualActionDigest", "responseDigest", "effectDigest", "recordedAt
              "traceContext", "limitations", "validity",
              # Finding 16 (self-fixable part, additive): receiverRefs / sequence — see the module-level
              # note above `_OUTCOME_RECEIVER_ROLE` for what each closes and its honest, documented limit.
-             "receiverRefs", "sequence")
+             "receiverRefs", "sequence",
+             # relation/v0.1 (EXPERIMENTAL, 3.3.0): typed signed lineage edges — validated fail-closed
+             # by relation.validate_relationships (incl. per-edge closure), not by the generic walker.
+             "relationships")
 _ALLOWED_TOP = set(_REQUIRED_ALWAYS) | set(_OPTIONAL)
 
 _DIGEST_FIELDS = ("requestedActionDigest", "actualActionDigest", "responseDigest", "effectDigest")
@@ -186,6 +189,14 @@ def validate_outcome_predicate(predicate: Any, *, strict: bool = False) -> list[
     if "validity" in predicate and not isinstance(val, dict):
         errors.append("validity must be an object")
 
+    # relationships (optional, relation/v0.1 EXPERIMENTAL): typed, SIGNED lineage edges — inside the
+    # predicate so the DSSE signature covers them; closure/enums/digests enforced fail-closed by the
+    # relation module itself.
+    if "relationships" in predicate:
+        from .relation import validate_relationships
+        errors.extend(f"relationships: {e}" if not e.startswith("relationships") else e
+                      for e in validate_relationships(predicate.get("relationships")))
+
     # Nested schema closure (Finding 04): additionalProperties:false at the TOP level does not, by itself,
     # close traceContext/validity — an undeclared key inside either previously rode along silently.
     errors.extend(nested_closure_violations(predicate, _NESTED_ALLOWED))
@@ -422,7 +433,7 @@ def _empty_result() -> dict:
         # a non-empty receiverRefs are supplied. Neither is wired into the aggregate `ok` (receiverRefs is
         # OPTIONAL supplementary evidence, not core to the outcome's own validity — see verify docstring).
         "receiver_bound": None, "receiver_role_trusted": None,
-        "warnings": [], "errors": [],
+        "lineage": None, "lineage_ok": None, "warnings": [], "errors": [],
     }
 
 
@@ -431,7 +442,8 @@ def verify_outcome_receipt(envelope: dict, public_key: bytes, *, strict: bool =
                            expected_audience: str | None = None, expected_nonce: str | None = None,
                            require_derived_subject: bool = False, trust_pack: dict | None = None,
                            evidence_resolver: Callable[[dict], bool] | None = None,
-                           receiver_attestation_resolver: Callable[[dict], bool] | None = None) -> dict:
+                           receiver_attestation_resolver: Callable[[dict], bool] | None = None,
+                           related: dict | None = None) -> dict:
     """Verify a DSSE-signed Outcome Receipt. Crypto first, then structure over the EXACT signed bytes.
 
     Outcome-specific fail-closed checks (each applies only after crypto passes; non-applicable = None):
@@ -547,6 +559,28 @@ def verify_outcome_receipt(envelope: dict, public_key: bytes, *, strict: bool =
                     "role separation violated — executor.id equals the decisionMaker id; whoever decides "
                     "must not witness their own execution (fail-closed)")
 
+        # relation/v0.1 (EXPERIMENTAL, additive): evaluate the OPTIONAL relationships edges against
+        # caller-attached targets (offline --with-related). Only over AUTHENTICATED bytes; NEVER feeds
+        # the crypto verdict (lattice monotonicity) — a lineage FAIL surfaces via errors[] + policy.
+        if "relationships" in predicate or related:
+            from . import anchors as _anchors_for_rel  # noqa: PLC0415
+            from .relation import successor_warning, verify_relationship_edges  # noqa: PLC0415
+            try:
+                _subject_hex = _anchors_for_rel.statement_content_root(body).hex()
+            except Exception:
+                _subject_hex = None
+            r["lineage"] = verify_relationship_edges(
+                predicate.get("relationships"), related, subject_hex=_subject_hex)
+            _sw = successor_warning(predicate.get("relationships"), related, subject_hex=_subject_hex)
+            r["lineage"]["supersededByAttached"] = _sw
+            if _sw:
+                r["warnings"].append(f"lineage: {_sw}")
+            if r["lineage"]["lineage"] == "FAIL":
+                r["errors"].extend(r["lineage"]["errors"] or ["relation: lineage verification FAILED"])
+            # No-Fake (6-Linsen-Audit L2): mirror of the decision path — a REQUESTED lineage FAIL is
+            # visible in `ok`/`automation`, not only at the CLI exit code. FAIL->False, else None.
+            r["lineage_ok"] = False if r["lineage"]["lineage"] == "FAIL" else None
+
         # execution proof (honesty limit, warning not hard-fail).
         r["execution_proven"] = outcome_execution_proven(predicate)
         if r["execution_proven"] is False:
@@ -675,7 +709,8 @@ def verify_outcome_receipt(envelope: dict, public_key: bytes, *, strict: bool =
         # Finding 01 (additive, backward compatible): None (no trust_pack supplied, the pre-existing
         # default for every caller) passes exactly like every other optional check above; only an explicit
         # False (a trust_pack WAS supplied and the executor is not a trusted role member) fails ok.
-        and r["executor_role_trusted"] is not False)
+        and r["executor_role_trusted"] is not False
+        and r["lineage_ok"] is not False)
 
     # Finding 01 (additive): the STRICTER automation-safety verdict — never changes `ok` above. Outcome has
     # no separate trust-policy layer (yet); executor_role_trusted (the outcomeExecutors role gate) is the
@@ -684,6 +719,6 @@ def verify_outcome_receipt(envelope: dict, public_key: bytes, *, strict: bool =
     r["automation"] = automation_summary(r, required_checks={
         "crypto": "crypto_ok", "structure": "structure_ok", "policy": "executor_role_trusted",
         "references": ["decision_bound", "role_separation_ok", "audience_ok", "nonce_ok",
-                       "subject_derived_ok"],
+                       "subject_derived_ok", "lineage_ok"],
     })
     return r

{proofbundle-3.2.3 → proofbundle-3.3.0}/src/proofbundle/policy.py

@@ -105,7 +105,7 @@ def _pinned_key_forgeable(b64: str) -> bool:
 
 
 _TOP_KEYS = {"schema", "policy_id", "allowed_schema_versions", "allowed_issuers", "signature",
-             "merkle", "sd_jwt", "status", "assurance", "decision_receipt", "anchors",
+             "merkle", "sd_jwt", "status", "assurance", "decision_receipt", "anchors", "relations",
              "deploymentReady", "requiresIdentityOverlay",   # AP-2 §6.2 template metadata
              "valid_until",                                  # AP-2 §6.4 lifecycle expiry
              "valid_from",                                   # A-P0-2 §6 lifecycle not-before
@@ -135,6 +135,11 @@ def _parse_iso_utc(s):
 _ANCHORS_KEYS = {"require_anchor", "require_anchor_target", "allow_pending",
                  "trusted_tsa_roots", "bitcoin_block_headers", "trusted_tsa_policy_oids"}
 _ANCHOR_TARGETS = ("receipt", "preRegistration", "statement")
+# relation/v0.1 (EXPERIMENTAL, 3.3.0): the lineage policy section. relation_signer is a documented
+# FOLLOW-UP (the CLI --with-related contract is same-key today; a pinned-set needs per-target key
+# plumbing) — an unknown key here is fail-closed, so a future field cannot silently no-op.
+_RELATIONS_KEYS = {"require_relation_resolution", "reject_superseded"}
+_RELATION_NAMES = ("supersedes", "revises", "corrects", "retracts", "renews", "derivedFrom", "amends")
 _DECISION_KEYS = {"trusted_decision_makers", "allowed_decision_types", "allowed_verdicts",
                   "required_evidence_relations", "accepted_predicate_types", "require_policy_digest",
                   "require_external_anchor", "allow_pending", "require_audience", "require_nonce",
@@ -410,6 +415,19 @@ def load_policy(source: Union[str, dict]) -> dict:
                     for k, v in hdrs.items()):
                 raise PolicyError("anchors.bitcoin_block_headers must map a decimal height string to a "
                                   "64-char hex merkle root")
+    if "relations" in policy:
+        # relation/v0.1 lineage requirements (v0.2-gated like decision_receipt/anchors).
+        if policy.get("schema") != POLICY_SCHEMA_V0_2:
+            raise PolicyError("relations section requires schema proofbundle/trust-policy/v0.2")
+        rel = _require_dict(policy["relations"], "relations")
+        _reject_unknown(rel, _RELATIONS_KEYS, "relations")
+        if "require_relation_resolution" in rel:
+            rr = rel["require_relation_resolution"]
+            if (not isinstance(rr, list) or not rr
+                    or not all(isinstance(x, str) and x in _RELATION_NAMES for x in rr)):
+                raise PolicyError("relations.require_relation_resolution must be a non-empty list of "
+                                  f"relation names out of {list(_RELATION_NAMES)}")
+        _require_bool(rel, "reject_superseded", "relations")
     if "decision_receipt" in policy:
         dr = _require_dict(policy["decision_receipt"], "decision_receipt")
         _reject_unknown(dr, _DECISION_KEYS, "decision_receipt")
@@ -977,6 +995,14 @@ def explain_policy(policy: dict) -> list:
         if anc.get("allow_pending"):
             detail += " (pending accepted)"
         lines.append(f"external time anchor required ({detail})")
+    # relation/v0.1: the relations section is enforced by the decision verify path (a
+    # violation fails policy_ok, exit 3; the outcome-path policy gate is a documented follow-up) — listed here for explain⟺enforce parity, same rule as anchors.
+    rel = policy.get("relations") or {}
+    if rel.get("require_relation_resolution"):
+        lines.append("lineage relations must resolve (target attached + verified): "
+                     + ", ".join(rel["require_relation_resolution"]))
+    if rel.get("reject_superseded"):
+        lines.append("superseded receipt rejected (an attached, verified successor blocks automation)")
     dr = policy.get("decision_receipt") or {}
     if dr:
         active = [k for k in dr if dr.get(k)]