reckon-rcdr 0.1.1__py3-none-any.whl

reckon/__init__.py

@@ -0,0 +1,27 @@
+"""Reckon — the capture layer for autonomous decisions.
+
+Emits RCDR v0.1 records (`docs/RCDR-v0.1.md`) and verifies which replay capability
+class a record actually supports. Capture is the primitive; replay exists to prove
+capture worked.
+"""
+
+from .emit import Decision, Recorder
+from .execution import SDK_VERSION
+from .run import Boundary, RunReport, boundary, verify_run
+from .sink import JsonlSink, MemorySink, Sink
+from .verify import Report, verify
+
+__all__ = [
+    "Boundary",
+    "Decision",
+    "JsonlSink",
+    "MemorySink",
+    "Recorder",
+    "Report",
+    "RunReport",
+    "SDK_VERSION",
+    "Sink",
+    "boundary",
+    "verify",
+    "verify_run",
+]

reckon/__main__.py

@@ -0,0 +1,64 @@
+"""`python -m reckon` — the verifier CLI.
+
+Exit code 1 when the requested class is not supported, so this can gate a pipeline.
+That is the whole point of instrumenting: a build should be able to fail because the
+evidence needed to re-adjudicate a decision was never captured.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .execution import SDK_VERSION
+from .run import boundary, verify_run
+from .verify import CLASS_NAMES
+
+
+def load(path: str) -> list[dict]:
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    return [json.loads(line) for line in lines if line.strip()]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="reckon", description=__doc__)
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"reckon {SDK_VERSION} (RCDR v0.1)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    verify_cmd = sub.add_parser("verify", help="report the class a run supports")
+    verify_cmd.add_argument("path", help="path to an RCDR .jsonl run")
+    verify_cmd.add_argument(
+        "--class",
+        dest="requested",
+        default="C1",
+        choices=sorted(CLASS_NAMES),
+        help="the counterfactual class you want to run",
+    )
+    verify_cmd.add_argument("--json", action="store_true", help="machine-readable output")
+
+    boundary_cmd = sub.add_parser(
+        "boundary", help="locate where evidence ends for a counterfactual"
+    )
+    boundary_cmd.add_argument("path")
+    boundary_cmd.add_argument("--decision", required=True, help="the decision to flip")
+    boundary_cmd.add_argument("--json", action="store_true")
+
+    args = parser.parse_args(argv)
+    records = load(args.path)
+
+    if args.command == "verify":
+        report = verify_run(records, requested=args.requested)
+        print(json.dumps(report.to_dict(), indent=2) if args.json else report.render())
+        return 0 if report.satisfied else 1
+
+    edge = boundary(records, args.decision)
+    print(json.dumps(edge.to_dict(), indent=2) if args.json else edge.render())
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

reckon/emit.py

@@ -0,0 +1,220 @@
+"""The emitter (§7, emitter conformance).
+
+The design rule the whole SDK obeys: **the emitter refuses to guess.** It will raise
+rather than invent a policy value it was never told about, or close a decision that
+never declared an outcome. A record that quietly fills its own gaps is the failure
+mode RCDR exists to prevent.
+"""
+
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Iterator
+
+from . import execution as execmodel
+from . import predicate as pred
+from .record import Candidate, Candidates, Execution, Policy, Predicate, digest
+from .sink import Sink
+
+OPERATORS = {
+    "gte": lambda a, b: a >= b,
+    "gt": lambda a, b: a > b,
+    "lte": lambda a, b: a <= b,
+    "lt": lambda a, b: a < b,
+    "eq": lambda a, b: a == b,
+    "ne": lambda a, b: a != b,
+    "in": lambda a, b: a in b,
+    "contains": lambda a, b: b in a,
+}
+
+
+class Decision:
+    """One decision in flight. Closed by `admit()` or `reject()`."""
+
+    def __init__(self, action: str, params: dict | None, pure: bool | None) -> None:
+        self.action = action
+        self.params = params or {}
+        self.pure = pure
+        self.policies: dict[str, Policy] = {}
+        self.predicate: Predicate | None = None
+        self.governing_key: str | None = None
+        self.compared_value: Any = None
+        self.compared_type: str | None = None
+        self.candidates = Candidates()
+        self.outcome: str | None = None
+        self.reads: list[dict] = []
+        self.writes: list[dict] = []
+
+    # --- policy (§4.4) ---------------------------------------------------------
+
+    def policy(
+        self,
+        key: str,
+        *,
+        value: Any,
+        provenance: str,
+        source: str,
+        revision: str | None = None,
+    ) -> None:
+        """Register the value in force at call time. A pointer will not do."""
+        self.policies[key] = Policy(
+            key=key,
+            resolved_value=value,
+            provenance=provenance,
+            source=source,
+            revision=revision,
+        )
+
+    # --- the crossing (§4.2, §4.3) ---------------------------------------------
+
+    def check(self, operator: str, *, left: str, value: Any, right: str) -> bool:
+        """Evaluate the predicate and record its structure, operand and policy.
+
+        Returns the real boolean so the caller branches on the same value that was
+        recorded. An SDK that records a decision the host did not actually make is
+        worse than no record at all.
+        """
+        if operator not in OPERATORS:
+            raise ValueError(f"unknown operator {operator!r}; expected one of {sorted(OPERATORS)}")
+        if right not in self.policies:
+            raise ValueError(
+                f"policy {right!r} is not registered for this decision. "
+                "Call .policy() with the value in force before comparing against it."
+            )
+
+        policy = self.policies[right]
+        self.predicate = Predicate(
+            id=pred.predicate_id(operator, left, right),
+            operator=operator,
+            expression=pred.expression(operator, left, right),
+        )
+        self.compared_value = value
+        self.compared_type = type(value).__name__
+        self.governing_key = right
+        return bool(OPERATORS[operator](value, policy.resolved_value))
+
+    # --- candidates (§4.6) ------------------------------------------------------
+
+    def candidate(
+        self,
+        action_id: str,
+        *,
+        compared_value: Any,
+        outcome: str,
+        predicate: str,
+    ) -> None:
+        self.candidates.items.append(
+            Candidate(
+                action_id=action_id,
+                compared_value=compared_value,
+                outcome=outcome,
+                predicate_id=predicate,
+            )
+        )
+
+    def candidates_exhaustive(self) -> None:
+        """Declare that every candidate considered was recorded.
+
+        Only the caller can know this, which is why it is an explicit statement and
+        never inferred from the fact that some candidates were logged.
+        """
+        self.candidates.completeness = "exhaustive"
+
+    def candidates_partial(self) -> None:
+        self.candidates.completeness = "partial"
+
+    # --- state (§4.7) -----------------------------------------------------------
+
+    def read(self, key: str, value: Any, source: str) -> None:
+        self.reads.append({"key": key, "value_digest": digest(value), "source": source})
+
+    def write(self, key: str, value: Any) -> None:
+        self.writes.append({"key": key, "value_digest": digest(value)})
+
+    # --- outcome (§4.5) ---------------------------------------------------------
+
+    def admit(self) -> None:
+        self.outcome = "admit"
+
+    def reject(self) -> None:
+        self.outcome = "reject"
+
+
+class Recorder:
+    def __init__(
+        self,
+        *,
+        sink: Sink,
+        run_id: str,
+        emitter: str,
+        seed: int | None = None,
+        clock: str | None = None,
+    ) -> None:
+        self.sink = sink
+        self.run_id = run_id
+        self.emitter = emitter
+        self.seed = seed
+        self.clock = clock
+        self._sequence = 0
+
+    @contextmanager
+    def decision(
+        self,
+        *,
+        action: str,
+        params: dict | None = None,
+        pure: bool | None = None,
+    ) -> Iterator[Decision]:
+        decision = Decision(action=action, params=params, pure=pure)
+        # If the body raises, the exception propagates untouched: no half-formed
+        # record is emitted, and the outcome complaint below never masks it.
+        yield decision
+        if decision.outcome is None:
+            raise ValueError(
+                f"decision on action {action!r} closed without an outcome; "
+                "call .admit() or .reject()"
+            )
+        self.sink.write(self._build(decision))
+
+    def _build(self, decision: Decision) -> dict:
+        record = {
+            "rcdr_version": "0.1",
+            "decision_id": f"d-{uuid.uuid4().hex[:12]}",
+            "run_id": self.run_id,
+            "sequence": self._sequence,
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "outcome": decision.outcome,
+            "action": {
+                "id": decision.action,
+                "params_digest": digest(decision.params),
+            },
+            "candidates": decision.candidates.to_dict(),
+            "reads": decision.reads,
+            "writes": decision.writes,
+            "execution": Execution(
+                runtime=execmodel.runtime(),
+                deps_digest=execmodel.deps_digest(),
+                path_digest=execmodel.path_digest(
+                    [policy.resolution_source for policy in decision.policies.values()],
+                    self.emitter,
+                ),
+                seed=self.seed,
+                clock=self.clock,
+                pure=decision.pure,
+            ).to_dict(),
+            "capture": {
+                "sdk_version": execmodel.SDK_VERSION,
+                "emitter": self.emitter,
+            },
+        }
+        self._sequence += 1
+
+        if decision.predicate is not None:
+            record["predicate"] = decision.predicate.to_dict()
+            record["compared"] = {
+                "value": decision.compared_value,
+                "type": decision.compared_type,
+            }
+        if decision.governing_key is not None:
+            record["policy"] = decision.policies[decision.governing_key].to_dict()
+        return record

reckon/execution.py

@@ -0,0 +1,47 @@
+"""Execution model (§4.8).
+
+`path_digest` is the field that carries the OPA finding. Replay soundness is not
+compositional: two runs with identical component versions can differ because one
+resolved its policy from a place the other did not. The path digest covers the
+resolution sources actually used, so those two runs hash differently.
+"""
+
+import hashlib
+import platform
+from importlib.metadata import distributions
+
+SDK_VERSION = "0.1.1"
+
+_deps_digest_cache: str | None = None
+
+
+def runtime() -> str:
+    return f"python{platform.python_version()}"
+
+
+def deps_digest() -> str:
+    """Digest of the resolved dependency set. Stable within a process."""
+    global _deps_digest_cache
+    if _deps_digest_cache is None:
+        installed = sorted(
+            f"{dist.metadata['Name']}=={dist.version}"
+            for dist in distributions()
+            if dist.metadata["Name"]
+        )
+        digest = hashlib.sha256("\n".join(installed).encode("utf-8"))
+        _deps_digest_cache = f"sha256:{digest.hexdigest()}"
+    return _deps_digest_cache
+
+
+def path_digest(resolution_sources: list[str], emitter: str) -> str:
+    """Digest over the whole execution path, not a composition of component versions.
+
+    `resolution_sources` are the `provenance:source` pairs that actually resolved a
+    policy in this decision. Two decisions with identical dependencies but different
+    resolution regimes — the OPA bundle case versus the Data API case — produce
+    different path digests, which is precisely what the bundle revision failed to do.
+    """
+    material = "\n".join(
+        [deps_digest(), runtime(), SDK_VERSION, emitter, *sorted(resolution_sources)]
+    )
+    return f"sha256:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"

reckon/predicate.py

@@ -0,0 +1,30 @@
+"""Predicate identity (§4.2).
+
+A predicate is identified by the hash of its canonical structure — operator plus
+operand identities — not by its name or source location. The LangGraph probe showed
+two gates that were indistinguishable in the record while behaving differently; a
+name does not survive a refactor and a line number does not separate look-alikes.
+"""
+
+import hashlib
+
+FIELD_SEPARATOR = "\x1f"
+
+
+def canonical_form(operator: str, left: str, right: str) -> str:
+    """The bytes that define a predicate's identity.
+
+    Operands are joined with an ASCII unit separator so that no operand value can
+    forge a boundary between fields.
+    """
+    return FIELD_SEPARATOR.join((operator, left, right))
+
+
+def predicate_id(operator: str, left: str, right: str) -> str:
+    digest = hashlib.sha256(canonical_form(operator, left, right).encode("utf-8"))
+    return f"p:{digest.hexdigest()[:16]}"
+
+
+def expression(operator: str, left: str, right: str) -> str:
+    """Human rendering. Informational only — never an identity."""
+    return f"{left} {operator} {right}"

reckon/record.py

@@ -0,0 +1,120 @@
+"""Record structures (§4). These emit the RCDR field names exactly.
+
+Nothing here infers a missing value. Where the emitter cannot establish a fact, the
+record says so — `provenance: unknown`, `completeness: taken_only` — because a format
+with no way to admit ignorance emits records that silently claim a class they cannot
+support (§4.4).
+"""
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+PROVENANCE = ("bundled", "runtime_override", "environment", "computed", "unknown")
+COMPLETENESS = ("exhaustive", "partial", "taken_only")
+OUTCOMES = ("admit", "reject")
+
+
+def digest(value: Any) -> str:
+    canonical = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+    return f"sha256:{hashlib.sha256(canonical.encode('utf-8')).hexdigest()}"
+
+
+@dataclass
+class Policy:
+    key: str
+    resolved_value: Any
+    provenance: str
+    source: str
+    revision: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.provenance not in PROVENANCE:
+            raise ValueError(
+                f"policy.resolution.provenance must be one of {PROVENANCE}, "
+                f"got {self.provenance!r}. Use 'unknown' when it cannot be established."
+            )
+
+    @property
+    def resolution_source(self) -> str:
+        return f"{self.provenance}:{self.source}"
+
+    def to_dict(self) -> dict:
+        resolution: dict[str, Any] = {
+            "provenance": self.provenance,
+            "source": self.source,
+        }
+        if self.revision is not None:
+            resolution["revision"] = self.revision
+        return {
+            "key": self.key,
+            "resolved_value": self.resolved_value,
+            "resolution": resolution,
+        }
+
+
+@dataclass
+class Predicate:
+    id: str
+    operator: str
+    expression: str
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "operator": self.operator, "expression": self.expression}
+
+
+@dataclass
+class Candidate:
+    action_id: str
+    compared_value: Any
+    outcome: str
+    predicate_id: str
+
+    def __post_init__(self) -> None:
+        if self.outcome not in OUTCOMES:
+            raise ValueError(f"candidate outcome must be one of {OUTCOMES}")
+
+    def to_dict(self) -> dict:
+        return {
+            "action_id": self.action_id,
+            "compared_value": self.compared_value,
+            "outcome": self.outcome,
+            "predicate_id": self.predicate_id,
+        }
+
+
+@dataclass
+class Candidates:
+    completeness: str = "taken_only"
+    items: list[Candidate] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.completeness not in COMPLETENESS:
+            raise ValueError(f"candidates.completeness must be one of {COMPLETENESS}")
+
+    def to_dict(self) -> dict:
+        return {
+            "completeness": self.completeness,
+            "items": [item.to_dict() for item in self.items],
+        }
+
+
+@dataclass
+class Execution:
+    runtime: str
+    deps_digest: str
+    path_digest: str
+    seed: int | None = None
+    clock: str | None = None
+    pure: bool | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "runtime": self.runtime,
+            "deps_digest": self.deps_digest,
+            "path_digest": self.path_digest,
+            "seed": self.seed,
+            "clock": self.clock,
+            "pure": self.pure,
+        }

reckon/run.py

@@ -0,0 +1,174 @@
+"""Run-level verification and the C3 boundary (§4.7, §5.1, §5.2).
+
+Two things happen here that cannot happen one record at a time.
+
+The first is that a run's class is its **weakest** decision, not its average. §5.2
+forbids aggregating evidence into a single number, and a mean would do exactly that:
+it would let ninety well-instrumented decisions hide the one that cannot support the
+counterfactual you actually want to run.
+
+The second is the C3 boundary. A changed decision perturbs state that later decisions
+read, and past that first flip nothing is replay any more — it is counterfactual
+inference. The boundary report locates the edge where evidence ends. It never
+certifies what lies beyond it; it labels it hypothesis and stops.
+"""
+
+from dataclasses import dataclass, field
+
+from .verify import CLASS_NAMES, LADDER, verify
+
+
+def _rank(name: str | None) -> int:
+    return -1 if name is None else LADDER.index(name)
+
+
+@dataclass
+class RunReport:
+    requested: str
+    available: str | None
+    satisfied: bool
+    counts: dict[str, int] = field(default_factory=dict)
+    shortfalls: list[tuple[str, str | None, list[str]]] = field(default_factory=list)
+
+    def render(self) -> str:
+        lines = [
+            f"Requested: {CLASS_NAMES[self.requested]} ({self.requested})",
+            f"Available: {self.available or 'none'}",
+            "Decisions: "
+            + ", ".join(f"{name} x{count}" for name, count in sorted(self.counts.items())),
+        ]
+        if self.shortfalls:
+            lines.append("Short:")
+            for decision_id, available, missing in self.shortfalls:
+                lines.append(f"  {decision_id}  available {available or 'none'}")
+                lines.extend(f"    missing {item}" for item in missing)
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "requested": self.requested,
+            "available": self.available,
+            "satisfied": self.satisfied,
+            "counts": self.counts,
+            "shortfalls": [
+                {"decision_id": decision_id, "available": available, "missing": missing}
+                for decision_id, available, missing in self.shortfalls
+            ],
+        }
+
+
+def verify_run(records: list[dict], *, requested: str) -> RunReport:
+    ordered = sorted(records, key=lambda record: record.get("sequence", 0))
+    reports = [(record, verify(record, requested=requested)) for record in ordered]
+
+    counts: dict[str, int] = {}
+    for _, report in reports:
+        key = report.available or "none"
+        counts[key] = counts.get(key, 0) + 1
+
+    available = None
+    if reports:
+        available = min((report.available for _, report in reports), key=_rank)
+
+    shortfalls = [
+        (record["decision_id"], report.available, report.missing)
+        for record, report in reports
+        if report.missing
+    ]
+
+    satisfied = (
+        requested != "C3"
+        and bool(reports)
+        and _rank(available) >= _rank(requested if requested in LADDER else "C2")
+    )
+    return RunReport(
+        requested=requested,
+        available=available,
+        satisfied=satisfied,
+        counts=counts,
+        shortfalls=shortfalls,
+    )
+
+
+@dataclass
+class Boundary:
+    origin: str
+    evidence: list[str]
+    hypothesis: list[str]
+    edges: list[tuple[str, str, str]]
+
+    def render(self) -> str:
+        lines = [
+            f"Counterfactual at: {self.origin}",
+            "Evidence:   " + ", ".join(self.evidence),
+        ]
+        if self.hypothesis:
+            lines.append("Hypothesis: " + ", ".join(self.hypothesis))
+            lines.append("Evidence ends at:")
+            lines.extend(
+                f"  {writer} --{key}--> {reader}" for writer, key, reader in self.edges
+            )
+            lines.append(
+                "Everything in the hypothesis region is inference, not replay. "
+                "C3 is not certifiable."
+            )
+        else:
+            lines.append("Hypothesis: none — nothing downstream reads what this decision wrote.")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "origin": self.origin,
+            "evidence": self.evidence,
+            "hypothesis": self.hypothesis,
+            "edges": [
+                {"writer": writer, "key": key, "reader": reader}
+                for writer, key, reader in self.edges
+            ],
+        }
+
+
+def boundary(records: list[dict], decision_id: str) -> Boundary:
+    """Locate where evidence ends if `decision_id` had gone the other way.
+
+    A decision is downstream if it reads a key written by the origin, or by anything
+    already downstream. The closure is taken forward in sequence order only — a
+    decision cannot be perturbed by one that had not happened yet.
+    """
+    ordered = sorted(records, key=lambda record: record.get("sequence", 0))
+    index = {record["decision_id"]: position for position, record in enumerate(ordered)}
+    if decision_id not in index:
+        raise ValueError(f"decision {decision_id!r} is not in this run")
+
+    origin_position = index[decision_id]
+    perturbed = {decision_id}
+    edges: list[tuple[str, str, str]] = []
+    # writer_of[key] is the most recent perturbed decision to have written it.
+    writer_of: dict[str, str] = {
+        write["key"]: decision_id for write in ordered[origin_position].get("writes", [])
+    }
+
+    for record in ordered[origin_position + 1 :]:
+        reader = record["decision_id"]
+        touched = False
+        for read in record.get("reads", []):
+            writer = writer_of.get(read["key"])
+            if writer is not None:
+                edges.append((writer, read["key"], reader))
+                touched = True
+        if touched:
+            perturbed.add(reader)
+            for write in record.get("writes", []):
+                writer_of[write["key"]] = reader
+
+    hypothesis = [
+        record["decision_id"]
+        for record in ordered[origin_position + 1 :]
+        if record["decision_id"] in perturbed
+    ]
+    return Boundary(
+        origin=decision_id,
+        evidence=[decision_id],
+        hypothesis=hypothesis,
+        edges=edges,
+    )

reckon/sink.py

@@ -0,0 +1,32 @@
+"""Sinks. A sink takes a finished record dict and puts it somewhere durable."""
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+
+class Sink(Protocol):
+    def write(self, record: dict) -> None: ...
+
+
+class JsonlSink:
+    """One JSON object per line. Append-only; the file is the run."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def write(self, record: dict) -> None:
+        line = json.dumps(record, sort_keys=True, default=str)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(line + "\n")
+
+
+class MemorySink:
+    """For tests and for verifying a run without touching disk."""
+
+    def __init__(self) -> None:
+        self.records: list[dict] = []
+
+    def write(self, record: dict) -> None:
+        self.records.append(record)

reckon/verify.py

@@ -0,0 +1,122 @@
+"""The verifier (§5).
+
+It implements §5.1 exactly and obeys §5.2. The output is type-error shaped: the class
+requested, the class actually available, and the specific evidence that separates them.
+Never a score — a percentage over incommensurable kinds of missing evidence is the same
+false confidence that made the OPA failure undetectable.
+"""
+
+from dataclasses import dataclass, field
+
+CLASS_NAMES = {
+    "C0": "Identity Replay",
+    "C1": "Tightening Replay",
+    "C2": "Loosening Replay",
+    "C3": "State-Coupled Replay",
+}
+LADDER = ("C0", "C1", "C2")
+
+
+@dataclass
+class Report:
+    requested: str
+    available: str | None
+    satisfied: bool
+    missing: list[str] = field(default_factory=list)
+
+    def render(self) -> str:
+        available = self.available or "none"
+        lines = [
+            f"Requested: {CLASS_NAMES[self.requested]} ({self.requested})",
+            f"Available: {available}",
+        ]
+        if self.missing:
+            lines.append(f"Missing:   {self.missing[0]}")
+            lines.extend(f"           {item}" for item in self.missing[1:])
+        return "\n".join(lines)
+
+
+def _get(record: dict, path: str):
+    node = record
+    for part in path.split("."):
+        if not isinstance(node, dict) or part not in node:
+            return None
+        node = node[part]
+    return node
+
+
+def _unmet_c0(record: dict) -> list[str]:
+    missing = [
+        f"execution.{name}"
+        for name in ("runtime", "deps_digest", "path_digest")
+        if not _get(record, f"execution.{name}")
+    ]
+    seed = _get(record, "execution.seed")
+    pure = _get(record, "execution.pure")
+    if seed is None and pure is not True:
+        # Determinism must be established, not assumed. Either the seed is recorded
+        # or the decision function is declared pure.
+        missing.append("execution.seed")
+        if pure is None:
+            missing.append("execution.pure")
+    return missing
+
+
+def _unmet_c1(record: dict) -> list[str]:
+    missing = []
+    if not _get(record, "predicate.id"):
+        missing.append("predicate.id")
+    if _get(record, "compared.value") is None:
+        missing.append("compared.value")
+    if _get(record, "policy.resolved_value") is None:
+        missing.append("policy.resolved_value")
+    if _get(record, "policy.resolution.provenance") == "unknown":
+        # §4.4: the record can say it does not know, and saying so caps it at C0.
+        missing.append("policy.resolution.provenance != unknown")
+    elif _get(record, "policy.resolution.provenance") is None:
+        missing.append("policy.resolution.provenance")
+    return missing
+
+
+def _unmet_c2(record: dict) -> list[str]:
+    missing = []
+    # §4.6: absent completeness reads as taken_only, the conservative interpretation.
+    completeness = _get(record, "candidates.completeness") or "taken_only"
+    if completeness != "exhaustive":
+        missing.append("candidates.completeness = exhaustive")
+    items = _get(record, "candidates.items") or []
+    if not items or any(item.get("compared_value") is None for item in items):
+        missing.append("candidates.items[].compared_value")
+    return missing
+
+
+UNMET = {"C0": _unmet_c0, "C1": _unmet_c1, "C2": _unmet_c2}
+
+
+def verify(record: dict, *, requested: str) -> Report:
+    if requested not in CLASS_NAMES:
+        raise ValueError(f"unknown class {requested!r}; expected one of {sorted(CLASS_NAMES)}")
+
+    unmet_by_class = {name: UNMET[name](record) for name in LADDER}
+
+    available: str | None = None
+    for name in LADDER:
+        if unmet_by_class[name]:
+            break
+        available = name
+
+    ceiling = LADDER.index(requested) if requested in LADDER else len(LADDER) - 1
+    start = 0 if available is None else LADDER.index(available) + 1
+    missing = [item for name in LADDER[start : ceiling + 1] for item in unmet_by_class[name]]
+
+    if requested == "C3":
+        # §3, §6: C3 is never certified. The verifier reports where evidence ends and
+        # marks everything downstream as hypothesis. No implementation may do otherwise.
+        missing.append(
+            "C3 (State-Coupled Replay) is not certifiable by any verifier; "
+            "past the first flip this is counterfactual inference, not replay"
+        )
+        return Report(requested=requested, available=available, satisfied=False, missing=missing)
+
+    satisfied = available is not None and LADDER.index(available) >= LADDER.index(requested)
+    return Report(requested=requested, available=available, satisfied=satisfied, missing=missing)

reckon_rcdr-0.1.1.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: reckon-rcdr
+Version: 0.1.1
+Summary: The capture layer for autonomous decisions — emit and verify replay-complete decision records (RCDR v0.1)
+Author-email: Ola <laolex55@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Laolex/reckon
+Project-URL: Specification, https://github.com/Laolex/reckon/blob/main/docs/RCDR-v0.1.md
+Project-URL: Source, https://github.com/Laolex/reckon
+Keywords: replay,audit,provenance,policy,agents,observability,rcdr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# Reckon
+
+**The capture layer for autonomous decisions.** Capture is the primitive; replay exists to
+prove capture worked.
+
+An autonomous system that made a decision you now regret leaves behind a record. The
+question you want to ask that record is not "what happened" — it is *"would this have gone
+the other way under a different policy?"* Reckon exists because that question is usually
+unanswerable, and because nothing in the record tells you it is unanswerable.
+
+## The finding
+
+Five systems were probed: OPA, LangGraph, Temporal, and the decision logs of a live
+Hyperliquid and a live Polymarket agent. Every one produced records that looked sufficient
+and were not.
+
+Three are reproducible here from the original probe artifacts, in [`demo/`](demo/):
+
+- **OPA.** A sound policy engine, versioned bundles and a complete decision log still
+  produced two decisions with **identical input, identical bundle revision and identical
+  engine version that came out opposite ways** — and nothing in the record revealed which
+  regime was in force.
+- **LangGraph.** Three threads, one identical persisted rationale, two different outcomes.
+  The threshold that separated them occurs in **zero of 12,286 persisted bytes**. The record
+  faithfully kept the reasoning that did not decide, and dropped the predicate that did.
+- **Temporal.** The hardest case, since deterministic replay *is* its product. The same
+  divergence — history says `trade`, replayed code decides `skip` — is caught when the
+  decision schedules an activity and **silent when it only changes a returned value**.
+  Detection is drawn at command boundaries, not at decisions.
+
+So: replay soundness is not compositional. It is a property of the whole execution path, not
+of the components in it. And no record carries its own soundness proof.
+
+The argument in full is in [`docs/ARGUMENT.md`](docs/ARGUMENT.md), including the
+non-goals and what would falsify it.
+
+## Capability classes
+
+The verifier reports a class, never a score. A percentage over incommensurable kinds of
+missing evidence manufactures exactly the false confidence that made the OPA failure
+undetectable.
+
+| Class | Counterfactual | Additionally requires |
+|---|---|---|
+| **C0** Identity | reproduce what happened | execution model, determinism |
+| **C1** Tightening | admit strictly fewer actions | predicate structure, compared value, resolved policy |
+| **C2** Loosening | admit more actions | the rejected candidate set and their values |
+| **C3** State-Coupled | a changed decision perturbs later state | **not certifiable by anyone** |
+
+C0–C2 are deductive given capture. C3 is not deductive for anyone — past the first flip it
+is counterfactual inference, not replay. Reckon's honest top guarantee is: certify soundness
+through C2, and for C3 certify *where the evidence ends*.
+
+## Install
+
+```
+pip install reckon-rcdr
+```
+
+Python 3.11+, no runtime dependencies. The distribution is `reckon-rcdr`; the import name
+and the CLI command are both `reckon`.
+
+## Use
+
+```python
+from reckon import JsonlSink, Recorder
+
+rec = Recorder(sink=JsonlSink("run.jsonl"), run_id="run-1", emitter="my-agent")
+
+with rec.decision(action="transfer", pure=True) as d:
+    d.policy("policy.limit", value=5000, provenance="bundled", source="opa:bundle")
+    allowed = d.check("lt", left="request.amount", value=4200, right="policy.limit")
+    d.candidate("transfer", compared_value=4200, outcome="admit", predicate="p:limit")
+    d.candidate("hold", compared_value=4200, outcome="reject", predicate="p:limit")
+    d.candidates_exhaustive()
+    d.admit() if allowed else d.reject()
+```
+
+```
+$ python -m reckon verify run.jsonl --class C2
+Requested: Loosening Replay (C2)
+Available: C2
+Decisions: C2 x1
+
+$ python -m reckon boundary run.jsonl --decision d-4f21a0c9e113
+```
+
+Exit code is non-zero when the requested class is unsupported, so it can gate a pipeline. A
+build should be able to fail because the evidence needed to re-adjudicate a decision was
+never captured.
+
+## The emitter refuses to guess
+
+Comparing against a policy that was never registered raises. Closing a decision without an
+outcome raises. `pure` is a declaration the caller makes, never something the SDK infers, so
+an undeclared decision without a seed fails C0. Absent candidate completeness reads as
+`taken_only`; unestablished provenance is written as `unknown` and caps the record at C0.
+
+Each of those is deliberately inconvenient. A record that quietly fills its own gaps is the
+failure this whole project is named after.
+
+## Layout
+
+| Path | |
+|---|---|
+| `docs/RCDR-v0.1.md` | the record format — the normative document |
+| `docs/ARGUMENT.md` | the argument: thesis, evidence, novelty, non-goals |
+| `src/reckon/` | emitter, verifier, run-level verifier, CLI |
+| `demo/` | three before/after arcs over real probe artifacts, plus the ablation |
+| `demo/ABLATION.md` | which fields are load-bearing — generated, not asserted |
+| `tests/` | every assertion traces to a requirement in the spec |
+
+```
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## License
+
+Apache-2.0. Chosen over MIT for the express patent grant: RCDR is meant to be implemented
+by other people, and an implementer should not have to wonder about that.
+
+## Scope
+
+No tamper evidence, no signatures, no anchoring — the demonstrated threat is omission, not
+modification. No confidentiality. No inference over uninstrumented systems: RCDR describes
+what an instrumented emitter must produce, and recovering decision semantics from arbitrary
+code is a separate and much harder problem. Any implementation reporting a C3 certification
+is non-conforming.

reckon_rcdr-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+reckon/__init__.py,sha256=5po5X_nb_MPRnK5WidJKZVJ_K7QhWpxLejRFmLc5slk,666
+reckon/__main__.py,sha256=ISrATKIgPrex2P5qp5cyhqmgWtJxh7KlbcWtRu0uREo,2163
+reckon/emit.py,sha256=XLhsq_TblNmBVZ6ELmUFtOxccNYXwTJwJDb5C9GIy3I,7518
+reckon/execution.py,sha256=UxiuQcrjuQPchKhVLWNzTmdqPwwKUgXC08FeL0fjU04,1751
+reckon/predicate.py,sha256=FLLiA9lzPqt3LAR_ybhzfKJi2v8Gi0vqsVnpUKTzbE8,1078
+reckon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reckon/record.py,sha256=GxPqZqZrKnLK-tbQ1Y3NudJbYqHrPxu1h3gd0ShsBZ0,3361
+reckon/run.py,sha256=lUiUd4hl1hm8pVOTC6OZCW_m48_K0JdZagXZziUCcmI,6163
+reckon/sink.py,sha256=ZiTrfhdeVBB6be6mUCZIFIIuMRS67JWulc-noYMsLSc,893
+reckon/verify.py,sha256=ZRBF32phzXFbODJvn1oODiUFHJf-p56pH90zZ3ctKrc,4528
+reckon_rcdr-0.1.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+reckon_rcdr-0.1.1.dist-info/METADATA,sha256=nhv4Gsik4xfTnk3JCzC0FTEI4ZRvG15ld2qxP8Sktkg,6763
+reckon_rcdr-0.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+reckon_rcdr-0.1.1.dist-info/entry_points.txt,sha256=bqJxuR8h4Btdk1xCKICqpSZpOu-BiiyA568SZwGXqE8,48
+reckon_rcdr-0.1.1.dist-info/top_level.txt,sha256=HWHjuFBolNZ_qyixEuNjpB_5H-zTjQctHStS29q7j_w,7
+reckon_rcdr-0.1.1.dist-info/RECORD,,

reckon_rcdr-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reckon_rcdr-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reckon = reckon.__main__:main

reckon_rcdr-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

reckon_rcdr-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+reckon