feat(ntt-core): production-interface guards — mod-q load, btn sync, timing gate

- ntt_core.v: host words are fully reduced on load (h_din is 14-bit
  < 2q, so one conditional subtract closes the < q operating envelope
  the verified datapath is proven for — an out-of-range host value can
  no longer propagate unreduced garbage).  tb_ntt_core.v's last
  round-trip vector now feeds RAW 14-bit words (>= q) and checks the
  round-trip lands on x mod q; the Python NTT-golden comparison covers
  the same vector end-to-end.
- basys3_ntt_selftest.v: 2-FF synchronizer on the async button (was
  raw pin -> FSM next-state logic), previous verdict LEDs cleared on
  re-run, self-test duration comment corrected to ~3 ms (simulated
  completion: 3.03 ms).
- bit.sh: nextpnr exit code no longer masked (grep||true dropped); adds
  a timing gate — every reported clock must close >= 50 MHz (the /2
  core clock) and any 'FAIL at' constraint aborts.  The first gate
  version parsed only single-space clock names and picked the IO-pad
  clock (1218 MHz) as the minimum; fixed and validated against the real
  log (min = clk_core 70.28 MHz).  README Fmax claim (~102 MHz) updated
  to the observed 70-95 MHz range.

Verified: run_check.py ALL PASS (incl. the raw >= q vector), Basys3
self-test sim PASS (3.03 ms), full Vivado-free bitstream flow end-to-end
with the timing gate on real nextpnr output.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: grandchildrice

ntt-core/README.md

@@ -62,7 +62,8 @@ python3 ntt-core/run_check.py
 `basys3_ntt_selftest.v` self-checks `INTT(NTT(x))==x` on-chip and shows the
 verdict on the LEDs (led0=done, led1=PASS, led2=FAIL, led[15:6]=mismatch
 count).  It runs the core on a **/2 BUFG clock (50 MHz)**; post-route the core
-clock closes at ~102 MHz, so 50 MHz has 2x margin.  Simulated PASS
+clock closes at ~70–95 MHz (run-dependent), and `bit.sh` **gates the build**
+on every reported clock closing ≥ 50 MHz.  Simulated PASS
 (`tb_selftest.v`, with the `sim_prims.v` BUFG stub).
 
 ```sh

ntt-core/basys3_ntt_selftest.v

@@ -27,7 +27,7 @@ module basys3_ntt_selftest #(
 );
     // ---- /2 clock: the core's Fmax (open flow) is ~95 MHz, so run the whole
     // design on a 50 MHz BUFG-buffered clock to meet timing with margin.  The
-    // self-test is not throughput-critical (it finishes in ~1.7 ms), so the
+    // self-test is not throughput-critical (it finishes in ~3 ms), so the
     // divided clock is invisible; only the verdict LEDs matter.
     reg clk_div = 1'b0;
     always @(posedge clk) clk_div <= ~clk_div;
@@ -42,6 +42,12 @@ module basys3_ntt_selftest #(
         else rst <= 1'b0;
     end
 
+    // ---- 2-FF synchronizer for the asynchronous button ---------------------
+    // btn_start comes straight off a pin; feeding it into FSM next-state
+    // logic unsynchronized risks metastability on the T_DONE->T_IDLE edge.
+    reg btn_m = 1'b0, btn_s = 1'b0;
+    always @(posedge clk_core) begin btn_m <= btn_start; btn_s <= btn_m; end
+
     // ---- the core ----------------------------------------------------------
     reg           start, mode, h_we;
     reg  [AW-1:0] h_addr;
@@ -73,12 +79,12 @@ module basys3_ntt_selftest #(
             idx <= 0; xg <= 14'd1; miss <= 0; btn_q <= 0;
         end else begin
             start <= 1'b0; h_we <= 1'b0;
-            btn_q <= btn_start;
+            btn_q <= btn_s;
             case (ts)
             // idle briefly, then auto-start; btnC re-runs
             T_IDLE: begin
                 idx <= 0; xg <= 14'd1; miss <= 0;
-                led[5:3] <= 3'd0;
+                led <= 16'h0000;       // clear the previous verdict on re-run
                 ts <= T_LOAD;
             end
             // ---- load x[i] via the host port ----
@@ -117,7 +123,7 @@ module basys3_ntt_selftest #(
                 led[2]     <= (miss != 0);     // FAIL
                 led[15:6]  <= miss;            // mismatch count
                 led[5:3]   <= 3'd7;
-                if (btn_start & ~btn_q) ts <= T_IDLE;   // re-run on button edge
+                if (btn_s & ~btn_q) ts <= T_IDLE;   // re-run on button edge (synced)
             end
             default: ts <= T_IDLE;
             endcase

ntt-core/bit.sh

@@ -35,9 +35,26 @@ nix shell nixpkgs#yosys --command yosys -p \
    write_json $OUT/design.json" >/dev/null
 
 echo "== 2/4 nextpnr-xilinx place & route -> FASM =="
+# no exit-code masking: a P&R failure aborts the flow immediately
 "$NP" --chipdb "$CHIPDB" --xdc ntt-core/basys3.xdc --json "$OUT/design.json" \
-      --fasm "$OUT/design.fasm" --write "$OUT/routed.json" 2>&1 \
-   | grep -iE "Max frequency|ERROR" || true
+      --fasm "$OUT/design.fasm" --write "$OUT/routed.json" \
+      > "$OUT/nextpnr.log" 2>&1 \
+  || { echo "nextpnr-xilinx FAILED:"; tail -30 "$OUT/nextpnr.log"; exit 1; }
+grep -iE "Max frequency" "$OUT/nextpnr.log" || true
+# timing gate: the core logic runs on clk/2 = 50 MHz, so EVERY reported clock
+# must close at >= 50 MHz (and any explicit constraint FAIL aborts).
+if grep -q "FAIL at" "$OUT/nextpnr.log"; then
+  echo "TIMING GATE FAIL: a constrained clock missed its target"; exit 1
+fi
+FMIN=$(grep -oE "Max frequency for clock +'[^']+': +[0-9.]+" "$OUT/nextpnr.log" \
+       | grep -oE '[0-9.]+$' | sort -n | head -1)
+if [ -z "${FMIN:-}" ]; then
+  echo "TIMING GATE FAIL: nextpnr reported no Fmax"; exit 1
+fi
+awk -v f="$FMIN" 'BEGIN {
+  if (f+0 < 50.0) { print "TIMING GATE FAIL: min Fmax " f " MHz < 50 MHz"; exit 1 }
+  print "timing gate OK: min Fmax " f " MHz >= 50 MHz (core clock)"
+}'
 
 echo "== 3/4 fasm2frames (prjxray db: $DB) =="
 nix-shell -p "python311.withPackages(ps: with ps; \

ntt-core/ntt_core.v

@@ -22,7 +22,9 @@
 //
 // Control:  start=1 with mode (0=NTT,1=INTT) begins a transform on the RAM
 // contents; done pulses when finished.  Load/read the RAM through the
-// host port (h_*) while idle.
+// host port (h_*) while idle.  Host input words are reduced mod q on load
+// (one conditional subtract — 14-bit input < 2q), so the core never feeds
+// an unreduced value into the verified datapath.
 // ============================================================================
 `timescale 1ns / 1ps
 module ntt_core #(
@@ -59,9 +61,14 @@ module ntt_core #(
     // block so the two write ports never form a multi-driver race; the engine
     // always drives lo on A and hi on B (distinct), and reads and writes of an
     // address never occur in the same cycle.
+    // Host words are fully reduced on load: h_din is 14 bits (max 16383
+    // < 2q), so ONE conditional subtract enforces the < q operating envelope
+    // that the verified datapath (K-RED butterfly, add/sub/half leaf proofs)
+    // is justified for — even when the host writes a raw value in [q, 2^14).
+    wire [DW-1:0] h_din_red = (h_din >= 14'd12289) ? h_din - 14'd12289 : h_din;
     wire [AW-1:0] pa_addr = busy ? a_addr : h_addr;
     wire          pa_we   = busy ? a_we   : h_we;
-    wire [DW-1:0] pa_din  = busy ? a_din  : h_din;
+    wire [DW-1:0] pa_din  = busy ? a_din  : h_din_red;
     always @(posedge clk) begin
         if (pa_we) mem[pa_addr] <= pa_din;
         if (b_we)  mem[b_addr]  <= b_din;

ntt-core/tb_ntt_core.v

@@ -37,7 +37,9 @@ module tb_ntt_core;
                 if (t == 0) x[m] = (m*7 + 1) % Q;
                 else begin
                     lcg  = lcg * 32'd1664525 + 32'd1013904223;
-                    x[m] = lcg % Q;
+                    // last round-trip vector: RAW 14-bit words (may be >= q)
+                    // — exercises the host-port mod-q reduction on load
+                    x[m] = (t == NRT-1) ? lcg[13:0] : (lcg % Q);
                 end
         end
     endtask
@@ -124,10 +126,11 @@ module tb_ntt_core;
             vec_errors = 0;
             for (i = 0; i < N; i = i + 1) begin
                 rd(i[AW-1:0], got);
-                if (got !== x[i]) begin
+                // raw inputs are reduced on load, so round-trip lands on x mod q
+                if (got !== (x[i] % Q)) begin
                     if (vec_errors < 4)
                         $display("  MISMATCH t=%0d i=%0d got=%0d want=%0d",
-                                 t, i, got, x[i]);
+                                 t, i, got, x[i] % Q);
                     vec_errors = vec_errors + 1;
                 end
             end