feat: resolve documented known gaps — abs, named constants, Field↔float, From vectors (sq-dtmg9) — v0.11.0

[jeswr]

🤖 SPARQ agent (Claude Fable 5) — automated contribution on behalf of @jeswr. Bead: sq-dtmg9 (maintainer directive 2026-07-06: resolve the documented known gaps in this repo).

What

Resolves every gap documented in this repo's README Known gaps section and TESTING.md's absent from the new public API table, except directed-rounding arithmetic (deliberately deferred — see below). Version 0.10.0 -> 0.11.0.

Gap resolutions

Gap (as documented)	Resolution
abs (10 unported deprecated tests)	IEEE 754-2019 §5.5.1 quiet bit-level sign clear, all 4 widths. NaN payloads pass through unchanged (matches hardware fabs); decode-only cost.
Named constant constructors (16 unported tests)	zero/neg_zero/one/neg_one/infinity/neg_infinity/nan/signaling_nan as comptime-constant struct literals (no decode, no gates). signaling_nan() uses the deprecated library's bit patterns (0x7FA00000 / 0x7FF4000000000000) with an explicit doc note that this library implements no signaling semantics.
Field↔float conversion (14 unported tests)	Loud semantics replacing the deprecated silent ones (which truncated from_field mod 2^64 and mapped NaN/negatives to 0): from_field asserts value < 2^128 in-circuit (assert_max_bit_size::<128>) then reuses the verified From<u128> RNE path; to_field truncates toward zero via the to_u64 kernel, inheriting its NaN/inf/range rejections.
Dead ct.nr at repo root	Deleted — unused duplicate of src/sizing.nr and home of the repo's only two stale TODO comments (including a wrong exponent-size formula already fixed in sizing.nr).
README source-of-truth header stale	This repo is now the source of truth (the in-sparq zk/ieee754 copy was removed by sparq#1602); header rewritten.
TESTING.md overclaimed "generated conversion vectors (From<u8..u128, i8..i64>)"	They did not exist in the committed fixture. Now they do: the exact-rational generator emits integer→float conversion vectors for all 9 source types × 4 widths, plus from_field/to_field vectors. Honest note left in the mapping table.

Deferred (documented, not guessed)

• Directed-rounding arithmetic (rndu/rndd/rndz/rna for Add/Sub/Mul/Div; 37 deprecated tests) → sparq bead sq-xs0pa. This is a kernel-level feature needing a design decision, not an additive API: the rounding mode must be threaded through round_pack_normalized{,_u64} in both kernels (mode-dependent overflow behaviour), the API shape (comptime-generic mode methods vs runtime parameter) has gate-budget consequences on the RNE hot path, and stable Rust has no directed-rounding host oracle (needs rustc_apfloat-class dependency). No SPARQL/XPath consumer needs non-RNE arithmetic today.
• f128 differential-oracle rows — pre-existing documented deferral, still tracked as sq-3x7dl.14.2. f128 remains covered by the exact-rational generated vectors (now including abs/from_field/to_field).
• Gate-bench rows for the new ops → sparq bead sq-hkhg8 (no bb on the work box; CI runs tests only). The arithmetic kernels are untouched, so the committed gate baselines remain valid — the additions are decode-only (abs), comptime-constant (constants), or compositions of already-measured kernels (from_field ≈ From<u128>, to_field ≈ to_u64).

Test evidence (all on pinned nargo 1.0.0-beta.21)

Suite	Before	After
In-source nargo test	32	43 (incl. 8 new should_fail rejection tests)
Generated vectors (exact-rational reference)	121 fns / 1793 asserts	199 fns / 3038 vectors (+abs all widths w/ NaN-payload probes, +From conversions, +from_field/to_field)
Public-API surface	6 (+4 rejections)	9 (+4 rejections)
Differential oracle (Rust host reference)	24 fns / ~4500 asserts	31 fns / ~5300 asserts (+abs f16/f32/f64, +from_field f32/f64 vs hardware RNE casts, +to_field f32/f64)

• Differential drift guard re-generated and verified; inject-fault self-test still fails exactly one test (harness non-vacuous).
• Harness Rust unit tests 24/24 (new direct tests for every new oracle fn, per the coverage discipline); cargo clippy --all-targets clean.
• The new from_field/to_field/abs circuit paths are verified against two independent references: the exact-rational Python model (all 4 widths) and hardware IEEE 754 (f32/f64 via correctly-rounded Rust int→float casts).

Notes for review

• abs intentionally does not canonicalise NaNs — IEEE abs is a quiet bit-level operation; both references agree.
• from_field rejects >= 2^128 loudly rather than adopting the deprecated silent mod-2^64: the deprecated implementation was self-declared "not extensively tested, use with caution", and silent truncation contradicts this library's loud-failure discipline (same doctrine as to_u64/to_i64 XPath rejections).
• differential/target/ is now gitignored (previously only /target/ was).

Merging per the face-repo pattern once test-summary + required contexts are green; will tag v0.11.0 and follow up with the sparq zk/compose pin bump PR.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.