decisioncontrol 0.1.0__py3-none-any.whl

decisioncontrol/__init__.py

@@ -0,0 +1,15 @@
+"""Policy-constrained agent actions with durable local approval and evidence."""
+
+__version__ = "0.1.0"
+
+from .evidence import export_record, replay
+from .evaluation import EvaluationCase, evaluate_cases, load_cases, replay_evaluation, write_evaluation
+from .models import DecisionError, Evaluation, Recommendation, RoutingPolicy, StateError, Status, Ticket, Verdict
+from .policy import evaluate
+from .store import TicketStore
+
+__all__ = [
+    "DecisionError", "Evaluation", "Recommendation", "RoutingPolicy", "StateError",
+    "Status", "Ticket", "TicketStore", "Verdict", "evaluate", "export_record", "replay",
+    "EvaluationCase", "evaluate_cases", "load_cases", "replay_evaluation", "write_evaluation",
+]

decisioncontrol/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

decisioncontrol/_outputs.py

@@ -0,0 +1,28 @@
+"""Publish complete artifacts from staging directories on the same filesystem."""
+from contextlib import contextmanager
+import os
+from pathlib import Path
+import tempfile
+from typing import Iterator
+
+from .models import DecisionError
+
+
+def _check_target(target: Path, directory: bool) -> None:
+    if target.is_symlink() or (target.exists() and (
+            not directory or not target.is_dir() or any(target.iterdir()))):
+        raise DecisionError("output must be a new file or a new or empty directory")
+
+
+@contextmanager
+def staged_output(out: str | Path, *, directory: bool = True) -> Iterator[Path]:
+    target = Path(out)
+    _check_target(target, directory)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=f".{target.name}-", dir=target.parent) as temporary:
+        staging = Path(temporary) / "output"
+        if directory:
+            staging.mkdir()
+        yield staging
+        _check_target(target, directory)
+        os.replace(staging, target)

decisioncontrol/cli.py

@@ -0,0 +1,116 @@
+"""JSON command line interface for trusted local operators."""
+import argparse
+import json
+import sqlite3
+import sys
+from pathlib import Path
+
+from ._outputs import staged_output
+from .evidence import RecordMismatch, export_record, replay
+from .evaluation import evaluate_cases, load_cases, replay_evaluation, write_evaluation
+from .models import DecisionError, Recommendation, RoutingPolicy, StateError
+from .store import TicketStore
+
+
+def _json_file(path):
+    with Path(path).open(encoding="utf-8") as stream:
+        return json.load(stream)
+
+
+def _parser():
+    parser = argparse.ArgumentParser(prog="decision-control")
+    parser.add_argument("--db", help="SQLite database path (required for storage commands)")
+    commands = parser.add_subparsers(dest="command", required=True)
+    create = commands.add_parser("ticket-create")
+    create.add_argument("--ticket-id", required=True)
+    create.add_argument("--department", required=True)
+    for name in ("ticket-show", "show", "execute"):
+        commands.add_parser(name).add_argument("id")
+    submit = commands.add_parser("submit")
+    submit.add_argument("--proposal", required=True)
+    submit.add_argument("--policy", required=True)
+    submit.add_argument("--proposed-by", required=True)
+    commands.add_parser("pending")
+    for name in ("approve", "reject", "cancel"):
+        review = commands.add_parser(name)
+        review.add_argument("id")
+        review.add_argument("--reviewer", required=True)
+        review.add_argument("--note", default="", required=name == "cancel")
+    export = commands.add_parser("export")
+    export.add_argument("id")
+    export.add_argument("--out")
+    commands.add_parser("replay").add_argument("--record", required=True)
+    commands.add_parser("demo").add_argument("--out", required=True)
+    evaluation = commands.add_parser("evaluate", help="score supplied labeled recommendations; execute nothing")
+    evaluation.add_argument("--cases", required=True, help="labeled JSON Lines cases")
+    evaluation.add_argument("--policy", required=True)
+    evaluation.add_argument("--require", help="metric/support gates; omitted means UNGATED")
+    evaluation.add_argument("--out", required=True, help="new or empty output directory")
+    commands.add_parser("replay-evaluation").add_argument("--record", required=True)
+    return parser
+
+
+def _run(args):
+    if args.command == "replay":
+        return replay(_json_file(args.record))
+    if args.command == "demo":
+        from .demo import run_demo
+        return run_demo(args.out)
+    if args.command == "evaluate":
+        requirements = _json_file(args.require) if args.require else None
+        report = evaluate_cases(load_cases(args.cases), RoutingPolicy.from_dict(_json_file(args.policy)), requirements)
+        return write_evaluation(report, args.out)
+    if args.command == "replay-evaluation":
+        return replay_evaluation(_json_file(args.record))
+    if not args.db:
+        raise DecisionError("--db is required for storage commands")
+    with TicketStore(args.db) as store:
+        if args.command == "ticket-create":
+            return store.create_ticket(args.ticket_id, args.department).to_dict()
+        if args.command == "ticket-show":
+            return store.get_ticket(args.id).to_dict()
+        if args.command == "submit":
+            return store.submit(Recommendation.from_dict(_json_file(args.proposal)),
+                                RoutingPolicy.from_dict(_json_file(args.policy)), args.proposed_by)
+        if args.command == "pending":
+            return store.pending()
+        if args.command == "show":
+            return store.get(args.id)
+        if args.command in ("approve", "reject", "cancel"):
+            return getattr(store, args.command)(args.id, args.reviewer, args.note)
+        if args.command == "execute":
+            return store.execute(args.id)
+        if args.command == "export":
+            envelope = export_record(store.get(args.id))
+            if args.out:
+                with staged_output(args.out, directory=False) as staging:
+                    with staging.open("x", encoding="utf-8") as stream:
+                        json.dump(envelope, stream, indent=2, allow_nan=False)
+                        stream.write("\n")
+            return envelope
+    raise DecisionError("unknown command")
+
+
+def main(argv=None):
+    """Return 0, invalid input/IO 2, or blocked lifecycle/evaluation gate 1."""
+    parser = _parser()
+    try:
+        args = parser.parse_args(argv)
+        result = _run(args)
+    except RecordMismatch as error:
+        print(f"decision-control: {error}", file=sys.stderr)
+        return 1 if args.command in ("replay", "replay-evaluation") else 2
+    except StateError as error:
+        print(f"decision-control: {error}", file=sys.stderr)
+        return 1
+    except (DecisionError, OSError, UnicodeError, json.JSONDecodeError, sqlite3.Error) as error:
+        print(f"decision-control: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, indent=2, allow_nan=False))
+    if args.command == "pending" and result.skipped:
+        for row in result.skipped:
+            print(f"decision-control: skipped corrupt decision {row['id']}: {row['error']}", file=sys.stderr)
+        return 1
+    if args.command == "execute" and result["status"] == "STALE":
+        return 1
+    return 1 if args.command == "evaluate" and result["report"]["disposition"] == "FAIL" else 0

decisioncontrol/demo.py

@@ -0,0 +1,70 @@
+"""Credential-free demonstration: hand-authored inputs, real SQLite mutations."""
+import json
+from pathlib import Path
+
+from ._outputs import staged_output
+from .evidence import export_record, replay
+from .models import Recommendation, RoutingPolicy
+from .store import TicketStore
+
+
+def _save(path, value):
+    with path.open("x", encoding="utf-8") as stream:
+        json.dump(value, stream, indent=2, allow_nan=False)
+        stream.write("\n")
+
+
+def run_demo(out):
+    with staged_output(out) as staging:
+        return _build_demo(staging, Path(out))
+
+
+def _build_demo(directory, published):
+    policy = RoutingPolicy("demo-policy-1", ("support", "engineering"),
+                           ("engineering",), ("local-reviewer",), 0.8)
+    cases = (("allow", "support", 0.95), ("review", "engineering", 0.95),
+             ("deny", "finance", 0.99), ("abstain", "support", None))
+    db = directory / "tickets.sqlite3"
+    ids = {}
+    _save(directory / "policy.json", policy.to_dict())
+    with TicketStore(db) as store:
+        for name, destination, probability in cases:
+            store.create_ticket(f"demo-{name}", "intake")
+            proposal = Recommendation("reassign_ticket", f"demo-{name}", destination,
+                                      probability, "hand-authored-demo", "routing-question-1")
+            _save(directory / f"proposal-{name}.json", proposal.to_dict())
+            ids[name] = store.submit(proposal, policy, proposed_by="local-proposer")["id"]
+        store.execute(ids["allow"])
+    # Review is durable: close and reopen before approval by a trusted operator.
+    with TicketStore(db) as store:
+        pending_before_approval = [record["id"] for record in store.pending()]
+        store.approve(ids["review"], "local-reviewer", "Reviewed destination and frozen policy")
+        first = store.execute(ids["review"])
+        repeated = store.execute(ids["review"])
+        replay_results = {}
+        records = {}
+        tickets = {}
+        for name, _, _ in cases:
+            record = store.get(ids[name])
+            envelope = export_record(record)
+            record_path = directory / f"record-{name}.json"
+            _save(record_path, envelope)
+            # Replay the serialized evidence, not just the in-memory envelope.
+            with record_path.open(encoding="utf-8") as stream:
+                replay_results[name] = replay(json.load(stream))
+            records[name] = {"id": record["id"], "verdict": record["evaluation"]["verdict"],
+                             "status": record["status"], "file": str(published / record_path.name)}
+            tickets[name] = store.get_ticket(f"demo-{name}").to_dict()
+    summary = {
+        "database": str(published / db.name),
+        "inputs": "Hand-authored probabilities and recommendations; no model or provider was called.",
+        "execution_boundary": "Actual local SQLite queue reassignment only; no external action.",
+        "reopened_before_approval": True,
+        "pending_before_approval": pending_before_approval,
+        "repeat_execution_same_record": first == repeated,
+        "decisions": records,
+        "tickets": tickets,
+        "replay": replay_results,
+    }
+    _save(directory / "summary.json", summary)
+    return summary

decisioncontrol/evaluation.py

@@ -0,0 +1,281 @@
+"""Offline policy evaluation on independently labeled, supplied recommendations.
+
+No model is called and no action is executed. Wilson intervals assume independent
+Bernoulli observations; synthetic or correlated cases do not validate deployment.
+"""
+
+from dataclasses import dataclass
+import hashlib
+import json
+import math
+from pathlib import Path
+
+from ._outputs import staged_output
+from .evidence import RecordMismatch, _canonical
+from .models import DecisionError, Recommendation, RoutingPolicy, Ticket, Verdict, _fields, _probability, _text
+from .policy import evaluate
+
+
+METRICS = (
+    "auto_allow_rate", "unsafe_auto_allow_rate", "auto_route_error_rate",
+    "review_rate", "abstain_rate", "deny_rate", "required_review_recall",
+    "review_precision", "incorrect_approval_rate", "review_observation_rate",
+)
+
+
+@dataclass(frozen=True)
+class EvaluationCase:
+    id: str
+    ticket: Ticket
+    recommendation: Recommendation
+    safe_to_execute: bool
+    requires_review: bool
+    correct_destination: str
+    review_outcome: str | None = None
+
+    def __post_init__(self):
+        _text(self.id, "case id")
+        if not isinstance(self.ticket, Ticket) or not isinstance(self.recommendation, Recommendation):
+            raise DecisionError("case requires a Ticket and a Recommendation")
+        if type(self.safe_to_execute) is not bool or type(self.requires_review) is not bool:
+            raise DecisionError("safe_to_execute and requires_review labels must be booleans")
+        _text(self.correct_destination, "correct_destination")
+        if self.review_outcome is not None and self.review_outcome not in ("APPROVED", "REJECTED"):
+            raise DecisionError("review_outcome must be APPROVED, REJECTED, or null")
+
+    def to_dict(self):
+        return {"id": self.id, "ticket": self.ticket.to_dict(),
+                "recommendation": self.recommendation.to_dict(),
+                "labels": {"safe_to_execute": self.safe_to_execute,
+                           "requires_review": self.requires_review,
+                           "correct_destination": self.correct_destination},
+                "review_outcome": self.review_outcome}
+
+    @classmethod
+    def from_dict(cls, value):
+        raw = _fields(value, {"id", "ticket", "recommendation", "labels"}, {"review_outcome"})
+        labels = _fields(raw["labels"], {"safe_to_execute", "requires_review", "correct_destination"})
+        return cls(raw["id"], Ticket.from_dict(raw["ticket"]),
+                   Recommendation.from_dict(raw["recommendation"]), **labels,
+                   review_outcome=raw.get("review_outcome"))
+
+
+def load_cases(path):
+    """Load JSON Lines, rejecting malformed cases instead of excluding them from scores."""
+    cases = []
+    with Path(path).open(encoding="utf-8") as stream:
+        for line_number, line in enumerate(stream, 1):
+            if not line.strip():
+                continue
+            try:
+                cases.append(EvaluationCase.from_dict(json.loads(line)))
+            except (DecisionError, json.JSONDecodeError) as error:
+                raise DecisionError(f"{path}:{line_number}: {error}") from error
+    return cases
+
+
+def _rate(numerator, denominator):
+    if denominator == 0:
+        return {"numerator": numerator, "denominator": 0, "value": None, "lower": None, "upper": None}
+    value = numerator / denominator
+    z = 1.959963984540054
+    z_squared = z * z
+    divisor = 1 + z_squared / denominator
+    center = (value + z_squared / (2 * denominator)) / divisor
+    half = z * math.sqrt(value * (1 - value) / denominator + z_squared / (4 * denominator ** 2)) / divisor
+    return {"numerator": numerator, "denominator": denominator, "value": value,
+            "lower": 0.0 if numerator == 0 else max(0.0, center - half),
+            "upper": 1.0 if numerator == denominator else min(1.0, center + half)}
+
+
+def _positive_int(value, name):
+    if type(value) is not int or value < 1:
+        raise DecisionError(f"{name} must be a positive integer")
+    return value
+
+
+def _requirements(value):
+    if value is None:
+        return None
+    raw = _fields(value, {"min_cases", "bounds"})
+    minimum = _positive_int(raw["min_cases"], "min_cases")
+    if not isinstance(raw["bounds"], dict) or not raw["bounds"]:
+        raise DecisionError("bounds must contain at least one metric requirement")
+    bounds = {}
+    for name, bound in raw["bounds"].items():
+        if name not in METRICS:
+            raise DecisionError(f"unknown metric: {name}")
+        bound = _fields(bound, (), {"min", "max", "statistic", "min_denominator"})
+        if not ("min" in bound or "max" in bound):
+            raise DecisionError(f"{name} needs a min or max bound")
+        statistic = bound.get("statistic", "value")
+        if statistic not in ("value", "lower", "upper"):
+            raise DecisionError(f"{name}: statistic must be value, lower, or upper")
+        normalized = {"statistic": statistic,
+                      "min_denominator": _positive_int(bound.get("min_denominator", 1), "min_denominator")}
+        for side in ("min", "max"):
+            if side in bound:
+                normalized[side] = _probability(bound[side], f"{name}.{side}")
+        if normalized.get("min", 0) > normalized.get("max", 1):
+            raise DecisionError(f"{name}: min exceeds max")
+        bounds[name] = normalized
+    return {"min_cases": minimum, "bounds": bounds}
+
+
+def _gates(metrics, count, requirements):
+    if requirements is None:
+        return []
+    enough_cases = count >= requirements["min_cases"]
+    gates = [{"metric": "cases", "statistic": "value", "observed": count,
+              "min": requirements["min_cases"], "max": None,
+              "denominator": count, "min_denominator": requirements["min_cases"],
+              "passed": enough_cases, "reason": None if enough_cases else "insufficient_cases"}]
+    for name, bound in sorted(requirements["bounds"].items()):
+        metric = metrics[name]
+        observed = metric[bound["statistic"]]
+        reason = None
+        if observed is None:
+            reason = "unmeasured"
+        elif metric["denominator"] < bound["min_denominator"]:
+            reason = "insufficient_denominator"
+        elif observed < bound.get("min", 0) or observed > bound.get("max", 1):
+            reason = "outside_bound"
+        gates.append({"metric": name, "statistic": bound["statistic"], "observed": observed,
+                      "min": bound.get("min"), "max": bound.get("max"),
+                      "denominator": metric["denominator"], "min_denominator": bound["min_denominator"],
+                      "passed": reason is None, "reason": reason})
+    return gates
+
+
+def evaluate_cases(cases, policy: RoutingPolicy, requirements=None) -> dict:
+    """Evaluate policy recommendations, not real execution or unauthenticated reviewers.
+
+    Unsafe automatic allowance means ALLOW despite a negative safety label or a
+    required-review label. Incorrect approval means an observed APPROVED outcome
+    on a REVIEW case with a negative safety label or an incorrect destination.
+    """
+    if not isinstance(policy, RoutingPolicy):
+        raise DecisionError("policy must be a RoutingPolicy")
+    requirements = _requirements(requirements)
+    seen = set()
+    results = []
+    verdict_counts = {verdict: 0 for verdict in Verdict}
+    unsafe = wrong_route = required = reviewed_required = observed_reviews = approvals = incorrect_approvals = 0
+    for case in cases:
+        if not isinstance(case, EvaluationCase):
+            raise DecisionError("cases must contain EvaluationCase instances")
+        if case.id in seen:
+            raise DecisionError(f"duplicate case id: {case.id}")
+        seen.add(case.id)
+        evaluation = evaluate(case.recommendation, case.ticket, policy)
+        verdict = evaluation.verdict
+        verdict_counts[verdict] += 1
+        automatic = verdict == Verdict.ALLOW
+        reviewing = verdict == Verdict.REVIEW
+        incorrect_destination = case.recommendation.destination != case.correct_destination
+        auto_unsafe = automatic and (not case.safe_to_execute or case.requires_review)
+        auto_incorrect = automatic and incorrect_destination
+        observed = reviewing and case.review_outcome is not None
+        approved = reviewing and case.review_outcome == "APPROVED"
+        approval_incorrect = approved and (not case.safe_to_execute or incorrect_destination)
+        unsafe += auto_unsafe
+        wrong_route += auto_incorrect
+        required += case.requires_review
+        reviewed_required += reviewing and case.requires_review
+        observed_reviews += observed
+        approvals += approved
+        incorrect_approvals += approval_incorrect
+        results.append({"case": case.to_dict(), "evaluation": evaluation.to_dict(),
+                        "auto_allow_unsafe": auto_unsafe, "auto_route_incorrect": auto_incorrect,
+                        "approval_incorrect": approval_incorrect if approved else None})
+    count = len(results)
+    if count == 0:
+        raise DecisionError("evaluation requires at least one labeled case")
+    allowed = verdict_counts[Verdict.ALLOW]
+    reviewed = verdict_counts[Verdict.REVIEW]
+    metrics = {
+        "auto_allow_rate": _rate(allowed, count),
+        "unsafe_auto_allow_rate": _rate(unsafe, allowed),
+        "auto_route_error_rate": _rate(wrong_route, allowed),
+        "review_rate": _rate(reviewed, count),
+        "abstain_rate": _rate(verdict_counts[Verdict.ABSTAIN], count),
+        "deny_rate": _rate(verdict_counts[Verdict.DENY], count),
+        "required_review_recall": _rate(reviewed_required, required),
+        "review_precision": _rate(reviewed_required, reviewed),
+        "incorrect_approval_rate": _rate(incorrect_approvals, approvals),
+        "review_observation_rate": _rate(observed_reviews, reviewed),
+    }
+    gates = _gates(metrics, count, requirements)
+    disposition = "UNGATED" if requirements is None else ("PASS" if all(g["passed"] for g in gates) else "FAIL")
+    return {"schema_version": 1, "kind": "policy_evaluation", "source": "supplied_recommendations",
+            "cases": count, "confidence_level": 0.95, "policy": policy.to_dict(),
+            "requirements": requirements, "metrics": metrics, "gates": gates,
+            "disposition": disposition, "case_results": results}
+
+
+def replay_evaluation(envelope: dict) -> dict:
+    """Check the complete report and independently recompute metrics/gates from frozen cases."""
+    raw = _fields(envelope, {"report", "sha256"})
+    report = raw["report"]
+    digest = raw["sha256"]
+    if (not isinstance(digest, str) or len(digest) != 64
+            or any(character not in "0123456789abcdef" for character in digest)):
+        raise DecisionError("sha256 must be a lowercase hexadecimal SHA-256 digest")
+    if hashlib.sha256(_canonical(report)).hexdigest() != digest:
+        raise RecordMismatch("evaluation checksum mismatch")
+    report = _fields(report, {"schema_version", "kind", "source", "cases", "confidence_level", "policy",
+                              "requirements", "metrics", "gates", "disposition", "case_results"})
+    if type(report["schema_version"]) is not int or report["schema_version"] != 1:
+        raise DecisionError("unsupported evaluation schema_version")
+    if not isinstance(report["case_results"], list):
+        raise DecisionError("case_results must be a list")
+    cases = []
+    for row in report["case_results"]:
+        row = _fields(row, {"case", "evaluation", "auto_allow_unsafe", "auto_route_incorrect", "approval_incorrect"})
+        cases.append(EvaluationCase.from_dict(row["case"]))
+    recomputed = evaluate_cases(cases, RoutingPolicy.from_dict(report["policy"]), report["requirements"])
+    if _canonical(recomputed) != _canonical(report):
+        raise RecordMismatch("evaluation report disagrees with its frozen cases, policy, or requirements")
+    return {"valid": True, "cases": recomputed["cases"], "disposition": recomputed["disposition"]}
+
+
+def _number(value):
+    return "unmeasured" if value is None else f"{value:.6g}"
+
+
+def render_evaluation(report, digest):
+    lines = [f"# Policy evaluation: {report['disposition']}", "",
+             f"- Labeled cases: {report['cases']}", f"- Canonical report SHA-256: `{digest}`",
+             "- Supplied recommendations only; no model call or action execution.", "",
+             "| Metric | Numerator | Denominator | Estimate | 95% lower | 95% upper |",
+             "| --- | ---: | ---: | ---: | ---: | ---: |"]
+    for name, metric in report["metrics"].items():
+        lines.append(f"| {name} | {metric['numerator']} | {metric['denominator']} | "
+                     f"{_number(metric['value'])} | {_number(metric['lower'])} | {_number(metric['upper'])} |")
+    if report["gates"]:
+        lines.extend(["", "| Gate | Statistic | Observed | Bounds | Minimum support | Result |",
+                      "| --- | --- | ---: | --- | ---: | --- |"])
+        for gate in report["gates"]:
+            bounds = ", ".join(f"{side} {gate[side]}" for side in ("min", "max") if gate[side] is not None)
+            result = "PASS" if gate["passed"] else f"FAIL ({gate['reason']})"
+            lines.append(f"| {gate['metric']} | {gate['statistic']} | {_number(gate['observed'])} | "
+                         f"{bounds} | {gate['min_denominator']} | {result} |")
+    lines.extend(["", "Wilson intervals assume independent observations. Hand-authored, correlated or",
+                  "unrepresentative cases do not establish deployed safety or provider quality.",
+                  "Unknown denominators are unmeasured, never zero-error proof. Point-estimate",
+                  "bounds are not confidence guarantees; use upper/lower bounds and enough support.", ""])
+    return "\n".join(lines)
+
+
+def write_evaluation(report: dict, out) -> dict:
+    """Preserve a complete, replayable report in a new or empty output directory."""
+    digest = hashlib.sha256(_canonical(report)).hexdigest()
+    envelope = {"report": report, "sha256": digest}
+    replay_evaluation(envelope)
+    with staged_output(out) as directory:
+        with (directory / "evaluation.json").open("x", encoding="utf-8") as stream:
+            json.dump(envelope, stream, indent=2, ensure_ascii=False, allow_nan=False)
+            stream.write("\n")
+        with (directory / "EVALUATION.md").open("x", encoding="utf-8") as stream:
+            stream.write(render_evaluation(report, digest))
+    return envelope

decisioncontrol/evidence.py

@@ -0,0 +1,147 @@
+"""Portable evidence replay without a model call or an action side effect.
+
+A checksum detects corruption, not a malicious writer who can replace the checksum.
+"""
+
+from collections.abc import Mapping
+from datetime import datetime, timedelta
+import hashlib
+import json
+from uuid import UUID
+
+from .models import DecisionError, Evaluation, Recommendation, RoutingPolicy, Status, Ticket, _fields, _text
+from .policy import INITIAL_STATUS, evaluate
+
+
+class RecordMismatch(DecisionError):
+    """A checksum or recomputed decision disagrees with recorded evidence."""
+
+
+RECORD_FIELDS = {"schema_version", "id", "created_at", "recommendation", "ticket", "policy",
+                 "evaluation", "status", "review", "result", "events"}
+
+
+def _canonical(value):
+    try:
+        return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False,
+                          allow_nan=False).encode("utf-8")
+    except (TypeError, ValueError) as error:
+        raise DecisionError(f"evidence must be finite JSON: {error}") from error
+
+
+def _timestamp(value):
+    _text(value, "timestamp")
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as error:
+        raise DecisionError("timestamp must be ISO 8601 UTC") from error
+    if parsed.tzinfo is None or parsed.utcoffset() != timedelta(0):
+        raise DecisionError("timestamp must be ISO 8601 UTC")
+    return value
+
+
+def _validate_record(record):
+    schema = record.get("schema_version") if isinstance(record, Mapping) else None
+    fields = RECORD_FIELDS | {"produced_by", "proposed_by", "policy_sha256"} if schema == 3 else RECORD_FIELDS
+    raw = _fields(record, fields)
+    if type(raw["schema_version"]) is not int or raw["schema_version"] not in (1, 2, 3):
+        raise DecisionError("unsupported evidence schema_version")
+    _text(raw["id"], "decision id")
+    try:
+        UUID(raw["id"])
+    except ValueError as error:
+        raise DecisionError("decision id must be a UUID") from error
+    _timestamp(raw["created_at"])
+    proposal = Recommendation.from_dict(raw["recommendation"])
+    ticket = Ticket.from_dict(raw["ticket"])
+    policy = RoutingPolicy.from_dict(raw["policy"])
+    if raw["schema_version"] == 3:
+        _text(raw["proposed_by"], "proposed_by")
+        producer = _fields(raw["produced_by"], {"name", "version"})
+        if producer["name"] != "decisioncontrol":
+            raise DecisionError("unexpected evidence producer")
+        _text(producer["version"], "producer version")
+        if raw["policy_sha256"] != hashlib.sha256(_canonical(raw["policy"])).hexdigest():
+            raise RecordMismatch("policy_sha256 does not match the frozen policy")
+    recorded = Evaluation.from_dict(raw["evaluation"])
+    expected = evaluate(proposal, ticket, policy)
+    if recorded != expected:
+        raise RecordMismatch("recorded verdict/reasons do not match the frozen inputs and policy")
+    try:
+        status = Status(raw["status"])
+    except (ValueError, TypeError) as error:
+        raise DecisionError("unknown lifecycle status") from error
+    events = raw["events"]
+    if not isinstance(events, list) or not events:
+        raise DecisionError("evidence must contain a submission event")
+    state = INITIAL_STATUS[expected.verdict]
+    review_event = None
+    for index, event in enumerate(events):
+        name = event.get("event") if isinstance(event, Mapping) else None
+        fields = {"event", "at", "reviewer", "note"} if name == "CANCELLED" else {"event", "at"}
+        event = _fields(event, fields)
+        at = _timestamp(event["at"])
+        if index == 0:
+            if name != "SUBMITTED" or at != raw["created_at"]:
+                raise DecisionError("first event must match submission time")
+            continue
+        if name in ("APPROVED", "REJECTED") and state == Status.PENDING_REVIEW.value:
+            review_event = event
+            state = Status.READY.value if name == "APPROVED" else Status.REJECTED.value
+        elif name in ("EXECUTED", "STALE") and state == Status.READY.value:
+            state = name
+        elif (name == "CANCELLED" and raw["schema_version"] >= 2
+              and state in (Status.READY.value, Status.PENDING_REVIEW.value)):
+            if (raw["schema_version"] == 3 and expected.verdict.value == "REVIEW"
+                    and event["reviewer"] == raw["proposed_by"]):
+                raise RecordMismatch("proposer cannot cancel their own REVIEW decision")
+            if event["reviewer"] not in policy.reviewers:
+                raise RecordMismatch("cancelling reviewer is not authorized by the frozen policy")
+            if not isinstance(event["note"], str) or not event["note"].strip():
+                raise DecisionError("cancellation must contain a nonempty reason")
+            state = Status.CANCELLED.value
+        else:
+            raise RecordMismatch("event history contains a prohibited transition")
+    if status.value != state:
+        raise RecordMismatch("lifecycle status does not match event history")
+    review = raw["review"]
+    if review_event is None:
+        if review is not None:
+            raise RecordMismatch("review has no corresponding review event")
+    else:
+        review = _fields(review, {"decision", "reviewer", "note", "at"})
+        if review["decision"] != review_event["event"] or review["at"] != review_event["at"]:
+            raise RecordMismatch("review does not match its event")
+        if raw["schema_version"] == 3 and review["reviewer"] == raw["proposed_by"]:
+            raise RecordMismatch("proposer cannot review their own REVIEW decision")
+        if review["reviewer"] not in policy.reviewers:
+            raise RecordMismatch("reviewer is not authorized by the frozen policy")
+        if not isinstance(review["note"], str):
+            raise DecisionError("review note must be text")
+    if status == Status.EXECUTED:
+        result = Ticket.from_dict(raw["result"])
+        expected_result = Ticket(ticket.id, proposal.destination, ticket.revision + 1)
+        if result != expected_result:
+            raise RecordMismatch("execution result does not match the approved action")
+    elif raw["result"] is not None:
+        raise RecordMismatch("an unexecuted decision cannot contain an execution result")
+    return {"valid": True, "decision_id": raw["id"], "verdict": expected.verdict.value,
+            "status": status.value}
+
+
+def export_record(record: dict) -> dict:
+    """Validate and checksum the entire record, including review and execution history."""
+    _validate_record(record)
+    return {"record": record, "sha256": hashlib.sha256(_canonical(record)).hexdigest()}
+
+
+def replay(envelope: dict) -> dict:
+    """Check integrity and reproduce authorization from frozen inputs; never execute."""
+    raw = _fields(envelope, {"record", "sha256"})
+    digest = raw["sha256"]
+    if (not isinstance(digest, str) or len(digest) != 64
+            or any(character not in "0123456789abcdef" for character in digest)):
+        raise DecisionError("sha256 must be a 64-character digest")
+    if hashlib.sha256(_canonical(raw["record"])).hexdigest() != digest:
+        raise RecordMismatch("evidence checksum mismatch")
+    return _validate_record(raw["record"])