@appaflytech/zeyrek-ai-mcp 0.0.4 → 0.0.6

package/dist/resources/guides/translation.md

@@ -14,9 +14,41 @@ kendi arayüz dili (`i18n.md`, yalnız frontend'i ilgilendirir) ile **karıştı
   `key`'e bakar).
 - Proje **dilleri** ve **varsayılan dil** application değil **proje** düzeyinde ayardır
   (`project_get`/`project_update` `languages`/`defaultLanguage`) ve tam **ISO 639-1** kod
-  kümesinden seçilir (`ProjectConstants.SupportedLanguages`, ~184 kod). `translation_update`'e
-  proje dillerinde olmayan bir kod verirsen platform isteği reddeder — önce `project_update` ile
-  dili ekle.
+  kümesinden seçilir (`ProjectConstants.SupportedLanguages`, ~184 kod).
+
+## ÖNCE DİLLERİ KUR — yoksa çeviri yazmak hiçbir işe yaramaz
+
+> **Gateway'den açılan projede bu iş halledilmiştir (PRJ-003).** Platformun create ucu dil alanı
+> taşımadığı için `project_create` projeyi dilsiz doğuruyordu; gateway artık create'ten hemen sonra
+> dilleri kuruyor — verdiğinizi, vermezseniz tek dillik `['en']` + `'en'` tohumunu — ve bunu
+> `gatewayNormalized` ile bildiriyor. Başka dil istiyorsanız `project_create`'e `languages`
+> yazın. Aşağısı **eski projeler** ve gateway dışından açılmış projeler için geçerlidir.
+
+**Platform tarafında yeni proje dilsiz doğar:** `CreateOrganizationProjectCommand`
+`Languages`/`DefaultLanguage` alanı taşımaz, ikisi de `null` başlar. Bu durumda:
+
+1. `translation_update` yazmayı **kabul eder ve 200 döner** — satırlar veritabanına düşer.
+2. Runtime sayfa paketi `languages: null` taşır, aktif dil hiç seçilemez ve fallback zinciri
+   anahtarın kendisine düşer: ekranda `dashboard.card.candidate_statistics` yazar.
+3. **Hiçbir katman uyarmaz.** Backend dil kodunu yalnız 184 kodluk ISO sözlüğüne göre doğrular
+   (TR-001), projenin `languages` listesine göre **doğrulamaz** — iki aggregate arasında bağ yoktur.
+
+Ölçüldü: 2026-09-09 1. koşu `S-15` — 15 anahtar × 2 dil (200) + 15 prop bağı (200), ekranda her
+etiket ham anahtar. Koşunun en pahalı sessiz düşmesi; yalnız gerçek karede görülüyor.
+
+```jsonc
+// SIRA: önce bu
+{ "id": "<project id>", "languages": ["en", "tr"], "defaultLanguage": "en" }  // project_update
+// sonra çeviriler
+{ "applicationId": "<app id>", "keys": [ /* … */ ] }                          // translation_update
+```
+
+Gateway bu bağı kurar: `translation_update` yazmadan önce projeyi okur ve liste boşsa, kod listede
+yoksa ya da `defaultLanguage` kurulu değilse **TR-002 caution** düşürür (yazmayı durdurmaz).
+`project_get` ve `project_overview` yanıtlarındaki `localization` bloğu durumu doğrudan söyler —
+`runtimeResolvesTranslations: false` ise çeviri yazmanın ekranda karşılığı olmayacak demektir.
+Platform dil alanlarını `null` olduklarında serileştirmede düşürdüğü için ham yanıtta `languages`
+diye bir alan **hiç görünmez**; blok tam olarak bunu görünür kılmak için var.
 
 ## Araçlar
 
@@ -49,12 +81,36 @@ backend'de zaten tanımlı, Studio'nun "Translate" aksiyonunun ürettiği şekil
   "value": { "type": "translation", "ref": "home.welcome", "data": "Hoş geldiniz" } }
 ```
 
+> **`replace_prop` ile kurulamaz, `set_prop_type` ile kurulur.** Micro-op applier her `value`'yu
+> `Static` (ifade verilmişse `Code`) Prop'a çevirir (`PageSchemaMicroOpApplier.cs:77`);
+> `translation` sarmalı gönderildiğinde sarmal `Data`'nın içine düşer ve prop sessizce bozulur.
+> Gateway `replace_prop`'un bu kullanımını **reddeder**. Kurulu bir prop'u çeviriye bağlamanın
+> yolu `set_prop_type`'tır:
+>
+> ```jsonc
+> { "op": "set_prop_type", "target": "welcome_text", "prop": "text",
+>   "propType": "translation", "ref": "home.welcome" }
+> ```
+>
+> Gateway şemayı okur, prop'un TİPİNİ yerinde değiştirir ve sayfayı tam gövdeyle geri yazar —
+> düğümün olay/setter bağları korunur. Eski yol (`remove_component` + `add_component`) düğümü
+> yeniden kurduğu için ona yazan setter iteratee'lerini sessizce öldürüyordu; artık gerekmiyor.
+> Taşıyıcı alan tipe göre değişir: `static` → `data`, `code` ve `translation` → `ref`. Eksik
+> taşıyıcı istek platforma gitmeden reddedilir ve `page_schema_validate` aynı kararı verir.
+>
+> Ölçüldü 2026-09-08 (yerel `dil-dogrulama/dil-app`): kurulu bir `statcard`'ın `title` prop'u tek
+> `set_prop_type` op'uyla `f11.tam` anahtarına bağlandı; gerçek ekranda `tr` → "iki dilde dolu",
+> `en` → "filled in both", `de` → "in beiden gefuellt" ve dil değişimi sayfa yenilenmeden geçti.
+
 - **Anahtar `ref`'tedir, `data` DEĞİL.** Runtime her `getNodeProps` turunda `data`'yı
   `resolveTranslation(...)` sonucuyla EZER (`code` prop'larıyla aynı davranış — `page.md` Kural 1c
   bunun `code` karşılığını anlatır). `ref`'i okumadan/yazmadan `data`'ya güvenme; `data` yalnız
   Studio'nun sakladığı önceki statik değerdir (fallback/geri dönüş amaçlı, çözümlemeyi ETKİLEMEZ).
 - **Fallback zinciri:** aktif dil → projenin varsayılan dili → anahtarın kendisi. Boş string de
   "eksik" sayılır ve zincirde bir alt basamağa düşer — bir anahtar hiçbir zaman boş render olmaz.
+  Zincirin sonu anahtarın kendisi olduğu için **proje dilsizken ekran boş değil, ham anahtar dolu
+  görünür** — hata gibi durmadığı için gözden kaçar. Kaynak: `resolveRuntimeLanguage` +
+  `resolveTranslation` (`zeyrek-frontend/packages/ng-apps-screen-builder/src/translation.functions.ts`).
 - Hangi prop'lar çeviriye bağlanabilir platformca kısıtlanmaz (Studio'da yalnız `text`/`long-text`
   tipli prop'larda "Translate" aksiyonu gösterilir, ama şema düzeyinde her static prop aynı Prop
   şeklini kabul eder).
@@ -67,14 +123,76 @@ Son kullanıcı dili `language-selector` komponentiyle değiştirir (`platform_g
 prop'lar sayfa yenilenmeden yeniden çözülür — ayrı bir akış kurmana gerek yok, komponenti sayfaya
 eklemen yeterli. Projede dil tanımlı değilse (`languages` boşsa) liste boş çizilir.
 
+## İstek dili: nereden gelir, hangi ifadede ne denir
+
+Her istekte dil şu sırayla çözülür: **`X-Data-Language` başlığı → `Accept-Language` → projenin
+varsayılan dili**. Bölgeli kodlar dil kısmına indirilir (`tr-TR` → `tr`). Aynı değer hem satır
+okumasında (companion tablosu), hem sayfa çevirilerinde, hem ifadelerde kullanılır.
+
+| Dünya | Aktif dil | Anahtar çözme | Nerede |
+|---|---|---|---|
+| UI flow (tarayıcı) | `machine` state'i | `t(key)` | `platform_guide('expressions')` §2 |
+| Backend (workflow/microservice ifadesi) | `context.language` | `Loc(key)` | `platform_guide('workflow')` |
+| Ham SQL | — | `{{language}}` ayrılmış parametresi | `platform_guide('microservice')` |
+
+`t()` ve `Loc()` **aynı fallback zincirini** izler: aktif dil → projenin varsayılan dili →
+anahtarın kendisi; boş string de "eksik" sayılır. İsimlerin farklı olmasının tek sebebi iki ayrı
+motor olmasıdır (tarayıcı JS'i ve Jint).
+
+> **Backend motorunun kültürü de istek dilinden gelir.** `tr` isteğinde `tr-TR`, diğer her dilde
+> `en-US`. Eskiden `tr-TR`'ye sabitti; sabit biçim istiyorsan kültüre güvenme.
+
+## Sayfa sekmesi başlığı: `browserTitleKey`
+
+`page_update` / `page_create` `browserTitle` (düz metin) yanında `browserTitleKey` alır. Anahtar
+verilmişse sekme başlığı çeviri sözlüğünden çözülür; anahtar boşsa `browserTitle` olduğu gibi
+kullanılır. İkisi de boşsa sayfa adı yazılır.
+
+> **Sekme başlığı SAYFA YÜKLENİRKEN çözülür, canlı dil değişimini İZLEMEZ.** Ölçüldü 2026-09-08
+> (yerel runtime): `language-selector` ile dil değiştirildiğinde sayfa içeriği ve layout başlığı
+> anında yeni dile geçiyor, sekme başlığı ise açılıştaki dilde kalıyor; aynı dille sayfa yeniden
+> yüklendiğinde başlık doğru geliyor. Sebep `Runtime.svelte`'te dilin bir `const` olarak bir kez
+> çözülmesi. Sekme başlığının dilini doğrulayacaksan **yeniden yükleyerek** doğrula.
+
+## Doğrulama mesajları: `t:` öneki
+
+Komponent şemasındaki `validations[].message` bir **düz metindir** ve translation prop'u ALMAZ.
+Çeviriye bağlamak için mesajın kendisine `t:` öneki konur:
+
+```jsonc
+{ "op": "set_validations", "target": "email_input",
+  "validations": [{ "type": "required", "message": "t:form.emailRequired", "isActive": true }] }
+```
+
+Runtime `t:` ile başlayan bir mesajı anahtar sayar ve normal zincirden çözer; önek yoksa metin
+olduğu gibi gösterilir. Çözüm çalışma anında olduğu için şema varsayılanlarını değiştirmek
+gerekmez — `schema.ts`'e dokunulmaz, katalog yeniden yüklenmez.
+
 ## Bilinen sınırlar
 
 - **Flow adımlarında Translation kaynağı YOK.** `value.type` sözlüğünde (`platform_guide('page')`
   Kural 1c sonundaki tablo) `translation` yoktur — bir flow adımının **değerini** doğrudan bir
   çeviri anahtarına bağlayamazsın, yalnız sayfa şemasındaki statik prop'lar bağlanabilir. İfadeden
-  okumak gerekiyorsa `t('anahtar')` Jexl fonksiyonu kullanılır (`platform_guide('expressions')`).
-- **Runtime sayfa yanıtı sunucu tarafında önbelleklidir** (Postgres `caches` tablosu). Bir
-  `translation_update`/`project_update(languages)` çağrısından hemen sonra `page_runtime_get`
-  eski değerleri gösterebilir — önbellek süresi dolana kadar. Acil doğrulama gerekiyorsa
-  `translation_list` ile yazma tarafını, `page_runtime_get` ile okuma tarafını AYRI doğrula.
+  okumak gerekiyorsa **UI flow kodunda** `t('anahtar')` kullanılır: bu tarayıcı tarafındaki
+  `runCode` önsözünde tanımlı bir yardımcıdır, backend ifade yüzeyinde (Jint) karşılığı YOKTUR —
+  backend tarafının karşılığı `Loc()`'tur (`platform_guide('workflow')`). İkisinin de fallback
+  zinciri aynı: aktif dil → varsayılan dil → anahtarın kendisi
+  (`platform_guide('expressions')` §2).
+- ~~Runtime sayfa yanıtı önbellekten eski çeviri döndürebilir.~~ **Çözüldü — 2026-09-08:**
+  `translation_update` artık uygulamanın bütün sayfalarının önbellek satırlarını düşürüyor
+  (`RefreshPageCacheWhenTranslationChangedCommand`), okuma yolu cache-aside olduğu için bir
+  sonraki `page_runtime_get` taze değeri kurar. Yazmadan hemen sonra okuyabilirsin.
 - Mobil runtime (`apps/mobile`) bu özelliği henüz beslemiyor — yalnız web.
+
+## Backend doğrulama sınırları (TR-001)
+
+`translation_update` gövdesi platforma gitmeden denetlenir (block): `keys[].key` boş olamaz ve
+tekil; `values`'taki dil kodları ISO 639-1 iki harfli küçük kod (`tr`, `en`, `de`… — `tr-TR`
+reddedilir; 184 kodluk liste `ngapps://rules/backend-constraints` içinde); `deletedKeys` boş anahtar
+taşıyamaz. Proje dilleri de aynı listeyle doğrulanır (`project_update`, PRJ-002).
+
+**Bu listenin doğrulamadığı şey:** kodun PROJENİN `languages` listesinde olup olmadığı.
+`UpdateTranslationsCommandValidator`, `UpsertTranslationKeyCommandValidator` ve
+`Translation.ValidateState()` üçü de yalnız `ProjectConstants.SupportedLanguages`'a bakar; hiçbiri
+`Project.Languages`'ı okumaz. Bağı **yalnız gateway** kurar (TR-002, `warn`) — Studio UI'dan ya da
+doğrudan API'den yazan bir istemci için boşluk açık kalır.

package/dist/resources/guides/view.md

@@ -4,6 +4,11 @@ View, **serbest metin araması** içindir: seçtiğin alanlar bir analizörden g
 projeksiyon tablosuna indekslenir. **Raporlama/agregasyon aracı değildir** — özet/sayım için
 `query_create` (raw SQL) + query kaynaklı microservice kullan.
 
+> **İki bağımsız koşu da bu yanlış beklentiyle başladı** (09-02 M-3; 2026-09-04'ün iki koşusunda
+> da tekrarladı): "view" adı SQL VIEW'ünü çağrıştırıyor, oysa buradaki view bir **arama
+> indeksidir**. Karar tek satır: *sayı/özet mi istiyorsun* → `query_create`; *metin arıyor
+> musun* → `view_create`. Tool açıklamaları da bunu söyler.
+
 Gövde şemaları: `ngapps://schemas/CreateViewCommand` · `ngapps://schemas/UpdateViewCommand`.
 
 ## Kuruluş sırası
@@ -35,6 +40,10 @@ Gövde şemaları: `ngapps://schemas/CreateViewCommand` · `ngapps://schemas/Upd
 - `analyzer` verilmezse platform `ViewAnalyzer.Default()` kullanır — Türkçe içerikte
   `language: 'turkish'` + `tokenFilters: ['lowercase','asciifolding']` açıkça verilmelidir, yoksa
   "Talep" ile "talep" ya da "yazilim" ile "yazılım" eşleşmez.
+- `asciifolding` PostgreSQL `unaccent()` ile **hem indeks hem sorgu** tarafında uygulanır: filtre
+  açıkken "Ayse" araması "Ayşe" satırını döndürür. Filtreyi var olan bir view'a **sonradan**
+  eklersen eski projeksiyon satırları aksansız metni taşımaz — `view_rebuild` çağırmadan eşleşme
+  olmaz.
 - `fields[].weight` sıralama ağırlığıdır (`double`): başlık 2, gövde 1 gibi.
 - `fields[].viewEntityAlias`, `entities[].alias` ile birebir eşleşmeli. Eşleşmezse alan **sessizce
   ilk tabloya** bağlanır (`ViewSourceMapper.Map` → `tablesByAlias.GetValueOrDefault(...) ?? tables.FirstOrDefault()`).
@@ -83,7 +92,13 @@ parametresi ister (+ `limit`/`offset`). Ayrıntı: `platform_guide('microservice
 ## Bakım
 
 - `view_rebuild` projeksiyonu sıfırdan kurar; toplu satır yüklemesinden ya da alan listesi
-  değişikliğinden sonra çağır.
+  değişikliğinden sonra çağır. `analyzer.tokenFilters` değişikliği de (özellikle `asciifolding`)
+  rebuild ister — analyzer yalnız yeni yazılan satırlara uygulanır.
 - View'in `slug`'ı projeksiyon tablosunun/indekslerinin adıdır — slug değiştirmek onları yeniden
   adlandırır; elle oluşturulmuş bir tabloyla çakışmasın diye entity slug'larıyla aynı isim uzayında
   düşün (`platform_guide('entity')` §"Slug seçimi").
+
+## Backend doğrulama sınırı (VIEW-001)
+
+`name` zorunlu; `providerType` yalnız `postgres` (tek değer). Gateway bunu istek gitmeden `block`
+olarak uygular; tam katalog `ngapps://rules/backend-constraints`.

package/dist/resources/guides/workflow.md

@@ -23,7 +23,7 @@ taşır; gateway açıklamasız gövdeyi platforma göndermez.
   okunuyor ve hiçbir şey eklemiyor. `"kullanıcının asal pozisyonunu seçer; birden çok aktif atama
   varsa is_primary olanı tercih eder, o da yoksa ilkini alır"` — yazılmadıkça hiçbir yerde
   bulunmayan bilgi budur.
-- **`start` ve `end` muaftır** (kural onları hiç sormaz): ikisi de yapısal işaretçi, açıklanacak
+- **`start` muaftır** (kural açıklama istemez): yapısal işaretçi, açıklanacak
   davranışları yok.
 - **Gateway'in enjekte ettiği `gatewayOnError` adımı kendi açıklamasını taşır** — o adımı sen
   yazmadığın için kural seni onun yüzünden durdurmaz.
@@ -74,6 +74,9 @@ outline görünümünde geri okunur — sonraki oturumda tuzağı tam gövdeyi a
 4. **Kaydetmeden önce `workflow_preview`.** Test girdisi **`previewPayload`** anahtarıyla
    verilir (`parameters`/`input` çalışmaz, ifadeler `undefined` üretir); değişkenler
    `previewVariables`.
+   `type:'workflow'` için `previewPayload` göndereceksen önce `parameterDtoId` ve
+   `parameterBehavior` tanımlamalısın; DTO'suz workflow'ta alan gerekçeli doğrulama hatasıyla
+   reddedilir. Automation ve middleware preview değişkenleri kendi bağlam kurallarını izler.
    - **`previewPayload` bir STRING olmalı ve tek kanonik biçimi `"({ … })"`'dir.** Alan
      JavaScript **kaynak metni** bekliyor (`PreviewWorkflowCommand` gövdeyi `jsEngine.Eval` ile
      çalıştırır) ve **ifadenin sonucu bir NESNE olmak zorundadır**:
@@ -101,12 +104,40 @@ outline görünümünde geri okunur — sonraki oturumda tuzağı tam gövdeyi a
      `Sequence contains no elements` alırsın ve hata seni entity'yi suçlamaya iter.
      Kalıcı satır istiyorsan akışı bağlı ucundan `microservice_execute` ile çağır.
 
+## İstek dili: `context.language` ve `Loc()`
+
+Aktif dil `context.language`, anahtar çözmek için `Loc(key)`. Motor kültürü de aynı dilden gelir
+(`tr` → `tr-TR`, diğerleri `en-US`). **`context.language` yalnız gerçek istekte doludur** —
+önizleme tetikleyici kaynağını kurmaz; dile bağlı dalı `microservice_execute` +
+`headers: { 'X-Data-Language': 'tr' }` ile doğrula. Ayrıntı: `platform_guide('translation')`.
+
 ## Step'ler nasıl bağlanır
 
 Her step'in `branches[]` dizisi vardır; `nextStepId` sonraki step'in id'sini gösterir.
 Bağlanmamış step çalışmaz. `start` tek branch taşır; normal step'ler `success` + `fail`;
-`condition` koşul branch'leri + `else`; terminal step'ler (`response`, `convert`, `revert`,
-`end`) **branch taşımaz**.
+`condition` koşul branch'leri + `else`; terminal step'ler (`response`, `convert`, `revert`)
+**branch taşımaz**. Ayrı bir `end` step tipi yoktur; son dalın `nextStepId` değerini
+`null` bırakarak akışı bitirin.
+
+## Preview yazmaz — rollback eder (ölçüm: İK koşusu W-1, 2026-09-01)
+
+`workflow_preview` ve `microservice_preview` tek transaction'da koşar ve sonunda **rollback**
+edilir (`PreviewWorkflowCommand`: `BeginTransactionAsync` → … → `RollbackTransactionAsync`).
+Table create/update/upsert step'leri kalıcı satır **yazmaz**; preview'ı istediğin kadar tekrar
+edebilirsin. Tek istisna: code step içinden yapılan **dış HTTP çağrıları** geri alınamaz — dış
+sisteme yazan bir akışı preview'da koşarken bunu bil.
+
+**Preview step/branch id'lerini de TÜKETMEZ** (ölçüldü 2026-09-05, `f09-repro`): aynı GUID
+bloğuyla iki kez preview 200 döner, sonra aynı gövde `workflow_create`'e verilince id'ler olduğu
+gibi kaydedilir — önizlemeye ayrı blok ayırmayın. Preview sonrası `RowAlreadyExists` alıyorsanız
+sebebi Kural 3'tür: o id'ler kaydedilmiş başka bir akışta duruyordur.
+
+`query_preview` de rollback edilir ve bu daha sinsidir: yazan bir sorgu `affectedRowCount`'ta
+gerçek sayıyı döner, tablo boş kalır (ölçüm: 09-04 Y-19) ve **yanıtta rollback'i söyleyen bir alan
+yoktur** (ölçüm: 2026-09-07). Yazmayı doğrulamak istiyorsan sorguyu kaydet, microservice/workflow
+üzerinden çalıştır ve sonucu `row_list` ile say.
+
+Tool açıklamaları bu bölüme işaret eder; iki kaynak çelişirse **bu rehber** doğrudur.
 
 ## Hata yolu
 
@@ -135,13 +166,16 @@ yapıyı dışarı sızdırır.
 
 - **Global-error dalı TEK olmalı ve START adımında durmalı.** Başka adıma koyulan dal hiç
   çalışmaz, platform 400 döner. Gateway bunu `WF-022` ile istek gitmeden reddeder.
-- **Hata `response` adımı ReturnDto'ya bağlı değildir.** Global-error modunda platform sözleşmeyi
-  atlar, gövde serbesttir — `returnDtoId` ile çakışmaz.
+- **`returnDtoId` süzmesi yalnız 2xx yanıtlarda uygulanır (2026-09-05).** Bir `response` adımının
+  `httpStatusCode`'u 2xx dışındaysa (401, 404, 422, 500…) gövde sözleşmeden GEÇMEZ ve
+  `bodyExpression` ne ürettiyse o döner. Yani bir koşul dalından `({ success: false, message: '…' })`
+  ile 401 dönmek için DTO'ya `message` alanı eklemek gerekmez — muafiyet artık global-error
+  dalıyla sınırlı değil. Öncesinde bu gövde sessizce boş `{}` oluyordu.
 - **Loop içi hatalar global-error dalına GİTMEZ.** Loop çocuk bağlamı bu yönlendirmeyi kapatır;
   loop adımının kendi `fail` dalını bağla.
 - **`automation` tipinde `response` adımı yasaktır**, bu yüzden gateway bu tipe enjeksiyon
-  yapmaz. Hata yolunu kendin yaz: global-error dalını `revert` (tetikleyen satır işlemini geri
-  alır) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
+  yapmaz. Hata yolunu kendin yaz: global-error dalını `revert` (kapsamı `isQueue`'ya
+  bağlı — §izin matrisi) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
 - **Hata yolu hiç yoksa** akış patladığında platform 500 + ham exception mesajı döner. Çalışır,
   ama çıktı denetimsizdir ve lokalize değildir.
 
@@ -206,6 +240,27 @@ gidilir, hiçbiri tutmazsa `else` dalı yürür:
 | convert | ✓ | – | – |
 | revert (Fail and Rollback) | – | ✓ | – |
 
+> **`revert`'in iki alanı JavaScript ifadesidir, düz metin değil.** `rule.revertType` ve
+> `rule.revertMessage` çalışma anında `Evaluate` edilir; Studio bu alanları kod editörüyle sunar ve
+> varsayılanlarını tırnaklı verir (`"Failed"`, `"Transaction is reverted."`). Tırnaksız metin
+> gönderirsen ifade çözülmez ve adım
+> `Step '<ad>' failed. Please check the workflow. [EvaluateWorkflowStepFailedException]` ile düşer;
+> mesaj hangi alanın sorunlu olduğunu söylemez. Doğru yazım: `revertType: "'all'"`,
+> `revertMessage: "'Is kurali hatasi.'"` (2026-09-02 ölçümü).
+>
+> **Önizlemede `revert` artık 400 değil, dolu bir adım ağacı döndürür (2026-09-05).** Kuru koşuda
+> revert bir hata değil, kapının çalıştığının kanıtıdır: `automation_preview` 200 döner,
+> `executionSuccess: false` olur ve `revert` adımı ağaçta `hasError: true` + `errorType` =
+> `revertType` + `errorMessage` = `revertMessage` ile görünür.
+>
+> **`revert` exception fırlatır ve bulunduğu transaction'ı İKİ yolda da geri alır; ayrım o
+> transaction'ın kapsamıdır (2026-09-07).** `isQueue:false` (async): kapsam yalnız akışın
+> yazdıklarıdır — tetikleyen satır COMMIT olmuş, çağıran 200 almıştır; olay `failed` +
+> `revertMessage` damgalanır ve bu yolda `failed` damgası kapının ÇALIŞTIĞININ izidir, kusur
+> değil. `isQueue:true` (senkron): kapsam satır işlemini de içerir — satır geri alınır, çağırana
+> 400 `{ code: revertType, message: revertMessage }` gider (**AUT-002**); seçim §Bilinen sınırlar'da.
+> `rule.isExpression` bayrağı bu iki alan için **okunmaz**.
+
 
 ## Loop step — dizinin her öğesi için bir adım koştur
 
@@ -316,10 +371,26 @@ Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seç
   **`platform_guide('expressions')`** — uydurma fonksiyon adı runtime 500'üdür.
 - Yazma step'lerinde (create/update): **yazılacak** alanlar `fields`, **okunacak** alanlar
   `selectFields` — aynı alan ikisinde birden olamaz (`An item with the same key...`).
-- **Yazma step'inin çıktısı yalnız primary key'dir** (`<step>.data.id`); sonraki step'lerin ya
-  da response'un başka alana ihtiyacı varsa bunları **`returnFields`** ile iste
+- **Yazma step'inin çıktısı yalnız primary key'dir**; sonraki step'lerin ya da response'un
+  başka alana ihtiyacı varsa bunları **`returnFields`** ile iste
   (`{ alias, fieldId, fieldSlug }` öğeleriyle) — `selectFields` write operasyonunda sessizce
   yok sayılır.
+- **Çıktının ŞEKLİ `isSingle`'a bağlıdır** (ölçüm: 09-04 koşusu Y-15). `isSingle: true` ise
+  `<step>.data` nesnedir ve `<step>.data.id` çalışır; **`isSingle: false` ise `data` bir
+  DİZİDİR** — `<step>.data.id` `undefined` olur, akış `RowValidationFailed` ile düşer ve hata
+  hangi adımı işaret ettiğini söylemez. YAZMA adımı da aynı kurala uyar: `isSingle: false` olan
+  bir `create`/`update` adımının çıktısı dizidir, ve o id'yi bir FK alanına geçiren sonraki adım
+  `23502 null value in column "<fk>"` ile düşer — hata FK'nın adını söyler, sebebin ŞEKİL
+  uyuşmazlığı olduğunu değil (09-05 koşusu `S-5`; kuru koşu yakaladı, kaydedilseydi yarım
+  kullanıcı yazılmış olurdu). **Üç vakayı da karşılayan tek savunmalı yazım:**
+
+  ```js
+  // dizi (isSingle:false) · nesne (isSingle:true) · düz değer (yalnız pk dönen yazma)
+  (Array.isArray(x.data) ? (x.data[0] && x.data[0].id) : (x.data && x.data.id !== undefined ? x.data.id : x.data))
+  ```
+
+  Şekli bilmiyorsan bu yazımı kullan; `workflow_preview` çıktısında `steps[].output`'a bakarak
+  hangi vakada olduğunu da görebilirsin.
 
 > **Gateway table step'lerinde `path`/`sort`/`limit` eksiklerini otomatik dolduruyor**
 > (yanıtta `gatewayNormalized`). Dolu değerlere dokunmaz; yanlış path yine WF/MS block'una takılır.
@@ -390,31 +461,45 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 
 ## Automation gerçekleri (hr + qm projelerinde doğrulandı)
 
-- **`returnDtoId`/`parameterDtoId` automation'da YASAKTIR** (validator: "'Return Dto Id' must
-  be empty"). `returnBehavior: "object"` verilebilir.
+- **`returnDtoId`/`parameterDtoId` ve `returnBehavior`/`parameterBehavior` automation'da
+  YASAKTIR** (validator: "'Return Dto Id' must be empty" / "'Return Behavior' must be empty");
+  `automation_create` kabul ediyor gibi görünse de `automation_update` reddeder (ölçüm: 09-04
+  Y-13). Dördünü de automation gövdesinde hiç yazma.
 - **`state: 'unready'` automation için NORMALDİR ve tetiklemeyi etkilemez** — qm'deki çalışan
   automation'lar da unready'dir; "Studio'dan aktifleştirme" diye bir işlem yoktur.
-- **Tetikleme kapısı üç alandır**, üçü de `automation` nesnesinde: `entityId` (tetikleyen
-  entity), `operation` (`create`/`update`/`delete`), **`isQueue` (false=anlık, true=kuyruklu;
-  null bırakılırsa tetikleme sorgusu HİÇ eşleşmez — automation sessizce ölü kalır)**.
-  `condition` opsiyonel JavaScript ifadesidir. `isActive` diye bir alan YOKTUR (yok sayılır).
+- **Tetikleme kapısı üç alandır**, üçü de `automation` nesnesinde: `entityId`, `operation`
+  (`create`/`update`/`delete`) ve **`isQueue`** — adı yanıltıcıdır (`Entity.cs:735-736`):
+  **`true` = isteğin İÇİNDE senkron** koşar (`queueOrder` zorunlu, sıra ondan gelir),
+  **`false` = RabbitMQ'ya giden async** ateşle-unut yoldur — satır yazıldıktan hemen sonra
+  okursanız automation'ın yazdığını göremezsiniz. `null` bırakılırsa tetikleme sorgusu HİÇ
+  eşleşmez — automation sessizce ölü kalır. `condition` opsiyonel JavaScript ifadesidir;
+  `isActive` diye bir alan YOKTUR (yok sayılır).
 - `steps` hem üst seviyede hem `automation` içinde verilir (PLT-007); `response` step'i
   kullanılamaz, hata yolu için `revert` vardır.
 - **Tetikleyen satıra `input` ile DEĞİL `row` ile erişilir**; update'te `previousRow`, işlemi
   yapan kullanıcı `user` altındadır (`row.title`, `previousRow.user`, `user.id`). Step
-  `fields[]` öğelerinde `source: 'body'` + `value: '<ifade>'` kullanılır.
-- **`isQueue: false` senkron demek değildir.** Tetikleme ateşle-unut çalışır; satırı yazdıktan
-  hemen sonra sonucu okursanız automation'ın yazdığı satırı göremezsiniz. Kısa bir bekleme
-  sonrası tekrar okuyun.
+  `fields[]` öğelerinde `source: 'expression'` + `value: '<ifade>'` kullanılır — table step ile
+  aynı yazım. Eski kayıtlarda `source: 'body'` görürsün; davranış AYNIDIR — `TableStep` default
+  modda her alanın `value`'sunu `source`'a **bakmadan** JS ile değerlendirir
+  (`TableStep.cs:392-412`), yani `expression` automation'da da çalışır.
 - Hem `row_create` ucundan hem `operation: 'create'` yapan bir microservice'ten tetiklenir —
   ikisi de aynı hook'a düşer.
-- **Bilinen platform sınırı (P-03):** kısa aralıklı ardışık tetiklerde (özellikle `rows[]` ile
-  TOPLU `row_create`) automation yalnız ilk satır için tetiklenebiliyor — kayıp satırlar
-  `automation_histories`'te hiç görünmez. Otomasyonlu entity'lere satırları **tekil** yazın
-  (ya da sonradan `automation_trigger` ile telafi edin); toplu ekleme sonrası tetiklenmeyi
-  mutlaka sayarak doğrulayın.
-- Doğrulama: `automation_trigger` + `automation_histories` (ya da tetikleyen satırı yazıp
-  sonucu kontrol et).
+- **Tetikleyen satıra geri yazan automation'ın kapısı `automation.condition` OLMALIDIR, akışın
+  içindeki bir `condition` ADIMI değil.** Sıra bunu belirler: `automation.condition` eşleşmezse
+  mesaj kuyruğa hiç girmez ve sayaç artmaz; akışın ilk adımına konan kapı iş sonucunu doğru tutar
+  ama koşumu saydırmaya devam eder. (Ölçüm: `08-kural-envanteri.md`, `B-20`.)
+- **Satır olayının DIŞINDAN değer geçirmek: `rowContext` (2026-09-05).** `row_create`/`row_update`
+  (tekil ve toplu) isteğe bağlı bir `rowContext` sözlüğü alır; tetiklenen automation onu
+  ifadelerinde **`rowContext.<anahtar>`** ile okur. Tarihsel (geçmiş tarihli) veri üretmenin yolu
+  budur: automation damgayı `UtcNow()` yerine `rowContext.occurredAt`'ten alabilir —
+  `(typeof rowContext !== 'undefined' && rowContext && rowContext.occurredAt) ? rowContext.occurredAt : UtcNow().toISOString()`.
+- **AUT-003:** `rowContext` yoksa automation sessizce `UtcNow()`a düşer — tarihsel automation'ın
+  entity'sine yazan her yol onu verir, duman testi dahil.
+- **`automation_trigger` bir DOĞRULAMA aracıdır, veri üretme aracı DEĞİL:** gerçekten çalıştırır,
+  `rowContext` **almaz**, damgası hep `UtcNow()`'dur — tarihsel tohumun üstünde tek çağrı huni
+  ortalamasını 5 sa → 226 sa yaptı ve hiçbir uyarı çıkmadı (`B-52`). Tarihsel veri: küçükse
+  `rowContext`'li `row_create`, kümeyse
+  `platform_guide('entity')` §"Toplu ve türetilmiş satır".
 
 ```jsonc
 {
@@ -431,6 +516,18 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 }
 ```
 
+## Bilinen sınırlar ve kabul edilen kanıt
+
+Bunlar **platform sınırıdır**, gövdeyi değiştirerek aşılmaz — ama sınır doğrulamayı iptal etmez,
+yolunu değiştirir: kapalı yolu deneyip raporuna "kanıtlayamadım" yazma, kanıt sütunundaki çıktıyı
+üret.
+
+| Kapalı yol | Kabul edilen kanıt |
+|---|---|
+| **`AUT-004`** — enum/zorunluluk/benzersizlik denetleyen `revert` dalı `row_create` yolundan HİÇ tetiklenemez: entity doğrulaması automation'dan ÖNCE koşar | `automation_preview`: revert adımı `hasError` + `errorType` ile döner (§izin matrisi) — **tam** kanıt, ikinci koşum aranmaz. Canlı red de şartsa kuralı enum OLMAYAN bir alana kur |
+| **`AUT-002`** — `isQueue:false` automation ÇAĞIRANI reddedemez (§izin matrisi) | Reddin izi `automation_histories`: `failed` + `revertMessage`; çağırana 400 gerekiyorsa kural `isQueue:true` + `queueOrder` yoluna kurulur |
+| **`automation_preview` CANLI davranışı göstermez** — tek transaction, rollback | ŞEKLİN kanıtı preview; CANLI davranışın kanıtı tetikleyen satır + `row_list` + `automation_histories` (`AUT-006`) |
+
 ## Sık hatalar (politika lint'inin yakaladıkları)
 
 - Bağlanmamış step grafı (WF-001, block) · workflow'da returnDtoId eksik (WF-002, block)
@@ -442,6 +539,15 @@ zorunludur (`CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → Re
 - Adımda ya da akışta `description` yok (WF-024, block — Studio'da adım okunamaz kalır)
 - İlişki alanının içini okuyan ifade (WF-020, warn — join yoksa alan düz FK'dır)
 - `set-user` adımı olmadan `user` okuyan middleware (MW-003, warn)
+- Backend zorunlulukları (WF-026, block — istek gitmeden): `name`/`slug`; `returnDtoId` varsa
+  `returnBehavior`, `parameterDtoId` varsa `parameterBehavior` (`primitive` | `object` | `array`),
+  update/preview'da DTO yokken behavior `null`; `type: 'workflow'` + `parameterDtoId` yokken
+  `previewPayload` verilemez; `variable` adımına `user` adı verilemez (set-user'a ayrılmış);
+  tekil filtrede `fieldId`; automation `parameterDtoId` almaz, `isQueue: true` ⇒ `queueOrder`
+  (0 geçerli). Tam katalog: `ngapps://rules/backend-constraints`.
+- DTO gövdesi (DTO-001, block): `type` sözlükten (`string`, `number`, `guid`, `datetime`, `object`,
+  `array`… — `text` YOK, G-23), `children[].slug` zorunlu ve kardeşler arasında tekil, `referenceId`
+  yalnız `object`/`array` çocukta.
 
 ## Hedefli değişiklik: `workflow_patch` yollarında İNDEKS KULLANMA
 
@@ -458,7 +564,9 @@ Gateway seçiciyi gövde platforma **gitmeden** indekse çevirir, çözülemezse
 ve yanıtta `patchTargets` ile her op'un hangi adıma (ad + tip + id) indiğini söyler. Aynı seçici
 `microservice_patch`'te de çalışır (`/sourceParameters/joins[alias=customers]/path`).
 
-
+Patch tam gövde yazmaz; gateway farkı `{ baseVersion, ops }` olarak gönderir. Araya başka bir
+yazma girdiyse **409** döner ve hiçbir op uygulanmaz — `workflow_get` ile yeniden oku. `version`
+**string**tir, sayıya çevirme.
 
 ## Table adımının filtresi: `alias` YOKSA filtre SESSİZCE DÜŞER
 
@@ -482,3 +590,66 @@ kusur `operation: 'update'` filtresinde **yanlış satırı günceller**.
 
 `source` da **`expression`** olmalı: verilmezse `body`'ye düşer ve `value` bir ifade değil
 **gövde alanı adı** sayılır — yine filtre kaybolur.
+
+## Query adımı: kayıtlı query'nin parametreleri (ölçüm 2026-09-03)
+
+**Parametreyi query'yi kaydederken bildir.** `query_create` ve `query_update` gövdesindeki
+`parameters: [{ name, type, value }]` alanı, query'ye bağlı bir parametre DTO'su kurar; `query_get`
+bunu `parameterScheme` olarak geri verir. Bildirmediğin bir parametre sözleşmede yoktur — kaydetme
+başarılı olur, sorgu runtime'da bağlanmaz.
+
+```jsonc
+// query_create gövdesi: "WHERE extract(year from start_date) = @year"
+{ "rawQuery": "SELECT count(*) AS total FROM leave_requests WHERE extract(year from start_date) = @year",
+  "slug": "izin-raporu", "name": "Izin Raporu", "datasourceId": "<datasource id>",
+  "outputType": "object",
+  "parameters": [ { "name": "year", "type": "number", "value": 2026 } ] }
+```
+
+`value` burada **önizleme değeridir**: kayıt sırasında sorgu bu değerlerle bir kez çalıştırılır, hem
+SQL doğrulanır hem de yanıt şeması (`returnScheme`) üretilir. Sorgu hatalıysa kayıt 422 ile reddedilir.
+
+Kaydedilen sözleşme üç tüketim yolunda da aynı şekilde bağlanır:
+
+| Tüketim yolu | Değer nereden gelir |
+|---|---|
+| `queryStepSourceType: 'library'` (workflow query adımı) | Adımın ifadeleri: `rule.expression` (nesne literali) ya da `rule.queryParameters[]` — ikisi de **JavaScript ifadesidir**; istek girdisini (`input.year`), önceki adım çıktısını **ve bağlı middleware'in `user.*` değişkenini** okur |
+| Query kaynaklı microservice (`source: 'query'`) | Yalnız çağrının kendisi: **body → query-string → header** (`MicroserviceExecuteParameter.FindValue`); ifade YOKTUR, `user.*` bu yola girmez |
+| `query_preview` | `parameters` alanı — davranış yukarıdaki ikisiyle aynıdır |
+
+> **Boş string parametre `NULL`'a çevrilir.** `Query.NormalizePreviewParameters` değeri normalize
+> ederken boş ya da yalnız boşluktan oluşan değeri `null` yapar. `WHERE status = {{durum}}` yazıp
+> `durum: ''` gönderirsen sorgu `= NULL` olur ve **hiçbir satırla eşleşmez**: 0 satır döner, hata
+> ya da uyarı yoktur. 2026-09-04 ölçümü: aynı sorgu `''` ile 0, `IS NULL` dalı yazıldığında 346
+> satır. "Filtre yok" demek istiyorsan sentinel kullan (`'all'` gibi) ya da sorguyu
+> `({{durum}} IS NULL OR status = {{durum}})` biçiminde yaz. Query kaynaklı uçta da aynı
+> (üç koşuda ölçüldü: 09-02, 09-04·1, 09-04·4).
+
+> **`query_preview` yazan sorguyu koşturur, geri alır ve bunu söylemez** (yukarıda Kural 3).
+> Kalıcı yazmanın reçetesi: `platform_guide('entity')` §"Toplu ve türetilmiş satır".
+
+```jsonc
+// library query adımı: query'de "WHERE extract(year from start_date) = @year" yazıyorsa
+{ "id": "<GUID-Q>", "name": "izin_raporu", "type": "query",
+  "rule": { "stepType": "query", "queryStepSourceType": "library", "isExpression": false,
+            "queryId": "<kayıtlı query id>",
+            "expression": "{ year: input.year }",   // bugün BAĞLAYAN yazım
+            "queryParameters": [ { "name": "year", "value": "input.year", "type": "number" } ] },
+  "branches": [ /* success + fail */ ] }
+```
+
+> **Bağlamayı `rule.expression`'a yaz.** Kayıtlı sorgunun parametreleri bildirilmişse çalışan
+> motor `rule.queryParameters` dizisine BAKMIYOR: parametreler `null` bağlanıyor ve çağrı
+> **`200` + sıfır satır** dönüyor, hiçbir katman uyarmıyor (ölçüldü 2026-09-07; düzeltme depoda
+> var, canlı dağıtım geride — `B-63`). Gateway bu adımı `WF-025` ile uyarır.
+>
+> **Kimlik/tenant kapsamı da buradan bağlanır** — query kaynaklı ucun yapamadığı şey budur:
+> `"{ company_id: user.company_id, from: input.from }"` (ölçüldü; `middlewareIds` boşsa
+> `500 user is not defined`). Reçete: `platform_guide('microservice')`.
+
+- `queryParameters[].name` **`@` ya da `{{ }}` olmadan** yazılır; belirtecin sorgudaki adıyla
+  eşleşmelidir.
+- Değer çağrıda bulunamazsa parametre `null` bağlanır — sorgu düşmez, `WHERE` koşulu boşa çıkar.
+- `parameters` bildirilmemiş eski query'lerde belirteçler ham SQL'den okunur; güvenme (string
+  literalindeki `@ad`'ı da parametre sanıyor, `query_get` boş `parameterScheme` gösteriyor). Böyle
+  bir query'yi `parameters` vererek bir kez `query_update` et.

package/dist/resources/knowledge.js

@@ -10,6 +10,11 @@ export function listKnowledgeFiles(kind) {
         return [];
     }
 }
+/**
+ * `schemas` MCP kaynağı olarak YAYINLANMAZ (yalnız `guides` ve `examples` kayıtlıdır) ama
+ * dosyalar aynı klasör düzeninde durur ve drift testleri onları da okur — şema kaynağı
+ * platformun swagger'ından üretiliyor ve bir alanın oradan düşmesi sessizce olur.
+ */
 export function readKnowledgeFile(kind, file) {
     return readFileSync(join(resourcesDirectory, kind, file), 'utf8');
 }

package/dist/resources/rules.js

@@ -0,0 +1,27 @@
+import { constraintCatalog } from '../knowledge/backendConstraints.js';
+/** `ngapps://rules/<ad>` kaynakları; docs-lint bu listeyle `ngapps://rules/…` referanslarını denetler. */
+export const ruleResourceNames = ['backend-constraints'];
+/**
+ * Backend doğrulayıcı kataloğu tek kaynak olarak koddan üretilir (`backendConstraints.ts`);
+ * dosya olarak paketlenmez ki tool açıklaması, lint ve bu kaynak hiçbir zaman ayrışmasın.
+ */
+export function registerRuleResources(server) {
+    server.registerResource('rules-index', 'ngapps://rules/index', {
+        title: 'Kural kaynakları dizini',
+        description: "Gateway'in koddan ürettiği kural katalogları; şu an backend doğrulayıcı aynası.",
+        mimeType: 'application/json'
+    }, async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                mimeType: 'application/json',
+                text: JSON.stringify({ rules: ruleResourceNames.map(name => `ngapps://rules/${name}`) })
+            }]
+    }));
+    server.registerResource('rules-backend-constraints', 'ngapps://rules/backend-constraints', {
+        title: 'Backend doğrulama sınırları',
+        description: "Platformun 422/409 ile reddedeceği gövde kuralları (uzunluk, zorunluluk, tek primaryKey, DTO/behavior eşleşmesi, dil kodları…) — kaynak referanslı; gateway aynı kuralı istek gitmeden block olarak uygular.",
+        mimeType: 'application/json'
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(constraintCatalog(), null, 2) }]
+    }));
+}

package/dist/resources/schema-fingerprint.json

@@ -0,0 +1,8 @@
+{
+  "hash": "0e6bb2b45f8c545b50dc6d6169e7d816d9cb9532ecbaed894307995d537ff3b6",
+  "generatedAt": "2026-09-09T09:49:52.511Z",
+  "types": 103,
+  "files": 73,
+  "note": "Şemaları üreten backend kaynaklarının parmak izi. Elle düzenlemeyin: 'npm run generate-schemas' yazar, 'npm run schema:check' denetler.",
+  "missing": []
+}

package/dist/resources/schemas/CreateBulkRowCommand.json

@@ -0,0 +1,33 @@
+{
+  "schema": {
+    "required": [
+      "rows"
+    ],
+    "type": "object",
+    "properties": {
+      "entityId": {
+        "type": "string",
+        "format": "uuid"
+      },
+      "rows": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": {}
+        },
+        "nullable": true
+      },
+      "rowContext": {
+        "type": "object",
+        "additionalProperties": {
+          "nullable": true
+        },
+        "nullable": true
+      }
+    },
+    "additionalProperties": false
+  },
+  "components": {
+    "schemas": {}
+  }
+}