Skip to content

Merge-Window Predictor Feature Boundary

Boundary status

The grey-box merge-window predictor (M2) is now built on top of this boundary guard. This module remains its first line of defence: the enumerated lock-window feature contract and the fail-closed validator that both adversarial critics of the SotA-trajectory study required before the predictor could exist. See ADR 0010 for the full decision and ADR 0001 for the ownership boundary it protects.

Closed feature set

A timing predictor predicts better the more plasma state it reads — and the more plasma state it reads, the further it creeps across the ownership boundary into FUSION's FRC equilibrium, flux, temperature, density, and MHD evolution. The guard removes that temptation by construction: the admissible inputs are exactly the lock-window observables MIF already owns, and nothing else.

MERGE_WINDOW_FEATURE_KEYS = {
  phase_lock_error_rad,   # merge-window alignment error  (MergeWindowSample)
  reference_error_m,      # chamber-reference position error (MergeWindowSample)
  separation_m,           # plasmoid separation            (MergeWindowSample)
  streak,                 # consecutive-lock-candidate count (MergeWindowSample)
  order_parameter,        # Kuramoto phase coherence       (DopplerKuramotoState)
}

validate_merge_window_features fails closed on any out-of-boundary key (boundary creep) and on any missing key (an underspecified vector); out-of-boundary keys are reported first. merge_window_feature_vector is the only sanctioned extraction path, so a feature vector is lock-window by construction and never touches sibling physics.

This is a contract guard, not a numeric kernel — it enumerates and checks keys once per prediction, so it has no multi-language acceleration path, the same as the dataclass spec validators. The predictor itself lives in Merge-window predictor and revalidates this boundary before every advisory score.

Python API

merge_window_features

Feature-boundary guard for the roadmap grey-box merge-window predictor (M2).

The predictor itself is roadmap, gated on a verified data surrogate (see ADR 0010, docs/adr/0010-merge-window-predictor-feature-boundary.md). This module is the delivered precondition both adversarial critics demanded before any predictor is built: an enumerated lock-window feature contract and a validator that fails closed when anything outside that boundary is offered.

The boundary is the whole point. A timing predictor that could read FRC equilibrium fields, flux, temperature, density, or any other FUSION physics internal would creep straight across the ownership boundary (ADR 0001) and could not be reviewed. The admissible inputs are exactly the lock-window observables MIF already owns — the merge-window alignment/separation errors and the Doppler-Kuramoto phase-coherence state — and nothing else. Offering an out-of-boundary key raises, so an over-reaching predictor cannot even be constructed.

This is a contract guard, not a numeric kernel: it enumerates and checks feature keys once per prediction, so it has no multi-language acceleration path (the same as the dataclass spec validators).

MergeWindowFeatureBoundaryError

Bases: ValueError

Raised when a feature mapping crosses the lock-window boundary.

Either an offered key is not in :data:MERGE_WINDOW_FEATURE_KEYS (an out-of-boundary ingestion — the boundary-creep the predictor contract forbids), or a required key is missing (an underspecified feature vector). Both are fail-closed: the predictor may never run on an unvalidated mapping.

MergeWindowFeatureVector(phase_lock_error_rad, reference_error_m, separation_m, streak, order_parameter) dataclass

A validated lock-window feature vector — the predictor's only admissible input.

The fields are exactly the keys of :data:MERGE_WINDOW_FEATURE_KEYS. Construct it from real monitor output with :func:merge_window_feature_vector; the frozen, slotted shape means no out-of-boundary attribute can be smuggled in after the fact.

to_mapping()

Return the feature vector as a plain {key: value} mapping.

The streak count is widened to float so the whole vector is numerically uniform for a downstream model, while the dataclass keeps its integer field.

validate_merge_window_features(features)

Fail closed unless features is exactly the lock-window feature set.

features is the candidate mapping destined for the predictor. This raises :class:MergeWindowFeatureBoundaryError when any key lies outside :data:MERGE_WINDOW_FEATURE_KEYS (boundary creep) and, separately, when any required key is absent (an underspecified vector); the out-of-boundary keys are reported before a missing key so the violation is actionable.

is_within_merge_window_boundary(features)

Return whether features is exactly the admissible lock-window set.

A total, non-raising counterpart to :func:validate_merge_window_features for call sites that branch on admissibility rather than enforce it.

merge_window_feature_vector(sample, state)

Extract the boundary-safe feature vector from real monitor output.

This is the only sanctioned construction path: it reads the lock-window observables (alignment, reference error, separation, streak) off the sample :class:~scpn_mif_core.kinematic.merge_window.MergeWindowSample and the phase coherence (order parameter) off the state :class:~scpn_mif_core.kinematic.doppler_kuramoto.DopplerKuramotoState at the same instant, so the returned vector is lock-window by construction and never touches sibling physics.

Status

The guard is delivered and gated into the curated facade and the capability manifest. The predictor consumes it directly and still rejects analytic-only weights by requiring runtime verified-surrogate: provenance.