# Geometry Pipeline Engine (GPE) — Mimari (çekirdek dilim)

Kaynak vizyon: `FikoCAD_Geometry_Pipeline_Engine_Opus48_Prompt.md` (10 fazlık plan).
GPE, Geometri Zekâ Motoru'nun (`motor/zeka`, bkz. `docs/zeka_motoru_mimari.md`)
üstünde çalışan **CAD semantik yürütme motorudur**: MongoDB Aggregation +
SQL optimizer + LLVM pass ruhu. Bu doküman 16 RFC başlığını kısaca karşılar ve
fazların şimdi/sonra ayrımını verir. Kod: `motor/zeka/include/fiko/zeka/pipeline.hpp`,
`motor/zeka/src/pipeline.cpp`, test: `motor/zeka/test/test_pipeline.cpp`.

## 1. Hedefler (Goals)
Tek yürütme planına derlenen çoklu temsil (Fluent C++ + JSON; görsel node grafı
sonra). Zekâ grafı üzerinde bildirimsel sorgu/dönüşüm: kaynak → süz → genişlet →
projeksiyon → sıralama/limit → agregasyon. Plugin-first stage registry (çekirdek
stage'ler de aynı kapıdan), sonuç önbelleği, optimizer tohum geçişleri, MCP/uzaktan
API için JSON sonuç serileştirme.

## 2. Hedef-dışı (Non-Goals)
GPE bir veritabanı değildir; kalıcılık/transaction yok. Bu dilimde: paralel/SIMD
yürütme yok, görsel editör yok, sandbox yok, incremental (delta) yürütme yok,
maliyet tabanlı plan seçimi yok. Sorgu API'si (`sorgu.hpp`) DEĞİŞMEZ — GPE onun
genelleşmiş halidir, ikisi yan yana yaşar.

## 3. Gereksinimler
Türkçe hata mesajları; plan `derle()` sonrası immutable; `calistir(const GrafDeposu&)`
grafı mutasyona uğratmaz; bilinmeyen stage/işleç/sürüm açık hata (sessiz bozuk plan
yasak); test tabanı küçülmez.

## 4. Üst Düzey Mimari
```
Fluent C++ ─┐
JSON ───────┼─→ PipelineAsama listesi (AST) ─→ Optimizer geçişleri ─→
Node grafı ─┘ (sonra)                          Fabrika (registry) ─→ AsamaYurutucu[]
                                               ─→ calistir(graf) ─→ PipelineSonuc (+önbellek)
```
AST bilinçli olarak DÜZ liste + parametre çantasıdır (LLVM taklidi sınıf
hiyerarşisi kurulmadı — mevcut ihtiyaç bu, genişleme parametre çantasından).

## 5. Pipeline Yaşam Döngüsü
1) Kurulum (fluent çağrılar ya da `jsonDanKur`) — plan mutable.
2) `derle()` — tohum optimizer geçişleri + dış geçişler; her stage için registry'den
   fabrika çağrılır (parametre doğrulama BURADA, koşuda değil); plan imzası hash'lenir;
   başarı sonrası plan immutable (sonraki fluent çağrı hata bırakır).
3) `calistir(graf)` — önbellek denetimi → yürütücüler sırayla → sonuç önbelleğe.
4) Aynı Pipeline nesnesi farklı graflarla tekrar tekrar koşturulabilir.

## 6. Bileşenler
- **PipelineAsama**: interned ad (`u32`, registry kimliği) + `param` (ad→`Deger`)
  + `kosullar` (Sorgu-benzeri) + `anahtarlar` (projeksiyon).
- **Stage registry**: ad→fabrika; `stageKaydet` ile plugin kaydı; çekirdek 9 stage
  (`kaynak/govdede/suz/genislet/sec/sirala/limit/say/topla`) aynı registry'de.
- **AsamaBaglam**: `graf` + akan `PipelineSonuc` + `baslatildi` bayrağı;
  `asamaBaslat()` küme boşken tüm canlı düğümleri doldurur (Sorgu'nun tam tarama
  fallback'inin karşılığı).
- **PipelineSonuc**: kimlikler + (sec varsa) paralel satırlar + (say/topla) skaler
  + `jsonYaz()`.

## 7. Veri Akışı
Stage'ler `vector<u64>` kimlik listesi üzerinde ARDIŞIK dönüşümdür (iterator/lazy
tiyatrosu yok — graf zaten bellekte, listeler küçük). `sec` satırları kimliklerle
paralel taşır; kümeyi değiştiren stage'ler (genislet) satırları düşürür, süzen/
sıralayan/kesenler paralel günceller.

## 8. Bellek Stratejisi
Plan ve sonuç değer-tipli (vector/string/variant); özel havuz yok. Yürütücüler
stage verisini KOPYAYLA yakalar (plan taşınabilir, sarkan referans imkânsız).
Pipeline kopyalanamaz (derlenmiş yürütücüler), taşınabilir. GPE sıcak yolda
ÇAĞRILMAZ (anayasa: her-kare kod kutsal) — tahsis serbestliği bilinçli.

## 9. İş Parçacığı Stratejisi
`calistir` grafı yalnız okur (`const GrafDeposu&`) → aynı graf üzerinde eşzamanlı
okumalar güvenli. Registry, dış geçiş listesi ve sonuç önbelleği mutex korumalı.
Stage-içi paralellik ve incremental yürütme gelecek faz (bkz. §13); bugünkü
sözleşme: tek pipeline nesnesi aynı anda tek iş parçacığından koşturulur.

## 10. Plugin Stratejisi
`stageKaydet(ad, fabrika)`: fabrika `(PipelineAsama, hata&) → AsamaYurutucu`.
Çekirdek stage'ler de bu kapıdan geçer (plugin-first kanıtı). JSON'da bilinmeyen
ad registry'de aranır; kayıtlıysa parametreleri genel çanta olarak okunur, değilse
"Bilinmeyen pipeline stage: 'X'". Lua/MCP köprüsü Faz 2'de JSON temsil üzerinden
bağlanır (motor bağımsızlığı korunur — `motor/zeka` yalnız core+geometri'ye bağlı).

## 11. Performans Stratejisi
- İlk stage `kaynak`/`govdede` ise tam tarama hiç yapılmaz (tip/gövde indeksi).
- Sonuç önbelleği: anahtar = graf adresi + `graf.surum()` + `dugumUst()` + plan
  imza hash'i (FNV-1a). Kapasite `Pipeline::onbellekKapasite` (64, public);
  LRU-vari (en eski tik düşer). Sürüm her mutasyonda arttığı için bayat sonuç dönmez.
- Optimizer tohumu: ardışık `suz` birleşir (tek geçişte tüm koşullar), ardışık
  `limit` min'e iner. Sabit kural: `limit`, `sirala` üzerinden geriye taşınmaz.

## 12. Hata Stratejisi
Üç kapı, hepsi Türkçe ve açık: (a) kurulum hataları (bilinmeyen işleç, JSON parse,
sürüm, bilinmeyen stage) → `Pipeline::hata()`; (b) derleme hataları (fabrika
parametre doğrulama) → `derle()==false` + `hata()`; (c) koşu hataları →
`PipelineSonuc::hata`. Bozuk plan asla koşmaz; hatalı sonuç önbelleğe girmez.
JSON'da `{"surum":1}` opsiyonel; `1` dışı sürüm reddedilir; bilinmeyen KÖK alanlar
ileri uyumluluk için yok sayılır (bilinmeyen STAGE yok sayılMAZ).

## 13. Gelecek Uzantılar
Görsel node grafı (üçüncü temsil — aynı AST'ye derlenir), maliyet tabanlı optimizer
(predicate pushdown, projection pruning, dead-stage elim.), stage-içi paralellik +
SIMD, incremental yürütme (graf delta → etkilenen stage'ler), akış (stream) sonuç,
alt-pipeline/dallanma, AyarSistemi kayıtları (önbellek kapasitesi vb. — uygulama
katmanı bağlar), Lua/MCP/REST köprüsü.

## 14. Riskler
- Önbellek anahtarında graf ADRESİ var: yaşamı biten grafın adresi yeniden
  kullanılırsa ve sürüm+düğüm-üst-sınırı+imza da çakışırsa teorik yanlış isabet.
  Azaltıldı (`dugumUst` anahtarda) ama sıfır değil; kalıcı graf kimliği Faz 2 işi.
- Registry süreç-geneli tekil: aynı adla yeniden kayıt fabrikayı DEĞİŞTİRİR
  (plugin güncelleme özelliği, ama yanlışlıkla gölgeleme riski).
- `sirala` yalnız sayısal/metin karşılaştırır; Vec3d/dizi özellikler "eksik" sayılır.

## 15. Alternatif Tasarımlar (reddedilenler)
- LLVM-tarzı düğüm sınıf hiyerarşisi + visitor: bu ölçek için over-engineering;
  düz liste + çanta yeterli, genişleme registry'den.
- Lazy iterator zinciri (C++ ranges): graf bellekte, kümeler küçük; kazanç yok,
  karmaşıklık çok.
- Sorgu API'sini genişletmek: Sorgu tek-küme süzgeçtir; genislet/sec/topla gibi
  dönüşümler onu şişirirdi. GPE ayrı katman, Sorgu dokunulmadan kaldı.

## 16. Önerilen Tasarım
Yukarıdaki çekirdek: düz AST + tek registry + fabrika-doğrulamalı derleme +
imza-anahtarlı önbellek + tohum optimizer. Üç temsilden ikisi (fluent+JSON) aynı
planı üretir ve testle kilitlidir; üçüncüsü (görsel) aynı AST'ye derlenecek.

## JSON Şeması (sürüm 1)
```json
{"surum":1,
 "pipeline":[
  {"kaynak":"Delik"},
  {"govdede":42},
  {"suz":{"cap":{">=":6,"!=":12,"var":true,"aralik":[6,13]},
          "iliskili":{"iliski":"bagli","hedef":"Fillet","yon":0}}},
  {"suz":{"uretim_tipi":"delme"}},
  {"genislet":{"iliski":"bagli","hedef":"Yuz","yon":0}},
  {"sec":["cap","derinlik"]},
  {"sirala":{"anahtar":"cap","artan":true}},
  {"limit":10},
  {"say":{}},
  {"topla":{"anahtar":"cap","islem":"sum"}},
  {"pluginStageAdi":{"parametre":1}}
 ]}
```
İşleçler: `==` `!=` `>` `>=` `<` `<=` `var` `aralik`; skaler değer = eşitlik
kısayolu. `topla.islem`: `sum|min|max|ort`. Sonuç JSON'u:
`{"kimlikler":[...],"satirlar":[{...}],"skaler":X}` ya da `{"hata":"..."}`.

## 10 Faz — Şimdi / Sonra
| Vizyon fazı | Durum |
|---|---|
| 1 Mimari (RFC) | ŞİMDİ — bu doküman |
| 2 JSON dili | ŞİMDİ (çekirdek şema, sürüm 1) — ifade/değişken/dallanma SONRA |
| 3 Fluent C++ API | ŞİMDİ (çekirdek stage'ler + genel `asama()`) |
| 4 AST | ŞİMDİ (düz liste — bilinçli sade) |
| 5 Optimizer | TOHUM ŞİMDİ (suz-birleşme, limit-min, geçiş arayüzü) — geri kalanı SONRA |
| 6 Yürütme motoru | ŞİMDİ (ardışık) — paralel/incremental/iptal SONRA |
| 7 Plugin SDK | ŞİMDİ (registry + fabrika) — ABI/sandbox/izin SONRA |
| 8 Görsel editör | SONRA |
| 9 Test stratejisi | ŞİMDİ (birim; 10 test) — perf/stres/golden SONRA |
| 10 Üretim yapısı | ŞİMDİ (motor/zeka içinde; ayrı modül gerekirse SONRA) |