transport-runtime 0.6.0__py3-none-any.whl

transport_runtime/__init__.py

@@ -0,0 +1,85 @@
+"""Transport Runtime: zero-label deployment for any fitted classifier."""
+from .core import TransportLayer, DeployedModel, DeployedConformal, moment_delta
+from .ot_gap import (cdf_l1_gap, label_free_gap, aux_minmax, aux_uniform,
+                     aux_model, total_coverage_gap)
+from .channels import discover_score_channels, quantile_channel
+from .clinical import channel_clinical_audit, clinical_threshold_audit, compare_decision_curves, decision_curve
+from .selection import select_transport_channel, select_transport_channel_stability
+from .slope import (
+    allocate_labels_for_slope,
+    apply_channel_affine,
+    channel_affine_repair,
+    channel_affine_margin_interval,
+    bootstrap_channel_affine,
+    ece_from_p,
+    evaluate_affine_repair,
+    fit_channel_affine,
+    margins_from_model,
+    slope_threshold_sensitivity,
+    summarize_slope_risk,
+    within_channel_score_shift,
+)
+from .certify import CertificateRecommendation, evaluate_certificate, recommend_certificate, recommend_certificate_from_audit_pack, summarize_channel_clinical_risk, summarize_slope_uncertainty
+from .audit import audit_pack, save_audit_pack
+from .diff import contract_diff
+from .verify import CheckResult, VerificationReport, verify_contract
+from .compiler import (
+    CertificateSpec,
+    ChannelSpec,
+    DeploymentContract,
+    PrevalenceSpec,
+    TransportCompiler,
+)
+from .robust import (
+    PrevalenceIntervalSet,
+    choose_repair,
+    deploy_eb,
+    deploy_interval,
+    empirical_bayes_target,
+    estimate_repair_gain,
+    interval_regret_bound,
+    interval_uniform_variance,
+    minimax_target,
+    worst_case_channel_bias,
+)
+from .identify import (
+    IdentificationResult,
+    STATUS_INCONCLUSIVE,
+    STATUS_NOT_TRANSPORTABLE_BY_ADJUSTMENT,
+    STATUS_TRANSPORTABLE,
+    ancestors,
+    d_connected,
+    descendants,
+    intervened_graph,
+    is_dag,
+    s_admissible,
+    transportability_id,
+    valid_backdoor_set,
+)
+
+__all__ = [
+    'TransportLayer', 'DeployedModel', 'DeployedConformal', 'moment_delta',
+    'ChannelSpec', 'PrevalenceSpec', 'CertificateSpec', 'TransportCompiler', 'DeploymentContract',
+    'quantile_channel', 'discover_score_channels', 'select_transport_channel', 'select_transport_channel_stability',
+    'decision_curve', 'compare_decision_curves', 'clinical_threshold_audit', 'channel_clinical_audit',
+    'margins_from_model', 'within_channel_score_shift', 'summarize_slope_risk', 'slope_threshold_sensitivity',
+    'fit_channel_affine', 'apply_channel_affine', 'channel_affine_repair',
+    'bootstrap_channel_affine', 'channel_affine_margin_interval',
+    'allocate_labels_for_slope',
+    'ece_from_p', 'evaluate_affine_repair',
+    'verify_contract', 'VerificationReport', 'CheckResult',
+    'recommend_certificate', 'recommend_certificate_from_audit_pack', 'CertificateRecommendation', 'evaluate_certificate', 'summarize_slope_uncertainty', 'summarize_channel_clinical_risk',
+    'audit_pack', 'save_audit_pack', 'contract_diff',
+    'cdf_l1_gap', 'label_free_gap', 'aux_minmax', 'aux_uniform',
+    'aux_model', 'total_coverage_gap',
+    'PrevalenceIntervalSet', 'deploy_interval', 'interval_regret_bound',
+    'deploy_eb', 'empirical_bayes_target', 'estimate_repair_gain', 'choose_repair', 'interval_uniform_variance',
+    'minimax_target', 'worst_case_channel_bias',
+    'IdentificationResult', 'transportability_id', 'valid_backdoor_set',
+    's_admissible', 'd_connected', 'intervened_graph', 'is_dag',
+    'ancestors', 'descendants', 'STATUS_TRANSPORTABLE', 'STATUS_INCONCLUSIVE',
+    'STATUS_NOT_TRANSPORTABLE_BY_ADJUSTMENT',
+]
+__version__ = '0.6.0'
+
+from transport_runtime.pipeline import TransportPipeline  # noqa: E402,F401

transport_runtime/audit.py

@@ -0,0 +1,210 @@
+"""Standardized audit pack for deployment contracts.
+
+An audit pack is the single JSON artifact that combines:
+- contract manifest;
+- slope-risk summary;
+- contract verification;
+- labeled-target certificate replay, when labels are available.
+"""
+from __future__ import annotations
+
+import json
+
+import numpy as np
+from scipy.special import expit
+
+from .certify import evaluate_certificate
+from .clinical import clinical_threshold_audit, decision_curve
+from .compiler import DeploymentContract
+from .slope import bootstrap_channel_affine, channel_affine_margin_interval, margins_from_model
+from .verify import verify_contract
+
+
+def _tolist(value):
+    return np.asarray(value, dtype=float).tolist()
+
+
+def _slope_repair_certificate(contract, X, channels, y, boot_kwargs):
+    levels = getattr(contract.deployed, "levels_", None)
+    if levels is None:
+        return None
+    f_repaired = margins_from_model(contract.layer.model, X) + np.asarray(levels, dtype=float)[np.asarray(channels, dtype=int)]
+    boot = bootstrap_channel_affine(f_repaired, y, channels, **boot_kwargs)
+    interval = channel_affine_margin_interval(f_repaired, channels, boot)
+    width = interval["upper"] - interval["lower"]
+    return {
+        "note": "finite-label uncertainty for affine slope repair fitted after level repair; "
+                "this is fitting uncertainty, not proof of target calibration",
+        "alpha": float(boot["alpha"]),
+        "ci_level": float(boot["ci_level"]),
+        "n_boot": int(boot["n_boot"]),
+        "channel_n": _tolist(boot["channel_n"]),
+        "a": _tolist(boot["a"]),
+        "b": _tolist(boot["b"]),
+        "a_mean": _tolist(boot["a_mean"]),
+        "b_mean": _tolist(boot["b_mean"]),
+        "a_std": _tolist(boot["a_std"]),
+        "b_std": _tolist(boot["b_std"]),
+        "a_ci_lower": _tolist(boot["a_ci_lower"]),
+        "a_ci_upper": _tolist(boot["a_ci_upper"]),
+        "b_ci_lower": _tolist(boot["b_ci_lower"]),
+        "b_ci_upper": _tolist(boot["b_ci_upper"]),
+        "bootstrap_success_rate": _tolist(boot["bootstrap_success_rate"]),
+        "margin_interval_summary": {
+            "n": int(len(width)),
+            "mean_width": float(np.mean(width)),
+            "median_width": float(np.median(width)),
+            "q95_width": float(np.quantile(width, 0.95)),
+            "max_width": float(np.max(width)),
+        },
+    }
+
+
+def _clinical_threshold_audit(contract, X, channels, y, thresholds):
+    base_p = expit(margins_from_model(contract.layer.model, X))
+    repaired_p = contract.predict_proba(X, channels)
+    audit = clinical_threshold_audit(y, base_p, repaired_p, thresholds=thresholds)
+    return {
+        "note": "threshold-specific net-benefit audit comparing repaired contract output with unrepaired model output; "
+                "synthetic or labeled-target audit evidence does not by itself prove clinical effectiveness",
+        "thresholds": audit["thresholds"],
+        "base_net_benefit": audit["base_net_benefit"],
+        "repaired_net_benefit": audit["repaired_net_benefit"],
+        "repaired_minus_base": audit["repaired_minus_base"],
+        "summary": audit["summary"],
+    }
+
+
+def _channel_clinical_summary(contract, X, channels, y, thresholds):
+    thresholds = np.asarray(
+        thresholds if thresholds is not None else np.linspace(0.01, 0.99, 99),
+        dtype=float,
+    )
+    base_p = expit(margins_from_model(contract.layer.model, X))
+    repaired_p = contract.predict_proba(X, channels)
+    y = np.asarray(y, dtype=float)
+    channels = np.asarray(channels, dtype=int)
+    summaries = []
+    for g in np.unique(channels):
+        sel = channels == g
+        base = decision_curve(y[sel], base_p[sel], thresholds=thresholds)
+        repaired = decision_curve(y[sel], repaired_p[sel], thresholds=thresholds)
+        gain = np.asarray(repaired["net_benefit"], dtype=float) - np.asarray(base["net_benefit"], dtype=float)
+        j = int(np.argmax(gain))
+        summaries.append(
+            {
+                "channel": int(g),
+                "channel_n": int(sel.sum()),
+                "channel_prevalence": float(np.mean(y[sel])),
+                "integrated_gain": float(np.trapz(gain, thresholds)),
+                "max_gain": float(gain[j]),
+                "threshold_at_max_gain": float(thresholds[j]),
+                "worst_gain": float(np.min(gain)),
+                "fraction_improved": float(np.mean(gain > 0.0)),
+            }
+        )
+    integrated = np.array([row["integrated_gain"] for row in summaries], dtype=float)
+    fragile = summaries[int(np.argmin(integrated))]
+    return {
+        "note": "channel-level threshold-specific net-benefit summary; negative channel gains can be masked by aggregate averages",
+        "thresholds": thresholds.tolist(),
+        "channel_summaries": summaries,
+        "overall": {
+            "n_channels": int(len(summaries)),
+            "mean_integrated_gain": float(np.mean(integrated)),
+            "min_integrated_gain": float(np.min(integrated)),
+            "n_channels_negative_integrated_gain": int(np.sum(integrated < 0.0)),
+            "most_fragile_channel": fragile["channel"],
+            "most_fragile_integrated_gain": fragile["integrated_gain"],
+            "most_fragile_worst_gain": fragile["worst_gain"],
+        },
+    }
+
+
+def audit_pack(
+    contract: DeploymentContract,
+    X=None,
+    channels=None,
+    y=None,
+    slope_boot=False,
+    slope_boot_kwargs=None,
+    clinical=False,
+    clinical_thresholds=None,
+    channel_clinical=False,
+    channel_clinical_thresholds=None,
+) -> dict:
+    """Build a standardized audit pack for a deployment contract.
+
+    Set `slope_boot=True` to add a finite-label affine slope-repair uncertainty
+    certificate when labeled target data are supplied. The option is disabled by
+    default to keep routine audit packs lightweight.
+    """
+    pack = contract.manifest()
+    pack["slope_risk"] = contract.slope_risk
+
+    if X is not None and channels is not None:
+        pack["verification"] = verify_contract(contract, X=X, channels=channels).to_dict()
+    else:
+        pack["verification"] = None
+
+    if contract.certificate is not None and X is not None and y is not None and channels is not None:
+        pack["certificate_evaluation"] = evaluate_certificate(contract, X, y, channels)
+    else:
+        pack["certificate_evaluation"] = None
+
+    if slope_boot:
+        if X is None or y is None or channels is None:
+            raise ValueError("slope_boot=True requires X, channels, and y")
+        kwargs = dict(slope_boot_kwargs or {})
+        pack["slope_repair_certificate"] = _slope_repair_certificate(contract, X, channels, y, kwargs)
+    else:
+        pack["slope_repair_certificate"] = None
+
+    if clinical:
+        if X is None or y is None or channels is None:
+            raise ValueError("clinical=True requires X, channels, and y")
+        pack["clinical_threshold_audit"] = _clinical_threshold_audit(contract, X, channels, y, clinical_thresholds)
+    else:
+        pack["clinical_threshold_audit"] = None
+
+    if channel_clinical:
+        if X is None or y is None or channels is None:
+            raise ValueError("channel_clinical=True requires X, channels, and y")
+        pack["channel_clinical_summary"] = _channel_clinical_summary(
+            contract, X, channels, y, channel_clinical_thresholds
+        )
+    else:
+        pack["channel_clinical_summary"] = None
+
+    return pack
+
+
+def save_audit_pack(
+    contract: DeploymentContract,
+    path,
+    X=None,
+    channels=None,
+    y=None,
+    slope_boot=False,
+    slope_boot_kwargs=None,
+    clinical=False,
+    clinical_thresholds=None,
+    channel_clinical=False,
+    channel_clinical_thresholds=None,
+) -> dict:
+    """Save an audit pack JSON and return it."""
+    pack = audit_pack(
+        contract,
+        X=X,
+        channels=channels,
+        y=y,
+        slope_boot=slope_boot,
+        slope_boot_kwargs=slope_boot_kwargs,
+        clinical=clinical,
+        clinical_thresholds=clinical_thresholds,
+        channel_clinical=channel_clinical,
+        channel_clinical_thresholds=channel_clinical_thresholds,
+    )
+    with open(str(path), "w", encoding="utf-8") as f:
+        json.dump(pack, f, indent=2, sort_keys=True)
+    return pack

transport_runtime/certificate_strategy.py

@@ -0,0 +1,115 @@
+"""Three-tier certificate strategy (B2 closure, v0.6.84).
+
+Empirical basis: docs/theory_impossibility.md rounds 66-68 and
+scripts/ncs_conformal_transport_v01.py - under transport, no single conformal
+certificate is universally safe (plain split-conformal collapses
+conditionally; Mondrian trades marginal for conditional coverage; label-free
+regime features only partially separate regimes). This module operationalises
+the resulting three-tier architecture:
+
+  Tier 1 - label_free_default: conservative certificate choice from deployment
+           quantities only (target logit-spread ratio + public prevalence).
+           Always deployable; matches 2/4 regimes in validation (the two
+           extremes), conservative elsewhere.
+  Tier 2 - label_pool_audit: definitive regime classification + certificate
+           selection from a small label pool (n~50-100, the runtime's existing
+           DCA protocol). Estimates class-conditional coverage of BOTH
+           candidate certificates on the pool.
+  Tier 3 - audit output: regardless of tier, both certificates' marginal and
+           conditional coverage are emitted - 'ship the audit that chooses',
+           not a bare certificate.
+
+Reproduce the validation: PYTHONPATH=. python scripts/ncs_conformal_transport_v01.py
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def logit(p):
+    p = np.clip(np.asarray(p, dtype=float), 1e-6, 1 - 1e-6)
+    return np.log(p / (1 - p))
+
+
+def spread_ratio(p_source_calibrated, p_target_naive):
+    """logit-spread ratio (label-free regime feature; see module docstring for
+    the documented limitation - binomial variance depends on the mean, so this
+    does NOT fully separate regimes)."""
+    ls, lt = logit(p_source_calibrated), logit(p_target_naive)
+    return float(np.std(lt) / max(np.std(ls), 1e-9))
+
+
+def label_free_default(ratio, pi_public, tau=0.10, pi_lo=0.05, pi_hi=0.50):
+    """Tier 1: conservative label-free certificate choice.
+
+    Returns 'mondrian+repair' for extreme-prevalence or spread-deviation
+    regimes, else 'plain+repair'."""
+    if pi_public < pi_lo or pi_public > pi_hi:
+        return "mondrian+repair"
+    if abs(ratio - 1.0) > tau:
+        return "mondrian+repair"
+    return "plain+repair"
+
+
+def _class_coverage(p, y, c, q):
+    p = np.asarray(p, dtype=float)
+    y = np.asarray(y, dtype=int)
+    m = y == c
+    if m.sum() == 0:
+        return np.nan
+    return float(np.mean(p[m] >= q))
+
+
+def label_pool_audit(p_pool, y_pool, p_deploy_pool, q_plain, qs_mondrian,
+                     pi_public, tau=0.10, pi_lo=0.05, pi_hi=0.50):
+    """Tier 2: definitive selection from a small label pool.
+
+    Estimates class-conditional coverage of both candidate certificates on the
+    label pool and selects the one with the better worst-class coverage
+    (maximin). Falls back to the label-free default when the pool has too few
+    positives to estimate conditional coverage.
+    """
+    p_pool = np.asarray(p_pool, dtype=float)
+    y_pool = np.asarray(y_pool, dtype=int)
+    ratio = spread_ratio(p_deploy_pool, p_pool)
+    default = label_free_default(ratio, pi_public, tau, pi_lo, pi_hi)
+    n_pos = int((y_pool == 1).sum())
+    if n_pos < 10:
+        return {"certificate": default, "tier": 1, "reason": "insufficient pool positives",
+                "n_pool": len(y_pool), "n_pos": n_pos}
+
+    cov_p = {"overall": float(np.mean(p_pool >= 1 - q_plain)),
+             "y1": _class_coverage(p_pool, y_pool, 1, 1 - q_plain),
+             "y0": _class_coverage(p_pool, y_pool, 0, q_plain)}
+    # Mondrian on 2-class with deploy probabilities: case threshold from qs[1],
+    # control threshold from qs[0]; coverage uses the appropriate threshold.
+    cov_m = {"overall": float(np.mean(
+                 (p_pool >= 1 - qs_mondrian[1]) | (1 - p_pool >= 1 - qs_mondrian[0]))),
+             "y1": _class_coverage(p_pool, y_pool, 1, 1 - qs_mondrian[1]),
+             "y0": _class_coverage(p_pool, y_pool, 0, 1 - qs_mondrian[0])}
+    worst = {"plain+repair": min(cov_p["y0"], cov_p["y1"]),
+             "mondrian+repair": min(cov_m["y0"], cov_m["y1"])}
+    chosen = max(worst, key=worst.get)
+    return {"certificate": chosen, "tier": 2, "reason": "maximin on label pool",
+            "n_pool": len(y_pool), "n_pos": n_pos,
+            "coverage_plain": cov_p, "coverage_mondrian": cov_m,
+            "worst_class_coverage": worst}
+
+
+def three_tier_strategy(p_source_calibrated, p_target_naive, pi_public,
+                        p_pool=None, y_pool=None, q_plain=None, qs_mondrian=None):
+    """Tier 3 orchestrator: emits the audit that chooses.
+
+    Returns a dict with the selected certificate, the tier used, the label-free
+    default (always reported), and - when a pool is provided - both
+    certificates' conditional coverage estimates."""
+    ratio = spread_ratio(p_source_calibrated, p_target_naive)
+    default = label_free_default(ratio, pi_public)
+    out = {"spread_ratio": ratio, "label_free_default": default,
+           "tier": 1, "certificate": default}
+    if p_pool is not None and y_pool is not None:
+        audit = label_pool_audit(p_pool, y_pool, p_target_naive[:len(p_pool)],
+                                 q_plain, qs_mondrian, pi_public)
+        out.update(audit)
+        out["audit"] = {k: v for k, v in audit.items() if k.startswith("coverage")}
+    return out

transport_runtime/certify.py

@@ -0,0 +1,236 @@
+"""Certificate recommendation for Transport Runtime deployment contracts.
+
+Innovation layer: a certificate is not always equally appropriate. Small channels,
+post-repair slope-risk flags, and high public-prevalence uncertainty should change
+the certificate policy.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .compiler import CertificateSpec, DeploymentContract, _certificate_to_dict
+
+
+@dataclass(frozen=True)
+class CertificateRecommendation:
+    spec: CertificateSpec
+    reasons: tuple[str, ...]
+
+    def to_dict(self) -> dict:
+        return {
+            "spec": {
+                "alpha": self.spec.alpha,
+                "per_channel": self.spec.per_channel,
+                "weighted": self.spec.weighted,
+            },
+            "reasons": list(self.reasons),
+        }
+
+
+def summarize_slope_uncertainty(slope_uncertainty) -> dict | None:
+    """Summarize optional slope-repair uncertainty for certificate policy.
+
+    Accepts either a scalar width or an audit-pack `slope_repair_certificate`
+    dictionary containing `a_ci_lower`, `a_ci_upper`, `b_ci_lower`, and
+    `b_ci_upper`. Returns `None` when no uncertainty evidence is supplied.
+    """
+    if slope_uncertainty is None:
+        return None
+    if isinstance(slope_uncertainty, dict):
+        required = ("a_ci_lower", "a_ci_upper", "b_ci_lower", "b_ci_upper")
+        if all(k in slope_uncertainty for k in required):
+            a_width = np.asarray(slope_uncertainty["a_ci_upper"], dtype=float) - np.asarray(slope_uncertainty["a_ci_lower"], dtype=float)
+            b_width = np.asarray(slope_uncertainty["b_ci_upper"], dtype=float) - np.asarray(slope_uncertainty["b_ci_lower"], dtype=float)
+            width = a_width + b_width
+            if np.any(~np.isfinite(width)):
+                raise ValueError("slope uncertainty intervals must be finite")
+            return {
+                "max_width": float(np.max(width)),
+                "mean_width": float(np.mean(width)),
+                "n_channels": int(len(width)),
+                "source": "slope_repair_certificate",
+            }
+        if "margin_interval_summary" in slope_uncertainty:
+            q95 = float(slope_uncertainty["margin_interval_summary"].get("q95_width", np.nan))
+            if not np.isfinite(q95):
+                raise ValueError("margin interval summary must contain a finite q95_width")
+            return {
+                "max_width": q95,
+                "mean_width": q95,
+                "n_channels": len(np.asarray(slope_uncertainty.get("channel_n", [0]))),
+                "source": "margin_interval_summary",
+            }
+        raise ValueError("unsupported slope_uncertainty dictionary")
+    width = float(slope_uncertainty)
+    if not np.isfinite(width):
+        raise ValueError("slope uncertainty width must be finite")
+    return {"max_width": width, "mean_width": width, "n_channels": None, "source": "scalar"}
+
+
+def summarize_channel_clinical_risk(channel_clinical, threshold: float = 0.0) -> dict | None:
+    """Summarize channel-level clinical evidence for certificate policy."""
+    if channel_clinical is None:
+        return None
+    if not isinstance(channel_clinical, dict) or "overall" not in channel_clinical:
+        raise ValueError("channel_clinical must be an audit-pack channel_clinical_summary dictionary")
+    overall = channel_clinical["overall"]
+    return {
+        "n_channels": int(overall.get("n_channels", 0)),
+        "n_negative_channels": int(overall.get("n_channels_negative_integrated_gain", 0)),
+        "most_fragile_channel": int(overall.get("most_fragile_channel", -1)),
+        "most_fragile_integrated_gain": float(overall.get("most_fragile_integrated_gain", np.nan)),
+        "most_fragile_worst_gain": float(overall.get("most_fragile_worst_gain", np.nan)),
+        "threshold": float(threshold),
+        "source": "channel_clinical_summary",
+    }
+
+
+def recommend_certificate(
+    channel_counts,
+    slope_risk: dict | None = None,
+    prevalence_variance=None,
+    slope_uncertainty=None,
+    channel_clinical=None,
+    alpha: float = 0.1,
+    min_channel_n: int = 200,
+    high_variance_threshold: float = 0.02**2,
+    slope_uncertainty_threshold: float = 0.20,
+    channel_clinical_threshold: float = 0.0,
+) -> CertificateRecommendation:
+    """Recommend a certificate policy from deployment risk features.
+
+    Rules
+    -----
+    - small channels, slope-risk flags, high finite-label slope uncertainty, or
+      channel-level clinical losses -> weighted per-channel certificate;
+    - otherwise high prevalence uncertainty -> weighted marginal certificate;
+    - otherwise -> plain split-conformal certificate.
+    """
+    counts = np.asarray(channel_counts, dtype=float)
+    if counts.ndim != 1 or len(counts) == 0:
+        raise ValueError("channel_counts must be a non-empty vector")
+    reasons: list[str] = []
+
+    small = bool(np.any(counts < min_channel_n))
+    if small:
+        reasons.append(f"at least one channel has n < {min_channel_n}")
+
+    flagged = False
+    if slope_risk is not None:
+        flagged = int(slope_risk.get("n_flagged", 0)) > 0
+        if flagged:
+            reasons.append(f"slope-risk flagged channels: {slope_risk.get('flagged_channels', [])}")
+
+    slope_summary = summarize_slope_uncertainty(slope_uncertainty)
+    high_slope_uncertainty = False
+    if slope_summary is not None:
+        high_slope_uncertainty = bool(slope_summary["max_width"] > slope_uncertainty_threshold)
+        if high_slope_uncertainty:
+            reasons.append(
+                "high finite-label slope uncertainty: "
+                f"max width {slope_summary['max_width']:.4f} > {slope_uncertainty_threshold:.4f}"
+            )
+
+    channel_summary = summarize_channel_clinical_risk(channel_clinical, threshold=channel_clinical_threshold)
+    high_channel_clinical_risk = False
+    if channel_summary is not None:
+        has_negative_channel = channel_summary["n_negative_channels"] > 0
+        fragile_below_threshold = (
+            np.isfinite(channel_summary["most_fragile_integrated_gain"])
+            and channel_summary["most_fragile_integrated_gain"] < channel_clinical_threshold
+        )
+        high_channel_clinical_risk = bool(has_negative_channel or fragile_below_threshold)
+        if high_channel_clinical_risk:
+            reasons.append(
+                "channel-level clinical loss: "
+                f"negative channels={channel_summary['n_negative_channels']}, "
+                f"most fragile ch{channel_summary['most_fragile_channel']} "
+                f"integrated gain={channel_summary['most_fragile_integrated_gain']:.4f}"
+            )
+
+    high_var = False
+    if prevalence_variance is not None:
+        var = np.asarray(prevalence_variance, dtype=float)
+        high_var = bool(np.max(var) > high_variance_threshold)
+        if high_var:
+            reasons.append("high public-prevalence uncertainty")
+
+    if small or flagged or high_slope_uncertainty or high_channel_clinical_risk:
+        return CertificateRecommendation(
+            spec=CertificateSpec(alpha=alpha, per_channel=True, weighted=True),
+            reasons=tuple(reasons) or ("small channels or slope-risk flags",),
+        )
+    if high_var:
+        return CertificateRecommendation(
+            spec=CertificateSpec(alpha=alpha, per_channel=False, weighted=True),
+            reasons=tuple(reasons),
+        )
+    return CertificateRecommendation(
+        spec=CertificateSpec(alpha=alpha, per_channel=False, weighted=False),
+        reasons=tuple(reasons) or ("large channels, no slope-risk flags, low prevalence uncertainty",),
+    )
+
+
+def recommend_certificate_from_audit_pack(
+    pack: dict,
+    alpha: float = 0.1,
+    min_channel_n: int = 200,
+    high_variance_threshold: float = 0.02**2,
+    slope_uncertainty_threshold: float = 0.20,
+    channel_clinical_threshold: float = 0.0,
+) -> CertificateRecommendation:
+    """Recommend a certificate policy directly from an audit pack.
+
+    Requires `audit_pack(..., slope_boot=True)` so that `channel_n` and the
+    finite-label slope-repair uncertainty certificate are available.
+    """
+    if not isinstance(pack, dict):
+        raise ValueError("pack must be an audit-pack dictionary")
+    slope_cert = pack.get("slope_repair_certificate")
+    if not isinstance(slope_cert, dict) or "channel_n" not in slope_cert:
+        raise ValueError("audit pack lacks slope_repair_certificate.channel_n; run audit_pack(..., slope_boot=True)")
+    counts = np.asarray(slope_cert["channel_n"], dtype=int)
+    return recommend_certificate(
+        counts,
+        slope_risk=pack.get("slope_risk"),
+        prevalence_variance=None,
+        slope_uncertainty=slope_cert,
+        channel_clinical=pack.get("channel_clinical_summary"),
+        alpha=alpha,
+        min_channel_n=min_channel_n,
+        high_variance_threshold=high_variance_threshold,
+        slope_uncertainty_threshold=slope_uncertainty_threshold,
+        channel_clinical_threshold=channel_clinical_threshold,
+    )
+
+
+def evaluate_certificate(contract: DeploymentContract, X, y, channels) -> dict:
+    """Replay a compiled certificate on labeled target data.
+
+    Returns overall empirical coverage and per-channel coverage, including the
+    minimum channel coverage. This closes the loop between certificate policy
+    recommendation and post-deployment evaluation.
+    """
+    if contract.certificate is None:
+        raise ValueError("contract has no certificate; compile with CertificateSpec")
+    X = np.asarray(X)
+    y = np.asarray(y, dtype=int)
+    channels = np.asarray(channels, dtype=int)
+    if not (len(X) == len(y) == len(channels)):
+        raise ValueError("X, y, and channels must have matching lengths")
+
+    pred_sets = contract.certificate.predict_set(X, channels)
+    covered = np.array([int(yi in s) for yi, s in zip(y, pred_sets)], dtype=float)
+    per_channel = {}
+    for g in sorted(set(channels)):
+        sel = channels == g
+        per_channel[int(g)] = float(np.mean(covered[sel])) if sel.any() else np.nan
+    return {
+        "overall_coverage": float(np.mean(covered)),
+        "per_channel_coverage": per_channel,
+        "min_channel_coverage": float(np.nanmin(list(per_channel.values()))),
+        "n": int(len(y)),
+        "certificate_spec": _certificate_to_dict(contract.certificate_spec),
+    }