WERSJA v10

jest to tylko do analizy i wyciagania logiki i perełek.

# GEMA-0 V10 APEX: OSTATECZNY MASTER PLAN I MAPA DROGOWA

**Status:** ZAMKNIĘTY. WERSJA PRODUKCYJNA.
**Cel:** Zbudowanie "Maksymalnie precyzyjnego programującego potwora", który miażdży rynek kosztami bliskimi zera i bezbłędnym wklejaniem kodu, bez żadnego "over-engineeringu".

> **Relacja z architecture v5:** Ten masterplan opisuje **silnik V10** (`backend/`, UI). **Idealny protokół plików i faz fabryki** to [architecture v5](../legacy/v2_monolith/examples/toy-projekt-gema0/.gema0/docs/architecture_v5.md). Mapowanie 1:1 faz, plików i luk: **[05_MAPA_PLANOW_V5_V10.md](05_MAPA_PLANOW_V5_V10.md)** — czytaj przed mieszaniem planów.

Usunęliśmy cały chaos. Odrzuciliśmy drogie GraphRAGi, niestabilne WASM i skomplikowane WebGPU. To jest esencja tego, czym GEMA-0 zdominuje branżę AI.

---

## 1. RDZEŃ ARCHITEKTURY: "THE APEX PREDATOR"

Rdzeń systemu to bezlitosna, jednokierunkowa taśma produkcyjna. Zero dyskusji z LLM-em. Zero halucynacji o architekturze.

### A. Mózg (Zero-Cost Context)
* **Docelowo:** `Tree-sitter` (Natywny parser w C++ podpięty pod Node.js).
* **Działanie (plan):** Zamiast wysyłać cały projekt do drogiego OpenAI (GraphRAG), system lokalnie buduje drzewo zależności AST. Tani model dostaje TYLKO sygnatury.
* **Stan w kodzie V10:** Oracle = **ręczny** — pole `oraclePrompt` w misji (`POST /api/mission`). Modułu Tree-sitter / Oracle automat **jeszcze nie ma**.

### B. Spekulatywny Rój (The Shotgun Swarm)
* **Narzędzie (kod):** Gemini API (+ mock LLM bez klucza). Plan: także Ollama / Groq / DeepSeek.
* **Działanie:** Orchestrator odpala **5 Ślepych Agentów jednocześnie** z różnymi ustawieniami temperatury. Agent dostaje absolutnie pusty szkielet i komentarz `// TODO`. Nic nie wie o bazie danych ani strukturze katalogów.
* **Brutalna Siła:** Pierwszy kod, który zadziała, wygrywa. Reszta agentów jest bezlitośnie odcinana przez `AbortController`. Koszt: **~0.0001 USD** za iterację. Czas oczekiwania: mierzony w milisekundach.

### C. Bezduszny Sędzia (Phantom VM)
* **Narzędzie:** Node.js `node:vm` + wstrzyknięty obiekt `Proxy`.
* **Działanie:** Wygenerowany tekst trafia do V8 Isolate (Piaskownica). Środowisko ma podstawiony fałszywy obiekt I/O (np. `db`). Zamiast dzwonić do prawdziwej bazy, obiekt `Proxy` łapie wywołanie i zapisuje do `Execution Trace` (Śladu Egzekucji). 
* **Sędzia orzeka:** Składnia, timeout, wykonanie w piaskownicy; opcjonalnie **`validateTrace()`** — reguły śladu I/O z misji (`traceExpectations`, np. wymagany `tenant_id` w `api.charge`).

### D. Chirurgiczna Wszywka (AST Grafter)
* **Narzędzie (kod):** `recast` + `@babel/parser` → `backend/ast/ast_grafter.mjs`.
* **Działanie:** Zwycięski kod **NIE JEST** mergowany przez Git. System podmienia **tylko ciało** docelowej funkcji w drzewie AST; reszta pliku nietknięta.
* **Docelowo (opcjonalnie):** `byteGrafter.mjs` z `magic-string` — precyzyjniejsze zakresy bajtowe, jeśli recast nie wystarczy.

---

## 2. INTERFEJS DOWODZENIA (THE NLE SEQUENCER)

Odrzuciliśmy Matrixowe Shadery 3D na rzecz błyskawicznej, pancernej i innowacyjnej koncepcji rodem z edytorów wideo (Non-Linear Editor).
* **Technologia:** `React` + `TailwindCSS` + `Framer Motion`.
* **Mechanika:** Głównym elementem interfejsu jest Oś Czasu (Timeline). Widzisz na niej ścieżki (Tracks) dla Architekta i 5 Agentów Roju (Swarm).
* **Przepływ:** Klikasz SWARM_START → wyścig roju na timeline (F2 ✅: WebSocket live z `events.ndjson`). Sędzia odrzuca agentów (`AGENT_FAILED`), zwycięzca (`AGENT_WON`) → animacja GRAFTED w AST X-Ray (dziś placeholder drzewa). **Następny krok UI:** time-travel (suwak cofania osi czasu).

---

## 3. MAPA DROGOWA WDROŻENIA (PROMPTY STARTOWE)

Gotowe bloki do skopiowania do czatów nowych Agentów (Cursor) w celu wygenerowania kodu.
`   
### [x] FAZA 0: EVENT BROKER & MOBILE TUNNEL - UKOŃCZONE
Budujemy szynę komunikacyjną i zdalny dostęp mobilny.
1. Stworzono `backend/core/eventBroker.mjs` z kolejką w pamięci RAM (`os.tmpdir()`), co gwarantuje atomowy, bezkolizyjny zapis zdarzeń od wielu równoległych agentów do wspólnego pliku `events.ndjson`.
2. API misji (`POST /api/mission`) i tunel mobilny — w **`backend/server.mjs`** (osobny `mobile_bridge.mjs` nie jest używany).
3. Wdrożono integrację z `localtunnel`, dzięki czemu natychmiast po uruchomieniu mostka generowany jest publiczny, zabezpieczony adres HTTPS.

### [x] FAZA 1: CORE - Mózg i Chirurg (UKOŃCZONE)
Zbudowano rdzeń oparty na manipulacji AST:
* Stworzono `backend/ast/ast_grafter.mjs` i pomyślnie zwalidowano koncepcję "Chirurga". Narzędzie sprawnie wyizolowuje abstrakcyjny szkielet funkcji usuwając z niego ciało dla LLMa, a następnie bezpiecznie i deterministycznie wszczepia wygenerowany poprawny blok z powrotem do drzewa AST, zachowując całkowicie resztę pliku (spacje, komentarze).
* (Do rozbudowy w przyszłości wg potrzeb: `byteGrafter.mjs` z `magic-string` i precyzyjny `Semantic Locking` dla pełnego wsparcia rygorystycznego event-loopa, ale podstawa udowodniona).

### [x] FAZA 2: PHANTOM VM (Sędzia) - UKOŃCZONE
* Zaprogramowano `backend/core/phantomVM.mjs` i potwierdzono, że potrafi przechwycić wywołania "ślepego" agenta przy użyciu wzorca The Phantom Object (JS Proxy).
* Symulowany kod wewnątrz piaskownicy V8 próbuje zapisać fałszywe dane, a Node.js bezpiecznie łapie te wywołania jako logiczne argumenty do weryfikacji. Odrzuca pętle nieskończone i błędy w kodzie ucinając błędy w milisekundach.
* Dodano **`validateTrace()`** — opcjonalne reguły semantyczne na śladzie I/O (`traceExpectations` w misji).

### [x] FAZA 3: SHOTGUN SWARM (Rój Strzelb) - UKOŃCZONE
* Stworzono rdzeń statystyczny `backend/ai/shotgunSwarm.mjs`, który w milisekundzie wypuszcza N-agentów równolegle z różnymi temperaturami.
* Podpięto pod ten system zintegrowanego Sędziego (`PhantomVM`) z użyciem mechanizmu `Promise.any`. Zwycięża ten kod, który jako pierwszy zwróci status `success: true` od Sędziego.
* Zaimplementowano bezlitosną gilotynę `AbortController`, natychmiast ubijającą pozostałe, wiszące w sieci wywołania do LLM-ów, oszczędzając czas i zasoby maszyny. Mamy fizyczny dowód, że wolny, ale dobry agent zostaje zabity, jeśli ktoś inny uwinął się szybciej.

### [x] FAZA 4: THE NLE SEQUENCER (Frontend UI) - UKOŃCZONE
* Stworzono aplikację `frontend/sequencer-ui` z trójdzielnym interfejsem.
* Wdrożono mroczny "Dark Mode" z akcentami rodem z profesjonalnych edytorów wideo/audio.
* Zaprogramowano główną Oś Czasu (The Timeline), na której ułożone są tory "Oracle" i "Ślepych Agentów".
* Przygotowano komponent "AST X-Ray" do wizualizacji struktury pliku źródłowego.
* F1 (layout) + **F2 (WebSocket live)** — `useGemaWebSocket`, proxy Vite, demo misja. Szczegóły: `_docs/02_WIZJA_FRONTEND_NLE_SEQUENCER.md`.
* **Następny front:** time-travel (suwak), opcjonalnie tor Judge.

---
*GEMA-0 APEX. The Ultimate Pragmatic Architecture. Fazy 0–4 rdzenia: ukończone. Iteracja: time-travel → Oracle/Tree-sitter.*