Strict Output Masks And Provenance

Start from the stable strict inference contract:

decoded, bottom_mask, gap_mask = result

The v0.6.x fault/semantic provenance mask set is stable too: fault_mask, semantic_bottom_mask, and bottom_provenance are guaranteed strict-inference result attributes. They are diagnostic detail layered on top of the three tuple outputs, not replacements for bottom_mask. Schema-v2 bundles declare this promotion with strict_inference_exports="stable_provenance_outputs". TorchScript preserves the three-field output tuple decoded, bottom_mask, and gap_mask; ONNX bundle exports include those three outputs plus fault_mask, semantic_bottom_mask, and bottom_provenance. When provenance layout metadata is written, the sidecar key is now inference_output_schema; the old experimental_inference_output_schema key is accepted as a DeprecationWarning-emitting alias for recorded bundles.

What each stable field means

  • decoded: finite decoded payload when available; NaN payload for bottoms.
  • bottom_mask: authoritative fail-closed mask for strict bottom events, including non-finite P/Q payloads and strict threshold bottoms.
  • gap_mask: finite samples in the monitor-only region tau_infer <= |Q| < tau_train.

The stable rules are:

  • use bottom_mask for reject or fallback decisions
  • do not treat gap_mask as another kind of bottom
  • keep bottom_mask and gap_mask disjoint

How the stable provenance diagnostics fit

Fault/semantic provenance does not replace the stable contract. It only explains why an entry in bottom_mask became bottom.

Two stable layouts exist today:

  • fault_mask + semantic_bottom_mask
  • bottom_provenance integer codes

They both refine the same merged bottom decision:

bottom_mask == (fault_mask | semantic_bottom_mask)
bottom_mask == (bottom_provenance != 0)

fault_mask and semantic_bottom_mask are not disjoint. A sample with both an IEEE-fault payload and a below-threshold denominator sets both masks; for example, non-finite P with |Q| < tau_infer is both fault and semantic. Consumers can route on bottom_mask for every bottom, on the split masks for fault-specific or semantic-specific handling, or on bottom_provenance when a single merged provenance tensor is the only exported diagnostic. Consumers reading the split masks see the full picture; consumers reading bottom_provenance alone see the same four-state picture through NONE, FAULT, SEMANTIC, and MIXED (3 = mixed in the integer tensor). The bottom_provenance states encode the same finite, fault, semantic, and mixed cases as the split masks.

For strict-flattened heads (FRU-style or hand-written equivalents), the fault/semantic split is also an implementation-hygiene signal. These heads should produce semantic bottoms in normal operation: a finite Q = 0, or |Q| < tau_infer, at a known singularity is the expected pathway and routes to semantic_bottom_mask. An IEEE-non-finite payload reaching strict inference usually means some intermediate computation in the head used raw IEEE division at a singularity, or an external numerical fault propagated in. That routes to fault_mask and should be rare in well-constructed strict-flattened heads; frequent fault_mask triggers are a signal that the head is doing IEEE arithmetic where SCM-aware fracterm arithmetic was intended. Heads that intentionally use IEEE arithmetic and rely on the fail-closed bridge for bottom detection will naturally produce fault_mask triggers as their normal pathway, and that is correct behavior for those heads.

At runtime, treat a sustained high fault_rate from this path as a non-finite/runtime debugging signal, not a model-quality metric. Set alerting thresholds for fault_rate separately from semantic_bottom_rate. If a consumer computes a finite tiny-denominator hazard mask, pass it to StrictInferenceMonitor or strict_inference_rates(...) as numerical_hazard_mask; the resulting numerical_hazard_rate is a separate conditioning monitor and must not be conflated with either fault or semantic bottom rates.

Consumer pattern

Write consumers against the stable three-field output first, then read the guaranteed provenance attributes:

decoded, bottom_mask, gap_mask = result

fault_mask = result.fault_mask
semantic_bottom_mask = result.semantic_bottom_mask
bottom_provenance = result.bottom_provenance

Use getattr(...) only in adapters that intentionally support recorded schema-v1 bundles or minimal external messages that predate the promotion.

When to use each signal

  • bottom_mask: deployment safety gate, abstention, analytic fallback routing for any bottom.
  • gap_mask: monitoring, dashboards, and conservative "numerically close" alerts.
  • fault_mask / semantic_bottom_mask: provenance-aware routing when fault bottoms and semantic bottoms need different fallback behavior.
  • bottom_provenance: merged provenance-aware routing when split masks are not exported.

Non-finite IEEE payloads in P, Q, or an evaluated guarded-FRU validity factor are fault-like bottoms. They set fault_mask, not semantic_bottom_mask. Finite denominator threshold failures set semantic_bottom_mask when |Q| < tau_infer; finite near-threshold monitoring cases remain in gap_mask when tau_train is configured. Finite validity factors below their configured threshold also set semantic_bottom_mask. Use InferenceConfig.numerical_hazard_threshold only as monitor metadata for external finite-denominator hazard reporting. Finite tiny denominators are no longer folded into fault_mask merely because they cross that monitor threshold. The old provenance_fault_threshold name is a deprecated alias and is not provenance for bottom or a fault_mask classification knob.

If you need a deployment control contract, depend on bottom_mask and gap_mask. If you need to analyze fault-like versus semantic bottoms, use the stable fault/semantic provenance attributes as an extra diagnostic layer.

FRU structural validity-factor provenance is a separate experimental axis: it answers "which symbolic denominator subexpression bottomed" during FRU flattening. FlattenedFRU.denominator_provenance remains available for compatibility, and FlattenedFRU.strict_validity_sources records the symbolic denominator factors used by guarded FRU evaluation when they are not already enforced by the reduced payload denominator; this structural trace is not promoted by the stable fault/semantic mask split and has no defined promotion gate. It also does not inherit the historical Q2 downstream-benefit, overhead, repeatability, and non-regression thresholds; those are precedent for the shape of a future structural-provenance gate, not pre-committed criteria. If a future consumer requests promotion, define the structural-provenance gate at that time instead of pre-committing thresholds now. The reserved promotion path is FlattenedFRU.structural_validity_output_schema(...), which gives each retained factor deterministic value, fault-mask, and semantic-mask output names without making those outputs stable today. The public trace is experimental, but guarded strict FRU evaluation still treats those validity factors as required internal checks for reduced payloads. When numeric validity factors are passed through strict inference, they are checked factorwise with ~isfinite(V_i) | (abs(V_i) < tau_i) so the fault/semantic split follows the kind of disjunct rather than the position of the factor in the payload.