physmap 0.2.0__py3-none-any.whl

physmap/pipeline/validity_signal.py

@@ -0,0 +1,273 @@
+"""PhysMAP D3 — literature-derived validity-range-distance signal.
+
+Per user directive after the sweep finding:
+  "Track B's signal was never the physics-validity signal PhysMAP claims —
+   that signal (literature validity-range distance) still needs to be
+   built and tested against genuinely-quiet baselines on real data."
+
+This module implements the ACTUAL PhysMAP physics-validity claim: a signal
+that depends ONLY on the literature-derived closure validated_range from
+`corpus.jsonl`, NOT on training data. That's the structural property that
+differentiates PhysMAP from input-distribution novelty detectors.
+
+Signal definition:
+  Given a test point (Re, Pr, ...) and a matched closure_id, look up the
+  closure's `validated_range` from corpus.jsonl. For each coordinate in
+  the range, compute the relative distance from the test point's value to
+  the [min, max] interval:
+    - 0 if min <= value <= max
+    - (min - value) / min if value < min
+    - (value - max) / max if value > max
+  Combine across coordinates as L2 norm. Signal > 0 iff test point is
+  outside the validated rectangle on at least one coordinate.
+
+Key property: this signal has NO training-data dependence. It catches
+out-of-validity points regardless of how training is distributed.
+That's the structural mechanism that lets PhysMAP differentiate from
+novelty detectors, IF such a differentiator cell exists in the data.
+
+Important: just because this signal fires doesn't mean it differentiates
+from baselines. Baselines fire when test points are far from training.
+A clean differentiator requires test points that are:
+  - INSIDE the training distribution (baselines genuinely quiet)
+  - OUTSIDE the closure's validated range (validity-distance fires)
+These conditions can only co-occur if training data includes points
+outside the closure's validated range — i.e., a practitioner trained on
+data spanning the closure's validity boundary.
+
+For Forrest:
+  Modified Sparrow-Cur validated_range: Re [10000, 70000], Pr [2.2, 5.4].
+  Forrest data includes:
+    - Sub-critical Re<4000  (OUTSIDE validated Re range)
+    - Transition  Re 4000-10000  (OUTSIDE validated Re range)
+    - Benign      Re>=10000     (INSIDE validated range)
+  If training includes any sub-critical or transition points, the closure's
+  validity boundary cuts THROUGH the training distribution. Test points on
+  the wrong side of that internal boundary would be baseline-quiet but
+  validity-loud — the genuine differentiator cell.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+
+from physmap.corpus.calibration import resolve_corpus_path
+
+
+# Map D3 feature names to corpus.jsonl coordinate names.
+# Geometry features (Dh, alpha_star, etc.) are NOT in corpus validated_range
+# (yet); they're in regime_context as prose. So those features don't
+# contribute to validity-distance — they're for baselines only.
+#
+# x_over_D added after the Track-C-extension for Gnielinski. The validity
+# signal now fires on entrance-region (x/D < 10) test points where the
+# bare correlation is invalid per textbook (Bergman/Incropera 7th ed §8.5).
+FEATURE_TO_CORPUS_COORD = {
+    "log10_Re": "reynolds_number",   # validated_range stores raw Re
+    "Pr": "prandtl_number",
+    "x_over_D": "x_over_D",          # straight passthrough
+    "log10_x_over_D": "x_over_D",    # for log-scale axial-position features
+    "Ri": "richardson_number",       # buoyancy validity ceiling (Stage-3 middle).
+                                     # raw Ri (NOT log) — signal() compares the raw
+                                     # value to the corpus min/max directly.
+    "ratio_mu_w_b": "viscosity_ratio_wall_bulk",  # property-variation bound (Velazquez sCO2)
+    "Bu": "liu_buoyancy_parameter",               # buoyancy validity bound (Jin sCO2 vertical tube;
+                                                  # raw Bu vs corpus max 1.3e-5 directly)
+    # aerospace / hypersonic-transition validity coords (raw passthrough — the
+    # signal() comparison uses the raw value vs corpus min/max directly):
+    "freestream_noise_pct": "freestream_noise_rms_pitot_pct",  # Casper (Pate-Stainback bound)
+    "st_xsw_ratio": "entropy_layer_shock_ratio",               # Marineau (entropy-layer/shock bound)
+}
+
+
+# Status weighting for picking the GOVERNING (dispositive) fired bound when a
+# point is past multiple bounds at once: a confirmed bound outranks a claimed
+# one at equal margin. Mirrors the corpus bound_status vocabulary.
+_STATUS_WEIGHT = {
+    "confirmed": 1.0,
+    "confirmed-contested": 0.9,
+    "extrapolated": 0.6,
+    "claimed": 0.4,
+}
+_DEFAULT_STATUS_WEIGHT = 0.4
+
+
+@dataclass(frozen=True)
+class PerBoundMargin:
+    """One bound's graded distance-past-bound for one test point.
+
+    `margin` is the same per-coordinate relative distance `signal()` squares into
+    its L2 norm: 0 inside [min, max], > 0 outside. `side` ∈ {below, above, inside}.
+    This is the graded, un-collapsed signal (the Tier-1 finding: graded margin
+    ensembles better than binary fire-at-bound). The detector reports which bound
+    was violated and by how much; it does NOT decide observability — that routing
+    lives in the aggregator.
+    """
+    coord: str               # corpus bound variable, e.g. "x_over_D"
+    feature_name: str        # the feature column read, e.g. "x_over_D" or "log10_Re"
+    margin: float            # graded distance-past-bound (0 inside; >0 outside)
+    bound_status: str        # confirmed | confirmed-contested | extrapolated | claimed
+    side: str                # below | above | inside
+
+
+@dataclass
+class ValidityRangeDistanceDetector:
+    """PhysMAP's literature-derived physics-validity signal.
+
+    Reads the matched closure's validated_range from corpus.jsonl. At each
+    test point, computes distance from the test point's coordinates to the
+    validated rectangle. Signal > 0 iff test point is outside the
+    rectangle on at least one coordinate.
+
+    NO training-data dependence. Pure literature lookup.
+    """
+    closure_id: str
+    feature_names: Sequence[str]
+    # Resolves the ACTIVE corpus (env → premium → bundled seed) at construction
+    # time; a dev/editable tree gets the full premium corpus unchanged, a core-only
+    # install gets the bundled seed. Pass an explicit path to override.
+    corpus_path: Path = field(default_factory=resolve_corpus_path)
+
+    valid_ranges: dict[str, tuple[float, float]] = field(default_factory=dict, init=False)
+    # bound_status[coord] mirrors the corpus bound_status; used by governing_bound's
+    # status weighting. Populated alongside valid_ranges; signal() never reads it.
+    bound_status: dict[str, str] = field(default_factory=dict, init=False)
+
+    def __post_init__(self):
+        self.valid_ranges = self._load_validated_ranges()
+        if not self.valid_ranges:
+            raise ValueError(
+                f"closure_id '{self.closure_id}' has no usable validated_range "
+                f"in corpus.jsonl (or closure_id not found)"
+            )
+        self.bound_status = self._load_bound_status()
+
+    def _load_validated_ranges(self) -> dict[str, tuple[float, float]]:
+        ranges = {}
+        with open(self.corpus_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                entry = json.loads(line)
+                if entry.get("closure_id") != self.closure_id:
+                    continue
+                for vr in entry.get("validated_range", []):
+                    coord = vr["coord"]
+                    vmin = float(vr["min"])
+                    vmax = float(vr["max"])
+                    ranges[coord] = (vmin, vmax)
+                break
+        return ranges
+
+    def signal(self, test_X: np.ndarray) -> np.ndarray:
+        """Per-test-point validity-distance to the closure's validated range.
+
+        For each test point and each feature that maps to a corpus coord,
+        compute the relative distance to the [min, max] interval and
+        combine as L2 norm. Geometry features (not in corpus) contribute 0.
+        """
+        n_test = len(test_X)
+        scores = np.zeros(n_test, dtype=float)
+        for i, x in enumerate(test_X):
+            sq_dist = 0.0
+            for j, fname in enumerate(self.feature_names):
+                coord = FEATURE_TO_CORPUS_COORD.get(fname)
+                if coord is None or coord not in self.valid_ranges:
+                    continue
+                # Convert feature value back to physical units for coord lookup
+                if fname == "log10_Re":
+                    value = 10.0 ** float(x[j])
+                elif fname == "log10_x_over_D":
+                    value = 10.0 ** float(x[j])
+                else:
+                    value = float(x[j])
+                vmin, vmax = self.valid_ranges[coord]
+                if value < vmin:
+                    rel = (vmin - value) / max(vmin, 1e-9)
+                    sq_dist += rel ** 2
+                elif value > vmax:
+                    rel = (value - vmax) / max(vmax, 1e-9)
+                    sq_dist += rel ** 2
+                # else: in [min, max], contributes 0
+            scores[i] = float(np.sqrt(sq_dist))
+        return scores
+
+    # ── graded per-bound margins + governing fired bound (additive) ───────────
+    # signal() above is left byte-identical (the locked phase1_gate depends on
+    # it). These methods expose the SAME per-coordinate relative distances
+    # un-collapsed, plus which bound governs — what the observability-weighted
+    # aggregator needs to route on the fired bound VARIABLE.
+
+    def _load_bound_status(self) -> dict[str, str]:
+        """{coord: bound_status} for the matched closure. A separate read keeps
+        _load_validated_ranges() and signal() byte-identical."""
+        statuses: dict[str, str] = {}
+        with open(self.corpus_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                entry = json.loads(line)
+                if entry.get("closure_id") != self.closure_id:
+                    continue
+                for vr in entry.get("validated_range", []):
+                    statuses[vr["coord"]] = vr.get("bound_status", "")
+                break
+        return statuses
+
+    def evaluate_bounds(self, test_X: np.ndarray) -> list[list[PerBoundMargin]]:
+        """Per test point, the graded per-bound margins — the un-collapsed terms
+        signal() L2-combines. One PerBoundMargin per (feature → corpus coord) the
+        detector can evaluate; margin > 0 means the point is past that bound. The
+        per-coordinate math mirrors signal() exactly."""
+        out: list[list[PerBoundMargin]] = []
+        for x in test_X:
+            row: list[PerBoundMargin] = []
+            for j, fname in enumerate(self.feature_names):
+                coord = FEATURE_TO_CORPUS_COORD.get(fname)
+                if coord is None or coord not in self.valid_ranges:
+                    continue
+                if fname in ("log10_Re", "log10_x_over_D"):
+                    value = 10.0 ** float(x[j])
+                else:
+                    value = float(x[j])
+                vmin, vmax = self.valid_ranges[coord]
+                if value < vmin:
+                    margin = (vmin - value) / max(vmin, 1e-9)
+                    side = "below"
+                elif value > vmax:
+                    margin = (value - vmax) / max(vmax, 1e-9)
+                    side = "above"
+                else:
+                    margin = 0.0
+                    side = "inside"
+                row.append(PerBoundMargin(
+                    coord=coord, feature_name=fname, margin=float(margin),
+                    bound_status=self.bound_status.get(coord, ""), side=side,
+                ))
+            out.append(row)
+        return out
+
+    def governing_bound(
+        self, per_bound: Sequence[PerBoundMargin], *, status_weighting: bool = True,
+    ) -> PerBoundMargin | None:
+        """The governing (dispositive) fired bound for one point: the most-
+        violated, status-weighted when `status_weighting` (a confirmed bound
+        outranks a claimed one at equal margin). None if the point is inside
+        every bound."""
+        fired = [b for b in per_bound if b.margin > 0.0]
+        if not fired:
+            return None
+
+        def _key(b: PerBoundMargin) -> float:
+            w = (_STATUS_WEIGHT.get(b.bound_status, _DEFAULT_STATUS_WEIGHT)
+                 if status_weighting else 1.0)
+            return w * b.margin
+
+        return max(fired, key=_key)

physmap/pipeline/vehicle_spec.py

@@ -0,0 +1,287 @@
+"""Per-vehicle parameterization shared by the observability score (D1) and the
+Stage-1 ensemble sweep (D2).
+
+The failure-region split, the surrogate-input + validity feature spaces, the
+closure_id, and the failure-driving variable are ALL derived here from the
+VehicleConfig (chiefly `cell_bands.type`). D1 computes the observability score
+over the failure region; D2 evaluates the sweep over the same region. Defining
+the region ONCE here is what keeps them from drifting apart — if they diverged,
+the Stage-3 axis plot would pair a score over one region with a verdict over
+another (a silent correctness bug).
+
+Step-scope: the NACA (`x_over_d_bands`) row is wired now. Forrest (`re_bands`)
+is added with the observability work (Step 1); Mudhafar (`dh_roughness_bands`)
+and Testi-Grassi (`richardson_bands`) with the scaffolding (Step 4). Unwired
+band types raise a clear NotImplementedError naming the step that wires them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from physmap.substrate.vehicle_config import VehicleConfig
+
+
+# Failure-driving variable per cell-bands type — the meta key whose
+# recoverability from the surrogate inputs IS the observability score.
+# None = the vehicle has no single failure axis (caller must pass failure_var).
+FAILURE_VAR_BY_CELL_BANDS_TYPE: dict[str, str | None] = {
+    "x_over_d_bands": "x_over_D",     # NACA — entrance region
+    "re_bands": "Re",                 # Forrest — sub-critical Re
+    "dh_roughness_bands": "Dh_um",    # Mudhafar — hydraulic diameter
+    "richardson_bands": "Ri",         # buoyancy middle vehicles (Testi-Grassi)
+    "buoyancy_parameter_bands": "Bu", # Jin sCO2 vertical tube — Liu buoyancy parameter
+    "property_variation_bands": "ratio_mu_w_b",  # Velazquez sCO2 — wall/bulk viscosity ratio
+    "freestream_disturbance_bands": "freestream_noise_pct",   # Casper — tunnel freestream noise
+    "entropy_layer_shock_interaction_bands": "st_xsw_ratio",  # Marineau — S_T/X_SW (bluntness)
+    "continuous": None,
+    "custom": None,
+}
+
+# NACA entrance-region locked boundary: x/D >= 10 trains (fully developed);
+# x/D < 10 is the failure region. Mirrors phase1_gate.X_OVER_D_CUTOFF.
+NACA_X_OVER_D_CUTOFF = 10.0
+
+
+@dataclass(frozen=True)
+class SplitSpec:
+    """How the failure region is carved from a vehicle's operating points.
+
+    `train_predicate` / `test_predicate` operate on a row's `.meta` dict. The
+    failure region (test) is where the surrogate is deployed beyond the regime
+    its closure was validated on; train is the in-distribution complement.
+    """
+    kind: str
+    train_predicate: Callable[[dict], bool]
+    test_predicate: Callable[[dict], bool]
+
+
+@dataclass(frozen=True)
+class VehicleSpec:
+    """Everything the observability score + Stage-1 sweep need that is not in
+    the bare VehicleConfig: the two feature spaces, the closure for the
+    validity detector, the failure-driving variable, and the failure-region
+    split."""
+    vehicle_id: str
+    baseline_feature_names: tuple[str, ...]
+    validity_feature_names: tuple[str, ...]
+    closure_id: str
+    failure_var: str
+    split: SplitSpec
+
+
+def vehicle_spec(cfg: VehicleConfig) -> VehicleSpec:
+    """Derive the VehicleSpec from a VehicleConfig, keyed on `cell_bands.type`."""
+    bands_type = cfg.cell_bands.type
+    closure_id = cfg.matched_closure_id
+
+    if bands_type == "x_over_d_bands":
+        # NACA: baselines see (log10_Re, Pr); the validity detector also sees
+        # x/D (the omitted failure axis). Locked cutoff x/D = 10. These feature
+        # spaces + closure reproduce phase1_gate's constants exactly, so the
+        # sweep's NACA arm is byte-identical to the locked gate.
+        cutoff = NACA_X_OVER_D_CUTOFF
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("log10_Re", "Pr"),
+            validity_feature_names=("log10_Re", "Pr", "x_over_D"),
+            closure_id=closure_id,
+            failure_var="x_over_D",
+            split=SplitSpec(
+                kind="x_over_d_threshold",
+                train_predicate=lambda m, c=cutoff: m["x_over_D"] >= c,
+                test_predicate=lambda m, c=cutoff: m["x_over_D"] < c,
+            ),
+        )
+
+    if bands_type == "re_bands":
+        # Forrest: failure axis is Reynolds number, which IS a surrogate input
+        # (log10_Re) — the high-observability pole. The validity space carries
+        # no extra coord (Sparrow-Cur's validated range is (Re, Pr) only).
+        # Failure region = lowest Re band (sub-critical); train = top catch-all
+        # band (benign turbulent); the transition band is excluded from both
+        # (indeterminate, per forrest_resolvability).
+        bands = cfg.cell_bands.bands
+        sub_critical_cut = float(bands[0]["re_lt"])     # e.g. 4000 (sub-critical < this)
+        benign_lo = float(bands[-2]["re_lt"])           # e.g. 10000 (benign >= this)
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("log10_Re", "Pr"),
+            validity_feature_names=("log10_Re", "Pr"),
+            closure_id=closure_id,
+            failure_var="Re",
+            split=SplitSpec(
+                kind="re_bands",
+                train_predicate=lambda m, lo=benign_lo: m["Re"] >= lo,
+                test_predicate=lambda m, c=sub_critical_cut: m["Re"] < c,
+            ),
+        )
+
+    if bands_type == "dh_roughness_bands":
+        # Mudhafar (out-of-envelope control): the steelman baseline is the
+        # cross-substrate feature space, which INCLUDES geometry (log10_Dh_mm).
+        # So the failure axis Dh IS a baseline input → high-observability /
+        # baseline-sufficient pole (the spec's prediction). Failure region =
+        # small-diameter OR rough cells; train = standard smooth.
+        bands = cfg.cell_bands.bands
+        dh_min = next((float(b["dh_um_min"]) for b in bands if "dh_um_min" in b), 200.0)
+        cross = ("log10_Re", "Pr", "log10_Dh_mm", "alpha_star",
+                 "heating_pattern_indicator", "roughness_relative")
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=cross,
+            validity_feature_names=cross,
+            closure_id=closure_id,
+            failure_var="Dh_um",
+            split=SplitSpec(
+                kind="dh_roughness",
+                train_predicate=lambda m, lo=dh_min: (
+                    float(m.get("Dh_um", 0.0)) >= lo and not m.get("rough", False)),
+                test_predicate=lambda m, lo=dh_min: (
+                    float(m.get("Dh_um", 1e18)) < lo or bool(m.get("rough", False))),
+            ),
+        )
+
+    if bands_type == "richardson_bands":
+        # Buoyancy middle vehicle (Testi-Grassi): the surrogate is a
+        # forced-convection (Re, Pr) closure with the buoyancy variable
+        # (Richardson number) OMITTED. Ri is NOT a baseline input but is
+        # partially correlated with Re/heat flux → MIDDLE observability by
+        # construction. Failure region = where buoyancy matters (Ri >= the
+        # forced-dominated cutoff); train = forced-dominated (low Ri).
+        #
+        # The corpus Ri-bound IS wired (Dirker/Meyer/Reid water vehicle): the
+        # MATCHED closure aung-worku-mixed-convection-1986 carries the
+        # richardson_number ceiling (corpus.jsonl); detectors.extract_features
+        # supports "Ri"/"log10_Ri", and validity_feature_names is ("Ri",) below.
+        # NOTE: aung-worku bounds ONLY richardson_number, so the public
+        # CredibilityGuardrail's derived (log10_Re, Pr, Ri) validity space is
+        # behaviorally IDENTICAL to this ("Ri",) — Re/Pr have no aung-worku bound
+        # and contribute zero distance (verified). The dedicated mixed-convection
+        # closure (NOT the shared gnielinski) keeps the Ri bound off NACA/Forrest.
+        # baseline_feature_names keeps (log10_Re, Pr) — buoyancy omission from the
+        # surrogate inputs IS the failure mechanism.
+        bands = cfg.cell_bands.bands
+        ri_forced_cut = float(bands[0].get("ri_lt", 0.1))
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("log10_Re", "Pr"),
+            validity_feature_names=("Ri",),
+            closure_id=closure_id,
+            failure_var="Ri",
+            split=SplitSpec(
+                kind="richardson_bands",
+                train_predicate=lambda m, c=ri_forced_cut: float(m["Ri"]) < c,
+                test_predicate=lambda m, c=ri_forced_cut: float(m["Ri"]) >= c,
+            ),
+        )
+
+    if bands_type == "buoyancy_parameter_bands":
+        # Jin sCO2 vertical-tube buoyancy vehicle: the surrogate is a CONSTANT-PROPERTY,
+        # direction-OMITTING Dittus-Boelter (Re, Pr) closure; the omitted failure driver is the Liu
+        # buoyancy parameter Bu (wall-aware), absent from the (Re, Pr) inputs and only PARTIALLY
+        # recoverable from them (it carries the wall-temperature/HTD signal) -> MIDDLE observability,
+        # MEASURED via cv_r2_knn. The matched closure dittus-boelter-buoyancy-sco2 carries the corpus
+        # Bu <= 1.3e-5 bound (REGIME_TO_CLOSURES[MIXED_CONVECTION_VERTICAL_TUBE]); validity_feature_names
+        # adds "Bu", so the corpus detector fires in the upward-HTD deploy while the (Re, Pr) baseline
+        # stays quiet (the matched up/down inputs are identical — the A6(ii) toggle). The benign/deploy
+        # split is the physical regime label `split_role` (benign = downward / high-G / low-q NHT;
+        # deploy = upward HTD), precomputed offline — NOT a Bu threshold (downward q=43.9 has Bu>1.3e-5
+        # from buoyancy ENHANCEMENT yet is benign NHT). baseline keeps (log10_Re, Pr): buoyancy
+        # omission from the surrogate inputs IS the failure mechanism.
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("log10_Re", "Pr"),
+            validity_feature_names=("log10_Re", "Pr", "Bu"),
+            closure_id=closure_id,
+            failure_var="Bu",
+            split=SplitSpec(
+                kind="buoyancy_parameter_bands",
+                train_predicate=lambda m: str(m["split_role"]) == "benign",
+                test_predicate=lambda m: str(m["split_role"]) == "deploy",
+            ),
+        )
+
+    if bands_type == "property_variation_bands":
+        # Velazquez sCO2 property-variation middle vehicle: the surrogate is a
+        # CONSTANT-PROPERTY (Re, Pr) closure (Gnielinski); the wall/bulk viscosity
+        # ratio mu_w/mu_b is OMITTED and drives the failure near the pseudo-critical
+        # point. mu_w/mu_b is NOT a baseline input but is partially correlated with
+        # Pr (which rises toward pseudo-critical) -> MIDDLE observability, to be
+        # MEASURED (could land nearer the observable pole; that is the open question).
+        # Buoyancy confound isolated by pressure: only p >= p_min_mpa, where the paper
+        # (Fig. 11) shows buoyancy negligible (>= 15 MPa). Failure region = near
+        # pseudo-critical (|T_b - T_pc| < abs_dt_pc_lt); train = far from it (benign
+        # property variation), same pressure subset.
+        bands = cfg.cell_bands.bands
+        b0 = bands[0]
+        p_min = float(b0.get("p_min_mpa", 15.0))
+        dt_cut = float(b0.get("abs_dt_pc_lt", 10.0))
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("log10_Re", "Pr"),
+            validity_feature_names=("log10_Re", "Pr", "ratio_mu_w_b"),
+            closure_id=closure_id,
+            failure_var="ratio_mu_w_b",
+            split=SplitSpec(
+                kind="property_variation_bands",
+                train_predicate=lambda m, p=p_min, c=dt_cut: (
+                    float(m["p_MPa"]) >= p and float(m["abs_dT_pc"]) >= c),
+                test_predicate=lambda m, p=p_min, c=dt_cut: (
+                    float(m["p_MPa"]) >= p and float(m["abs_dT_pc"]) < c),
+            ),
+        )
+
+    if bands_type == "freestream_disturbance_bands":
+        # Casper hypersonic transition (aerospace PHYSMAP_WINS). The surrogate
+        # sees (Mach, unit Reynolds, axial x); the omitted driver is the tunnel
+        # freestream disturbance (freestream_noise_pct), a distinct flow-
+        # environment axis NOT recoverable from the inputs -> UNOBSERVABLE. The
+        # validity space adds freestream_noise_pct, and the corpus Pate-Stainback
+        # bound fires on the QUIET deploy while the baseline stays silent (quiet
+        # deploy is interior in the Mach-spanned training). Train = noisy
+        # (fs >= cut), deploy = quiet (fs < cut); band[0].fs_lt is the 0.5% edge.
+        fs_cut = float(cfg.cell_bands.bands[0].get("fs_lt", 0.5))
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("M", "Re_per_m_e6", "x_m"),
+            validity_feature_names=("M", "Re_per_m_e6", "x_m", "freestream_noise_pct"),
+            closure_id=closure_id,
+            failure_var="freestream_noise_pct",
+            split=SplitSpec(
+                kind="freestream_disturbance_bands",
+                train_predicate=lambda m, c=fs_cut: float(m["freestream_noise_pct"]) >= c,
+                test_predicate=lambda m, c=fs_cut: float(m["freestream_noise_pct"]) < c,
+            ),
+        )
+
+    if bands_type == "entropy_layer_shock_interaction_bands":
+        # Marineau bluntness transition (aerospace NEGATIVE CONTROL). The
+        # surrogate sees (unit Reynolds, nose radius). The failure driver
+        # S_T/X_SW (st_xsw_ratio) is a deterministic function of nose radius (a
+        # surrogate input) at fixed Mach -> OBSERVABLE; the steelman baseline
+        # fires on the large-bluntness deploy (exterior in Rn). The validity
+        # space adds st_xsw_ratio and the corpus bound fires there too, but the
+        # baseline is NOT quiet -> no clean lift (the discrimination control).
+        # Train = benign (S_T/X_SW >= cut), deploy = failure (< cut).
+        st_cut = float(cfg.cell_bands.bands[0].get("st_xsw_lt", 0.1))
+        return VehicleSpec(
+            vehicle_id=cfg.vehicle_id,
+            baseline_feature_names=("Re_per_m", "Rn_mm"),
+            validity_feature_names=("Re_per_m", "Rn_mm", "st_xsw_ratio"),
+            closure_id=closure_id,
+            failure_var="st_xsw_ratio",
+            split=SplitSpec(
+                kind="entropy_layer_shock_interaction_bands",
+                train_predicate=lambda m, c=st_cut: float(m["st_xsw_ratio"]) >= c,
+                test_predicate=lambda m, c=st_cut: float(m["st_xsw_ratio"]) < c,
+            ),
+        )
+
+    raise NotImplementedError(
+        f"vehicle_spec: cell_bands.type={bands_type!r} not wired. "
+        f"Supported: x_over_d_bands, re_bands, dh_roughness_bands, richardson_bands, "
+        f"buoyancy_parameter_bands, property_variation_bands, freestream_disturbance_bands, "
+        f"entropy_layer_shock_interaction_bands."
+    )

physmap/release.py

@@ -0,0 +1,81 @@
+"""Release state — what this build of PhysMAP is allowed to claim.
+
+Three states. The state is a CONSTANT fixed at release time. It is deliberately
+**not** derived from which files happen to be present on disk: a command must not
+appear or disappear because a data directory was copied in. That would make the
+package's claims a function of the user's filesystem instead of a function of what
+was actually reviewed and released.
+
+  GUARDRAIL           closure/observability method, the NACA x/D regression, and the
+                      v0.4 seven-vehicle benchmark. No causal-materiality claim.
+
+  CAUSAL_PREVIEW      the above, plus the causal-materiality API exercised on
+                      synthetic and unit fixtures only. No precision/recall/F1,
+                      no expected_metrics.json, and NO `reproduce` subcommand.
+
+  NAFEMS_REPRODUCTION the above, plus the complete redistributable benchmark:
+                      a locked reconstruction protocol, independent experimental
+                      truth, a geometry-appropriate forced-convection
+                      counterfactual, and expected metrics.
+
+Promotion to NAFEMS_REPRODUCTION is gated by `physmap.benchmarks.readiness`, which
+is a RELEASE-ENGINEERING check run in CI before this constant may be changed. It is
+never consulted at runtime to decide what the CLI offers.
+
+Why the causal numbers in the NAFEMS abstract are not reproduced here: the original
+study's inputs are not available, and the experimental-truth basis is unresolved.
+A reconstruction under a locked protocol will produce its OWN numbers. Those will
+not be the abstract's numbers, and this package never presents them as such.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = [
+    "ReleaseState",
+    "CURRENT_RELEASE_STATE",
+    "EvidenceState",
+    "emits_performance_metrics",
+    "has_reproduce_command",
+    "causal_api_is_preview",
+]
+
+
+class ReleaseState(str, Enum):
+    GUARDRAIL = "guardrail"
+    CAUSAL_PREVIEW = "causal_preview"
+    NAFEMS_REPRODUCTION = "nafems_reproduction"
+
+
+#: Set at release time. Changing this requires the readiness gate to pass in CI.
+CURRENT_RELEASE_STATE: ReleaseState = ReleaseState.CAUSAL_PREVIEW
+
+
+class EvidenceState(str, Enum):
+    """What kind of thing produced a result. Carried on every causal assessment and
+    screen so no emitted artifact can be mistaken for a validated performance claim."""
+
+    #: Generated by a synthetic or unit fixture. Demonstrates mechanics, proves nothing
+    #: about the physical world.
+    SYNTHETIC_FIXTURE = "synthetic_fixture"
+    #: A stated case: the refusal logic and its reason code, with no evidence inputs
+    #: behind it. The two screened-out vehicles are this.
+    DECLARATIVE = "declarative"
+    #: Backed by checked-in evidence inputs with cleared provenance.
+    MEASURED = "measured"
+
+
+def emits_performance_metrics(state: ReleaseState | None = None) -> bool:
+    """True only where precision/recall/F1 may legitimately be produced."""
+    return (state or CURRENT_RELEASE_STATE) is ReleaseState.NAFEMS_REPRODUCTION
+
+
+def has_reproduce_command(state: ReleaseState | None = None) -> bool:
+    """Whether the CLI exposes `reproduce`. Static per release, by design."""
+    return (state or CURRENT_RELEASE_STATE) is ReleaseState.NAFEMS_REPRODUCTION
+
+
+def causal_api_is_preview(state: ReleaseState | None = None) -> bool:
+    """True where the causal-materiality API ships but carries no performance claim."""
+    return (state or CURRENT_RELEASE_STATE) is ReleaseState.CAUSAL_PREVIEW

physmap/stress_tests/__init__.py

@@ -0,0 +1,9 @@
+"""Controlled stress tests of the causal path.
+
+A stress test here is a deliberately constructed situation with a known answer, used to show
+what a check can and cannot see. It is a development demonstration, not an evaluation: no
+performance metric is computed or implied. Each one reproduces from the checkout with one
+command and is drift-checked against a committed bank, the same way `physmap benchmark run`
+is -- and each is kept apart from that benchmark, which measures closure validity and
+observability, not materiality.
+"""