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 computes

Each contributor holds an alt-allele dosage vector g ∈ {0,1,2}^L over the
same 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 published
fixed-point factor S (w_scaled[j] = round(w_j·S)) and folded into the bundle
digest. 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 them
as a ciphertext × plaintext multiply, which does not raise ciphertext degree
(no relinearization) and involves no rotation (no Galois keys). The
cross-coordinate reduction Σ_j is done post-decrypt in the CLI, never under
encryption — that is what keeps the protocol on the same minimal BFV params as
the 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 the
cleartext sum bit-for-bit (tolerance: 0). The released real values carry
the fixed-point resolution of S (per-weight rounding error ≤ 1/S).

Append-1 sentinel (one subtlety this protocol adds): encryption appends a
trailing 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 sentinel
slot, so it is left unscaled and still decrypts to exactly N. It is an
integrity/corruption check, not a MAC (see SECURITY.md).

BFV parameters

Params are unchanged from the flagship except the plaintext modulus (which must
grow to fit the weight-inflated value envelope) and the coeff-modulus chain
(selected by --security, below):

--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 security
level 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 — the
depth-0 noise floor for this payload sits in the 256 band, so 128/192 carry
surplus modulus (bigger/slower ciphertexts) than 256 (the “256 is cheaper than
128” inversion).

Why 3-prime chains (not 2). TenSEAL reserves the LAST coeff prime as a
key-switching special prime, so the effective ciphertext modulus = Σ(all but
last). This protocol’s 30-bit t combined with the ciphertext × plaintext weight
multiply (scale up to ~2000) needs an effective q ≳ 80 bits, so a 2-prime
chain (e.g. [60,60], effective 60) FAILS to decrypt; every level ships a
3-prime chain (effective 120 / 100 / 90). All four additive protocols standardize
on these same PGS-safe chains so the SECURITY table is byte-identical across
bundles. The security benchmark column is computed by the harness as the
strictest level whose HomomorphicEncryption.org cap the chain fits under —
never read back from SEAL (SEAL only validates at tc128). Every level
decrypts the public-weighted aggregate bit-exact (verified, TenSEAL 0.3.16).

Downstream stages ts.context_from(...) the serialized context, so the chain
flows 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 exact
integer weight vector from that seed (stable random.Random(seed)), so the
server and the cleartext oracle score every contributor against the identical
vector, and any change to the seed/scale/generator changes the protocol digest.
No separate weight file is shipped (per docs/protocol_structure.md: public
weights live in the manifest for synthetic v1 protocols).

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, 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 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).

Run the full loop by hand

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

uv --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 the
integer-scaled aggregate, and the sentinel decrypts to exactly N despite
the weight multiply (weight 1 on the sentinel slot), including that dropping one
upload yields N−1 and removes exactly that contributor’s weighted dosage. A
parametrized case (test_bit_exact_at_every_security_level) re-runs the full
public-weighted loop at --security 128, 192, and 256, asserting bit-exact
correctness and sentinel==N under each coeff-modulus chain, and that each chain’s
achieved security equals the requested level. Skips with a clear reason only if
TenSEAL cannot be imported.

Coordinate & weight definition & synthetic data

For the synthetic v1 demo both the L=1000 coordinate list and the public
weight vector are generated deterministically from manifest.yml seeds
(input.coordinates.seed, weights.values.seed). The invariant that matters is
that every contributor encodes against the same published coordinate
definition and is scored against the same published weights, and that both
are folded into the bundle SHA-256. All data here is synthetic integer/real
vectors; no real genomic data is used anywhere.