# Plugin + Makro Platformu — Native-Kalite Dinamik Genişleme

> **Vizyon:** Yeni komut / feature / workbench / araç / panel / geometri-op / dosya-format /
> CAM stratejisi / analiz eklemek için **tüm programı baştan derleyip dağıtmak zorunda kalmadan**;
> core sabit kalır, yeni yetenek **ayrı derlenir ve damla-bırak (drop-in)** eklenir.
>
> **İki yol, tek registry:**
> 1. **DLL plugin** — ayrı derlenir, **native hız** (derlenmiş kod), stable C-ABI sınırından core'a takılır.
> 2. **Lua makro** — derlemesiz, anında; sık yollarda native köprüye delege eder.
>
> Her ikisi de **aynı merkezi registry**'ye (Cekirdek) kaydolur → menü + toolbar + palet + kısayol +
> makro-görünürlük + olay bedavaya gelir. Bu, [[fikatia-mimari-ilke-makro-plugin-olay]] ilkesinin
> genişleme (extensibility) katmanına taşınmış hâlidir.

**Durum:** SALT TASARIM. Kod yok. Mevcut sistem incelendi; bu doküman mevcut `EklentiYonetici`,
`MakroMotor` ve `Cekirdek` registry'sinin üzerine **kararlı ABI katmanı** ekleyen bir mimari yol
haritasıdır.

---

## 1. Mevcut Durum — Ne Var, Ne Eksik

### 1.1 DLL eklenti sistemi (bugün)

| Bileşen | Dosya | Ne yapıyor |
|---|---|---|
| `Eklenti` arayüzü | `motor/eklenti/include/fiko/eklenti/eklenti_sdk.hpp:22` | Soyut C++ sınıf: `bilgi()/baslat()/kapat()/kareGuncelle()` |
| `EklentiBaglam` | `eklenti_sdk.hpp:17` | `{ Cekirdek&, Sahne& }` — **C++ referansları DLL sınırından geçiyor** |
| `FIKO_EKLENTI(SINIF)` | `eklenti_sdk.hpp:35` | `extern "C"` factory: `fikoEklentiApiSurum` / `fikoEklentiOlustur` / `fikoEklentiYokEt` |
| `EKLENTI_API_SURUM` | `eklenti_sdk.hpp:8` | `= 1`, `yukle()`'de **sert eşitlik** kontrolü |
| `EklentiYonetici` | `motor/eklenti/src/eklenti_yonetici.cpp` | `tara(dizin)` → `LoadLibraryW` + `GetProcAddress` + sürüm eşitliği + `baslat`; yaşam döngüsü `yukle→baslat`, `kaldir→kapat→yokEt→FreeLibrary`; aynı dosya-adı idempotent (çift kayıt/leak önler, `eklenti_yonetici.cpp:53`) |
| Örnek plugin | `uygulama/eklentiler/ornek_eklenti/ornek_eklenti.cpp` | `baslat()`'ta `cekirdek.menuler().ekle(...)` + `olaylar().abone<VarlikEklendi>(...)`; `kapat()`'ta `menuler().sil()` + `aboneIptal()` |
| UI paneli | `uygulama/fikocad/yardimci_penceler.cpp:75` | "Eklenti Yöneticisi" — "Dizini Tara", liste, `sonHata()`, kaldır |
| Sahiplik | `uygulama/fikocad/belge.hpp:46` | `EklentiYonetici` **her Belge'ye ait** (belge-scope) |

**Doğru olan taşlar:** `extern "C"` factory (isim-mangling'den kaçıyor), plugin kendi heap'inde
`new/delete` (yıkım export üzerinden — `eklenti_sdk.hpp:33` yorumu), sürüm alanı fikri, idempotent
tarama, temiz yaşam döngüsü, registry'ye native komutla **aynı yoldan** kayıt.

### 1.2 KRİTİK ABI kırılganlıkları (bugünkü sistemin gerçek sınırı)

Bugünkü sistem **yalnızca aynı derleyici + aynı flag'lerle** derlenen kendi DLL'lerimizde çalışır.
Gerçek "üçüncü taraf drop-in" için şu duvarlar var:

1. **C++ nesneler ABI sınırından geçiyor.** `EklentiBaglam{ Cekirdek&, Sahne& }` — plugin, `cekirdek.hpp`
   + `sahne.hpp` + tüm ECS başlıklarına derlenir. `Cekirdek`/`Sahne`/`MenuOge` düzeni, `std::function`
   /`std::string`/`std::vector` iç yerleşimi **derleyici sürümüne göre değişir**. Farklı MSVC/farklı STL
   ile derlenmiş bir DLL → sessiz bellek bozulması.
2. **`std::string`/`std::function` sahiplik heap sınırından geçiyor.** Plugin `MenuOge{ std::string, std::function }`
   üretip core'un `std::vector`'üne `push_back` ediyor → **çapraz-heap STL sahipliği**. Bugün çalışıyor
   çünkü tek toolchain; drop-in'de UB.
3. **Sert sürüm eşitliği** (`api != EKLENTI_API_SURUM` → red, `eklenti_yonetici.cpp:81`). Core'da **herhangi**
   bir değişiklik → sürüm artar → **eski tüm plugin'ler reddedilir**. İleri uyumluluk yok.
4. **Olaylar sabit `enum` + sabit dizi.** `OlayTuru` (`olay.hpp:13`) `SAYAC` ile biter; handler dizisi
   `OLAY_TURU_SAYISI` boyutlu. Plugin **yeni olay türü tanımlayamaz**.
5. **Genişleme noktaları sınırlı.** Plugin bugün pratikte yalnız komut ekleyip olay dinleyebiliyor.
   Feature / workbench / panel / araç / dosya-format / CAM stratejisi / analiz için **stable kayıt yüzeyi yok**
   (native modüller bunları doğrudan `Cekirdek` iç API'siyle kaydediyor — plugin'e açık değil).
6. **Hot-reload yok.** `kaldir()` var ama editör-döngüsü (dosya değişti → otomatik reload) yok; DLL kilidi
   (`LoadLibraryW`) yerinde-güncellemeyi bloklar.
7. **Güven/imza yok.** Herhangi bir `.dll` `tara()` ile yükleniyor — lisans/güncelleme sistemiyle tutarlı
   imza doğrulaması yok.

### 1.3 Lua makro motoru (bugün)

| Özellik | Dosya | Not |
|---|---|---|
| Motor | `motor/betik/src/makro_motor.cpp` | Lua 5.4, `luaL_newstate` + `luaL_openlibs`, **her Belge'ye ait** (`belge.hpp:45`) |
| API yüzeyi | `makro_motor.cpp:48` (`apiKur`) | `fiko.log/guncelle/geriAl/yinele`, `fiko.olay.dinle`, `fiko.sahne.*` (14 fn), `fiko.secim.*`, `fiko.komut.listesi/calistir`, `fiko.workbench.*`, `fiko.ui.*`, `fiko.ayar.*`, `fiko.cam.*` (17 fn) |
| Olay köprüsü | `makro_motor.cpp:157` (`olayKopruleriKur`) | ~30 olay türü Lua dinleyicilerine köprüleniyor (`koprule<Olay>`) |
| Komut çağırma | `lua_api_diger.cpp:32` (`l_komutCalistir`) | **Merkezi dispatch**'ten geçer (`cekirdek_.komutCalistir(o,"makro")`) → lisans + audit; bypass yok |
| Undo uyumu | — | Sahne mutasyonları `Islem`/`KomutYigini` yolundan (undo/redo uyumlu) |
| Çalıştırma | `dosyaCalistir` / `satirCalistir` | Makro Konsolu paneli (`yardimci_penceler.cpp:18`) |

**Eksikler:**
- Makro **yeni komut tanımlayamaz** — `fiko.komut.tanimla(...)` yok. Makro sadece var olanları çağırıyor.
  (Vizyon: "makro yeni komut yazınca registry'ye kaydolsun" → bu yok.)
- **Native köprü genelleştirilmemiş** — ağır iş için Lua'dan native fonksiyona delege var (`fiko.cam.hesapla`
  vb.) ama plugin'lerin sağladığı native fonksiyonları Lua'ya açan genel bir köprü yok.
- Vanilla Lua 5.4 (JIT yok). Sıcak makrolar için LuaJIT opsiyonu değerlendirilmeli.
- Makro sahiplik belge-scope; uygulama-genel (persistent) makro/komut kaydı yok.

### 1.4 Merkezi registry (Cekirdek) — tek gerçek kaynak

`motor/cekirdek/include/fiko/cekirdek/cekirdek.hpp` + `kayit.hpp`:

| Registry | Öğe tipi | Erişim |
|---|---|---|
| `menuler()` | `MenuOge{grup,ad,simge,sira,calistir,etkinMi,workbench}` | `MenuKaydi::ekle/sil/hepsi` |
| `paneller()` | `Panel{kimlik,baslik,sira,ciz,varsayilanAcik}` | `PanelKaydi::ekle/bul/hepsi` |
| `araclar()` | `Arac{kimlik,ad,etkinlestir,pasiflestir}` | `AracKaydi::ekle/etkinlestir/aktif` |
| `agac()` | `AgacDugum` sağlayıcı (`function<void(Cekirdek&,vector<AgacDugum>&)>`) | `AgacSaglayiciKaydi::ekle/topla` |
| `workbenchler()` | `WorkbenchOge{kimlik,ad,simge,giris,cikis}` | `WorkbenchKaydi::ekle/aktifAyarla/bul` |
| `olaylar()` | Tipli pub/sub + halka tampon | `OlayGunlugu::abone<Olay>/aboneIptal/yayinla` |
| `komutlar()` | Undo/redo yığını | `KomutYigini` |
| `gorevler()` | Arka-plan iş | `GorevSistemi` |
| `recompute()` | Feature DAG | `RecomputeMotor` |
| `moduller` | Statik modül dikişi | `modulEkle`/`moduleriKur`, `Modul` arayüzü (`kayit.hpp:120`) |

**Tek dispatch noktası:** `Cekirdek::komutCalistir(oge, kaynak)` (`cekirdek.hpp:40`) — TÜM komut
çalıştırma (menü/palet/kısayol/jest/makro/**plugin**) buradan geçer: **lisans kapısı** (`lisansKapisiAyarla`,
`cekirdek.hpp:63`) → `etkinMi` → çalıştır → **`KomutCalisti`** audit olayı yayınla. Bu, plugin+makro
platformunun **lisans/telemetri omurgası**; yeni ABI bunu KORUR ve tek geçiş kapısı yapar.

**Feature katalog deseni:** `motor/parca/include/fiko/parca/feature_registry.hpp` — `FeatureTanim`
statik vektörü, **veri-odaklı param şeması** (`ParamTip::Mesafe/Bayrak/Secim`, koşullu görünürlük
lambda'ları). GSD aynı deseni (`gsd_registry`) kullanır. Plugin feature'ları **bu deseni** genişletir.

---

## 2. Hedef Mimari — Katmanlar

```
┌──────────────────────────────────────────────────────────────────────┐
│  ÜÇÜNCÜ TARAF / BİZ  (ayrı derlenen genişletme)                        │
│                                                                        │
│   DLL Plugin (native hız)              Lua Makro (derlemesiz, anında)  │
│   fiko_sdk.h + fiko_sdk.hpp'ye         fiko.* API                      │
│   derlenir                                                             │
└───────────────┬──────────────────────────────┬───────────────────────┘
                │  C-ABI (stable)               │  Lua C-API köprüsü
                ▼                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  KÖPRÜ KATMANI  (motor/eklenti + motor/betik — core'a ait, kararlı)   │
│                                                                        │
│  ● HostApi (C fonksiyon-işaretçi tablosu)  ← plugin buna çağrı yapar   │
│  ● Marshalling: C-POD ↔ C++ registry öğeleri (MenuOge/Panel/...)       │
│  ● Trampolin: C callback (ctx*+fn) ↔ std::function<void(Cekirdek&)>    │
│  ● Genişleme-noktası kayıt yüzeyleri (komut/feature/workbench/...)     │
│  ● Sürüm/capability negotiation + imza doğrulama + hot-reload          │
└───────────────┬──────────────────────────────────────────────────────┘
                │  doğrudan C++ (aynı binary)
                ▼
┌──────────────────────────────────────────────────────────────────────┐
│  ÇEKİRDEK REGISTRY  (Cekirdek) — TEK GERÇEK KAYNAK                     │
│  menuler / paneller / araclar / agac / workbenchler / olaylar /        │
│  komutlar(undo) / recompute / komutCalistir(lisans+audit)             │
└──────────────────────────────────────────────────────────────────────┘
```

**Anahtar ilke:** ABI sınırı **saf C**'dir. Plugin yazarı yine **C++ yazar** (ergonomik `fiko_sdk.hpp`
inline sarmalayıcı), ama binary sınırından **yalnız C tipleri** (POD struct, `const char*`, opak handle,
fonksiyon işaretçisi) geçer. Böylece derleyici/STL/sürüm farkı ABI'yi kırmaz.

---

## 3. Stable SDK / ABI Tasarımı

### 3.1 Neden C-ABI (C++ değil)

C++ ABI kırılgan: vtable düzeni, isim mangling, `std::string`/`std::function`/`std::vector` iç yerleşimi,
exception unwind tablosu — derleyici sürümüne bağlı. C-ABI kararlı: `extern "C"`, POD, fonksiyon işaretçisi.
Bu yüzden sınır C, **kolaylık katmanı** (plugin-tarafı, `#include` edilen inline header) C++.

### 3.2 SDK dosya seti

Yeni dizin: `motor/eklenti/sdk/` — plugin'lerin derleneceği **tek başlık seti** (core iç başlıklarından
bağımsız, sadece bunlar dağıtılır):

| Dosya | İçerik | Kim kullanır |
|---|---|---|
| `fiko_abi.h` | Saf C: ABI sürümü, POD struct'lar, `FikoHostApi` fonksiyon-tablosu, handle tipleri, callback imzaları | Hem core hem plugin |
| `fiko_sdk.hpp` | C++ inline sarmalayıcı: `HostApi` üzerinden ergonomik `Komut/Feature/Workbench/Panel` kayıt sınıfları, RAII abonelik | **Yalnız plugin** (inline, header-only) |
| `fiko_plugin.h` | `FIKO_PLUGIN(...)` makrosu + zorunlu export imzaları (`fikoPluginTanim`/`fikoPluginBaslat`/`fikoPluginKapat`) | Plugin |

Plugin **yalnız bu 3 dosyaya** derlenir; `cekirdek.hpp`/`sahne.hpp`/`kayit.hpp`/STL-sahiplik **görmez**.

### 3.3 ABI sürüm modeli — semantik, sert-eşitlik DEĞİL

Bugünkü `api != EKLENTI_API_SURUM` (sert red) yerine **major.minor** + capability:

```
FIKO_ABI_MAJOR   // ABI şekli kırıldığında artar (struct düzeni/imza değişimi) — ESKİ PLUGIN REDDEDİLİR
FIKO_ABI_MINOR   // Yalnız EK yapıldığında artar (yeni HostApi fn tablonun SONUNA) — eski plugin ÇALIŞIR
```

Yükleme kuralı (bugünkü `yukle()`'nin genişletilmişi, `eklenti_yonetici.cpp:80`):
- Plugin'in beklediği `major != host major` → **net sürüm kapısı** (red + Türkçe mesaj: "Eklenti bu
  sürümle uyumsuz — yeniden derlenmeli").
- `plugin.minor <= host.minor` → yükle. Host yeni fonksiyonları tablonun **sonuna** ekler; eski plugin
  onları çağırmaz → forward compat.
- **Capability sorgusu:** plugin `host->ozellikVar("feature.loft")` ile çalışma-zamanı yetenek yoklar;
  eksikse zarifçe geriler. Böylece core büyüdükçe eski plugin çalışmaya devam eder.

### 3.4 HostApi — C fonksiyon tablosu (ABI çekirdeği)

Plugin, core'a **doğrudan** dokunmaz; `baslat()`'a verilen `const FikoHostApi*` üzerinden her şeyi yapar.
`FikoHostApi`, **fonksiyon işaretçisi tablosu**dur (COM/Vulkan `vkGetInstanceProcAddr` deseni). Yerleşimi
ABI-major'a bağlı; yeni girdiler **sona** eklenir.

Kavramsal içerik (imzalar C):

```
struct FikoHostApi {
  uint32_t abiMajor, abiMinor;

  // — Bağlam handle'ları (opak; plugin içini görmez) —
  FikoCtx      ctx;        // Cekirdek'i sarar (opak)
  FikoSahne    sahne;      // Sahne'yi sarar (opak)

  // — Genişleme kaydı (her biri bir "genişleme noktası", §4) —
  FikoKomutId  (*komutKaydet)(FikoCtx, const FikoKomutTanim*);
  void         (*komutSil)(FikoCtx, FikoKomutId);
  FikoFeatureId(*featureKaydet)(FikoCtx, const FikoFeatureTanim*);
  FikoWbId     (*workbenchKaydet)(FikoCtx, const FikoWorkbenchTanim*);
  FikoPanelId  (*panelKaydet)(FikoCtx, const FikoPanelTanim*);
  FikoAracId   (*aracKaydet)(FikoCtx, const FikoAracTanim*);
  FikoAgacId   (*agacSaglayiciKaydet)(FikoCtx, FikoAgacSaglayiciFn, void* kullanici);
  FikoFormatId (*dosyaFormatKaydet)(FikoCtx, const FikoDosyaFormatTanim*);
  FikoCamId    (*camStratejiKaydet)(FikoCtx, const FikoCamStratejiTanim*);
  FikoAnalizId (*analizKaydet)(FikoCtx, const FikoAnalizTanim*);

  // — Olaylar (§3.6: sabit türler + plugin-tanımlı isimli olaylar) —
  FikoAbone    (*olayDinle)(FikoCtx, uint32_t olayTuru, FikoOlayFn, void* kullanici);
  FikoAbone    (*isimliOlayDinle)(FikoCtx, const char* ad, FikoOlayFn, void* kullanici);
  void         (*aboneIptal)(FikoCtx, FikoAbone);
  void         (*isimliOlayYayinla)(FikoCtx, const char* ad, const void* veri, size_t n);

  // — Komut çağırma (TEK dispatch — lisans+audit korunur) —
  int          (*komutCalistir)(FikoCtx, const char* ad, const char* kaynak);

  // — Sahne mutasyonu (undo-uyumlu; hepsi Islem yolundan) —
  FikoVarlik   (*dugumEkle)(FikoSahne, int tip);
  void         (*dugumSil)(FikoSahne, FikoVarlik);
  void         (*geriAl)(FikoCtx);  void (*yinele)(FikoCtx);
  // ... konum/ad/renk/gorunur/parametre/boolean/step (mevcut Lua yüzeyinin C dengi)

  // — Yardımcı —
  int          (*ozellikVar)(FikoCtx, const char* yetenek);  // capability yoklama
  void         (*gunluk)(int seviye, const char* mesaj);      // core log'una yaz
  void*        (*bellekAyir)(size_t);  void (*bellekBirak)(void*);  // çapraz-heap güvenli
};
```

**Çapraz-heap kuralı korunur:** Plugin, core'a **string/callback sahipliği aktarmaz**. `komutKaydet`,
`FikoKomutTanim`'daki `const char*` alanları **kopyalar** (marshalling katmanı `std::string`'e çevirir);
callback'ler `{ FikoKomutFn, void* ctx }` çiftidir — core bunları trampoline `std::function`'a sarar.
Böylece core-tarafı STL, plugin-tarafı STL'e asla dokunmaz.

### 3.5 Callback trampoline (C fn ↔ std::function)

`MenuOge::calistir` = `std::function<void(Cekirdek&)>`. Plugin C fonksiyonu verir:
`void (*)(FikoHostApi*, void* kullanici)`. Köprü katmanı:

```
// Kaydet anında marshalling (motor/eklenti/src/koprubridge.cpp — YENİ):
MenuOge oge;
oge.grup = tanim->grup;               // const char* → std::string KOPYA
oge.ad   = tanim->ad;
oge.calistir = [fn = tanim->calistir, // C fn ptr
                ku = tanim->kullanici, // opak ctx
                api = hostApiPtr](Cekirdek&) {
  fn(api, ku);                        // trampoline: C++ std::function içinde C fn çağır
};
cekirdek.menuler().ekle(std::move(oge));
```

Sonuç: plugin native komutla **bit-bit aynı** yoldan menü/toolbar/palet/kısayola girer; `komutCalistir`
merkezî dispatch'i onları da lisans+audit'ten geçirir (§1.4).

### 3.6 Plugin-tanımlı olaylar (sabit enum sınırını aşma)

Sorun (§1.2/4): `OlayTuru` sabit; plugin yeni tür ekleyemez. Çözüm — **iki kanal**:
- **Sabit türler** (mevcut ~60 olay): plugin `olayDinle(ctx, FIKO_OLAY_VARLIK_EKLENDI, ...)` ile dinler.
  ABI'de olay türleri **sabit sayısal kimlik** olarak dondurulur (`fiko_abi.h`); yeni core olayı **sona**
  eklenir → sayısal kararlılık (bugünkü `olay.hpp` "SONA ekle" kuralıyla birebir).
- **İsimli olaylar** (plugin/makro icadı): `isimliOlayYayinla(ctx, "benim.olay", veri, n)` /
  `isimliOlayDinle(ctx, "benim.olay", ...)`. Core tarafında `enum` gerektirmeyen **string-anahtarlı**
  ikinci bir pub/sub (küçük `unordered_map<string, vector<Abonelik>>`). Böylece plugin A, plugin B'ye
  olay yayınlar — core değişmeden. (OlayGunlugu halka-tamponuna `Diger` türü + özet olarak da düşer →
  denetçi görünür.)

### 3.7 Plugin giriş noktası (yeni `FIKO_PLUGIN`)

Bugünkü `FIKO_EKLENTI(SINIF)` (C++ sınıf + `Cekirdek&` sızıntısı) yerine C-imzalı üçlü:

```c
// fiko_plugin.h:
#define FIKO_PLUGIN(TANIM_FN, BASLAT_FN, KAPAT_FN)                       \
  extern "C" FIKO_EXPORT const FikoPluginTanim* fikoPluginTanim(void)    \
      { return TANIM_FN(); }                                             \
  extern "C" FIKO_EXPORT int fikoPluginBaslat(const FikoHostApi* h)      \
      { return BASLAT_FN(h); }                                           \
  extern "C" FIKO_EXPORT void fikoPluginKapat(const FikoHostApi* h)      \
      { KAPAT_FN(h); }
```

`FikoPluginTanim` = POD manifest (`ad`, `surum`, `abiMajor/Minor` beklenen, `yazar`, `imzaVar`).
`EklentiYonetici::yukle` bu üçlüyü + ABI major/minor'u doğrular; `fikoPluginBaslat`'a **HostApi tablosu**
verir (bugünkü `baslat(EklentiBaglam&)` yerine — C++ referansı geçmez).

> **Geriye uyum:** Eski `FIKO_EKLENTI`/`Eklenti` yolu **shim** olarak korunabilir (v1 ABI). `EklentiYonetici`
> önce `fikoPluginTanim` (v2) arar; yoksa `fikoEklentiOlustur` (v1) dener. Böylece mevcut `ornek_eklenti`
> kırılmaz; yeni plugin'ler stable C-ABI'yi kullanır.

---

## 4. Genişleme Noktaları Kataloğu

Her genişleme noktası: **(a)** `fiko_abi.h`'de POD `*Tanim` struct'ı, **(b)** `FikoHostApi`'de
`...Kaydet` fn'i, **(c)** köprüde marshalling → mevcut `Cekirdek` registry'sine ekleme, **(d)**
`fiko_sdk.hpp`'de ergonomik C++ sarmalayıcı. Registry tek kaynak → menü+toolbar+palet+makro+olay bedava.

| # | Genişleme noktası | ABI tanımı (POD) | Hedef registry (mevcut) | Not |
|---|---|---|---|---|
| 1 | **Komut** | `FikoKomutTanim{grup,ad,simge,sira,workbench,calistir,kullanici,etkinMi}` | `menuler()` (`kayit.hpp:36`) | Callback trampoline (§3.5); `komutCalistir` lisans+audit |
| 2 | **Feature / geometri-op** | `FikoFeatureTanim{id,ad,simge,malzemeEkler,param[]}` (param = `FikoParam{ad,tip,var,min,max,adim,birim,secenek[],kosul}`) | `parca` feature_registry deseni + `recompute()` DAG | Web `FikoKomutIcerik` param şemasının C dengi; her feature kendi penceresi (part_design deseni) |
| 3 | **Workbench** | `FikoWorkbenchTanim{kimlik,ad,simge,giris,cikis,kullanici}` | `workbenchler()` (`workbench.hpp`) | giris/cikis C callback → trampoline |
| 4 | **Panel (FikoUi)** | `FikoPanelTanim{kimlik,baslik,sira,ciz,kullanici,varsayilanAcik}` | `paneller()` (`kayit.hpp:13`) | `ciz` her kare; ImGui çağrıları **HostApi UI alt-tablosu** üzerinden (ABI-güvenli ImGui sarmalayıcı, §4.1) |
| 5 | **Araç (viewport etkileşim)** | `FikoAracTanim{kimlik,ad,etkinlestir,pasiflestir,kullanici}` | `araclar()` (`kayit.hpp:93`) | Aktif araç tıklama/hover dispatch'ine katılır |
| 6 | **Ürün ağacı sağlayıcı** | `FikoAgacSaglayiciFn(FikoHostApi*, FikoAgacYazici, void*)` | `agac()` (`kayit.hpp:80`) | `FikoAgacYazici` = ağaç düğümü ekleme C API'si (AgacDugum'un opak yazıcısı) |
| 7 | **Olay dinleyici** | `olayDinle` / `isimliOlayDinle` | `olaylar()` (`olay.hpp:464`) | §3.6 iki kanal |
| 8 | **Dosya format (import/export)** | `FikoDosyaFormatTanim{uzanti,ad,yon(import/export),oku,yaz,kullanici}` | YENİ `DosyaFormatKaydi` (Cekirdek'e eklenecek küçük registry) | STEP/STL yanına drop-in yeni format; `sahne`'ye undo-uyumlu import |
| 9 | **CAM stratejisi** | `FikoCamStratejiTanim{kimlik,ad,param[],hesapla}` | `cam::CamSistemi` strateji kaydı | `hesapla`: geometri+param → takım yolu hamleleri (C dizi); mevcut 3D strateji deseni |
| 10 | **Analiz** | `FikoAnalizTanim{tip,ad,hesapla,gorsellestir}` | `analiz::AnalizSistemi` | draft/undercut/kalınlık yanına yeni analiz; GPU compute opsiyonel |
| 11 | **Tessellation / mesher** | `FikoTessTanim{ad,uygula}` | `recompute`/sahne mesh üretimi | B-rep → mesh alternatif sağlayıcı (ileri dalga) |

### 4.1 Panel/UI ABI güvenliği

ImGui doğrudan plugin'e açılırsa ImGui sürüm/derleme uyumu ABI kırar. Çözüm: **HostApi UI alt-tablosu**
— core, plugin'e sınırlı, stable bir ImGui-benzeri C çizim API'si sunar (`uiMetin/uiButon/uiKaydir/
uiAyirici/uiGirdiMetin...`). Plugin bunları çağırır; core kendi ImGui'sine yönlendirir. Böylece plugin
ImGui'ye **derlenmez**, ImGui yükseltmesi plugin'i kırmaz. (İleri dalga; ilk sürümde panel = salt-metin +
temel widget seti yeterli.)

---

## 5. Lua Makro — Native-Yakın + Komut Tanımlama

### 5.1 Makro yeni komut tanımlar (kritik boşluğu kapat)

Bugün makro sadece var olan komutu çağırıyor (`fiko.komut.calistir`). Eklenecek:

```lua
fiko.komut.tanimla({
  grup = "Benim", ad = "Delikleri Say", simge = "#", workbench = "part",
  calistir = function() ... end,          -- Lua closure
  etkinMi  = function() return true end,  -- opsiyonel
})
```

Köprü (`lua_api_diger.cpp` yanına): `l_komutTanimla` Lua closure'ı `luaL_ref`'le registry'de tutar,
`MenuOge{ calistir = [ref](Cekirdek&){ lua closure'ı pcall } }` üretip `cekirdek_.menuler().ekle` eder.
Sonuç: **makro-tanımlı komut**, menü+toolbar+palet+kısayolda native komutla aynı; `komutCalistir` onu da
lisans+audit'ten geçirir. `fiko.komut.sil(grup, ad)` ile geri alınır (makro yeniden-yüklemede idempotent).

Aynı desen **panel/araç/olay** için genişletilir: `fiko.panel.tanimla`, `fiko.arac.tanimla`,
`fiko.olay.yayinla(ad, veri)` (isimli olay §3.6).

### 5.2 Native köprü — ağır işi delege et

İlke: **karar/akış Lua'da, sıcak döngü native'de.** Lua per-eleman döngü yazmaz; `fiko.sahne.boolean`,
`fiko.cam.hesapla`, `fiko.sahne.stepIceAktar` gibi **native fonksiyona toplu** delege eder (mevcut desen —
`makro_motor.cpp:118` `fiko.cam.hesapla` bunu zaten yapıyor). Genişletme: plugin'in sağladığı native
fonksiyonları da Lua'ya aç — `fiko.plugin.<ad>(...)` genel köprüsü (HostApi'ye kayıtlı plugin fn'leri
Lua tablosuna yansıtılır). Böylece "ağır iş native, tetik Lua" her plugin için otomatik.

### 5.3 LuaJIT opsiyonu (performans)

Vanilla Lua 5.4 → yorumlayıcı. Sık/sıcak makrolar (per-kare `fiko.guncelle` callback'leri,
geometri döngüleri) için **LuaJIT** değerlendirilmeli:
- **Artı:** 5-50× hız; FFI ile native köprü neredeyse sıfır-maliyet.
- **Eksi:** LuaJIT Lua 5.1 tabanlı (5.4 sözdizim farkı); Windows/x64 destekli; ek bağımlılık.
- **Karar:** MakroMotor'u **motor arkası soyut** tut (`MakroMotor` iç `lua_State*`'i gizli). İlk sürüm
  vanilla 5.4 (mevcut `ucuncu_taraf/lua`); LuaJIT bir **derleme-zamanı bayrağıyla** takas edilebilir
  bırakılır. Sıcak-yol profillenene kadar erken optimize etme (bkz. §7 performans).

### 5.4 Makro → paket (kalıcı komut)

Makro şu an belge-scope. Uygulama-genel kalıcı makro için: `makrolar/` dizinindeki `.lua` dosyaları
açılışta taranır; içinde `fiko.komut.tanimla` çağıranlar komutlarını her belgede kaydeder. Manifest'li
makro (§6.2) "makro paketi" olarak dağıtılabilir — DLL derlemeden yeni komut seti.

---

## 6. Drop-in Akışı + Paket Formatı

### 6.1 İki yolun karşılaştırması

| | **DLL Plugin** | **Lua Makro** |
|---|---|---|
| Hız | Native (derlenmiş) | Yorumlanmış (LuaJIT ile native-yakın) |
| Derleme | Gerekir (SDK ile, core değil) | Yok — anında |
| Kullanım | Ağır geometri/CAM/analiz, yeni feature | Hızlı otomasyon, komut zinciri, UI tetik |
| Dağıtım | `.fikoplug` paketi (manifest+DLL+kaynak) | `.lua` dosyası / `.fikomac` paketi |
| Güven | İmzalı (§6.3) | Sandbox + opsiyonel imza |
| Reload | Hot-reload (§6.4) | Anında yeniden-çalıştır |

**"Derlemeden yeni özellik":** kullanıcı yeni komut isterse → makro yaz (anında). Native hız gerekiyorsa
→ SDK ile DLL derle (core değil, küçük+ayrı) → `eklentiler/` dizinine bırak. **Core her iki durumda da
sabit kalır.**

### 6.2 Plugin paket formatı — `.fikoplug`

Zip konteyner:
```
benim_eklentim.fikoplug
├── manifest.json      # ad, surum, abiMajor/Minor, yazar, giris-dll, izinler, imza
├── benim_eklentim.dll # SDK'ya derlenmiş
├── kaynaklar/         # simge/PNG/SVG, .lua yardımcıları, shader (opsiyonel)
└── imza.sig           # manifest+dll hash imzası (§6.3)
```
`EklentiYonetici::tara`, ham `.dll` yerine `.fikoplug`'ı da açar: manifest → ABI/imza doğrula → DLL yükle.
Manifest `izinler` alanı (bkz. §6.5) plugin'in hangi HostApi alt-kümesine erişebileceğini bildirir.

### 6.3 İmza + güven (lisans/güncelleme ile tutarlı)

[[fikatia-merkezi-olay-komut]] / merkezi lisans sistemiyle uyumlu:
- Her `.fikoplug` **imzalı** (manifest+DLL hash → bizim/geliştirici anahtarıyla imza).
- Yükleme politikası (merkezi ayardan, `ayar` sistemi): `SadeceImzali` (varsayılan üretim) /
  `ImzasizUyar` (geliştirme) / `Serbest`.
- İmzalı plugin ↔ lisans kapısı: `lisansKapisiAyarla` (§1.4) plugin komutlarını da gate'ler → lisanssız
  plugin komutu **çalışmaz** ama kayıt görünür (denetimde iz kalır).
- Güncelleme: plugin sürümü merkezi sunucuyla eşlenebilir (opsiyonel — mevcut lisans altyapısına takılır).

### 6.4 Hot-reload (çalışırken ekle/çıkar)

- **Dosya izleme:** `eklentiler/` dizini watch (Windows `ReadDirectoryChangesW`). `.fikoplug`/`.dll`
  değişti → ilgili plugin `kaldir()` (mevcut yaşam döngüsü: `kapat→yokEt→FreeLibrary`, `eklenti_yonetici.cpp:110`)
  → yeni sürüm `yukle`.
- **DLL kilidi:** `LoadLibraryW` DLL'i kilitler → yerinde-güncelleme bloklanır. Çözüm: DLL'i **gölge-kopya**
  ile yükle (temp'e kopyala, kopyayı yükle) → orijinal serbest kalır, güncellenebilir.
- **Durum güvenliği:** kaldır, plugin'in tüm registry kayıtlarını (komut/panel/abonelik) sökmeli. Bunun
  için `EklentiKayit` her plugin'in ürettiği kayıt-id'lerini (`FikoKomutId`, `FikoAbone`...) izler; kaldırma
  hepsini otomatik geri alır (**scope-tracking** — plugin `kapat()` yazmayı unutsa da köprü temizler).
- **Reload sırasında undo yığını:** plugin feature'ı içeren belge açıkken plugin kaldırılırsa → o feature
  "bilinmeyen tip" placeholder'a düşer (mevcut boş-mesh sentinel deseniyle tutarlı, [[fikatia-hiyerarsik-import]]).

### 6.5 Çökme izolasyonu

Native DLL, core adres alanında çalışır → kötü plugin teorik olarak core'u çökertebilir. Azaltma
(tamamen izole etmek ayrı süreç gerektirir — ileri dalga):
- **SEH sarmalama:** plugin çağrıları (`baslat`/`kareGuncelle`/komut trampoline) `__try/__except` içinde;
  erişim ihlali → plugin devre-dışı + Türkçe uyarı, core yaşar. (Mevcut çökme handler + `g_sonAdim`
  faz-izleyici altyapısıyla tutarlı, [[fikatia-dangling-lambda-cokme]].)
- **İzin kısıtı:** manifest `izinler` → HostApi alt-kümesi (ör. yalnız "komut+olay", "sahne-yaz" yok).
  Köprü, izinsiz fn'i `nullptr` bırakır → plugin capability yoklamayla geriler.
- **Kaynak kotası:** per-plugin bellek/süre telemetrisi (KomutCalisti audit'e benzer) — aşırı kullanan
  plugin işaretlenir.
- **İleri dalga (tam izolasyon):** güvenilmeyen plugin'i ayrı süreçte çalıştır (mevcut süreçler-arası
  IPC merkezi komut altyapısı, [[fikatia-merkezi-surec-yoneticisi]] / commit 446335d) — plugin çökse core
  yaşar. Performans maliyeti (IPC) yüzünden yalnız güvenilmeyen/deneysel plugin'ler için.

---

## 7. Güvenlik / Sürüm / Performans — Özet Kararlar

| Konu | Karar |
|---|---|
| **ABI sınırı** | Saf C (POD + fn-tablosu); C++ kolaylık katmanı plugin-tarafı inline `fiko_sdk.hpp` |
| **Sürüm** | major (kır) + minor (ek, sona) + runtime capability yoklama; sert-eşitlik DEĞİL |
| **Çapraz-heap** | String kopyalanır, callback = {fn, ctx} trampoline; STL sahipliği sınırdan geçmez; `bellekAyir/Birak` HostApi'de |
| **Olaylar** | Sabit türler (sayısal, sona-ekle) + isimli string-anahtarlı kanal (plugin-tanımlı) |
| **Güven** | İmzalı `.fikoplug` + lisans kapısı + izin manifesti |
| **Hot-reload** | Gölge-kopya DLL + dosya-izleme + scope-tracking otomatik söküm |
| **Çökme** | SEH sarmalama + izin kısıtı; tam izolasyon = ayrı süreç (ileri) |
| **Yükleme perf.** | **Lazy** — plugin manifest'i hemen okunur ama DLL yalnız ilk kullanımda/etkinleştirmede yüklenir; tarama arka-plan görevi (`gorevler()`) |
| **Makro perf.** | Vanilla Lua 5.4 → soyut arka-uç; LuaJIT derleme-bayrağı takası; sıcak yol profillenene kadar erken optimize etme |
| **Native hız** | DLL = derlenmiş kod → native; ağır iş HostApi native fn'lerine delege; sınır-geçişi minimum (toplu API) |

---

## 8. DALGA Planı

Her dalga bağımsız derlenip test edilebilir; önceki dalgayı kırmaz. Mevcut `EklentiYonetici`/`MakroMotor`
korunur, üzerine inşa edilir.

### Dalga 1 — Stable SDK + C-ABI çekirdek (temel)
- `motor/eklenti/sdk/`: `fiko_abi.h` (POD'lar, `FikoHostApi` v2-major.minor, komut+olay alt-kümesi),
  `fiko_sdk.hpp` (C++ sarmalayıcı), `fiko_plugin.h` (`FIKO_PLUGIN`).
- Köprü: `motor/eklenti/src/host_api.cpp` (HostApi tablosunu doldur — komutKaydet/olayDinle/komutCalistir
  marshalling + trampoline).
- `EklentiYonetici::yukle` v2 yolu (`fikoPluginTanim`/`fikoPluginBaslat`) + v1 shim (`ornek_eklenti` çalışır).
- ABI sürüm negotiation + capability.
- **Çıktı:** stable C-ABI ile komut ekleyen örnek plugin drop-in çalışır (native hız, core değişmeden).

### Dalga 2 — Genişleme noktaları (komut → feature → workbench → panel → araç → ağaç)
- Her nokta için `*Tanim` + `...Kaydet` + marshalling (§4 katalog sırasıyla).
- Feature: `parca` feature_registry deseninin ABI dengi (veri-odaklı param → `recompute` DAG).
- Panel: HostApi UI alt-tablosu (§4.1, ilk sürüm temel widget).
- **Çıktı:** plugin yeni feature+workbench+panel ekler; ürün ağacında+menüde native gibi görünür.

### Dalga 3 — Lua genişletme (makro yeni komut tanımlar)
- `fiko.komut.tanimla/sil`, `fiko.panel.tanimla`, `fiko.arac.tanimla`, `fiko.olay.yayinla` (isimli).
- Genel native köprü: plugin fn'leri → `fiko.plugin.*` Lua yansıması.
- `makrolar/` açılış taraması + kalıcı makro-komut.
- **Çıktı:** derlemesiz yeni komut (makro) menü+palet+kısayolda; makro↔plugin köprüsü.

### Dalga 4 — İsimli olaylar + dosya-format/CAM/analiz genişleme
- String-anahtarlı pub/sub (§3.6); plugin↔plugin olay.
- Dosya-format (yeni import/export drop-in), CAM stratejisi, analiz genişleme noktaları.
- **Çıktı:** üçüncü taraf yeni dosya formatı / CAM stratejisi / analiz ekler.

### Dalga 5 — Hot-reload + paket + imza + güvenlik
- Gölge-kopya DLL + dosya-izleme + scope-tracking otomatik söküm.
- `.fikoplug` paket formatı (manifest+DLL+kaynak+imza) — Eklenti Yöneticisi paneli paketi açar/gösterir.
- İmza doğrulama + lisans kapısı + izin manifesti + SEH sarmalama.
- **Çıktı:** çalışırken plugin ekle/çıkar/güncelle; imzalı-güvenli dağıtım; kötü plugin core'u çökertmez.

### Dalga 6 — İleri (opsiyonel)
- LuaJIT arka-uç takası (profil sonrası).
- HostApi UI alt-tablosu tam ImGui-benzeri set.
- Ayrı-süreç plugin izolasyonu (güvenilmeyen plugin, IPC üzerinden).
- Plugin pazar/güncelleme sunucu entegrasyonu (merkezi lisans altyapısı).

---

## 9. Somut Dosya:Satır Referansları (uygulama için giriş noktaları)

| Ne | Dosya:satır | Aksiyon |
|---|---|---|
| Plugin arayüzü (v1) | `motor/eklenti/include/fiko/eklenti/eklenti_sdk.hpp:22,35` | v1 korunur (shim); v2 `sdk/` altında yeni |
| Plugin yükleyici | `motor/eklenti/src/eklenti_yonetici.cpp:49,80,110` | `yukle`'ye v2 yolu + ABI negotiation + hot-reload |
| Plugin kayıt struct | `eklenti_yonetici.hpp:9` (`EklentiKayit`) | Kayıt-id izleme (scope-tracking) alanları ekle |
| Merkezi registry | `motor/cekirdek/include/fiko/cekirdek/cekirdek.hpp:19-117` | Hedef — değişmeden kalır; HostApi buna köprü |
| Komut dispatch (lisans+audit) | `cekirdek.hpp:40` (`komutCalistir`) | Plugin+makro komutları buradan geçer (korunur) |
| Lisans kapısı | `cekirdek.hpp:63` (`lisansKapisiAyarla`) | Plugin komutlarını gate'le (§6.3) |
| Registry öğe tipleri | `motor/cekirdek/include/fiko/cekirdek/kayit.hpp:13-128` | Her `*Tanim` bunlara marshal olur |
| Workbench registry | `motor/cekirdek/include/fiko/cekirdek/workbench.hpp` | `FikoWorkbenchTanim` hedefi |
| Olay sistemi | `motor/cekirdek/include/fiko/cekirdek/olay.hpp:464` (`OlayGunlugu`) | Sabit kanal; §3.6 isimli kanal EKLENİR |
| Olay türleri | `olay.hpp:13` (`OlayTuru`) | ABI'de sayısal kimlik dondur; yeni tür SONA (mevcut kural) |
| Makro motoru | `motor/betik/src/makro_motor.cpp:48` (`apiKur`) | `fiko.komut.tanimla` + genel plugin köprüsü ekle |
| Makro komut çağırma | `motor/betik/src/lua_api_diger.cpp:32` (`l_komutCalistir`) | Yanına `l_komutTanimla` |
| Makro API başlığı | `motor/betik/include/fiko/betik/makro_motor.hpp:64` | Yeni `l_*` bildirimleri |
| Feature katalog deseni | `motor/parca/include/fiko/parca/feature_registry.hpp` | `FikoFeatureTanim` param şeması kaynağı |
| Belge sahipliği | `uygulama/fikocad/belge.hpp:45-46` | `MakroMotor`+`EklentiYonetici` belge-scope (korunur) |
| Plugin/makro paneli | `uygulama/fikocad/yardimci_penceler.cpp:18,75` | Paket açma + hot-reload + imza durumu UI |
| Örnek plugin | `uygulama/eklentiler/ornek_eklenti/ornek_eklenti.cpp` | v1 referans; v2 örneği yanına eklenir |

---

## 10. Anayasa Uyumu

- **[[fikatia-mimari-ilke-makro-plugin-olay]]:** Yeni genişleme noktası eklenince makro+plugin+olay
  **bedava** gelir — çünkü hepsi tek merkezi registry'ye (Cekirdek) köprülenir. Yeni `*Tanim` = üç
  yüzeyde birden görünür.
- **Merkezi komut/lisans:** Tüm plugin+makro komutları `komutCalistir` tek dispatch'inden → lisans kapısı
  + `KomutCalisti` audit. Bypass yok (`l_komutCalistir:37` deseni plugin'e de uygulanır).
- **OOP/minimal:** Yeni sistem modülü açılmaz — mevcut `EklentiYonetici` + `MakroMotor` + `Cekirdek`
  registry genişletilir; köprü katmanı (`motor/eklenti/src/host_api.cpp`) tek yeni dosya ailesi.
- **Olay struct kuralı:** Sabit olaylar enum SONUNA (mevcut `olay.hpp` kuralı); plugin-tanımlı olaylar
  string kanalda (enum'a dokunmaz).