Polygenic Score Aggregate

# `polygenic_score_aggregate` — Blind Machine curated protocol> tenseal-BFV, **minimal (additive-tier) params**. The clearest "looks> multiplicative, remains additive" example: a public-weighted polygenic score> `Σ_j w_j·g_j` computed as an additive homomorphic fold **plus one> plaintext-scalar multiply** by the PUBLIC effect-weight vector — never a> ciphertext × ciphertext multiply. See `docs/protocol_catalog.md` §4.## What it computesEach contributor holds an alt-allele **dosage vector** `g ∈ {0,1,2}^L` over thesame fixed, published coordinate definition as the flagship (ordered variants`(chrom,pos,ref,alt)`), missing calls encoded as 0. The protocol also fixes a**public effect-weight vector** `w ∈ ℝ^L`, integer-scaled by a publishedfixed-point factor `S` (`w_scaled[j] = round(w_j·S)`) and folded into the bundledigest. The cohort aggregate released is the per-coordinate **public-weighted**sum:```weighted_counts[j] = w_scaled[j] · Σ_i g_i[j]        (integer, exact in Z_t)cohort_pgs_scaled  = Σ_j weighted_counts[j]          (integer)mean_PGS           = cohort_pgs_scaled / (S·N)       (real, post-decrypt)```where each contributor's polygenic score is `PGS_i = Σ_j (w_scaled[j]/S)·g_ij`.**Why it stays additive.** Every weight is **public**, so the server applies themas a **ciphertext × plaintext** multiply, which does not raise ciphertext degree(no relinearization) and involves no rotation (no Galois keys). Thecross-coordinate reduction `Σ_j` is done **post-decrypt in the CLI**, never underencryption — that is what keeps the protocol on the same minimal BFV params asthe flagship. This is the catalog's canonical demonstration that a statistic can*look* multiplicative and still be served by additive-tier BFV.**Exactness:** BFV is exact in `Z_t`; the integer-scaled aggregate equals thecleartext sum **bit-for-bit** (`tolerance: 0`). The released real values carrythe fixed-point resolution of `S` (per-weight rounding error `≤ 1/S`).**Append-1 sentinel (one subtlety this protocol adds):** encryption appends atrailing `1` slot to every contribution, so the homomorphic sum's last slot is`N`. The server's plaintext-weight multiply uses **weight `1` on that sentinelslot**, so it is left unscaled and still decrypts to **exactly N**. It is anintegrity/corruption check, **not a MAC** (see `SECURITY.md`).## BFV parametersParams are unchanged from the flagship except the plaintext modulus (which mustgrow to fit the weight-inflated value envelope) and the coeff-modulus chain(selected by `--security`, below):| param | value | why ||-------|-------|-----|| `poly_modulus_degree` | 8192 | 8192 slots ≫ L+1; FIXED across all security levels (batching prime valid only at N=8192, depth-0 needs no bump). || `plain_modulus` | 1073692673 | 30-bit batching prime (≡ 1 mod 16384). Max slot after the weight multiply is `max_j(w_scaled[j])·2N`; the flagship's 20-bit `t` is under-sized. Exact for `S=1000`, `w_scaled ≤ 2000`, N up to ~250k. FIXED — a function of the value envelope, not security. || `coeff_mod_bit_sizes` | see `--security` | selects the q-band that fixes the achieved HE security level. || relin / Galois keys | **none** | ciphertext × plaintext only; no rotation |### `--security {128,192,256}` (default 128)`--security` is the ONLY knob that varies with the requested HE security level;it selects the `coeff_mod_bit_sizes` chain. At **fixed N=8192** the securitylevel is the q-band: **smaller Σbits ⇒ more secure**, so certifying a *higher*level spends a *smaller* modulus. This is correct RLWE behaviour, not a bug — thedepth-0 noise floor for this payload sits in the 256 band, so 128/192 carrysurplus modulus (bigger/slower ciphertexts) than 256 (the "256 is cheaper than128" inversion).| `--security` | `coeff_mod_bit_sizes` | Σ bits | achieved ||---|---|---|---|| 128 (default) | `[60, 60, 60]` | 180 | 128 || 192 | `[50, 50, 50]` | 150 | 192 || 256 | `[45, 45, 28]` | 118 | 256 |**Why 3-prime chains (not 2).** TenSEAL reserves the LAST coeff prime as akey-switching *special* prime, so the effective ciphertext modulus = Σ(all butlast). This protocol's 30-bit `t` combined with the ciphertext × plaintext weightmultiply (scale up to ~2000) needs an **effective q ≳ 80 bits**, so a 2-primechain (e.g. `[60,60]`, effective 60) FAILS to decrypt; every level ships a3-prime chain (effective 120 / 100 / 90). All four additive protocols standardizeon these same PGS-safe chains so the `SECURITY` table is byte-identical acrossbundles. The `security` benchmark column is computed by the harness as thestrictest level whose HomomorphicEncryption.org cap the chain fits under —**never** read back from SEAL (SEAL only validates at tc128). Every leveldecrypts the public-weighted aggregate **bit-exact** (verified, TenSEAL 0.3.16).Downstream stages `ts.context_from(...)` the serialized context, so the chainflows through unchanged — they stay security-agnostic.## Public weights (deterministic, content-addressed)`manifest.yml` declares `weights: { scale: 1000, values: { kind:synthetic_weights, seed: blind-v1-pgs-weights, range: [1, 2000] } }`.`30_compute_encrypted.py`'s `scaled_weights(length)` regenerates the exactinteger weight vector from that seed (stable `random.Random(seed)`), so theserver and the cleartext oracle score every contributor against the identicalvector, and any change to the seed/scale/generator changes the protocol digest.No separate weight file is shipped (per `docs/protocol_structure.md`: publicweights live in the manifest for synthetic v1 protocols).## 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 — identical to flagship) || `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 **then public plaintext-weight multiply**; **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 [--scale S] --out result.json` (splits sentinel→N, weighted counts, cohort/mean PGS) |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`, `weighted_counts`, `cohort_pgs_scaled`, `cohort_pgs_sum`,`mean_pgs`.`server.py`'s `compute` is written **once** against an abstract evaluator `E`(`zero`/`add`/`scalar_mul`), so `docs/simulation_mode.md`'s cleartext correctnessoracle swaps a `PlaintextEvaluator` for the same `compute` and cannot drift fromthis encrypted path. Determinism gives verify-by-re-execution: the same orderedciphertexts in → a bit-identical result digest out (compute is deterministic;encryption is not).## Run the full loop by hand```bashcd protocols/polygenic_score_aggregateD=/tmp/pgs && mkdir -p "$D"R() { (cd signed && uv --project env run python "$@"); }R 00_keygen.py --out-dir "$D"for i in 00 01 02 03; 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" "$D/c_03.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 oracle (same public weights) **bit-exact on theinteger-scaled aggregate**, and the sentinel decrypts to **exactly N** despitethe weight multiply (weight 1 on the sentinel slot), including that dropping oneupload yields N−1 and removes exactly that contributor's weighted dosage. Aparametrized case (`test_bit_exact_at_every_security_level`) re-runs the fullpublic-weighted loop at **`--security` 128, 192, and 256**, asserting bit-exactcorrectness and sentinel==N under each coeff-modulus chain, and that each chain'sachieved security equals the requested level. Skips with a clear reason only ifTenSEAL cannot be imported.## Coordinate & weight definition & synthetic dataFor the synthetic v1 demo both the `L=1000` coordinate list and the publicweight vector are generated deterministically from `manifest.yml` seeds(`input.coordinates.seed`, `weights.values.seed`). The invariant that matters isthat every contributor encodes against the **same** published coordinatedefinition and is scored against the **same** published weights, and that bothare folded into the bundle SHA-256. All data here is synthetic integer/realvectors; no real genomic data is used anywhere.