Mask Provenance Guide¶

This guide describes the v0.6.x mask provenance contract exposed by strict_inference(...) and SCMInferenceWrapper. The result object carries stable bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, and bottom_provenance attributes while still unpacking as (decoded, bottom_mask, gap_mask) for backward compatibility. Provenance only refines why an entry landed in bottom_mask; it does not replace bottom_mask or change how gap_mask works.

Provenance axes¶

ZeroProofML tracks two provenance axes separately:

Axis	Surface	Stability	Meaning
Fault versus semantic bottom provenance	`strict_inference(...)` result attributes: `fault_mask`, `semantic_bottom_mask`, `bottom_provenance`	Stable	Runtime strict-inference diagnostics explaining why an entry reached `bottom_mask`
Structural validity provenance	`FlattenedFRU.denominator_provenance`, `FlattenedFRU.strict_validity_sources`, and derived validity-factor views	Experimental	Symbolic FRU flattening metadata identifying denominator or divisor subexpressions, with guarded validity factors tracking the bottom-producing factors not already enforced by the reduced payload denominator

The structural validity-factor provenance axis is FRU-flattening-specific: it answers "which symbolic denominator subexpression bottomed." It remains experimental with no defined promotion gate and is not promoted by the stable strict-inference mask split. It does not automatically inherit the historical Q2 gate thresholds. If a future consumer requests promotion, define a new structural-provenance gate at that time with fresh thresholds for that surface while citing the Q2 pattern of downstream benefit, overhead, repeatability, and stable-contract non-regression as precedent. The legacy FlattenedFRU.denominator_provenance and derived validity-factor views remain available in the experimental API. FlattenedFRU.strict_validity_sources is the experimental source field guarded FRU evaluation uses directly; its derived validity_factors view contains the factors moved outside the reduced payload denominator. Guarded evaluation keeps these entries factorwise instead of multiplying them into one scalar product, so thresholds and source provenance stay attached to the factor that failed. FlattenedFRU.structural_validity_output_schema(...) is the reserved promotion path for this axis: it assigns deterministic value, fault-mask, and semantic-mask output names for each retained factor while the current surface remains experimental. Source kinds distinguish direct explicit_denominator factors from divisor_numerator and divisor_denominator factors introduced by division flattening. When numeric validity factors are passed to strict_inference(...), each factor V_i uses the same fail-closed predicate ~isfinite(V_i) | (abs(V_i) < tau_i): the non-finite branch routes to fault_mask, while the below-threshold branch routes to semantic_bottom_mask.

Stable contract first¶

Every strict inference result starts with the same three tuple fields:

Field	Meaning	Stability
`decoded`	Finite decoded value when available; `NaN` payload for `⊥`	Stable
`bottom_mask`	Authoritative fail-closed mask for strict bottoms, including non-finite `P`/`Q` payloads	Stable
`gap_mask`	Samples in the training-inference gap `tau_infer <= \|Q\| < tau_train`	Stable

Keep using bottom_mask as the primary reject/safety signal. The provenance split does not weaken that rule.

How provenance relates to `bottom_mask` and `gap_mask`¶

The provenance signal refines bottom_mask. It does not create a third kind of strict failure, and it does not redefine the gap region.

Sample state	`bottom_mask`	`gap_mask`	Provenance
Finite and outside the gap	`False`	`False`	finite / absent
Finite but in the gap region	`False`	`True`	finite / absent
Bottom caused by non-finite/runtime-fault conditions	`True`	`False`	fault
Bottom caused by a finite strict semantic threshold	`True`	`False`	semantic
Bottom caused by both conditions	`True`	`False`	mixed

In other words:

bottom_mask and gap_mask stay disjoint.
Provenance only answers "what kind of bottom was this?"
fault_mask and semantic_bottom_mask may overlap on mixed bottoms.
gap_mask still means "finite decode, but numerically close to the training-time safety margin."

Accessing provenance¶

No opt-in is required for eager Python results:

from zeroproofml.inference import strict_inference

result = strict_inference(P, Q)
decoded, bottom_mask, gap_mask = result
fault_mask = result.fault_mask
semantic_bottom_mask = result.semantic_bottom_mask
bottom_provenance = result.bottom_provenance

That unpacking path stays stable. The provenance fields are attributes on the same result object.

Representation A: `split_masks`¶

The split representation provides two boolean masks:

fault_mask: bottoms attributed to non-finite inputs or equivalent not-in-the-carrier runtime faults.
semantic_bottom_mask: bottoms attributed to strict semantic thresholds, including finite denominators with |Q| < tau_infer.

Non-finite IEEE payloads in P, Q, or an evaluated validity factor are fault-like inputs. They route to fault_mask, not semantic_bottom_mask. Finite denominators in tau_infer <= |Q| < tau_train remain finite decodes and surface through gap_mask as a monitoring signal, not as faults. InferenceConfig.numerical_hazard_threshold is likewise monitor-only metadata for finite denominator hazards. The deprecated provenance_fault_threshold alias is retained for compatibility, but it is not bottom provenance and never classifies fault_mask. When a consumer computes such a finite-hazard mask, monitor it through numerical_hazard_rate separately from fault_rate and semantic_bottom_rate. Finite validity factors below their configured threshold route to semantic_bottom_mask.

The merged contract does not change:

bottom_mask == (fault_mask | semantic_bottom_mask)

Use this mode when downstream tooling already expects boolean masks and you want the most direct relationship to the stable bottom_mask.

Representation B: `bottom_provenance`¶

The enum representation provides one integer-coded tensor:

0 = finite
1 = fault
2 = semantic
3 = mixed

The merged contract is still derived from that field:

bottom_mask == (bottom_provenance != 0)

Use this mode when you need a single tensor for serialization, logging, or schema declarations.

Not structural validity provenance¶

This guide covers runtime strict-inference mask provenance. It does not promote FlattenedFRU.denominator_provenance or FlattenedFRU.strict_validity_sources, the structural validity provenance recorded by symbolic FRU flattening. That trace identifies which denominator subexpression contributed a validity factor before runtime evaluation; it remains experimental, has no defined promotion gate, and is orthogonal to the stable fault_mask / semantic_bottom_mask split. Do not treat the historical Q2 downstream-benefit, overhead, repeatability, and non-regression thresholds as inherited acceptance criteria for this structural trace; draft a new gate at that time if a consumer asks to promote it, and do not pre-commit thresholds now. If that promotion work starts, use FlattenedFRU.structural_validity_output_schema(...) as the stable output-name shape instead of inventing per-export names.

That experimental status applies to exposing and consuming the structural trace as provenance. In guarded strict FRU evaluation, the validity factors themselves are internal semantics: reduced payloads must evaluate every factor with the fail-closed predicate before accepting the decoded P/Q value.

Practical interpretation¶

bottom_mask=True always means reject or fall back according to the stable strict-inference policy.
gap_mask=True means "not bottom, but near the train/infer threshold gap"; it is useful for monitoring or conservative fallback policies.
Provenance is diagnostic detail layered on top of bottom_mask.

This is why helpers such as StrictInferenceMonitor, decode_strict_censored_3way(...), and route_to_analytic_solver(...) accept provenance fields only as optional inputs. When a non-finite scalar payload routes to fault_mask, decode_strict_censored_3way(...) does not recover orientation from the payload's IEEE sign; preserve orientation near singular boundaries with an independently computed weak_sign side channel, an angular/projective head, or an auxiliary direction head. Typed semantic labels can carry the same contract when the label source owns the orientation.

Export and bundle implications¶

Eager Python results expose stable provenance attributes. Schema-v2 ONNX bundle exports expose decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, and bottom_provenance in the canonical order declared by bundle metadata. TorchScript keeps the backward-compatible decoded, bottom_mask, and gap_mask export path.

Recommended consumer pattern¶

Prefer code that reads the stable tuple fields first and then uses provenance attributes for routing or monitoring:

decoded, bottom_mask, gap_mask = result

fault_mask = getattr(result, "fault_mask", None)
semantic_bottom_mask = getattr(result, "semantic_bottom_mask", None)
bottom_provenance = getattr(result, "bottom_provenance", None)

That keeps merged-mask consumers unchanged while allowing monitoring, calibration, or fallback experiments to use the richer signal when present.