@appaflytech/zeyrek-ai-mcp 0.0.4 → 0.0.6

package/dist/resources/guides/component.md

@@ -30,6 +30,23 @@ component_get   → tek tipin TAM sözleşmesi, üç katman birleşik:
   `appearance.heightType: 'auto'` tercih edilir. Katalog varsayılanı bazı tiplerde kendi
   sınırını aşar — körü körüne kopyalama, gateway kırpar ve bildirir.
 
+### Arayüz metni ve biçimler uygulama dilini izler
+
+Komponentlerin KENDİ arayüz metni (tablo sayfalaması, filtre operatörleri, boş durumlar, kırpma
+düğmeleri) ve sayı/tarih biçimleri uygulamanın aktif dilinden gelir — prop vermene gerek yok.
+İki ayrı kural işliyor ve karıştırılmamalı:
+
+- **Metin İngilizceye düşer.** Kütüphanenin sözlüğü tr/en taşır; projede `de` seçiliyse o metinler
+  İngilizce çıkar. Yeni dil eklemek sözlüğe satır eklemektir, komponent değişikliği değil.
+- **Biçim düşmez.** Sayı ayraçları ve tarih adları seçilen dilin kendi kuralını kullanır
+  (`de` → `1.234,5`). Dili olmayan bir biçim yoktur; dil verilmediğinde taban İngilizcedir.
+
+Bazı komponentlerin `locale` prop'u geriye uyum için durur ve **doluysa kazanır** — bilinçli
+sabitleme içindir. Boş bırakmak doğru varsayılandır.
+
+Doğrulama mesajını çeviriye bağlamak ayrı bir sözleşmedir (`t:` öneki, `platform_guide('page')`
+§validasyon); prop'ları bağlamak için `set_prop_type` (`platform_guide('translation')`).
+
 ## Olay modeli
 
 - Olay adları `component_get.events`'ten okunur, **`on` öneki almaz** (tek istisna
@@ -79,29 +96,73 @@ Her şema düğümünde iki sözlük vardır; ikisi de ortak render katmanında
 |---|---|
 | `isDroppable` | İçine komponent alır (container/form/repeater true) |
 | `isScrollable` | İçeriği kendi alanında kaydırır (sabit yükseklikte `overflow-y: auto`) |
-| `isWrapper` | Sayfanın/layout'un/widget'ın ANA kabı — salt düzen elemanı: `height:100%` + **`min-height:80vh`**, kap başlığı ÇİZİLMEZ. **Yalnız sayfa boyu kaplaması gereken tek kap için kullan:** iç içe kutuya verirsen 720px'lik pencerede o kutu 36px içerikle bile 576px çizilir (ölçüldü, `platform_guide('page')` Kural 1f). Çerçeve/başlık gizlemek için wrapper değil `style` / `hideBorders` kullan; `states` için micro-op olmadığından düzeltmek düğümü yeniden kurmayı gerektirir |
+| `isWrapper` | Sayfanın/layout'un/widget'ın ANA kabı — salt düzen elemanı: `height:100%` + **`min-height:80vh`**, kap başlığı ÇİZİLMEZ. **Yalnız sayfa boyu kaplaması gereken tek kap için kullan:** iç içe kutuya verirsen 720px'lik pencerede o kutu 36px içerikle bile 576px çizilir (ölçüldü, `platform_guide('page')` Kural 1f). Çerçeve/başlık gizlemek için wrapper değil `style` / `hideBorders` kullan. Kurulmuş bir düğümün bayrağını `resize_component` micro-op'unun `states` alanı değiştirir — düğümü yeniden kurmak gerekmez |
 | `isSticky` | Kaydırmada yerinde kalır (header/sidebar; z-index'i otomatik) |
+| `isFloating` | Düğümü akıştan çıkarıp yüzdürür (katman davranışı; nadir) |
+| `isQuickStack` | Studio'nun Quick Stack iskelet hücresi işareti — editörde kesikli çerçeve çizer, **runtime'da hiçbir etkisi yoktur**. MCP'den iskelet kurarken yazmak serbesttir ama gerekmez |
 
 > **Çocukların DİZİLİMİ `states`'te değil kabın PROP'undadır:** `container` — ve dolayısıyla
 > `page_container` — `layout: 'flex' | 'grid'` + altı ayar (`direction`, `horizontalAlign`,
-> `verticalAlign`, `size`, `gap`, `wrap`) taşır. Katalog varsayılanı `flex`'tir ama varsayılan
-> düğüm kurulurken yazılır: `layout` prop'u hiç yoksa renderer IZGARA çizer, o yüzden şemayı sen
-> kuruyorsan açıkça yaz. Ortalama/yaslama/aralık işini `style` ile değil bu grupla kur:
-> `platform_guide('page')` Kural 1f-2.
+> `verticalAlign`, `size`, `gap`, `wrap`) taşır; **`form` (2026-09-01), `box`/`aibox` ve
+> `layout`/`widget-area` (2026-09-03) da aynı grubu aynı varsayılanlarla taşır** — değer
+> kümesi hepsinde `flex`/`grid`, yalnız `box-section` tek değerlidir. Katalog
+> varsayılanı `flex` + `wrap: true`'dur ama varsayılan düğüm kurulurken yazılır: `layout`
+> prop'u hiç yoksa renderer IZGARA çizer, o yüzden şemayı sen kuruyorsan açıkça yaz.
+> Ortalama/yaslama/aralık işini `style` ile değil bu grupla kur: `platform_guide('page')`
+> Kural 1f-2.
 
 | `appearance` | Değerler | Anlamı |
 |---|---|---|
-| `heightType` | `auto` · `fixed` · `fill` | `auto`: içerik kadar (önerilen — Kural 1d); `fixed`: `blocks.h × 10px`; `fill`: **kalanı doldur** — ebeveynin bıraktığı yer (ızgarada `height:100%`, flex sütununda `flex:1 1 auto`, flex satırında `align-self:stretch`). Tam ekran yerleşim kabuğu bununla kurulur, bkz. `platform_guide('layout')` |
-| `marginType` / `marginValue` | `normal` · `none` · `custom` + px | Dış boşluk: normal=5px, custom=`marginValue` |
+| `heightType` | `auto` · `fixed` · `fill` | `auto`: içerik kadar (önerilen — Kural 1d); `fixed`: `heightString` varsa o, yoksa `blocks.h × 10px`; `fill`: **kalanı doldur** — ebeveynin bıraktığı yer (ızgarada `height:100%`, flex sütununda `flex:1 1 auto`, flex satırında `align-self:stretch`). Tam ekran yerleşim kabuğu bununla kurulur, bkz. `platform_guide('layout')` |
+| `widthType` | `cover` · `contain` · `auto` · `fixed` · `fill` | İlk ikisi görsel/medya sığdırma. Kalanı **flex (ve eski cssgrid) kabın çocuğunun genişlik modu** (2026-09-01): `auto` içerik kadar, `fixed` `widthString`'den, `fill` kabın tüm genişliği (satırda `flex:1 1 100%`, sütunda `align-self:stretch`). **Yazılmazsa eski 12 kolon `blocks.size.w` payı geçerlidir** — öncelik: `fill` > `fixed` > `auto` > span |
+| `widthString` / `heightString` | CSS uzunluğu | Sabit ölçü; **yalnız ilgili `*Type: 'fixed'` iken okunur** (aksi PAGE-017 uyarısı). Kabul: çıplak sayı (px sayılır) · `px % vw vh vmin vmax rem em ch` birimli değer · `calc(...)`. Negatif/`pt`/`fr`/`auto` GEÇMEZ — platform kaydeder ama panel ve runtime sessizce düşürür (PAGE-018). Eski `widthPx` alanı 2026-09-01'de kaldırıldı |
+| `marginType` / `marginValue` | `normal` · `none` · `custom` + px | Dış boşluk: **yazılmazsa `normal` sayılır** = her kenara 4px (`spacing.ts` `CANVAS_NORMAL_MARGIN`); custom=`marginValue`. Bileşenleri dip dibe dizmek için `none` ŞART — `gap:'none'` olsa bile normal margin komşular arasında 8px bırakır (sıkı dizilim tarifi: `platform_guide('page')` Kural 1f-2) |
 | `paddingType` / `paddingValue` | `normal` · `none` · `custom` + px | Droppable kapların iç boşluğu: normal=10px |
 | `alignType` | `left` · `center` · `right` | İçerik hizalama (destekleyen komponentlerde) |
-| `widthType` | `cover` · `contain` | Görsel/medya sığdırma davranışı |
 | `aspectRatio` | sayı | En-boy oranı kilidi (medya komponentleri) |
 
 `isHidden` bu sözlüklerde değil PROP'tur ve her komponentte çalışır; flow'lar `margin` /
 `padding` / `height` prop adlarıyla da appearance'ı setter üzerinden değiştirebilir
 (RenderComponent bu üç prop'u appearance'a çevirir).
 
+> **Yerleşim YALNIZ `appearance`'tan geçer — `style`'a yazılan CSS kaçamakları sessizce
+> yutulur.** `style` serbest bir sözlüktür: doğrulama duvarı susar, kayıt 200 döner, `*_get`
+> değeri geri verir ve düzen hiç değişmez. 2026-09-06·2 koşusunda üst çubuktaki "Dashboard"
+> etiketi flex satırında sıkışıp "Dashboar" olarak çizildi; `style.flexShrink: 0` hiçbir şey
+> yapmadı, çözüm `appearance` oldu (`S-11`). Karşılıklar:
+>
+> | `style`'a yazma | Karşılığı |
+> |---|---|
+> | `flexShrink` · `flexGrow` · `flexBasis` · `flex` | `widthType`/`heightType`: küçülmeyi durdurmak `fixed` + `*String`, kalanı almak `fill`, içerik kadar `auto` |
+> | `width` · `minWidth` · `maxWidth` | `widthType: 'fixed'` + `widthString` |
+> | `height` · `minHeight` · `maxHeight` | `heightType: 'fixed'` + `heightString` (ya da `auto`/`fill`) |
+> | `margin` · `padding` | `marginType`/`marginValue` · `paddingType`/`paddingValue` |
+> | `alignSelf` · `justifySelf` | Ebeveynin flex prop'ları (`horizontalAlign`/`verticalAlign`) + çocuğun `*Type`'ı |
+>
+> `style` rengin, tipografinin ve kenarlığın yeridir; kutu modeline ait her şey `appearance`'ta.
+
+> **Jeton kümesi kapalıdır ve tanınmayan jeton artık 400 döner.** Yukarıdaki beş alanın
+> (`paddingType` · `marginType` · `widthType` · `heightType` · `alignType`) kabul ettiği değerler
+> platformun kendi enum'larıdır; tanınmayan bir jeton eskiden **sessizce sıfırlanıyordu** —
+> 2026-09-06 koşusunda `paddingType: 'large'` gönderildi, HTTP 200 döndü ve kart `none` ile,
+> yani hiç iç boşluksuz çizildi (`S-2`). Platform bunu artık kabul edilen jetonları sayan bir
+> hatayla reddeder. Aynı kümeler `component_get` yanıtının `appearanceValues` alanında da döner,
+> `states` bayraklarının "true iken ne olur" karşılıkları ise `stateFlags` alanında —
+> `gap` gibi komponente özel jetonlar için `component_get` prop şemasına bakın.
+>
+> **`gap` jetonlarına benzeterek jeton uydurma:** `gap` bir container PROP'udur ve kendi kümesi
+> vardır; `appearance` alanlarıyla aynı sözlüğü paylaşmaz.
+
+## Dosya/görsel taşıyan prop'lar nesne bekler
+
+Görsel ya da dosya gösteren her yüzey (`datatable`'ın `image`/`file` kolonu başta olmak üzere)
+düz URL string'i değil **dosya nesnesi** ister: `{ absolute_path, display_name }` (etikette
+`fileName` de okunur). Düz string verilirse kaynak boş kalır ve hücre/kutu **sessizce boş**
+çizilir — istek 200 döner, hata yoktur (ölçüm: 09-04 koşusu Y-21). Entity'nin `FILE` alanı bu
+şekli zaten döner; ham bir URL'yi göstermek istiyorsan ya kolonu `url`/`link` yap ya da veriyi
+`{ absolute_path: '<url>', display_name: '<ad>' }` biçimine çevir. Komponentin kendi sözleşmesi
+için `component_get` `propNotes`.
+
 ## Komponent seçimi
 
 "Hangi işe hangi komponent" tablosu ve `table` / `datatable` karşılaştırması:

package/dist/resources/guides/entity.md

@@ -4,6 +4,12 @@ Buradaki kurallar gerçek projelerde (qm, hr, sms, klinik) **deneyerek doğrulan
 
 ## Slug seçimi — isim uzayı platformla paylaşımlıdır
 
+> **Yanıttaki `silentlyDropped`'ı oku.** Gateway her yazma çağrısında gönderdiğin gövdeyi
+> kaydedilenle karşılaştırır ve kayda geçmeyen alanları bu listede sayar — istek 200 döner, alan
+> yok sayılmıştır. Bu, hata listesinde hiç görünmeyen tek sinyaldir; yazmadan sonra yanıtın o
+> alanına bakmayı alışkanlık yap. Ayrıntılı örnek: `platform_guide('microservice')`.
+
+
 Her environment şeması ~75 platform tablosu taşır ve entity slug'ları bu tablolarla aynı isim
 uzayındadır. Çakışan slug `Migration failed … relation "X" already exists` verir ve **entity
 kaydı hiç oluşmaz**. Rezerve adlardan bilinenler: `branches`, `applications`, `caches`,
@@ -48,18 +54,24 @@ doğrudan kullan).
   silinemez. Buna karşılık **`entity_patch` ile alan EKLENEBİLİR** — telefon, departman, avatar,
   `musteri_tipi` gibi profil alanları `users`'a eklenebilir.
 - **Eklediğin alan `nullable: true` olmalı.** Platform bu tabloya EF üzerinden de yazıyor
-  (`organization_sync_users`) ve EF senin kolonunu bilmiyor; NOT NULL + varsayılansız bir kolon o
-  yolu kırar.
+  (bakım yolları dâhil) ve EF senin kolonunu bilmiyor; NOT NULL + varsayılansız bir kolon o yolu
+  kırar.
 - **`password` alanı `Hasher.Hash`'lidir.** Satır yazarken hash'i ifadeyle ürettir
   (`crypto.SHA256.encode(...)` — gerçek algoritma için `platform_guide('expressions')`); düz metin
   yazarsan giriş hiçbir zaman eşleşmez.
 - **`isAuditTrailActive`'i AÇMA.** `users` tablosunun audit kolonları EF tarafında `Ignore`
   edilmiş; `sys_*` eklemek EF'in bilmediği kolonlar yaratır.
-- **`organization_sync_users` Studio operatörlerini bu tabloya süper yönetici rolüyle kopyalar**
-  (yalnız production dışı environment'lara). Yani tablo hem platform operatörünü hem uygulama
-  kullanıcısını taşır ve roller `page.roleIds` yetkilendirmesiyle ortaktır.
+- **Tablo hem platform operatörünü hem uygulama kullanıcısını taşıyabilir** ve roller
+  `page.roleIds` yetkilendirmesiyle ortaktır. Ama **yeni projede boş gelir**: Studio operatörü
+  kendiliğinden uygulama kullanıcısı olmaz. İlk kullanıcıyı açmanın yolu
+  `platform_guide('getting-started')` §"İlk kullanıcıyı kim açar?".
 - **İlişki aynı datasource içinde kurulur.** `users` built-in datasource'tadır; entity'lerin dış
   bir DB'deyse `users`'a ilişki kuramazsın.
+- **Sonuç: kimlik gerektiren her uygulama built-in datasource'ta kurulur.** Entity'lerini dış bir
+  DB'ye açarsan giriş, `user.id` kapsaması ve roller kullanılamaz hâle gelir — bunlar `users`'a
+  ilişki üzerinden bağlıdır. Built-in her projeyle birlikte doğar (`datasource_list` çıktısında
+  `isBuiltIn: true`); `datasource_create` yalnız **kullanıcı kendi veritabanını verdiğinde**
+  çağrılır ve o kurulum bu bedeli kabul etmiş olur.
 
 ### Karar: `users`'ı genişlet mi, ayrı entity mi?
 
@@ -76,6 +88,50 @@ kurmak. O noktada iki ayrı kullanıcı tablosu, iki ayrı hash düzeni ve `midd
 ile hiç konuşmayan bir yetkilendirme olur. Gateway bu şekli ENT-009 ile hatırlatır (warn — bilerek
 yapıyorsan devam et).
 
+### Rol yönetimi — `roles` da sıradan bir entity
+
+**`role_create` diye bir tool yoktur ve olmayacak.** Rol tablosu built-in datasource'ta yaşar;
+uygulamanın rol açması/düzenlemesi gerekiyorsa yol her domain tablosuyla aynıdır: entity + kendi
+microservice ucun + sayfa. `role_list` yalnız okur.
+
+`roles` entity'sinin açtığı alanlar — fiziksel tabloda ayrıca `template_*` kolonları var, hepsi
+nullable, gateway'den görünmez:
+
+| alan | not |
+|---|---|
+| `id` | uuid PK; `page.roleIds` ve `microservice.roles` BUNU ister |
+| `name` | **UNIQUE** (`ix_roles_name`) — aynı adı ikinci kez yazan insert veritabanı hatasıyla düşer |
+| `slug` | **yetkilendirmenin karşılaştırdığı alan**; `role_list` bunu DÖNDÜRMEZ |
+
+**İki farklı anahtar, karıştırma:**
+
+- **id** → `page_create/page_update` ve `microservice_create` `roleIds` alanı (gövdede `roles` diye bir
+  yazma alanı YOKTUR; `microservice.roles` middleware'de RUNTIME şeklidir, `{ id, name: '<slug>' }`).
+  `role_list`ten okunur.
+- **slug** → `Authorized(user.roles)`, middleware'in kurduğu `user.roles` / `Page.user.roles`.
+  Platformun get-user sorgusu `roles`'u `user_roles` üzerinden **slug dizisi** olarak üretir
+  (`SELECT … ARRAY(SELECT r.slug FROM roles r INNER JOIN user_roles ur …)`), auth middleware
+  tarifi de aynı şeyi yapar — `platform_guide('middleware')` §Rol karşılaştırması SLUG üzerinden.
+
+Bu yüzden **slug'sız yazılan rol sessizdir:** insert 200 döner, satır `role_list`te görünür,
+`page.roleIds` ile bağlanır — ama `Authorized(user.roles)` o rol için hiçbir zaman tutmaz. Gateway
+bunu `ROL-002` ile uyarır.
+
+Rol açma reçetesi:
+
+1. `entity_get('01917ede-88a2-72ea-8397-2619e5d5dca0')` ile alan id'lerini al.
+2. Yazma ucunu kur: `microservice_create` `source:'table'`, `entityId` = roles, `operation:'create'`,
+   `fields` = `name` + `slug` (slug'ı ifadeyle ada göre üretmek serbest; **`super-admin` slug'ını
+   verme** — platform süper yöneticiyi `slug == 'super-admin'` ile arar).
+3. Rolü kullanıcıya bağlamak ayrı bir satırdır: `user_roles` (`01917ede-be1e-7d62-9a7c-d0ce4e4daaaf`)
+   `user_id` + `role_id`; çift **(user_id, role_id) UNIQUE**'tir, aynı bağı iki kez yazma.
+4. Yeni rol, kullanıcının bir sonraki isteğinde geçerlidir — middleware rolleri her çağrıda
+   tablodan okur; jeton tazelemeye gerek yoktur (rolleri jetona kendi gömen bir middleware
+   yazdıysan orada geçerli değil).
+
+`permissions` / `role_permissions` **Studio'nun yetki matrisidir**, uygulama sayfasının yetkisi
+değil; uygulama tarafında yetkiyi `page.roleIds` ve middleware ifadesi kurar.
+
 ## Alan tipleri (dbType + commonType İKİSİ birden verilir)
 
 | dbType (BÜYÜK HARF zorunlu) | commonType |
@@ -101,6 +157,11 @@ yapıyorsan devam et).
   `description`'a yaz: para → `INT8` kuruş (`*_minor`), süre → `INT4` dakika, yüzde →
   `INT4` ×100, puan → `INT4` ×10.
 - `commonType`'sız `UUID`/`BOOL` "isn't a supported database type" hatasıyla reddedilir.
+- **Katalogu okumak gerekiyorsa** (bu datasource'ta hangi `dbType` var, hangisi varsayılan, tip
+  hangi seçenekleri kabul ediyor, hangi tipe dönüştürülebilir) `datasource_configuration_options`
+  çağır: varsayılan yanıt ~5 KB'lık **özettir**; 816 kayıtlık collation DEĞER listesi yalnız
+  `includeCollations: true` ile gelir (tam yanıt ~45 KB). Katalogda görünen bir tipin
+  `entity_create` tarafından kabul edileceğini varsayma — yukarıdaki ondalık maddesi bunun kanıtı.
 
 ## Alan tipine karar verme (önce buna bak, sonra yaz)
 
@@ -138,13 +199,35 @@ olduğu için serbest metindir; `course_assignments.semester` (Güz/Bahar/Yaz) e
   "relationType": "none", "nullable": false,
   "isEnum": true,
   "valueOptions": [
-    { "value": "Aktif",      "icon": "#47ad10" },
-    { "value": "Bırakıldı",  "icon": "#888888" },
-    { "value": "Tamamlandı", "icon": "#0052CC" }
+    { "value": "Aktif",      "icon": "#47ad10", "order": 1 },
+    { "value": "Bırakıldı",  "icon": "#888888", "order": 2 },
+    { "value": "Tamamlandı", "icon": "#0052CC", "order": 3 }
   ] }
 ```
 
 - `valueOptions[].icon` bir **hex renktir**, ikon adı değil.
+- **`valueOptions[].order` seçeneğin İŞ SIRASIDIR (2026-09-05).** Huni, aşama, öncelik gibi
+  sıralı raporlarda sırayı sorguya statik `VALUES` listesi olarak gömmek gerekmez — sıra alan
+  tanımında durur ve `entity_get` ile geri gelir. Verilmezse `0`'dır; sıralı bir enum tanımlarken
+  doldurun, çünkü etiket değişince sorguya gömülmüş liste sessizce yanlış sıralar.
+- **Sıra SQL'den de okunur.** `value_options` tenant veritabanında `fields` tablosunda `jsonb`
+  kolondur ve anahtarları küçük harftir (`value` · `icon` · `order`). Sıralı bir rapor sırayı
+  buradan JOIN'ler:
+
+  ```sql
+  WITH ord AS (
+    SELECT opt->>'value' AS status, (opt->>'order')::int AS pos
+    FROM fields f CROSS JOIN LATERAL jsonb_array_elements(f.value_options) AS opt
+    WHERE f.entity_id = '<entity id>' AND f.slug = 'status')
+  SELECT o.status, COALESCE(c.total, 0) AS candidates
+  FROM ord o
+  LEFT JOIN (SELECT status, COUNT(*) AS total FROM candidates GROUP BY status) c
+    ON c.status = o.status
+  ORDER BY o.pos
+  ```
+
+  Ölçüldü 2026-09-05 (`query_preview`): dört durumluk bir enum bu sorguyla doğru sırada döndü,
+  sorguda tek bir sabit değer yok.
 - `isEnum` Studio tarafında `valueOptions.length > 0` ile türetilir; yine de ikisini birlikte ver.
 - **Enum PostgreSQL'de CHECK constraint üretir.** Var olan bir metin alanını enum'a çevirirken
   tablodaki değerler `valueOptions` içinde yoksa migration `check constraint ... is violated` ile
@@ -181,6 +264,11 @@ Girdi sınırları (`IncrementalCodeInput.TryParse`; ihlal edilirse nesne geçer
   (`EntityIncrementSequenceService.ResolveStartingCounterAsync`), yani elle `TLP-0005` yazdıktan
   sonra nesne biçimiyle yazılan ilk satır `TLP-0006` olur. `Counter: 1` vermek "1'den başla"
   demek değil, "taban 1" demektir.
+- **Kodu kaydetmeden görmek:** `row_next_code` aynı nesneyi alır (`prefix` · `separator` ·
+  `counter` · `digitCount`) ve sıradaki kodu sayacı ilerletmeden döner (`persist: false`).
+  `counter` ile `digitCount` platform tarafında **zorunludur** (`GetNextIncrementalCodeQuery`
+  validator'ı `NotEmpty` der, yani 0 kabul edilmez); eksik gönderirsen uç 400 verir — gateway de
+  bu ikisini zorunlu tutar (ölçüm: 09-02 D-2).
 - `properties.isCaseSensitive` büyük/küçük harf duyarlılığını belirler (`Field.IsCaseSensitiveIncremental`).
 - Sayfa tarafındaki karşılığı `incrementalinput` komponentidir.
 - `datasource_list.dataTypes` çıktısında bu tipi ayrı bir grup olarak görürsün; listede
@@ -194,6 +282,15 @@ parametre YOKTUR). Kısıt (`FieldDtoValidator`): `isLocalized: true` iken `prim
 · `unique` `false` olmalı ve `relationType: 'none'` olmalı — bunlardan biri doluysa platform
 reddeder.
 
+**`display: true` alanı `isLocalized` OLABİLİR** (ürün kararı 2026-09-08). Alan companion'a
+taşınır ama okuyucular onu çözer: `entity_get` companion alanını ana listeye katar, `row_list`
+bire-çok ilişkinin etiketini istek dilinde döndürür (`kategori_id: { id, ad }`).
+
+> **İlişkinin hedefinde de çalışır.** Çoka-çok listesi `[{ id, <display> }]` olarak istek dilinde
+> gelir, join'li (bire-çok) tablonun çok dilli kolonu mikroservis alan seçicisinde görünür ve
+> `returnScheme`'e girer. Çevirisi olmayan satır varsayılan dile düşer, listeden düşmez.
+> Ölçüldü 2026-09-08 (`dil-iliski2`: `etiketler[].ad` ve `kategori_id.ad` iki dilde).
+
 **Platform bunun için ayrı bir uç açmaz.** Bir entity'de `isLocalized` alanı olduğunda (create ya
 da update'te) platform otomatik olarak `{entity_slug}_localization` adlı **companion bir entity**
 kurar/genişletir:
@@ -208,6 +305,29 @@ language                              Text
 artı `(relation, language)` üzerinde unique index. Yani bir satırın Türkçe/İngilizce değerleri
 **ayrı satırlardır**, ana tabloda değil bu companion entity'de yaşar.
 
+**Satır araçları companion'ı senin yerine konuşur — normalde companion'a hiç dokunmazsın:**
+
+| İstediğin | Çağrı |
+|---|---|
+| Satırı bir dilde yaz | `row_create(row, localizations: { tr: {…}, en: {…} })` |
+| Toplu yaz | `row_create(rows: [{ …, localizations: { tr: {…} } }])` — `localizations` SATIRIN İÇİNDE |
+| Yalnız çeviriyi güncelle | `row_update(row: { <pk>: … }, localizations: { en: {…} })` — ana satır değişmese de olur |
+| Satırı bir dilde oku | `row_list(language: 'en')` / `row_get(language: 'en')` — alan düz gelir |
+| Bütün dilleri gör | `row_list(includeTranslations: true)` → satırda `localizations.<dil>.<alan>` |
+| Çok dilli alana filtre/sıralama | `row_list(language, filters)` — alan slug'ı düz yazılır |
+
+`language` verilmezse platform `Accept-Language`'a, o da yoksa projenin varsayılan diline düşer;
+bölgeli kod ('tr-TR') kabul edilir ve gateway 'tr'ye indirger. **Okumada çevirisi olmayan alan
+varsayılan dile düşer ama filtre ve sıralama fallback GÖRMEZ** — o satır filtrede eşleşmez ve
+sıralamada `NULL` sayılır.
+
+Dil satırlarını platform yazar: `row_delete` companion satırlarını ana satırdan önce kendisi siler,
+desteklenmeyen bir dil kodu 400 döner ve ana satır da yazılmaz. Yanıtta
+`gatewayNormalized: ["platform 'localizations' alanını tanımıyor …"]` görürsen platform bu
+sözleşmeden eski bir sürümdedir; gateway o zaman companion'a kendisi yazar ve `localizations.count`
+ile kaç dil satırı yazdığını söyler — `localizationsFailed` ise ana satır yazılmış, dil satırları
+yazılmamıştır. Aşağıdaki elle tarif yalnız o eski yol ve `rows` ile toplu yazma için gerekir.
+
 **Kullanım (tamamı mevcut genel araçlarla, yeni tool GEREKMEZ):**
 
 ```
@@ -219,6 +339,14 @@ artı `(relation, language)` üzerinde unique index. Yani bir satırın Türkçe
 
 `{fk_slug}` companion entity'nin `entity_get`'inde görünen ilişki alanının slug'ıdır (ana entity
 adından türetilir); satırı elle kurmadan önce mutlaka `entity_get` ile doğrula, tahmin etme.
+Companion'ı adından değil **ana entity'nin `localizationEntityId` alanından** bul — ad kalıbı
+(`{slug}_localization`) bir kolaylıktır, bağ ise `entity_get`'in döndürdüğü bu id'dir.
+
+> **Toplu uçta `localizations` SATIRIN İÇİNDEDİR** (2026-09-08): `rows: [{ kod: 'A1',
+> localizations: { tr: { ad: 'Kalem' }, en: { ad: 'Pen' } } }]`. Üst düzeye koymak toplu uçta
+> hangi satıra ait olduğunu söyleyemeyeceği için gateway tarafından reddedilir. `localizations`
+> bu yüzden hem okuma hem yazma tarafında **ayrılmış bir anahtardır**: `includeTranslations: true`
+> ile okunan satırda da aynı adla gelir, yani bu adda gerçek bir kolonun olamaz.
 
 ```jsonc
 // GUID anahtar
@@ -249,6 +377,10 @@ adından türetilir); satırı elle kurmadan önce mutlaka `entity_get` ile doğ
 
 Gateway bu iki kuralı ENT-006 (PK identity/tip uyumu) ve ENT-007 (enum şekli) olarak denetler.
 
+> **Çok dilli bir entity TEK adımda silinir.** `entity_delete` ana entity'ye uygulanır, companion
+> da onunla düşer. (Aynı gün daha erken bir ölçümdeki "önce companion'ı sil" adımı artık geçersiz;
+> EF izleme hatası giderildi. Ölçüldü 2026-09-08, `dil-iliski`.)
+
 ## Application bağı — ne yapar, ne yapmaz
 
 `applicationIds` **create'te platformca bağlanır** (`CreateEntityCommand` → `EntityService.CreateAsync`
@@ -273,8 +405,9 @@ Karar: **Studio'dan yönetilecek entity'lerde `applicationIds` ver; yalnız API'
 boş bırakmak geçerli bir tercihtir** (ENT-002 warn'ı bunu hatırlatır, zorunlu kılmaz).
 
 > `entity_patch` uyarısı: `EntityDto` çıktıda `applications` (nesne listesi) döner ama
-> `UpdateEntityCommand` girdide `applicationIds` (Guid listesi) okur. Gateway bu çeviriyi
-> kendisi yapar; ham PUT atarken **siz yapmazsanız her güncelleme bağı sessizce siler.**
+> `UpdateEntityCommand` girdide `applicationIds` (Guid listesi) okur. `PATCH /entities/{id}`
+> yolunda bu çeviriyi **platform** yapar; ham PUT atarken **siz yapmazsanız her güncelleme bağı
+> sessizce siler.**
 
 ## İlişkiler (doğru şekil — 57 alanla doğrulandı)
 
@@ -300,6 +433,120 @@ boş bırakmak geçerli bir tercihtir** (ENT-002 warn'ı bunu hatırlatır, zoru
 - İki entity'yi önce ilişkisiz oluşturup ilişki alanını sonra `entity_patch` ile eklemek en
   güvenli sıra (id'ler ancak oluşunca belli olur).
 - `display: true` entity başına tek alanda olabilir; ilişkilerde görüntülenen değer bu alandır.
+- **Boş ilişki `null` değil boş nesne `{}` döner** (ölçüm: İK koşusu D-8, 2026-09-01). JS'te
+  `{}` truthy'dir: `if (row.manager_id)` "yöneticisi var" der. Varlık kontrolünü
+  `row.manager_id?.id` üzerinden yap. (Backend'in `null` döndürmesi P0-6 olarak planlı; o gelene
+  dek bu şekil geçerlidir.)
+
+## Index'ler
+
+`indexes` alanı `entity_create` ve `entity_update` gövdesinde geçer.
+**Studio'da index ekranı YOKTUR** — bu alan platformun tek index yönetim yüzeyidir, yanlış
+yazdığın bir index'i arayüzden görüp düzeltemezsin. Tam şema:
+`ngapps://schemas/CreateEntityCommand` (`EntityIndexDto`).
+
+```jsonc
+{ "indexes": [
+  { "id": "<guid, opsiyonel — verilmezse platform üretir>",
+    "name": "candidate_company_status",
+    "unique": true,
+    "fieldIds": ["<field id>", "<field id>"] }
+] }
+```
+
+Alan adları 422 ile kendini söyler; **sessiz olan kurallar** şunlar:
+
+- **`unique` — `isUnique` DEĞİL.** Yanlış anahtar hata vermez, platform onu yok sayar ve index
+  UNIQUE OLMADAN kurulur. Aynı tuzak `fields` için de var, ama o 422 döner
+  (`Indexes[0].FieldIds: 'Field Ids' must not be empty`); doğru ad **`fieldIds`**.
+- **`fieldIds` sırası bileşik index'in KOLON SIRASIDIR.** Dizideki konum `Order` olarak
+  yazılır, DDL kolonları o sırayla kurar. `(company_id, status)` ile `(status, company_id)`
+  farklı index'lerdir; öndeki kolon önek sorgularını hızlandıran kolondur.
+- **`entity_update` gövdesinde `indexes` YOKSA entity'nin BÜTÜN index'leri silinir** — kayıt da
+  düşer, `DROP INDEX` de koşar. Gateway `entity_update` çağrısında alan verilmemişse mevcut
+  index'leri gövdeye taşır ve bunu `gatewayNormalized` ile bildirir; silmek istiyorsan
+  `indexes: []` yazarak **açıkça** iste.
+- **Var olan bir index'te `name` / `unique` / `fieldIds` değiştirmek İŞE YARAMAZ:** platform farkı
+  yalnız `id` üzerinden alır, aynı `id` ile yapılan değişiklik UYGULANMAZ ve hata da vermez.
+  Değiştirmenin yolu index'i silip **yeni bir `id`** ile yeniden yazmaktır.
+
+**Sıra:** `fieldIds` alan **id'si** ister, slug değil — ve alan id'lerini platform ÜRETİR
+(`FieldDto.Id` gövdede yoksa sunucuda atanır). İki geçerli yol var:
+
+1. Entity'yi index'siz kur, `entity_get view:'outline'` ile alan id'lerini oku, index'i
+   `entity_patch` ile ekle. **Varsayılan yol budur.**
+2. Tek çağrıda kuracaksan `fields[].id`'leri kendin ver ve aynı guid'leri `fieldIds`'e yaz.
+   (Ölçüldü 2026-09-07: üç alanı ve bileşik unique index'i olan bir entity tek `entity_create`
+   çağrısıyla kuruldu.)
+
+Var olmayan bir alan id'si reddedilir ama **hata mesajı yanıltıcıdır**: platform
+`This record is in use. Related table: 'Fields', column: 'Field Id'. Please remove its relations
+first.` der — sanki bir bağımlılık varmış gibi. Gerçek sebep bunun tersidir: o id'de alan YOKTUR.
+Bu mesajı alınca bağımlılık aramaya gitme, `fieldIds`'i alan listesiyle karşılaştır.
+
+Doğrulama kuralları (hepsi 422 döner):
+
+- `fieldIds` boş olamaz ve aynı alanı iki kez taşıyamaz.
+- `name` zorunlu; **önek hariç** en fazla 32 karakter.
+- Index adları entity içinde benzersizdir (büyük/küçük harf duyarsız).
+
+Ada dokunma: platform ada `IX_<entity id'sinin 5 hanesi>_` öneki ekler ve okuma yolu **önekli**
+adı döner. Gidiş-dönüş kararlıdır — okuduğun adı geri yazabilirsin, önek ikinci kez eklenmez.
+
+Kurulabilen tek şekil **artan (ASC), çok kolonlu, opsiyonel UNIQUE** b-tree'dir. `DESC`, kısmi
+index (`WHERE`), ifade index'i, `INCLUDE` ve GIN/GiST platform yüzeyinde yoktur; bunlardan birine
+ihtiyacın varsa `platform_gap_report` ile bildir.
+
+Platformun kendi ürettiği örnek, bileşik unique için okunabilir bir kalıptır: çoklu dilli alan
+kurulunca yan entity'ye `(relation, language)` üzerinde unique bir index açılır — yani "bir
+satırın her dilde en fazla bir çevirisi olur" kuralı index'le zorlanır.
+
+Yazdığın index'i `entity_get view:'outline'` çıktısındaki `indexes` bloğundan doğrula; DDL'in
+gerçekten kurulduğunu görmek istiyorsan `query_preview` ile
+`select indexname, indexdef from pg_indexes where tablename = '<slug>'` sorgusunu koştur —
+`entity_get` yalnız metadata'yı kanıtlar, `CREATE UNIQUE INDEX` satırını değil.
+
+## Backend doğrulama sınırları (ENT-015 · ENT-016 · ENT-017 · ENT-018 · ENT-004 · ENT-013)
+
+Bu tablo `CreateEntityCommandValidator` / `UpdateEntityCommandValidator` / `FieldDtoValidator`'ın
+aynasıdır. Gateway aynı kuralı **istek gitmeden** `block` olarak uygular ve mesaj platformun 422
+cümlesidir — 2026-09-08 koşusunda bu kurallar ancak platforma gidip öğrenildi (index adı 33
+karakter, primaryKey yok). Tam katalog, kaynak referanslı JSON: `ngapps://rules/backend-constraints`.
+
+| Alan | Kural | ID |
+|---|---|---|
+| `name` | zorunlu, en fazla 255 karakter | ENT-015 |
+| `description` | en fazla 1024 | ENT-015 |
+| `slug` | zorunlu (create) | ENT-015 |
+| `fields[].name` | en fazla 50 | ENT-015 |
+| `fields[].description` | en fazla 512 | ENT-015 |
+| `fields[].slug`, `fields[].dbType` | zorunlu; dbType en fazla 50 | ENT-015 |
+| `fields[]` | **tam 1** alan `primaryKey: true` — "Please select exactly one primary key." | ENT-016 |
+| `fields[]` | adlar tekil (büyük/küçük harf duyarsız): create `name`, update `slug` üzerinden | ENT-016 |
+| `fields[].display` | en fazla 1 alan | ENT-004 |
+| `primaryKey` / `identity` | `nullable: false`; PK ayrıca `hidden: false` | ENT-017 |
+| `isLocalized` | `primaryKey`/`identity`/`unique` yok, `relationType: 'none'` | ENT-017 |
+| `folderId` | yalnız `commonType: 'file'` alanında | ENT-017 |
+| `properties.generationType` | yalnız `commonType` `guid` ya da `number` | ENT-017 |
+| `commonType` / `defaultValueType` / `relationType` | sözlükten; bilinmeyen değer 400 `InvalidEnumTokenException` (`multiFile` diye bir tip YOK) | ENT-017 |
+| `recordTransferMode: 'specific'` | `transferRowIds` dolu, tekil, boşsuz | ENT-018 |
+| `indexes[]` | ad önek hariç en fazla 32, `fieldIds` dolu ve tekil, adlar tekil | ENT-013 |
+
+**Birincil anahtar kalıbı** (bu rehberde yoktu; 2026-09-08 koşusunda iki hatalı çağrı + bir
+keşif turuna mal oldu):
+
+```jsonc
+{ "slug": "id", "name": "Id", "dbType": "UUID", "commonType": "guid",
+  "primaryKey": true, "unique": true, "identity": true, "nullable": false,
+  "properties": { "generationType": 0 } }
+```
+
+**Create tuzağı:** create yolu alan adlarını `name` üzerinden tekil arar. `name` yazılmayan iki alan
+aynı (boş) gruba düşer ve platform "Duplicate value: 'Slug'" der — mesaj slug'ı suçlar, sebep ad
+eksikliğidir. Her alana `name` yaz; update yolu aynı denetimi `slug` üzerinden yapar.
+
+Satır yazma da aynı katalogdan denetlenir (ROW-002, `row_create` / `row_update`): satır sözlüğü
+boş olamaz, boş anahtar taşıyamaz, bütün değerleri null olamaz; toplu yolda her satır ayrı bakılır.
 
 ## TEXT kolonunda JSON: yazarken string, okurken NESNE döner
 
@@ -328,8 +575,19 @@ bilmezsen "kayıt bozulmuş" sanırsın.
 
 ## Satır işlemleri
 
+- `row_*` tool'ları `entityId` olarak slug kabul eder (`employees`, çakışmada
+  `BuiltIn/employees`); gateway id'ye çevirir ve yanıtta `gatewayResolved` ile bildirir.
 - `row_create/row_update` anahtarları **field slug'larıdır** (name değil): `{"code": "IK"}`.
+- **Toplu yazımın (`rows[]`) id döndürmesine GÜVENME.** 2026-09-05'te uç `data: [{ "<pk slug>":
+  değer }, …]` döndürüyordu; 2026-09-07 ölçümünde iki ayrı entity'de **boş gövde** döndü (gateway
+  onu `{success: true}` diye gösterir) — satırlar yazıldı ama anahtarlar gelmedi. Fark `B-63`
+  olarak takipte. Yazdığın satırların anahtarları lazımsa yanıta bel bağlama, `row_list` çek ve
+  bu turu bütçene ekle. Daha iyisi: türetilmiş satırı bu id'lerle kurma — §"Toplu ve türetilmiş
+  satır"daki SQL yolunda id hiç dolaşmaz.
 - Yazdıktan sonra `row_list` ile geri oku; ilişki alanları `{ id, name }` nesnesi olarak döner.
+- **Boş to-one ilişki `null` döner**, boş nesne değil — `if (row.manager_id)` kontrolü doğru
+  çalışır (İK koşusu D-8; 2026-09-03 öncesinde `{}` dönüyordu ve JS'te truthy'ydi). Boş
+  many-to-many alan `[]` döner.
 - **`isAuditTrailActive: true` ile KURULAN entity'ye satır yazılamaz.** `sys_*` kolonları create
   yolunda oluşmaz, yalnız ilk **etkin** `entity_update`'inde eklenir; o ana kadar **her**
   `row_create` şu hatayla 500 verir:
@@ -366,15 +624,145 @@ bilmezsen "kayıt bozulmuş" sanırsın.
 - **`defaultValueType: "static"` sessizce `"none"`e düşer** — DB varsayılanı kurulmaz. Bu yüzden
   her `BOOL`/sayısal alanı **her** `row_create`'te ve her workflow write adımında **açıkça** yaz;
   "varsayılanı platform koyar" varsayımı `null` satır üretir.
-- **`row_list`'in `filters` parametresi çalışmıyor** — denenen her biçim
-  `Failed to invoke 'CompileNestedCondition'` ile 500 verir. Daraltmayı `selectedFields` +
-  `order` + `pageLength` ile yap, ya da doğrulamayı entity satırından değil **ucun kendisinden**
-  (`microservice_execute`) yap.
-- **`users`'ta `row_create` verdiğin `id`'yi yok sayar** (PK `identity` + `generationType: 0`);
-  Studio operatörünü proje tablosuna aynı id ile taşıyamazsın, eşleme e-posta üzerinden kurulur.
+- **`row_list.filters` desteklenir.** Tekil filtre `{ field, operator, value, filterType:'single' }`,
+  grup filtre `{ filterType:'group', conditionType, children:[...] }` biçimindedir. Tekil filtrede
+  `field`, grupta `children` zorunludur; `in`/`notin` operatörleri liste değer ister. Eksik/yanlış
+  şekiller SQL derleyicisine düşmeden alanı ve beklenen şekli söyleyen doğrulama hatası döner.
+- **`row_create` identity Guid birincil anahtara verdiğin `id`'yi artık korur** — 2026-09-04
+  öncesinde platform değeri sessizce kendi ürettiğiyle değiştiriyordu (`EntityRuntimeValidator`);
+  şimdi değer verilmişse o yazılır, verilmemişse üretilir. Seed ve veri taşımada "gönderilen id ile
+  oluşan id farklı" sınıfı buradan geliyordu. `users` tablosunun kendi kısıtları ayrıdır; oradaki
+  eşlemeyi e-posta üzerinden kurmak en güvenli yoldur.
 - Silmeden önce `entity_dependencies` / `dependency_graph`.
 
+## Toplu ve türetilmiş satır
+
+`row_*` bir **veritabanı yönetim yüzeyidir**: satırı gövdede taşır, iş kurallarını koşturur,
+anahtarı üretir. **Var olan satır kümesinden TÜRETİLEN** bir küme onun işi değildir — durum
+geçmişi, hareket/log tablosu, junction dolgusu, backfill. İki koşu bunu elle yazdı (2026-09-05:
+802 satır, 2026-09-06: 552 satır); ikincisinde koşunun 65 dakikasının **~21'i** tek bu faza gitti,
+gateway süresi ise aynı fazda toplam 7.9 sn'ydi — maliyetin tamamı gövde yazmaktı.
+
+Türetilmiş satırın yolu **ham SQL**'dir: `INSERT … SELECT` kaydedilir ve query kaynaklı bir uçtan
+çalıştırılır. `candidate_id` gibi bağlar `SELECT`'in içinde kalır, hiçbir id yanıttan yanıta
+taşınmaz.
+
+| Satırlar nereden geliyor | Yol |
+|---|---|
+| Dışarıdan: kullanıcı verisi, içe aktarma, sabit liste | `row_create` / `row_update` |
+| Var olan satırlardan türetiliyor: geçmiş, hareket, junction, backfill | kayıtlı `INSERT … SELECT` + `source: 'query'` uç |
+
+> **Ham SQL UYGULAMA katmanını atlar, VERİTABANI katmanını atlamaz.**
+> Koşmayan: automation'lar (satır olayı hiç doğmaz), `EntityRuntimeValidator`'ın tip ayrıştırma
+> ve identity anahtar üretimi, incremental kod üretimi, çoklu dilli companion yazımı, audit izi.
+> **Koşan:** tablonun bütün veritabanı kısıtları — NOT NULL, FK, UNIQUE ve **enum'un CHECK
+> constraint'i**. Ölçüldü: `source` alanına listede olmayan bir değer yazmak
+> `23514 … violates check constraint "check_<alan id'si>"` veriyor (HTTP 500). Kısıt adı alanın
+> **id'sini** taşır (tireler alt çizgi olur), kolon adını değil — 23514 alırken suçluyu böyle
+> bulursun. Yani enum'a çöp yazamazsın, ama iş kuralın automation'daysa o çalışmaz:
+> seed/backfill için istediğin tam olarak budur, **iş kuralı çalışması gereken satırı bu yoldan
+> yazma.**
+
+### Reçete (uçtan uca ölçüldü, 2026-09-07)
+
+```jsonc
+// 1) sorguyu KAYDET — query_create
+{ "name": "Aday Geçmişi Dolgusu", "slug": "seed_candidate_history",
+  "datasourceId": "<built-in datasource id>",
+  "rawQuery": "INSERT INTO status_history (id, candidate_id, status, occurred_at) SELECT gen_random_uuid(), c.id, c.status, c.applied_at FROM candidate c" }
+
+// 2) ucu aç — microservice_create (MS-002 warn'ı bekleniyor: ham SQL bilinçli tercih)
+{ "name": "Aday Geçmişi Dolgusu", "slug": "seed-candidate-history",
+  "description": "Var olan adaylardan durum geçmişi satırlarını üretir (tek seferlik dolgu).",
+  "type": "rest-api", "httpMethod": "post", "url": "seed-candidate-history",
+  "source": "query", "queryId": "<query id>" }
+
+// 3) çalıştır — microservice_execute { method: 'POST' } → HTTP 204, GÖVDE YOK
+// 4) doğrula — row_list('<hedef entity>') → satırlar burada; sayım tek doğrulama yolu
+```
+
+### Ölçülmüş sözleşme
+
+- **Tablo adı = entity slug'ı, kolon adı = alan slug'ı.** İlişki alanının kolonu da kendi
+  slug'ıdır (`src_id`), ayrı bir FK adı türetilmez. Şema öneki YAZMA: bağlantı zaten ortamın
+  şemasına bağlıdır.
+- **Anahtar sözleşmesi anahtar TİPİNE göre TERSİNE döner** — ikisi de `identity: true` +
+  `generationType: 0` olduğu hâlde:
+
+  | Anahtar | Ham SQL'de | Yanlışta ne olur |
+  |---|---|---|
+  | `UUID` / `guid` | anahtarı **SEN ver** (`gen_random_uuid()`) | `23502: null value in column "id" … violates not-null constraint` (HTTP 500) |
+  | `INT2/INT4/INT8` / `number` | anahtarı **HİÇ VERME** | `428C9: cannot insert a non-DEFAULT value into column "id" … GENERATED ALWAYS` (HTTP 500) |
+
+  Sebebi: GUID anahtarı **uygulama** üretiyor (`EntityRuntimeValidator`, `Guid.CreateVersion7()`),
+  kolonun veritabanı varsayılanı yok; INT anahtar ise Postgres `GENERATED ALWAYS` identity'sidir.
+  Alan tanımındaki `specifications.hasAutoData: true` bir **Studio ipucudur, DB varsayılanı
+  değildir** — ham SQL'de sana anahtarı üretmez.
+- **`gen_random_uuid()` v4 üretir**, platformun kendi anahtarları v7'dir (zaman sıralı). Aynı
+  tabloda iki sürüm karışır; anahtara göre sıralayan bir ekranın varsa sıralamayı zaman
+  kolonundan yap.
+- **`query_preview` yazan sorguyu çalıştırır ve GERİ ALIR ve bunu SÖYLEMEZ.** Yanıt yalnız
+  `{ affectedRowCount, elapsedMilliseconds }` taşıyor; `affectedRowCount` gerçek sayıyı döndüğü
+  için başarı gibi görünüyor, tabloda satır kalmıyor. Kalıcılığın tek kanıtı sonradan çekilen
+  `row_list`'tir.
+- **`query_create` gövdeyi kaydetmeden önce bir kez koşturur ve geri alır** — yazan bir sorguyu
+  kaydetmek satır bırakmaz, ama SQL hatası kayıt anında patlar. Yazan sorgunun `returnScheme`'i
+  boş döner (yanıt şeması yalnız okuyan sorgudan üretilir).
+- **Uç `204` ve BOŞ gövde döner** — `affectedRowCount` bile gelmez. Kaç satır yazıldığını
+  `row_list` ile say.
+- `;` ile birden çok ifade ya da `RETURNING` içeren sorgu `multiple` tipine düşer ve okuma
+  yolundan koşar (kaynak: `PostgreSqlConnector.FindQueryType`); tek ifadeli sade `INSERT` için
+  tip `insert`'tür.
+- **`WITH … INSERT` (CTE önekli yazma) BUGÜN REDDEDİLİYOR.** Ölçüldü 2026-09-07: `query_create`
+  `500 "Please correct the query syntax."`, `query_preview` `400 "Please use a supported query
+  type."` veriyor. Sorgu Postgres'te geçerlidir; reddeden, platformun tip sınıflandırıcısıdır
+  (`FindMainCommand` `WITH`i çözemeyip `NotSupportedQueryTypeException` atıyor). Depo kodunda
+  `WITH` çözümü **var** (`bcf722d1`, 2026-09-04) ama canlıda yok — `B-63`. **Bugünkü yazım:**
+  CTE yerine `JOIN (VALUES …) AS x(kolon, kolon)` kullan ve ifade `INSERT` ile başlasın.
+
+### Merdiven kalıbı: aşama geçmişi (S-4'ün tam şekli)
+
+Her adayın **bulunduğu aşamaya kadarki** geçişlerini üretir. 300 adaydan **579 satır** tek çağrıda
+yazıldı (ölçüldü 2026-09-07); huni piramidi 210 → 135 → 90 → 60 → 39 → 24 → 12 → 6 → 3, FK'sız
+satır 0, `applied_at`'ten önceye düşen satır 0.
+
+```sql
+INSERT INTO candidate_status_history (id, candidate_id, from_status, to_status, occurred_at)
+SELECT gen_random_uuid(), c.id, p.stage, n.stage,
+       c.applied_at + (n.pos - 1) * interval '3 days'
+FROM candidate c
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS cur(pos, stage) ON cur.stage = c.status          -- adayın bugünkü aşaması
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS n(pos, stage) ON n.pos > 1 AND n.pos <= cur.pos  -- ona kadarki her aşama
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS p(pos, stage) ON p.pos = n.pos - 1               -- bir önceki aşama
+```
+
+Merdiven listesi CTE olamadığı için üç kez tekrarlanır (yukarıdaki `WITH` maddesi). Zaman damgası
+`applied_at`'ten türetildiği için geçmiş **tarihseldir** — `UtcNow()` tuzağı (`AUT-003`) bu yolda
+hiç doğmaz, çünkü automation yoktur.
+
+Toplu **güncelleme** de aynı yola aittir: var olan satırlardan hesaplanan bir damga/toplam için
+`UPDATE … FROM` yaz, satırları `row_update`'in gövdesinde taşıma.
+
 ## Büyük entity'lerde
 
 `entity_get view:'outline'` alan listesi; `view:'part', part:'fields[slug=email]'` tek alan;
 değişiklik `entity_patch`.
+
+## Sürüm ve 409 — `entity_patch` tam gövde YAZMAZ
+
+`entity_patch` okuduğu tanımın üstüne JSON Patch uygular ama geri **tam gövde göndermez**: op'lar
+platformun `PATCH /entities/{id}` ucuna `{ baseVersion, ops }` olarak gider ve yalnız değişen
+alanlar yazılır. Bir alan adı değişimi `fields` tablosunda **tek** UPDATE üretir (ölçüldü
+2026-09-08, `pg_stat_user_tables`).
+
+`baseVersion` okunan kaydın `version` alanıdır ve zorunludur (eksikse 422). Sen okuduktan sonra
+kayıt değiştiyse platform **409 `AggregateVersionConflictException`** döner ve HİÇBİR op uygulanmaz
+— `entity_get` ile yeniden okuyup patch'i güncel hâle göre kur, aynı op'ları eski sürümle tekrar
+gönderme.
+
+`version` bir **string**tir (mikrosaniye zaman damgası, `Number.MAX_SAFE_INTEGER`'ın üstünde):
+sayıya çevirirsen yuvarlanır ve her patch 409 döner. Yanıttaki `newVersion` bir sonraki patch'in
+`baseVersion`'ıdır.