docs: algorithm-level implications note + prime scout

docs/algorithm-level.md records where the two identities pay outside
hardware — deliberately kept out of the paper's claim set: embedded
cores, masked implementations (linear-vs-quadratic masking cost),
GPU FHE twiddle-table bandwidth, and the Goldilocks connection — and
distills the fold-economics boundary into a parameter-selection
criterion (signed-digit weight of k <= 2; check for a shift-friendly
psi).

generator/prime_scout.py makes the criterion executable: enumerates
Proth primes with k = 2^a +/- 1 across 14-16 / 28-32 / 60-64 bit
windows (deterministic Miller-Rabin), reports the planner's fold count
and the smallest shift-friendly primitive 2048-th root. Honest finding
from the sweep: cheap-fold primes are plentiful (incl. BabyBear,
3*2^30+1, 127*2^24+1, Goldilocks), but a shift-friendly psi is the
scarce property — only Falcon's 12289 has one among small candidates,
so multiplier-free psi-folding must be selected for explicitly.

The note states plainly that its software claims are cost-model
arguments, not CI-validated measurements.

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

Author: grandchildrice

docs/algorithm-level.md

@@ -0,0 +1,95 @@
+# Algorithm-level implications
+
+The paper deliberately claims hardware results only. This note records
+where the same ideas apply *outside* hardware — in software
+implementations and, most usefully, in protocol parameter selection.
+Nothing here is in the paper's claim set.
+
+## The observation
+
+Both inventions are algebraic identities, not circuits:
+
+- K-RED fold (Lemma 1): `k·z₀ − z₁ ≡ k·z (mod q)` for `q = k·2^m + 1`.
+- ψ-fold (Lemma 3): `w[N/2+j] = ψ·w[j]` in the bit-reversed negacyclic
+  twiddle table.
+
+Identities are substrate-independent; whether they pay depends on the
+cost model. Hardware pays because multipliers are the scarcest resource.
+The software contexts below share that shape.
+
+## Where K-RED pays in software
+
+K-RED started as a software technique (Longa–Naehrig 2016), so this is
+less a port than a map of where it still wins:
+
+- **Embedded cores** (Cortex-M0/M4 class): narrow multipliers make the
+  Barrett/Montgomery multiply chains expensive; shift-add folds are the
+  same trade the FPGA makes.
+- **Masked (side-channel-protected) implementations**: masking a linear
+  operation costs linearly in the share count, masking a multiplication
+  quadratically. Replacing two multiplies per butterfly with shift-adds
+  is the hardware win re-priced in masking cost — plausibly larger, and
+  unmeasured as far as we know.
+- **ZK fields**: the Goldilocks reduction used by ZK provers is exactly
+  this fold shape (k = 2³² − 1, signed-digit weight 1 subtraction), and
+  `k^F ≡ 1 (mod q)` there, so no scaling correction is needed at all
+  (§4.3 of the paper, Table 2).
+
+On a desktop CPU with a full 64-bit multiplier, the win mostly vanishes.
+
+## Where ψ-fold pays in software
+
+Software NTTs store the same bit-reversed tables, so halving (recursively
+quartering) transfers directly, at one constant multiply (or, for
+shift-friendly ψ, a shift-subtract) per derived access:
+
+- **Flash/ROM-constrained targets**: hundreds of bytes per table; modest
+  but free.
+- **GPU FHE libraries**: tables exist per RNS prime, dozens of primes,
+  N up to 2¹⁶ — megabytes of twiddles whose traffic competes with data
+  for memory bandwidth, which is the usual NTT bottleneck on GPUs. The
+  ψ-fold is a middle point between storing everything and full
+  on-the-fly generation: half (or quarter) the table for one constant
+  multiply per derived access.
+
+## The most useful transfer: parameter selection
+
+The fold-economics boundary (paper §4.3) is a *selection criterion* for
+anyone choosing new NTT primes (FHE RNS chains, new protocol
+parameters):
+
+> Prefer `q = k·2^m + 1` with the signed-digit weight of k at most 2
+> (k = 2^a ± 1), and check whether a shift-friendly ψ exists for the
+> target N.
+
+Both properties cost nothing at the protocol level and make every future
+implementation — hardware and software — cheaper. `generator/prime_scout.py`
+enumerates the candidates:
+
+```
+uv run generator/prime_scout.py
+```
+
+Findings from the current sweep (14–16, 28–32 and 60–64 bit windows,
+m ≥ 12):
+
+- Cheap-fold primes are plentiful: every window has many `2^a ± 1`
+  candidates with F = 2–3 folds, including the classics — Falcon 12289,
+  BabyBear `15·2²⁷+1`, the FFT primes `3·2³⁰+1` and `127·2²⁴+1`-class
+  entries, and Goldilocks (F = 3, no scaling needed).
+- The scarce property is the **shift-friendly ψ**, not the cheap fold:
+  in the sweep, only Falcon's q = 12289 has a signed-digit-weight-≤2
+  primitive 2048-th root among small candidates (ψ = 7). Everywhere
+  else the ψ-fold still works but needs a constant multiply instead of
+  a shift-subtract — cheap in software, a real multiplier in hardware.
+  A protocol that wants the multiplier-free fold must select for it
+  explicitly.
+
+## What does not transfer
+
+- No asymptotic change: the transform stays O(N log N) with the same
+  schedule; these are constant-factor, representation-level savings.
+- Desktop-CPU scalar code: multipliers are effectively free there.
+- All software claims above are cost-model arguments, not measurements;
+  none of them is validated by this repository's CI. Treat this note as
+  a map of where measuring would be worthwhile.

generator/prime_scout.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""
+Prime scout: enumerate Proth primes q = k*2^m + 1 whose k has signed-digit
+weight <= 2 (k = 2^a +/- 1), i.e. the primes for which the K-RED fold costs
+at most one adder/subtractor per fold — the selection criterion
+docs/algorithm-level.md proposes for new protocol parameters.
+
+For each hit we print the fold count F (from kred_gen's planner) and the
+smallest shift-friendly psi (signed-digit weight <= 2) that is a primitive
+2048-th root of unity, i.e. supports the N = 1024 negacyclic NTT with a
+multiplier-free psi-fold ROM ('-' if none of the small candidates works;
+the psi-fold then needs a constant multiply instead).
+
+Windows scanned: 14-16 bit (Falcon-class), 28-32 bit (BabyBear-class),
+60-64 bit (RNS/FHE-class).  Run: uv run generator/prime_scout.py
+"""
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from kred_gen import plan_kred
+
+MR_BASES = (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37)  # exact for < 2^64
+
+
+def is_prime(n):
+    if n < 2:
+        return False
+    for p in MR_BASES:
+        if n % p == 0:
+            return n == p
+    d, s = n - 1, 0
+    while d % 2 == 0:
+        d //= 2
+        s += 1
+    for a in MR_BASES:
+        x = pow(a, d, n)
+        if x in (1, n - 1):
+            continue
+        for _ in range(s - 1):
+            x = x * x % n
+            if x == n - 1:
+                break
+        else:
+            return False
+    return True
+
+
+def shift_friendly_psi(q, n=1024):
+    """Smallest psi with signed-digit weight <= 2 that is a primitive
+    2n-th root mod q (psi^n == -1)."""
+    if (q - 1) % (2 * n):
+        return None
+    cands = sorted({(1 << a) + s for a in range(1, 8) for s in (-1, 1)})
+    for psi in cands:
+        if 1 < psi < q and pow(psi, n, q) == q - 1:
+            return psi
+    return None
+
+
+WINDOWS = [(14, 16), (28, 32), (60, 64)]
+KNOWN = {12289: "Falcon", 3329: "Kyber", 8380417: "Dilithium",
+         2013265921: "BabyBear", (2**32 - 1) * 2**32 + 1: "Goldilocks"}
+
+
+def main():
+    print(f"{'q':>22}  {'k':>12}  {'m':>3}  {'F':>2}  {'psi':>4}  note")
+    for lo, hi in WINDOWS:
+        print(f"-- {lo}-{hi} bit --")
+        rows = []
+        for a in range(1, hi):
+            for s in (-1, 1):
+                k = (1 << a) + s
+                if k < 1 or k % 2 == 0:
+                    continue
+                for m in range(12, hi + 1):
+                    q = k * (1 << m) + 1
+                    if not (lo <= q.bit_length() <= hi):
+                        continue
+                    if not is_prime(q):
+                        continue
+                    F = len(plan_kred(q)["folds"])
+                    psi = shift_friendly_psi(q)
+                    rows.append((q, k, a, s, m, F, psi))
+        seen = set()
+        for q, k, a, s, m, F, psi in sorted(set(rows)):
+            if q in seen:
+                continue
+            seen.add(q)
+            kform = f"2^{a}{'+' if s > 0 else '-'}1"
+            note = KNOWN.get(q, "")
+            print(f"{q:>22}  {kform:>12}  {m:>3}  {F:>2}  "
+                  f"{psi if psi else '-':>4}  {note}")
+
+
+if __name__ == "__main__":
+    main()