Skip to content

fix(core): explicit saturating narrowing, const decoders, complete API docs, and a rustdoc gate - #1

Merged
mertefesensoy merged 5 commits into
Pactolus-Microelectronics:mainfrom
danalec:fix/narrowing-and-doc-gates
Nov 14, 2026
Merged

mertefesensoy merged 5 commits into
Pactolus-Microelectronics:mainfrom
danalec:fix/narrowing-and-doc-gates

Conversation

@danalec

@danalec danalec commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A behaviour-preserving quality pass over the shipped surface. The public API
gains const on six accessors, which is additive and therefore a semver
commitment: removing it later would be breaking. No decoded output changes for
real SPD bytes — every golden snapshot passes byte for byte. The only behaviour
change is for hand-built, out-of-range values, which now saturate or round
exactly instead of wrapping.

This is opened from a fork. The branch carries the quality pass and the
corrections requested in review, on top of main.

The bug class worth reviewing first

The core is forbid(unsafe_code) and never panics, so its interesting failure
mode is not a crash but a wrong value. Every place where a wider integer was
narrowed with an unchecked as was hardened:

  • The two CAS-latency derivations — the linter's supported-set check (spdr/src/lint.rs)
    and the vendor-profile rated CL (spdr/src/vendor.rs) — narrowed a u32
    quotient to u16. Safe for decoded bytes, since both fields are 16-bit, but
    fragile and not evident from the code. They now narrow explicitly and
    saturate, so a hand-built out-of-range value cannot wrap. Each has a
    regression test, including the case that wrapped to a silent CL5 — a
    plausible-looking latency that would have been reported as real.
  • The rated-CL derivation computes its round-to-nearest in u64, so it stays
    exact across the whole u32 input range; only the final narrowing saturates.
  • The supported-CAS mask arithmetic (spdr/src/timing.rs) now computes its bit
    index in a single integer domain, with a compile-time assertion tying the bit
    count to the byte count it derives from.
  • The reference-raw-card Display (spdr/src/module.rs) no longer casts the
    alphabet length or array indices.

Gate gaps this closes

cargo doc was not run anywhere, so doc breakage was invisible. Bit-range
notation in field docs (bits [7:5]) parsed as intra-doc links and produced 21
unresolved-link warnings on the base, plus one public doc link to a private
item — 22 warnings in total. The rendered documentation was correct: the
bit-range text appeared as plain text, not a link. The defect was the warnings,
so CI now builds rustdoc with -D warnings and fails on them.

A curated set of clippy::pedantic lints is deny-ed at the workspace level,
covering exactly the classes this pass found: silent narrowing, missing
# Errors sections, unbackticked identifiers, &Option<T> arguments, and
needless pass-by-value. It is curated rather than blanket so that a future
upstream lint cannot break CI on a toolchain bump. ref_option is resolved by
clippy on the MSRV toolchain (it is implied by clippy::pedantic), so MSRV
builds are unaffected — measured, not assumed. bool_to_int_with_if was dropped
from the set: it is a style lint whose only effect here was to force a less
readable exit code.

Also included

  • Every pure decoder and accessor that can be is now const fn (31 functions:
    27 in spdr, 4 in spdr-cli), which is the point of an embeddable no_std
    crate. No public decode_* entry point is const, so a downstream user
    still cannot decode an SPD image at compile time.
  • # Errors sections on every public Result-returning function; identifiers
    in prose wrapped in backticks; bit-range notation as code spans ([7:5]),
    which rustdoc does not link and which read cleanly.
  • A correction to this repo's own documentation. The fuzz harness was
    documented as unable to link on Windows MSVC. That is wrong: cargo fuzz build decode_all does compile and link, and the binary then fails to load on its
    clang_rt.asan_dynamic-x86_64.dll import (STATUS_DLL_NOT_FOUND;
    STATUS_ENTRYPOINT_NOT_FOUND with LLVM's runtime on PATH; LNK1120 with
    CC=clang CXX=clang++). The measured failure mode is now recorded in
    spdr/fuzz/Cargo.toml and the phase-6 report, and the attempt is logged in
    the deep-run ledger instead of sitting as a silently blank row.
  • spdr/fuzz/Cargo.lock is committed, so the harness resolves reproducibly
    like the parent workspace already does.
  • Every number in this pass is traced in docs/numerical-claims.md, and the
    dated note is docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md.

On the "fuzzed" claim

The README wording is deliberately unchanged: it still says property-tested,
not fuzzed
. The deep run is still owed on a Linux or WSL host; on Windows the
harness never reached a single execution. The on-box substitute noted in the
ledger is PROPTEST_CASES=100000 cargo test --release --test robustness, which
is property-testing, not fuzzing.

How this was checked

cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings,
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib,
cargo build -p spdr (the existing no_std guard), and cargo test --workspace are all clean on Windows and on Linux, full suite passing. With
blanket -W clippy::pedantic there is one warning, bool_to_int_with_if on
the restored if ok { 0 } else { 1 } exit code: the lint is not in the deny
set and the CI gate does not enable blanket pedantic, so the gate stays
clean. The two saturation tests were confirmed to fail against the previous
as cast before being kept; the bit-domain test is a characterization test,
since the base arithmetic was already correct.

Workflow runs from this fork require a maintainer's approval because the change
set touches .github/workflows/ci.yml; approving one runs the same steps on
ubuntu-latest.

The decoder is `forbid(unsafe_code)` and never panics, so the interesting
failure mode is not a crash but a wrong value. This hardens every place where
a wider integer was narrowed with an unchecked `as`.

- The two CAS-latency derivations (the linter's supported-set check and the
  vendor-profile rated CL) narrowed a `u32` quotient to `u16`. Safe for decoded
  bytes, but fragile and non-obvious; they now narrow explicitly and saturate,
  so a hand-built out-of-range value cannot wrap into a plausible-looking
  latency. Regression tests cover both, including the case that wrapped to a
  silent `CL5`.
- The supported-CAS mask arithmetic now computes its bit index in one integer
  domain, with a compile-time check tying the bit count to the byte count it
  derives from.
- The reference-raw-card `Display` no longer casts the alphabet length or
  array indices.

Also, since the crate is `no_std` and meant to be embeddable, every pure
decoder and accessor it can is now `const fn`, and two `pub(crate)` markers that
were redundant inside private modules became plain `pub` (same effective
visibility).

Documentation is completed in the same pass: an `# Errors` section on every
public `Result`-returning function, identifiers in prose wrapped in backticks,
and bit-range notation escaped so it no longer parses as an intra-doc link.

No decoded output changes: the golden snapshots pass byte for byte.
…z blocker

The gate gains a rustdoc step, because doc breakage was invisible to it:
bit-range notation in field docs (`bits [7:5]`) parsed as intra-doc links, so
every rendered field doc was a broken link, and one public doc pointed at a
private item. Both are now fixed and cannot regress silently.

A curated set of `clippy::pedantic` lints moves to `deny` at the workspace
level, covering exactly the classes this pass found: silent narrowing, missing
`# Errors`, unbackticked identifiers, `&Option<T>` arguments, and needless
pass-by-value. It stays curated rather than blanket so a future upstream lint
cannot break CI on a toolchain bump. `ref_option` postdates the MSRV; plain
`rustc` ignores `clippy::*` names entirely, so MSRV builds are unaffected.

The fuzz harness documentation claimed the fuzz crate "cannot link" on Windows
MSVC. That was wrong, and now says what is actually true: it compiles and links,
and the resulting binary fails to load on its
`clang_rt.asan_dynamic-x86_64.dll` import (exit `STATUS_DLL_NOT_FOUND`, then
`STATUS_ENTRYPOINT_NOT_FOUND` with LLVM's runtime on `PATH`, and LNK1120 with
`CC=clang CXX=clang++`). The attempt is recorded in the phase ledger rather than
left as a silently blank row, and `spdr/fuzz/Cargo.lock` is committed so the
harness resolves reproducibly.

The README still says "property-tested, not fuzzed", which remains the honest
state: the deep run is still owed on a Linux or WSL host.

@mertefesensoy mertefesensoy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, @danalec. The code side is solid: the saturation guards are correct, the rustdoc gate closes a real gap, and the README's "property-tested, not fuzzed" line is left honest. What needs another pass is the prose. In this repo the accuracy of every public claim is the bar, and several statements in the CHANGELOG and the lint-table comment don't hold up against the diff or against a run. No blockers; one major, four minor, five nits.

What I verified

On the PR head (663a30f), Windows, stable 1.96:

  • cargo build -p spdr (no_std guard), cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings: clean.
  • Same clippy with -W clippy::pedantic: zero warnings.
  • RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib: clean.
  • cargo test --workspace: 110 passed, 0 failed.
  • MSRV (rustc 1.85.1): cargo build -p spdr, cargo clippy --workspace --all-targets -- -D warnings, and cargo test --workspace (110 passed) all clean. The 31 new const fns are fine on the MSRV.

On the base (6b0d2d5), for comparison:

  • cargo doc emits 22 warnings: 21 unresolved link to 7:5-style, plus the private run_lint link. So the new gate is needed.
  • I copied the three new tests into the base tree and ran them there. lint::cas_latency_saturates_instead_of_wrapping and vendor::rated_cas_latency_saturates_instead_of_wrapping fail (wrapped CL5). The u32::MAX rounding case panics on the add overflow. timing::cas_latency_bit_domain_covers_exactly_the_mask passes.

Major

M1 · The CHANGELOG and the lint-table comment make claims the diff does not support. The CHANGELOG ships with the next crates.io release, so each of these needs correcting before merge:

  1. CHANGELOG.md:18 · "29 pure decoders and accessors marked const fn". The diff adds const to 31 functions: 27 in spdr and 4 in spdr-cli. Neither count is 29.
  2. CHANGELOG.md:18-19 · "so a constant SPD byte can be decoded at compile time". Every field decoder that became const is crate-internal. None of the public decode_* entry points is const. A downstream user still can't decode anything at compile time.
  3. CHANGELOG.md:9 and the PR description · "No public API change". const is now on five public spdr items (Finding::severity, Finding::code, SpdImage::is_empty, CasLatencies::contains, Timings::base_data_rate_mt_s) and on spdr_cli::DecodeResults::all_decoded. The change is additive and I'm fine with it, but removing const later is breaking. This is a semver commitment, so list it as an API addition, not as "no change".
  4. CHANGELOG.md:15 · "each was confirmed to fail against the previous as cast". The two saturation tests do. The bit-domain test does not, and can't: the base arithmetic was already correct. It is a characterization test, which is still worth having. Say that.
  5. CHANGELOG.md:33 · "every rendered field doc was a broken link". Not on the base. Rustdoc warned 21 times about bit ranges, but the rendered HTML shows bits [7:5] as plain text with no link. The real defect was the warnings, which the new -D warnings gate would trip on. The rendered output was fine.
  6. Cargo.toml:25-27 · "ref_option postdates the 1.85 MSRV ... only clippy runs on pre-1.87 toolchains warn". Clippy's own changelog moves ref_option into pedantic in Rust 1.83 (released 2024-11-28), before the MSRV. It also checks out empirically: clippy 1.85 runs this workspace under -D warnings with no unknown_lints warning. The PR description repeats this as "verified, not assumed". Please correct or drop the sentence in both places.
  7. Cargo.toml:21 · "each of these caught a real issue". bool_to_int_with_if is a style lint. The only change it drove is the exit-code rewrite (see N2). Either drop it from the list or soften the comment.

Minor

m1 · Documentation trail.

  • docs/numerical-claims.md says every number in the docs is logged there with its source. This PR adds several numbers and logs none of them: the 29 (31) count, "3 passed in 1.17 s", PROPTEST_CASES=100000, -max_total_time=45, and the two exit codes.
  • Every prior change has its own docs/implementations/YYYY-MM-DD-<slug>.md. This one needs one too: a CI gate, a workspace lint policy, and a numeric-behaviour change are each meaningful. Most of the content is already in the PR description.

m2 · Phase 6 report edits (docs/implementations/2026-06-05-phase-6-robustness.md).

  • Lines 129-130 repeat a sentence: "proptest is pure Rust and runs anywhere cargo test does." appears twice.
  • Line 176 says "see the measured details in Design Decisions". Design Decisions (line 132) only says "measured above", and the details are actually in Problem / Motivation (line 28).
  • The deep-run ledger is the right place for the attempted run, and logging it beats leaving the row blank. The row should say who ran it and on which host, though, because "this machine" in that report means the maintainer's box.
  • The dated June rationale is rewritten in place. A dated addendum would preserve what the report said when it was written.

m3 · pub(crate) to pub (spdr/src/identity.rs:400, spdr/src/timing.rs:291). Effective visibility is unchanged today. Before, though, the compiler enforced the boundary; now a comment does. A future pub use identity::* or a module made pub would silently export these helpers. None of the denied lints requires the change, so please revert to pub(crate). const can stay.

m4 · Em dashes at CHANGELOG.md:19 and spdr/src/timing.rs:220. The repo uses the middle dot (·) or plain punctuation as its separator and has no em or en dashes anywhere in the shipped tree. To be fair, that convention isn't written down anywhere in the repo yet, so you had no way to know.

Nits

  • N1 spdr/src/vendor.rs:507 · saturating_add keeps the add from overflowing, but near u32::MAX it rounds down. For example, taa = u32::MAX with tck = 2^31 gives 1 instead of 2. Widening to u64 for the add and divide makes the rounding exact, and only the final narrowing needs to saturate. This is unreachable from decoded bytes, so it's a nit.
  • N2 spdr-cli/src/lib.rs:162 · i32::from(!results.all_decoded()) reads worse than if results.all_decoded() { 0 } else { 1 } for an exit code. Consider dropping bool_to_int_with_if from the deny list, or an #[allow] at this site.
  • N3 .github/workflows/ci.yml:31 · missing # Errors sections are caught by the Clippy step (missing_errors_doc), not by rustdoc. The comment conflates the two.
  • N4 CHANGELOG.md:15 · "the silent-narrowing fix above". The fix is listed below, under Fixed.
  • N5 The \[7:5\] escapes are correct, but they make the source harder to read in a crate whose source is meant to be the open reference. A code span (`[7:5]`) or "bits 7:5" also silences rustdoc and reads cleanly.

No need to split the PR. It's reviewable as one, and the fixes above are all prose apart from m3 and N1.

… claims

The review asked for prose corrections, three code changes, and a
documentation trail. All of it is in this commit.

Code:

- `vendor::rated_cas_latency` computes the round-to-nearest in `u64`, so the
  rounding stays exact across the whole `u32` input range instead of
  saturating the add and rounding down. Only the final narrowing to `u16`
  saturates. New test: `rated_cas_latency_rounds_in_u64`.
- `identity::decode_module_type` and `timing::data_rate_mt_s` go back to
  `pub(crate)`. The pass had widened them to `pub`, which left the boundary to
  a comment instead of the compiler. `const` is kept.
- The CLI exit code is `if results.all_decoded() { 0 } else { 1 }` again.
  `bool_to_int_with_if` is dropped from the workspace deny list: it is a style
  lint that forbids the branch form and asks for `i32::from(!ok)`, so its only
  effect here was to force the less readable expression.

Claims corrected, each against a measurement recorded in
`docs/numerical-claims.md`:

- 31 functions became `const fn` (27 in `spdr`, 4 in `spdr-cli`), and every
  one of them is crate-internal or an accessor: no public `decode_*` entry
  point is `const`.
- Six public items gained `const`, so the change is additive rather than "no
  public API change".
- The two saturation tests were confirmed to fail against the previous `as`
  cast; the bit-domain test is a characterization test, since the base
  arithmetic was already correct.
- The rendered documentation was never broken: on the base `6b0d2d5` the
  bit-range text is plain text and no occurrence is wrapped in an `<a>`
  element. The defect was the 22 rustdoc warnings, which the new `-D warnings`
  gate turns into a build failure.
- `ref_option` is not newer than the MSRV: clippy 1.85.1 reports it as implied
  by `clippy::pedantic`.

Trails:

- `docs/numerical-claims.md` records every number above with its source.
- `docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md` is the
  dated note for this change.
- The Phase 6 report keeps its dated June rationale and gains a dated
  addendum for the measured Windows fuzz failure mode, instead of the
  rationale being rewritten in place.

No decoded output changes. `cargo fmt --check`, `cargo clippy --workspace
--all-targets -- -D warnings`, `RUSTDOCFLAGS="-D warnings" cargo doc
--workspace --no-deps --lib`, `cargo build -p spdr` and `cargo test
--workspace` are all clean.
@danalec

danalec commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Every point is addressed in fd92f40.

Code (3 changes)

  • m3 - identity::decode_module_type and timing::data_rate_mt_s are back to pub(crate); const is kept. Agreed that a comment is not a boundary.
  • N1 - vendor::rated_cas_latency does the add and the divide in u64, so the round-to-nearest stays exact across the whole u32 range and only the final narrowing saturates. New test rated_cas_latency_rounds_in_u64 pins your case: u32::MAX over 2^31 is 2, where the saturating u32 add gave 1.
  • N2 - the exit code is if results.all_decoded() { 0 } else { 1 } again, and bool_to_int_with_if is dropped from the workspace deny list rather than allowed at that site. Measured: the lint fires on the branch form and asks for i32::from(!ok); it does not fire on i32::from(!flag). So its only effect here was to force the less readable expression, and dropping it also answers M1.7.

M1 - the seven claims, corrected

  1. 31, not 29 (27 in spdr, 4 in spdr-cli); the per-file breakdown is in docs/numerical-claims.md.
  2. "a constant SPD byte can be decoded at compile time" removed: no public decode_* entry point is const, so a downstream user still cannot decode at compile time.
  3. "No public API change" replaced by an explicit additive API note listing the six public items that gained const.
  4. "each was confirmed to fail" now reads: the two saturation tests were confirmed to fail against the previous as cast, and the bit-domain test is a characterization test, since the base arithmetic was already correct.
  5. "every rendered field doc was a broken link" corrected. Measured on the base 6b0d2d5: the rendered bits [7:5] text is plain text, and no occurrence is wrapped in an <a> element. The defect was the 22 rustdoc warnings, which the -D warnings gate now turns into a build failure.
  6. The ref_option MSRV sentence is gone. Measured: clippy 1.85.1 reports ref-option as implied by pedantic, and an invented lint name on the same toolchain gives error[E0602]: unknown lint, so the name is resolved rather than ignored.
  7. bool_to_int_with_if is dropped from the list and from the deny set, per the point above.

Minor and nits

  • m1 - docs/numerical-claims.md gains a section for this pass: the 31 / 27 / 4 counts, the six public const items, the 22 rustdoc warnings, the clippy measurements, PROPTEST_CASES=100000, the "3 passed in 1.17 s" run, -max_total_time=45, the exit codes, and the round-to-nearest boundary, each with its source. New dated note: docs/implementations/2026-10-25-narrowing-const-and-doc-gates.md.
  • m2 - the duplicated proptest sentence is gone; the "see the measured details in Design Decisions" pointer now resolves to the addendum; the ledger row names the host and who ran it; and the June rationale is preserved as written, with a dated Addendum 2026-10-16 section carrying the measured correction.
  • m4 - the two em dashes are gone.
  • N3 - the CI comment now separates rustdoc (broken intra-doc links) from clippy (missing_errors_doc).
  • N4 - "the silent-narrowing fix above" now reads "below".
  • N5 - the 40 escaped bit ranges are code spans (`[7:5]`) now, which rustdoc does not link and which read cleanly. The rendered text is unchanged.

Checks

cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib, cargo build -p spdr and cargo test --workspace are all clean locally. The CI run for this head is held pending approval, because the commit touches .github/workflows/ci.yml; approving it runs the same steps on ubuntu-latest.

The dated implementation note listed `bool_to_int_with_if` among the denied
workspace lints even though `Cargo.toml` dropped it in the same pass, and its
verification section kept the "zero warnings" result from the pre-review head
instead of re-running after the exit code returned to the branch form. Both
claims are now corrected against measurements recorded in
`docs/numerical-claims.md`.

`CHANGELOG.md` no longer claims `cargo doc` warned on every bit-range field;
it states the measured count, which is traced in the same file.

The PR description is updated separately to match the corrected claims.
@danalec

danalec commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Head is now c949eb0 — documentation-only, no code changes. An independent re-check of the fd92f40 review fixes found two claims in the new dated note that did not hold up, so they are corrected here:

  • The note listed bool_to_int_with_if among the denied workspace lints, although Cargo.toml dropped it in the same pass — and the note itself said so two paragraphs later.
  • Its verification section carried over "zero warnings" for -W clippy::pedantic from the pre-review head. Re-run on the final head, blanket pedantic emits one warning, bool_to_int_with_if on the restored if ok { 0 } else { 1 } exit code; on 663a30f it emitted none, because the exit code was i32::from(!ok). The CI gate is unaffected: the lint is not denied and the gate does not enable blanket pedantic.

CHANGELOG.md no longer says cargo doc warned on every bit-range field — measured on the base, 21 unresolved-link warnings plus one private-item link. The PR description is updated to match, and every corrected number is traced in docs/numerical-claims.md.

Re-verified on Windows and Linux: cargo fmt --check, cargo build -p spdr, cargo clippy --workspace --all-targets -- -D warnings, RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --lib, cargo test --workspace — all clean, full suite passing.

A maintainer still needs to approve the CI run for this head (it is action_required, as before) and re-review or dismiss the earlier CHANGES_REQUESTED. Neither is possible from this account: the approve endpoint answers 403 Must have admin rights to Repository, and a review re-request answers danalec does not have the correct permissions. Both are therefore on the OMI side.

@mertefesensoy mertefesensoy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. Every point from my review is answered in fd92f40 and c949eb0, and CI passed at c949eb07 (run).

  • The CHANGELOG now matches the diff: 31 const fn (CHANGELOG.md:25), the six public const items listed as an API addition (:16-18), and the bit-domain test described as a characterization test (:23).
  • rated_cas_latency rounds in u64 (spdr/src/vendor.rs:509-510, test at :591), and both helpers are back to pub(crate) (spdr/src/identity.rs:400, spdr/src/timing.rs:290).
  • I pushed one commit on top that turns the two em dashes left in docs/numerical-claims.md (lines 239 and 240) into commas, so the docs keep the repo's no-dash convention.

Thanks for the careful follow-up, and for tracing every new number in docs/numerical-claims.md.

AI-assisted with Claude Code.

@mertefesensoy
mertefesensoy merged commit 162790d into Pactolus-Microelectronics:main Nov 14, 2026
1 check passed
@mertefesensoy

Copy link
Copy Markdown
Member

Your patch is live in 1.1.2 @danalec. Thank you for your contribution 😋

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants