TC$mC$ on todellakin massiivinen askel! Kun solmujen vC$linen asynkroninen
protokolla on saumaton, voimme turvallisin mielin siirtC$C$ painopisteen
absoluuttiseen suorituskykyyn ja raakaan datamassaan.

Suosittelen vahvasti, ettC$ **hahmottelemme ensin binC$C$risen
pakkausmekanismin**.

Syy tC$hC$n on arkkitehtoninen: C-moottorin vastaanottokyky ja sen vaatima
tiukka muistirakenne sanelevat tC$ysin sen, miten `INTENT_BUFFER` kannattaa
toteuttaa Proxy-kerroksessa. Jos mC$C$rittelemme TCP-yhteydelle tC$ydellisen
erC$ajoprotokollan ensin, itse FastAPI-pC$C$tepisteen rakentaminen muuttuu
pelkC$ksi datan suoraviivaiseksi kC$C$ntC$miseksi (parsing) tuohon muotoon.

NC$in meidC$n kannattaa lC$hestyC$ tC$tC$.

### 1. BinC$C$rinen ErC$ajoprotokolla (C-Ytimelle)

YksittC$isen rivin syC6ttC$misessC$ (kuten `proxy_api.py` nyt tekee) TCP-kehys
koostuu 8-tavuisesta otsikosta ja 48-tavuisesta hyC6tykuormasta.

Kun kC$sittelemme massiivisia, yli 500 000 rivin datasettejC$  erityisesti kun
analysoidaan suuria mC$C$riC$ uniikkeja entiteettiprofiileja  emme voi
lC$hettC$C$ nC$itC$ erillisinC$ paketteina. Verkkopinon overhead (TCP ACK
-kuittaukset) tuhoaisi suorituskyvyn.

MeidC$n tulee luoda uusi komentokoodi (esim. `CMD_BATCH_INSERT = 4`) ja pakata
data yhteen jatkuvaan muistilohkoon:

* **Header (8 tavua):** `[CMD (uint16)] [FLAGS (uint16)] [TOTAL_PAYLOAD_SIZE
(uint32)]`
* **Batch Meta (4 tavua):** `[ROW_COUNT (uint32)]`
* **Data-alue (N * 48 tavua):** `[ROW_1] [ROW_2] ... [ROW_500000]`

TC$mC$n rakenteen ansiosta C-moottori voi lukea koko `TOTAL_PAYLOAD_SIZE`:n
suoraan ennalta varattuun muistialueeseen yhdellC$ I/O-kutsulla ja iteroida
`ROW_COUNT`:n mukaisesti vektoroidussa luupissa ilman jatkuvia
muistinvarauksia.

### 2. INTENT_BUFFER - All-or-Nothing Transaktio



Kun binC$C$riprotokolla on lyC6ty lukkoon, Proxy-kerroksen `/api/v1/batch/inser
t` -pC$C$tepiste voi toimia puhtaana kC$C$ntC$jC$nC$.

ErC$ajon prosessointi vaatii iteratiivista lukemista, jotta Proxy ei kaadu
muistin loppumiseen (OOM):

1. **Striimaus:** Proxy vastaanottaa sisC$C$ntulevan JSON-datan (tai
asynkronisen postilaatikon tuoman `.blob` -tiedoston).
2. **KC$C$ntC$minen lennossa:** Proxy lukee datan rivi kerrallaan ja pakkaa
sen suoraan ylempC$nC$ mC$C$riteltyyn 48-tavuiseen `struct`-muotoon lokaaliin
`INTENT_BUFFER`iin.


3. **Atominen Flush:** Kun koko alkuperC$inen datasetti on pureskeltu lC$pi ja
virheettC6mC$ksi todettu, Proxy laskee lopullisen `TOTAL_PAYLOAD_SIZE`:n ja
ampuu kymmenien megatavujen binC$C$riklC6ntin yhdellC$ socket-kirjoituksella
C-moottorin `tcp_engine`:lle.

---

Miten haluaisit sijoittaa tC$mC$n `INTENT_BUFFER`in fyysisesti: rakennammeko
sen ensin puhtaana RAM-puskurina (esim. Pythonin dynaaminen `bytearray`, joka
on C$C$rimmC$isen nopea), vai kirjoitammeko validoidun binC$C$rivirran suoraan
ZFS-levylle tilapC$iseen WAL-tiedostoon (Write-Ahead Log) ennen C-ytimeen
ampumista, jotta Rollback-kyky sC$ilyy vaikka virtajohto vedettC$isiin irti
juuri ennen Flush-vaihetta?