ADR-0008 — RR dataset non-finite JSON encoding¶

Status: proposed

Date: 2026-08-25

Owners: ZeroProofML maintainers

Supersedes / superseded by: none

Context¶

The maintained RR inverse-kinematics dataset generator can produce positive infinity for the condition number at exact singularities and uses positive infinity as the terminal determinant-bucket edge. Python's default JSON encoder writes these values as bare Infinity tokens, which are outside the JSON standard and are rejected by the reference deployment's strict artifact loader.

Decision¶

RR dataset JSON encodes positive and negative mathematical infinity as the strings "inf" and "-inf". It rejects NaN instead of silently persisting an ambiguous diagnostic value. The producer uses the repository's strict JSON writer so that no bare non-standard constants can escape. The dataset object loader decodes the sentinel strings back to floating-point infinities for compatibility with in-memory numerical consumers.

Consequences¶

New RR dataset files are standards-compliant JSON and remain lossless for the condition-number and bucket-boundary meanings. Consumers that inspect raw JSON must accept the documented string sentinels for non-finite values. Existing Python consumers already parse the terminal bucket sentinel, and the object loader continues to return floats.

Alternatives considered¶

• Relaxing the deployment loader would weaken the strict artifact boundary.
• Replacing infinity with a large finite number would misstate the mathematics.
• Encoding infinity as null would lose the distinction between an unbounded value and a missing value.

Verification and rollout¶

A regression test writes a dataset containing an exact infinite condition number and terminal bucket edge, parses it with the strict JSON loader, and checks that the object loader restores both infinities. The reference robotics smoke command provides end-to-end rollout coverage.