treecf 0.2.1__tar.gz → 0.2.2__tar.gz

{treecf-0.2.1 → treecf-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treecf
-Version: 0.2.1
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License

{treecf-0.2.1 → treecf-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "treecf"
-version = "0.2.1"
+version = "0.2.2"
 description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions."
 readme = "README.md"
 license = { text = "MIT" }

{treecf-0.2.1 → treecf-0.2.2}/rust/Cargo.lock

@@ -419,7 +419,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "treecf-core"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "numpy",
  "pyo3",

{treecf-0.2.1 → treecf-0.2.2}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 # f64::next_down (cells.rs) stabilized in 1.86; pyo3 0.29 needs 1.83
 rust-version = "1.86"

{treecf-0.2.1 → treecf-0.2.2}/src/treecf/__init__.py

@@ -10,6 +10,7 @@ from treecf._errors import (
     UnsupportedModelError,
 )
 from treecf.api import Counterfactual, Explainer, Grid, Infeasible
+from treecf.audit import constraints_fingerprint, ir_fingerprint
 from treecf.batch import BatchRecord, BatchResult
 from treecf.constraints import (
     AllowMissing,
@@ -27,7 +28,7 @@ from treecf.plausibility import Plausibility
 from treecf.regions import RecourseRegion
 from treecf.targets import Target
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 __all__ = [
     "AllowMissing",
@@ -58,5 +59,7 @@ __all__ = [
     "UnsupportedModelError",
     "__version__",
     "constraint",
+    "constraints_fingerprint",
+    "ir_fingerprint",
     "suggest_constraints",
 ]

{treecf-0.2.1 → treecf-0.2.2}/src/treecf/api.py

@@ -1248,6 +1248,98 @@ class Explainer:
             )
         return self._region_for(x, x_cf, interval)
 
+    def certificate(
+        self,
+        x: FloatArray,
+        result: Counterfactual | Infeasible,
+        target: Target,
+        *,
+        band: str | None = None,
+        seed: int | None = None,
+        node_budget: int | None = None,
+        gap: float | None = None,
+        time_budget_s: float | None = None,
+        warm_start: bool | None = None,
+    ) -> dict[str, object]:
+        """Issue an audit certificate for a stored result (post-hoc, like
+        ``recourse_region``).
+
+        A certificate is a reproducibility record plus a fresh verification —
+        it binds the result to a model fingerprint, a constraint fingerprint,
+        and the solve parameters, and re-verifies the returned plan at issue
+        time; it does not cryptographically prove that a search ran or that a
+        ``proof="optimal"`` claim is true — re-running with the recorded seed
+        and budgets on a fingerprint-matching model is how a validator checks
+        that. See
+        [Certification — audit certificates](concepts/certification.md#audit-certificates)
+        for the schema.
+
+        The certificate is a plain ``dict`` (``"schema_version": 1``) that
+        serializes with ``json.dumps(cert, allow_nan=False, sort_keys=True)``;
+        non-finite floats are encoded as the strings ``"NaN"``/``"Infinity"``/
+        ``"-Infinity"``. Accepts a ``Counterfactual`` or an ``Infeasible`` —
+        the certified "no" is exactly the case a validator cares most about.
+        The verification block is computed fresh here, never copied from the
+        solve: the plan's score, target membership, and constraint check are
+        recomputed (plus the plausibility bound when configured, and a sampled
+        set of region points when the result carries a region). A certificate
+        whose fresh verification fails is still returned, with the failing
+        booleans recorded — but a ``TreecfWarning`` names the failed check.
+
+        ``seed``/``node_budget``/``gap``/``time_budget_s``/``warm_start`` are
+        recorded under ``solve.declared`` when given: the result object does
+        not carry them, so they are caller-supplied, and the block's name
+        makes that provenance explicit.
+
+        Args:
+            x: The factual instance the result was solved from.
+            result: The ``Counterfactual`` or ``Infeasible`` to certify.
+            target: The target the result was solved against.
+            band: For a ``Target.bands`` result, the band this result belongs
+                to; required then, invalid otherwise.
+            seed: The seed the solve ran with, if the caller wants it recorded.
+            node_budget: The node budget the solve ran with, likewise.
+            gap: The relative gap the solve ran with, likewise.
+            time_budget_s: The time budget the solve ran with, likewise.
+            warm_start: The warm-start setting the solve ran with, likewise.
+
+        Returns:
+            The certificate as a strict-JSON-serializable ``dict``.
+
+        Raises:
+            TreecfError: If ``target`` is a ``Target.bands`` ladder and
+                ``band`` is missing or unknown, or if ``band`` is given for a
+                plain-interval target.
+        """
+        from treecf.audit import build_certificate
+
+        return build_certificate(
+            self, x, result, target, band=band, seed=seed, node_budget=node_budget,
+            gap=gap, time_budget_s=time_budget_s, warm_start=warm_start,
+        )
+
+    def check_certificate(self, cert: dict[str, object]) -> dict[str, object]:
+        """Validate a stored certificate against *this* explainer.
+
+        Recomputes both fingerprints (model and constraints) against this
+        explainer and re-runs the certificate's verification block from its
+        stored factual/plan, so a tampered ``x_cf``, a swapped model, or a
+        changed constraint set each flips the corresponding boolean. This
+        method reports — it never raises on a mismatch.
+
+        Args:
+            cert: A certificate produced by ``Explainer.certificate`` (a
+                ``json.loads`` round trip of one works identically).
+
+        Returns:
+            ``{"model_match": bool, "constraints_match": bool,
+            "verification_ok": bool, "mismatches": [...]}`` with one
+            human-readable string per mismatch.
+        """
+        from treecf.audit import check_certificate
+
+        return check_certificate(self, cert)
+
     def _region_for(
         self, x: FloatArray, x_cf: FloatArray, interval: tuple[float, float]
     ) -> RecourseRegion:

treecf-0.2.2/src/treecf/audit.py

@@ -0,0 +1,525 @@
+"""Audit certificates: reproducibility records with a fresh verification.
+
+A certificate binds a returned result to a model fingerprint, a constraint
+fingerprint, and the solve parameters, and re-verifies the returned plan at
+issue time — it does not cryptographically prove that a search ran or that an
+optimality claim is true; re-running with the recorded seed and budgets
+against a fingerprint-matching model is how a validator checks that.
+
+Certificates are plain ``dict[str, object]`` values (``"schema_version": 1``)
+that serialize with ``json.dumps(cert, allow_nan=False, sort_keys=True)``:
+non-finite floats are encoded as the strings ``"NaN"``, ``"Infinity"``, and
+``"-Infinity"`` wherever they can occur. See
+[Certification — audit certificates](concepts/certification.md#audit-certificates).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import struct
+import warnings
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import numpy as np
+import numpy.typing as npt
+
+from treecf._errors import TreecfError, TreecfWarning
+from treecf.constraints.objects import (
+    AllowMissing,
+    Constraint,
+    Equals,
+    Freeze,
+    Implies,
+    Linear,
+    Monotone,
+    OneHot,
+    Range,
+)
+from treecf.ir.evaluate import raw_score
+from treecf.ir.model import EnsembleIR, SplitOp
+
+if TYPE_CHECKING:
+    from treecf.api import Counterfactual, Explainer, Infeasible
+    from treecf.targets import Target
+
+FloatArray = npt.NDArray[np.float64]
+
+_NONE_U32 = 0xFFFFFFFF  # sentinel for an index field that does not apply
+_NONE_F64 = b"\xff" * 8  # sentinel for a float field that does not apply
+
+
+def _json_float(value: float) -> float | str:
+    """A float as strict JSON allows it: finite as-is, non-finite as a string."""
+    if math.isnan(value):
+        return "NaN"
+    if value == math.inf:
+        return "Infinity"
+    if value == -math.inf:
+        return "-Infinity"
+    return float(value)
+
+
+def _from_json_float(value: object) -> float:
+    """Inverse of ``_json_float``."""
+    if value == "NaN":
+        return math.nan
+    if value == "Infinity":
+        return math.inf
+    if value == "-Infinity":
+        return -math.inf
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise TreecfError(f"not a certificate float: {value!r}")
+    return float(value)
+
+
+def _encode_array(values: FloatArray) -> list[float | str]:
+    return [_json_float(v) for v in values.tolist()]
+
+
+def _decode_array(values: object) -> FloatArray:
+    if not isinstance(values, list):
+        raise TreecfError("certificate array field is not a list")
+    return np.array([_from_json_float(v) for v in values], dtype=np.float64)
+
+
+def ir_fingerprint(ir: EnsembleIR) -> str:
+    """SHA-256 fingerprint of an ensemble over a canonical byte encoding.
+
+    The encoding is positional bytes — the link name, the base score, the
+    tree count, then every node of every tree in index order with fixed-width
+    little-endian fields and fixed sentinel bytes where a field does not
+    apply to the node kind — so the fingerprint is stable across Python
+    versions, platforms, and dict ordering, and changes when any structural
+    or numeric detail of the ensemble changes (a one-ulp leaf perturbation
+    included).
+
+    Args:
+        ir: The parsed ensemble to fingerprint (``Explainer.ir``).
+
+    Returns:
+        A 64-character SHA-256 hex digest.
+    """
+    hasher = hashlib.sha256()
+    hasher.update(ir.link.name.encode("utf-8") + b"\x00")
+    hasher.update(struct.pack("<d", ir.base_score))
+    hasher.update(struct.pack("<I", len(ir.trees)))
+    for tree in ir.trees:
+        hasher.update(struct.pack("<I", len(tree.nodes)))
+        for node in tree.nodes:
+            if node.feature is None:  # leaf
+                assert node.value is not None
+                hasher.update(b"\x00" + struct.pack("<I", _NONE_U32) + _NONE_F64)
+                hasher.update(b"\x00\x02")  # op / missing_left sentinels
+                hasher.update(struct.pack("<II", _NONE_U32, _NONE_U32))
+                hasher.update(struct.pack("<d", node.value))
+            else:
+                assert node.threshold is not None and node.op is not None
+                assert node.missing_left is not None
+                assert node.left is not None and node.right is not None
+                hasher.update(b"\x01" + struct.pack("<I", node.feature))
+                hasher.update(struct.pack("<d", node.threshold))
+                hasher.update(
+                    bytes((1 if node.op is SplitOp.LT else 2, 1 if node.missing_left else 0))
+                )
+                hasher.update(struct.pack("<II", node.left, node.right))
+                hasher.update(_NONE_F64)
+    return hasher.hexdigest()
+
+
+def _constraint_record(c: Constraint, index: dict[str, int]) -> bytes:
+    """One constraint as canonical bytes: type tag, resolved feature indices,
+    parameters as little-endian f64. Never ``repr`` — bytes stay stable."""
+    if isinstance(c, Freeze):
+        return b"Freeze\x00" + struct.pack("<I", index[c.feature])
+    if isinstance(c, Monotone):
+        return b"Monotone\x00" + struct.pack("<I", index[c.feature]) + c.direction.encode("utf-8")
+    if isinstance(c, Range):
+        return b"Range\x00" + struct.pack("<Idd", index[c.feature], c.lo, c.hi)
+    if isinstance(c, Linear):
+        terms = sorted((index[name], float(coef)) for name, coef in c.coefficients.items())
+        body = b"".join(struct.pack("<Id", j, coef) for j, coef in terms)
+        return (
+            b"Linear\x00" + body + c.op.encode("utf-8") + b"\x00"
+            + struct.pack("<d", c.rhs) + c.missing_policy.encode("utf-8")
+        )
+    if isinstance(c, Equals):
+        return b"Equals\x00" + struct.pack("<Id", index[c.feature], c.value)
+    if isinstance(c, Implies):
+        return (
+            b"Implies\x00"
+            + struct.pack("<Id", index[c.condition.feature], c.condition.value)
+            + struct.pack("<Id", index[c.consequence.feature], c.consequence.value)
+        )
+    if isinstance(c, OneHot):
+        members = sorted(index[name] for name in c.features)
+        return b"OneHot\x00" + b"".join(struct.pack("<I", j) for j in members)
+    assert isinstance(c, AllowMissing)
+    delta_from = c.delta_miss if c.delta_from_miss is None else c.delta_from_miss
+    return b"AllowMissing\x00" + struct.pack("<Idd", index[c.feature], c.delta_miss, delta_from)
+
+
+def _constraints_encoding(explainer: Explainer) -> tuple[bytes, str | None]:
+    """Canonical bytes for the effective objective and constraint set, plus a
+    non-reproducibility reason when a component has no canonical encoding."""
+    index = {name: j for j, name in enumerate(explainer.ir.feature_names)}
+    records = sorted(_constraint_record(c, index) for c in explainer.compiled.constraints)
+    parts = [struct.pack("<I", len(records)), *records]
+    parts.append(np.asarray(explainer.sigma, dtype="<f8").tobytes())
+    parts.append(np.asarray(explainer.weights, dtype="<f8").tobytes())
+    reason: str | None = None
+    for name in sorted(explainer.value_policy):
+        policy = explainer.value_policy[name]
+        parts.append(struct.pack("<I", index[name]))
+        if isinstance(policy, str):
+            parts.append(policy.encode("utf-8") + b"\x00")
+        elif callable(policy):
+            # a callable has no canonical encoding — never hash its repr
+            parts.append(b"unhashable_custom\x00")
+            reason = (
+                f"value_policy[{name!r}] is a callable policy with no canonical "
+                "encoding, so the constraints fingerprint cannot pin it"
+            )
+        else:
+            parts.append(b"Grid\x00" + struct.pack("<dd", policy.step, policy.anchor))
+    return b"".join(parts), reason
+
+
+def constraints_fingerprint(explainer: Explainer) -> str:
+    """SHA-256 fingerprint of an explainer's effective objective and constraints.
+
+    Covers the compiled constraint set (type tags, resolved feature indices,
+    parameters), the distance normalizers ``sigma``, the per-feature
+    ``weights``, and every value-policy entry, all as canonical little-endian
+    bytes. A callable value policy has no canonical encoding: it is hashed as
+    a fixed ``unhashable_custom`` tag, and any certificate built from the
+    explainer records ``"reproducible": false`` with a reason.
+
+    Args:
+        explainer: The explainer whose constraint set to fingerprint.
+
+    Returns:
+        A 64-character SHA-256 hex digest.
+    """
+    encoding, _ = _constraints_encoding(explainer)
+    return hashlib.sha256(encoding).hexdigest()
+
+
+def _backend_of(stats: dict[str, object]) -> str:
+    """Recover which backend family produced a result from its own stats;
+    ``"unknown"`` when the stats identify neither family."""
+    if "completed" in stats:  # the exact backend always reports this key
+        return "exact"
+    if not stats or "generations" in stats:
+        return "genetic/python"
+    return "unknown"
+
+
+def _json_stats(stats: dict[str, object]) -> dict[str, object]:
+    """A JSON-safe copy of solver stats (numpy scalars unwrapped, floats
+    encoded per the non-finite rule, anything exotic stringified)."""
+    out: dict[str, object] = {}
+    for key, value in stats.items():
+        if isinstance(value, np.generic):
+            value = value.item()
+        if isinstance(value, bool | int | str):
+            out[key] = value
+        elif isinstance(value, float):
+            out[key] = _json_float(value)
+        else:
+            out[key] = repr(value)
+    return out
+
+
+def _region_points(
+    x_cf: FloatArray,
+    intervals: dict[str, tuple[float, float]],
+    feature_names: tuple[str, ...],
+) -> list[tuple[str, FloatArray]]:
+    """The finite point set a certificate verifies for a region (all corners
+    would be exponential): each widened feature's own two endpoints holding
+    every other coordinate at ``x_cf``, plus the all-lo and all-hi corners."""
+    index = {name: j for j, name in enumerate(feature_names)}
+    points: list[tuple[str, FloatArray]] = []
+    all_lo = x_cf.copy()
+    all_hi = x_cf.copy()
+    for name, (lo, hi) in intervals.items():
+        j = index[name]
+        for side, endpoint in (("lo", lo), ("hi", hi)):
+            point = x_cf.copy()
+            point[j] = endpoint
+            points.append((f"{name}={side}", point))
+        all_lo[j] = lo
+        all_hi[j] = hi
+    points.append(("all-lo", all_lo))
+    points.append(("all-hi", all_hi))
+    return points
+
+
+def _verify_plan(
+    explainer: Explainer,
+    x: FloatArray,
+    x_cf: FloatArray,
+    interval: tuple[float, float],
+    region_intervals: dict[str, tuple[float, float]] | None,
+) -> tuple[dict[str, object], list[str]]:
+    """Fresh verification of a plan: recomputed score, target membership, the
+    compiled constraint check, plausibility when configured, and the region's
+    sampled points. Returns the block and the names of any failed checks."""
+    score = raw_score(explainer.ir, x_cf)
+    in_target = bool(interval[0] <= score <= interval[1])
+    constraints_ok = bool(explainer.compiled.check_matrix(x_cf[None, :], x)[0])
+    verification: dict[str, object] = {
+        "score_raw": _json_float(score),
+        "in_target_interval": in_target,
+        "constraints_ok": constraints_ok,
+    }
+    failed = [
+        name
+        for name, ok in (("in_target_interval", in_target), ("constraints_ok", constraints_ok))
+        if not ok
+    ]
+    if explainer.plausibility is not None:
+        anomaly = explainer.plausibility.anomaly_score(x_cf)
+        plausibility_ok = bool(anomaly <= explainer.plausibility.max_anomaly_score + 1e-12)
+        verification["plausibility_ok"] = plausibility_ok
+        if not plausibility_ok:
+            failed.append("plausibility_ok")
+    if region_intervals is not None:
+        checked: list[dict[str, object]] = []
+        for label, point in _region_points(x_cf, region_intervals, explainer.ir.feature_names):
+            ok = explainer._verify(x, point, interval) is None
+            checked.append({"point": label, "ok": ok})
+            if not ok:
+                failed.append(f"region point {label}")
+        verification["region_points"] = checked
+    return verification, failed
+
+
+def _verify_infeasible(
+    explainer: Explainer, x: FloatArray, interval: tuple[float, float]
+) -> dict[str, object]:
+    """For an ``Infeasible`` there is no plan to verify — record only whether
+    the factual itself already sits outside the target interval."""
+    score = raw_score(explainer.ir, x)
+    return {
+        "factual_score_raw": _json_float(score),
+        "factual_in_target_interval": bool(interval[0] <= score <= interval[1]),
+    }
+
+
+def _target_block(
+    target: Target, band: str | None, explainer: Explainer
+) -> tuple[dict[str, object], tuple[float, float]]:
+    """The certificate's target block and the resolved raw interval."""
+    if target.bands_spec is not None:
+        if band is None:
+            raise TreecfError(
+                "certificate for a Target.bands result requires band= naming which "
+                "band the result belongs to"
+            )
+        by_name = {name: (lo, hi) for name, lo, hi in target.bands_spec}
+        if band not in by_name:
+            raise TreecfError(f"band {band!r} is not part of this Target.bands ladder")
+        lo, hi = by_name[band]
+        interval = target.band_intervals(explainer.ir.link)[band]
+    else:
+        if band is not None:
+            raise TreecfError("band= is only valid for a Target.bands ladder")
+        lo, hi = target.lo, target.hi
+        interval = target.raw_interval(explainer.ir.link)
+    block: dict[str, object] = {
+        "space": target.space,
+        "lo": _json_float(lo),
+        "hi": _json_float(hi),
+        "raw_interval": [_json_float(interval[0]), _json_float(interval[1])],
+    }
+    if band is not None:
+        block["band"] = band
+    if target.space == "calibrated":
+        block["calibrator"] = "external — not embedded"
+    return block, interval
+
+
+def build_certificate(
+    explainer: Explainer,
+    x: FloatArray,
+    result: Counterfactual | Infeasible,
+    target: Target,
+    *,
+    band: str | None = None,
+    seed: int | None = None,
+    node_budget: int | None = None,
+    gap: float | None = None,
+    time_budget_s: float | None = None,
+    warm_start: bool | None = None,
+) -> dict[str, object]:
+    """Body of ``Explainer.certificate``; see its docstring."""
+    from treecf import __version__
+    from treecf.api import Counterfactual
+
+    x = np.asarray(x, dtype=np.float64)
+    target_block, interval = _target_block(target, band, explainer)
+    _, reproducible_reason = _constraints_encoding(explainer)
+
+    model: dict[str, object] = {
+        "ir_fingerprint": ir_fingerprint(explainer.ir),
+        "feature_names": list(explainer.ir.feature_names),
+        "link": explainer.ir.link.name,
+    }
+    if explainer.plausibility is not None:
+        model["plausibility"] = {
+            "ir_fingerprint": ir_fingerprint(explainer.plausibility.if_ir),
+            "min_total_path": _json_float(explainer.plausibility.min_total_path),
+        }
+
+    declared: dict[str, object] = {}
+    if seed is not None:
+        declared["seed"] = seed
+    if node_budget is not None:
+        declared["node_budget"] = node_budget
+    if gap is not None:
+        declared["gap"] = _json_float(gap)
+    if time_budget_s is not None:
+        declared["time_budget_s"] = _json_float(time_budget_s)
+    if warm_start is not None:
+        declared["warm_start"] = warm_start
+    solve: dict[str, object] = {
+        "backend": _backend_of(result.solver_stats),
+        "proof": result.proof,
+        "solver_stats": _json_stats(result.solver_stats),
+    }
+    if declared:
+        solve["declared"] = declared
+
+    cert: dict[str, object] = {
+        "schema_version": 1,
+        "created_utc": datetime.now(UTC).isoformat(timespec="seconds"),
+        "treecf_version": __version__,
+        "reproducible": reproducible_reason is None,
+        "model": model,
+        "constraints": {
+            "fingerprint": constraints_fingerprint(explainer),
+            "listing": [repr(c) for c in explainer.compiled.constraints],
+        },
+        "target": target_block,
+        "solve": solve,
+        "factual": {"x": _encode_array(x)},
+    }
+    if reproducible_reason is not None:
+        cert["reproducible_reason"] = reproducible_reason
+
+    if isinstance(result, Counterfactual):
+        plan: dict[str, object] = {
+            "x_cf": _encode_array(result.x_cf),
+            "changes": {
+                name: [_json_float(src), _json_float(dst)]
+                for name, (src, dst) in result.changes.items()
+            },
+            "distance": _json_float(result.distance),
+            "snapped": dict(result.snapped),
+        }
+        region_intervals = None
+        if result.region is not None:
+            region_intervals = dict(result.region.feature_intervals)
+            plan["region_feature_intervals"] = {
+                name: [_json_float(lo), _json_float(hi)]
+                for name, (lo, hi) in region_intervals.items()
+            }
+        cert["plan"] = plan
+        verification, failed = _verify_plan(explainer, x, result.x_cf, interval, region_intervals)
+        if failed:
+            warnings.warn(
+                "certificate verification failed: " + ", ".join(failed)
+                + "; the certificate is issued with the failing checks recorded",
+                TreecfWarning,
+                stacklevel=3,  # build_certificate <- Explainer.certificate <- user code
+            )
+    else:
+        cert["infeasible"] = {"reason": result.reason, "proof": result.proof}
+        verification = _verify_infeasible(explainer, x, interval)
+    cert["verification"] = verification
+    return cert
+
+
+def check_certificate(explainer: Explainer, cert: dict[str, object]) -> dict[str, object]:
+    """Body of ``Explainer.check_certificate``; see its docstring."""
+    mismatches: list[str] = []
+
+    model = cert.get("model")
+    model_match = isinstance(model, dict) and model.get("ir_fingerprint") == ir_fingerprint(
+        explainer.ir
+    )
+    if not model_match:
+        mismatches.append("model fingerprint does not match this explainer's ensemble")
+    stored_plaus = model.get("plausibility") if isinstance(model, dict) else None
+    if explainer.plausibility is None:
+        if stored_plaus is not None:
+            model_match = False
+            mismatches.append(
+                "certificate declares a plausibility ensemble; this explainer has none"
+            )
+    elif not (
+        isinstance(stored_plaus, dict)
+        and stored_plaus.get("ir_fingerprint") == ir_fingerprint(explainer.plausibility.if_ir)
+    ):
+        model_match = False
+        mismatches.append("plausibility ensemble fingerprint does not match this explainer's")
+
+    constraints = cert.get("constraints")
+    constraints_match = (
+        isinstance(constraints, dict)
+        and constraints.get("fingerprint") == constraints_fingerprint(explainer)
+    )
+    if not constraints_match:
+        mismatches.append("constraints fingerprint does not match this explainer's constraint set")
+
+    verification_ok = True
+    try:
+        target = cert.get("target")
+        if not isinstance(target, dict):
+            raise TreecfError("certificate has no target block")
+        raw = target.get("raw_interval")
+        if not isinstance(raw, list) or len(raw) != 2:
+            raise TreecfError("certificate target block has no raw_interval")
+        interval = (_from_json_float(raw[0]), _from_json_float(raw[1]))
+        factual = cert.get("factual")
+        if not isinstance(factual, dict):
+            raise TreecfError("certificate has no factual block")
+        x = _decode_array(factual.get("x"))
+        plan = cert.get("plan")
+        if isinstance(plan, dict):
+            x_cf = _decode_array(plan.get("x_cf"))
+            intervals: dict[str, tuple[float, float]] | None = None
+            stored_intervals = plan.get("region_feature_intervals")
+            if isinstance(stored_intervals, dict):
+                intervals = {
+                    str(name): (_from_json_float(pair[0]), _from_json_float(pair[1]))
+                    for name, pair in stored_intervals.items()
+                }
+            _, failed = _verify_plan(explainer, x, x_cf, interval, intervals)
+            if failed:
+                verification_ok = False
+                mismatches.extend(f"verification failed: {name}" for name in failed)
+        else:
+            fresh = _verify_infeasible(explainer, x, interval)
+            stored = cert.get("verification")
+            stored_flag = stored.get("factual_in_target_interval") if isinstance(
+                stored, dict
+            ) else None
+            if stored_flag != fresh["factual_in_target_interval"]:
+                verification_ok = False
+                mismatches.append(
+                    "the recomputed factual-in-target check no longer matches the certificate"
+                )
+    except Exception as exc:  # a validator's tool reports; it never raises on bad input
+        verification_ok = False
+        mismatches.append(f"verification could not be re-run: {exc}")
+
+    return {
+        "model_match": model_match,
+        "constraints_match": constraints_match,
+        "verification_ok": verification_ok,
+        "mismatches": mismatches,
+    }

{treecf-0.2.1 → treecf-0.2.2}/src/treecf/batch.py

@@ -39,9 +39,10 @@ class BatchRecord:
     """One counterfactual (or the infeasibility marker) for one dataset row.
 
     Fields mirror ``Counterfactual`` (``x_cf``, ``changes``, ``distance``,
-    ``n_changed``, ``score_raw``, ``score_prob``, ``region``), plus batch
-    bookkeeping: ``id`` and ``k`` place the record in the dataset, and
-    ``feasible`` distinguishes a real plan from the infeasibility marker.
+    ``n_changed``, ``score_raw``, ``score_prob``, ``proof``, ``solver_stats``,
+    ``region``), plus batch bookkeeping: ``id`` and ``k`` place the record in
+    the dataset, and ``feasible`` distinguishes a real plan from the
+    infeasibility marker.
 
     Attributes:
         id: The row identifier this record belongs to (an element of
@@ -84,6 +85,14 @@ class BatchRecord:
         region: The certified box around ``x_cf``, set only when
             ``explain_batch`` ran with ``region=True`` and ``feasible`` is
             ``True``; ``None`` otherwise.
+        proof: The claim this record makes, mirroring the single-instance
+            result that produced it: ``Counterfactual.proof`` (``"heuristic"``
+            | ``"optimal"`` | ``"optimal_within_gap"``) for a feasible
+            record, ``Infeasible.proof`` (``"search_exhausted"`` |
+            ``"certified"``) for an infeasibility marker.
+        solver_stats: Exact-backend diagnostics for the solve behind this
+            record, same keys as ``Counterfactual.solver_stats``; empty for
+            genetic/python solves (those engines report no per-row stats).
     """
 
     id: object
@@ -99,6 +108,8 @@ class BatchRecord:
     blocked_lever: str | None = None  # diversity="lever-blocking": the frozen lever
     coalition: str | None = None  # diversity="coalitions": the group this plan may touch
     region: RecourseRegion | None = None  # set by explain_batch(..., region=True)
+    proof: str = "heuristic"  # mirrors Counterfactual.proof / Infeasible.proof
+    solver_stats: dict[str, object] = field(default_factory=dict)  # exact-backend only
 
 
 @dataclass(frozen=True)
@@ -180,6 +191,11 @@ class BatchResult:
                     "seed": record.seed,
                     "blocked_lever": record.blocked_lever,
                     "coalition": record.coalition,
+                    "proof": record.proof,
+                    "solver_stats": {
+                        key: encode_floats(value)
+                        for key, value in record.solver_stats.items()
+                    },
                     "region": (
                         None
                         if record.region is None
@@ -207,7 +223,9 @@ class BatchResult:
         A file saved without ``region=True``, or by a version of treecf
         before regions existed, loads with every record's ``region`` set to
         ``None``; a file saved before coalition support loads with every
-        record's ``coalition`` set to ``None``.
+        record's ``coalition`` set to ``None``; a file saved before per-record
+        proofs existed loads with ``proof`` defaulted by feasibility
+        (``"heuristic"``/``"search_exhausted"``) and empty ``solver_stats``.
 
         Args:
             path: Path to a file written by ``save``.
@@ -257,6 +275,14 @@ class BatchResult:
                     blocked_lever=raw["blocked_lever"],
                     coalition=raw.get("coalition"),  # absent in pre-coalition files
                     region=region,
+                    # pre-0.2.2 files carry neither field; default by feasibility
+                    proof=raw.get(
+                        "proof", "heuristic" if raw["feasible"] else "search_exhausted"
+                    ),
+                    solver_stats={
+                        key: decode_floats(value)
+                        for key, value in raw.get("solver_stats", {}).items()
+                    },
                 )
             )
         essential_ids = [decode_floats(k) for k in data.get("essential_lever_ids", [])]
@@ -271,11 +297,13 @@ class BatchResult:
     def to_frame(self) -> Any:
         """One row per (id, k), wide ``cf_<feature>`` columns (pandas, lazy import).
 
-        Every ``BatchRecord`` field except ``x_cf``/``changes``/``region``
-        becomes its own column; ``x_cf`` is spread into one ``cf_<feature>``
-        column per model feature (``NaN`` for an infeasible record, or an
-        unchanged feature's factual-equal value); ``changes`` is summarized as
-        a ``changed_features`` column (sorted feature names).
+        Every ``BatchRecord`` field except ``x_cf``/``changes``/``region``/
+        ``solver_stats`` becomes its own column (``solver_stats`` stays
+        record-only — read it off the ``BatchRecord`` directly); ``x_cf`` is
+        spread into one ``cf_<feature>`` column per model feature (``NaN`` for
+        an infeasible record, or an unchanged feature's factual-equal value);
+        ``changes`` is summarized as a ``changed_features`` column (sorted
+        feature names).
 
         Returns:
             A pandas ``DataFrame`` with one row per record.
@@ -300,6 +328,7 @@ class BatchResult:
                 "seed": record.seed,
                 "blocked_lever": record.blocked_lever,
                 "coalition": record.coalition,
+                "proof": record.proof,
                 "changed_features": sorted(record.changes),
             }
             for j, name in enumerate(self.feature_names):
@@ -540,6 +569,13 @@ def explain_batch(
     )
 
 
+def _exact_stats(stats: dict[str, object]) -> dict[str, object]:
+    """Stats worth mirroring onto a record: the exact backend's per-solve
+    diagnostics (recognized by their ``completed`` key). Genetic/python engine
+    stats are not mirrored — those engines report no per-row diagnostics."""
+    return stats if "completed" in stats else {}
+
+
 def _record_from(
     row_id: object,
     k: int,
@@ -563,14 +599,23 @@ def _record_from(
         blocked_lever=blocked_lever,
         coalition=coalition,
         region=region,
+        proof=cf.proof,
+        solver_stats=_exact_stats(cf.solver_stats),
     )
 
 
-def _infeasible_record(row_id: object, k: int = 0, coalition: str | None = None) -> BatchRecord:
+def _infeasible_record(
+    row_id: object,
+    k: int = 0,
+    coalition: str | None = None,
+    infeasible: Infeasible | None = None,
+) -> BatchRecord:
     return BatchRecord(
         id=row_id, k=k, feasible=False, x_cf=None, changes={},
         distance=None, n_changed=None, score_raw=None, score_prob=None,
         coalition=coalition,
+        proof="search_exhausted" if infeasible is None else infeasible.proof,
+        solver_stats={} if infeasible is None else _exact_stats(infeasible.solver_stats),
     )
 
 
@@ -860,8 +905,9 @@ def _rows_by_coalitions(
             records.append(_record_from(row_id, k, cf, coalition=name, region=reg))
             k += 1
         for name in solvers:
-            if not isinstance(outcomes[name][i], Counterfactual):
-                records.append(_infeasible_record(row_id, k=k, coalition=name))
+            outcome = outcomes[name][i]
+            if isinstance(outcome, Infeasible):
+                records.append(_infeasible_record(row_id, k=k, coalition=name, infeasible=outcome))
                 k += 1
     return records
 
@@ -888,9 +934,10 @@ def _row_by_seeds(
     ``warm_start=False`` alongside it, so a ``None`` incumbent -- an
     infeasible warm draw -- also runs unwarmed rather than falling back to a
     per-attempt genetic pass; see ``explain_batch``'s ``allow_exact_batch``)."""
-    from treecf.api import Counterfactual
+    from treecf.api import Counterfactual, Infeasible
 
     found: dict[frozenset[str], tuple[Counterfactual, int]] = {}
+    last_infeasible: Infeasible | None = None
     for attempt in range(_SEED_ATTEMPT_FACTOR * n_per_example):
         attempt_seed = master_seed + attempt
         result = explainer._explain(
@@ -905,8 +952,10 @@ def _row_by_seeds(
                 found[key] = (result, attempt_seed)
                 if len(found) == n_per_example:
                     break
+        elif isinstance(result, Infeasible):  # bands are rejected by explain_batch
+            last_infeasible = result
     if not found:
-        return [_infeasible_record(row_id)]
+        return [_infeasible_record(row_id, infeasible=last_infeasible)]
     ranked = sorted(found.values(), key=lambda pair: pair[0].distance)[:n_per_example]
     interval = target.raw_interval(explainer.ir.link) if region else None
     return [
@@ -947,7 +996,7 @@ def _row_by_lever_blocking(
         assert not isinstance(explained, dict)  # bands are rejected by explain_batch
         primary = explained
     if not isinstance(primary, Counterfactual):
-        return [_infeasible_record(row_id)], []
+        return [_infeasible_record(row_id, infeasible=primary)], []
 
     interval = target.raw_interval(explainer.ir.link) if region else None
     primary_region = (