solo-builder-core 0.4.0__py3-none-any.whl

solo_builder/__init__.py

@@ -0,0 +1,5 @@
+"""Solo Builder: the Strix Labs Shipping Factory."""
+
+__version__ = "0.4.0"
+
+__all__ = ["__version__"]

solo_builder/_canonical.py

@@ -0,0 +1,59 @@
+"""Shared canonical-byte primitives — the single source of truth.
+
+Every hashed object in the Strix stack — ``record_hash`` (ADR-006),
+``signed_envelope`` payload hashes (ADR-005), Kafka wire bytes
+(ADR-007), CSV-export metadata (ADR-008), ``plan_hash`` (ADR-012),
+webhook signature payloads (ADR-013), AA-1 attestation payload bytes
+(ADR-015) — reaches through this module. One canonicalization
+contract; zero parallel serialization shapes.
+
+The byte contract is locked by ADR-005 §4:
+
+- JSON serialization.
+- Object keys sorted lexicographically.
+- No whitespace (separators ``,`` and ``:``).
+- ``ensure_ascii=False`` so Unicode survives byte-for-byte.
+- ``allow_nan=False`` — NaN and Infinity are forbidden because they
+  break determinism across implementations.
+
+Implementations in other languages (TypeScript ``@strixgov/sdk``)
+MUST produce byte-identical output for the same logical input.
+Cross-SDK byte-equivalence is asserted in every module's test suite
+that touches hashing, so divergence is caught immediately if it ever
+re-introduces itself.
+
+For module-level naming compatibility, ``evidence_store`` re-exports
+``hash_canonical`` as ``hash_payload`` so callers that import
+``from .evidence_store import hash_payload`` continue to work
+unchanged.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonicalize(obj: Any) -> bytes:
+    """Deterministic JSON bytes used for hashing and signing.
+
+    The single byte-contract chokepoint for the entire stack.
+    """
+
+    return json.dumps(
+        obj,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def hash_canonical(obj: Any) -> str:
+    """Lowercase SHA-256 hex digest of :func:`canonicalize` output."""
+
+    return hashlib.sha256(canonicalize(obj)).hexdigest()
+
+
+__all__ = ["canonicalize", "hash_canonical"]

solo_builder/_signing.py

@@ -0,0 +1,88 @@
+"""Shared Ed25519 attestation-signing policy for the local proof artifacts.
+
+The provenance chain, proof bundle, replay pack, and LinkedIn decision chain
+all sign with the same ``SOLO_ATTESTATION_PRIVATE_KEY``. They historically each
+inlined the same ``except Exception: return None`` block, which had one correct
+case and one latent gap:
+
+  * **No key configured** → return ``None`` (best-effort unsigned). Correct: the
+    hash chain still verifies; the artifact is simply not authorship-bound.
+
+  * **Key configured but signing/loading FAILS** (bad hex, wrong length, broken
+    crypto backend) → the old code *also* returned ``None``, silently producing
+    an unsigned artifact indistinguishable from "intentionally unsigned". A
+    downstream consumer could mistake a misconfigured-key run for a deliberate
+    best-effort one. That is the gap this module closes.
+
+Policy (single source of truth):
+
+  ============================  =================  ========================
+  key state                     strict mode off    strict mode on
+  ============================  =================  ========================
+  absent                        return None        raise SigningRequiredError
+  present but invalid/broken    raise SigningError raise SigningError
+  present and valid             return signature   return signature
+  ============================  =================  ========================
+
+Strict mode is opt-in via ``SOLO_REQUIRE_SIGNING`` ∈ {1,true,yes,on}. Trust
+surfaces that must never emit an unsigned artifact set it; local development
+leaves it unset and keeps the best-effort behavior.
+
+A configured-but-broken key ALWAYS raises, in both modes — a broken key is a
+fault, never a silent downgrade.
+"""
+
+from __future__ import annotations
+
+import os
+
+_ENV_KEY = "SOLO_ATTESTATION_PRIVATE_KEY"
+_ENV_REQUIRE = "SOLO_REQUIRE_SIGNING"
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+class SigningError(RuntimeError):
+    """A signing key was configured but signing could not be performed."""
+
+
+class SigningRequiredError(SigningError):
+    """Strict mode is on but no signing key is configured."""
+
+
+def signing_required() -> bool:
+    """True when ``SOLO_REQUIRE_SIGNING`` opts into fail-closed signing."""
+    return os.environ.get(_ENV_REQUIRE, "").strip().lower() in _TRUTHY
+
+
+def sign_attestation(payload: bytes, *, require: bool | None = None) -> str | None:
+    """Sign ``payload`` (raw bytes) with the configured Ed25519 key.
+
+    Returns the hex signature, or ``None`` when no key is configured and strict
+    mode is off. Raises :class:`SigningRequiredError` when no key is configured
+    and strict mode is on, and :class:`SigningError` when a key IS configured
+    but loading or signing fails. Callers pass pre-encoded bytes so the exact
+    signed-byte contract (e.g. ``head_hash.encode("ascii")``) stays unchanged.
+    """
+    strict = signing_required() if require is None else require
+    raw = os.environ.get(_ENV_KEY)
+
+    if not raw:
+        if strict:
+            raise SigningRequiredError(f"{_ENV_KEY} is not set but {_ENV_REQUIRE} requires a signed artifact")
+        return None
+
+    # A key is configured. From here, any failure is a real fault — never a
+    # silent unsigned artifact.
+    try:
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+            Ed25519PrivateKey,
+        )
+
+        key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex(raw))
+    except Exception as exc:  # noqa: BLE001 — surface the misconfiguration loudly
+        raise SigningError(f"{_ENV_KEY} is set but is not a valid Ed25519 private key (hex): {exc}") from exc
+
+    try:
+        return key.sign(payload).hex()
+    except Exception as exc:  # noqa: BLE001 — a configured key that cannot sign is a fault
+        raise SigningError(f"attestation signing failed: {exc}") from exc

solo_builder/acceptance_report.py

@@ -0,0 +1,445 @@
+"""Report-only acceptance-criterion results for an autonomous ship run.
+
+A ticket carries 3-7 acceptance tests (``ticket.py``). Until this module,
+nothing in the agent pipeline assessed them: ``review_code`` never saw them,
+and the execution loop runs the repo's own tests, which answer "does the
+generated code run?" and not "was the ticket delivered?". Those are different
+questions, and a run could finish green having answered only the first.
+
+This module reports, per criterion, what the review stage ASSERTED — and is
+deliberately incapable of being more than that:
+
+* **Report-only.** There is no ``ok`` / ``passed`` / ``all_met`` on
+  ``AcceptanceReport``, on purpose: a single green bit is exactly the collapse
+  this codebase's ProofState and verification ladder exist to prevent. The
+  report never feeds ``AgentResult.ok``, the trust engine, budget, deploy, or
+  any exit code; ``tests/test_acceptance_report.py`` pins that.
+* **Model assertion is not evidence.** Every asserted verdict carries
+  ``evidence_class="MODEL_ASSERTION"`` and an empty ``deterministic_evidence``.
+  ``MET`` here means "the reviewing model said so about code it was shown",
+  never "verified". A verdict may only be promoted by tying the criterion to
+  deterministic evidence (a named test's recorded result) or to a named human
+  decision (``human_decision``); neither exists yet, so both fields are carried
+  empty and named rather than omitted. Promotion is NOT built, and the claim
+  ceiling is structural: ``claim_ceiling == "MODEL_ASSERTION_ONLY"``.
+* **Absence is recorded, never fabricated.** A criterion the model did not
+  address, or addressed in a form this parser does not recognize, is
+  ``UNASSESSED`` — not ``UNCLEAR`` (the model said it could not tell) and never
+  a quiet pass. A run with no acceptance criteria, or no review output,
+  produces no report at all (``None``) rather than an empty green one.
+* **Never raises.** Parsing model prose is a best-effort read; a malformed
+  review degrades to ``UNASSESSED`` rows. It must not break a ship.
+
+Gate H: ``AcceptanceReport`` is type-disjoint from ``EvidenceRecord`` (no
+``record_hash`` / ``chain_seq`` / ``prev_hash`` / ``signature``); it is an
+unsigned measurement, never proof.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._canonical import hash_canonical
+
+SCHEMA = "acceptance_report_v1"
+SOURCE_STAGE = "review_code"
+GATING = "REPORT_ONLY"
+CLAIM_CEILING = "MODEL_ASSERTION_ONLY"
+
+ASSERTED_MET = "ASSERTED_MET"
+ASSERTED_NOT_MET = "ASSERTED_NOT_MET"
+ASSERTED_UNCLEAR = "ASSERTED_UNCLEAR"
+UNASSESSED = "UNASSESSED"
+#: A criterion BOUND to a named test whose recorded result decided it.
+EVIDENCE_PASSED = "EVIDENCE_PASSED"
+EVIDENCE_FAILED = "EVIDENCE_FAILED"
+#: A named person decided it, with a reason, on the record.
+HUMAN_MET = "HUMAN_MET"
+HUMAN_NOT_MET = "HUMAN_NOT_MET"
+
+STATES: tuple[str, ...] = (
+    ASSERTED_MET,
+    ASSERTED_NOT_MET,
+    ASSERTED_UNCLEAR,
+    UNASSESSED,
+    EVIDENCE_PASSED,
+    EVIDENCE_FAILED,
+    HUMAN_MET,
+    HUMAN_NOT_MET,
+)
+
+EVIDENCE_MODEL_ASSERTION = "MODEL_ASSERTION"
+EVIDENCE_NONE = "NONE"
+EVIDENCE_DETERMINISTIC_TEST = "DETERMINISTIC_TEST"
+EVIDENCE_HUMAN_DECISION = "HUMAN_DECISION"
+
+#: Strict order of evidence strength. A stronger class REPLACES a weaker verdict
+#: on the same criterion; a weaker one never overwrites a stronger one.
+EVIDENCE_RANK: dict[str, int] = {
+    EVIDENCE_NONE: 0,
+    EVIDENCE_MODEL_ASSERTION: 1,
+    EVIDENCE_DETERMINISTIC_TEST: 2,
+    EVIDENCE_HUMAN_DECISION: 3,
+}
+#: The report-level claim ceiling is the STRONGEST evidence class any row
+#: carries — it names what the report can at most be read as, never more.
+CLAIM_CEILING_BY_EVIDENCE: dict[str, str] = {
+    EVIDENCE_NONE: "MODEL_ASSERTION_ONLY",
+    EVIDENCE_MODEL_ASSERTION: "MODEL_ASSERTION_ONLY",
+    EVIDENCE_DETERMINISTIC_TEST: "DETERMINISTIC_TEST",
+    EVIDENCE_HUMAN_DECISION: "HUMAN_DECISION",
+}
+
+#: ``[test: tests/test_api.py::test_returns_200]`` or ``[test: test_returns_200]``
+#: inside a criterion's text binds it to a named test. Several bindings are
+#: allowed; ALL must pass for EVIDENCE_PASSED, ANY failure is EVIDENCE_FAILED.
+_BINDING = re.compile(r"\[\s*tests?\s*:\s*([^\]]+?)\s*\]", re.IGNORECASE)
+#: pytest ``-rA`` short-summary lines: ``PASSED tests/test_x.py::test_a``.
+_PYTEST_RESULT = re.compile(r"^(PASSED|FAILED|ERROR|XPASS|XFAIL|SKIPPED)\s+(\S+?)(?:\s+-\s.*)?$")
+
+DISCLAIMER = (
+    "Unsigned measurement, never proof. Verdicts are the reviewing model's opinion about code it was "
+    "shown; none is backed by deterministic evidence or a human decision, and none affects whether the "
+    "run succeeded."
+)
+
+#: Max characters of the model's stated basis kept per criterion. The report is
+#: surfaced in terminals, audit lines and JSON; an unbounded model paragraph
+#: does not belong in any of them.
+_BASIS_MAX = 300
+
+_HEADING = re.compile(r"^\W*acceptance\s+criteri(?:a|on)\s+assessment\b", re.IGNORECASE)
+#: ``1. MET — basis`` / ``2) NOT_MET: basis`` / ``- 3. UNCLEAR - basis``,
+#: tolerating markdown emphasis around the verdict word.
+_ROW = re.compile(
+    r"^\s*(?:[-*]\s*)?(?P<n>\d{1,3})\s*[.)]\s*[*_`]*\s*"
+    r"(?P<verdict>NOT[\s_-]*MET|UNCLEAR|MET)\b[*_`]*\s*[—–:\-]*\s*(?P<basis>.*)$",
+    re.IGNORECASE,
+)
+_NEXT_HEADING = re.compile(r"^\s*#{1,6}\s+\S")
+
+_VERDICT_STATE = {"MET": ASSERTED_MET, "NOT_MET": ASSERTED_NOT_MET, "UNCLEAR": ASSERTED_UNCLEAR}
+
+
+@dataclass(frozen=True)
+class CriterionResult:
+    index: int
+    text: str
+    state: str
+    basis: str = ""
+    evidence_class: str = EVIDENCE_NONE
+    #: Deterministic evidence ties (e.g. a named test's recorded result). Always
+    #: empty in v1 — carried so the absence is a stated fact, not an omission.
+    deterministic_evidence: tuple[str, ...] = ()
+    #: A named human decision on this criterion. None until one is recorded.
+    human_decision: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "index": self.index,
+            "text": self.text,
+            "state": self.state,
+            "basis": self.basis,
+            "evidence_class": self.evidence_class,
+            "deterministic_evidence": list(self.deterministic_evidence),
+            "human_decision": self.human_decision,
+        }
+
+
+@dataclass(frozen=True)
+class AcceptanceReport:
+    criteria: tuple[CriterionResult, ...] = field(default_factory=tuple)
+    source_stage: str = SOURCE_STAGE
+    gating: str = GATING
+    schema: str = SCHEMA
+    disclaimer: str = DISCLAIMER
+
+    @property
+    def claim_ceiling(self) -> str:
+        """Derived from the rows, never stored: the strongest evidence present."""
+        strongest = max(
+            (c.evidence_class for c in self.criteria),
+            key=lambda e: EVIDENCE_RANK.get(e, 0),
+            default=EVIDENCE_NONE,
+        )
+        return CLAIM_CEILING_BY_EVIDENCE.get(strongest, CLAIM_CEILING)
+
+    @property
+    def counts(self) -> dict[str, int]:
+        """Per-state tallies. Deliberately NOT collapsed into one verdict."""
+        tally = dict.fromkeys(STATES, 0)
+        for c in self.criteria:
+            tally[c.state] += 1
+        return tally
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema": self.schema,
+            "gating": self.gating,
+            "claim_ceiling": self.claim_ceiling,
+            "source_stage": self.source_stage,
+            "counts": self.counts,
+            "criteria": [c.to_dict() for c in self.criteria],
+            "disclaimer": self.disclaimer,
+        }
+
+    def format_text(self) -> str:
+        icons = {
+            ASSERTED_MET: "◻︎✓",
+            ASSERTED_NOT_MET: "◻︎✗",
+            ASSERTED_UNCLEAR: "◻︎?",
+            UNASSESSED: "◻︎–",
+            EVIDENCE_PASSED: "■✓",
+            EVIDENCE_FAILED: "■✗",
+            HUMAN_MET: "👤✓",
+            HUMAN_NOT_MET: "👤✗",
+        }
+        lines = [
+            "Acceptance criteria (report only; does not affect the run) — "
+            "◻︎ model-asserted, NOT verified · ■ bound to a recorded test result · 👤 named human decision:"
+        ]
+        for c in self.criteria:
+            tail = f" — {c.basis}" if c.basis else ""
+            if c.deterministic_evidence:
+                tail += f" [{', '.join(c.deterministic_evidence)}]"
+            if c.human_decision:
+                tail += f" [{c.human_decision}]"
+            lines.append(f"  {icons[c.state]} {c.index}. {c.state}: {c.text}{tail}")
+        n = self.counts
+        lines.append(
+            f"  asserted met {n[ASSERTED_MET]} · asserted not met {n[ASSERTED_NOT_MET]} · "
+            f"unclear {n[ASSERTED_UNCLEAR]} · unassessed {n[UNASSESSED]} · "
+            f"evidence passed {n[EVIDENCE_PASSED]} · evidence failed {n[EVIDENCE_FAILED]} · "
+            f"human met {n[HUMAN_MET]} · human not met {n[HUMAN_NOT_MET]}"
+        )
+        lines.append(f"  claim ceiling: {self.claim_ceiling}")
+        return "\n".join(lines)
+
+
+def _clean_basis(raw: str) -> str:
+    text = re.sub(r"[*_`]+", "", raw).strip(" \t-—–:")
+    text = re.sub(r"\s+", " ", text)
+    return text[: _BASIS_MAX - 1] + "…" if len(text) > _BASIS_MAX else text
+
+
+def parse_review_assessment(review_text: str, count: int) -> dict[int, tuple[str, str]]:
+    """Read ``{criterion index: (state, basis)}`` from a review's assessment section.
+
+    Only rows inside the "Acceptance Criteria Assessment" section count, indices
+    must be within ``1..count`` (anything else is ignored, never remapped), and
+    the FIRST row for an index wins — a later contradictory row must not
+    silently overwrite an earlier verdict. Unrecognized shapes yield nothing.
+    """
+    found: dict[int, tuple[str, str]] = {}
+    in_section = False
+    for line in review_text.splitlines():
+        if not in_section:
+            if _HEADING.match(line.strip().lstrip("#").strip()):
+                in_section = True
+            continue
+        if _NEXT_HEADING.match(line) and not _HEADING.match(line.strip().lstrip("#").strip()):
+            break
+        m = _ROW.match(line)
+        if not m:
+            continue
+        index = int(m.group("n"))
+        if not 1 <= index <= count or index in found:
+            continue
+        verdict = re.sub(r"[\s-]+", "_", m.group("verdict").upper())
+        state = _VERDICT_STATE.get(verdict)
+        if state is None:
+            continue
+        found[index] = (state, _clean_basis(m.group("basis")))
+    return found
+
+
+def build_acceptance_report(criteria: Sequence[str], review_text: str | None) -> AcceptanceReport | None:
+    """The report for a run, or None when there is nothing honest to report.
+
+    None when the ticket has no criteria or the review stage produced no
+    output: an empty report would read as "nothing failed".
+    """
+    texts = [c.strip() for c in criteria if c and c.strip()]
+    if not texts or not review_text or not review_text.strip():
+        return None
+    try:
+        found = parse_review_assessment(review_text, len(texts))
+    except Exception:  # noqa: BLE001 — a parse defect must degrade to UNASSESSED, never break a ship
+        found = {}
+    rows: list[CriterionResult] = []
+    for i, text in enumerate(texts, start=1):
+        if i in found:
+            state, basis = found[i]
+            rows.append(
+                CriterionResult(
+                    index=i, text=text, state=state, basis=basis, evidence_class=EVIDENCE_MODEL_ASSERTION
+                )
+            )
+        else:
+            rows.append(CriterionResult(index=i, text=text, state=UNASSESSED))
+    return AcceptanceReport(criteria=tuple(rows))
+
+
+# ---------------------------------------------------------------------------
+# Promotion beyond a model assertion: deterministic test evidence, human decision
+# ---------------------------------------------------------------------------
+
+
+def bound_tests(criterion_text: str) -> tuple[str, ...]:
+    """The test ids a criterion names with ``[test: ...]``, in order, de-duplicated."""
+    return tuple(dict.fromkeys(m.strip() for m in _BINDING.findall(criterion_text) if m.strip()))
+
+
+def parse_pytest_results(stdout: str) -> dict[str, str]:
+    """``{nodeid: PASSED|FAILED|...}`` from pytest ``-rA`` short-summary lines.
+
+    Only lines in that exact shape count; a FAILED anywhere else in the output
+    (a traceback header, a docstring) is not a result. The LAST line for a
+    nodeid wins, since a re-run inside one capture reports the final state.
+    """
+    results: dict[str, str] = {}
+    for line in stdout.splitlines():
+        m = _PYTEST_RESULT.match(line.strip())
+        if m:
+            results[m.group(2)] = m.group(1)
+    return results
+
+
+def _match_binding(binding: str, results: Mapping[str, str]) -> list[str]:
+    """Nodeids a binding names: exact, ``::``-suffix, or bare function name."""
+    exact = [n for n in results if n == binding]
+    if exact:
+        return exact
+    suffix = [n for n in results if n.endswith("::" + binding) or n.endswith("/" + binding)]
+    if suffix:
+        return suffix
+    return [n for n in results if n.split("::")[-1] == binding]
+
+
+def bind_deterministic_evidence(report: AcceptanceReport, results: Mapping[str, str]) -> AcceptanceReport:
+    """Replace model assertions with the recorded result of each bound test.
+
+    A criterion with no binding is untouched. A binding that names no test in
+    ``results`` is recorded in the basis as unresolved and the row keeps its
+    weaker verdict — a missing test is never read as a pass. A human decision
+    already on the row outranks test evidence and is left alone.
+    """
+    rows: list[CriterionResult] = []
+    for c in report.criteria:
+        bindings = bound_tests(c.text)
+        if not bindings or c.evidence_class == EVIDENCE_HUMAN_DECISION:
+            rows.append(c)
+            continue
+        evidence: list[str] = []
+        unresolved: list[str] = []
+        statuses: list[str] = []
+        for b in bindings:
+            matched = _match_binding(b, results)
+            if not matched:
+                unresolved.append(b)
+                continue
+            for nodeid in matched:
+                statuses.append(results[nodeid])
+                evidence.append(f"pytest:{nodeid}:{results[nodeid]}")
+        if not evidence:
+            rows.append(
+                dataclasses.replace(
+                    c,
+                    basis=(c.basis + " · " if c.basis else "")
+                    + f"bound test(s) not found in results: {', '.join(unresolved)}",
+                )
+            )
+            continue
+        failed = any(st in ("FAILED", "ERROR") for st in statuses)
+        passed = all(st in ("PASSED", "XPASS") for st in statuses)
+        if failed:
+            state = EVIDENCE_FAILED
+        elif passed and not unresolved:
+            state = EVIDENCE_PASSED
+        else:
+            # Skipped/xfail or a partly-unresolved binding set: evidence exists but
+            # does not establish the criterion either way. Keep the weaker verdict.
+            rows.append(
+                dataclasses.replace(
+                    c,
+                    basis=(c.basis + " · " if c.basis else "")
+                    + "bound tests inconclusive: "
+                    + ", ".join(evidence + [f"{u}:NOT_FOUND" for u in unresolved]),
+                )
+            )
+            continue
+        rows.append(
+            dataclasses.replace(
+                c,
+                state=state,
+                evidence_class=EVIDENCE_DETERMINISTIC_TEST,
+                deterministic_evidence=tuple(evidence),
+                basis=(c.basis + " · " if c.basis else "") + "decided by recorded test result",
+            )
+        )
+    return dataclasses.replace(report, criteria=tuple(rows))
+
+
+def apply_human_decision(
+    report: AcceptanceReport,
+    index: int,
+    *,
+    met: bool,
+    decided_by: str,
+    reason: str,
+    decided_at: str,
+) -> AcceptanceReport:
+    """Record a NAMED person's decision on one criterion. Outranks every other
+    evidence class; refuses an anonymous or unexplained decision outright."""
+    if not decided_by.strip() or not reason.strip():
+        raise ValueError("a human decision needs both a named decider and a reason")
+    if not any(c.index == index for c in report.criteria):
+        raise ValueError(f"no criterion {index}; the report has {len(report.criteria)}")
+    rows = [
+        dataclasses.replace(
+            c,
+            state=HUMAN_MET if met else HUMAN_NOT_MET,
+            evidence_class=EVIDENCE_HUMAN_DECISION,
+            human_decision=f"{decided_by.strip()} @ {decided_at}: {reason.strip()}",
+        )
+        if c.index == index
+        else c
+        for c in report.criteria
+    ]
+    return dataclasses.replace(report, criteria=tuple(rows))
+
+
+def report_digest(report: AcceptanceReport) -> str:
+    """Content address of the report: sha256 over its canonical document.
+
+    Computed from ``to_dict()``, i.e. from the ROWS — ``claim_ceiling`` and
+    ``counts`` in the document are derived, so a planted ceiling in a stored
+    file cannot change the digest of the report it was loaded into. Used by
+    ``ship_attestation`` to bind WHICH report accompanied a ship; it says
+    nothing about whether the report is right."""
+
+    return hash_canonical(report.to_dict())
+
+
+def report_from_dict(data: Mapping[str, Any]) -> AcceptanceReport:
+    """Rebuild a report from ``to_dict()`` output; a stored ``claim_ceiling`` is
+    ignored and re-derived from the rows (a planted ceiling is never trusted)."""
+    if data.get("schema") != SCHEMA:
+        raise ValueError(f"not an {SCHEMA} document")
+    rows = tuple(
+        CriterionResult(
+            index=int(c["index"]),
+            text=str(c["text"]),
+            state=str(c["state"]) if c.get("state") in STATES else UNASSESSED,
+            basis=str(c.get("basis", "")),
+            evidence_class=str(c.get("evidence_class", EVIDENCE_NONE)),
+            deterministic_evidence=tuple(str(x) for x in c.get("deterministic_evidence", ())),
+            human_decision=(str(c["human_decision"]) if c.get("human_decision") else None),
+        )
+        for c in data.get("criteria", [])
+    )
+    return AcceptanceReport(criteria=rows, source_stage=str(data.get("source_stage", SOURCE_STAGE)))