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 computes

Each contributor holds an alt-allele dosage vector g ∈ {0,1,2}^L over a
fixed, published coordinate definition (ordered variants (chrom,pos,ref,alt));
coordinate j is the participant’s alt-allele count at variant j, missing
calls 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 every
contribution, so the homomorphic sum’s last slot decrypts to exactly N, the
contributor count. It is an integrity/corruption check, not a MAC — it says
nothing about whether contributors are distinct or genuine (see SECURITY.md).

Stage lifecycle & I/O contract

The 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 visible
without opening a subdirectory.

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 swaps
a PlaintextEvaluator for the same compute and cannot drift from this encrypted
path. 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 the
prior behaviour). It is the only knob that varies with the security level and
selects the coeff-modulus chain (coeff_mod_bit_sizes); poly_modulus_degree
(N=8192) and plain_modulus (t=1032193) are FIXED — functions of the value
envelope and depth (0), not of security. Downstream stages context_from(...)
the serialized context, so they stay security-agnostic: the choice flows through
automatically.

Intentional inversion: at FIXED N, the security level is the coeff-modulus
band — smaller Σ ⇒ more secure. So the 256 chain is the SMALLEST (and its
ciphertexts are the cheapest); the depth-0 noise floor for this payload already
sits in the 256 band, so certifying 128/192 spends surplus modulus. “256 is
cheaper than 128” is correct RLWE behaviour, not a bug. The chains are shared
byte-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). Every
level is verified bit-exact vs the cleartext oracle (see the test below).

(cd signed && uv --project env run python 00_keygen.py --out-dir "$D" --security 256)

Run the full loop by hand

cd protocols/allele_frequency_count
D=/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"
done
R 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)

uv --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 case
re-runs the whole loop at each --security level {128, 192, 256}, asserting
bit-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 data

For the synthetic v1 demo the L=1000 coordinate list is generated
deterministically from manifest.yml’s input.coordinates.seed rather than
enumerated inline. The invariant that matters is not a separate coordinate file —
it is that every contributor encodes against the same published definition and
that definition is folded into the bundle SHA-256. All data here is synthetic
integer vectors; no real genomic data is used anywhere.