physmap 0.2.0__py3-none-any.whl

physmap/pipeline/observability.py

@@ -0,0 +1,430 @@
+"""Observability score — how recoverable a vehicle's failure-driving variable
+is from its surrogate inputs, over the failure region. 0 (orthogonal, NACA-like
+— only the literature corpus can see the failure) → 1 (on-axis, Forrest-like —
+the failure axis IS an input, so baselines see it and the corpus is redundant).
+
+LOCKED DEFAULT + INTERFACE; MIDDLE SCORES PROVISIONAL
+-----------------------------------------------------
+The locked default estimator is cross-validated R² of a k-NN regression of the
+standardized failure variable on the standardized surrogate inputs, clipped to
+[0,1] (`cv_r2_knn`). The estimator is a pluggable strategy; `max_spearman` and
+`nmi_kraskov` are cross-checks.
+
+CV-R² conflates "the failure variable IS an input" with "the failure variable
+is recoverable in THIS dataset." These coincide at the poles (NACA orthogonal
+by design → 0; Forrest Re is an input → 1) but can diverge in the middle, where
+the score becomes sampling-dependent. Therefore:
+
+  * `cross_estimator_agreement` checks all three estimators agree on pole
+    placement (NACA ≈ 0, Forrest ≡ 1) — agreement is what licenses the lock.
+  * `subsampling_stability` resamples the region and flags a score `provisional`
+    if it is unstable — a middle vehicle's score is not trusted until it passes.
+    Poles pass naturally (orthogonal → stably ~0; degenerate → exactly 1).
+
+The measure is locked in `physmap/results/prereg/observability_v0_1.json`
+before any vehicle is classified, so the axis is not tuned to the verdicts it
+is later plotted against.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace as dc_replace
+from typing import Sequence
+
+import numpy as np
+
+from physmap.pipeline.detectors import extract_features_batch
+from physmap.pipeline.vehicle_spec import vehicle_spec
+from physmap.substrate.engine import build_substrate
+from physmap.substrate.vehicle_config import load_named_vehicle
+
+
+# ── locked parameters (mirror observability_v0_1.json) ──────────────────────
+
+DEFAULT_ESTIMATOR = "cv_r2_knn"
+RNG_SEED = 20260605
+K_NEIGHBORS = 5
+SMALL_N_MIN = 5            # n < this -> no CV, in-sample fallback
+CV_MIN_N = 8              # SMALL_N_MIN <= n < this -> LOO; else 5-fold
+DEFAULT_STABILITY_TOLERANCE = 0.15   # subsampling std bar for "stable"
+POLE_AGREEMENT_TOLERANCE = 0.25      # cross-estimator spread bar at the poles
+
+# A failure-driving variable (a meta key) would appear in the surrogate-input
+# space under one of these standardized feature names. If any is an input, the
+# failure axis is directly observable → observability ≡ 1 by definition.
+_FAILURE_VAR_INPUT_ALIASES: dict[str, tuple[str, ...]] = {
+    "Re": ("log10_Re", "Re"),
+    "x_over_D": ("x_over_D", "log10_x_over_D"),
+    "Dh_um": ("log10_Dh_mm", "Dh_um", "Dh_mm"),
+    "Ri": ("Ri", "log10_Ri"),
+}
+
+
+# ── result schemas ──────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class ObservabilityResult:
+    score: float                 # in [0, 1] (NaN only for an empty region)
+    estimator_name: str
+    n_region: int
+    degenerate_on_axis: bool     # failure var IS a surrogate input
+    raw_statistic: float | None  # pre-clip statistic (None if degenerate)
+    notes: str
+    provisional: bool = False    # middle-vehicle score not yet stability-confirmed
+    stability: dict | None = None
+
+    def as_dict(self) -> dict:
+        return {
+            "score": self.score, "estimator": self.estimator_name,
+            "n_region": self.n_region, "degenerate_on_axis": self.degenerate_on_axis,
+            "raw_statistic": self.raw_statistic, "notes": self.notes,
+            "provisional": self.provisional, "stability": self.stability,
+        }
+
+
+@dataclass(frozen=True)
+class StabilityResult:
+    mean: float
+    std: float
+    spread_p5_p95: float
+    n_boot: int
+    tolerance: float
+    stable: bool
+    estimator_name: str
+    notes: str = ""
+
+    def as_dict(self) -> dict:
+        return {
+            "mean": self.mean, "std": self.std, "spread_p5_p95": self.spread_p5_p95,
+            "n_boot": self.n_boot, "tolerance": self.tolerance, "stable": self.stable,
+            "estimator": self.estimator_name, "notes": self.notes,
+        }
+
+
+# ── estimators (pluggable strategies; cv_r2_knn is the locked default) ───────
+
+def _zscore(M: np.ndarray) -> np.ndarray:
+    M = np.asarray(M, dtype=float)
+    mu = M.mean(axis=0)
+    sd = M.std(axis=0)
+    sd = np.where(sd == 0.0, 1.0, sd)
+    return (M - mu) / sd
+
+
+def _est_cv_r2_knn(Y: np.ndarray, X: np.ndarray, rng_seed: int,
+                   k_neighbors: int = K_NEIGHBORS) -> tuple[float, str]:
+    """Cross-validated R² of k-NN regression: failure var ~ surrogate inputs.
+
+    This is "fraction of the failure variable's variance recoverable from the
+    inputs." 0 when inputs carry no info (NACA: x/D varies at fixed Re,Pr →
+    negative R² → clipped to 0). Robust at small n via an LOO / in-sample
+    ladder.
+    """
+    from sklearn.neighbors import KNeighborsRegressor
+    from sklearn.model_selection import KFold, LeaveOneOut, cross_val_score
+    from sklearn.metrics import r2_score
+
+    n = len(Y)
+    Xs = _zscore(X)
+    Ys = _zscore(Y.reshape(-1, 1)).ravel()
+
+    if n < SMALL_N_MIN:
+        k = min(k_neighbors, max(1, n - 1))
+        model = KNeighborsRegressor(n_neighbors=k)
+        model.fit(Xs, Ys)
+        r2 = float(r2_score(Ys, model.predict(Xs)))   # optimistic in-sample
+        return r2, f"cv_r2_knn:small_n_in_sample(n={n},k={k})"
+
+    if n < CV_MIN_N:
+        # LOO: each train fold is all-but-one — no sorted-data fold artifact.
+        splitter = LeaveOneOut()
+        k = min(k_neighbors, max(1, n - 2))             # train fold has n-1 pts
+        note = f"cv_r2_knn:loo(n={n},k={k})"
+    else:
+        # SHUFFLED 5-fold. Without shuffle, KFold makes contiguous folds, which
+        # on Re-sorted rows become extrapolation blocks and wreck R^2 — a fold
+        # artifact, not a property of the data. Shuffle (seeded) fixes it.
+        splitter = KFold(n_splits=5, shuffle=True, random_state=rng_seed)
+        k = min(k_neighbors, max(1, (n - n // 5) - 1))
+        note = f"cv_r2_knn:5fold_shuffled(n={n},k={k})"
+
+    model = KNeighborsRegressor(n_neighbors=k)
+    scores = cross_val_score(model, Xs, Ys, cv=splitter, scoring="r2")
+    return float(np.mean(scores)), note
+
+
+def _est_max_spearman(Y: np.ndarray, X: np.ndarray, rng_seed: int,
+                      k_neighbors: int = K_NEIGHBORS) -> tuple[float, str]:
+    """Max |Spearman rho| between the failure var and any single input.
+    Cheapest, most robust at tiny n; per-input + monotone-only cross-check."""
+    import warnings
+    from scipy.stats import ConstantInputWarning, spearmanr
+    best = 0.0
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", ConstantInputWarning)
+        for j in range(X.shape[1]):
+            rho, _ = spearmanr(X[:, j], Y)   # NaN if a column is constant
+            if not np.isnan(rho):
+                best = max(best, abs(float(rho)))
+    return best, "max_abs_spearman"
+
+
+def _est_nmi_kraskov(Y: np.ndarray, X: np.ndarray, rng_seed: int,
+                     k_neighbors: int = 3) -> tuple[float, str]:
+    """Kraskov k-NN mutual information (per input), mapped to a correlation-
+    equivalent on [0,1) via the Gaussian relation rho = sqrt(1 - exp(-2·MI)).
+    A nonlinear-dependence cross-check; uses the strongest single input as a
+    lower bound on joint recoverability."""
+    from sklearn.feature_selection import mutual_info_regression
+    n = len(Y)
+    mi = mutual_info_regression(
+        X, Y, n_neighbors=min(k_neighbors, max(1, n - 1)), random_state=rng_seed,
+    )
+    mi_max = float(np.max(mi)) if len(mi) else 0.0
+    nmi = float(np.sqrt(1.0 - np.exp(-2.0 * max(0.0, mi_max))))
+    return nmi, "nmi_kraskov_gaussian_equiv(max_input)"
+
+
+ESTIMATORS = {
+    "cv_r2_knn": _est_cv_r2_knn,
+    "max_spearman": _est_max_spearman,
+    "nmi_kraskov": _est_nmi_kraskov,
+}
+
+
+# ── core score ───────────────────────────────────────────────────────────────
+
+def observability_score(
+    rows: Sequence,
+    failure_var: str,
+    surrogate_inputs: Sequence[str],
+    region_mask: np.ndarray | None = None,
+    estimator: str = DEFAULT_ESTIMATOR,
+    *,
+    rng_seed: int = RNG_SEED,
+    k_neighbors: int = K_NEIGHBORS,
+) -> ObservabilityResult:
+    """Observability of `failure_var` from `surrogate_inputs` over the region.
+
+    Order of operations:
+      1. Restrict to the region (region_mask, or all rows).
+      2. Degenerate check: if the failure variable IS a surrogate input,
+         return 1.0 without fitting (Forrest path).
+      3. Otherwise run the estimator; clip the raw statistic to [0,1].
+    """
+    if estimator not in ESTIMATORS:
+        raise ValueError(f"unknown estimator {estimator!r}; choices: {sorted(ESTIMATORS)}")
+
+    if region_mask is not None:
+        region_mask = np.asarray(region_mask, dtype=bool)
+        region_rows = [r for r, m in zip(rows, region_mask) if m]
+    else:
+        region_rows = list(rows)
+    n = len(region_rows)
+
+    # Degenerate (on-axis) check — purely structural, independent of the data.
+    aliases = _FAILURE_VAR_INPUT_ALIASES.get(failure_var, (failure_var,))
+    inputs = tuple(surrogate_inputs)
+    hit = next((a for a in aliases if a in inputs), None)
+    if hit is not None:
+        return ObservabilityResult(
+            score=1.0, estimator_name=estimator, n_region=n,
+            degenerate_on_axis=True, raw_statistic=None,
+            notes=(f"failure var {failure_var!r} is a surrogate input "
+                   f"(as {hit!r}); observability = 1 by definition"),
+        )
+
+    if n < 3:
+        return ObservabilityResult(
+            score=float("nan"), estimator_name=estimator, n_region=n,
+            degenerate_on_axis=False, raw_statistic=None,
+            notes=f"region too small to estimate (n={n} < 3)",
+        )
+
+    Y = np.array([float(r.meta[failure_var]) for r in region_rows], dtype=float)
+    if float(np.std(Y)) == 0.0:
+        # Failure var constant over the region → nothing to recover; treat as
+        # orthogonal (no information gradient for the inputs to track).
+        return ObservabilityResult(
+            score=0.0, estimator_name=estimator, n_region=n,
+            degenerate_on_axis=False, raw_statistic=0.0,
+            notes=f"failure var {failure_var!r} constant over region; score=0",
+        )
+
+    X = extract_features_batch([r.meta for r in region_rows], list(surrogate_inputs))
+    raw, note = ESTIMATORS[estimator](Y, X, rng_seed, k_neighbors)
+    score = float(np.clip(raw, 0.0, 1.0))
+    return ObservabilityResult(
+        score=score, estimator_name=estimator, n_region=n,
+        degenerate_on_axis=False, raw_statistic=float(raw), notes=note,
+    )
+
+
+# ── per-vehicle convenience wrapper ──────────────────────────────────────────
+
+def vehicle_observability(
+    vehicle_id: str,
+    *,
+    estimator: str = DEFAULT_ESTIMATOR,
+    region: str = "failure",
+    csv_override: str | None = None,
+    check_stability: bool = False,
+    stability_tolerance: float = DEFAULT_STABILITY_TOLERANCE,
+    rng_seed: int = RNG_SEED,
+) -> ObservabilityResult:
+    """Observability of a named vehicle. Uses `vehicle_spec()` so the region is
+    the SAME failure region the Stage-1 sweep evaluates (D1/D2 must agree)."""
+    cfg = load_named_vehicle(vehicle_id)
+    if csv_override is not None:
+        from dataclasses import replace as _dc
+        cfg = _dc(cfg, data_source=_dc(cfg.data_source, path=csv_override))
+    spec = vehicle_spec(cfg)
+    rows, _, _ = build_substrate(cfg)
+
+    if region == "failure":
+        mask = np.array([spec.split.test_predicate(r.meta) for r in rows], dtype=bool)
+    elif region == "all":
+        mask = np.ones(len(rows), dtype=bool)
+    else:
+        raise ValueError(f"region must be 'failure' or 'all', got {region!r}")
+
+    res = observability_score(
+        rows, spec.failure_var, spec.baseline_feature_names,
+        region_mask=mask, estimator=estimator, rng_seed=rng_seed,
+    )
+
+    # Stability gate: non-degenerate vehicles only. Poles pass naturally
+    # (orthogonal → stably ~0), so no hardcoded pole-exemption list is needed.
+    if check_stability and not res.degenerate_on_axis and res.n_region >= 4:
+        region_rows = [r for r, m in zip(rows, mask) if m]
+        stab = subsampling_stability(
+            region_rows, spec.failure_var, spec.baseline_feature_names,
+            estimator=estimator, tolerance=stability_tolerance, rng_seed=rng_seed,
+        )
+        res = dc_replace(res, provisional=(not stab.stable), stability=stab.as_dict())
+    return res
+
+
+# ── estimator-validity checks (gate whether the axis means anything) ─────────
+
+def subsampling_stability(
+    region_rows: Sequence,
+    failure_var: str,
+    surrogate_inputs: Sequence[str],
+    *,
+    estimator: str = DEFAULT_ESTIMATOR,
+    n_boot: int = 200,
+    frac: float = 0.8,
+    tolerance: float = DEFAULT_STABILITY_TOLERANCE,
+    rng_seed: int = RNG_SEED,
+) -> StabilityResult:
+    """Resample the failure region (subsample `frac` without replacement) and
+    recompute the score `n_boot` times. A score is `stable` if its bootstrap
+    std is within `tolerance` — distinguishing physics-observability (stable
+    under resampling) from a sampling-design artifact (unstable). This is the
+    required gate before a MIDDLE vehicle's score is trusted on the axis."""
+    n = len(region_rows)
+    if n < 4:
+        return StabilityResult(
+            mean=float("nan"), std=float("nan"), spread_p5_p95=float("nan"),
+            n_boot=0, tolerance=tolerance, stable=False, estimator_name=estimator,
+            notes=f"region too small to bootstrap (n={n} < 4)",
+        )
+    rng = np.random.default_rng(rng_seed)
+    size = max(3, int(round(frac * n)))
+    scores: list[float] = []
+    for b in range(n_boot):
+        idx = rng.choice(n, size=size, replace=False)
+        sub = [region_rows[i] for i in idx]
+        r = observability_score(
+            sub, failure_var, surrogate_inputs,
+            estimator=estimator, rng_seed=rng_seed + b + 1,
+        )
+        if not np.isnan(r.score):
+            scores.append(r.score)
+    arr = np.array(scores, dtype=float)
+    std = float(np.std(arr))
+    spread = float(np.percentile(arr, 95) - np.percentile(arr, 5))
+    return StabilityResult(
+        mean=float(np.mean(arr)), std=std, spread_p5_p95=spread,
+        n_boot=len(scores), tolerance=tolerance, stable=(std <= tolerance),
+        estimator_name=estimator,
+        notes=f"subsample frac={frac} without replacement",
+    )
+
+
+def cross_estimator_agreement(
+    vehicle_id: str,
+    *,
+    estimators: Sequence[str] = ("cv_r2_knn", "max_spearman", "nmi_kraskov"),
+    region: str = "failure",
+    tolerance: float = POLE_AGREEMENT_TOLERANCE,
+    csv_override: str | None = None,
+) -> dict:
+    """Run every estimator on a pole and check they agree on its placement
+    (spread within `tolerance`). Agreement at the endpoints is what licenses
+    the locked default — if the estimator choice changed the score, it would
+    be the estimator, not the physics, doing the work."""
+    scores = {
+        est: vehicle_observability(
+            vehicle_id, estimator=est, region=region, csv_override=csv_override,
+        ).score
+        for est in estimators
+    }
+    vals = [v for v in scores.values() if not np.isnan(v)]
+    spread = (max(vals) - min(vals)) if vals else float("nan")
+    return {
+        "vehicle_id": vehicle_id, "region": region, "scores": scores,
+        "spread": spread, "tolerance": tolerance,
+        "agree": bool(vals and spread <= tolerance),
+    }
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Compute a vehicle's observability score (0=orthogonal, 1=on-axis)."
+    )
+    parser.add_argument("vehicle_id", help="e.g. naca_tn1451, forrest")
+    parser.add_argument("--estimator", default=DEFAULT_ESTIMATOR, choices=sorted(ESTIMATORS))
+    parser.add_argument("--region", default="failure", choices=["failure", "all"])
+    parser.add_argument("--stability", action="store_true",
+                        help="run the subsampling-stability gate (sets provisional)")
+    parser.add_argument("--agreement", action="store_true",
+                        help="report cross-estimator pole-agreement instead")
+    parser.add_argument("--csv-override", default=None)
+    args = parser.parse_args(argv)
+
+    if args.agreement:
+        rep = cross_estimator_agreement(
+            args.vehicle_id, region=args.region, csv_override=args.csv_override,
+        )
+        print(f"cross-estimator agreement for {args.vehicle_id} ({args.region} region):")
+        for est, sc in rep["scores"].items():
+            print(f"  {est:>14}: {sc:.4f}")
+        print(f"  spread={rep['spread']:.4f}  agree={rep['agree']} (tol={rep['tolerance']})")
+        return 0
+
+    res = vehicle_observability(
+        args.vehicle_id, estimator=args.estimator, region=args.region,
+        csv_override=args.csv_override, check_stability=args.stability,
+    )
+    print(f"vehicle:    {args.vehicle_id}")
+    print(f"estimator:  {res.estimator_name}")
+    print(f"region n:   {res.n_region}")
+    print(f"degenerate: {res.degenerate_on_axis}")
+    print(f"raw stat:   {res.raw_statistic}")
+    print(f"SCORE:      {res.score:.4f}")
+    print(f"provisional:{res.provisional}")
+    if res.stability:
+        s = res.stability
+        print(f"stability:  std={s['std']:.4f} (tol={s['tolerance']}) stable={s['stable']}")
+    print(f"notes:      {res.notes}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

physmap/pipeline/surrogate.py

@@ -0,0 +1,251 @@
+"""PhysMAP D3 — explicit Surrogate class for the real-surrogate protocol.
+
+Per prereg v0.3 (locked 2026-06-05): the surrogate is an explicit
+first-class object trained on a defined set, with .predict() and
+.predict_variance() methods. The GP-variance baseline is the surrogate's
+own posterior std — NOT a separately-fit GP. This removes the E1
+ambiguity by making "what the surrogate predicts" a measurable quantity
+distinct from baseline detectors.
+
+Locked v0.3 choices:
+  - Model class: GP (sklearn GaussianProcessRegressor)
+  - Mean function: neutral (constant; normalize_y=True; NOT closure-as-mean)
+  - Inputs: (log10_Re, Pr) — surrogate inputs locked in prereg
+  - Kernel: one of {matern_5_2, matern_3_2, rbf} — selected per v0.4 screen
+  - Training set: fully-developed (x/D >= 10) ONLY; developing never in
+    training (per non-negotiable #2)
+
+Surrogate-error categorization (locked v0.3, threshold values deferred
+to v0.4 per calibration formulas):
+  ACCURATE: error <= accuracy_threshold (do-no-harm cell input)
+  MARGINAL: accuracy_threshold < error <= lift_threshold (dead band)
+  WRONG:    error > lift_threshold (lift target)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Sequence
+
+import numpy as np
+
+from sklearn.gaussian_process import GaussianProcessRegressor
+from sklearn.gaussian_process.kernels import (
+    Matern, RBF, ConstantKernel, WhiteKernel,
+)
+
+
+ErrorBucket = Literal["ACCURATE", "MARGINAL", "WRONG"]
+
+KERNEL_MENU_V0_3 = ("matern_5_2", "matern_3_2", "rbf")
+
+
+def make_kernel(kernel_name: str, n_features: int):
+    """Build a sklearn kernel from the v0.3-locked menu."""
+    if kernel_name == "matern_5_2":
+        inner = Matern(length_scale=[1.0]*n_features,
+                        length_scale_bounds=(1e-2, 1e2), nu=2.5)
+    elif kernel_name == "matern_3_2":
+        inner = Matern(length_scale=[1.0]*n_features,
+                        length_scale_bounds=(1e-2, 1e2), nu=1.5)
+    elif kernel_name == "rbf":
+        inner = RBF(length_scale=[1.0]*n_features,
+                    length_scale_bounds=(1e-2, 1e2))
+    else:
+        raise ValueError(f"Unknown kernel '{kernel_name}'; must be one of "
+                          f"{KERNEL_MENU_V0_3}")
+    return (
+        ConstantKernel(constant_value=1.0, constant_value_bounds=(1e-3, 1e3))
+        * inner
+        + WhiteKernel(noise_level=1.0, noise_level_bounds=(1e-5, 1e2))
+    )
+
+
+@dataclass
+class Surrogate:
+    """Explicit surrogate trained on a defined set.
+
+    Per prereg v0.3: the surrogate is a GP with NEUTRAL mean (normalize_y=True
+    centers training y; equivalent to a constant prior mean), one of the
+    locked kernels, fit on training_X (n_train × n_features) + training_y.
+
+    .predict(test_X) returns the surrogate's prediction (the practitioner's
+    deployed prediction). .predict_variance(test_X) returns the surrogate's
+    own posterior std — this IS the GP-variance baseline (no separate fit).
+    """
+    training_X: np.ndarray
+    training_y: np.ndarray
+    kernel_name: str = "matern_5_2"
+    n_restarts: int = 3
+    random_state: int = 20260605
+
+    _gp: GaussianProcessRegressor = field(init=False, default=None)
+    _n_features: int = field(init=False, default=0)
+
+    def __post_init__(self):
+        n, d = self.training_X.shape
+        if n < 2:
+            raise ValueError(f"Surrogate needs >= 2 training points, got {n}")
+        self._n_features = d
+        kernel = make_kernel(self.kernel_name, d)
+        self._gp = GaussianProcessRegressor(
+            kernel=kernel,
+            normalize_y=True,        # constant-mean prior via training-y centering
+            n_restarts_optimizer=self.n_restarts,
+            random_state=self.random_state,
+        )
+        self._gp.fit(self.training_X, self.training_y)
+
+    @property
+    def n_train(self) -> int:
+        return len(self.training_y)
+
+    @property
+    def fitted_kernel(self):
+        return self._gp.kernel_
+
+    def predict(self, test_X: np.ndarray) -> np.ndarray:
+        """Surrogate's prediction (posterior mean) at each test point."""
+        return self._gp.predict(test_X, return_std=False)
+
+    def predict_variance(self, test_X: np.ndarray) -> np.ndarray:
+        """Surrogate's posterior std at each test point.
+        This IS the GP-variance baseline (no separate fit per prereg v0.3)."""
+        _, std = self._gp.predict(test_X, return_std=True)
+        return std
+
+    def predict_relative_variance(self, test_X: np.ndarray) -> np.ndarray:
+        """Posterior std divided by surrogate predicted mean magnitude.
+        The relative variance is what the GP-variance detector reports."""
+        mean, std = self._gp.predict(test_X, return_std=True)
+        floor = max(1.0, float(np.abs(self.training_y).mean()) * 0.01)
+        return std / np.maximum(np.abs(mean), floor)
+
+
+# ── surrogate error analysis ────────────────────────────────────────────────
+
+@dataclass
+class SurrogateError:
+    """Per-test-point surrogate prediction vs measured Nu, with categorization."""
+    test_X: np.ndarray
+    predicted_Nu: np.ndarray         # surrogate's prediction
+    measured_Nu: np.ndarray          # ground truth at test point
+    accuracy_threshold_pct: float    # ACCURATE iff |error|/|measured| <= this
+    lift_threshold_pct: float        # WRONG iff |error|/|measured| > this
+
+    @property
+    def abs_error(self) -> np.ndarray:
+        return np.abs(self.predicted_Nu - self.measured_Nu)
+
+    @property
+    def rel_error_pct(self) -> np.ndarray:
+        return self.abs_error / np.maximum(np.abs(self.measured_Nu), 1e-9) * 100.0
+
+    def bucket(self) -> list[ErrorBucket]:
+        """Per-point bucket: ACCURATE / MARGINAL / WRONG."""
+        rel_pct = self.rel_error_pct
+        buckets: list[ErrorBucket] = []
+        for r in rel_pct:
+            if r <= self.accuracy_threshold_pct:
+                buckets.append("ACCURATE")
+            elif r > self.lift_threshold_pct:
+                buckets.append("WRONG")
+            else:
+                buckets.append("MARGINAL")
+        return buckets
+
+    def is_accurate(self) -> np.ndarray:
+        return self.rel_error_pct <= self.accuracy_threshold_pct
+
+    def is_wrong(self) -> np.ndarray:
+        return self.rel_error_pct > self.lift_threshold_pct
+
+
+# ── threshold calibration (from prereg-locked formulas) ──────────────────────
+
+@dataclass
+class ThresholdCalibration:
+    """Implements the prereg-locked calibration formulas.
+
+    sigma_combined := sqrt(paper_unc_pct² + dig_unc_pct²) measured from dev
+    accuracy_threshold := 2.0 × sigma_combined  (ACCURATE iff <=)
+    lift_threshold     := 3.0 × sigma_combined  (WRONG iff >)
+
+    Per user-directed decomposition (2026-06-05):
+      paper_uncertainty_pct = 3.0  (NACA TN-1451 line 329 REPRODUCIBILITY,
+        explicit text: 'reproducibility of values of fc was found to be
+        within 3 percent'). NOT 5%; the 5% is the MAX TOTAL EXPERIMENTAL
+        ERROR (different statistic that includes systematic + reading +
+        calibration bias on top of reproducibility). For sigma_combined
+        we use the per-measurement noise floor (3% reproducibility), which
+        is the right object to combine with digitization noise.
+      digitization_uncertainty_pct = MEASURED FROM WPD per-marker scatter
+        in the asymptotic region (where the true value is ~flat so
+        observed scatter is mostly digitization noise + paper-noise).
+        Use `dig_unc_from_observed_asymptotic_cv()` for the proper
+        quadrature-subtraction with the floor.
+      visual-vs-WPD delta: used to VERIFY the dig_unc estimate, NOT to
+        re-derive total noise from the figure (that would conflate
+        the two sources — the paper already gave us paper_unc).
+
+    v0.4 plugs in WPD-measured dig_unc; v0.4 may NOT change formulas.
+    """
+    paper_uncertainty_pct: float = 3.0          # NACA TN-1451 reproducibility (line 329)
+    digitization_uncertainty_pct: float = 3.0   # WPD typical default; v0.4 sets from data
+    wpd_instrument_precision_floor_pct: float = 1.0  # WPD's stated reading precision
+
+    @staticmethod
+    def dig_unc_from_observed_asymptotic_cv(
+        observed_asymptotic_cv_pct: float,
+        paper_unc_pct: float = 3.0,
+        wpd_instrument_floor_pct: float = 1.0,
+    ) -> tuple[float, str]:
+        """Compute dig_unc by quadrature-subtracting paper noise from observed.
+
+        Per user 2026-06-05 directive (prevents imaginary-sqrt crash):
+        if the WPD asymptotic CV is ≤ paper_unc, the quadrature subtraction
+        sqrt(CV² − paper²) would go imaginary. That's NOT 'negative noise';
+        it's 'asymptotic scatter is below the paper-noise resolution floor'.
+        In that case, fall back to the WPD instrument's stated reading
+        precision (default 1%) as the dig_unc floor.
+
+        Returns (dig_unc_pct, regime_tag) where regime_tag describes
+        which branch was taken (informational, not used in calibration).
+        """
+        if observed_asymptotic_cv_pct > paper_unc_pct:
+            # Normal regime: scatter dominated by dig noise above paper floor
+            dig_unc = float(np.sqrt(observed_asymptotic_cv_pct ** 2 -
+                                     paper_unc_pct ** 2))
+            return dig_unc, "above_paper_floor"
+        else:
+            # Quiet asymptote regime: scatter ≤ paper noise; use WPD instrument floor
+            return wpd_instrument_floor_pct, "below_paper_floor_use_instrument_precision"
+
+    @property
+    def sigma_combined(self) -> float:
+        return float(np.sqrt(self.paper_uncertainty_pct ** 2 +
+                              self.digitization_uncertainty_pct ** 2))
+
+    @property
+    def accuracy_threshold_pct(self) -> float:
+        return 2.0 * self.sigma_combined
+
+    @property
+    def lift_threshold_pct(self) -> float:
+        return 3.0 * self.sigma_combined
+
+    @property
+    def dead_band_pct(self) -> tuple[float, float]:
+        return (self.accuracy_threshold_pct, self.lift_threshold_pct)
+
+    # Gate 1 derived thresholds (per locked formulas)
+    @property
+    def gate_1_median_fd_holdout_error_pct_max(self) -> float:
+        return 2.0 * self.sigma_combined
+
+    @property
+    def gate_1_p95_fd_holdout_error_pct_max(self) -> float:
+        return max(25.0, 3.0 * self.sigma_combined)
+
+    def gate_1_median_gp_relative_std_max(self, train_y: np.ndarray) -> float:
+        return 0.5 * float(train_y.std()) / max(float(np.abs(train_y).mean()), 1e-9)