physmap 0.2.0__py3-none-any.whl

physmap/guardrail/weighting_heuristic.py

@@ -0,0 +1,216 @@
+"""Config-time observability weighting heuristic — the derived (not tuned) rule.
+
+Spec: docs/specs/PhysMAP_Ensemble_ConfigTime_Observability_Heuristic_Spec_v0_1.md
+
+Given ONLY config-time-legal inputs — the surrogate's declared inputs, the regime's
+resolved closures + their bound-variables, the Layer-2a observability_class, and (when
+a real vehicle has calibrated it) the Layer-2c partial_degree — assign each bound
+variable a detector-weight decision:
+
+    OBSERVABLE   → trust the BASELINE  (failure axis is a surrogate input; corpus redundant)
+    UNOBSERVABLE → trust the CORPUS    (baseline structurally blind; its silence is *expected*)
+    PARTIAL      → depends on degree_status:
+        uncalibrated, no lean → DEFER  (honest UNCERTAIN; no weight invented)
+        uncalibrated + lean   → LEAN   (qualitative physics default, NOT a measured weight)
+        calibrated            → GRADED (interpolate from the calibrated Layer-2c degree)
+
+The poles are fully determined from structure today; the PARTIAL middle is honestly
+deferred until a real vehicle calibrates its (regime, variable) degree, then graduates
+to a graded weight WITHOUT any rule change — the same heuristic just reads a richer corpus.
+
+DISCIPLINE (load-bearing): this module NEVER computes or estimates an observability
+score/degree. The graded weight comes ONLY from a calibrated Layer-2c degree read via
+`partial_degree_for()`; deriving a degree from structural inputs would fabricate an
+empirical quantity (the same error the mapping spec forbids). There is deliberately NO
+import of the cv_r2_knn estimator (`pipeline.observability`) anywhere in this module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from physmap.corpus.calibration import ClosureEntry
+from physmap.guardrail.classify import coord_input_aliases, load_default_corpus_index
+from physmap.guardrail.corpus_regimes import (
+    KNOWN_PARTIAL,
+    REGIME_TO_CLOSURES,
+    observability_class_for,
+    partial_degree_for,
+)
+from physmap.guardrail.enums import Observability, Regime
+
+
+# Half-width of the near-pole "collapse" zone on the observability axis. A JUDGMENT
+# CHOICE, not a fitted/tuned number: a calibrated degree within POLE_BAND of a pole is
+# treated AS that pole (corpus-trust near 0, baseline-trust near 1); strictly between,
+# the corpus fire is a calibrated SOFT-flag whose weight is scaled by (1 - degree).
+# Chosen deliberately coarse (0.15) so a single mid-range calibration cannot masquerade
+# as a hard pole; it is the one knob here and is meant to be revisited (not re-fit) as
+# the corpus accumulates more calibrated degrees.
+POLE_BAND = 0.15
+
+# weight_target vocabulary — the per-variable decision the aggregator consumes.
+WEIGHT_BASELINE = "baseline"
+WEIGHT_CORPUS = "corpus"
+WEIGHT_DEFER = "defer"
+WEIGHT_LEAN = "lean"
+WEIGHT_GRADED = "graded"
+
+# graded sub-lean — which pole behavior a calibrated degree resolves to.
+LEAN_CORPUS_TRUST = "corpus-trust"
+LEAN_BASELINE_TRUST = "baseline-trust"
+LEAN_SOFT_FLAG = "soft-flag"
+
+# Structural-lean hook (spec-optional). A qualitative physics-knowledge default for an
+# UNCALIBRATED known-partial cell — explicitly a LEAN pending confirmation, never a
+# measured weight, and overridden the instant a calibrated degree lands. EMPTY today
+# (no lean encoded) → the heuristic defers. When a real lean is authored it belongs
+# alongside the other corpus prerequisites in corpus_regimes.py.
+STRUCTURAL_LEAN_OVERRIDES: dict[tuple[str, str], str] = {}
+
+
+def structural_lean_for(closure_id: str, coord: str) -> str | None:
+    """The qualitative physics-knowledge lean for an uncalibrated known-partial cell,
+    or None (→ DEFER). Never a measured weight."""
+    return STRUCTURAL_LEAN_OVERRIDES.get((closure_id, coord))
+
+
+def _clamp01(x: float) -> float:
+    return 0.0 if x < 0.0 else 1.0 if x > 1.0 else float(x)
+
+
+def graded_weights(degree: float) -> tuple[float, float]:
+    """(w_baseline, w_corpus) for a calibrated partial degree.
+
+    POLARITY (load-bearing — guard against sign inversion): the observability degree
+    runs 0 = baseline blind (unobservable end) → 1 = baseline sees the axis (observable
+    end). So a HIGHER degree means MORE baseline weight:
+
+        w_baseline = degree,   w_corpus = 1 - degree
+
+    At the endpoints this reproduces the poles exactly:
+        graded_weights(0.0) == (0.0, 1.0)   # all corpus  (unobservable)
+        graded_weights(1.0) == (1.0, 0.0)   # all baseline (observable)
+    """
+    d = _clamp01(degree)
+    return d, 1.0 - d
+
+
+def graded_lean(degree: float) -> str:
+    """Which pole behavior a calibrated degree resolves to (the continuous-blend rule).
+
+    corpus-trust near the unobservable pole (degree <= POLE_BAND), baseline-trust near
+    the observable pole (degree >= 1 - POLE_BAND), else a calibrated soft-flag in between.
+    """
+    d = _clamp01(degree)
+    if d <= POLE_BAND:
+        return LEAN_CORPUS_TRUST
+    if d >= 1.0 - POLE_BAND:
+        return LEAN_BASELINE_TRUST
+    return LEAN_SOFT_FLAG
+
+
+@dataclass(frozen=True)
+class BoundWeightDecision:
+    """The config-time weight decision for one regime bound-variable. Inspectable: it
+    carries the class, the target, the (poles + graded) weights, the degree_status, and
+    the provenance, so the derived rule can be audited end-to-end."""
+    closure_id: str
+    coord: str
+    observability: Observability
+    weight_target: str             # baseline | corpus | defer | lean | graded
+    w_baseline: float | None       # set for poles + graded; None for defer/lean
+    w_corpus: float | None
+    degree_status: str             # n/a | uncalibrated | calibrated
+    partial_degree: float | None   # regime-resolved calibrated degree (graded only)
+    structural_lean: str | None    # corpus_lean | baseline_lean | neutral (lean target only)
+    calibrated_by: tuple[str, ...]
+    rationale: str
+
+
+def resolve_partial(
+    closure_id: str, coord: str, *, regime_value: str | None = None,
+) -> BoundWeightDecision:
+    """Weight decision for a PARTIAL (known-partial, absent) bound — the ONLY branch
+    that consults Layer-2c. Reads `partial_degree_for()`; never derives a degree.
+
+    The calibrated degree is regime-resolved: a degree calibrated for one regime must
+    not weight a deployment in a different regime, so a calibrated cell with no entry
+    for `regime_value` falls back to the honest uncalibrated behavior for this deployment.
+    """
+    degree_map, degree_status, calibrated_by = partial_degree_for(closure_id, coord)
+
+    degree: float | None = None
+    if degree_status == "calibrated" and degree_map:
+        degree = degree_map.get(regime_value) if regime_value is not None else None
+        if degree is None:
+            degree_status, calibrated_by = "uncalibrated", []  # not calibrated for THIS regime
+
+    if degree_status == "calibrated" and degree is not None:
+        w_b, w_c = graded_weights(degree)
+        lean = graded_lean(degree)
+        return BoundWeightDecision(
+            closure_id, coord, Observability.PARTIAL, WEIGHT_GRADED,
+            w_b, w_c, "calibrated", float(degree), None, tuple(calibrated_by),
+            f"partial graded: degree={degree:g} → (w_baseline={w_b:g}, w_corpus={w_c:g}), "
+            f"{lean}; calibrated_by={list(calibrated_by)}",
+        )
+
+    lean = structural_lean_for(closure_id, coord)
+    if lean is not None:
+        return BoundWeightDecision(
+            closure_id, coord, Observability.PARTIAL, WEIGHT_LEAN,
+            None, None, "uncalibrated", None, lean, (),
+            f"partial uncalibrated: applying labeled structural_lean={lean!r} "
+            f"(qualitative physics default, not a measured weight)",
+        )
+    return BoundWeightDecision(
+        closure_id, coord, Observability.PARTIAL, WEIGHT_DEFER,
+        None, None, "uncalibrated", None, None, (),
+        "partial uncalibrated: DEFER (UNCERTAIN) — no calibrated degree, no weight invented",
+    )
+
+
+def config_time_weights(
+    surrogate_inputs: Sequence[str],
+    regime: Regime,
+    corpus_index: dict[str, ClosureEntry] | None = None,
+) -> list[BoundWeightDecision]:
+    """The full per-bound weight table for a deployment — the inspectable derived rule.
+
+    Mirrors `classify_observability`'s structural step (same `coord_input_aliases` +
+    `observability_class_for` primitives, so the OBSERVABLE/PARTIAL/UNOBSERVABLE split
+    cannot diverge from the canonical classifier) and additionally attaches the weight
+    decision + provenance per bound. PARTIAL delegates to `resolve_partial` (the only
+    Layer-2c read). UNLISTED (or no resolved closures) → [] → statistical-only.
+    """
+    if corpus_index is None:
+        corpus_index = load_default_corpus_index()
+    out: list[BoundWeightDecision] = []
+    if regime is Regime.UNLISTED:
+        return out
+    inputs = set(surrogate_inputs)
+    for closure_id in REGIME_TO_CLOSURES.get(regime, ()):
+        entry = corpus_index.get(closure_id)
+        if entry is None:
+            continue
+        for bound in entry.validated_range:
+            coord = bound.coord
+            if any(a in inputs for a in coord_input_aliases(coord)):
+                out.append(BoundWeightDecision(
+                    closure_id, coord, Observability.OBSERVABLE, WEIGHT_BASELINE,
+                    1.0, 0.0, "n/a", None, None, (),
+                    "observable: failure axis is a surrogate input → baseline sees the "
+                    "failure region; corpus redundant",
+                ))
+            elif observability_class_for(closure_id, coord) == KNOWN_PARTIAL:
+                out.append(resolve_partial(closure_id, coord, regime_value=regime.value))
+            else:
+                out.append(BoundWeightDecision(
+                    closure_id, coord, Observability.UNOBSERVABLE, WEIGHT_CORPUS,
+                    0.0, 1.0, "n/a", None, None, (),
+                    "unobservable: failure axis absent + structural-binary → baseline "
+                    "blind; trust corpus (its silence is expected, not reassuring)",
+                ))
+    return out

physmap/infra/__init__.py

@@ -0,0 +1,23 @@
+"""Cross-cutting infrastructure shared across the architecture refactor and
+the broader physmap system. Grouped under one subpackage during R7 of
+the cleanup.
+
+Modules:
+  corpus_runtime    — Entry + corpus_error_magnitude (used by
+                       pipeline.detectors.CorpusDetector)
+  gate_runner       — generic gate-running orchestration
+  gates             — gate definitions
+  ledger            — append-only run ledger (12 consumers — load-bearing)
+  metrics           — generic metrics helpers
+  physics_causal    — physics-side causal/non-causal split
+  physics_synth     — physics synthesis
+  schema            — shared schema definitions
+  stage1_adapter    — Stage-1 adapter
+  stage1_harness    — Stage-1 harness
+
+These modules are kept INSIDE the package (not archived) because they
+have widely-distributed consumers. The infra subpackage isolates them
+from the architecture refactor's canonical surface so a reader can tell
+"new architecture" (pipeline / substrate / corpus / closures) from
+"shared old infrastructure" (this subpackage) at a glance.
+"""

physmap/infra/blindspot_oracle.py

@@ -0,0 +1,356 @@
+"""PhysMAP Step 0 (S0.1) — two-mechanism hemolysis apparatus (truth + closures + surrogate).
+
+The constructed-but-physically-motivated truth/closure pair for the blind-spot pilot.
+Two distinguishable hemolysis mechanisms feed one QoI (the hemolysis index HI):
+
+  shear damage    S(tau)  — instantaneous, driven by shear stress tau
+  exposure damage E(t)    — cumulative, driven by residence time t
+  HI = S + E              — additive, so the mechanism contributions stay separable
+
+Each mechanism's TRUTH saturates (hemolysis saturates as cells are destroyed); each
+CLOSURE is a power-law fit on its own calibration box only (tracks truth in-box,
+OVERSHOOTS beyond — truth saturates, the power-law does not). A surrogate is trained on
+the closure across the full envelope, so it is confident even in the extrapolation
+region where the closure is wrong. That confident-but-wrong region is the candidate
+blind spot.
+
+Parameters are chosen so (a) the closures fit their box well, (b) extrapolation error is
+material at plausible saturation, and (c) materiality genuinely FLIPS across the grid
+(shear dominates at high tau, exposure at low-tau/high-t) — the precondition for the
+causal-vs-naive lift to be testable. The choice is VERIFIED by coherence_report(), not
+eyeballed (same discipline as the synthesizer coupling fix).
+
+Torch-free: numpy + scikit-learn only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+# ── operating envelope (normalized shear tau, normalized residence time t) ────
+# box = calibration region (closures fit here); envelope = surrogate training span.
+TAU_LO, TAU_CAL_S, TAU_HI = 1.0, 3.0, 6.0
+T_LO, T_CAL_E, T_HI = 1.0, 3.0, 6.0
+
+# ── truth: saturating exponential per mechanism ───────────────────────────────
+# 1 - exp(-(k x^a)) is power-law-like (~ k x^a) below the box edge so a power-law
+# closure fits the box, and bends toward the ceiling beyond it.
+# Shear grows STEEPLY (as=2.0) and its in-box closure coefficient (Cs ≈ SMAX*KS)
+# DOMINATES exposure's (Ce ≈ EMAX*KE), so at high tau shear carries HI and exposure
+# is immaterial even when out-of-box (the disc band). Exposure grows SHALLOWLY
+# (ae=1.3) but reaches far in t, so at LOW tau / HIGH t (small shear) exposure
+# dominates and is material — materiality genuinely FLIPS across the grid.
+SMAX, KS, AS = 1.0, 0.12, 2.0       # Cs ≈ 0.12
+EMAX, KE, AE = 0.40, 0.08, 1.3      # Ce ≈ 0.032  (< Cs → immaterial at high tau)
+
+THETA_MAT = 0.20    # a mechanism is "material" if its closure contribution fraction >= this
+TOL = 0.05          # trustworthy if |HI_sur - HI_true| / (SMAX+EMAX) <= this
+N_TRAIN = 300       # surrogate training points across the full envelope
+K_ENSEMBLE = 10     # bootstrap ensemble size (guardrail variance signal)
+GRID_N = 26         # query grid is GRID_N x GRID_N over the envelope
+
+
+def s_true(tau: np.ndarray) -> np.ndarray:
+    return SMAX * (1.0 - np.exp(-(KS * np.asarray(tau, float) ** AS)))
+
+
+def e_true(t: np.ndarray) -> np.ndarray:
+    return EMAX * (1.0 - np.exp(-(KE * np.asarray(t, float) ** AE)))
+
+
+def hi_true(tau: np.ndarray, t: np.ndarray) -> np.ndarray:
+    return s_true(tau) + e_true(t)
+
+
+def fit_power_law(x: np.ndarray, y: np.ndarray) -> tuple[float, float]:
+    """Log-linear least squares: y = C * x**alpha  ->  log y = log C + alpha log x."""
+    lx, ly = np.log(np.asarray(x, float)), np.log(np.asarray(y, float))
+    alpha, logC = np.polyfit(lx, ly, 1)
+    return float(np.exp(logC)), float(alpha)
+
+
+@dataclass
+class Closures:
+    """The two power-law closures, each fit on its own calibration box."""
+    Cs: float
+    alphas: float
+    Ce: float
+    alphae: float
+
+    def s_clo(self, tau: np.ndarray) -> np.ndarray:
+        return self.Cs * np.asarray(tau, float) ** self.alphas
+
+    def e_clo(self, t: np.ndarray) -> np.ndarray:
+        return self.Ce * np.asarray(t, float) ** self.alphae
+
+    def hi_clo(self, tau: np.ndarray, t: np.ndarray) -> np.ndarray:
+        return self.s_clo(tau) + self.e_clo(t)
+
+
+def fit_closures(n_box: int = 40, seed: int = 0) -> Closures:
+    """Fit each power-law closure to truth samples drawn ONLY from its calibration box."""
+    rng = np.random.default_rng(seed)
+    tau_box = rng.uniform(TAU_LO, TAU_CAL_S, n_box)
+    t_box = rng.uniform(T_LO, T_CAL_E, n_box)
+    Cs, alphas = fit_power_law(tau_box, s_true(tau_box))
+    Ce, alphae = fit_power_law(t_box, e_true(t_box))
+    return Closures(Cs, alphas, Ce, alphae)
+
+
+def _make_gp():
+    from sklearn.gaussian_process import GaussianProcessRegressor
+    from sklearn.gaussian_process.kernels import RBF, ConstantKernel, WhiteKernel
+    # WhiteKernel fixed (not optimized) → no convergence-to-bound warning, deterministic.
+    kernel = (ConstantKernel(1.0) * RBF(length_scale=[1.0, 1.0])
+              + WhiteKernel(noise_level=1e-6, noise_level_bounds="fixed"))
+    return GaussianProcessRegressor(kernel=kernel, normalize_y=True, alpha=1e-8,
+                                    n_restarts_optimizer=0, random_state=0)
+
+
+@dataclass
+class Surrogate:
+    """GP fit to the CLOSURE across the full envelope + a K-member bootstrap ensemble.
+    The surrogate approximates the closure (confident everywhere trained); its error vs
+    truth is dominated by the closure's extrapolation error — the point of the pilot."""
+    members: list = field(default_factory=list)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        return self.members[0].predict(np.asarray(X, float))
+
+    def ensemble_variance(self, X: np.ndarray) -> np.ndarray:
+        preds = np.stack([m.predict(np.asarray(X, float)) for m in self.members], axis=0)
+        return preds.var(axis=0)
+
+
+def train_surrogate(closures: Closures, n_train: int = N_TRAIN, k: int = K_ENSEMBLE,
+                    seed: int = 0, box_only: bool = False) -> tuple[Surrogate, np.ndarray]:
+    """Train K surrogates on bootstrap resamples of N_train closure evaluations.
+    members[0] is the full-sample fit (the point predictor); the rest are bootstrap
+    members for the ensemble-variance guardrail. Returns (surrogate, X_train).
+
+    box_only=False → train across the full envelope (the deployed surrogate; confident
+    even in the extrapolation region — the blind spot). box_only=True → train ONLY on the
+    calibration box (the CONTROL arm: a correctly-scoped surrogate whose guardrails, when
+    recomputed against this box-only training distribution, should flag the extrapolation
+    region the full-envelope surrogate's guardrails miss)."""
+    rng = np.random.default_rng(seed)
+    tau_max = TAU_CAL_S if box_only else TAU_HI
+    t_max = T_CAL_E if box_only else T_HI
+    Xtr = np.column_stack([rng.uniform(TAU_LO, tau_max, n_train),
+                           rng.uniform(T_LO, t_max, n_train)])
+    ytr = closures.hi_clo(Xtr[:, 0], Xtr[:, 1])
+    members = []
+    full = _make_gp()
+    full.fit(Xtr, ytr)
+    members.append(full)
+    for b in range(k - 1):
+        idx = rng.integers(0, n_train, n_train)         # bootstrap resample
+        m = _make_gp()
+        m.fit(Xtr[idx], ytr[idx])
+        members.append(m)
+    return Surrogate(members), Xtr
+
+
+def query_grid(grid_n: int = GRID_N) -> np.ndarray:
+    """Query points over the full envelope. A regular grid spans all four regions; a
+    targeted refinement block deliberately populates the disc band (high tau IN box ×
+    just-over-box t), where exposure is out-of-calibration but immaterial. Populating it
+    by construction is explicitly allowed (the spec: "populate it deliberately"); the
+    coherence report verifies those points are genuinely immaterial AND trustworthy."""
+    taus = np.linspace(TAU_LO, TAU_HI, grid_n)
+    ts = np.linspace(T_LO, T_HI, grid_n)
+    base = np.array([[a, b] for a in taus for b in ts], float)
+    # disc-band refinement: tau in the upper third of the box, t just beyond the box edge
+    d_tau = np.linspace(TAU_LO + 0.6 * (TAU_CAL_S - TAU_LO), TAU_CAL_S, 7)
+    d_t = np.linspace(T_CAL_E + 0.15, T_CAL_E + 1.4, 7)
+    disc = np.array([[a, b] for a in d_tau for b in d_t], float)
+    return np.vstack([base, disc])
+
+
+@dataclass
+class Dataset:
+    """All per-query-point quantities the pilot reasons over."""
+    X: np.ndarray            # (n, 2) [tau, t]
+    hi_true: np.ndarray
+    hi_clo: np.ndarray
+    hi_sur: np.ndarray
+    c_s: np.ndarray          # closure shear contribution
+    c_e: np.ndarray          # closure exposure contribution
+    in_cal_s: np.ndarray     # tau <= TAU_CAL_S
+    in_cal_e: np.ndarray     # t <= T_CAL_E
+    material_e: np.ndarray   # c_e / (c_s + c_e) >= THETA_MAT  (closure-based)
+    material_s: np.ndarray   # c_s / (c_s + c_e) >= THETA_MAT  (closure-based)
+    closures: Closures
+    surrogate: Surrogate
+    X_train: np.ndarray
+
+
+def build_dataset(seed: int = 0, grid_n: int = GRID_N, theta_mat: float = THETA_MAT,
+                  box_only: bool = False) -> Dataset:
+    """box_only=False → the deployed full-envelope surrogate (default, the main pilot).
+    box_only=True → the control-arm surrogate trained only on the calibration box; the
+    oracle, closures, grid, and all closure-derived fields are IDENTICAL — only the
+    surrogate's training distribution (and hence hi_sur + X_train) changes."""
+    closures = fit_closures(seed=seed)
+    surrogate, Xtr = train_surrogate(closures, seed=seed, box_only=box_only)
+    X = query_grid(grid_n)
+    tau, t = X[:, 0], X[:, 1]
+    c_s, c_e = closures.s_clo(tau), closures.e_clo(t)
+    total = c_s + c_e
+    return Dataset(
+        X=X, hi_true=hi_true(tau, t), hi_clo=closures.hi_clo(tau, t),
+        hi_sur=surrogate.predict(X), c_s=c_s, c_e=c_e,
+        in_cal_s=tau <= TAU_CAL_S, in_cal_e=t <= T_CAL_E,
+        material_e=(c_e / total) >= theta_mat, material_s=(c_s / total) >= theta_mat,
+        closures=closures, surrogate=surrogate, X_train=Xtr,
+    )
+
+
+# ── specificity-cell substrate (ensemble experiment, vehicle (a)) ────────────
+# Tighter calibration box than the default — leaves a benign out-of-envelope band.
+TAU_CAL_S_SPEC = 2.0
+T_CAL_E_SPEC = 2.0
+
+
+class _QuietSurrogate:
+    """Stub surrogate for the specificity STAND-IN: predicts closure exactly and
+    reports zero ensemble variance. Keeps the guardrail signals silent on the
+    out-of-envelope band where truth ≡ closure (the spec's 'baseline FA ≈ 0 by cell
+    definition' premise). Duck-types Surrogate's interface used by pilot_compute."""
+
+    def __init__(self, closures: "Closures") -> None:
+        self._closures = closures
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        X = np.asarray(X, float)
+        return self._closures.hi_clo(X[:, 0], X[:, 1])
+
+    def ensemble_variance(self, X: np.ndarray) -> np.ndarray:
+        return np.zeros(len(np.asarray(X, float)))
+
+
+def build_specificity_dataset(seed: int = 0, grid_n: int = GRID_N,
+                              theta_mat: float = THETA_MAT,
+                              tau_cal: float = TAU_CAL_S_SPEC,
+                              t_cal: float = T_CAL_E_SPEC) -> Dataset:
+    """Specificity-cell synthetic substrate for the ensemble experiment (STAND-IN).
+
+    Builds a Dataset where:
+      - truth ≡ closure ≡ surrogate everywhere (err = 0 by construction; trustworthy.all())
+      - the surrogate is a quiet stub (exact closure, zero ensemble variance) so the
+        guardrail signals stay silent — matches the spec's 'baseline FA ≈ 0 by cell
+        definition' premise; a GP-trained surrogate's variance would fire on
+        out-of-envelope points even when truth tracks closure, contaminating the
+        baseline reading.
+      - the calibration box is tightened (tau_cal, t_cal) so the query grid contains a
+        BENIGN OUT-OF-ENVELOPE band: points beyond the box have closure tracking truth
+        but are flagged out-of-calibration by naive/causal.
+      - materiality (c_s, c_e fractions) varies across the band — some out-of-envelope
+        rows are causal-firing (material out-of-cal mechanism), some causal-silent
+        (immaterial out-of-cal mechanism); both must be present for H-harm to be
+        empirically falsifiable.
+
+    Status: STAND-IN — the EMPIRICAL upgrade is vehicle (b), a grounded convection
+    sub-range where the correlation is inside its validated range across a
+    materiality-varying sweep.
+    """
+    closures = fit_closures(seed=seed)
+    surrogate = _QuietSurrogate(closures)
+    X = query_grid(grid_n)
+    tau, t = X[:, 0], X[:, 1]
+    c_s, c_e = closures.s_clo(tau), closures.e_clo(t)
+    total = c_s + c_e
+    # Clip closure to the saturating bound. The corpus_runtime PDE-residual signal
+    # checks hi_sur > BOUND (SMAX + EMAX) as a physics constraint; the algebraic
+    # closures overshoot this bound at high (tau, t), which would fire the PDE arm
+    # as a spurious baseline FA in the specificity cell where truth tracks closure
+    # by definition. Clipping hi_sur AND hi_clo to BOUND preserves truth ≡ closure
+    # (both clip to the same value) while keeping the PDE signal silent.
+    bound = SMAX + EMAX
+    hi_clo_raw = closures.hi_clo(tau, t)
+    hi_clo_arr = np.clip(hi_clo_raw, 0.0, bound)
+    # truth ≡ closure ≡ surrogate everywhere (the specificity condition)
+    hi_true_arr = hi_clo_arr.copy()
+    hi_sur_arr = hi_clo_arr.copy()
+    # Uniform training reference for the OOD guardrail self-calibration. Sampling
+    # over the same envelope as the query keeps maha distances comparable, so
+    # baseline guardrails fire only on the ~5% Mahalanobis tail.
+    rng = np.random.default_rng(seed)
+    Xtr = np.column_stack([
+        rng.uniform(TAU_LO, TAU_HI, N_TRAIN),
+        rng.uniform(T_LO, T_HI, N_TRAIN),
+    ])
+    return Dataset(
+        X=X, hi_true=hi_true_arr, hi_clo=hi_clo_arr,
+        hi_sur=hi_sur_arr, c_s=c_s, c_e=c_e,
+        in_cal_s=tau <= tau_cal, in_cal_e=t <= t_cal,
+        material_e=(c_e / total) >= theta_mat, material_s=(c_s / total) >= theta_mat,
+        closures=closures, surrogate=surrogate, X_train=Xtr,
+    )
+
+
+def coherence_report(ds: Dataset | None = None, seed: int = 0) -> dict:
+    """Verify the construction is sound (not manufactured): box fit good, extrapolation
+    error material, materiality flips, disc_region populated + genuinely trustworthy."""
+    if ds is None:
+        ds = build_dataset(seed=seed)
+    tau, t = ds.X[:, 0], ds.X[:, 1]
+    scale = SMAX + EMAX
+
+    # box-fit quality (max relative residual inside each box)
+    box_tau = np.linspace(TAU_LO, TAU_CAL_S, 50)
+    box_t = np.linspace(T_LO, T_CAL_E, 50)
+    s_box_res = float(np.max(np.abs(ds.closures.s_clo(box_tau) - s_true(box_tau)) / SMAX))
+    e_box_res = float(np.max(np.abs(ds.closures.e_clo(box_t) - e_true(box_t)) / EMAX))
+
+    # extrapolation error (closure vs truth) at the far corner
+    far = np.abs(ds.closures.hi_clo(np.array([TAU_HI]), np.array([T_HI]))
+                 - hi_true(np.array([TAU_HI]), np.array([T_HI])))[0] / scale
+
+    err = np.abs(ds.hi_sur - ds.hi_true) / scale
+    trustworthy = err <= TOL
+
+    # disc_region = exactly one mechanism out-of-box AND that mechanism not material
+    exactly_one_out = (ds.in_cal_s ^ ds.in_cal_e)
+    # the out-of-box mechanism: if exposure out (not in_cal_e) it must be immaterial
+    exp_out_immaterial = (~ds.in_cal_e) & ds.in_cal_s & (~ds.material_e)
+    shear_out_immaterial = (~ds.in_cal_s) & ds.in_cal_e & (~ds.material_s)
+    disc = exp_out_immaterial | shear_out_immaterial
+
+    return {
+        "box_fit_max_rel_residual": {"shear": round(s_box_res, 4), "exposure": round(e_box_res, 4)},
+        "extrapolation_error_far_corner": round(float(far), 4),
+        "closure_alphas": round(ds.closures.alphas, 3),
+        "closure_alphae": round(ds.closures.alphae, 3),
+        "n_grid": len(ds.X),
+        "materiality_flip": {
+            "frac_exposure_material": round(float(ds.material_e.mean()), 3),
+            "frac_shear_material": round(float(ds.material_s.mean()), 3),
+        },
+        "region_counts": {
+            "both_in": int((ds.in_cal_s & ds.in_cal_e).sum()),
+            "exactly_one_out": int(exactly_one_out.sum()),
+            "both_out": int((~ds.in_cal_s & ~ds.in_cal_e).sum()),
+            "disc_region": int(disc.sum()),
+        },
+        "disc_region": {
+            "n": int(disc.sum()),
+            "frac_trustworthy": round(float(trustworthy[disc].mean()), 3) if disc.any() else None,
+            "mean_exposure_materiality": round(float((ds.c_e / (ds.c_s + ds.c_e))[disc].mean()), 3)
+            if disc.any() else None,
+        },
+        "n_untrustworthy": int((~trustworthy).sum()),
+    }
+
+
+def main(argv=None) -> int:
+    import json
+    print("PhysMAP Step 0 — oracle coherence report\n")
+    print(json.dumps(coherence_report(), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())