@appaflytech/zeyrek-ai-mcp 0.0.6 → 0.0.7

package/dist/resources/guides/functions.md

@@ -0,0 +1,262 @@
+# Fonksiyonlar — iki kaynak, tek biçim
+
+Studio kullanıcısı (ya da ajan) **parametreli JavaScript fonksiyonları** tanımlar. Backend tek
+aggregate tutar (`GlobalFunction`, `/global-functions`), ajan sözlüğü `function_*` araçlarıdır; ayrım
+**`source`** bayrağıdır ve kaydedildikten sonra değişmez — tarayıcıda `Functions.<ad>()`, sunucuda `<ad>()`:
+
+| `source` | Nerede çalışır | Nasıl çağrılır | Kapsam |
+|---|---|---|---|
+| `workflow` | **Sunucu** (Jint): workflow / middleware / automation ifadeleri | çıplak ad `toplamHesapla(10, 3)` | tenant geneli; `applicationId`/`scope`/`pageId` verilmez, `isAsync` olamaz |
+| `studio` | **Tarayıcı**: `{{ }}` prop bağlamaları, UI flow `code` / `function` adımı | `Functions.toplamHesapla(10, 3)` | uygulamaya ait; `applicationId` + `scope` (`application` \| `page`) zorunlu |
+
+Kod ve parametre biçimi ikisinde **aynıdır**: gövde düz deyimler (`return fiyat * adet;`),
+parametreler tipli ve sıralı bir liste, `defaultValue`/`required` zinciri aynı. Aynı ad iki kaynakta
+yan yana yaşayabilir — ad alanları farklıdır (`ad()` vs `Functions.ad()`), ikisi ayrı kayıttır.
+
+> **`source:'studio'` YALNIZ TARAYICIDA çalışır (2026-09-10).** Sunucu `Functions` diye bir ad
+> alanı tanımaz — sunucu ifadesindeki `Functions.<ad>(…)` çağrısı `Functions is not defined` ile
+> düşer ve gateway ifadeyi `WF-030` ile **istek gitmeden bloklar**. Sunucu için `source:'workflow'`
+> tanımla. Mikroservis ifadeleri hiçbir kaynağı yüklemez.
+
+Araçlar: `function_list` · `function_get` · `function_create` · `function_update` · `function_delete`
+(modül `function`; `core` ve `studio` kümelerinde). Örnekler: `ngapps://examples/function-total`
+(iki kaynak), `ngapps://examples/flow-call-function`.
+
+## Ne zaman fonksiyon, ne zaman değil
+
+Fonksiyon **şu iki durumda** yazılır:
+
+1. Aynı ifade üç ya da daha çok yerde kopyalanıyor (her `code` adımına, her prop bağlamasına aynı
+   hesap) — tek tanım, tek düzeltme noktası.
+2. Parametreli bir hesap gerekiyor: `toplamHesapla(fiyat, adet)`, `kdvEkle(tutar, oran = 0.2)`.
+
+Bir iş kuralı **hem tarayıcıda hem sunucuda** geçerliyse iki kayıt gerekir: `source:'studio'` ve
+`source:'workflow'`, aynı gövdeyle. Kopyayı gizleme — kapatamıyorsan `platform_gap_report` ile bildir.
+
+Fonksiyon **yazılmaz**: tek yerde kullanılan ifade için (doğrudan yaz); veri çekmek için
+(uç çağrısı `microservice` adımının işidir, fonksiyon HTTP yapmaz); `system.*` / `file.*` /
+`crypto.*` zaten yapıyorsa (`platform_guide('expressions')`).
+
+## Kaynak ve kapsam seçimi
+
+| Seçim | Nerede görünür | Alanlar | Ne zaman |
+|---|---|---|---|
+| `source:'workflow'` | Tenant'ın **her** workflow / middleware / automation ifadesinde | yalnız `name`, `parameters`, `body`, `description` | Sunucu tarafı iş kuralı, hesap, biçimlendirme |
+| `source:'studio'`, `scope:'application'` | Uygulamanın **her sayfasında** (tarayıcı) | `applicationId` | Varsayılan tarayıcı seçimi |
+| `source:'studio'`, `scope:'page'` | **Yalnız o sayfanın** tarayıcı bağlamında | `applicationId` + `pageId` | Gövde sayfaya özgü komponent adlarını / `state.page`'i kullanıyor |
+
+Tekillik: workflow adı tenant içinde, studio adı uygulama içinde **kapsamlar arası benzersizdir**
+(K3) — `homepage`'de `hesapla` varsa başka bir sayfada da uygulama düzeyinde de `hesapla` açılamaz;
+platform `422 GlobalFunctionNameAlreadyExists` döner ve mesaj çakışan kapsamı/sayfayı söyler.
+Gölgeleme yoktur. Kaynak/kapsam tutarsızlığını gateway `FN-005` ile istek gitmeden yakalar
+(workflow'a `applicationId`, studio'ya `applicationId`sız, `page` kapsamına `pageId`sız).
+
+## Hangi bağlam nerede çalışır (K4, K7)
+
+Fonksiyonun **hedefi yoktur**: gövde nerede çağrılırsa o bağlamda çalışır ve çağıranın tüm
+globallerini kapanış olarak görür. Yanlış bağlamda çağrı çalışma anında `X is not defined` verir;
+lint bunu yakalayamaz, tablo sana kalır:
+
+| Gövdede kullanılan ad | `studio` sayfa fonksiyonu | `studio` uygulama fonksiyonu | `workflow` fonksiyonu |
+|---|:-:|:-:|:-:|
+| parametreler (`fiyat`, `adet`) | ✓ | ✓ | ✓ |
+| `state.app.<key>` | ✓ | ✓ | — |
+| `state.page.<key>`, komponent adları, `Page.components` / `Page.properties` / `Page.queryParams` | ✓ | ✓ (**çağrıldığı sayfada varsa** — statik olarak bilinemez) | — |
+| `Page.user`, `Page.authorized(roles)`, `Page.variables` | ✓ | ✓ | — |
+| `Steps`, `self`, `item`, `event` | çağıran akışın bağlamından | çağıran akışın bağlamından | — |
+| `input`, middleware değişkenleri, adım çıktıları (`<adım>.data`), `row` (automation) | — | — | çağıran ifadenin bağlamından |
+| `system.*`, `file.*`, `crypto.*`, `convert.*`, `Now()`, `UtcNow()` | — | — | ✓ |
+| `cookie` | `get/set/remove` | `get/set/remove` | okunur (`cookie.<ad>`) |
+| `await` | `isAsync:true` ise | `isAsync:true` ise | **yok** (FN-004 block) |
+| başka bir fonksiyon | `Functions.b()` ✓ (K15) | `Functions.b()` ✓ | çıplak `b()` ✓ (aynı kaynaktan) |
+
+Kural: uygulama fonksiyonunda **sayfaya özgü ad kullanma**; workflow fonksiyonunda **adım adına
+bağlanma** — dinamik veriyi parametre olarak geçir (`Functions.hesapla(state.page.sayac)`,
+`hesapla(input.tutar)`), gerekiyorsa gövdeyi guard'la (`typeof state !== 'undefined'`).
+
+## İmza: parametreler, varsayılan, `required` (K5)
+
+Parametreler **bildirimlidir ve sıralıdır**; çağrı **konumsaldır**: `f(a, b)` bildirimin birinci ve
+ikinci parametresine bağlanır, ad eşlemesi yoktur. İki runtime da her fonksiyonu aynı şekilde kurar
+(tek fark ad alanı ve hata öneki):
+
+```js
+globalThis["toplamHesapla"] = function (fiyat, adet) {       // studio: Functions.toplamHesapla = function (…)
+  if (adet === undefined) adet = 1;                          // defaultValue ÖNCE
+  if (fiyat === undefined) throw new Error('toplamHesapla: "fiyat" is required'); // required SONRA
+  try { return fiyat * adet }                                 // gövde
+  catch (e) { throw new Error('toplamHesapla: ' + e.message) }
+};
+```
+
+- `defaultValue` yalnız argüman `undefined` kalınca uygulanır; `null` geçmek varsayılanı **tetiklemez**.
+- `required:true` parametreye `defaultValue` da verilirse varsayılan kazanır, hata hiç fırlamaz.
+- `type` (`text` · `number` · `boolean` · `date` · `object` · `array` · `any`) yalnız Studio
+  imzası ve autocomplete içindir; çalışma zamanı tip denetlemez, `"10"` string olarak gelir.
+- Fazla argüman yok sayılır; eksik argüman `undefined` → varsayılan → `required` hatası zinciri.
+- İmza gösterimi (yanıtlardaki `signature`): studio `Functions.toplamHesapla(fiyat, adet = 1)`,
+  workflow `toplamHesapla(fiyat, adet = 1)`; zorunlu olmayan ve varsayılansız parametre `ad?` yazılır.
+
+## Tanımlama: `function_create`
+
+```jsonc
+// sunucu
+{ "source": "workflow",
+  "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
+  "parameters": [ { "name": "fiyat", "type": "number", "required": true },
+                  { "name": "adet",  "type": "number", "defaultValue": 1 } ],
+  "body": "return fiyat * adet;" }
+
+// tarayıcı
+{ "source": "studio", "applicationId": "<app id>", "scope": "application",
+  "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
+  "isAsync": false,
+  "parameters": [ … aynı liste … ],
+  "body": "return fiyat * adet;" }
+```
+
+Gövde **düz deyimlerdir** — `function (…) { }` sarmalı ya da arrow yazılmaz; `return` serbesttir,
+dönüşsüz gövde `undefined` döner. Platform gövdeyi kaydetmeden **ayrıştırır** (yürütmez):
+sözdizimi hatası `422 GlobalFunctionBodyInvalid` ile ve ayrıştırıcı mesajıyla döner. Yanıt
+`signature` ve `hint` (çağrı biçimleri) taşır. İstek gitmeden denetlenenler:
+
+| Kural | Ne | Sonuç |
+|---|---|---|
+| FN-001 | Ad JS tanımlayıcısı değil ya da ayrılmış sözcük; studio'da `Functions`, workflow'da motor global adı (`system`, `input`, `Now`…); parametre adı geçersiz | **block** — platform da 422 verirdi |
+| FN-002 | Aynı parametre adı iki kez | **block** — 422 `GlobalFunctionParameterNameDuplicate` |
+| FN-003 | Gövde kendini çağırıyor (`Functions.<ad>(` / çıplak `<ad>(`) | warn — durma koşulu yoksa sonsuz özyineleme |
+| FN-004 | `source:'workflow'` + `isAsync:true` | **block** — motor senkron, 422 `GlobalFunctionAsyncNotAllowed` |
+| FN-004 | studio: `isAsync:true` ama `await` yok · `isAsync:false` ama `await` var | warn — ilki gereksiz async (inline `[object Promise]`), ikincisi **derlenmeyen gövde**: fonksiyon atlanır |
+| FN-005 | Kaynak/kapsam tutarsız: workflow'a `applicationId`/`scope`/`pageId`; studio'ya `applicationId` ya da `scope` yok; `page` kapsamına `pageId` yok; `application` kapsamına `pageId` var | **block** — platform 422 |
+
+Studio kaydı sonrası bağlı sayfaların çalışma paketi `Pages.Updated` ile yeniden kurulur (B-11):
+`/dev` yolu yeni gövdeyi hemen, `/view` yolu önbellek tazelenince gösterir. Workflow kaydı önbellek
+taşımaz; sonraki koşu yeni gövdeyi görür.
+
+## İfadeden çağrı: `{{ }}` ve `code` adımı (studio)
+
+```jsonc
+// prop bağlaması — page_schema_patch set_binding
+{ "op": "set_binding", "target": "txt_toplam", "prop": "content", "expression": "{{ Functions.toplamHesapla(num_fiyat.value, num_adet.value) }}" }
+```
+
+```js
+// UI flow code adımı (args.value) — await serbest
+const toplam = Functions.toplamHesapla(10, 3);
+state.page.sonuc = toplam;
+```
+
+- Hata gövdeden yayılır ve `Functions.<ad>: <mesaj>` ile öneklenir; prop bağlamasında `runCode`
+  hatayı yutar, prop **yazılmaz** ve `page_screenshot` `runtimeErrors` taşır (PAGE-020/021).
+- `isAsync:true` fonksiyonu `{{ }}` içinde çağırma: dönüş Promise'dir, ekranda `[object Promise]`
+  görünür. Async fonksiyon `code` adımında `await Functions.x()` ile ya da `function` adımıyla çağrılır.
+- `flow_create`/`flow_update` yazımında gateway her `Functions.<ad>(` çağrısını uygulamanın studio
+  fonksiyon listesiyle karşılaştırır (FLOW-025, uyarı): bilinmeyen ad, başka sayfanın sayfa
+  fonksiyonu, bildirimden fazla argüman, setter/condition ifadesinde async fonksiyon.
+
+## UI flow `function` adımı ("Call function", K9)
+
+```jsonc
+{ "stepId": "hesapla", "name": "hesapla", "type": "function", "kind": "normal",
+  "args": { "functionId": "<function_list id>", "functionName": "toplamHesapla",
+            "parameters": [
+              { "name": "fiyat", "value": { "type": "property", "ref": { "source": "component", "element": "num_fiyat", "property": "value" } } },
+              { "name": "adet",  "value": { "type": "static", "ref": 3 } } ] },
+  "branches": [ { "name": "always", "nextStepId": "yaz" } ] }
+```
+
+- `functionId` **zorunlu**, uygulamada var olmalı ve bir **studio** fonksiyonu olmalı (backend
+  `422 GlobalFunctionNotFound` — workflow fonksiyonu adıma bağlanamaz; gateway FLOW-024 ile istek
+  gitmeden bloklar). Runtime fonksiyonu **önce id** ile çözer, `functionName` yalnız gösterim ve
+  yedektir — yeniden adlandırma akışı kırmaz.
+- `parameters[].name` bildirimdeki adla eşleşir; `value` şekli `microservice` adımıyla aynı
+  (`static` · `property` · `storage` · `state` · `variable` · `code` · `page` · `item`). Eksik
+  zorunlu parametre adımı düşürür, tanınmayan ad sessizce düşer (FLOW-024 ikisini de uyarır).
+- Çıktı `Steps.<adımAdı>.data`; hata `Steps.<adımAdı>.error.message` (nesne — `microservice`
+  adımının dize hatasından farklı). Dal adı `always`; hata yolu `errorSteps` ile aynı mekanizma.
+- Sonucu ekrana yazmak için sonraki `setter` iteratee'si `storage` tipiyle `mapping.source:
+  "hesapla.data"` okur (adım **adı**, stepId değil) — tam gövde `ngapps://examples/flow-call-function`.
+- Akışı olaya bağlamak ayrı adımdır: `page_schema_patch set_event { target, event:'click', eventValue:<flow id> }`.
+- `end` adımı koyma; son adımın dalı `nextStepId: null` ile biter (FLOW-023).
+
+## Sunucuda ne kullanılır: `source:'workflow'`
+
+Bir hesabı workflow / middleware / automation ifadesinden çağırman gerekiyorsa
+`function_create source:'workflow'` ile tanımla ve **çıplak adla** çağır:
+
+```js
+// workflow code adımı (rule.expression)
+return { toplam: toplamHesapla(input.fiyat, 2) };
+```
+
+```js
+// automation koşulu
+toplamHesapla(row.fiyat, row.adet) > 1000
+```
+
+- Tenant kapsamlıdır: tanımlandığı andan sonra her uygulamanın her workflow ifadesinde görünür,
+  her koşuda DB'den yüklenir (önbellek yok). Gövde bağlamdan bağımsız olmalı — dinamik veriyi
+  parametre olarak geçir.
+- `workflow_preview` ile doğrula: `return toplamHesapla(3, 2)` → `data: 5`.
+- İfadede `Functions.<ad>(…)` yazarsan gateway **istek gitmeden bloklar** (`WF-030`); zorlarsan
+  Jint `Functions is not defined` fırlatır ve adım hata yoluna girer.
+- Mikroservis alan/filtre ifadeleri hiçbir kaynağı yüklemez — orada fonksiyon yok.
+
+## Güncelleme ve silme
+
+- `function_update` platforma **tam gövde** gönderir; gateway mevcut kaydı okuyup vermediğin alanları
+  doldurur — yalnız `body` göndermen yeter. `source`/`applicationId`/`scope`/`pageId` değişmez. Ayrı
+  patch aracı yoktur: fonksiyonun tek büyük alanı gövdedir.
+- **Yanıt kimin etkileneceğini söyler:** `dependents` (kullanan flow/workflow adları) ve
+  `signatureChange` (ad ya da parametre ad/sırası değiştiyse eski → yeni; tip, varsayılan ve gövde
+  imzayı değiştirmez). İkisi birden doluysa `warnings[]` gelir — çağrı konumsaldır (K5), `function`
+  adımı parametreyi ada göre eşler; güncelleme yine yapılır (K12), silme ise engellenir. Uyarı
+  aldıysan çağıran ifadeleri gözden geçir, `dependency_graph(module:'global-function')` listeyi verir.
+- **Yeniden adlandırma çağıranlara yazılır (2026-09-11):** platform yeni adı aynı işlemde çağıranlara
+  taşır; yanıt `renamedReferences` ile kaç kaydın yazıldığını söyler. Studio kaynağında `Functions.<eskiAd>`
+  başvuruları (akış adımları, `function` adımının `functionName`'i, `code` bağlamaları, diğer fonksiyon
+  gövdeleri) yazılır; düz metin (`static`) prop'lar kod değildir, değişmez. Workflow kaynağında
+  `<eskiAd>(…)` çağrıları (workflow ifadeleri, otomasyon koşulları, workflow fonksiyonu gövdeleri)
+  yazılır; eski ad yeni adın yazılamadığı bir yerde kalırsa — çağrı dışı kullanım (değişken, nesne
+  anahtarı) ya da ham sorgu ifadesi (`isExpression: true` `rawQuery`; içindeki SQL çoğunlukla JS metnidir)
+  — platform **400** `CantRenameUsedGlobalFunction` ile reddeder ve hiçbir şey yazmaz. Düz SQL
+  (`isExpression: false`) kullanım sayılmaz, yazılmaz. Fonksiyonun kendi gövdesindeki çağrılar
+  (özyineleme) da yeni adı alır. Tablo adımı alan ifadeleri taramaya girmez, onları elle düzelt.
+- `function_delete`: gateway önce bağımlılık grafiğini okur ve kullanan flow/workflow varsa isteği
+  göndermez (409, liste). Studio kaynağında platform silmeyi **engellemez** (K12); bilinçli silme için
+  `acknowledgeDependents: true`. Workflow kaynağında platform **400** `CantDeleteUsedGlobalFunction`
+  ile reddeder, `acknowledgeDependents` bunu geçemez.
+- Uygulama silinince studio fonksiyonları cascade silinir; deploy ve şablon iki kaynağı da taşır
+  (`function` adımlarının `functionId`'si kurulumda yeniden eşlenir, workflow kaynağı ada göre upsert).
+
+## Tuzaklar
+
+- **Yanlış kaynak:** sunucu ifadesinde `Functions.x(` → `WF-030` block; tarayıcı ifadesinde çıplak
+  workflow adı → `x is not defined`. Aynı hesap iki dünyada gerekiyorsa iki kayıt.
+- **Async inline:** `{{ Functions.veriGetir() }}` → `[object Promise]`. Async fonksiyon yalnız
+  `code`/`function` adımından; workflow kaynağı async olamaz.
+- **Sayfa fonksiyonu başka sayfada yok:** `Functions.x is not a function`. Ortak kural uygulama
+  kapsamına.
+- **Ad çakışması 422:** studio'da uygulama içinde kapsamlar arası, workflow'da tenant içinde;
+  mesaj çakışan kapsamı/sayfayı söyler.
+- **Ayrılmış adlar:** studio'da `Functions` (K1: komponent adı da olamaz, PAGE-009); workflow'da
+  motor globalleri (`system`, `input`, `request`, `Now`, `crypto`…). `Functions` workflow kaynağında
+  serbesttir — sunucuda o ad alanı yok.
+- **Önekli hata:** gövde hatası `Functions.<ad>: <mesaj>` (studio) ya da `<ad>: <mesaj>` (workflow)
+  olarak gelir; `Steps.<adım>.error.message` ya da `runtimeErrors`'ta bu öneki ara.
+- **Mobil yok** (K11): `apps/mobile` runtime'ı `Functions`'ı boş nesne kurar.
+- **Önbellek:** `/view` yolu eski gövdeyi birkaç saniye gösterebilir; `/dev` yolu anlıktır.
+- **Parametre konumsal:** `parameters` sırasını değiştirmek mevcut çağrıların anlamını değiştirir;
+  `function` adımları ada göre eşlendiği için etkilenmez.
+
+## Doğrulama
+
+1. `function_list` → kaynak, imza ve id doğru mu (`source` süzgeciyle iki listeyi ayrı gör).
+2. Studio: `page_runtime_get` özeti `appFunctions` / `pageFunctions` imzalarını taşır — sayfa paketi
+   fonksiyonu gördü mü (önbellek tazelenmiş mi).
+3. Studio: `page_screenshot` `actions` ile butona tıkla, kareyi ve `actionsReport[].flowRuns`'ı oku;
+   ifade patladıysa `runtimeErrors`.
+4. Workflow: `workflow_preview` ile çıplak adla koştur (`return toplamHesapla(3, 2)`); sonuç
+   `data`'da.
+5. Nerede kullanıldığı: `dependency_graph(module:'global-function', id)` — iki kaynakta da
+   `{ flows, workflows }` döner (workflow kaynağında `flows` boş).

package/dist/resources/guides/getting-started.md

@@ -51,6 +51,11 @@ Bağımlılıklar bu sırayı zorunlu kılar; atlama:
                           sonra execute+debug)
 10. workflow_create /    (bkz. platform_guide('workflow'); branch bağlantıları + returnDtoId —
     automation_create     returnDtoId'siz workflow 'unready' kalır; automation/middleware muaf)
+10b. function_create     (İSTEĞE BAĞLI, uygulama düzeyinde: 3+ yerde tekrarlanacak hesap ya da hem
+                          tarayıcıda hem sunucuda geçerli iş kuralı varsa ŞİMDİ tanımla — sayfalar
+                          ifadelerde Functions.<ad>(…) ile, akışlar 'function' adımıyla çağırır;
+                          sayfaya özgü fonksiyon (scope:'page') sayfa açıldıktan sonra gelir.
+                          Kurallar platform_guide('functions'))
 11. layout_create        (header/sidebar + MUTLAKA bir 'slot' — slot'suz layout'a bağlı sayfa
                           boş görünür; bkz. platform_guide('page') Kural 5)
 12. page_create + …      (İŞ BURADA BİTMEZ: her kaydın yönetim ekranı, kimlik varsa giriş

package/dist/resources/guides/merge.md

@@ -0,0 +1,231 @@
+# Dal ve Merge Rehberi (environment dallanma)
+
+Kendi başına çalışabileceğin bir kopya aç, orada değiştir, sonra `development`'a geri birleştir.
+Deployment (`deployment_start`) bu işin dışındadır: o `development → production` yolu ve **insan
+onaylıdır**. Buradaki tool'ların hiçbiri production'a yazmaz.
+
+## Politika (değişmez)
+
+- **Merge hedefi her zaman dalın ebeveynidir.** Ebeveyn `development`'tır; başka bir hedef seçilemez.
+- **Production'a merge eden tool yoktur.** Production'a giden tek yol insan onaylı deployment'tır.
+- Sabit environment'lar (`development`, `production`) silinemez; `environment_delete` bunu HTTP'ye
+  gitmeden reddeder.
+
+## Akış
+
+```
+environment_create {projectId, name}        → 202, dal "creating"
+environment_list   {projectId}              → state "ready" olana kadar (30-60 sn)
+… tenant tool'larını environment: "<dal>" ile çağır (page_schema_patch, entity_patch, …)
+merge_plan   {projectId, sourceEnvironmentId} → 202, plan "planning"
+merge_get    {projectId, planId}              → status "planned" olana kadar
+merge_get    {projectId, planId, view:"conflicts"} → çakışanları oku
+merge_resolve{projectId, planId, resolutions[]}   → her çakışmaya source|target seç
+merge_apply  {projectId, planId, message}         → 202  (message ZORUNLU)
+merge_get    {projectId, planId}                  → status "applied"
+environment_list {projectId}                      → dal listede yok, şeması düştü
+```
+
+## Dalda çalışmak
+
+Dal adı `X-Environment` başlığının değeridir. Tenant tool'larına `environment: "odeme_akisi"`
+geçmek yeterlidir; `DEFAULT_ENVIRONMENT` yalnız varsayılandır. Dal `ready` değilken o dalda
+yazmaya çalışmak 400 döner — `environment_list` ile durumu doğrula.
+
+Dal açılırken **yalnız tanımlar** kopyalanır. `includeRecords: true` verirsen projenin kendi
+veritabanındaki **bütün** veri tablolarının satırları da gelir — entity'de kayıt taşıması ayarı
+açık olmasa bile (çok dilli companion tablolar ve junction'lar dahil; `files`/`folders` ve audit
+trail tabloları hariç, dış datasource'lara dokunulmaz). Kayıt taşıması ayarı deployment'ın
+(`promote`) kuralıdır ve orada aynen geçerlidir. **Satırlar merge'de geri taşınmaz** — merge yalnız
+tanım işidir.
+
+Dalda `page_screenshot` **çalışır** (2026-09-09'dan beri); ayrıntısı bir sonraki bölümde.
+
+## Dalda görsel doğrulama
+
+**Dalda kurulan sayfanın karesi dalda alınır** — `page_screenshot {..., environment: "<dal>"}`.
+Studio'nun runtime rotasının üç şeridi vardır ve **ortamı URL belirler**:
+
+| Ortam | Şerit |
+|---|---|
+| `production` | `/view/{proje}/{app}/{sayfa}` |
+| `development` | `/dev/{proje}/{app}/{sayfa}` |
+| dal | `/branch/{dal}/{proje}/{app}/{sayfa}` |
+
+Sayfanın **bütün** istekleri o dala gider: sayfa şeması da, akışların uç çağrıları da. Yani kare
+"yarı doğru" değildir — gördüğünüz ekran dalın gerçek ekranıdır.
+
+Reddedilen tek şey **dal adı olamayacak bir ad**: harfle başlamayan, küçük harf/rakam/alt çizgi
+dışında karakter taşıyan, 3-31 aralığının dışına çıkan ya da rezerve bir ad (`public`, `api`,
+`pg_*` …). Projedeki dalları `environment_list` verir.
+
+2026-09-09 öncesinde bu çağrı **reddediliyordu**: runtime rotası dal adı taşımıyordu, ortam
+modül içi bir store'dan geliyordu ve dal adıyla istenen kare development'ı gösterirdi. O günlerin
+alışkanlığı olan "dalda `page_schema_get` + `page_runtime_get`, kare merge sonrasına" zinciri
+hâlâ geçerli bir doğrulama yoludur, ama artık **zorunlu değildir**.
+
+`page_schema_get` (komponent ağacı, prop ve olay bağları) ile `page_runtime_get` (akışlar,
+değişkenler, çözülen ref'ler) kareyi tamamlar: kare ne çizildiğini, bu ikisi neden öyle
+çizildiğini söyler.
+
+## Planı okumak
+
+`merge_get` üç görünüm sunar; varsayılan `conflicts`:
+
+| view | ne döner |
+|---|---|
+| `summary` | yalnız sayaçlar (`added/updated/deleted/conflicts/unresolved/dataRisk`) |
+| `conflicts` | yalnız çakışan kayıtlar ve onların çakışan elemanları |
+| `full` | değişen her kayıt ve her eleman |
+
+`items[]` yalnız **değişen** kayıtları taşır. Her kayıtta:
+
+- `kind`: `add` | `update` | `delete` | `conflict`
+- `dataRisk`: entity kaleminde veri riski var — **sebep `dataRiskReasons[]` içindedir**
+- `derivedFromKey`: kalem OTOMATİK ÜRETİLMİŞ bir kayıtsa (varsayılan DTO) kaynağının anahtarı
+- `elements[]`: `path`, `kind`, `base`, `source` (dal), `target` (development), `resolution`
+
+`dataRisk` bir **uyarıdır, apply'ı bloklamaz**; üç sebepten biriyle doğrudur:
+
+| `dataRiskReasons` | Ne demek |
+|---|---|
+| `field-removed` | Alan siliniyor |
+| `field-narrowed` | Tip / `nullable` / `unique` daraltılıyor |
+| `not-null-without-default-on-populated-table` | **Hedefte satır varken** varsayılansız zorunlu alan ekleniyor — bu apply'ı DDL aşamasında düşürür. Alanı `nullable` yapın ya da `defaultValueType: "default-value"` + `defaultValue` verin |
+
+Son satır 2026-09-09'da eklendi; öncesinde bu durum `dataRisk: 0` diyordu ve risk ancak apply
+denenerek öğreniliyordu. Hedef tablo **boşsa** aynı alan riskli sayılmaz.
+
+`derivedFromKey` dolu olan kalemi ayrıca çözmeye çalışmayın: kaynağını (entity ya da query)
+çözdüğünüzde aynı yoldaki çakışması **kendiliğinden** aynı tarafa çözülür. Entity adını değiştiren
+bir merge'de entity ve onun varsayılan DTO'su böylece zıt çözülemez.
+
+`add` / `update` / `delete` elemanları **otomatik alınır** — karar istemezler. Yalnız `conflict` ve
+`order-conflict` elemanları `merge_resolve` bekler.
+
+## Çakışma çözmek
+
+```json
+{ "itemKey": "page:8f1c…", "path": "components[elementId=btn_save].props[name=label].ref", "choice": "source" }
+```
+
+`path` boş bırakılırsa o kaydın **tüm** çakışmaları aynı tarafa çözülür. `source` = dal,
+`target` = development.
+
+`merge_resolve` **özet döner** — `{ planId, status, summary, resolved }`. Planın kendisi yanıtta
+yoktur; kalan çakışmalar için `merge_get {planId, view:"conflicts"}` çağırın.
+`summary.unresolved` 0 olduğunda `merge_apply` yolu açıktır.
+
+## Apply'ın reddettiği üç durum
+
+| Durum | Kod | Ne yapmalı |
+|---|---|---|
+| Çözülmemiş çakışma var | 409 | `merge_get view:"conflicts"` → `merge_resolve` → tekrar `merge_apply` |
+| Development plan alındığından beri değişti | 409 | `merge_plan` ile **yeniden planla**; eski planı uygulama |
+| Plan 24 saatten eski | 400 | yeniden planla |
+
+Aynı `merge_apply` çağrısını tekrarlamak sonucu değiştirmez — 409 geçici bir hata değildir.
+
+## Mesaj zorunludur
+
+`merge_apply` mesajsız çalışmaz. Mesaj plana yazılır, plan uygulandıktan sonra da durur ve
+geçmişte bu mesajla görünür — git'teki merge commit mesajının karşılığıdır.
+
+- Boş ya da yalnız boşluktan oluşan mesaj **şema katmanında** reddedilir; istek platforma hiç gitmez.
+- En fazla 200 karakter.
+- Kalıp: `<dal> → development: <amaç>`. Ne yaptığını yaz, "merge" yazma.
+
+Gateway senin yerine mesaj **uydurmaz**: ne değiştirdiğini bilen sensin.
+
+## Geri almak
+
+Uygulanmış bir merge silinmez, **ters bir planla** geri alınır:
+
+```
+merge_revert {projectId, planId, message}   → 202, ters plan planning
+merge_get {projectId, planId: <ters plan>}  → status planned olana kadar
+merge_apply {projectId, planId: <ters plan>, message}
+```
+
+Bittiğinde ters plan `applied`, kaynak plan `reverted` olur; ikisi de geçmişte durur.
+
+Üç şey normal merge'den farklıdır:
+
+- **Sütunların anlamı terstir.** Ters planın `elements` satırlarında `source` merge **öncesi**
+  değer, `target` **şimdiki** değerdir. Bir kaydı merge'den sonra elle değiştiren biri olduysa o
+  satır `conflict` gelir; `source` seçmek geri almayı, `target` seçmek o kaydı olduğu gibi bırakmayı
+  seçer.
+- **Pencere vardır.** `RevertWindowDays` (varsayılan 7 gün) dolduğunda 400 döner, çünkü merge
+  öncesi anlık görüntü de aynı pencereyle silinir. Uygun bir plan için `merge_list status:'applied'`.
+- **Ters planın ters planı yoktur.** `kind=revert` bir planı geri almaya çalışmak 400 verir; aynı
+  değişikliği tekrar istiyorsanız dalı yeniden merge edin.
+
+Geri alma reddedildiğinde **mesaj hangi kapıya takıldığını söyler** — üçünü karıştırmayın
+(2026-09-09'dan beri üç ayrı cümle; öncesinde üçü de aynı cümleyi veriyordu):
+
+| Ne denendi | Mesaj ne der | Ne yapılır |
+|---|---|---|
+| `kind=revert` bir planı geri almak | "A revert plan cannot itself be reverted" | Ters planın geri aldığı **kaynak planı** geri alın ya da dalı yeniden merge edin |
+| Hiç uygulanmamış plan (`planned`, `failed`, `discarded`) | "this plan is '<durum>'" — planın **gerçek durumu** cümlede | `merge_list status:'applied'` ile uygulanmış planı seçin |
+| Zaten geri alınmış plan | aynı cümle, **`this plan is 'reverted'`** | Geri alma zaten yapılmış; ters planı `merge_get` ile görün |
+
+## Geçmişi okumak
+
+Merge sonrası hedefte dokunulan kayıtlar revizyon defterine `source: merge` ile düşer:
+`revision_list {projectId, module, recordId}` bir kaydın merge ile mi yoksa elle mi değiştiğini
+söyler, `revision_diff` ise ne değiştiğini.
+
+
+`merge_list` projenin merge planlarını en yeniden eskiye verir:
+
+```
+merge_list {projectId}                          → son planlar (her durumdan)
+merge_list {projectId, status:"applied"}        → uygulanmış merge'ler
+merge_list {projectId, environmentId:"<env>"}   → o environment'ı kaynak ya da hedef alan planlar
+```
+
+`items[]` bu uçta **her zaman boştur** — bir planın değişiklik listesi için `merge_get`.
+Satırda `message`, `createdBy` (planı alan), `appliedBy` (uygulayan), `appliedAt` ve
+`summary` sayaçları gelir. Sayfalama `pageIndex` / `pageLength` ile.
+
+Bir kaydın neden değiştiğini ararken sıra: `merge_list status:"applied"` → ilgili satırın
+`id`'si → `merge_get {planId, view:"full"}`.
+
+`activity_list` daha geniştir: dal açma/silme, plan alma/çözme/uygulama ve dağıtım aynı akışta.
+
+```
+activity_list {projectId}                              → tüm geçmiş, en yeni önce
+activity_list {projectId, kind:"merge.applied"}        → yalnız uygulanmış merge'ler
+activity_list {projectId, environmentId:"<env>"}       → o dalın hikâyesi
+activity_list {projectId, userId:"<id>"}               → bir kişinin yaptıkları
+```
+
+Her satırda `actor`, `actorSource` (`human` | `ai` | `system`) ve türe göre değişen bir
+`summary` vardır. **Bu gateway üzerinden yaptığın her iş `actorSource: "ai"` olarak düşer** —
+istekler `X-Client: mcp` başlığı taşır. Merge satırlarında `subjectId` plan id'sidir;
+ayrıntı için `merge_get`.
+
+## Merge bittikten sonra
+
+**Cache için elle bir şey yapmanız gerekmez (2026-09-09'dan beri).** Merge, dokunduğu entity'lerin
+`entityId:` / `entityApi:` / `entityRelationId:` anahtarlarını hedef ortamda **merge biter bitmez**
+yeniden kurar; dalda kurulmuş join'li bir microservice `development`'ta ilk çağrıda çalışır.
+Öncesinde entity anahtarları yalnız geçersizleştiriliyor, yeniden kurulmuyordu ve uç
+`Sequence contains no matching element` ile **500** veriyordu — kurtulmanın tek yolu entity'ye
+anlamsız bir `entity_patch` atmaktı. Cache yenileme hatası merge'i düşürmez: `cacheError`'a yazılır,
+plan `applied` kalır.
+
+- `applied` → dal `merged` olur ve **şeması düşer**; `environment_list` artık göstermez.
+- `applied-with-drift` → dal ve şeması **durur**. `verification.driftTables` dal ile development
+  arasında hâlâ farklı olan tabloları listeler; incelenmeden dal silinmez.
+- `failed` → plan `failed`, dal `ready`'ye döner. Dal ve içindeki iş kaybolmaz; yeniden planlanır.
+
+## Sınırlar
+
+- Projede aynı anda **tek** açık merge planı olur. Yenisini istemeden önce `merge_apply` ya da
+  `merge_discard`.
+- Merge sürerken dal ve development'a yazma kilitlidir; **diğer dallar etkilenmez**.
+- Proje başına açık dal sayısı sınırlıdır (varsayılan 5) — sınır bağlantı bütçesidir, ürün kararı
+  değil.
+- Dal adı `^[a-z][a-z0-9_]{2,30}$` kuralına uyar ve şema adı olur; `development`, `production`,
+  `public`, `pg_*` gibi adlar rezervedir.