fix(ntt): cross-validate against PQClean reference, add citation provenance#86
Open
erfanjazebnikoo wants to merge 1 commit into
Open
fix(ntt): cross-validate against PQClean reference, add citation provenance#86erfanjazebnikoo wants to merge 1 commit into
erfanjazebnikoo wants to merge 1 commit into
Conversation
…enance Closes a self-consistency-only gap: the NTT known-answer tests previously checked the fast NTT against a naive reference multiplication written for this project, not an independent ground truth. numx_ntt_forward and numx_ntt_polymul are now additionally cross-validated bit-for-bit against PQClean's ml-kem-512 (FIPS 203) reference implementation. Also adds inline scientific-source citations to every public NTT function's docstring and to each formula section in docs/algorithms/ntt.md, and tightens CONTRIBUTING.md's L1 test-level definition and citation conventions so this is a repeatable practice, not a one-off.
This was referenced Jul 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes a real gap flagged by outside review: the NTT module's known-answer
tests validated the fast NTT against a naive reference multiplication
written for this project, not an independent ground truth. A shared
systematic error (wrong root of unity, wrong modulus constant) in both the
fast and "reference" path would have passed every test.
numx_ntt_forwardandnumx_ntt_polymulare now additionallycross-validated bit-for-bit against PQClean's
ml-kem-512(FIPS 203,formerly CRYSTALS-Kyber-512) reference implementation. See
validation/reference/ntt/README.mdfor the pinned commit, theMontgomery-domain reasoning, and regeneration steps. The generator is
validation tooling only; PQClean is never a build or runtime dependency.
include/numx/ntt.h(andpriv_barrettinsrc/ntt.c) now cites its scientific source inline in the docstring, notonly in the docs page.
docs/algorithms/ntt.md's formula sections now carry inline[n]citation markers next to each formula; added the missing Cooley & Tukey
1965 citation (the Forward NTT section was titled "Cooley-Tukey" but
never cited them).
CONTRIBUTING.md: tightened the L1 test-level definition (crypto/security-critical modules need an external, independently-citable
reference, not an internally-written one) and added a "Citing sources"
convention covering docstring citations and the
validation/reference/<module>/regression-script pattern for futuremodules.
Test plan
cmake --build build --target numx_testsclean, zero warnings(
-Wall -Wextra -Wpedantic -Werror)ctestpasses: 339/339 tests, 0 failurestest_ntt_forward_vs_pqclean_referenceandtest_ntt_polymul_vs_pqclean_referenceconfirmed exercising thefixture, not skipped