physmap 0.2.0__py3-none-any.whl

physmap/guardrail/corpus_regimes.py

@@ -0,0 +1,208 @@
+"""Corpus prerequisites for the structural-observability layer.
+
+Four additive pieces the CredibilityGuardrail needs that the shipped corpus
+does not yet provide. They live here — NOT by mutating corpus/calibration.py or
+corpus.jsonl — so the locked calibration validator + SHACL + phase tests stay
+untouched. The classifier reads the existing corpus via the existing accessors
+(load_corpus / index_by_id / get_validated_range) and joins to these maps.
+
+  1. REGIME_TO_CLOSURES  — a structured Regime → closure_ids map. The corpus only
+     carries `regime_context` as prose; this is authored from closures/registry.py
+     geometry groupings ∩ the corpus closure_ids. ENTRANCE_REGION_PIPE →
+     gnielinski-1976 is what carries the x/D bound the locked NACA case fires on.
+  2. observability_class  — a (closure_id, coord) → tag, defaulting to
+     "structural-binary"; only buoyancy/property-ratio/roughness coords are
+     "known-partial". Drives the PARTIAL routing.
+  3. partial_degree       — the graded-partial DEGREE (Layer 2c) for known-partial
+     coords: empirical, regime-specific, and EMPTY until a middle vehicle calibrates
+     it. Leaving it empty is the honest state — an uncalibrated degree that drove a
+     weight would be a fabricated empirical claim.
+  4. corpus_fingerprint   — version + content hash for the save/load manifest.
+
+These maps are the authoritative source the regime→observability mapping artifact
+(physmap/guardrail/regime_observability.py) is GENERATED from; the artifact is a
+validated, version-tagged projection, never a second runtime source of truth.
+
+TODO: the canonical home for observability_class is a field on CoordinateBound,
+once a buoyancy vehicle lands and the corpus owner re-blesses the validator.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from physmap.corpus.calibration import (
+    DEFAULT_PATH as CALIBRATION_CORPUS_PATH,
+    active_tier,
+    resolve_corpus_path,
+)
+from physmap.guardrail.enums import Regime
+
+
+# Regime → the corpus closure_ids whose validity bounds define that regime.
+# Closure_ids verified present in results/calibration_corpus/corpus.jsonl.
+REGIME_TO_CLOSURES: dict[Regime, tuple[str, ...]] = {
+    Regime.ENTRANCE_REGION_PIPE: ("gnielinski-1976",),
+    Regime.INTERNAL_FORCED_CONVECTION_PIPE: (
+        "gnielinski-1976",
+        "dittus-boelter-1930",
+        "sieder-tate-1936",
+        "petukhov-1970",
+    ),
+    Regime.INTERNAL_FORCED_CONVECTION_RECT_CHANNEL: (
+        "modified-sparrow-cur-asym-narrow-rect-channel-2014",
+    ),
+    Regime.EXTERNAL_FLAT_PLATE_FORCED: (
+        "blasius-pohlhausen-flat-plate-forced-1921",
+    ),
+    Regime.MIXED_CONVECTION_HORIZONTAL_TUBE: (
+        "aung-worku-mixed-convection-1986",   # carries the richardson_number bound
+    ),
+    Regime.MIXED_CONVECTION_VERTICAL_TUBE: (
+        "dittus-boelter-buoyancy-sco2",       # carries the liu_buoyancy_parameter (Bu) bound (Jin sCO2)
+    ),
+    Regime.INTERNAL_FORCED_CONVECTION_PROPERTY_VARIATION: (
+        "gnielinski-constprop-sco2",          # carries the viscosity_ratio_wall_bulk bound
+    ),
+    Regime.HYPERSONIC_TRANSITION_DISTURBANCE: (
+        "pate-stainback-freestream-noise-hypersonic-1980",   # freestream-noise validity bound (Casper)
+    ),
+    Regime.HYPERSONIC_TRANSITION_ENTROPY: (
+        "marineau-entropy-layer-shock-interaction-2014",     # S_T/X_SW validity bound (Marineau)
+    ),
+    Regime.UNLISTED: (),                       # statistical-only; physics layer inactive
+}
+
+# TODO (handbook-harvest rounds 1+2, corpus v0.2.3) — closures present in the corpus but NOT yet
+# wired to a Regime above. They are INERT: discoverable via load_default_corpus_index(), but they
+# do NOT fire in the guardrail until mapped here. Each needs a human physics decision on which
+# Regime it defines (+ a known-partial override in OBSERVABILITY_CLASS_OVERRIDES below if its coord
+# is absent-but-correlated rather than a clean structural-binary miss).
+#
+#   ⚠ CONSISTENCY OBLIGATION — viscosity_ratio_wall_bulk is KNOWN_PARTIAL on the mapped
+#     gnielinski-constprop-sco2, and a variable's class is one value everywhere it appears, so BOTH
+#     inert closures that reuse it (whitaker-sphere-external-forced-1972, sieder-tate-laminar-
+#     combined-entry-1936) MUST get a known-partial override here AT THE MOMENT THEY ARE WIRED, or
+#     the mapping class-consistency gate fails. Harmless while inert: build_mapping() omits unmapped
+#     closures, so the conflict is latent until one is wired.
+#
+#   Round 1 (still inert):
+#     * swanson-catton-opposing-mixed-convection-1987       (grashof_number)              — opposing mixed convection
+#     * mack-second-mode-transition-1969                    (mach_number)                 — compressible 2nd-mode transition
+#     * perfect-gas-constant-cp-compressible-bl-1989        (mach_number)                 — compressible boundary layer
+#     * blasius-pohlhausen-horizontal-plate-forced-1921     (gr_over_re2p5, gr_xl1p5_*)   — horizontal-plate mixed convection
+#     * campbell-perkins-triangular-duct-air-1968           (temperature_ratio_wall_bulk) — triangular-duct gas property variation
+#     * sieder-tate-laminar-combined-entry-1936             (viscosity_ratio_wall_bulk)   — laminar combined-entry μ/μ_s  [known-partial WHEN WIRED]
+#   Round 2 (promoted v0.2.3, all inert):
+#     * whitaker-sphere-external-forced-1972                (viscosity_ratio_wall_bulk)   — sphere μ/μ_s moat  [known-partial WHEN WIRED]
+#     * cheng-curved-square-duct-nusselt-1975               (dean_number)                 — curved square duct; De is hydraulic-diameter-normalized
+#     * depew-august-horizontal-tube-mixed-convection-1971  (rayleigh_number)             — horizontal-tube mixed convection (isothermal wall)
+#     * marcos-bergles-horizontal-tube-mixed-convection-1975 (rayleigh_number)            — horizontal-tube mixed convection (uniform heat flux)
+#     * eckert-reference-temperature-compressible-1972      (mach_number)                 — compressible reference-temperature property method
+#     * herwig-perturbation-variable-property-bl-1985       (mach_number)                 — compressible variable-property BL skin friction
+#     * goertler-concave-wall-transition-1940               (goertler_number)             — concave-wall centrifugal transition (momentum-thickness G)
+#     * millikan-log-law-of-the-wall-1938                   (wall_y_plus)                 — log-law overlap onset; may JOIN the wall-function closures
+#     * rotta-constant-turbulent-prandtl-number-1964        (prandtl_number)              — bound on MOLECULAR Pr (not Pr_t) → OBSERVABLE / low-moat
+#     * laminar-fully-developed-tube-isothermal-nu366       (reynolds_number)             — Nu=3.66 analytical backbone → OBSERVABLE / low-moat
+#     * laminar-fully-developed-tube-uniform-flux-nu436     (reynolds_number)             — Nu=4.36 analytical backbone → OBSERVABLE / low-moat
+
+
+# Observability class for a bound coordinate. Cleanly-in/out axes (Re, Pr, x/D)
+# are "structural-binary": the surrogate either consumes the axis or it does not.
+# Absent-but-correlated axes (buoyancy, property-ratio, roughness) are
+# "known-partial" — a surrogate may carry correlated information even without the
+# axis itself, so set-membership can't cleanly weight them yet.
+DEFAULT_OBSERVABILITY_CLASS = "structural-binary"
+KNOWN_PARTIAL = "known-partial"
+
+OBSERVABILITY_CLASS_OVERRIDES: dict[tuple[str, str], str] = {
+    ("aung-worku-mixed-convection-1986", "richardson_number"): KNOWN_PARTIAL,
+    # Wall/bulk property ratio: absent from (Re, Pr) inputs but correlated with them
+    # through the property field near the pseudo-critical point — set-membership sees
+    # it absent, so it routes PARTIAL (not a clean structural-binary miss).
+    ("gnielinski-constprop-sco2", "viscosity_ratio_wall_bulk"): KNOWN_PARTIAL,
+    # NOTE (Jin sCO2 vertical-tube, liu_buoyancy_parameter Bu): NOT overridden -> defaults to
+    # structural-binary -> routes UNOBSERVABLE. This is the MEASURED result, not a guess: the Liu Bu
+    # (and even the bulk-only Jackson Bo*) recoverability from the (Re, Pr) surrogate inputs over the
+    # deploy region is cv_r2_knn ~ 0 (corr ~ -0.2), because Bu carries the wall-temperature/HTD signal
+    # the DIRECTION toggle drives — orthogonal to the bulk inputs, the SAME structure as Casper's
+    # freestream noise (a flow-environment binary), NOT the Velazquez property-ratio middle. So Jin
+    # plots at the unobservable pole (a thermal-fluids PHYSMAP_WINS + the buoyancy/property-variation
+    # confound-isolation case), not the partial band. (Distinct group from richardson_number Gr/Re^2.)
+    # Sparrow-Gregg forced-convection buoyancy-validity bound (Gr/Re^2 <= 0.225, Rohsenow §4.9).
+    # richardson_number is the SAME physical quantity already classed known-partial above, and the
+    # per-variable class-consistency invariant requires one class everywhere it appears — so it is
+    # known-partial here too (Ri absent from a forced (Re,Pr) surrogate, correlated through Re).
+    ("blasius-pohlhausen-flat-plate-forced-1921", "richardson_number"): KNOWN_PARTIAL,
+}
+
+
+def observability_class_for(closure_id: str, coord: str) -> str:
+    """Return "structural-binary" (default) or "known-partial" (override table)."""
+    return OBSERVABILITY_CLASS_OVERRIDES.get((closure_id, coord), DEFAULT_OBSERVABILITY_CLASS)
+
+
+# Graded-partial DEGREE (Layer 2c). For a known-partial coord, HOW partial it is —
+# the correlation between the absent axis and the surrogate's inputs in a given
+# operating regime. Empirical and regime-specific, so keyed (closure_id, coord) →
+# {"partial_degree": {regime_value: degree}, "calibrated_by": [middle_vehicle_ids]}.
+# A cell is populated ONLY by a middle vehicle that passes the digitization protocol
+# + the stability gate; an uncalibrated cell stays absent here (the classifier then
+# defers: PARTIAL → UNCERTAIN/REVIEW). Honesty discipline: an uncalibrated degree that
+# drives a weight is a fabricated empirical claim — never invent a cell, and never key
+# one to a regime the calibrating vehicle did not actually operate in.
+PARTIAL_DEGREE_CALIBRATIONS: dict[tuple[str, str], dict] = {
+    # Velázquez sCO2 (property-variation middle): cv_r2_knn = 0.575, stability-confirmed
+    # (provisional=false, subsampling std 0.139 < 0.15 gate). Measured value banked in
+    # results/velazquez_sco2_digitization/observability_result.json; this cell consumes
+    # that score, it does not recompute it. Keyed to the regime the vehicle operates in.
+    ("gnielinski-constprop-sco2", "viscosity_ratio_wall_bulk"): {
+        "partial_degree": {"internal_forced_convection_property_variation": 0.575},
+        "calibrated_by": ["velazquez_sco2"],
+    },
+}
+
+
+def partial_degree_for(
+    closure_id: str, coord: str,
+) -> tuple[dict[str, float] | None, str, list[str]]:
+    """Return (partial_degree, degree_status, calibrated_by) for a bound coordinate.
+
+    Three states, mirroring the spec's `degree_status` vocabulary:
+      * structural-binary           → (None, "n/a", [])
+      * known-partial, uncalibrated → (None, "uncalibrated", [])
+      * known-partial, calibrated   → ({regime_value: degree}, "calibrated", [ids])
+    """
+    if observability_class_for(closure_id, coord) != KNOWN_PARTIAL:
+        return None, "n/a", []
+    cal = PARTIAL_DEGREE_CALIBRATIONS.get((closure_id, coord))
+    if not cal:
+        return None, "uncalibrated", []
+    return cal["partial_degree"], "calibrated", list(cal.get("calibrated_by", []))
+
+
+# Bumped by hand when the calibration corpus changes in a way that affects
+# guardrail bounds. The content hash catches silent drift a semver alone misses.
+CALIBRATION_CORPUS_VERSION = "0.2.4"   # 0.2.4: +dittus-boelter-buoyancy-sco2 (corpus 52->53) — NEW coordinate liu_buoyancy_parameter (Liu et al. 2017 Bu, wall-aware; DISTINCT from richardson_number Gr/Re^2, same-name trap avoided), validated_range Bu<=1.3e-5 (a-priori, banked jin-2023-correct Claim). WIRED into REGIME_TO_CLOSURES[MIXED_CONVECTION_VERTICAL_TUBE] + KNOWN_PARTIAL (Bu partial-recoverable) — FIRES for the Jin sCO2-buoyancy benchmark cell, INERT for the other six (they carry no Bu coordinate, so their cells stay byte-identical). MAPPING regenerated (Jin regime/closure now in the projection). 0.2.3: handbook-harvest round 2 — 11 INERT new closures promoted (corpus 41->52), all claimed, none wired. MAPPING_VERSION intentionally stays 0.2.2: every promoted closure is inert (not in REGIME_TO_CLOSURES), so build_mapping()'s projection is byte-identical and the drift-guard is green WITHOUT regen. New: Incropera whitaker-sphere-external-forced-1972 (viscosity_ratio_wall_bulk [1.0,3.2] sphere μ/μ_s moat; known-partial WHEN WIRED) + laminar-fully-developed-tube nu366/nu436 (reynolds_number<=2300 analytical backbone, OBSERVABLE); Rohsenow cheng-curved-square-duct-nusselt-1975 (dean_number [20,705], D_h-normalized) + depew-august/marcos-bergles horizontal-tube mixed-conv (rayleigh_number); VDI eckert-reference-temperature-compressible-1972 (mach_number<=20); Schlichting millikan-log-law (wall_y_plus>=70) + goertler-concave-wall-transition (goertler_number>=7, momentum-thickness) + herwig-variable-property-bl (mach_number<=3) + rotta-constant-turbulent-prandtl (prandtl_number>=0.5 MOLECULAR-Pr, OBSERVABLE). dean_number & goertler_number are new vocabulary coords (conventions pinned in SCHEMA.md). 0.2.2: handbook-harvest batch — VDI gnielinski-1976 property-variation (prandtl_ratio_bulk_wall [0.1,10] + temperature_ratio_bulk_wall [0.5,1.0], FIRE) + swanson-catton-opposing-mixed-convection-1987 grashof_number (inert); Schlichting mach_number closures mack-second-mode-transition-1969 (>=2.2) + perfect-gas-constant-cp-compressible-bl-1989 (<=5.0) (inert); Rohsenow blasius-pohlhausen-horizontal-plate-forced-1921 (3 buoyancy-grouping coords) + campbell-perkins-triangular-duct-air-1968 (temperature_ratio_wall_bulk [1.10,2.11] gas T-ratio) (both inert); all new coords structural-binary/UNOBSERVABLE, additive. 0.2.1: +Sparrow-Gregg Ri<=0.225 on blasius-pohlhausen (fires) + sieder-tate-laminar (inert)
+
+
+def corpus_fingerprint(path: str | Path | None = None) -> dict:
+    """{'version', 'sha256', 'n_entries', 'tier'} for the save/load manifest.
+
+    The hash is over the SORTED non-empty JSONL lines, so reordering closures
+    does not change it (the corpus is a set of closures, not an ordered list).
+    path=None fingerprints the ACTIVE corpus (env → premium → bundled seed); the
+    'tier' field lets load() distinguish a seed-fitted guard from a premium one
+    (different content → different hash already, but tier makes the drift message
+    explicit). Seed and premium therefore carry distinct fingerprints by design.
+    """
+    p = Path(path) if path is not None else resolve_corpus_path()
+    lines = [ln.strip() for ln in p.read_text(encoding="utf-8").splitlines() if ln.strip()]
+    digest = hashlib.sha256("\n".join(sorted(lines)).encode("utf-8")).hexdigest()
+    return {
+        "version": CALIBRATION_CORPUS_VERSION,
+        "sha256": digest,
+        "n_entries": len(lines),
+        "tier": active_tier(p),
+    }

physmap/guardrail/detector_conformal.py

@@ -0,0 +1,129 @@
+"""Observable-pole conformal statistical mode — the split-conformal residual detector.
+
+Spec: docs/specs/PhysMAP_AxisAdaptive_Guardrail_Unified_Spec_v0_1.md (action #4 — the
+observable-pole "competent statistical detector" mode).
+
+At the OBSERVABLE pole the failure driver IS a surrogate input, so a GP emulator fit on
+truth sees it and is a sound reference. This detector flags test points where the
+SURROGATE's prediction falls OUTSIDE the GP's split-conformal prediction interval — a
+DEPLOYABLE credibility signal (it needs the surrogate prediction, NOT the test truth) with
+a distribution-free coverage guarantee.
+
+Split conformal (Vovk; Lei et al. 2018):
+  * fit a GP emulator (the locked Matérn-5/2 GPVarianceDetector) on a PROPER-train split;
+  * on a held-out CALIBRATION split compute the studentized GP residual
+        s_i = |y_i - mu(x_i)| / sigma(x_i)
+    and take the conformal quantile q = the ceil((n_cal+1)(1-alpha))-th smallest s_i, so
+    P(|y - mu(x)| / sigma(x) <= q) >= 1 - alpha for an exchangeable future point;
+  * at DEPLOY, FIRE when the surrogate's prediction is outside that interval:
+        |pred(x) - mu(x)| / sigma(x) > q.
+
+WHY THIS IS NOT THE FLOORED gp_variance BASELINE (the honest comparison bar — the floor
+already beats naive percentile-of-self, so beating naive would be hollow):
+  * The floored gp_variance fires on the predictive-variance MAGNITUDE (sigma/|mu| above a
+    floored percentile-of-self). It is structurally BLIND to a surrogate that is
+    confidently WRONG at a point where the GP variance is LOW (a dense-training region):
+    sigma is small there, so it stays quiet.
+  * This detector fires on surrogate–GP DISAGREEMENT studentized by sigma, so a confident
+    wrong surrogate at low variance lands far outside the (tight) conformal interval and
+    FIRES — the failure class the floored gp_variance misses — while the conformal quantile
+    is calibrated OUT-OF-SAMPLE (on a held-out split, not the in-sample self-scores that
+    degenerate under dense training), so the in-distribution false-alarm rate is ~alpha: a
+    coverage guarantee the percentile-of-self + floor heuristic does not provide.
+
+DISCIPLINE: a competent, better-than-NAIVE statistical detector for OBSERVABLE regimes
+(table stakes), NOT a moat and NOT aiming to beat a steelman OOD detector. It is OPT-IN
+(absent from the default detector set and from the banked benchmark detector tuple), so it
+is strictly ADDITIVE — the banked matrix is untouched.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from physmap.pipeline.core import DetectorResult
+from physmap.pipeline.detectors import GPVarianceDetector
+
+CONFORMAL_NAME = "conformal_residual"
+_MIN_PROPER_TRAIN = 2          # the GP emulator needs at least this many proper-train rows
+_STD_FLOOR_REL = 1e-6          # relative floor on sigma, applied identically to calib + test
+
+
+class ConformalResidualDetector:
+    """Split-conformal studentized-residual detector over the locked GP emulator.
+
+    Calibration uses train TRUTH (the GP residual on a held-out split); the deploy-time
+    FIRE condition uses the surrogate PREDICTION (no test truth) — so it is deployable.
+    """
+
+    def __init__(
+        self,
+        train_X: np.ndarray,
+        train_y: np.ndarray,
+        *,
+        alpha: float = 0.1,
+        calib_frac: float = 0.3,
+        random_state: int = 20260605,
+    ) -> None:
+        train_X = np.asarray(train_X, dtype=float)
+        train_y = np.asarray(train_y, dtype=float).ravel()
+        n = train_X.shape[0]
+        if n < _MIN_PROPER_TRAIN + 1:
+            raise ValueError(
+                f"conformal_residual needs >= {_MIN_PROPER_TRAIN + 1} train rows to split "
+                f"into proper-train + calibration; got {n}.")
+        self.alpha = float(alpha)
+        self.calib_frac = float(calib_frac)
+
+        rng = np.random.default_rng(random_state)
+        perm = rng.permutation(n)
+        n_cal = int(round(self.calib_frac * n))
+        n_cal = min(max(n_cal, 1), n - _MIN_PROPER_TRAIN)   # keep >= _MIN_PROPER_TRAIN proper
+        cal_idx, prop_idx = perm[:n_cal], perm[n_cal:]
+
+        # Emulator on the PROPER-train split only (split-conformal exchangeability).
+        self._gp = GPVarianceDetector(
+            train_X[prop_idx], train_y[prop_idx], random_state=random_state)
+        self._std_floor = max(float(np.abs(train_y).mean()) * _STD_FLOOR_REL, _STD_FLOOR_REL)
+
+        mu, std = self._gp.gp.predict(train_X[cal_idx], return_std=True)
+        std = np.maximum(std, self._std_floor)
+        nonconf = np.abs(train_y[cal_idx] - mu) / std
+
+        # Split-conformal quantile: the ceil((n_cal+1)(1-alpha))-th smallest calibration score.
+        k = int(np.ceil((n_cal + 1) * (1.0 - self.alpha)))
+        k = min(max(k, 1), n_cal)
+        self.q = float(np.sort(nonconf)[k - 1])
+        self.n_cal = int(n_cal)
+        self.n_proper = int(len(prop_idx))
+
+    def score(self, test_X: np.ndarray, test_pred: np.ndarray):
+        """The studentized surrogate–GP residual |pred - mu| / sigma at each test point,
+        plus (mu, sigma) for audit. Uses the surrogate prediction; NO test truth."""
+        test_X = np.asarray(test_X, dtype=float)
+        mu, std = self._gp.gp.predict(test_X, return_std=True)
+        std = np.maximum(std, self._std_floor)
+        pred = np.asarray(test_pred, dtype=float).ravel()
+        return np.abs(pred - mu) / std, mu, std
+
+    def evaluate(self, test_X: np.ndarray, test_pred) -> list[DetectorResult]:
+        """One DetectorResult per test row. With no surrogate prediction the detector is
+        honestly quiet (its signal is undefined without a prediction to test)."""
+        n = np.asarray(test_X, dtype=float).shape[0]
+        if test_pred is None:
+            return [
+                DetectorResult(
+                    CONFORMAL_NAME, 0.0, False, self.q,
+                    f"{CONFORMAL_NAME}: quiet (no surrogate prediction supplied)", "decision")
+                for _ in range(n)
+            ]
+        scores, _mu, _std = self.score(test_X, test_pred)
+        out: list[DetectorResult] = []
+        for si in scores:
+            si_f = float(si)
+            fired = bool(si_f > self.q)   # NaN (missing pred) → False
+            rationale = (
+                f"{CONFORMAL_NAME}: {'FIRED' if fired else 'quiet'} "
+                f"(studentized surrogate–GP residual={si_f:.3g} "
+                f"{'>' if fired else '<='} conformal q(α={self.alpha:g})={self.q:.3g})")
+            out.append(DetectorResult(CONFORMAL_NAME, si_f, fired, self.q, rationale, "decision"))
+        return out

physmap/guardrail/detector_density.py

@@ -0,0 +1,74 @@
+"""GMM novelty-density detector — the steelman NVIDIA-style density baseline.
+
+New code: the shipped pipeline had distance / GP-variance / ensemble / corpus /
+closure-validity, but NO density detector, and the spec's default novelty slot is
+GMM density. This fits a sklearn GaussianMixture on the training feature matrix;
+the per-point signal is the negative log-likelihood (higher = lower density =
+more novel). Two thresholds are calibrated from the TRAIN NLL distribution —
+warn_pct and reject_pct — so the guardrail can tier WARN vs REJECT.
+
+sklearn is imported lazily (inside fit) so importing this module stays import-safe
+even without the experiment extra (the no-heavy-imports test imports every
+submodule). DensityMethod.PCE and Device.CUDA are wired but raise
+NotImplementedError — GPU is deferred per the locked scope (workloads are small).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from physmap.guardrail.enums import DensityMethod, Device
+
+RANDOM_STATE = 20260605
+
+
+@dataclass
+class DensityNoveltyDetector:
+    """A `.signal(test_X) -> ndarray` detector (the uniform inner interface),
+    fitted at construction. Carries two thresholds for WARN/REJECT tiering."""
+
+    train_X: np.ndarray
+    components: int = 1
+    warn_pct: float = 99.0
+    reject_pct: float = 99.9
+    method: DensityMethod = DensityMethod.GMM
+    device: Device = Device.CPU
+    random_state: int = RANDOM_STATE
+
+    _gmm: object = field(init=False, default=None, repr=False)
+    warn_threshold: float = field(init=False, default=0.0)
+    reject_threshold: float = field(init=False, default=0.0)
+
+    def __post_init__(self) -> None:
+        if self.method is not DensityMethod.GMM:
+            raise NotImplementedError(
+                f"density method {self.method.value!r} is not implemented; "
+                f"only GMM ships now (PCE is deferred)."
+            )
+        if self.device is Device.CUDA:
+            raise NotImplementedError(
+                "CUDA density path is not implemented; device is wired but only "
+                "CPU is built (workloads are small — GPU is deferred)."
+            )
+        from sklearn.mixture import GaussianMixture
+
+        X = np.asarray(self.train_X, dtype=float)
+        self._gmm = GaussianMixture(
+            n_components=self.components,
+            covariance_type="full",
+            random_state=self.random_state,
+        ).fit(X)
+        train_nll = -self._gmm.score_samples(X)
+        self.warn_threshold = float(np.percentile(train_nll, self.warn_pct))
+        self.reject_threshold = float(np.percentile(train_nll, self.reject_pct))
+
+    def signal(self, test_X: np.ndarray) -> np.ndarray:
+        """Per-point negative log-likelihood under the fitted GMM.
+
+        Higher = lower density = more novel. Compared against warn/reject
+        thresholds (percentiles of the train NLL) by the guardrail.
+        """
+        X = np.asarray(test_X, dtype=float)
+        return -np.asarray(self._gmm.score_samples(X), dtype=float)

physmap/guardrail/enums.py

@@ -0,0 +1,69 @@
+"""Public typed surface for the physmap CredibilityGuardrail.
+
+Everything categorical is an enum — no magic strings for any fixed choice.
+Continuous params (thresholds, counts) are plain numbers; only the developer's
+own data-column names stay strings (validated, not enumerated).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+# ── Developer's fixed choices ─────────────────────────────────────────────────
+class Regime(Enum):
+    INTERNAL_FORCED_CONVECTION_PIPE = "internal_forced_convection_pipe"
+    INTERNAL_FORCED_CONVECTION_RECT_CHANNEL = "internal_forced_convection_rect_channel"
+    ENTRANCE_REGION_PIPE = "entrance_region_pipe"
+    EXTERNAL_FLAT_PLATE_FORCED = "external_flat_plate_forced"
+    MIXED_CONVECTION_HORIZONTAL_TUBE = "mixed_convection_horizontal_tube"
+    MIXED_CONVECTION_VERTICAL_TUBE = "mixed_convection_vertical_tube"          # Jin (sCO2 buoyancy, Liu Bu)
+    INTERNAL_FORCED_CONVECTION_PROPERTY_VARIATION = "internal_forced_convection_property_variation"
+    HYPERSONIC_TRANSITION_DISTURBANCE = "hypersonic_transition_disturbance"   # Casper (freestream noise)
+    HYPERSONIC_TRANSITION_ENTROPY = "hypersonic_transition_entropy"           # Marineau (bluntness/entropy)
+    UNLISTED = "unlisted"                          # → statistical-only mode
+
+
+class DetectorKind(Enum):
+    DISTANCE_TO_TRAINING = "distance_to_training"
+    GP_VARIANCE = "gp_variance"
+    NOVELTY_DENSITY = "novelty_density"
+    CLOSURE_VALIDITY = "closure_validity"
+    CONFORMAL_RESIDUAL = "conformal_residual"   # observable-pole conformal statistical mode
+
+
+class DensityMethod(Enum):
+    GMM = "gmm"
+    PCE = "pce"                                    # deferred (raises NotImplementedError)
+
+
+class AggregatorKind(Enum):
+    OBSERVABILITY_WEIGHTED = "observability_weighted"   # default
+    ANY_FIRED = "any_fired"
+    CORPUS_GATED = "corpus_gated"
+
+
+class Device(Enum):
+    CPU = "cpu"
+    CUDA = "cuda"                                   # wired; CPU implemented (CUDA → NotImplementedError)
+
+
+# ── Typed outputs ─────────────────────────────────────────────────────────────
+class Observability(Enum):
+    OBSERVABLE = "observable"
+    PARTIAL = "partial"
+    UNOBSERVABLE = "unobservable"
+
+
+class Verdict(Enum):
+    TRUSTWORTHY = "trustworthy"
+    WARN = "warn"
+    REJECT = "reject"
+    UNCERTAIN = "uncertain"
+
+
+class Disposition(Enum):
+    CHARACTERIZE_REGION = "characterize_region"
+    RESTRICT_COU = "restrict_cou"
+    ACCEPT_RESIDUAL_RISK = "accept_residual_risk"
+    REVIEW = "review"

physmap/guardrail/graph.py

@@ -0,0 +1,73 @@
+"""Public Assessment → v0.6 SHACL-valid JSON-LD subgraph.
+
+Thin reuse of pipeline.assessment_v06: rebuild a core Assessment from the public
+one and run assessment_to_v06_subgraph with the DefeasibleAdjudicator (which emits
+an action_class in the 5 SHACL classes). The graph is conformant by construction,
+and the public 4-way Disposition (incl. REVIEW) never reaches the graph as a
+literal — the adjudicator's SHACL action_class is used directly.
+"""
+
+from __future__ import annotations
+
+from physmap.guardrail.configs import Assessment as PublicAssessment
+from physmap.guardrail.enums import DetectorKind
+from physmap.pipeline.assessment_v06 import assessment_to_v06_subgraph
+from physmap.pipeline.core import Assessment as CoreAssessment
+from physmap.pipeline.core import DetectorResult as CoreDetectorResult
+from physmap.pipeline.defeasible_aggregator import DefeasibleAdjudicator
+
+
+# Public DetectorKind ↔ the core detector_name strings the v0.6 mapper keys on.
+NAME_BY_KIND = {
+    DetectorKind.DISTANCE_TO_TRAINING: "distance",
+    DetectorKind.GP_VARIANCE: "gp_variance",
+    DetectorKind.NOVELTY_DENSITY: "novelty_density",
+    DetectorKind.CLOSURE_VALIDITY: "closure_validity",
+    DetectorKind.CONFORMAL_RESIDUAL: "conformal_residual",
+}
+KIND_BY_NAME = {v: k for k, v in NAME_BY_KIND.items()}
+
+
+def _to_core_signals(signals: dict) -> dict[str, CoreDetectorResult]:
+    out: dict[str, CoreDetectorResult] = {}
+    for kind, r in signals.items():
+        name = NAME_BY_KIND.get(kind, getattr(kind, "value", str(kind)))
+        out[name] = CoreDetectorResult(
+            detector_name=name, score=r.score, fired=r.fired,
+            threshold=r.threshold, rationale=r.rationale, role="decision",
+        )
+    return out
+
+
+def assessment_to_graph(a: PublicAssessment) -> dict:
+    """Render one public Assessment as a v0.6 JSON-LD doc (@context + @graph)."""
+    if a.solver_truth is None:
+        raise ValueError(
+            "to_graph() requires solver_truth — the v0.6 Discrepancy shape pins "
+            "exactly one solverTruth. A deployment without truth still yields a "
+            "flat Assessment, but cannot produce a SHACL graph. Supply truth "
+            "(a Path with a truth column, or graph=True over data that carries it)."
+        )
+    if a.surrogate_prediction is None:
+        raise ValueError(
+            "to_graph() requires surrogate_prediction (the Discrepancy needs the "
+            "surrogate-vs-truth pair). Supply predictions via the surrogate "
+            "callable, a prediction column, or test_pred."
+        )
+    core_signals = _to_core_signals(a.signals)
+    label = "fire" if any(r.fired for r in core_signals.values()) else "quiet"
+    core = CoreAssessment(
+        operating_point=a.operating_point,
+        verdict=label,
+        decision_signals=core_signals,
+        justification_signals={},
+        rationale=a.rationale,
+    )
+    sub = assessment_to_v06_subgraph(
+        core,
+        surrogate_prediction=float(a.surrogate_prediction),
+        solver_truth=float(a.solver_truth),
+        discrepancy_region=a.region,
+        adjudicator=DefeasibleAdjudicator(),
+    )
+    return sub.to_jsonld()