Skip to content

Merge-Window Predictor

The ADR 0010 predictor is an advisory software gate for one already-validated lock-window sample. It consumes only the closed MergeWindowFeatureVector surface, loads runtime weights with verified-surrogate: provenance, and returns a logistic lock probability with a conformal interval. The result cannot widen the verified fire envelope: advisory fire is permitted only when the MIF-011 kinematic safety certificate passes, the hardware veto gate permits fire, and the conformal lower probability meets the configured threshold.

Contract

The predictor deliberately stays small and auditable:

  • MergeWindowPredictorWeights validates every scalar weight, a non-negative conformal radius, a strict (0, 1) decision threshold, and verified-surrogate provenance.
  • load_merge_window_predictor_weights loads those weights from a runtime JSON file, so calibration data stays outside the verified RTL path.
  • predict_merge_window accepts either a MergeWindowFeatureVector or an exact mapping with MERGE_WINDOW_FEATURE_KEYS, then revalidates the boundary before scoring.
  • MergeWindowPrediction.advisory_fire_permitted is false if the safety certificate fails or the veto gate does not permit fire, regardless of model probability.

This is a calibrated policy surface, not a dispatch kernel. It does not add HDL, rewrite the trigger fabric, or create a performance claim; the verified safety/veto chain remains the controlling path.

Python API

merge_window_predictor

Advisory merge-window predictor constrained by ADR 0010.

The predictor consumes only :class:~scpn_mif_core.kinematic.MergeWindowFeatureVector, requires runtime weights with verified-surrogate provenance, and stays subordinate to the sampled kinematic safety certificate plus the hardware veto gate. It never widens the verified fire envelope: its advisory may only accept a window that those existing guards already permit.

MergeWindowPredictorWeights(intercept, phase_lock_error_weight, reference_error_weight, separation_weight, streak_weight, order_parameter_weight, conformal_radius, decision_threshold, provenance) dataclass

Runtime grey-box weights calibrated on a verified FUSION surrogate seam.

Parameters

intercept: Logistic-model intercept. phase_lock_error_weight: Weight for phase_lock_error_rad from the lock-window feature vector. reference_error_weight: Weight for reference_error_m from the lock-window feature vector. separation_weight: Weight for separation_m from the lock-window feature vector. streak_weight: Weight for streak from the lock-window feature vector. order_parameter_weight: Weight for order_parameter from the lock-window feature vector. conformal_radius: Additive probability radius for conformal prediction intervals. decision_threshold: Probability threshold the conformal lower bound must meet before the advisory can accept a window. provenance: Runtime calibration provenance. It must start with verified-surrogate: so analytic-only weights cannot satisfy ADR 0010.

__post_init__()

Validate numeric weights and verified-surrogate calibration provenance.

MergeWindowPrediction(score, lock_probability, conformal_lower_probability, conformal_upper_probability, decision_threshold, safety_passed, veto_permit, boundary_validated, advisory_fire_permitted, reason, provenance) dataclass

Veto-subordinate advisory prediction for one lock-window feature vector.

The probability interval is clipped to [0, 1]. advisory_fire_permitted is true only when the kinematic safety certificate passed, the veto gate permitted fire, and the conformal lower probability meets the configured threshold.

load_merge_window_predictor_weights(path)

Load runtime predictor weights from a JSON file.

Parameters

path: JSON file containing the fields of :class:MergeWindowPredictorWeights.

Returns

MergeWindowPredictorWeights Validated weights with verified-surrogate provenance.

Raises

ValueError If the JSON payload is not an object or any field is invalid.

predict_merge_window(features, weights, safety_certificate, *, veto_permit)

Predict whether a lock window is admissible inside verified gates.

Parameters

features: The closed ADR 0010 lock-window feature vector, either as the dataclass returned by :func:merge_window_feature_vector or as an exact mapping with the same keys. weights: Runtime grey-box weights loaded from verified-surrogate provenance. safety_certificate: Existing MIF-011 sampled kinematic safety certificate. A failed certificate always blocks the advisory regardless of model score. veto_permit: Existing hardware veto/fast-veto decision. False always blocks the advisory regardless of model score.

Returns

MergeWindowPrediction Probability, conformal interval, and the final veto-subordinate advisory.