physmap 0.2.0__py3-none-any.whl

physmap/explain/benchmark.py

@@ -0,0 +1,101 @@
+"""Deterministic explanation of one benchmark cell.
+
+Every rendering states, in the header, which KIND of claim the cell is. That is not
+decoration. The seven-vehicle benchmark measures closure validity and surrogate
+observability; it measures nothing about causal materiality.
+
+**And the reason cannot be "no vehicle is close to the causal case", because one is.**
+`jin_sco2_buoyancy` is a mixed-convection vertical tube whose failure driver is a
+buoyancy parameter -- geometrically the nearest thing here to the NAFEMS mixed-convection
+pipe. It is the cell most likely to be mistaken for causal evidence, and it is not: it
+asks whether `Bu` is observable to the surrogate. It computes no ablation, no
+counterfactual, no materiality and no metric. Its truth is a measured heat-transfer
+coefficient, not a quantity of interest with a mechanism removed.
+
+So the disclaimer names it rather than waving at geometry, and a test asserts that it
+does. A reader who takes any cell here as support for the causal result has drawn a
+conclusion the data cannot carry.
+
+Templates only. Same cell, same bytes.
+"""
+
+from __future__ import annotations
+
+from physmap.benchmarks.registry import DataQuality, Redistribution, get
+from physmap.core.signals import SignalKind
+from physmap.release import CURRENT_RELEASE_STATE
+
+__all__ = ["BENCHMARK_MEASURES", "render_cell", "NOT_EVIDENCE_FOR",
+           "NEAREST_TO_CAUSAL_CASE"]
+
+#: What this benchmark measures. Both are closure/observability claims.
+BENCHMARK_MEASURES = (SignalKind.CLOSURE_VALIDITY, SignalKind.OBSERVABILITY)
+
+#: What it does not measure, and must never be quoted as supporting.
+NOT_EVIDENCE_FOR = SignalKind.CAUSAL_MATERIALITY
+
+#: The vehicle closest to the causal case, and therefore the one most likely to be
+#: mistaken for evidence of it. Named explicitly in every rendering.
+NEAREST_TO_CAUSAL_CASE = "jin_sco2_buoyancy"
+
+_OUTCOME_MEANING = {
+    "PHYSMAP_WINS": "the closure guard fired where the statistical baselines were silent",
+    "PARTIAL": "the guard fired, but the baselines were not wholly silent",
+    "DO_NO_HARM": "the guard stayed quiet where the baselines already saw the failure",
+    "BASELINE_VISIBLE": "the baselines saw it; the guard correctly claims no credit",
+}
+
+_REDISTRIBUTION_LINE = {
+    Redistribution.CLEAR: "source data ships under an affirmative licence",
+    Redistribution.NO_LICENCE_FACTS_BASIS:
+        "source data ships WITHOUT a licence, on a facts basis (see NOTICE)",
+    Redistribution.AGAINST_PUBLISHER_TERMS:
+        "source data ships AGAINST an express publisher term (see NOTICE)",
+    Redistribution.EXCLUDED_BY_DECISION: "source data does not ship",
+}
+
+
+def render_cell(cell: dict, *, recomputed: bool = False) -> str:
+    vid = cell["vehicle_id"]
+    rec = get(vid)
+    kinds = " + ".join(k.value for k in BENCHMARK_MEASURES)
+
+    lines = [
+        f"{vid}  [{cell['empirical_outcome']}]",
+        f"  measures        {kinds}",
+        f"  NOT evidence for {NOT_EVIDENCE_FOR.value} -- no cell here computes an",
+        f"                  ablation, a counterfactual, a materiality or any metric.",
+        f"                  Not even {NEAREST_TO_CAUSAL_CASE}, which IS a mixed-convection",
+        f"                  vertical tube and is the closest vehicle to the causal case:",
+        f"                  it asks whether its buoyancy parameter is observable, nothing more.",
+        "",
+        f"  domain          {cell['domain']}",
+        f"  regime          {cell.get('regime', 'n/a')}",
+        f"  failure driver  {cell['failure_var']} ({cell['failure_observability']})",
+        f"  surrogate sees  {', '.join(cell.get('surrogate_inputs', []))}",
+        f"  train / test    {cell.get('n_train')} / {cell.get('n_test')}",
+        "",
+        f"  outcome         {cell['empirical_outcome']} -- "
+        f"{_OUTCOME_MEANING.get(cell['empirical_outcome'], 'see the benchmark report')}",
+        f"  guard passed    {cell.get('observability_guard_passed')}",
+        f"  numbers from    {'this run (recomputed)' if recomputed else 'the banked matrix'}",
+    ]
+    if cell.get("caveat"):
+        lines.append(f"  caveat          {cell['caveat']}")
+    if cell.get("rationale"):
+        lines.append(f"  rationale       {cell['rationale']}")
+
+    lines.append("")
+    lines.append(f"  provenance      {rec.source}")
+    lines.append(f"  values          {rec.how_values_were_produced}")
+    lines.append(f"  redistribution  {_REDISTRIBUTION_LINE[rec.redistribution]}")
+
+    if rec.quality is not DataQuality.BENCHMARK_GRADE:
+        lines.append("")
+        lines.append(f"  DATA QUALITY    {rec.quality.value.upper()}")
+        lines.append(f"                  {rec.quality_note}")
+
+    lines.append("")
+    lines.append(f"  release         {CURRENT_RELEASE_STATE.value} -- this build reports "
+                 f"no precision, recall or F1.")
+    return "\n".join(lines)

physmap/explain/causal.py

@@ -0,0 +1,82 @@
+"""Deterministic explanations for causal assessments.
+
+Rendered templates. No LLM, no sampling, no model call anywhere in this path -- the same
+inputs give byte-identical output, which is what makes an explanation checkable rather
+than merely fluent.
+
+Every rendering states its evidence state and its release state, so an explanation can
+never be quoted as a performance claim that this build does not make.
+"""
+
+from __future__ import annotations
+
+from physmap.applicability.screen import Applicability, ScreenResult
+from physmap.core.signals import Signal
+from physmap.materiality.estimator import MaterialityResult, MaterialityStatus
+from physmap.release import CURRENT_RELEASE_STATE, EvidenceState
+
+__all__ = ["render_screen", "render_materiality", "render_signal"]
+
+_EVIDENCE_NOTE = {
+    EvidenceState.SYNTHETIC_FIXTURE:
+        "Synthetic fixture: inputs are constructed, not measured. No claim about any "
+        "real case follows from this result.",
+    EvidenceState.DECLARATIVE:
+        "Declarative: the preconditions are asserted from the case description, not read "
+        "from data. This demonstrates refusal logic; it is not an evidence-backed case.",
+    EvidenceState.MEASURED:
+        "Measured: inputs come from recorded data with stated provenance.",
+}
+
+
+def _footer(evidence_state: EvidenceState) -> str:
+    return (
+        f"  evidence: {evidence_state.value} -- {_EVIDENCE_NOTE[evidence_state]}\n"
+        f"  release:  {CURRENT_RELEASE_STATE.value} -- this build reports no precision, "
+        f"recall or F1."
+    )
+
+
+def render_screen(result: ScreenResult) -> str:
+    verdict = {
+        Applicability.APPLICABLE: "APPLICABLE",
+        Applicability.NOT_APPLICABLE: "NOT APPLICABLE",
+        Applicability.INSUFFICIENT_EVIDENCE: "INSUFFICIENT EVIDENCE",
+    }[result.applicability]
+    lines = [
+        f"{result.case_id}  [{verdict}]",
+        f"  quantity of interest: {result.qoi}",
+        f"  reason code:          {result.reason_code.value}",
+        f"  why:                  {result.rationale}",
+    ]
+    lines.extend(f"  note:                 {n}" for n in result.notes)
+    lines.append(_footer(result.evidence_state))
+    return "\n".join(lines)
+
+
+def render_materiality(result: MaterialityResult) -> str:
+    head = (
+        f"{result.mechanism_id} -> {result.qoi}  "
+        f"[{'materiality ' + format(result.value, '.4g') if result.is_usable() else result.status.value.upper()}]"
+    )
+    lines = [head, f"  why: {result.reason}"]
+    if result.status is MaterialityStatus.ESTIMATED:
+        i = result.inputs
+        lines.append(
+            f"  inputs: qoi_full={i.qoi_full:g}  qoi_ablated={i.qoi_ablated:g}  "
+            f"provenance={i.provenance.value}"
+        )
+    else:
+        lines.append("  inputs: incomplete -- no value is inferred, and none is a zero.")
+    lines.append(_footer(result.evidence_state))
+    return "\n".join(lines)
+
+
+def render_signal(signal: Signal) -> str:
+    state = "FIRED" if signal.fired else "quiet"
+    value = "n/a" if signal.value is None else format(signal.value, ".4g")
+    thresh = "n/a" if signal.threshold is None else format(signal.threshold, ".4g")
+    return (
+        f"{signal.kind.value}  [{state}]  value={value}  threshold={thresh}\n"
+        f"  {signal.rationale}"
+    )

physmap/guardrail/__init__.py

@@ -0,0 +1,38 @@
+"""Public API for the physmap CredibilityGuardrail.
+
+Importing this package pulls numpy + sklearn (via the pipeline detectors) but
+never torch or an LLM SDK — the no-heavy-imports guard stays green. Bare
+`import physmap` does NOT import this package; it is loaded lazily on first
+access to a guardrail symbol (see physmap/__init__.py).
+"""
+
+from physmap.guardrail.configs import (
+    Assessment,
+    ClosureValidityDetectorConfig,
+    ColumnMap,
+    DetectorResult,
+    DistanceDetectorConfig,
+    GPVarianceDetectorConfig,
+    NoveltyDetectorConfig,
+)
+from physmap.guardrail.enums import (
+    AggregatorKind,
+    DensityMethod,
+    Device,
+    DetectorKind,
+    Disposition,
+    Observability,
+    Regime,
+    Verdict,
+)
+from physmap.guardrail.guardrail import CredibilityGuardrail
+
+__all__ = [
+    "CredibilityGuardrail",
+    # enums
+    "Regime", "DetectorKind", "DensityMethod", "AggregatorKind", "Device",
+    "Observability", "Verdict", "Disposition",
+    # configs / data contracts
+    "NoveltyDetectorConfig", "DistanceDetectorConfig", "GPVarianceDetectorConfig",
+    "ClosureValidityDetectorConfig", "ColumnMap", "DetectorResult", "Assessment",
+]

physmap/guardrail/aggregator_observability.py

@@ -0,0 +1,187 @@
+"""The observability-weighted aggregator — where the physics signal is trusted
+precisely on the axes the statistical baselines are structurally blind to.
+
+This is NOT a pipeline.core.Aggregator (that returns the internal fire/quiet
+Verdict and sees only decision_signals); it needs the observability dict + the
+governing fired bound, so it has its own combine(). Three branches, keyed on the
+FIRED BOUND's observability, not baseline silence:
+
+  UNOBSERVABLE → REJECT          baselines blind → their silence is expected, not
+                                 reassuring → trust the corpus. THE product value.
+  PARTIAL      → UNCERTAIN/REVIEW honest interim; defer, do not over-fire.
+  OBSERVABLE / → baseline verdict corpus redundant → defer to baselines, never
+   corpus quiet                  double-count (do-no-harm).
+
+The Disposition reuses the shipped DefeasibleAdjudicator (action_class ∈ the 5
+SHACL classes), mapped to the public 4-way Disposition enum. Verdict is the public
+4-way enum (distinct from the internal fire/quiet core.Verdict).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from physmap.guardrail.enums import Disposition, Observability, Regime, Verdict
+from physmap.guardrail.weighting_heuristic import (
+    LEAN_BASELINE_TRUST,
+    LEAN_CORPUS_TRUST,
+    WEIGHT_GRADED,
+    graded_lean,
+    resolve_partial,
+)
+from physmap.pipeline.assessment_v06 import (
+    _PATTERN_ID_BY_DETECTOR,
+    WeakenerAnnotationNode,
+)
+from physmap.pipeline.core import DetectorResult
+from physmap.pipeline.defeasible_aggregator import DefeasibleAdjudicator
+from physmap.pipeline.validity_signal import PerBoundMargin
+
+
+CORPUS_NAME = "closure_validity"
+
+# SHACL action_class → public Disposition. The public enum (spec-locked at 4) is
+# narrower than the 5 SHACL classes: acquire-validation maps to REVIEW, and
+# change-cou folds into RESTRICT_COU (both narrow/alter the context of use).
+_DISPOSITION_FROM_ACTION = {
+    "characterize-region": Disposition.CHARACTERIZE_REGION,
+    "restrict-cou": Disposition.RESTRICT_COU,
+    "accept-residual-risk": Disposition.ACCEPT_RESIDUAL_RISK,
+    "acquire-validation": Disposition.REVIEW,
+    "change-cou": Disposition.RESTRICT_COU,
+}
+
+
+@dataclass(frozen=True)
+class AggregateOutcome:
+    verdict: Verdict
+    disposition: Disposition
+    action_class: str        # the SHACL action_class (kept for graph/audit consistency)
+    rule: str                # which branch fired (debug / rationale seed)
+
+
+def _build_weakeners(decision_signals: dict[str, DetectorResult]) -> list[WeakenerAnnotationNode]:
+    """One WeakenerAnnotation per FIRED detector — the adjudicator's input. Mirrors
+    assessment_v06's construction but needs no truth/Discrepancy (placeholder ids)."""
+    return [
+        WeakenerAnnotationNode(
+            id_=f"weakener:guardrail/{name}",
+            pattern_id=_PATTERN_ID_BY_DETECTOR.get(name, name),
+            affected_node="discrepancy:guardrail",
+            justification=r.rationale,
+        )
+        for name, r in decision_signals.items()
+        if r.fired
+    ]
+
+
+@dataclass
+class ObservabilityWeightedAggregator:
+    """The default aggregator. status_weighting is informational here (the
+    governing bound is chosen upstream in the detector); kept for parity."""
+
+    status_weighting: bool = True
+    _adjudicator: DefeasibleAdjudicator = field(default_factory=DefeasibleAdjudicator, repr=False)
+
+    def combine(
+        self,
+        *,
+        decision_signals: dict[str, DetectorResult],
+        observability: dict[str, Observability],
+        fired_bound: PerBoundMargin | None,
+        severities: dict[str, str | None],
+        fired_closure_id: str | None = None,
+        regime: Regime | None = None,
+    ) -> AggregateOutcome:
+        coord = fired_bound.coord if fired_bound is not None else None
+        obs = observability.get(coord) if coord is not None else None
+
+        if fired_bound is not None and obs is Observability.UNOBSERVABLE:
+            # Corpus fired on a bound the baselines are STRUCTURALLY BLIND to.
+            # Trust it. Disposition from the adjudicator over ALL fired weakeners.
+            action = self._adjudicate(decision_signals)
+            return AggregateOutcome(
+                Verdict.REJECT, _DISPOSITION_FROM_ACTION[action], action,
+                "unobservable-corpus-trusted",
+            )
+
+        if fired_bound is not None and obs is Observability.PARTIAL:
+            return self._partial_outcome(
+                decision_signals, severities, coord, fired_closure_id, regime,
+            )
+
+        # OBSERVABLE (corpus redundant) or corpus quiet → baseline verdict.
+        return self._baseline_outcome(decision_signals, severities)
+
+    def _partial_outcome(
+        self,
+        decision_signals: dict[str, DetectorResult],
+        severities: dict[str, str | None],
+        coord: str,
+        closure_id: str | None,
+        regime: Regime | None,
+    ) -> AggregateOutcome:
+        """The PARTIAL middle. Uncalibrated → DEFER (honest UNCERTAIN), exactly as
+        before. Calibrated (a real vehicle has set this regime+variable's Layer-2c
+        degree) → the continuous-blend graded weight: corpus-trust near the unobservable
+        pole, baseline verdict near the observable pole (corpus redundant), else a
+        calibrated WARN soft-flag. No rule change at graduation — we just read the
+        richer corpus value."""
+        regime_value = regime.value if regime is not None else None
+        decision = (
+            resolve_partial(closure_id, coord, regime_value=regime_value)
+            if closure_id else None
+        )
+        if decision is None or decision.weight_target != WEIGHT_GRADED:
+            # Uncalibrated, or a labeled lean — set membership can't weight it; defer.
+            return AggregateOutcome(
+                Verdict.UNCERTAIN, Disposition.REVIEW, "acquire-validation",
+                "partial-defer",
+            )
+
+        lean = graded_lean(decision.partial_degree)
+        if lean == LEAN_CORPUS_TRUST:
+            # Calibrated near the unobservable pole → trust the corpus fire.
+            action = self._adjudicate(decision_signals)
+            return AggregateOutcome(
+                Verdict.REJECT, _DISPOSITION_FROM_ACTION[action], action,
+                "partial-graded-corpus-trust",
+            )
+        if lean == LEAN_BASELINE_TRUST:
+            # Calibrated near the observable pole → corpus redundant; defer to baselines.
+            return self._baseline_outcome(decision_signals, severities)
+        # Mid-axis → calibrated soft-flag: warn + characterize the partial-driver region.
+        return AggregateOutcome(
+            Verdict.WARN, Disposition.CHARACTERIZE_REGION, "characterize-region",
+            "partial-graded-softflag",
+        )
+
+    def _baseline_outcome(
+        self,
+        decision_signals: dict[str, DetectorResult],
+        severities: dict[str, str | None],
+    ) -> AggregateOutcome:
+        # Exclude the corpus detector entirely — never double-count on observable
+        # axes; this is what makes OBSERVABLE equivalent to statistical-only.
+        baselines = {n: r for n, r in decision_signals.items() if n != CORPUS_NAME}
+        fired = {n: r for n, r in baselines.items() if r.fired}
+        action = self._adjudicate(baselines)            # adjudicate over fired baselines only
+
+        if not fired:
+            verdict = Verdict.TRUSTWORTHY
+        elif any(severities.get(n) == "reject" for n in fired):
+            verdict = Verdict.REJECT
+        else:
+            verdict = Verdict.WARN
+        return AggregateOutcome(
+            verdict, _DISPOSITION_FROM_ACTION[action], action, "baseline-verdict",
+        )
+
+    def _adjudicate(self, decision_signals: dict[str, DetectorResult]) -> str:
+        weakeners = _build_weakeners(decision_signals)
+        result = self._adjudicator.adjudicate(
+            weakeners=weakeners,
+            decision_signals=decision_signals,
+            discrepancy_id="discrepancy:guardrail",
+        )
+        return result.action_class

physmap/guardrail/classify.py

@@ -0,0 +1,147 @@
+"""Structural observability — the one genuinely new mechanism.
+
+At fit time, classify each resolved closure's validity-bound variable as
+OBSERVABLE / PARTIAL / UNOBSERVABLE by SET MEMBERSHIP against the surrogate's
+declared inputs. NOT CV-R²: that estimator is retrospective (needs truth + a
+region + a population) and cannot run at deployment. This is pure — a corpus
+lookup + a feature-name map + a corpus tag; no truth, no population.
+
+Also houses the coordinate-name bridges the guardrail shares. Three vocabularies
+are in play:
+  * corpus coords (long):     reynolds_number, prandtl_number, x_over_D, richardson_number
+  * surrogate inputs (short): Re, Pr, x_over_D, Ri
+  * detector features:        log10_Re, Pr, x_over_D
+FEATURE_TO_CORPUS_COORD (from validity_signal) is the canonical feature↔coord
+source; the short-name + meta-key bridges are added here.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from physmap.corpus.calibration import ClosureEntry, index_by_id, load_corpus
+from physmap.guardrail.corpus_regimes import (
+    KNOWN_PARTIAL,
+    REGIME_TO_CLOSURES,
+    observability_class_for,
+)
+from physmap.guardrail.enums import Observability, Regime
+from physmap.pipeline.validity_signal import FEATURE_TO_CORPUS_COORD
+
+
+# Corpus coord → surrogate-input name(s) that would make it observable. These mirror
+# FEATURE_TO_CORPUS_COORD; the absent-but-correlated axes (richardson_number/Ri,
+# viscosity_ratio_wall_bulk) are listed explicitly so set-membership reads them as
+# absent from a (Re, Pr) surrogate and routes them PARTIAL rather than OBSERVABLE.
+_COORD_TO_INPUT_ALIASES: dict[str, tuple[str, ...]] = {
+    "reynolds_number": ("Re", "log10_Re"),
+    "prandtl_number": ("Pr",),
+    "x_over_D": ("x_over_D", "log10_x_over_D"),
+    "richardson_number": ("Ri", "log10_Ri"),
+    "viscosity_ratio_wall_bulk": ("ratio_mu_w_b",),
+    # Jin: Liu buoyancy parameter Bu is NOT a (Re, Pr) surrogate input and (MEASURED) not recoverable
+    # from them — cv_r2_knn ~ 0 over the deploy region, 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). Its only alias is its own meta key and it is NOT known-partial, so set-
+    # membership reads it absent → UNOBSERVABLE (the pole, like Casper). Distinct physical group from
+    # richardson_number (Gr/Re^2); the same-name trap is avoided by its own coordinate.
+    "liu_buoyancy_parameter": ("Bu",),
+    # Casper: tunnel freestream noise is a distinct flow-environment axis, NOT a
+    # surrogate input and NOT recoverable from (M, Re/m, x) — its only alias is
+    # its own feature, so set-membership reads it absent → UNOBSERVABLE (the
+    # PHYSMAP_WINS classification: baselines are structurally blind to it).
+    "freestream_noise_rms_pitot_pct": ("freestream_noise_pct",),
+    # Marineau: the entropy-layer/shock ratio S_T/X_SW is a deterministic
+    # function of nose radius (Rn) and unit Reynolds at fixed Mach — BOTH
+    # surrogate inputs — so it is recoverable from the inputs → OBSERVABLE
+    # (baseline-visible). The negative control: a real validity bound exists,
+    # but the steelman baseline already sees the failure via Rn.
+    "entropy_layer_shock_ratio": ("Rn_mm", "Re_per_m"),
+}
+
+# Corpus coord → the raw meta key the feature extractor reads (extract_features
+# computes log10_Re from meta["Re"], reads meta["Pr"], meta["x_over_D"], …).
+_COORD_TO_META_KEY: dict[str, str] = {
+    "reynolds_number": "Re",
+    "prandtl_number": "Pr",
+    "x_over_D": "x_over_D",
+    "richardson_number": "Ri",
+    "viscosity_ratio_wall_bulk": "ratio_mu_w_b",
+    "liu_buoyancy_parameter": "Bu",                             # Jin (sCO2 vertical-tube buoyancy)
+    "freestream_noise_rms_pitot_pct": "freestream_noise_pct",   # Casper
+    "entropy_layer_shock_ratio": "st_xsw_ratio",                # Marineau
+}
+
+# Short surrogate-input name → canonical feature name extract_features understands.
+_INPUT_TO_FEATURE: dict[str, str] = {
+    "Re": "log10_Re",
+    "Pr": "Pr",
+    "x_over_D": "x_over_D",
+    "Ri": "Ri",
+    "Dh_mm": "log10_Dh_mm",
+    "alpha_star": "alpha_star",
+}
+
+
+def input_to_feature(name: str) -> str:
+    """Surrogate-input name → feature name (pass-through if already a feature)."""
+    return _INPUT_TO_FEATURE.get(name, name)
+
+
+def coord_input_aliases(coord: str) -> tuple[str, ...]:
+    """The surrogate-input name(s) whose presence makes `coord` observable."""
+    if coord in _COORD_TO_INPUT_ALIASES:
+        return _COORD_TO_INPUT_ALIASES[coord]
+    return tuple(f for f, c in FEATURE_TO_CORPUS_COORD.items() if c == coord)
+
+
+def coord_to_feature(coord: str) -> str | None:
+    """Corpus coord → canonical baseline feature name, or None if the coord has
+    no baseline feature (e.g. richardson_number is not in the feature space)."""
+    feats = [f for f, c in FEATURE_TO_CORPUS_COORD.items() if c == coord]
+    if not feats:
+        return None
+    for f in feats:           # prefer the passthrough form (x_over_D over log10_x_over_D)
+        if f == coord:
+            return f
+    return sorted(feats)[0]
+
+
+def coord_to_meta_key(coord: str) -> str | None:
+    """Corpus coord → the raw data column / meta key the extractor needs."""
+    return _COORD_TO_META_KEY.get(coord)
+
+
+def load_default_corpus_index() -> dict[str, ClosureEntry]:
+    """Load + index the installed calibration corpus (closure_id → ClosureEntry)."""
+    return index_by_id(load_corpus())
+
+
+def classify_observability(
+    surrogate_inputs: Sequence[str],
+    regime: Regime,
+    corpus_index: dict[str, ClosureEntry],
+) -> dict[str, Observability]:
+    """Map each resolved closure's bound variable → its structural observability.
+
+    UNLISTED (or no resolved closures) → {} → the guard runs statistical-only.
+    A bound variable is OBSERVABLE if the surrogate consumes its axis; PARTIAL if
+    it is tagged known-partial (absent-but-correlated); else UNOBSERVABLE.
+    """
+    if regime is Regime.UNLISTED:
+        return {}
+    inputs = set(surrogate_inputs)
+    out: dict[str, Observability] = {}
+    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[coord] = Observability.OBSERVABLE
+            elif observability_class_for(closure_id, coord) == KNOWN_PARTIAL:
+                out[coord] = Observability.PARTIAL
+            else:
+                out[coord] = Observability.UNOBSERVABLE
+    return out

physmap/guardrail/configs.py

@@ -0,0 +1,120 @@
+"""Detector config dataclasses, the ColumnMap data contract, and the public
+result types (DetectorResult, Assessment) for the CredibilityGuardrail.
+
+A detector is specified by a bare DetectorKind (no params) OR a frozen config
+object (params). Continuous params are numbers; categorical params are enums.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Union
+
+from physmap.guardrail.enums import (
+    DensityMethod,
+    DetectorKind,
+    Device,
+    Disposition,
+    Observability,
+    Verdict,
+)
+
+
+# ── Detector specs (bare enum if no params; config object if params) ──────────
+@dataclass(frozen=True)
+class NoveltyDetectorConfig:
+    kind: DetectorKind = DetectorKind.NOVELTY_DENSITY
+    method: DensityMethod = DensityMethod.GMM
+    components: int = 1
+    warn_pct: float = 99.0
+    reject_pct: float = 99.9
+    device: Device = Device.CPU
+
+
+@dataclass(frozen=True)
+class DistanceDetectorConfig:
+    kind: DetectorKind = DetectorKind.DISTANCE_TO_TRAINING
+    k: int = 3
+    device: Device = Device.CPU
+
+
+@dataclass(frozen=True)
+class GPVarianceDetectorConfig:
+    kind: DetectorKind = DetectorKind.GP_VARIANCE
+    kernel: str = "matern52"
+    device: Device = Device.CPU
+
+
+@dataclass(frozen=True)
+class ClosureValidityDetectorConfig:
+    kind: DetectorKind = DetectorKind.CLOSURE_VALIDITY
+    graded: bool = True              # continuous distance-past-bound; False = binary
+    status_weighting: bool = True    # weight signal by bound status (confirmed > … > claimed)
+
+
+@dataclass(frozen=True)
+class ConformalResidualDetectorConfig:
+    """The observable-pole conformal statistical mode (spec v0.1, action #4). Opt-in —
+    NOT in the default detector set, so it is strictly additive."""
+    kind: DetectorKind = DetectorKind.CONFORMAL_RESIDUAL
+    alpha: float = 0.1               # target miscoverage / in-distribution false-alarm rate
+    calib_frac: float = 0.3          # fraction of train held out for the conformal calibration split
+    random_state: int = 20260605     # locked seed (matches the GP emulator)
+    device: Device = Device.CPU
+
+
+DetectorSpec = Union[
+    DetectorKind,
+    NoveltyDetectorConfig,
+    DistanceDetectorConfig,
+    GPVarianceDetectorConfig,
+    ClosureValidityDetectorConfig,
+    ConformalResidualDetectorConfig,
+]
+
+
+@dataclass(frozen=True)
+class ColumnMap:
+    """Column schema for the Path / named-array branches.
+
+    `inputs` is the FULL assessment-coordinate set the data carries — a SUPERSET
+    of surrogate_inputs that MUST include the bound variables the closure-validity
+    detector reads (e.g. x_over_D even when the surrogate only sees Re, Pr).
+    """
+    inputs: list[str]
+    truth: str = "truth"
+    prediction: str = "prediction"
+
+
+# ── Results ───────────────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class DetectorResult:
+    detector: DetectorKind
+    score: float
+    fired: bool
+    threshold: float | None
+    rationale: str
+
+
+@dataclass(frozen=True)
+class Assessment:
+    verdict: Verdict
+    disposition: Disposition
+    rationale: str
+    signals: dict[DetectorKind, DetectorResult]
+    observability: Observability | None
+    fired_bound_variable: str | None
+    # Context needed to render the v0.6 SHACL subgraph (to_graph). Not part of the
+    # narrative surface, but the Discrepancy/Disposition nodes require it. truth is
+    # optional: a deployment without truth still yields a flat Assessment, but
+    # to_graph() then raises (the Discrepancy shape pins exactly-one solverTruth).
+    surrogate_prediction: float | None = None
+    solver_truth: float | None = None
+    operating_point: tuple = ()
+    closure_id: str | None = None
+    region: str = ""              # human-readable coords, e.g. "Re=55570, x_over_D=1.42"
+
+    def to_graph(self) -> dict:
+        """v0.6-conformant, SHACL-valid JSON-LD subgraph (reuses assessment_v06)."""
+        from physmap.guardrail.graph import assessment_to_graph
+        return assessment_to_graph(self)