physmap 0.2.0__py3-none-any.whl

physmap/guardrail/regime_observability.py

@@ -0,0 +1,519 @@
+"""PhysMAP Regime → Observability Mapping — schema, generator, validator, loader, CLI.
+
+The static knowledge the observability classifier resolves against at `fit`
+(spec: docs/specs/PhysMAP_Regime_Observability_Mapping_Spec_v0_1.md), materialized
+as ONE version-tagged JSONL artifact with three tables (one `table`-tagged record
+per line, line-diffable):
+
+  * regimes                — Regime → closure_ids                       (spec Layer 1)
+  * closure_bounds         — closure_id → [{variable, bound, status,…}] (spec Layer 1)
+  * variable_observability — variable → observability_class + the graded-partial
+                             degree slot                                (spec Layers 2a + 2c)
+
+AUTHORITY: this artifact is a GENERATED PROJECTION of the existing authoritative
+sources — it is never a second runtime source of truth. The classifier keeps
+resolving against the code maps directly; this file just makes the mapping
+inspectable, version-tagged, and shippable. The sources:
+
+  * regimes / closure set     ← guardrail.corpus_regimes.REGIME_TO_CLOSURES
+  * bounds (Layer 1)          ← corpus.calibration validated_range (corpus.jsonl)
+  * observability_class (2a)  ← guardrail.corpus_regimes.observability_class_for
+  * partial_degree slot (2c)  ← guardrail.corpus_regimes.partial_degree_for
+
+Regenerate with `python -m physmap.guardrail.regime_observability build`. A test
+(tests/test_regime_observability_mapping.py) asserts the committed artifact equals
+a fresh build, so it cannot silently drift from the sources.
+
+This is a guardrail-LAYER tool (it reads the guardrail's corpus_regimes maps), not
+a corpus-layer one — so it lives here rather than under corpus/, which stays
+stdlib-only and foundational.
+
+Honesty discipline (spec): empty Layer-2c cells stay `uncalibrated` — an
+uncalibrated degree that drove a weight would be a fabricated empirical claim.
+The validator REJECTS any `uncalibrated` slot carrying a degree, and any
+`calibrated` slot missing its degree or its `calibrated_by` provenance.
+
+Torch-free and LLM-free (the no-heavy-imports guard stays green); numpy/sklearn
+arrive transitively via the guardrail package, which is expected at this layer.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+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,
+    partial_degree_for,
+)
+from physmap.guardrail.enums import Regime
+
+# ── controlled vocabularies ───────────────────────────────────────────────────
+
+OBSERVABILITY_CLASSES = {"structural-binary", "known-partial"}
+DEGREE_STATUSES = {"n/a", "uncalibrated", "calibrated"}
+TABLE_NAMES = {"regimes", "closure_bounds", "variable_observability"}
+
+# Display alias: the short surrogate-input name for a corpus coord, mirroring the
+# classifier's coord↔input bridge (physmap/guardrail/classify.py). Readability only —
+# the authoritative join key everywhere is the long corpus coord name.
+_COORD_SHORT_ALIAS: dict[str, str] = {
+    "reynolds_number": "Re",
+    "prandtl_number": "Pr",
+    "x_over_D": "x_over_D",
+    "richardson_number": "Ri",
+    "viscosity_ratio_wall_bulk": "mu_w/mu_b",
+}
+
+MAPPING_VERSION = "0.2.3"   # 0.2.3: +Jin sCO2 vertical-tube buoyancy — MIXED_CONVECTION_VERTICAL_TUBE -> dittus-boelter-buoyancy-sco2 carrying liu_buoyancy_parameter (Liu Bu). FIRST genuinely WIRED closure since 0.2.2 (the buoyancy benchmark cell FIRES), so the projection grows by one regime + one closure (mapping.jsonl regenerated, not byte-identical). Bu classed structural-binary -> UNOBSERVABLE (MEASURED cv_r2_knn~0 from (Re,Pr); Casper-structured direction toggle, NOT a partial middle). 0.2.2: +VDI gnielinski-1976 prandtl_ratio_bulk_wall & temperature_ratio_bulk_wall (UNOBSERVABLE, fire on gnielinski's regimes) + new inert closures (swanson-catton grashof_number; mack/perfect-gas mach_number; blasius-horizontal grouping coords), additive. 0.2.1: +richardson_number on blasius-pohlhausen (Sparrow-Gregg)
+
+# Checkout-only artifact: generated by this module, committed, and checked for
+# drift by a test. It is not runtime data and does not ship in the wheel.
+def _default_path() -> Path:
+    from physmap._paths import repo_root
+    root = repo_root()
+    base = root if root is not None else Path.cwd()
+    return base / "data" / "regime_observability" / "mapping.jsonl"
+
+
+DEFAULT_PATH = _default_path()
+
+
+# ── schema dataclasses ──────────────────────────────────────────────────────────
+
+@dataclass
+class RegimeRow:
+    """regimes table — one Regime member (minus UNLISTED) and its closure set."""
+    regime: str                       # Regime enum value, e.g. "entrance_region_pipe"
+    closures: list[str]               # closure_ids
+
+
+@dataclass
+class BoundExpr:
+    """One validity bound of a closure, projected from the calibration corpus."""
+    variable: str                     # corpus coord (long), e.g. "reynolds_number"
+    variable_short: str               # surrogate-input alias, e.g. "Re" (display only)
+    bound: str                        # human expr, e.g. "3000 <= Re <= 5e+06"
+    status: str                       # corpus bound_status (confirmed/claimed/…)
+    min: float | None
+    max: float | None
+    unit: str
+
+
+@dataclass
+class ClosureBoundRow:
+    """closure_bounds table — one row per distinct closure (deduped across regimes)."""
+    closure_id: str
+    bounds: list[BoundExpr]
+
+
+@dataclass
+class VariableObservabilityRow:
+    """variable_observability table — Layer 2a tag + Layer 2c graded-degree slot."""
+    variable: str                     # corpus coord (long)
+    variable_short: str               # display alias
+    observability_class: str          # ∈ OBSERVABILITY_CLASSES
+    partial_degree: dict | None       # null until calibrated; {regime_value: degree} once
+    degree_status: str                # ∈ DEGREE_STATUSES
+    calibrated_by: list[str] = field(default_factory=list)  # middle-vehicle ids (provenance)
+
+
+@dataclass
+class RegimeObservabilityMapping:
+    """The whole artifact: three tables. Dataclass equality drives the drift test."""
+    regimes: list[RegimeRow]
+    closure_bounds: list[ClosureBoundRow]
+    variable_observability: list[VariableObservabilityRow]
+
+
+# ── human-readable bound expression ───────────────────────────────────────────
+
+def _fmt(x: float) -> str:
+    return f"{x:g}"
+
+
+def _bound_expr(name: str, lo: float | None, hi: float | None) -> str:
+    if lo is not None and hi is not None:
+        return f"{_fmt(lo)} <= {name} <= {_fmt(hi)}"
+    if lo is not None:
+        return f"{name} >= {_fmt(lo)}"
+    if hi is not None:
+        return f"{name} <= {_fmt(hi)}"
+    return name
+
+
+def _short_alias(coord: str) -> str:
+    return _COORD_SHORT_ALIAS.get(coord, coord)
+
+
+# ── generator (the projection from authoritative sources) ─────────────────────
+
+def _variable_rows(
+    closure_bounds: list[ClosureBoundRow],
+) -> list[VariableObservabilityRow]:
+    """One row per distinct bound variable, with its (per-variable) class + 2c slot.
+
+    The class is a property of the variable's physics, so it must be consistent across
+    every closure the coord appears in; the validator enforces that. The graded degree
+    is regime-specific, so partial_degree is a {regime_value: degree} map merged over
+    the coord's closures — empty (→ uncalibrated) until a middle vehicle calibrates it.
+    """
+    coord_to_closures: dict[str, list[str]] = {}
+    for cbr in closure_bounds:
+        for b in cbr.bounds:
+            seen = coord_to_closures.setdefault(b.variable, [])
+            if cbr.closure_id not in seen:
+                seen.append(cbr.closure_id)
+
+    rows: list[VariableObservabilityRow] = []
+    for coord in sorted(coord_to_closures):
+        cids = coord_to_closures[coord]
+        classes = {observability_class_for(cid, coord) for cid in cids}
+        klass = KNOWN_PARTIAL if KNOWN_PARTIAL in classes else "structural-binary"
+
+        if klass != KNOWN_PARTIAL:
+            degree, status, calby = None, "n/a", []
+        else:
+            merged: dict[str, float] = {}
+            calby = []
+            any_calibrated = False
+            for cid in cids:
+                d, st, cb = partial_degree_for(cid, coord)
+                if st == "calibrated" and d:
+                    any_calibrated = True
+                    merged.update(d)
+                    for x in cb:
+                        if x not in calby:
+                            calby.append(x)
+            if any_calibrated:
+                degree, status = merged, "calibrated"
+            else:
+                degree, status, calby = None, "uncalibrated", []
+
+        rows.append(VariableObservabilityRow(
+            variable=coord, variable_short=_short_alias(coord),
+            observability_class=klass, partial_degree=degree,
+            degree_status=status, calibrated_by=calby,
+        ))
+    return rows
+
+
+def build_mapping(
+    corpus_index: dict[str, ClosureEntry] | None = None,
+    regime_to_closures: dict[Regime, tuple[str, ...]] | None = None,
+) -> RegimeObservabilityMapping:
+    """Compose the three tables from the authoritative code/corpus sources.
+
+    Deterministic: regimes in enum-declaration order (minus UNLISTED), closures and
+    variables sorted by id/name, bounds in corpus order. A dangling closure_id (in a
+    regime but not in the corpus) is omitted from closure_bounds and flagged by the
+    validator, rather than silently fabricated.
+    """
+    if corpus_index is None:
+        corpus_index = index_by_id(load_corpus())
+    if regime_to_closures is None:
+        regime_to_closures = REGIME_TO_CLOSURES
+
+    listed = [r for r in Regime if r is not Regime.UNLISTED]
+
+    regimes = [
+        RegimeRow(regime=r.value, closures=list(regime_to_closures.get(r, ())))
+        for r in listed
+    ]
+
+    closure_ids: set[str] = set()
+    for r in listed:
+        closure_ids.update(regime_to_closures.get(r, ()))
+
+    closure_bounds: list[ClosureBoundRow] = []
+    for cid in sorted(closure_ids):
+        entry = corpus_index.get(cid)
+        if entry is None:
+            continue  # dangling — validator flags it
+        bounds = [
+            BoundExpr(
+                variable=b.coord, variable_short=_short_alias(b.coord),
+                bound=_bound_expr(_short_alias(b.coord), b.min, b.max),
+                status=b.bound_status, min=b.min, max=b.max, unit=b.unit,
+            )
+            for b in entry.validated_range
+        ]
+        closure_bounds.append(ClosureBoundRow(closure_id=cid, bounds=bounds))
+
+    variable_observability = _variable_rows(closure_bounds)
+
+    return RegimeObservabilityMapping(
+        regimes=regimes,
+        closure_bounds=closure_bounds,
+        variable_observability=variable_observability,
+    )
+
+
+# ── (de)serialization (one `table`-tagged record per JSONL line) ──────────────
+
+def to_records(m: RegimeObservabilityMapping) -> list[dict]:
+    recs: list[dict] = []
+    for r in m.regimes:
+        recs.append({"table": "regimes", **asdict(r)})
+    for c in m.closure_bounds:
+        recs.append({"table": "closure_bounds", **asdict(c)})
+    for v in m.variable_observability:
+        recs.append({"table": "variable_observability", **asdict(v)})
+    return recs
+
+
+def to_jsonl(m: RegimeObservabilityMapping) -> str:
+    return "".join(json.dumps(rec, ensure_ascii=False) + "\n" for rec in to_records(m))
+
+
+def from_records(records: list[dict]) -> RegimeObservabilityMapping:
+    regimes: list[RegimeRow] = []
+    closure_bounds: list[ClosureBoundRow] = []
+    variable_observability: list[VariableObservabilityRow] = []
+    for rec in records:
+        table = rec.get("table")
+        body = {k: v for k, v in rec.items() if k != "table"}
+        if table == "regimes":
+            regimes.append(RegimeRow(**body))
+        elif table == "closure_bounds":
+            body["bounds"] = [BoundExpr(**b) for b in body.get("bounds", [])]
+            closure_bounds.append(ClosureBoundRow(**body))
+        elif table == "variable_observability":
+            variable_observability.append(VariableObservabilityRow(**body))
+        else:
+            raise ValueError(f"unknown table discriminator: {table!r}")
+    return RegimeObservabilityMapping(
+        regimes=regimes,
+        closure_bounds=closure_bounds,
+        variable_observability=variable_observability,
+    )
+
+
+def load_mapping(path: str | Path = DEFAULT_PATH) -> RegimeObservabilityMapping:
+    """Parse the JSONL artifact into a RegimeObservabilityMapping. Raises on parse
+    errors; consistency must be checked separately via validate_mapping()."""
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"mapping file not found: {p}")
+    records: list[dict] = []
+    with open(p, "r", encoding="utf-8") as f:
+        for lineno, line in enumerate(f, start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                records.append(json.loads(stripped))
+            except json.JSONDecodeError as e:
+                raise ValueError(f"mapping JSONL parse error at line {lineno}: {e}") from e
+    try:
+        return from_records(records)
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"mapping schema mismatch: {e}") from e
+
+
+def mapping_fingerprint(path: str | Path = DEFAULT_PATH) -> dict:
+    """{'version', 'sha256', 'n_records'} for a save/load manifest (mirrors
+    corpus_fingerprint). Hash is over SORTED non-empty lines — order-independent."""
+    p = Path(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": MAPPING_VERSION, "sha256": digest, "n_records": len(lines)}
+
+
+# ── consistency validation (the spec's done-gate, as one function) ────────────
+
+def validate_mapping(
+    m: RegimeObservabilityMapping,
+    corpus_index: dict[str, ClosureEntry] | None = None,
+) -> dict[str, list[str]]:
+    """Return errors keyed by table name (empty dict = the mapping is consistent).
+
+    Implements the spec's done-gate invariants:
+      • enum ↔ regimes agreement (every Regime member minus UNLISTED; no strays)
+      • every regime resolves to ≥1 closure with ≥1 bound; closures exist in the corpus
+      • every Layer-1 bound variable has a Layer-2a row (and no orphan rows)
+      • a variable's observability_class is consistent across every closure it appears in
+      • known-partial → an uncalibrated|calibrated 2c slot; structural-binary → no degree
+      • honesty gate: uncalibrated carries no degree; calibrated carries degree + provenance
+    """
+    if corpus_index is None:
+        corpus_index = index_by_id(load_corpus())
+    out: dict[str, list[str]] = {}
+
+    def add(key: str, msg: str) -> None:
+        out.setdefault(key, []).append(msg)
+
+    # enum ↔ regimes
+    expected = {r.value for r in Regime if r is not Regime.UNLISTED}
+    present = [row.regime for row in m.regimes]
+    present_set = set(present)
+    for miss in sorted(expected - present_set):
+        add("regimes", f"missing regime row: {miss}")
+    for stray in sorted(present_set - expected):
+        add("regimes", f"regime row '{stray}' is not a Regime member (or UNLISTED leaked in)")
+    if len(present) != len(present_set):
+        add("regimes", "duplicate regime rows")
+    for row in m.regimes:
+        if not row.closures:
+            add("regimes", f"{row.regime}: no closures (every listed regime needs ≥1)")
+
+    # closure_bounds: dedupe, regime FK, corpus FK, ≥1 bound
+    cb_index = {c.closure_id: c for c in m.closure_bounds}
+    if len(cb_index) != len(m.closure_bounds):
+        add("closure_bounds", "duplicate closure_id rows")
+    referenced = {cid for row in m.regimes for cid in row.closures}
+    for cid in sorted(referenced):
+        if cid not in cb_index:
+            add("closure_bounds", f"closure '{cid}' referenced by a regime but has no closure_bounds row")
+    for c in m.closure_bounds:
+        if c.closure_id not in corpus_index:
+            add("closure_bounds", f"closure '{c.closure_id}' not in calibration corpus")
+        if not c.bounds:
+            add("closure_bounds", f"closure '{c.closure_id}' has no bounds")
+
+    # variable_observability: coverage, vocab, per-variable consistency, 2c slot + honesty
+    vo_index = {v.variable: v for v in m.variable_observability}
+    if len(vo_index) != len(m.variable_observability):
+        add("variable_observability", "duplicate variable rows")
+    bound_vars = {b.variable for c in m.closure_bounds for b in c.bounds}
+    for var in sorted(bound_vars):
+        if var not in vo_index:
+            add("variable_observability", f"bound variable '{var}' has no observability_class row (Layer 2a gap)")
+
+    for v in m.variable_observability:
+        if v.variable not in bound_vars:
+            add("variable_observability", f"variable '{v.variable}' has a row but appears in no closure bound (orphan)")
+        if v.observability_class not in OBSERVABILITY_CLASSES:
+            add("variable_observability",
+                f"variable '{v.variable}': observability_class '{v.observability_class}' not in {sorted(OBSERVABILITY_CLASSES)}")
+        if v.degree_status not in DEGREE_STATUSES:
+            add("variable_observability",
+                f"variable '{v.variable}': degree_status '{v.degree_status}' not in {sorted(DEGREE_STATUSES)}")
+
+        # per-variable class consistency vs the authoritative source
+        for c in m.closure_bounds:
+            if any(b.variable == v.variable for b in c.bounds):
+                src = observability_class_for(c.closure_id, v.variable)
+                if src != v.observability_class:
+                    add("variable_observability",
+                        f"variable '{v.variable}': class {v.observability_class!r} disagrees with "
+                        f"source ({c.closure_id} → {src!r}); a variable's class must be consistent "
+                        f"across every closure it appears in")
+
+        # 2c slot rules + honesty gate
+        if v.observability_class == "structural-binary":
+            if v.partial_degree is not None or v.degree_status != "n/a":
+                add("variable_observability",
+                    f"variable '{v.variable}': structural-binary must have partial_degree=null and degree_status='n/a'")
+            if v.calibrated_by:
+                add("variable_observability",
+                    f"variable '{v.variable}': structural-binary must not carry calibrated_by")
+        elif v.observability_class == "known-partial":
+            if v.degree_status not in ("uncalibrated", "calibrated"):
+                add("variable_observability",
+                    f"variable '{v.variable}': known-partial needs degree_status uncalibrated|calibrated, got {v.degree_status!r}")
+            if v.degree_status == "uncalibrated":
+                if v.partial_degree is not None or v.calibrated_by:
+                    add("variable_observability",
+                        f"variable '{v.variable}': uncalibrated must have partial_degree=null and empty "
+                        f"calibrated_by (no faked degrees — defer is the honest behavior)")
+            elif v.degree_status == "calibrated":
+                if not v.partial_degree:
+                    add("variable_observability",
+                        f"variable '{v.variable}': calibrated requires a non-empty partial_degree")
+                if not v.calibrated_by:
+                    add("variable_observability",
+                        f"variable '{v.variable}': calibrated requires non-empty calibrated_by (provenance, no laundering)")
+
+    return out
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def _print_errors(errs: dict[str, list[str]]) -> int:
+    if not errs:
+        return 0
+    total = sum(len(v) for v in errs.values())
+    print(f"mapping validation FAILED — {total} errors across {len(errs)} tables:")
+    for table in sorted(errs):
+        print(f"  [{table}]")
+        for e in errs[table]:
+            print(f"      • {e}")
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="PhysMAP Regime → Observability Mapping — generator + validator CLI",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_build = sub.add_parser("build", help="(re)generate mapping.jsonl from the sources")
+    p_build.add_argument("--path", type=Path, default=DEFAULT_PATH,
+                         help=f"output path (default: {DEFAULT_PATH})")
+
+    p_val = sub.add_parser("validate", help="run the consistency gates (+ drift check for the canonical artifact)")
+    p_val.add_argument("--path", type=Path, default=DEFAULT_PATH)
+
+    p_sum = sub.add_parser("summary", help="print a status summary of the mapping")
+    p_sum.add_argument("--path", type=Path, default=DEFAULT_PATH)
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "build":
+        m = build_mapping()
+        errs = validate_mapping(m)
+        if errs:
+            print("refusing to write — fresh build does not validate:", file=sys.stderr)
+            return _print_errors(errs)
+        args.path.parent.mkdir(parents=True, exist_ok=True)
+        args.path.write_text(to_jsonl(m), encoding="utf-8")
+        print(f"wrote {args.path}")
+        print(f"  regimes: {len(m.regimes)}  closures: {len(m.closure_bounds)}  "
+              f"variables: {len(m.variable_observability)}")
+        print(f"  fingerprint: {mapping_fingerprint(args.path)}")
+        return 0
+
+    if args.cmd == "validate":
+        try:
+            m = load_mapping(args.path)
+        except (FileNotFoundError, ValueError) as e:
+            print(f"FAILED to load mapping: {e}", file=sys.stderr)
+            return 2
+        errs = validate_mapping(m)
+        # Drift check for the canonical artifact: it must equal a fresh projection.
+        if Path(args.path).resolve() == DEFAULT_PATH.resolve() and m != build_mapping():
+            errs.setdefault("__drift__", []).append(
+                "committed mapping.jsonl != fresh build_mapping(); run `build` to regenerate")
+        if not errs:
+            print(f"mapping validation PASSED — {len(m.regimes)} regimes, "
+                  f"{len(m.closure_bounds)} closures, {len(m.variable_observability)} variables "
+                  f"({args.path})")
+            return 0
+        return _print_errors(errs)
+
+    if args.cmd == "summary":
+        m = load_mapping(args.path)
+        kp = [v for v in m.variable_observability if v.observability_class == "known-partial"]
+        calibrated = [v for v in kp if v.degree_status == "calibrated"]
+        print(f"mapping: {len(m.regimes)} regimes, {len(m.closure_bounds)} closures, "
+              f"{len(m.variable_observability)} variables  ({args.path})")
+        print(f"  known-partial variables: {len(kp)}  "
+              f"(calibrated: {len(calibrated)}, uncalibrated: {len(kp) - len(calibrated)})")
+        for v in kp:
+            print(f"    {v.variable:>18s} : {v.degree_status}"
+                  + (f"  calibrated_by={v.calibrated_by}" if v.calibrated_by else ""))
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

physmap/guardrail/render.py

@@ -0,0 +1,159 @@
+"""Deterministic explanation renderer — no LLM.
+
+Each renderer composes a FIXED template over STRUCTURED facts: the closure + the
+bound that fired (calibration corpus), the bound variable + its observability
+class, the evidence-corpus provenance (source citation + measured divergence),
+and the baseline state. Same inputs → same string (regression-testable); no model
+call. Determinism: provenance claims are picked after sorting by claim_id, floats
+use a fixed precision, and no timestamps appear.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from physmap.corpus.evidence import Claim, Source
+from physmap.guardrail.enums import Observability
+from physmap.pipeline.validity_signal import PerBoundMargin
+
+
+_OBS_PHRASE = {
+    Observability.UNOBSERVABLE: "is not a surrogate input (unobservable to input-based OOD detectors)",
+    Observability.PARTIAL: "is not a surrogate input but is correlated with one (only partially observable)",
+    Observability.OBSERVABLE: "is a surrogate input (observable to input-based OOD detectors)",
+}
+
+
+def _fmt_interval(lo: float | None, hi: float | None) -> str:
+    """Human-friendly bound text. A huge upper bound reads as a one-sided ≥."""
+    if lo is not None and (hi is None or hi >= 1e8):
+        return f"≥ {lo:.3g}"
+    if hi is not None and (lo is None or lo <= 0.0):
+        return f"≤ {hi:.3g}"
+    if lo is not None and hi is not None:
+        return f"[{lo:.3g}, {hi:.3g}]"
+    return "(unbounded)"
+
+
+def _pick_provenance(claims_for_closure: Sequence[Claim], variable: str) -> Claim | None:
+    """Deterministically choose the provenance claim FOR THE FIRED VARIABLE.
+
+    Only ever returns a claim about `variable` — never borrows a divergence
+    measured on a different axis (that would be provenance laundering: a Re
+    divergence is not evidence about an x/D bound). Prefer a variable-matching
+    claim carrying a measured_divergence; else a variable-matching originating
+    claim (source citation only, no magnitude). Sorted by claim_id for stability.
+    """
+    var_claims = sorted(
+        (c for c in claims_for_closure if c.bound and c.bound.variable == variable),
+        key=lambda c: c.claim_id,
+    )
+    for c in var_claims:
+        if c.measured_divergence is not None:
+            return c
+    return var_claims[0] if var_claims else None
+
+
+def _provenance_phrase(
+    claim: Claim | None, sources_index: dict[str, Source],
+) -> str:
+    if claim is None:
+        return "no evidence-corpus claim is recorded for this bound"
+    src = sources_index.get(claim.source_id)
+    cite = src.citation if src is not None else claim.source_id
+    md = claim.measured_divergence
+    if md is not None and md.magnitude_pct is not None:
+        return (f"the literature ({cite}) reports divergence up to "
+                f"{md.magnitude_pct:.3g}% past this bound")
+    return f"the literature ({cite}) documents this bound"
+
+
+def render_unobservable(
+    *,
+    closure_id: str,
+    fired_bound: PerBoundMargin,
+    bound_interval: tuple[float | None, float | None],
+    baseline_fired: bool,
+    claims_for_closure: Sequence[Claim],
+    sources_index: dict[str, Source],
+) -> str:
+    """THE product-value explanation: the corpus fired on a bound the baselines
+    are structurally blind to, so their silence is expected, not reassuring."""
+    var = fired_bound.coord
+    obs_phrase = _OBS_PHRASE[Observability.UNOBSERVABLE]
+    prov = _provenance_phrase(_pick_provenance(claims_for_closure, var), sources_index)
+    bound_txt = _fmt_interval(*bound_interval)
+    baseline_txt = (
+        "An input-based OOD detector also fired."
+        if baseline_fired
+        else f"Input-based OOD detectors are silent because they cannot observe {var}."
+    )
+    return (
+        f"Prediction relies on {closure_id} beyond its validated {var} bound "
+        f"({var} {bound_txt}); {var} {obs_phrase}, and {prov}. {baseline_txt}"
+    )
+
+
+def render_partial(
+    *,
+    closure_id: str,
+    fired_bound: PerBoundMargin,
+    bound_interval: tuple[float | None, float | None],
+) -> str:
+    """PARTIAL deferral — honest interim until the middle-vehicle calibration
+    table exists. We do not over-fire; we flag for review."""
+    var = fired_bound.coord
+    bound_txt = _fmt_interval(*bound_interval)
+    return (
+        f"Prediction relies on {closure_id} beyond its validated {var} bound "
+        f"({var} {bound_txt}); {var} {_OBS_PHRASE[Observability.PARTIAL]}. Set "
+        f"membership cannot yet weight this axis against the input-based OOD detectors, so the "
+        f"verdict is deferred for review rather than over-fired."
+    )
+
+
+def render_partial_graded(
+    *,
+    closure_id: str,
+    fired_bound: PerBoundMargin,
+    bound_interval: tuple[float | None, float | None],
+    degree: float,
+    calibrated_by: Sequence[str],
+    soft_flag: bool,
+) -> str:
+    """Graded PARTIAL — a real vehicle has calibrated this (regime, variable)'s Layer-2c
+    observability degree, so we weight the corpus fire by (1 - degree) instead of
+    deferring. soft_flag → calibrated mid-axis WARN; else → corpus-trust near the
+    unobservable pole. The weight traces to `calibrated_by` (provenance, not runtime)."""
+    var = fired_bound.coord
+    bound_txt = _fmt_interval(*bound_interval)
+    by = ", ".join(calibrated_by) or "(unknown)"
+    if soft_flag:
+        tail = (
+            f"its calibrated observability (degree={degree:g}, from {by}) places it "
+            f"mid-axis, so the corpus fire is a calibrated soft-flag (corpus weight "
+            f"{1.0 - degree:g}) raised for review, scaled against the input-based OOD detectors rather "
+            f"than over-fired."
+        )
+    else:
+        tail = (
+            f"its calibrated observability (degree={degree:g}, from {by}) places it near "
+            f"the unobservable pole, so the corpus fire is trusted — the input-based OOD detectors are "
+            f"largely blind on this axis here."
+        )
+    return (
+        f"Prediction relies on {closure_id} beyond its validated {var} bound "
+        f"({var} {bound_txt}); {var} {_OBS_PHRASE[Observability.PARTIAL]}. {tail}"
+    )
+
+
+def render_baseline(*, baseline_fired_names: Sequence[str], all_quiet: bool) -> str:
+    """OBSERVABLE / corpus-quiet narrative: the verdict defers to the statistical
+    baselines (the corpus is redundant on observable axes — never double-counted)."""
+    if all_quiet:
+        return ("All input-based OOD detectors are quiet and no physics bound is "
+                "violated on an unobservable axis; prediction is trustworthy.")
+    fired = ", ".join(sorted(baseline_fired_names)) or "(none)"
+    return (f"Input-based OOD detector(s) fired ({fired}); the physics signal is "
+            f"redundant here (observable axis) and is deferred to those detectors, "
+            f"not double-counted.")