Allele Frequency Count

# `allele_frequency_count` — Blind Machine flagship protocol> tenseal-BFV, **minimal (additive-only) params**. The simplest possible circuit:> a coordinate-wise homomorphic vector add. It carries the whole trust loop> end-to-end (freeze cohort → encrypted sum → min-N release → certificate) and is> the additive-suffices baseline every multiplicative-depth cost number is> measured against. See `docs/protocol_catalog.md` §1.## What it computesEach contributor holds an alt-allele **dosage vector** `g ∈ {0,1,2}^L` over afixed, published coordinate definition (ordered variants `(chrom,pos,ref,alt)`);coordinate `j` is the participant's alt-allele count at variant `j`, missingcalls encoded as 0. The cohort aggregate released is the per-coordinate sum:```sum_g[j] = Σ_i g_i[j]          (integer, exact)frequency[j] = sum_g[j] / (2·N)   (derived post-decrypt; 2 alleles per diploid coordinate)```**Exactness:** BFV is exact in `Z_t` with plaintext modulus `t > max sum = 2N`.`tolerance: 0` — the encrypted result equals the cleartext sum **bit-for-bit**.**Append-1 sentinel:** encryption appends a trailing `1` slot to everycontribution, so the homomorphic sum's last slot decrypts to **exactly N**, thecontributor count. It is an integrity/corruption check, **not a MAC** — it saysnothing about whether contributors are distinct or genuine (see `SECURITY.md`).## Stage lifecycle & I/O contractThe author's logic lives in three pure-function files, grouped by role: `server.py`(`compute`, the only server-side function), `local_project_owner.py`(`keygen`/`decrypt`/`decode`), and `local_data_owner.py` (`encode`/`encrypt`) —these are what sibling `tests/` import. The six numbered files are materialized into `signed/` at run time and are**kit-owned shims** (thin argparse wrappers; do not edit) that map each stage's CLI(`python NN_*.py --help`) onto those functions, keeping the lifecycle visiblewithout opening a subdirectory.| stage | runs | trust in → out | I/O ||-------|------|----------------|-----|| `00_keygen.py` | local (researcher) | — → PRIVATE + PUBLIC context | `--out-dir DIR [--security {128,192,256}]` → `secret_context.tenseal` (never upload), `public_context.tenseal` (uploadable) || `10_encode.py` | local (data owner) | RAW → ENCODED | `--raw raw.json --length L --out encoded.json` (validate {0,1,2}, null→0, pad to L) || `20_encrypt.py` | local (data owner) | ENCODED → ENCRYPTED | `--context public_context.tenseal --encoded encoded.json --out cipher.bin` (appends sentinel, BFV-encrypts) || `30_compute_encrypted.py` | **SERVER** | ENCRYPTED → ENCRYPTED | `--context public_context.tenseal --inputs c0.bin c1.bin … --out result.bin` (homomorphic sum; **no secret key present**) || `40_decrypt.py` | local (researcher) | ENCRYPTED → PRIVATE | `--context secret_context.tenseal --result result.bin --out plain.json` (length L+1) || `50_decode.py` | local (researcher) | PRIVATE → RELEASED | `--plain plain.json --length L --out result.json` (splits sentinel→N, counts, frequencies) |Inter-stage formats: contexts and ciphertexts are TenSEAL's raw serialized bytes(binary); raw/encoded/plain are JSON int lists; the released result is JSON with`n_contributors`, `allele_counts`, `allele_frequencies`.`server.py`'s `compute` is written **once** against an abstract evaluator `E`(`zero`/`add`), so `docs/simulation_mode.md`'s cleartext correctness oracle swapsa `PlaintextEvaluator` for the same `compute` and cannot drift from this encryptedpath. Determinism gives verify-by-re-execution: the same ordered ciphertexts in →a bit-identical result digest out (compute is deterministic; encryption is not).## HE security level (`--security`)`00_keygen.py` accepts `--security {128,192,256}` (default `128`, matching theprior behaviour). It is the **only** knob that varies with the security level andselects the coeff-modulus chain (`coeff_mod_bit_sizes`); `poly_modulus_degree`(N=8192) and `plain_modulus` (t=1032193) are FIXED — functions of the valueenvelope and depth (0), not of security. Downstream stages `context_from(...)`the serialized context, so they stay security-agnostic: the choice flows throughautomatically.| `--security` | `coeff_mod_bit_sizes` | Σ bits | achieved | N | t ||---|---|---|---|---|---|| `128` (default) | `[60, 60, 60]` | 180 | 128 | 8192 | 1032193 || `192` | `[50, 50, 50]` | 150 | 192 | 8192 | 1032193 || `256` | `[45, 45, 28]` | 118 | 256 | 8192 | 1032193 |**Intentional inversion:** at FIXED N, the security level is the coeff-modulusband — *smaller* Σ ⇒ *more* secure. So the 256 chain is the SMALLEST (and itsciphertexts are the cheapest); the depth-0 noise floor for this payload alreadysits in the 256 band, so certifying 128/192 spends *surplus* modulus. "256 ischeaper than 128" is correct RLWE behaviour, not a bug. The chains are sharedbyte-for-byte across all four additive protocols (PGS-safe 3-prime chains).The benchmark's `security` column is computed by the harness as`achieved(N, Σbits)` = the strictest level whose HomomorphicEncryption.org capΣ fits under — never read back from SEAL (SEAL only validates at tc128). Everylevel is verified bit-exact vs the cleartext oracle (see the test below).```bash(cd signed && uv --project env run python 00_keygen.py --out-dir "$D" --security 256)```## Run the full loop by hand```bashcd protocols/allele_frequency_countD=/tmp/afc && mkdir -p "$D"R() { (cd signed && uv --project env run python "$@"); }R 00_keygen.py --out-dir "$D"for i in 00 01 02; do  R 10_encode.py  --raw ../tests/vectors/contributor_$i.json --length 16 --out "$D/enc_$i.json"  R 20_encrypt.py --context "$D/public_context.tenseal" --encoded "$D/enc_$i.json" --out "$D/c_$i.bin"doneR 30_compute_encrypted.py --context "$D/public_context.tenseal" \  --inputs "$D/c_00.bin" "$D/c_01.bin" "$D/c_02.bin" --out "$D/result.bin"R 40_decrypt.py --context "$D/secret_context.tenseal" --result "$D/result.bin" --out "$D/plain.json"R 50_decode.py  --plain "$D/plain.json" --length 16 --out "$D/result.json"cat "$D/result.json"```## Test (local-loop equivalence)```bashuv --project signed/env run --group dev python -m pytest tests/```Proves keygen → encode → encrypt (≥3 synthetic contributors) → compute → decrypt→ decode equals the cleartext aggregate **exactly**, and the sentinel decrypts to**exactly N** (including that dropping one upload yields N−1). A parametrized casere-runs the whole loop at **each** `--security` level {128, 192, 256}, assertingbit-exactness and that each chain's *achieved* security equals the *requested*level. Skips with a clear reason only if TenSEAL cannot be imported.## Coordinate definition & synthetic dataFor the synthetic v1 demo the `L=1000` coordinate list is generateddeterministically from `manifest.yml`'s `input.coordinates.seed` rather thanenumerated inline. The invariant that matters is not a separate coordinate file —it is that every contributor encodes against the **same** published definition andthat definition is folded into the bundle SHA-256. All data here is syntheticinteger vectors; no real genomic data is used anywhere.