Migrating from v0.6.x to v0.7

v0.7.0a1 is a breaking semantic alpha. The central change is that a single numeric payload and bottom_mask no longer serve as the source of truth for semantic bottom, floating faults, observation state, representation validity, ambiguity, or operational rejection.

Required code changes

  1. Replace zeroproof.* imports with zeroproofml.*. Compatibility imports warn, remain available through 0.8.x, and may be removed in 1.0.0. If an environment may contain another zeroproof distribution, call zeroproofml.require_compatibility_namespace() before relying on the old name; it raises when import precedence selects a foreign package.
  2. Use zeroproofml.scm.sign4 for pure real SCM sign. Keep hysteretic routing in projective.orientation and complex unit phase in projective.phase; neither changes the algebraic sign result.
  3. At strict boundaries, call typed_strict_inference or typed_strict_inference_tensor and inspect named axes/masks. The legacy projection is deliberately lossy and emits a deprecation warning.
  4. Treat an observed floating 0.0 as MachineZeroEvent.ZERO, not proof of an exact denominator zero. Only an exact expression or certificate may produce ExactZeroEvidence.PROVEN_ZERO.
  5. Normalize (P,Q) with normalize_projective. The canonical gauge uses overflow-safe max scaling, unit L2 norm, and deterministic Q-positive orientation. (0,0) is REPRESENTATION_FAULT. For a vector numerator and one shared denominator, declare the tuple axis with coordinate_axis=-1; omitted axes retain elementwise scalar-pair behavior. Put the same axis in StrictDecodePolicy, where it is hashed into bundle identity, and pass it to soft_coverage_loss. Supported shared-denominator models declare their axis for TrainingConfig(projective_coordinate_axis="model"). Custom schema-v3 tuple exporters must additionally declare projective_denominator_contract="shared_denominator_by_construction_v1"; an axis declaration alone is refused because it cannot become a runtime ONNX equality guard. The exported graph additionally maps any runtime denominator disagreement to a typed representation fault and rejection.
  6. Recalibrate every v0.6 raw-|Q| threshold. Old thresholds cannot be transferred to the normalized denominator score. Pass numerator=P to the retained margin/separation helpers on maintained 0.7 paths, and feed the adaptive sampler canonical scores in [0,1].
  7. Include resolved_semantic_identity().to_dict() in new checkpoints and artifacts. Resume rejects changes in profile, gauge, decoder, zero, status, or refinement identity.
  8. Pass SemanticTargetLabel enum members to lift_semantic_targets; v0.7 no longer accepts raw string compatibility labels.
  9. Keep typed projective coordinates real. Complex tensors now fail before float64 promotion instead of silently discarding their imaginary component.
  10. Treat SemanticResult.finite(...) as asserted input construction. Floating computation paths use computed constructors and carry ResultOrigin plus hash-bound ExecutionEvidence. Do not copy an operand's bare execution label onto a new result.
  11. Freeze a working ResultTensor with freeze_evidence() before durable serialization, monitoring, reporting, or external handoff.
  12. Pass vector masks only by keyword. Positional mask forms have been removed from both canonical and compatibility namespaces and now raise TypeError.

Before and after

# v0.6 compatibility result: information is merged
decoded, masked = legacy_decode(...)

# v0.7 typed result: axes remain independent
from zeroproofml.inference import typed_strict_inference

result = typed_strict_inference(3.0, 2.0)
assert result.payload == 1.5
assert result.operational.value == "accept"

A finite result may be censored or rejected while retaining its payload and algebraic sign. A numerical fault has NO_CORE; it never becomes semantic bottom. Exact bottom has a present core category but no fake numeric payload.

Bundle and checkpoint compatibility

  • Bundle schemas v1 and v2 are legacy ONNX contracts. Their explicit reader is retained, but they are never assigned v0.7 semantic identity.
  • Bundle schema v3 requires all semantic policy hashes and a fixed-width output for each result axis. export_bundle(...) emits this typed ABI by default, embeds the complete decoder policy under its identity hash, records the onnxruntime-cpu refinement profile, and hashes the ordered CPUExecutionProvider options contract. The Python loader reconstructs ResultTensor and refuses provider/order/options mismatch or unrecorded session options. Other providers and runtimes remain unqualified.
  • Scalar result schema v2 serializes origin plus complete execution evidence. Strict from_dict rejects schema v1; use from_legacy_dict explicitly, which produces DESERIALIZED_LEGACY without synthesized qualification. Tensor evidence uses canonical ResultTensorSnapshot serialization.
  • Checkpoint schema v4 carries semantic identity, strict resume/component identity, named profile, and required RNG/sampler state. Legacy checkpoints are labelled legacy-unqualified; they cannot silently qualify as v0.7 claim-bearing artifacts.
  • Untrusted checkpoint entry points require PyTorch 2.10.0 or newer and fail closed below that floor. The warned trusted loader is only for artifacts whose producer and custody are trusted.
  • validate_bundle_descriptor(...) is strict by default. Legacy inspection requires the explicitly named legacy reader/flag and returns unverified status rather than silently accepting missing integrity metadata.

Downstream migration checklist

  • [ ] canonical imports use zeroproofml.*;
  • [ ] bottom, fault, invalid observation, rejection, and representation fault have separate handling;
  • [ ] exact-zero evidence is sourced from an exact expression/certificate;
  • [ ] projective thresholds are recalibrated under the v1 canonical gauge;
  • [ ] resume and artifact loaders verify semantic hashes;
  • [ ] legacy bundle support is explicitly labelled;
  • [ ] deployment claims remain disabled until the required runtime is qualified.
  • [ ] working result tensors are frozen before durable evidence boundaries;
  • [ ] checkpoint callers select an explicit named resume profile and meet its preconditions;
  • [ ] old result/checkpoint records use explicit unqualified compatibility readers.