# GEMA-0 APEX — Brief dla Głównego Architekta AI (Gemini)

**Adresat:** Architekt planujący migrację RAM-first  
**Data:** 2026-05-30  
**Repozytorium:** `DamianMalenta/Gema0`, gałąź `main` @ `301c9c6`  
**Wersja produktu:** `10.1.0` (`package.json`; `GET /api/status` → `version`)  
**Szczegóły techniczne (kod):** `_docs/2026-05-30_RAPORT_RUROCIAG_GEMA0_V10.md`

---

## 1. Czym jest GEMA-0 V10.1 (stan faktyczny)

GEMA-0 APEX to **jeden serwer Node.js** (`backend/server.mjs`, port 7878) realizujący pipeline **Zero-Trust Triad**:

| Warstwa | Moduł | Rola |
|---------|--------|------|
| **Oraculum** | `ai/oraculum.mjs` + `api/oraculumDispatch.mjs` | LLM (Gemini Pro) → JSON manifestu misji na podstawie `projectMap` |
| **Shotgun Swarm** | `ai/shotgunSwarm.mjs` | N równoległych agentów (Gemini Flash), temperatura rosnąca |
| **Phantom VM** | `core/phantomVM.mjs` | Sędzia: AST lub `vm.Script` + testy / trace |
| **Orkiestrator** | `core/orchestrator.mjs` | RAM mount, tryb CREATE/GRAFT, flush na dysk |
| **ByteGrafter** | `ast/byteGrafter.mjs` | Grafting AST (MagicString + współrzędne Babel) |

**V10.1** to nie nowy silnik — to **domknięcie integracji/SRE** na tym samym kodzie V10: respektowanie `swarmSize` z manifestu, rozszerzony radar plików (`.jsx`, `.html`, …), wspólny `dispatchOraculumMissions` dla `/api/oraculum` i skrótu `/api/mission`, `ramWorkspace.unmountAll()` przy shutdown.

**Frontend:** `frontend/sequencer-ui` — panel operatorski (prompt → Oraculum, telemetria WS), **nie** drugi orchestrator.

---

## 2. Odpowiedzi na pytania planistyczne (dla Gemini)

### P1. Jaki jest dokładny przepływ od żądania użytkownika do zapisu pliku?

**Ścieżka produkcyjna (UI Live):**

```
Użytkownik (prompt + projectId)
  → POST /api/oraculum
  → buildProjectMap(workspace)
  → generateManifest() [Gemini Pro, max 45s]
  → dla każdej misji w manifest.missions:
       enqueueMission(projectId) [szeregowo per projekt]
       → Orchestrator.executeMission()
            → ramWorkspace.mountFile()  // tmpdir/gema0_ram_workspaces/...
            → [CREATE_NEW_FILE | GRAFT_EXISTING_AST]
            → fireSwarm() [Gemini Flash, Promise.any, max 60s]
            → PhantomVM.run() [sędzia]
            → zapis w RAM (writeFile | graftFunctionBody)
            → ramWorkspace.flushFile()  // copyFileSync → workspaces/<id>/
  → HTTP 200 + manifest (orchestrator dalej async w kolejce)
  → zdarzenia NDJSON → WebSocket /ws → UI
```

**Alternatywy wejścia (ten sam orchestrator):**

- `POST /api/mission` + pełny JSON (`targetFile`, `validationArgs`, `assemblyDir`, …) → **bez** Oraculum, bezpośrednio `executeMission`.
- `POST /api/mission` + tylko `{ projectId, prompt }` → ten sam dispatch co Oraculum (HTTP 202).

---

### P2. Czy mamy już „RAM-first”, czy tylko „RAM-then-disk”?

**Dziś: RAM-then-disk (hybryda).**

- Edycja odbywa się na `os.tmpdir()/gema0_ram_workspaces/<projectId>/...`.
- **Każda udana misja kończy się obowiązkowym `flushFile`** — `copyFileSync` do `repoRoot/workspaces/<projectId>/`.
- Po misji plik RAM **nie jest** usuwany (`unmount` tylko globalnie przy SIGINT/SIGTERM).

**Implikacja dla migracji RAM-first:** źródłem prawdy operacyjnej nadal jest **dysk workspace** po flush; RAM to bufor wydajności/kolejki zapisu, nie jedyne źródło prawdy.

---

### P3. Co jest zaimplementowane, a niepodpięte do rurociągu HTTP?

| Komponent | Status | Wpływ na plan |
|-----------|--------|----------------|
| `assemblyAdapter.parseAssemblyJob` | Kod gotowy, **brak route** | Drugi model misji (pliki `.gema0/assembly/<jobId>/`) — wymaga endpointu lub merge z Oraculum |
| `assemblyDir`, `mechanicalGate`, `traceExpectations` w ścieżce Oraculum | Orchestrator obsługuje; **dispatch ich nie mapuje** | Pełne testy VM/gate tylko przez `POST /api/mission` (pełny payload) |
| `llmProvider` w `fireSwarm` | Parametr **martwy** — zawsze `aiGateway.generateContent` | Abstrakcja providera do dokończenia przy multi-model |
| `createLlm()` w `oraculumDispatch` | Bez `await` | Do naprawy przy podłączeniu providera do Oraculum/Swarm |
| Marketing API | HTTP jest, **brak UI** | Osobny tor, poza generacją kodu |
| `legacy/` + `npm run start:legacy` | Osobny monolit | **Nie** planować migracji V10 na bazie legacy |

---

### P4. Czy istnieje „drugi rurociąg” generacji kodu?

**Nie** — jeden `Orchestrator`. Są **osobne tory**:

- Provision / dev server (`provisionRoutes`, `workspaceDevManager`)
- Marketing (`marketingRoutes` — dynamiczny import z workspace)
- CLI (`workspace-provision.mjs`, `workspace-vite-dev.mjs`)
- Legacy monolit (wyłącznie kompatybilność)

**Prawie-drugi tor:** assembly z plików (`assemblyAdapter`) — zaprojektowany, **niepodłączony**.

---

### P5. Jak frontend współgra z backendem?

| Aspekt | Fakty z kodu |
|--------|----------------|
| Start misji (Live) | `POST /api/oraculum` — tylko `{ projectId, prompt }` |
| Telemetria | WebSocket `/ws` ← `events.ndjson` (tail + broadcast) |
| Wizualizacja roju | UI: 5 slotów; backend: `swarmSize` 3–20 z manifestu |
| Sterowanie trybem/plikiem | Wyłączone w UI (zakomentowane); decyduje Oraculum |
| Mock | Symulacja lokalna bez API |
| Provision / podgląd | Osobne endpointy; reaguje na zdarzenia `PROVISION_*`, `DEV_SERVER_*` |

**Wniosek architektoniczny:** Sequencer to **NLE/operator panel**, nie warstwa planowania. Planowanie misji = Oraculum (LLM Pro). Egzekucja = Orchestrator + Swarm (LLM Flash).

---

### P6. CREATE_NEW_FILE vs GRAFT_EXISTING_AST — różnice krytyczne dla projektu RAM-first

| | CREATE_NEW_FILE | GRAFT_EXISTING_AST |
|---|-----------------|---------------------|
| Wejście VM (`targetFile`) | ścieżka **RAM** | ścieżka **fizyczna** (niespójność) |
| Sędzia (NODE, bez gate) | AST całego pliku (`FULL_FILE`) | `vm.Script` + wywołanie funkcji |
| Zapis | `writeFile` całości | `graftFunctionBody` (MagicString) |
| Concurrency | kolejka zapisu per plik | + `lockManager` na zakresie AST |

Przy migracji RAM-first **należy ujednolicić**: PhantomVM, locki i graft wyłącznie na `ramTargetFile`; flush jako opcjonalny/export, nie domyślny commit.

---

### P7. Modele LLM i kontrakty JSON

| Faza | Model (kod) | Format wyjścia |
|------|-------------|----------------|
| Oraculum | `gemini-2.5-pro` (`responseMimeType: application/json`) | `{ "missions": [ { targetFile, functionName, mode, oraclePrompt, validationArgs, profile, swarmSize } ] }` |
| Swarm (każdy agent) | `gemini-2.5-flash` | surowy kod (bez markdown; `sanitizeGeneratedCode`) |

Timeouty SRE: Oraculum 45s; Swarm globalnie 60s; VM 2s per test.

---

### P8. Co zalecamy Architektowi AI zaplanować w migracji RAM-first (priorytety)

**P0 — spójność warstwy pliku**

1. Jedno źródło prawdy w RAM na czas misji (`ramTargetFile` wszędzie: VM, lock, graft, read).
2. `flushFile` jako **explicit commit** (API / flaga misji / batch), nie domyślny krok każdej misji.
3. `unmountFile` / wersjonowanie po misji (uniknięcie „brudnego” tmpdir).

**P1 — domknięcie kontraktów**

4. Podpiąć `assemblyAdapter` (HTTP lub rozszerzenie manifestu Oraculum).
5. Mapować `assemblyDir`, `mechanicalGate`, `traceExpectations` w `oraculumDispatch`.
6. Użyć `llmProvider` w `fireSwarm` lub usunąć z API (jeden gateway).

**P2 — UI i observability**

7. UI: `swarmSize` z manifestu, opcjonalnie pełna misja / preview przed flush.
8. Zdarzenia: `RAM_MOUNT`, `RAM_FLUSH`, `RAM_DISCARD` dla Timeline.

**Poza zakresem V10.1 (nie mieszać):** `legacy/`, marketing, provision — osobne bounded contexts.

---

## 3. Diagram architektury (stan obecny)

```mermaid
flowchart TB
  UI[sequencer-ui Live]
  API[server.mjs :7878]
  ORC[Oraculum Gemini Pro]
  DISP[oraculumDispatch]
  Q[enqueueMission per projectId]
  O[Orchestrator]
  RAM[ramWorkspaceManager tmpdir]
  SW[fireSwarm Gemini Flash]
  VM[PhantomVM]
  DISK[workspaces/projectId]

  UI -->|POST /api/oraculum| API
  UI -->|WS /ws| API
  API --> DISP
  DISP --> ORC
  DISP --> Q
  Q --> O
  O --> RAM
  O --> SW
  SW --> VM
  O -->|flushFile| DISK
  RAM -.->|mount copy| DISK
```

---

## 4. Checklist weryfikacji (dla Architekta po wdrożeniu planu)

- [ ] Wszystkie ścieżki czytania/zapisu w misji używają `ramTargetFile`
- [ ] `flushFile` wywoływany tylko gdy użytkownik/system żąda commit
- [ ] Oraculum lub assembly dostarcza `mechanicalGate` gdy wymagane testy VM
- [ ] `GET /api/status.version` === `package.json.version`
- [ ] Brak równoległego orchestratora w legacy dla nowych feature’ów
- [ ] UI odzwierciedla rzeczywisty `swarmSize` i kolejkę `manifest.missions`

---

## 5. Tekst do wklejenia w rozmowę z Gemini (skrót)

> GEMA-0 APEX **10.1.0** na `main`: jeden orchestrator Node (Oraculum → manifest → Shotgun Swarm → PhantomVM → RAM w tmpdir → **obowiązkowy flush** na `workspaces/`). To **RAM-then-disk**, nie pełne RAM-first. Niepodpięte: `assemblyAdapter` (HTTP), pola `assemblyDir`/`mechanicalGate`/`traceExpectations` w dispatch Oraculum, `llmProvider` w swarm. Frontend sequencer to prompt + WS, bez sterowania trybem. Migracja RAM-first: ujednolicić ścieżki na RAM, flush jako commit, podpiąć assembly i gate, opcjonalnie rozdzielić „draft w RAM” od „publish na dysk”. Szczegóły: `_docs/2026-05-30_RAPORT_RUROCIAG_GEMA0_V10.md`.

---

*Brief przygotowany na podstawie reverse engineeringu kodu `backend/` i `frontend/sequencer-ui` (2026-05-30).*