track-certify 0.1.0__tar.gz

track_certify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Track-and-Certify authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

track_certify-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include examples *.py

track_certify-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: track-certify
+Version: 0.1.0
+Summary: Anytime joint certification of causal graphs and unknown intervention targets: certify-or-refuse sequential experiments with instance-optimal adaptive sampling
+Author: The Track-and-Certify authors
+License: MIT
+Project-URL: Homepage, https://pypi.org/project/track-certify/
+Keywords: causal-discovery,causal-inference,experimental-design,sequential-testing,e-process,anytime-valid,best-arm-identification,intervention-targets,fixed-confidence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# track-certify
+
+**Anytime joint certification of causal graphs and unknown intervention
+targets** — a certify-or-refuse layer for sequential causal experiments,
+with instance-optimal adaptive sampling.
+
+```bash
+pip install track-certify
+```
+
+Pure Python; depends only on `numpy` and `scipy`.
+
+## The problem it solves
+
+You run interventional experiments (gene perturbations, drug assays, A/B
+interventions) where **the perturbed variables themselves are uncertain**: a
+reagent may act off-target, weakly, or not at all. A causal conclusion is then
+a *joint* claim — the graph **and** each environment's intervention target —
+and every additional batch of samples costs money. Two questions matter more
+than any point estimate:
+
+1. **Where should the next observation be taken?**
+2. **When is it safe to stop and certify the joint answer at error level δ?**
+
+`track-certify` answers both with guarantees: an anytime-valid e-process
+stopping rule (no peeking penalty, no multiplicity correction), a no-regret
+allocation learner that provably attains the instance's information-theoretic
+sample requirement `T*`, and an exact assignment oracle that replaces
+factorial target enumeration with polynomial rectangular assignment. When it
+cannot certify — budget cap reached, or model preconditions infeasible — it
+**refuses rather than guesses**.
+
+## 60 seconds: certify a joint answer
+
+```python
+import numpy as np
+import track_certify as tc
+
+# Declare the class: 2 candidate graphs over a known covariance,
+# 2 environments with unknown, distinct targets of unknown amplitude.
+sigma = np.array([[1.0, 0.5],
+                  [0.5, 1.0]])
+model = tc.build_model(sigma, {"X->Y": (0, 1), "Y->X": (1, 0)})
+
+cert = tc.Certifier(model, n_environments=2, delta=0.01, cap=200_000)
+
+while True:
+    e = cert.next_environment()      # which environment to sample now
+    y = run_my_experiment(e)         # one fresh d-vector from environment e
+    out = cert.observe(y)
+    if out.stopped:
+        break
+
+out.certificate   # ("X->Y", (0, 1))  — graph + per-environment targets,
+                  # wrong with probability <= 0.01 under optional stopping;
+                  # None if out.refused (cap reached: refusal, not a guess)
+```
+
+The certifier never receives the true hypothesis, the amplitudes, `T*`, or
+the optimal allocation.
+
+## Before you sample: how hard is your instance?
+
+```python
+rep = tc.characteristic_time(model, ("X->Y", (0, 1)), amplitudes=(1.5, 1.2))
+rep.tstar          # first-order samples per unit log(1/delta)
+rep.w_star         # optimal budget split across environments
+rep.active_kinds   # which wrong answers dominate: 'graph' / 'target' / 'coupled'
+rep.budget(0.01)   # first-order sample estimate at delta = 0.01
+
+tax = tc.coupling_tax(model, ("X->Y", (0, 1)), (1.5, 1.2))
+tax.tax            # how much harder JOINT certification is than the harder
+                   # conditional problem — near the identifiability boundary
+                   # this diverges, and "estimate targets, then certify the
+                   # graph" becomes unboundedly suboptimal
+```
+
+## Unknown covariance: certify or refuse, with explicit constants
+
+```python
+obs = collect_observational_samples()          # (n0, d), no interventions
+try:
+    setup = tc.robust_certifier(
+        obs, {"X->Y": (0, 1), "Y->X": (1, 0)},
+        n_environments=2, delta=0.01, c_max=3.0)
+except tc.Refusal as r:
+    print("infeasible for this n0/delta/d/c_max:", r)   # pre-start refusal
+else:
+    cert = setup.certifier    # threshold already carries the certified
+                              # envelope inflation — nothing calibrated
+```
+
+## Benchmark instances with theorem-known difficulty
+
+```python
+inst = tc.solvable_instance(r=0.9)      # closed-form T*, coupled alternative
+                                        # provably active (paper Prop. 3)
+inst = tc.scalable_instance(rs=[0.8, 0.9], cs=[1.0, 1.2])
+                                        # additive T*, 2^m graphs (Cor. 1)
+res = tc.simulate(inst.model, inst.truth, inst.amplitudes, delta=1e-3,
+                  rng=np.random.default_rng(0))
+res.tau, res.correct                    # compare against inst.tstar_closed_form
+```
+
+Run `track-certify demo` for a self-contained certification demo, or
+`track-certify envelope --n0 500000 --delta 0.01 --d 3 --c-max 1.0` to check
+robust-mode feasibility from the command line.
+
+## Guarantees, precisely
+
+* **Validity.** With a correctly declared class and known covariance, the
+  returned joint answer is wrong with probability at most `delta`, under
+  arbitrary adaptive sampling and optional stopping (Gaussian mixture
+  e-process + Ville's inequality; no union bound over hypotheses).
+* **Optimality.** Expected stopping time satisfies
+  `E[tau]/log(1/delta) -> T*` as `delta -> 0` — the change-of-measure lower
+  bound for *any* delta-correct procedure, attained.
+* **Estimated covariance.** With the split-sample envelope, validity is exact
+  whenever the envelope's computable feasibility conditions hold; otherwise
+  the workflow refuses before starting. Efficiency degrades by explicit,
+  measured constant factors.
+* **Refusal semantics.** A reached cap or an infeasible envelope produces a
+  refusal, never a certificate. There is no procedure here that converts
+  arbitrary data into a certificate.
+
+**Model scope** (checked where checkable, refused when violated): finite
+declared graph class sharing one positive-definite covariance; mean-shift
+interventions with one unknown, distinct target per environment; Gaussian
+noise; no hidden confounding. Duplicate or ray-identical graph declarations
+are refused by default (they make hypotheses mutually uncertifiable).
+
+## Relation to the paper
+
+This package accompanies *Track-and-Certify: Anytime Joint Certification of
+Causal Graphs and Unknown Intervention Targets* (under review). The
+statistical core in `track_certify/_vendor/` is vendored **byte-identically**
+from the paper's audited evidence archive — the same code that produced every
+number in the paper — and `tests/test_equivalence.py` proves trajectory
+equivalence (identical actions, decisions, stopping times, and counts) between
+the streaming `Certifier` and the audited driver over shared noise tapes, on
+five instances under two allocation policies.
+
+## License
+
+MIT.

track_certify-0.1.0/README.md

@@ -0,0 +1,145 @@
+# track-certify
+
+**Anytime joint certification of causal graphs and unknown intervention
+targets** — a certify-or-refuse layer for sequential causal experiments,
+with instance-optimal adaptive sampling.
+
+```bash
+pip install track-certify
+```
+
+Pure Python; depends only on `numpy` and `scipy`.
+
+## The problem it solves
+
+You run interventional experiments (gene perturbations, drug assays, A/B
+interventions) where **the perturbed variables themselves are uncertain**: a
+reagent may act off-target, weakly, or not at all. A causal conclusion is then
+a *joint* claim — the graph **and** each environment's intervention target —
+and every additional batch of samples costs money. Two questions matter more
+than any point estimate:
+
+1. **Where should the next observation be taken?**
+2. **When is it safe to stop and certify the joint answer at error level δ?**
+
+`track-certify` answers both with guarantees: an anytime-valid e-process
+stopping rule (no peeking penalty, no multiplicity correction), a no-regret
+allocation learner that provably attains the instance's information-theoretic
+sample requirement `T*`, and an exact assignment oracle that replaces
+factorial target enumeration with polynomial rectangular assignment. When it
+cannot certify — budget cap reached, or model preconditions infeasible — it
+**refuses rather than guesses**.
+
+## 60 seconds: certify a joint answer
+
+```python
+import numpy as np
+import track_certify as tc
+
+# Declare the class: 2 candidate graphs over a known covariance,
+# 2 environments with unknown, distinct targets of unknown amplitude.
+sigma = np.array([[1.0, 0.5],
+                  [0.5, 1.0]])
+model = tc.build_model(sigma, {"X->Y": (0, 1), "Y->X": (1, 0)})
+
+cert = tc.Certifier(model, n_environments=2, delta=0.01, cap=200_000)
+
+while True:
+    e = cert.next_environment()      # which environment to sample now
+    y = run_my_experiment(e)         # one fresh d-vector from environment e
+    out = cert.observe(y)
+    if out.stopped:
+        break
+
+out.certificate   # ("X->Y", (0, 1))  — graph + per-environment targets,
+                  # wrong with probability <= 0.01 under optional stopping;
+                  # None if out.refused (cap reached: refusal, not a guess)
+```
+
+The certifier never receives the true hypothesis, the amplitudes, `T*`, or
+the optimal allocation.
+
+## Before you sample: how hard is your instance?
+
+```python
+rep = tc.characteristic_time(model, ("X->Y", (0, 1)), amplitudes=(1.5, 1.2))
+rep.tstar          # first-order samples per unit log(1/delta)
+rep.w_star         # optimal budget split across environments
+rep.active_kinds   # which wrong answers dominate: 'graph' / 'target' / 'coupled'
+rep.budget(0.01)   # first-order sample estimate at delta = 0.01
+
+tax = tc.coupling_tax(model, ("X->Y", (0, 1)), (1.5, 1.2))
+tax.tax            # how much harder JOINT certification is than the harder
+                   # conditional problem — near the identifiability boundary
+                   # this diverges, and "estimate targets, then certify the
+                   # graph" becomes unboundedly suboptimal
+```
+
+## Unknown covariance: certify or refuse, with explicit constants
+
+```python
+obs = collect_observational_samples()          # (n0, d), no interventions
+try:
+    setup = tc.robust_certifier(
+        obs, {"X->Y": (0, 1), "Y->X": (1, 0)},
+        n_environments=2, delta=0.01, c_max=3.0)
+except tc.Refusal as r:
+    print("infeasible for this n0/delta/d/c_max:", r)   # pre-start refusal
+else:
+    cert = setup.certifier    # threshold already carries the certified
+                              # envelope inflation — nothing calibrated
+```
+
+## Benchmark instances with theorem-known difficulty
+
+```python
+inst = tc.solvable_instance(r=0.9)      # closed-form T*, coupled alternative
+                                        # provably active (paper Prop. 3)
+inst = tc.scalable_instance(rs=[0.8, 0.9], cs=[1.0, 1.2])
+                                        # additive T*, 2^m graphs (Cor. 1)
+res = tc.simulate(inst.model, inst.truth, inst.amplitudes, delta=1e-3,
+                  rng=np.random.default_rng(0))
+res.tau, res.correct                    # compare against inst.tstar_closed_form
+```
+
+Run `track-certify demo` for a self-contained certification demo, or
+`track-certify envelope --n0 500000 --delta 0.01 --d 3 --c-max 1.0` to check
+robust-mode feasibility from the command line.
+
+## Guarantees, precisely
+
+* **Validity.** With a correctly declared class and known covariance, the
+  returned joint answer is wrong with probability at most `delta`, under
+  arbitrary adaptive sampling and optional stopping (Gaussian mixture
+  e-process + Ville's inequality; no union bound over hypotheses).
+* **Optimality.** Expected stopping time satisfies
+  `E[tau]/log(1/delta) -> T*` as `delta -> 0` — the change-of-measure lower
+  bound for *any* delta-correct procedure, attained.
+* **Estimated covariance.** With the split-sample envelope, validity is exact
+  whenever the envelope's computable feasibility conditions hold; otherwise
+  the workflow refuses before starting. Efficiency degrades by explicit,
+  measured constant factors.
+* **Refusal semantics.** A reached cap or an infeasible envelope produces a
+  refusal, never a certificate. There is no procedure here that converts
+  arbitrary data into a certificate.
+
+**Model scope** (checked where checkable, refused when violated): finite
+declared graph class sharing one positive-definite covariance; mean-shift
+interventions with one unknown, distinct target per environment; Gaussian
+noise; no hidden confounding. Duplicate or ray-identical graph declarations
+are refused by default (they make hypotheses mutually uncertifiable).
+
+## Relation to the paper
+
+This package accompanies *Track-and-Certify: Anytime Joint Certification of
+Causal Graphs and Unknown Intervention Targets* (under review). The
+statistical core in `track_certify/_vendor/` is vendored **byte-identically**
+from the paper's audited evidence archive — the same code that produced every
+number in the paper — and `tests/test_equivalence.py` proves trajectory
+equivalence (identical actions, decisions, stopping times, and counts) between
+the streaming `Certifier` and the audited driver over shared noise tapes, on
+five instances under two allocation policies.
+
+## License
+
+MIT.

track_certify-0.1.0/examples/01_certify_streaming.py

@@ -0,0 +1,22 @@
+"""Streaming certification on a two-graph class (known covariance)."""
+import numpy as np
+import track_certify as tc
+from track_and_certify_general import true_means  # vendored helper
+
+sigma = np.array([[1.0, 0.5], [0.5, 1.0]])
+model = tc.build_model(sigma, {"X->Y": (0, 1), "Y->X": (1, 0)})
+
+# Simulated lab: truth is X->Y with env targets (node0, node1), amplitudes (1.5, 1.2)
+truth, amps = ("X->Y", (0, 1)), (1.5, 1.2)
+rng = np.random.default_rng(7)
+chol = np.linalg.cholesky(sigma)
+means = true_means(model, truth, amps)
+
+cert = tc.Certifier(model, n_environments=2, delta=0.01, cap=100_000)
+while True:
+    e = cert.next_environment()
+    y = rng.normal(size=2) @ chol.T + means[e]      # your experiment here
+    out = cert.observe(y)
+    if out.stopped:
+        break
+print("certificate:", out.certificate, "| tau:", out.t, "| counts:", out.counts)

track_certify-0.1.0/examples/02_design_budget.py

@@ -0,0 +1,12 @@
+"""Pre-experiment design: T*, optimal allocation, coupling tax."""
+import track_certify as tc
+
+inst = tc.solvable_instance(r=0.9, c1=1.0, c2=1.0)
+rep = tc.characteristic_time(inst.model, inst.truth, inst.amplitudes)
+tax = tc.coupling_tax(inst.model, inst.truth, inst.amplitudes)
+print("T* (LP)        :", round(rep.tstar, 4), "| closed form:",
+      round(inst.tstar_closed_form, 4))
+print("optimal split  :", tuple(round(w, 3) for w in rep.w_star))
+print("active kinds   :", rep.active_kinds)
+print("coupling tax   :", round(tax.tax, 3))
+print("budget @ 1e-3  :", round(rep.budget(1e-3), 1), "samples (first order)")

track_certify-0.1.0/examples/03_robust_unknown_sigma.py

@@ -0,0 +1,19 @@
+"""Estimated-covariance workflow: certify or refuse with explicit constants."""
+import numpy as np
+import track_certify as tc
+
+rng = np.random.default_rng(0)
+sigma_true = np.array([[1.0, 0.5], [0.5, 1.0]])
+n0 = 600_000
+obs = rng.multivariate_normal(np.zeros(2), sigma_true, size=n0)
+
+try:
+    setup = tc.robust_certifier(obs, {"X->Y": (0, 1), "Y->X": (1, 0)},
+                                n_environments=2, delta=0.01, c_max=3.0)
+except tc.Refusal as r:
+    print("pre-start refusal:", r)
+else:
+    env = setup.envelope
+    print(f"feasible: eps={env.eps:.4f}, eta_bar={env.eta_bar:.4f}, "
+          f"beta_scale={env.beta_scale:.3f}, drift={env.beta_drift:.2e}/step")
+    print("certifier ready:", type(setup.certifier).__name__)

track_certify-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "track-certify"
+version = "0.1.0"
+description = "Anytime joint certification of causal graphs and unknown intervention targets: certify-or-refuse sequential experiments with instance-optimal adaptive sampling"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "The Track-and-Certify authors"}]
+keywords = [
+  "causal-discovery", "causal-inference", "experimental-design",
+  "sequential-testing", "e-process", "anytime-valid", "best-arm-identification",
+  "intervention-targets", "fixed-confidence",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Typing :: Typed",
+]
+dependencies = ["numpy>=1.22", "scipy>=1.8"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://pypi.org/project/track-certify/"
+
+[project.scripts]
+track-certify = "track_certify.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+track_certify = ["py.typed"]

track_certify-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

track_certify-0.1.0/src/track_certify/__init__.py

@@ -0,0 +1,49 @@
+"""track-certify: anytime joint certification of causal graphs and unknown
+intervention targets.
+
+Given a declared finite class of candidate causal graphs over a shared
+covariance, and K interventional environments whose targets and amplitudes
+are unknown, this package answers three questions with guarantees:
+
+* **Where to sample next, and when to stop.** :class:`Certifier` streams:
+  it emits the next environment to sample, consumes one fresh observation at
+  a time, and stops with a jointly certified (graph, target-vector) answer
+  whose error probability is at most ``delta`` under optional stopping -- or
+  with a refusal, never a guess.
+* **How hard the problem is, before sampling.** :func:`characteristic_time`
+  returns the instance's first-order sample requirement ``T*`` and the
+  optimal budget split across environments; :func:`coupling_tax` quantifies
+  how much harder joint certification is than its staged relaxations.
+* **What survives an estimated covariance.** :func:`certified_envelope` and
+  :func:`robust_certifier` implement the split-sample workflow with fully
+  explicit constants, refusing before starting when the envelope is
+  infeasible.
+
+Ready-made benchmark instances with theorem-known difficulty are in
+:func:`solvable_instance` and :func:`scalable_instance`; the audited
+simulation driver behind the paper's experiments is exposed as
+:func:`simulate`.
+
+The statistical core is vendored byte-identically from the audited research
+archive; ``tests/test_equivalence.py`` proves trajectory equivalence between
+the streaming interface and that driver.
+"""
+
+from .api import (Certifier, Envelope, Refusal, StepOutcome, build_model,
+                  certified_envelope)
+from .design import (CouplingReport, DesignReport, characteristic_time,
+                     coupling_tax)
+from .instances import Instance, scalable_instance, solvable_instance
+from .robust import RobustSetup, estimate_covariance, robust_certifier
+from . import _vendor  # noqa: F401
+from track_and_certify_general import run_general as simulate  # noqa: E402
+
+__all__ = [
+    "Certifier", "Envelope", "Refusal", "StepOutcome", "build_model",
+    "certified_envelope",
+    "DesignReport", "CouplingReport", "characteristic_time", "coupling_tax",
+    "Instance", "solvable_instance", "scalable_instance",
+    "RobustSetup", "estimate_covariance", "robust_certifier",
+    "simulate",
+]
+__version__ = "0.1.0"

track_certify-0.1.0/src/track_certify/_vendor/__init__.py

@@ -0,0 +1,58 @@
+"""Vendored audited modules, byte-identical to the paper's evidence archive.
+
+The four modules import one another by their original top-level names
+(``assignment_oracle``, ``best_alternative``, ``finite_ray_model``,
+``track_and_certify_general``).  To keep them byte-identical, this package
+loads them from files in dependency order and registers them in
+``sys.modules`` under those names -- **without** touching ``sys.path``, so
+nothing else on the import path is shadowed.
+
+If one of these names is already imported from somewhere else (a user module
+with the same name), loading raises ``ImportError`` immediately with an
+explanation instead of silently mixing implementations.  Each module is also
+registered under ``track_certify._vendor.<name>`` for unambiguous access.
+"""
+
+import importlib.util
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_ORDER = (
+    "assignment_oracle",
+    "best_alternative",
+    "finite_ray_model",
+    "track_and_certify_general",
+)
+
+
+def _load(name):
+    path = os.path.join(_HERE, name + ".py")
+    existing = sys.modules.get(name)
+    if existing is not None:
+        existing_file = getattr(existing, "__file__", None)
+        if existing_file is None or \
+                os.path.dirname(os.path.abspath(existing_file)) != _HERE:
+            raise ImportError(
+                f"track-certify vendors an audited module named {name!r}, "
+                f"but a different module with that name is already imported "
+                f"from {existing_file!r}. Import track_certify before the "
+                f"conflicting module, or rename it.")
+        return existing
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        del sys.modules[name]
+        raise
+    return module
+
+
+for _name in _ORDER:
+    _mod = _load(_name)
+    sys.modules[__name__ + "." + _name] = _mod
+    globals()[_name] = _mod
+
+del _name, _mod

track_certify-0.1.0/src/track_certify/_vendor/assignment_oracle.py

@@ -0,0 +1,100 @@
+"""Exact target-assignment oracle for joint graph--target certification.
+
+For a fixed graph, each row is an intervention environment and each column is
+a candidate target.  The certification loss is additive across rows and the
+main model requires distinct targets, so the best target vector is a
+rectangular linear assignment.  No hypothesis is pruned.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Hashable, Iterable, Optional, Sequence, Tuple
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+@dataclass(frozen=True)
+class AssignmentSolution:
+    cost: float
+    targets: Tuple[int, ...]
+
+
+def _checked_cost(cost: np.ndarray) -> np.ndarray:
+    arr = np.asarray(cost, dtype=float)
+    if arr.ndim != 2:
+        raise ValueError("cost must be a K-by-d matrix")
+    k, d = arr.shape
+    if k == 0 or k > d:
+        raise ValueError("distinct-target assignment requires 1 <= K <= d")
+    if np.isnan(arr).any():
+        raise ValueError("cost contains NaN")
+    return arr
+
+
+def best_assignment(
+    cost: np.ndarray,
+    forbidden_pairs: Iterable[Tuple[int, int]] = (),
+) -> Optional[AssignmentSolution]:
+    """Return the minimum-cost injective target vector, or None if infeasible."""
+
+    arr = _checked_cost(cost).copy()
+    for e, target in forbidden_pairs:
+        if not (0 <= e < arr.shape[0] and 0 <= target < arr.shape[1]):
+            raise ValueError("forbidden pair is outside the cost matrix")
+        arr[e, target] = np.inf
+    try:
+        rows, cols = linear_sum_assignment(arr)
+    except ValueError:
+        return None
+    if len(rows) != arr.shape[0] or not np.isfinite(arr[rows, cols]).all():
+        return None
+    targets = np.empty(arr.shape[0], dtype=int)
+    targets[rows] = cols
+    return AssignmentSolution(float(arr[rows, cols].sum()), tuple(targets.tolist()))
+
+
+def best_distinct_assignment(
+    cost: np.ndarray,
+    incumbent_targets: Sequence[int],
+) -> Optional[AssignmentSolution]:
+    """Return the best injective assignment different from the incumbent.
+
+    Every different assignment omits at least one incumbent row--target pair.
+    Solving K assignments, each forbidding one such pair, is therefore exact.
+    """
+
+    arr = _checked_cost(cost)
+    incumbent = tuple(int(t) for t in incumbent_targets)
+    if len(incumbent) != arr.shape[0] or len(set(incumbent)) != len(incumbent):
+        raise ValueError("incumbent_targets must be an injective K-vector")
+    if any(t < 0 or t >= arr.shape[1] for t in incumbent):
+        raise ValueError("incumbent target is outside the cost matrix")
+
+    best: Optional[AssignmentSolution] = None
+    for e, target in enumerate(incumbent):
+        candidate = best_assignment(arr, forbidden_pairs=((e, target),))
+        if candidate is not None and (best is None or candidate.cost < best.cost):
+            best = candidate
+    return best
+
+
+def best_wrong_hypothesis(
+    graph_costs: Dict[Hashable, np.ndarray],
+    incumbent_graph: Hashable,
+    incumbent_targets: Sequence[int],
+) -> Tuple[Hashable, AssignmentSolution]:
+    """Return the exact lowest-loss graph--target answer excluding incumbent."""
+
+    if incumbent_graph not in graph_costs:
+        raise ValueError("incumbent graph is absent from graph_costs")
+    answer = None
+    for graph, cost in graph_costs.items():
+        if graph == incumbent_graph:
+            solution = best_distinct_assignment(cost, incumbent_targets)
+        else:
+            solution = best_assignment(cost)
+        if solution is not None and (answer is None or solution.cost < answer[1].cost):
+            answer = (graph, solution)
+    if answer is None:
+        raise ValueError("the declared class contains no alternative hypothesis")
+    return answer