docs: v0.0.60 release notes + Türkçe migration rehberi

blog-migration/2026-06-13-v0-0-60-migration.md

@@ -0,0 +1,252 @@
+---
+slug: v0060-migration
+title: "vNext v0.0.60 Migration Rehberi"
+authors: [vnext-team]
+tags: [migration]
+date: 2026-06-13
+---
+
+Bu rehber, **vNext v0.0.60** ile gelen yeni yetenekleri ve mevcut bir domain projesini bu sürüme taşırken atılması gereken adımları anlatır. Sürüm beş ana başlık getiriyor: yeniden kullanılabilir **sys-mappings** bileşeni ve sandbox'lı **custom C# helper**'lar, **rol bazlı state alias**, tutarlı **FunctionScope** zorunluluğu, **Operations & Observability** sıkılaştırmaları ve **yapılandırılabilir asenkron transition** işletimi.
+
+Bu sürümle birlikte bileşen şeması **0.0.46**'ya yükseldi. Doğrulama yapmadan önce domain projenizde `@burgan-tech/vnext-schema` paketini güncelleyin.
+
+> Teknik release notları için: [Release v0.0.60](/blog/release-v0-0-60).
+
+{/* truncate */}
+
+---
+
+## 1. Mappings Bileşeni & Custom C# Helper'lar
+
+vNext'e yeni bir sistem bileşeni eklendi: **`sys-mappings`** (kısaca *Mappings*). Mapping bileşeni, script mapping kodlarının **yeniden kullanılabilir**, **versiyonlanabilir** ve daha verimli kullanılmasını sağlar. Ayrıca plugin özelliği ile 3rd-party kütüphane/DLL'leri embed ederek kullanım sağlar — bu da business case'lerinde sıkça ihtiyaç duyulan ayrı "utilities API" gereksinimini ortadan kaldırır.
+
+### Ne değişti
+
+- Geliştiriciler kendi C# yardımcı sınıflarını `.csx` olarak — tıpkı flow, task ve view'lar gibi — bir **bileşen** olarak yükleyebilir.
+- Bu helper'lar bir flow tanımının mapping'inden referans verilir; runtime önce helper sınıflarını derler, ardından mapping'i bunlara karşı derleyip çalıştırır.
+- Helper'lar **sandbox** altında, içerik hash'i ile cache'lenerek çalıştırılır.
+
+### Bileşen ağacı ve `vnext.config.json`
+
+Domain bileşen ağacına `Mappings/` dizini eklendi:
+
+```plaintext
+├── <domain>/
+│   ├── Extensions/
+│   ├── Functions/
+│   ├── Schemas/
+│   ├── Tasks/
+│   ├── Views/
+│   ├── Mappings/      # YENİ
+│   └── Workflows/
+├── vnext.config.json
+```
+
+`vnext.config.json` `paths` ve `exports` blokları `mappings` ile genişletildi:
+
+```json
+{
+  "domain": "my-domain",
+  "paths": {
+    "mappings": "Mappings"
+  },
+  "exports": {
+    "mappings": []
+  }
+}
+```
+
+### Mapping objesindeki `scripts` bloğu
+
+Tüm mapping objelerinde (`viewRule`, `rule`, transition mapping, subflow mapping, task mapping, extension/function task mapping) yeni bir **`scripts`** objesi tanımlanabilir. `scripts.helpers[]` bir **referans dizisidir** (string değil — `key`/`version`/`domain`/`flow` alanları olan objeler), `scripts.allowedAssemblies[]` ise o mapping'e özel sandbox izinlerini global temel listenin üzerine ekler:
+
+```json
+{
+  "mapping": {
+    "location": "./src/UserSessionMapping.csx",
+    "code": "",
+    "encoding": "NAT",
+    "scripts": {
+      "helpers": [
+        {
+          "key": "json-helper",
+          "version": "1.0.0",
+          "domain": "core",
+          "flow": "sys-mappings"
+        }
+      ],
+      "allowedAssemblies": [
+        "Newtonsoft.Json"
+      ]
+    }
+  }
+}
+```
+
+Aynı `scripts` bloğu flow konfigürasyonuna da (`attributes.scripts`) eklenebilir:
+
+```json
+{
+  "attributes": {
+    "type": "F",
+    "scripts": {
+      "helpers": [
+        { "key": "rsa-crypto", "version": "1.0.0", "domain": "core", "flow": "sys-mappings" }
+      ],
+      "allowedAssemblies": [ "System.Security.Cryptography" ]
+    }
+  }
+}
+```
+
+### `REF` encoding
+
+`code` encoding tipine yeni bir değer eklendi: **`REF`**. Bir mapping, kod gömmek yerine bir `sys-mappings` bileşenine referans verebilir:
+
+```json
+{
+  "mapping": {
+    "encoding": "REF",
+    "code": {
+      "key": "initial-mapping",
+      "version": "1.0.0",
+      "flow": "sys-mappings",
+      "domain": "core"
+    }
+  }
+}
+```
+
+> **Kısıt:** `sys-mappings` bileşeninin kendisi `REF` kullanamaz — referans hedefinin kendisidir, kendine referans veremez.
+
+### Sandbox
+
+Helper'lar iki katmanlı derleme zamanı kapısı (reference allow-list + yasaklı API analizörü) ile kısıtlanır ve paylaşımlı, toplanabilir bir `AssemblyLoadContext` içinde derlenir. `allowedAssemblies` ile mapping bazında verilen izinler global temel listenin (`Scripting:Sandbox:AllowedAssemblies`) üzerine eklenir — yani bir flow, herkesin temel listesini genişletmeden yalnızca kendi helper'ının ihtiyacı olan assembly'yi açar.
+
+### Migrasyon adımları
+
+1. `vnext.config.json`'a `paths.mappings` ve `exports.mappings` alanlarını ekleyin; `Mappings/` dizinini oluşturun.
+2. Tekrar eden mapping kodlarını `sys-mappings` bileşenlerine çıkarın; flow/mapping'lerden `scripts.helpers[]` ile referans verin.
+3. Helper'ınızın baz dışı bir assembly'ye ihtiyacı varsa `scripts.allowedAssemblies[]` ile tanımlayın. Sandbox ayarları (varsayılan ban listesi, `using`'ler, referanslar) için [Scripting / Sandbox Yapılandırması](/docs/configuration/scripting) sayfasına bakın.
+
+> İlgili dokümanlar: [Mapping Bileşeni (sys-mappings)](/docs/components/mapping-component) · [Mapping Rehberi](/docs/components/mappings) · [Scripting / Sandbox Yapılandırması](/docs/configuration/scripting)
+
+---
+
+## 2. State Alias — Rol Bazlı State Görünürlüğü
+
+State Function, client tarafında **long-polling** ile süreç durumunu döner. Client'ta başlayan bir iş akışı backoffice'e geçtiğinde **Fraud, KPS, Limit** gibi iç kontrol state'lerine uğrar. Client bu noktada sorgulama yaptığında ham `state.key` döner — iç süreç adımlarının client'a sızması bir **güvenlik açığı** oluşturabilir.
+
+### Ne değişti
+
+State'lere opsiyonel bir **`alias[]`** dizisi tanımlanabilir. Alias, aktör/rol bazlı yapı sayesinde hangi client'ın ne göreceğini belirler; aynı zamanda **çoklu-dil (multi-localization)** desteği sağlar. İç state kimliği değişmez — alias yalnızca **sunum** katmanını etkiler; transition'lar, kalıcılık ve iş akışı mantığı aynı `state.key` üzerinden çalışmaya devam eder.
+
+Her `alias` öğesi şu alanları taşır:
+
+| Alan | Tip | Zorunlu | Açıklama |
+|------|-----|---------|----------|
+| `name` | string | Evet | Alias adı. İstek diline uygun bir `label` bulunamazsa fallback olarak döner. |
+| `roles` | array | Evet | Bu alias'ın geçerli olduğu roller (`minItems: 1`). **DENY her zaman ALLOW'u geçersiz kılar.** |
+| `labels` | array | Evet | Alias'ın çoklu-dil etiketleri (`minItems: 1`). |
+
+```json
+{
+  "alias": [
+    {
+      "name": "Değerlendirme Aşamasında",
+      "roles": [
+        { "role": "backoffice.operator", "grant": "allow" }
+      ],
+      "labels": [
+        { "label": "Operasyon İncelemesinde", "language": "tr" },
+        { "label": "Under Operational Review", "language": "en" }
+      ]
+    }
+  ]
+}
+```
+
+Birden fazla iç state aynı dış alias'a eşlenebilir. Çözümleme isteği yapan aktörün rollerini her alias'ın `roles` listesine göre değerlendirir; eşleşme varsa istek dilindeki `label`, o dilde label yoksa `alias.name` döner; hiçbir alias eşleşmezse `state.key`'e geri düşer.
+
+### Migrasyon adımları
+
+1. Client'a sızması istenmeyen iç state'leri belirleyin (ör. Fraud/KPS/Limit).
+2. Bu state'lere uygun `alias[]` tanımları ekleyin; hangi rolün hangi label'ı göreceğini `roles` + `labels` ile belirtin.
+3. Çok dilli kullanımda her dil için `labels` girişi ekleyin; rol modeli ve DENY/ALLOW önceliği için [Yetkilendirme](/docs/concepts/authorization) sayfasına bakın.
+
+> İlgili dokümanlar: [Workflow → State Alias](/docs/components/workflow#state-alias-rol-tabanlı-state-maskeleme) · [Yetkilendirme](/docs/concepts/authorization)
+
+---
+
+## 3. FunctionScope Zorunluluğu ve Tutarlı Yanıt
+
+`FunctionScope`, fonksiyon çağrısının her iki giriş noktasında (`GetFunctionByKeyAsync` ve `GetFunctionByInstanceAsync`) artık **tutarlı** şekilde uygulanır:
+
+| Scope | Kural |
+|-------|-------|
+| `D` (Domain) | Her zaman çalışır — tüm scope kısıtlarından muaftır. |
+| `I` (Instance) | Yalnızca bir instance mevcutsa çalışır. |
+| `F` (Flow) | Bir instance **ve** fonksiyonun o instance'ın flow'unda tanımlı olması (`workflow.Functions`) gerekir. |
+
+### Ne değişti
+
+Eski davranışta scope kısmen uygulanıyordu: guard yalnızca Flow üyeliğini ve yalnızca bir instance varken kontrol ediyordu. Sonuç olarak `Instance`/`Flow` kapsamlı fonksiyonlar domain seviyesindeki uçtan kısıtsız çağrılabiliyor, scope hataları ise tesadüfi **404** olarak sızıyor ve rol kapsamı (authorize role evaluation) ele alınmıyordu.
+
+Yeni davranışta authorize rol değerlendirmesi yapılır ve scope/tanım eksikliği veya yetki ihlali durumunda **403 Forbidden** (`FunctionScopeNotSatisfied`) döner.
+
+### Migrasyon adımları
+
+1. Fonksiyonlarınızın `scope` değerlerini gözden geçirin: `F` kapsamlı bir fonksiyonun ilgili flow'un `workflow.Functions` listesinde tanımlı olduğundan emin olun.
+2. Domain seviyesindeki uçtan `Instance`/`Flow` kapsamlı fonksiyon çağıran client'ları güncelleyin.
+3. Hata yönetiminde scope ihlallerinin artık **404 değil 403** döndüğünü dikkate alın.
+
+> İlgili doküman: [Function](/docs/components/functions/)
+
+---
+
+## 4. Operations & Observability
+
+### `publish` endpoint'i OpenAPI'de gizlendi
+
+`publish` endpoint'i varsayılan olarak OpenAPI'de expose ediliyordu. Bu, OpenAPI okunarak API'nin **bileşen yükleme** bilgisini açığa çıkarıyordu. Endpoint artık API Explorer / OpenAPI çıktısında gizlidir.
+
+### Production'da Swagger UI kapalı
+
+Swagger arayüzü **production** ortamında tüm API host'larında kapatıldı; public production yüzeyi artık API explorer'ı sunmaz.
+
+### Migrasyon adımları
+
+1. Production'da Swagger UI'a bağımlı araç/akış varsa bunları kaldırın veya non-production ortamlara taşıyın.
+2. `publish` işlemini OpenAPI üzerinden keşfeden entegrasyonları gözden geçirin; endpoint artık API Explorer'da listelenmez.
+
+---
+
+## 5. Yapılandırılabilir Asenkron Transition İşletimi
+
+`sync=false` (asenkron) işletim için **durable** bir yöntem implemente edildi. Artık asenkron işlemlerde her transition **scale edilebilir** ve **outbox** yapısı ile **retry** edilebilir hale geldi.
+
+### Ne değişti
+
+- Continuation'lar inline çalışmak yerine (opsiyonel olarak **outbox** üzerinden) kuyruğa alınarak dayanıklılık (durability) kazanır.
+- **Busy** durumundaki instance'lara erişim, bir **chain ownership token** sistemiyle kontrol edilir; eşzamanlı zincirlerin birbirini ezmesi önlenir.
+- Heartbeat'i bayatlamış (takılı kalmış) instance'ları otomatik toparlayan bir **chain reaper** servisi devreye alındı.
+
+### Migrasyon adımları
+
+1. `sync=true` / `sync=false` davranışı ve karar kriterleri için [Async / Sync Yöntemi](/docs/how-to/async-sync) sayfasına bakın.
+2. Bu sürüm, dayanıklılık refactor'ü için EF Core migration'ları içerir — `db-migrator` image'ı ile şema güncellemesini uygulayın.
+
+> İlgili doküman: [Async / Sync Yöntemi](/docs/how-to/async-sync)
+
+---
+
+## Özet
+
+- **sys-mappings** bileşeni + sandbox'lı custom C# helper'lar; `scripts.helpers[]` (obje referansı) / `scripts.allowedAssemblies[]` ve `REF` encoding.
+- **State alias** ile rol bazlı, çoklu-dil state maskeleme (DENY > ALLOW); iç state'ler client'a sızmaz.
+- **FunctionScope** her çağrı yolunda tutarlı; ihlaller artık **403** döner.
+- **Operations:** `publish` endpoint'i OpenAPI'de gizli, production Swagger kapalı.
+- **Asenkron transition** durable işletim: outbox ile retry, chain ownership token, chain reaper.
+- Bileşen **şeması 0.0.46**'ya yükseldi.
+
+> Teknik release notları: [Release v0.0.60](/blog/release-v0-0-60)

blog/2026-05-21-v0-0-55.md

@@ -240,7 +240,7 @@ Configuration for v0.0.55:
 
 ## See Also
 
-- [v0.0.55 Duyurusu](/blog/v0055-neler-degisti) — Feature-focused announcement in Turkish
+- [v0.0.55 Duyurusu](/blog/migration/v0055-neler-degisti) — Feature-focused announcement in Turkish (Migration Guides)
 
 ---
 

blog/2026-06-01-v0-0-58.md

@@ -10,8 +10,6 @@ date: 2026-06-01
 
 This release closes the gap in **subflow fault handling**: a faulted child now propagates through the parent's error boundary chain instead of leaving the parent stuck in **Busy** ([#699](https://github.com/burgan-tech/vnext/issues/699)). **Function responses and wizard-state behavior** are extended — `acceptedStatusCodes` are honored end-to-end so `rawResponse=true` endpoints can forward structured HTTP 400s, and wizard states resolve transition views first while reporting `hasView` in a loop-safe way ([#697](https://github.com/burgan-tech/vnext/issues/697)). A **hotfix** standardizes instance audit columns via a shared base model and fixes the async reserved-transition lock ([#644](https://github.com/burgan-tech/vnext/issues/644)). The runtime repository's own documentation was rebuilt into an architecture-first structure ([#693](https://github.com/burgan-tech/vnext/issues/693)), and vocabulary-aware runtime schema validation was added (PR [#692](https://github.com/burgan-tech/vnext/pull/692)). This bump also advances the component **schema to 0.0.43**.
 
-A Turkish announcement (**Duyuru**) is included at the end of this post.
-
 {/* truncate */}
 
 ---