carrier_count — Blind Machine curated protocol

tenseal-BFV, minimal (additive-only) params. A coordinate-wise homomorphic
vector add over the flagship’s exact published coordinate definition — but with
a different client-side encoding. It is the registry-composability proof:
one published coordinate definition and one additive primitive drive a second
registered protocol without touching the trust loop. See
docs/protocol_catalog.md §2.

What it computes

Each contributor starts from the same alt-allele dosage vector g ∈ {0,1,2}^L
as the flagship, over the same fixed, published coordinate definition (ordered
variants (chrom,pos,ref,alt)). Encoding then thresholds each coordinate to a
carrier indicator locally, before encryption:

c[j] = 1 if g[j] >= 1 else 0        (missing call -> 0)

The cohort aggregate released is the per-coordinate carrier count — how many
participants carry at least one alt allele at each coordinate:

carrier_count[j] = Σ_i c_i[j]         (integer, exact, in [0, N])
carrier_rate[j]  = carrier_count[j] / N   (derived post-decrypt; people, not alleles → no ×2)

The contrast with the flagship is the whole point. Same raw genotypes, same
homomorphic circuit — but the flagship sums dosages (sum_g / 2N allele
frequency) while this sums thresholded indicators (n / N carrier rate). The
tests/vectors/ fixtures are byte-identical to the flagship’s so you can diff
the two released statistics from one input set.

Exactness: BFV is exact in Z_t with plaintext modulus t > max sum = N
(a carrier indicator is ≤ 1). tolerance: 0 — the encrypted result equals the
cleartext sum bit-for-bit. The default t = 1032193 stays exact for N up to
~1M (a larger margin than the flagship’s 2N ceiling).

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).
Note a free cross-check this protocol admits: every carrier_count[j] must lie
in [0, N] (a headcount can’t exceed the cohort), and 50_decode.py asserts it.

Security levels (--security {128,192,256})

00_keygen.py takes --security (default 128) to certify the context at a
chosen HE security level. It selects the coeff-modulus chain only; the ring
N = 8192 and plaintext modulus t = 1032193 are fixed (functions of the value
envelope and depth-0 circuit, not of security). Downstream stages read the
context and stay security-agnostic.

At fixed N, security level == the q-band and a smaller coeff modulus is
more secure. This protocol’s depth-0 noise floor sits in the 256 band, so
certifying 128/192 spends surplus modulus — the 128-bit chain is intentionally
larger (bigger, slower ciphertexts) than the 256-bit chain. That inversion is
correct RLWE behaviour, not a bug. The chain uses the PGS-safe 3-prime layout so
the SECURITY table is byte-identical across all four additive protocols. All
three levels decrypt bit-exact vs the cleartext oracle (parametrized in
tests/test_local_loop.py); the security column is computed from (N, Σbits)
against the HomomorphicEncryption.org table, never read back from SEAL.

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

Reuse map (vs the flagship allele_frequency_count)

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, carrier_counts, carrier_rates.

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

Run the full loop by hand

cd protocols/carrier_count
D=/tmp/cc && 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 carrier-count aggregate exactly, that the
distinguishing encoding thresholds dosage → {0,1}, and that the sentinel decrypts
to exactly N (including that dropping one upload yields N−1). 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 — the same
seed (blind-v1-demo-coordinates) as the flagship, because this protocol reuses
that exact coordinate definition. The invariant that matters 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.