#  OMEGA Orkestraattorin ArkkitehtuurimC$C$rittely ja API-Spesifikaatio (Draft
v1.0) OMEGA Orkestraattorin ArkkitehtuurimC$C$rittely ja API-Spesifikaatio
(Draft v1.0)
## 1. Yleiskatsaus ja Arkkitehtuuri
JC$rjestelmC$ on asynkroninen, tapahtumapohjainen ja tC$ysin verkkotyhjiC6ssC$
toimiva Hiekkalaatikko-orkestraattori (Sandbox Orchestrator). Se ei tarjoa
ulospC$in TCP/IP-portteja (kuten perinteinen REST API), vaan kommunikoi
ulkomaailman kanssa lokaalin tiedostojC$rjestelmC$n **IN- ja OUT-kansioiden**
kautta (Spooler / Drop-directory pattern).

### 1.1. Zero Trust -eristys
* **Orkestraattori (`node-base`):** Ei tiedC$ asiakkaiden (agenttien)
identiteettiC$, sijaintia tai verkkotopologiaa. Se ainoastaan lukee
IN-kansiosta komentoja ja kirjoittaa tulokset OUT-kansioon.
* **Instanssit (Hiekkalaatikot):** Ajetaan tC$ysin eristetyissC$
Linux-resurssikarsinoissa (Cgroups v2). Verkko-ominaisuudet on fyysisesti
irrotettu (Linux Network Namespaces `netns` `unshare`-komennolla).
* **IPC (Inter-Process Communication):** Orkestraattorin ja instanssien
vC$linen sekC$ instanssien ulospC$in suuntautuva tiedonsiirto tapahtuu
yksinomaan jaettujen, tiedostojC$rjestelmC$C$n perustumattomien
RAM-muistipankkien (`memfd`) kautta.

## 2. OMEGA-pakettien Rakenne (JSON)
Kommunikaatio on tilatonta ja asynkronista. Jokainen pyyntC6 vaatii
yksilC6llisen `transactionId`:n, jonka avulla lC$hettC$jC$ voi myC6hemmin
korreloida IN-kansioon jC$ttC$mC$nsC$ pyynnC6n OUT-kansioon ilmestyvC$C$n
vastaukseen.

### PyyntC6 (IN-kansio: esim. `cmd_<uuid>.json`)
{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2026-08-08T11:55:00Z",
  "command": "INSTANCE_INJECT_EVAL",
  "targetId": "alpha-sandbox-01",
  "payload": {
    "buffer": "c2hhcmVkTWVtWzBdID0gOTk5OTs=", 
    "encoding": "base64"
  }
}

### Vastaus (OUT-kansio: esim. `res_<uuid>.json`)
{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": "2026-08-08T11:55:01Z",
  "status": "SUCCESS",
  "data": {
    "evalResult": "true",
    "executionTimeMs": 14
  }
}

## 3. Komentohakemisto (Command Set)
Komennot on jaettu viiteen loogiseen pC$C$kategoriaan.

### 3.1. Instanssien Elinkaari ja Tila (Lifecycle)
| Komento | Kuvaus | Payload-parametrit |
| --- | --- | --- |
| `INSTANCE_CREATE` | Uuden hiekkalaatikon pystyttC$minen. | `name`,
`memoryLimitMb`, `cpuPercent` |
| `INSTANCE_DELETE` | Hiekkalaatikon lopullinen tuhoaminen ja siivous. |
`targetId` |
| `INSTANCE_START` | KC$ynnistC$C$ pysC$ytetyn hiekkalaatikon. | `targetId` |
| `INSTANCE_STOP` | PysC$yttC$C$ hiekkalaatikon (SIGKILL). | `targetId` |
| `INSTANCE_SUSPEND` | JC$C$dyttC$C$ suorituksen (SIGSTOP). CPU-aikaa ei kulu.
| `targetId` |
| `INSTANCE_RESUME` | Jatkaa jC$C$dytettyC$ suoritusta (SIGCONT). | `targetId`
|
| `INSTANCE_STATUS` | Kysyy yksittC$isen hiekkalaatikon tilan. | `targetId` |
| `INSTANCE_LIST` | Listaa kaikki aktiiviset hiekkalaatikot ja niiden tilat. |
- |
| `INSTANCE_GLOBAL_CTRL` | Massakomento kaikille laatikkoille
(suspend/resume/stop/start). | `action` ("suspend", "stop" jne.) |
| `INSTANCE_SAFE_MODE` | Asettaa instanssin vikasietotilaan (V8 debug-socket
pC$C$lle/pois). | `targetId`, `enabled` (boolean) |

### 3.2. Jaettu Muisti (Memory Banks & IPC)
| Komento | Kuvaus | Payload-parametrit |
| --- | --- | --- |
| `MEMORY_CREATE` | Luo uuden jaetun `memfd`-muistipankin. | `sizeBytes` |
| `MEMORY_ATTACH` | LiittC$C$ olemassa olevan muistipankin instanssiin. |
`targetId`, `memoryBankId` |
| `MEMORY_READ` | Lukee dataa muistipankista. Palauttaa puskurin Base64/Hex. |
`memoryBankId`, `offset`, `length` |
| `MEMORY_WRITE` | Kirjoittaa dataa muistipankkiin annetusta puskurista. |
`memoryBankId`, `offset`, `buffer` |

### 3.3. LC$hdekoodi ja V8-SyvC$luotaus (Code & Execution)
| Komento | Kuvaus | Payload-parametrit |
| --- | --- | --- |
| `CODE_SET` | Asettaa instanssin suoritettavan lC$hdekoodin. | `targetId`,
`buffer` (koodi) |
| `CODE_GET` | Palauttaa instanssiin ladatun lC$hdekoodin. | `targetId` |
| `CODE_RESET` | Formatoi / nollaa lC$hdekoodin oletustilaan. | `targetId` |
| `CODE_PATCH` | Haku- ja korvausoperaatio (sed/regex) olemassa olevaan
koodiin. | `targetId`, `pattern`, `replacement` |
| `DEBUG_INJECT_EVAL` | Ajaa koodia livenC$ V8-Debuggerin (CDP) kautta
lennosta. | `targetId`, `buffer` (eval-koodi) |
| `DEBUG_BATCH_RUN` | Ajaa newline-erotellun koodierC$n debuggerin lC$pi rivi
kerrallaan. | `targetId`, `buffer` (batch-skripti) |
| `LOG_TAIL` | Noutaa instanssin stdout/stderr -puskurin viimeiset N riviC$. |
`targetId`, `lines` (int) |

### 3.4. Metatiedot ja Konfiguraatio (Metadata)
| Komento | Kuvaus | Payload-parametrit |
| --- | --- | --- |
| `META_LIST_ALL` | Listaa kaikkien hiekkalaatikoiden nimikoidut metatiedot. |
- |
| `META_GET` | Hakee yksittC$isen instanssin tC$yden metadatapuun. |
`targetId` |
| `META_SET_KEY` | Asettaa instanssin metadatasta yksittC$isen avaimen arvon.
| `targetId`, `key`, `value` |
| `META_MERGE` | YhdistC$C$ (merge) uuden JSON-objektin olemassa olevaan
metadataan. | `targetId`, `jsonPayload` |
| `META_REPLACE` | Ylikirjoittaa koko metadatapuun uudella JSON-objektilla. |
`targetId`, `jsonPayload` |

### 3.5. JC$rjestelmC$n Tila ja Monitorointi (System)
| Komento | Kuvaus | Payload-parametrit |
| --- | --- | --- |
| `SYS_STATS` | Palauttaa isC$ntC$ympC$ristC6n ja cgroups-karsinoiden
resurssitiedot (uptime, free, df). | - |
| `SYS_POWER` | Suorittaa isC$ntC$-daemonille kC$yttC6jC$rjestelmC$tason
komennon. | `action` ("shutdown", "reboot") |

## 4. JC$rjestelmC$n Toimintaprosessi (Workflow)
1. **PyyntC6:** Ulkopuolinen agentti muodostaa yllC$ olevan spesifikaation
mukaisen JSON-paketin.
2. **Toimitus:** Agentti tallentaa tiedoston lokaalille levylle `IN/`-kansioon
(atomisesti kirjoittamalla ensin `.tmp`-pC$C$tteellC$ ja nimeC$mC$llC$ sen
uudelleen estC$C$kseen osittaiset luvut).
3. **KC$sittely:** `node-base`-orkestraattori kuuntelee hakemistoa (esim.
`fs.watch`). Kun uusi tiedosto ilmestyy, se lukee sen, reitittC$C$ oikealle
moduulille, suorittaa Cgroup/V8/netns-operaatiot ja luo tuloksesta
JSON-objektin.
4. **Vastaus:** Orkestraattori poistaa kC$sitellyn tiedoston `IN/`-kansiosta
ja kirjoittaa vastauspaketin `OUT/`-kansioon.
5. **Kuittaus:** Agentti lukee tuloksen `OUT/`-kansiosta `transactionId`:n
perusteella ja tuhoaa tiedoston.