feat(pqc): add device-resident ML-KEM-512 SampleNTT

[midhatn]

Summary

Adds DR2a, a narrow device-resident ML-KEM-512 building block that computes one bounded matrix polynomial:

SampleNTT(SHAKE128(rho || j || i))

for j,i in 0..1.

This reuses the physically proven DR1 two-worker streaming topology while replacing the earlier fixed-stream partial-polynomial behavior with a complete-or-error terminal contract.

Device topology

• Two host ingress ObjectFIFOs: 32-byte rho and 16-byte descriptor
• One internal depth-two 180-byte SHAKE token ObjectFIFO
• One depth-two 528-byte terminal result ObjectFIFO
• Five SHAKE128 rate blocks per request: 840 bytes, or 280 FIPS 203 candidate iterations
• Exactly two host fills and one terminal drain
• No host or Python reference fallback
• LIMIT_EXCEEDED and BAD_DESCRIPTOR return fixed zero-payload terminal records

Physical Phoenix validation

Validated on Phoenix XDNA1 with IRON 1.4.1:

• Backend: dr2a-mlkem512-samplentt:silicon
• Physical corpus: TOTAL 13/13 PASS
• Exact comparisons: 13 requests x 256 lanes = 3,328
• Repeated execution: two complete corpora in one Python process, 26/26 requests passed
• Producer core (0,2): .text 6,192 B, .bss 272 B, 16 KiB stack reservation
• Consumer core (0,3): .text 2,976 B, .bss 524 B, 16 KiB stack reservation
• Generated xclbin: 18,520 B
• PDI UUID: dff7cf7e-0931-4fd5-b1e3-55f43b342e83

The placed MLIR records depth-two FIFO allocation, bank/address placement, two shim MM2S ingress routes, and one shim S2MM terminal route.

Host validation

• Combined DR0/DR1/DR2a suite: 78 tests passed, zero skips
• Dedicated DR2a suite: 22 tests passed
• Compiled production C++ harness checks the full five-block stream and all 256 coefficients against an independent hashlib.shake_128 / FIPS 203 parser
• Repeated-request reset, token corruption, malformed ABI, full drain, and bounded failure paths covered
• Ruff passed
• git diff --check passed
• run_all_silicon_tests.py is unchanged

Claim boundary

This PR validates one bounded ML-KEM-512 SampleNTT polynomial per invocation. It does not claim complete K-PKE KeyGen, complete ML-KEM residency or conformance, performance, constant-time behavior, secure zeroization, side-channel resistance, CMVP validation, or certification.

The physical corpus did not inject malformed descriptors or corrupted internal tokens. Those fail-closed paths remain compiled host-harness and source-contract evidence.

Specification references:

• FIPS 203: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
• FIPS 202: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf

[midhatn]

Withdrawing this narrow DR2a sub-milestone for now. DR2 will be pushed as one complete milestone immediately before DR3 begins. The validated work remains local while DR2 integration continues.

[Copilot]

Pull request overview

Adds a new narrow “DR2a” device-resident ML-KEM-512 building block that deterministically computes one bounded SampleNTT(SHAKE128(rho || j || i)) polynomial (for j,i ∈ {0,1}) with a terminal-only, complete-or-error ABI, plus host-side validation, an independent reference oracle, and silicon/host test gates. This fits into the PQC device-resident roadmap as a proven streaming topology primitive intended to be composed later into broader ML-KEM graphs (explicitly not full KeyGen).

Changes:

• Introduces a fixed DR2a ABI (descriptor + terminal result) and a two-worker IRON graph that performs exactly two ingress fills and one terminal drain, with no host/reference fallback.
• Adds production C++ kernels for the SHAKE128 streaming producer and SampleNTT consumer (fixed 5-block schedule; fail-closed terminal contract).
• Adds an independent hashlib.shake_128 / FIPS-203 candidate parser oracle and comprehensive off-hardware + native-only silicon gate tests, plus design/validation documentation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_pqc_dr2a_contract.py	Adds static contract tests asserting DR2a topology, ABI constants, and documentation invariants.
tests/pqc_device_resident/test_dr2a_mlkem512_samplentt_silicon.py	Adds a native-only silicon gate that fails closed when hardware/runtime is unavailable.
tests/pqc_device_resident/test_dr2_mlkem512_samplentt.py	Adds host/off-hardware tests including a compiled C++ harness that checks full 5-block streams and terminal outputs.
tests/pqc_device_resident/dr2a_reference.py	Adds an independent SHAKE128 + FIPS-203 candidate decoding oracle used by tests.
phoenix_sdr_dsp/pqc/kernels/dr2_mlkem512_shake128_service.cc	Adds the device-side SHAKE128 producer emitting 5 fixed rate blocks per request.
phoenix_sdr_dsp/pqc/kernels/dr2_mlkem512_samplentt.cc	Adds the device-side SampleNTT consumer producing a terminal-only complete-or-error result.
phoenix_sdr_dsp/pqc/dr2_mlkem512_samplentt_graph.py	Adds the DR2a IRON graph and native dispatch wrapper with strict host validation and terminal parsing.
phoenix_sdr_dsp/pqc/dr2_mlkem512_samplentt_abi.py	Defines the fixed ABI and strict terminal parsing (including fail-closed error behavior).
docs/PQC_DR2A_SILICON_VALIDATION_PENDING.md	Records the narrow physical validation evidence and reproduction steps.
docs/PQC_DR2A_DESIGN.md	Documents DR2a scope, topology, fixed ABI, and claim boundaries.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.