@appaflytech/zeyrek-ai-mcp 0.0.6 → 0.0.7

package/dist/tools/rows.js

@@ -7,6 +7,12 @@ import { attachFindings, evaluatePolicy, enforcePolicy } from '../knowledge/poli
 import { policyRules } from '../knowledge/rules.js';
 import { languageHeader } from '../knowledge/languageCodes.js';
 import { handle } from '../platform/responses.js';
+import { uploadFile } from './files.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { secretKeyPattern } from '../platform/secrets.js';
+import { csvRows } from '../platform/csv.js';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
 import { z } from 'zod';
 const rowValues = z.record(z.unknown()).describe("Alan SLUG'ı → değer sözlüğü; anahtarlar entity_get çıktısındaki field SLUG'larıdır (name değil — name kullanmak 'Please enter a valid value' hatası verir)");
 /**
@@ -25,10 +31,178 @@ function derivedRowFindings(rows) {
     return [{
             ruleId: 'ROW-001',
             severity: 'warn',
-            message: `Gövdede ${rows.length} satır var. Bu satırlar VAR OLAN satırlardan türetiliyorsa (geçmiş/hareket/log/junction tablosu, backfill) onları gövdede taşımayın: tek bir kayıtlı 'INSERT … SELECT' sorgusu aynı işi TEK çağrıda yapar ve hiçbir id elle taşınmaz (ölçüldü 2026-09-07). Satırlar dışarıdan geliyorsa (içe aktarma, kullanıcı verisi) bu çağrı doğru yoldur. Ham SQL yolu UYGULAMA katmanını atlar (automation tetiklenmez, incremental sayaç ilerlemez, localization companion yazılmaz) ama veritabanı kısıtları — NOT NULL, FK, UNIQUE, enum CHECK — aynen uygulanır. Reçete, merdiven kalıbı ve anahtar sözleşmesi: platform_guide('entity') §'Toplu ve türetilmiş satır'.`,
+            message: `Gövdede ${rows.length} satır var. Satırlar dışarıdan bir dosyadan geliyorsa gövdeden değil DOSYADAN yazın: aynı çağrıyı \`path: "seed.csv" | "seed.json"\` ile verin, gateway dosyayı okur ve 1000'lik partilere böler — satırlar ajan bağlamından hiç geçmez. Bu satırlar VAR OLAN satırlardan türetiliyorsa (geçmiş/hareket/log/junction tablosu, backfill) onları gövdede taşımayın: tek bir kayıtlı 'INSERT … SELECT' sorgusu aynı işi TEK çağrıda yapar ve hiçbir id elle taşınmaz (ölçüldü 2026-09-07). Satırlar dışarıdan geliyorsa (içe aktarma, kullanıcı verisi) bu çağrı doğru yoldur. Ham SQL yolu UYGULAMA katmanını atlar (automation tetiklenmez, incremental sayaç ilerlemez, localization companion yazılmaz) ama veritabanı kısıtları — NOT NULL, FK, UNIQUE, enum CHECK — aynen uygulanır. Reçete, merdiven kalıbı ve anahtar sözleşmesi: platform_guide('entity') §'Toplu ve türetilmiş satır'.`,
             guide: 'ngapps://guides/entity'
         }];
 }
+const bulkBatchSize = 1000;
+const maxPathBytes = 50 * 1024 * 1024;
+const maxPathRows = 100_000;
+const pathParam = z.string().min(1).optional()
+    .describe("Gateway sürecinin okuyabildiği yerel `.json` (satır dizisi) ya da `.csv` dosyası; 'row'/'rows' ile birlikte verilmez. Satırlar ajan bağlamından HİÇ geçmez: gateway dosyayı okur, 1000'lik partilere böler ve ardışık toplu çağrı yapar. CSV ayracı ilk satırdan bulunur (`;` sayısı `,` sayısını geçerse `;`), değerler string gider ve tipe backend çevirir. 50 MB / 100.000 satır üstü reddedilir — o boyut import_analyze zinciridir.");
+const relationsByNameParam = z.boolean().optional()
+    .describe("İlişki alanlarına id yerine GÖRÜNEN AD yazmayı açar: 'departman: \"Satış\"' hedef tablonun display ya da benzersiz alanında aranır ve id'ye çevrilir. Yalnız toplu yolda (rows / path) çalışır. Eşleşmeyen değer 422 döndürür ve hangi satırın hangi alanı olduğunu söyler — sessizce boş bırakmaz.");
+function collectIds(payload, into) {
+    const data = payload?.data;
+    if (Array.isArray(data))
+        into.push(...data);
+}
+async function readRowsFromPath(tool, path) {
+    const absolute = resolve(path);
+    const extension = extname(absolute).toLowerCase();
+    if (extension !== '.json' && extension !== '.csv') {
+        throw new PlatformApiError(`${tool}: \`path\` yalnız .json ya da .csv okur — verilen: ${absolute}`);
+    }
+    let sizeBytes;
+    try {
+        sizeBytes = (await stat(absolute)).size;
+    }
+    catch (error) {
+        throw new PlatformApiError(`${tool}: dosya okunamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür.`);
+    }
+    if (sizeBytes > maxPathBytes) {
+        throw new PlatformApiError(`${tool}: dosya ${maxPathBytes} bayt sınırını aşıyor (${sizeBytes} B). Bu boyut satır yazma yolu değil içe aktarma zinciridir — import_analyze → import_plan → import_run.`);
+    }
+    const text = await readFile(absolute, 'utf8');
+    let rows;
+    if (extension === '.csv') {
+        rows = csvRows(text);
+    }
+    else {
+        try {
+            rows = JSON.parse(text);
+        }
+        catch (error) {
+            throw new PlatformApiError(`${tool}: JSON okunamadı — ${absolute} (${error instanceof Error ? error.message : String(error)}).`);
+        }
+    }
+    if (!Array.isArray(rows)) {
+        throw new PlatformApiError(`${tool}: \`path\` dosyası bir satır DİZİSİ taşımalı — ${absolute} içinde ${typeof rows} bulundu.`);
+    }
+    if (rows.length === 0) {
+        throw new PlatformApiError(`${tool}: dosyada satır yok — ${absolute}. CSV ise başlık satırı var mı ve ayraç doğru mu kontrol edin.`);
+    }
+    if (rows.length > maxPathRows) {
+        throw new PlatformApiError(`${tool}: ${rows.length} satır, ${maxPathRows} sınırının üstünde. Bu boyutta içe aktarma zincirini kullanın: import_analyze → import_plan → import_run (iş kuyruğa alınır, ilerleme import_status'tan izlenir).`);
+    }
+    return rows;
+}
+/**
+ * Dosya satır numarası 1 tabanlıdır ve başlık satırını sayar: CSV'de düşen satırı kullanıcı
+ * editörde bu numarayla bulur. JSON dizisinde de aynı formül kullanılır — ilk eleman 2. satırda
+ * durur çünkü açılış köşeli parantezi ilk satırı yer.
+ */
+function fileLineOf(batchIndex, rowIndexInBatch) {
+    return batchIndex * bulkBatchSize + rowIndexInBatch + 2;
+}
+async function writeInBatches(platform, method, project, environment, headers, entityId, rows, rowContext, relationsByName) {
+    const query = relationsByName ? { relationsByName: true } : undefined;
+    const ids = [];
+    let written = 0;
+    let batches = 0;
+    for (let start = 0; start < rows.length; start += bulkBatchSize) {
+        const batch = rows.slice(start, start + bulkBatchSize);
+        const batchIndex = batches;
+        try {
+            const payload = await platform.tenant(method, project, `/entities/${entityId}/row/bulk`, { environment, headers, body: { rows: batch, ...(rowContext ? { rowContext } : {}) }, ...(query ? { query } : {}) });
+            collectIds(payload, ids);
+            written += batch.length;
+            batches += 1;
+        }
+        catch (error) {
+            // Hiç satır yazılmadıysa ortada kısmi durum yoktur: bu düz bir REDDİR ve platformun kendi
+            // mesajı (satır indeksi + all-or-nothing notu) her özetten iyidir. Yutup 'written: 0'
+            // döndürmek çağırana başarı gibi okunurdu.
+            if (written === 0)
+                throw error;
+            const rowIndexInBatch = error instanceof PlatformApiError && typeof error.rowIndex === 'number' ? error.rowIndex : 0;
+            return {
+                written,
+                batches,
+                ...(ids.length > 0 ? { ids } : {}),
+                stopped: {
+                    fileLine: fileLineOf(batchIndex, rowIndexInBatch),
+                    batchIndex,
+                    rowIndexInBatch,
+                    error: error instanceof Error ? error.message : String(error),
+                    note: `${written} satır YAZILDI ve öyle kaldı: partiler arası transaction yoktur, yalnız düşen parti geri alındı. Dosyayı ${fileLineOf(batchIndex, rowIndexInBatch)}. satırdan düzeltip kalanını yeniden gönderin; hepsi-ya-hiç gerekiyorsa import_run kullanın.`
+                }
+            };
+        }
+    }
+    return { written, batches, ...(ids.length > 0 ? { ids } : {}) };
+}
+/**
+ * Üç kaynaktan tam olarak biri: gövdedeki tek satır, gövdedeki dizi ya da dosya. İkisi birden
+ * verilirse hangisinin yazılacağı belirsizdir ve sessizce birini seçmek yanlış veri yazar.
+ */
+function assertOneSource(tool, row, rows, path) {
+    const given = [row, rows, path].filter(value => value !== undefined).length;
+    if (given === 1)
+        return;
+    throw new Error(given === 0
+        ? `${tool}: 'row', 'rows' ya da 'path' parametrelerinden biri zorunlu.`
+        : `${tool}: 'row', 'rows' ve 'path' birlikte verilemez — tam olarak biri.`);
+}
+const exportFolderName = 'Dışa aktarmalar';
+const maxSelectedRowIds = 1000;
+/**
+ * `inline` örneği ajan bağlamına girer. Sütun tanımı + iki satır dar bir tabloda birkaç KB'dir;
+ * yüzlerce sütunlu tabloda aynı iki satır bağlamı dosyanın kendisi kadar doldururdu. Sınırı aşan
+ * örnekte `data` düşer, `columns` kalır — dosyanın şekli yine görülür, satırlar Sürücü'dedir.
+ */
+const templateInlineMaxChars = 16_000;
+const templateFormatNotes = {
+    xlsx: "xlsx şablonda ipuçları başlık hücresi yorumunda ve gizli `_zeyrek` sayfasındadır; veri alanında ipucu satırı yoktur.",
+    csv: 'csv şablonda ipucu satırı ve `#zeyrek` satırı yoktur; başlıklar alan adıdır.',
+    json: 'JSON şablon `{ meta, data }` gövdesidir; `meta` analizde atlanır, satırlar `data`dadır ve anahtarları alan slug\'ıdır.'
+};
+const rowFiltersParam = z.array(z.record(z.unknown())).optional()
+    .describe('Platform Filter dizisi; biçim için row_list\'i filtresiz çağırıp Studio\'daki bir filtreyi referans alın');
+const exportScopeParam = z.object({
+    kind: z.enum(['view', 'all', 'selected']).describe("'view' filtre + sıralama ile, 'all' tüm satırlar, 'selected' rowIds listesi"),
+    filters: rowFiltersParam,
+    sort: z.object({ field: z.string(), ascending: z.boolean().optional() }).optional()
+        .describe("Sıralama; 'ascending' verilmezse artan"),
+    rowIds: z.array(z.string()).optional().describe(`'selected' kapsamında dışa aktarılacak satır id'leri; en çok ${maxSelectedRowIds} — üstü için filtre kullanın`)
+}).optional().describe("Verilmezse tüm satırlar ('all')");
+/**
+ * Dosya adı sunucudan gelir; başlık RFC 5987 yüzde kodlu da olabilir. Ada zaman damgası
+ * eklenir çünkü aynı tablo günde birkaç kez dışa aktarılır ve Sürücü'de aynı ad çakışır.
+ */
+function exportFileName(headers, fallbackSlug, extension) {
+    const disposition = headers['content-disposition'] ?? '';
+    const matched = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(disposition);
+    let base = fallbackSlug;
+    const captured = matched?.[1];
+    if (captured) {
+        try {
+            base = decodeURIComponent(captured);
+        }
+        catch {
+            base = captured;
+        }
+    }
+    const dot = base.lastIndexOf('.');
+    const stem = dot > 0 ? base.slice(0, dot) : base;
+    const stamp = new Date().toISOString().slice(0, 16).replace(/[-:]/g, '').replace('T', '-');
+    return `${stem}-${stamp}.${extension}`;
+}
+/**
+ * Klasörün `name`'i ASCII'ye katlanmıştır ('Dışa aktarmalar' → 'Disa aktarmalar'); ham ad yalnız
+ * `displayName`'de durur. Katlanmış ada bakan arama hiçbir zaman eşleşmez ve her dışa aktarma
+ * yeni bir '… (1)' klasörü açardı.
+ */
+async function exportFolderIdAsync(platform, project, environment) {
+    const listed = await platform.tenant('GET', project, '/folders', { environment, query: { searchTerm: exportFolderName, pageLength: 50 } });
+    const rows = listed?.data ?? [];
+    const existing = rows.find(folder => folder.displayName === exportFolderName);
+    if (typeof existing?.id === 'string')
+        return existing.id;
+    const created = await platform.tenant('POST', project, '/folders', { environment, body: { name: exportFolderName } });
+    const id = created?.data?.id;
+    return typeof id === 'string' ? id : undefined;
+}
 const includeTranslationsParam = z.boolean().optional()
     .describe("Çok dilli alanların TÜM dillerini de getirir: satıra 'localizations: { <dil>: { <alan>: <değer> } }' eklenir. Verilmezse satır yalnız istek dilinde düzleştirilmiş gelir (çevirisi olmayan alan varsayılan dile düşer).");
 const localizationsParam = z.record(z.record(z.unknown())).optional()
@@ -43,7 +217,7 @@ export function registerRowTools(server, platform) {
             environment: environmentParam,
             entityId: entityRef,
             selectedFields: z.array(z.string()).optional().describe('Dönen satırlar bu alan adlarına indirgenir, id her zaman dahildir; platform tam satırı hesapladığı için kırpma gateway tarafında yapılır'),
-            filters: z.array(z.record(z.unknown())).optional().describe('Platform Filter dizisi; biçim için row_list\'i filtresiz çağırıp Studio\'daki bir filtreyi referans alın'),
+            filters: rowFiltersParam,
             language: languageParam,
             includeTranslations: includeTranslationsParam,
             ...pagingParams
@@ -93,29 +267,34 @@ export function registerRowTools(server, platform) {
             entityId: entityRef,
             row: rowValues.optional(),
             rows: z.array(z.record(z.unknown())).optional(),
+            path: pathParam,
+            relationsByName: relationsByNameParam,
             localizations: localizationsParam,
             language: languageParam,
             rowContext: z.record(z.unknown()).optional()
                 .describe("Satır olayının DIŞINDAN automation'a geçirilecek değerler. Tetiklenen automation bunları ifadelerinde `rowContext.<anahtar>` ile okur — zaman damgası, göç kaynağı, toplu iş kimliği gibi. Tarihsel (geçmiş tarihli) veri üretmenin yolu budur: automation `UtcNow()` yerine `rowContext.occurredAt`'i yazabilir. Verilmezse automation bağlamı değişmez.")
         },
         annotations: writes
-    }, handle(config, async ({ project, environment, entityId, row, rows, localizations, rowContext, language }) => {
-        if (row && rows)
-            throw new Error("'row' ve 'rows' birlikte verilemez.");
+    }, handle(config, async ({ project, environment, entityId, row, rows, path, relationsByName, localizations, rowContext, language }) => {
+        assertOneSource('row_create', row, rows, path);
         if (localizations && !row)
             throw new Error("Üst düzey 'localizations' yalnız 'row' ile verilir: toplu uçta hangi satıra ait olduğu belirsizdir. Toplu eklemede dil değerlerini satırın kendi içine koyun — rows: [{ …, localizations: { tr: {…} } }].");
-        if (!row && !rows)
-            throw new Error("'row' ya da 'rows' parametrelerinden biri zorunlu.");
+        if (relationsByName && row)
+            throw new Error("'relationsByName' yalnız toplu yolda ('rows' ya da 'path') çalışır: tek satır ucu ad → id çözümlemesi yapmaz, ilişki alanına id yazın.");
         const notes = [];
         const headers = languageHeader(language, notes);
         const wantedLocalizations = localizations && Object.keys(localizations).length > 0 ? localizations : undefined;
-        const shapeFindings = enforcePolicy(evaluatePolicy(config, policyRules, 'row', rows ? { rows } : { row }, { operation: 'create' }));
+        const fileRows = path ? await readRowsFromPath('row_create', path) : undefined;
+        const bulkRows = rows ?? fileRows;
+        const shapeFindings = enforcePolicy(evaluatePolicy(config, policyRules, 'row', bulkRows ? { rows: bulkRows } : { row }, { operation: 'create' }));
         const resolver = new RefResolver(platform, project, environment);
-        if (rows) {
+        if (bulkRows) {
             const bulkEntityId = await resolveEntityId(resolver, entityId);
-            const bulkBody = { rows, ...(rowContext ? { rowContext } : {}) };
-            const bulkDrift = unmappedMembers('CreateBulkRowCommand', bulkBody);
-            return attachFindings(withUnmappedMembers(withNormalization(withResolved(await platform.tenant('POST', project, `/entities/${bulkEntityId}/row/bulk`, { environment, headers, body: bulkBody }), resolver.resolved), notes), bulkDrift), [...shapeFindings, ...derivedRowFindings(rows)]);
+            const bulkDrift = unmappedMembers('CreateBulkRowCommand', { rows: bulkRows, ...(rowContext ? { rowContext } : {}), ...(relationsByName ? { relationsByName } : {}) });
+            const outcome = await writeInBatches(platform, 'POST', project, environment, headers, bulkEntityId, bulkRows, rowContext, relationsByName);
+            if (fileRows)
+                notes.push(`${path} okundu: ${fileRows.length} satır, ${Math.ceil(fileRows.length / bulkBatchSize)} parti.`);
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved(outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
         }
         const resolvedEntityId = await resolveEntityId(resolver, entityId);
         const body = { row, ...(wantedLocalizations ? { localizations: wantedLocalizations } : {}), ...(rowContext ? { rowContext } : {}) };
@@ -158,33 +337,174 @@ export function registerRowTools(server, platform) {
             entityId: entityRef,
             row: rowValues.optional(),
             rows: z.array(z.record(z.unknown())).optional(),
+            path: pathParam,
+            relationsByName: relationsByNameParam,
             localizations: localizationsParam,
             language: languageParam,
             rowContext: z.record(z.unknown()).optional()
                 .describe("Satır olayının DIŞINDAN automation'a geçirilecek değerler. Tetiklenen automation bunları ifadelerinde `rowContext.<anahtar>` ile okur — zaman damgası, göç kaynağı, toplu iş kimliği gibi. Tarihsel (geçmiş tarihli) veri üretmenin yolu budur: automation `UtcNow()` yerine `rowContext.occurredAt`'i yazabilir. Verilmezse automation bağlamı değişmez.")
         },
         annotations: updates
-    }, handle(config, async ({ project, environment, entityId, row, rows, localizations, rowContext, language }) => {
-        if (row && rows)
-            throw new Error("'row' ve 'rows' birlikte verilemez.");
+    }, handle(config, async ({ project, environment, entityId, row, rows, path, relationsByName, localizations, rowContext, language }) => {
+        assertOneSource('row_update', row, rows, path);
         if (localizations && !row)
             throw new Error("Üst düzey 'localizations' yalnız 'row' ile verilir: toplu uçta hangi satıra ait olduğu belirsizdir. Toplu güncellemede dil değerlerini satırın kendi içine koyun — rows: [{ id, localizations: { tr: {…} } }].");
-        if (!row && !rows)
-            throw new Error("'row' ya da 'rows' parametrelerinden biri zorunlu.");
-        const shapeFindings = enforcePolicy(evaluatePolicy(config, policyRules, 'row', rows ? { rows } : { row }, { operation: 'update' }));
+        if (relationsByName && row)
+            throw new Error("'relationsByName' yalnız toplu yolda ('rows' ya da 'path') çalışır: tek satır ucu ad → id çözümlemesi yapmaz, ilişki alanına id yazın.");
         const notes = [];
+        const fileRows = path ? await readRowsFromPath('row_update', path) : undefined;
+        const bulkRows = rows ?? fileRows;
+        const shapeFindings = enforcePolicy(evaluatePolicy(config, policyRules, 'row', bulkRows ? { rows: bulkRows } : { row }, { operation: 'update' }));
         const headers = languageHeader(language, notes);
         const resolver = new RefResolver(platform, project, environment);
         const resolvedEntityId = await resolveEntityId(resolver, entityId);
-        if (rows) {
-            const bulkBody = { rows, ...(rowContext ? { rowContext } : {}) };
-            const bulkDrift = unmappedMembers('UpdateBulkRowCommand', bulkBody);
-            return attachFindings(withUnmappedMembers(withNormalization(withResolved(await platform.tenant('PUT', project, `/entities/${resolvedEntityId}/row/bulk`, { environment, headers, body: bulkBody }), resolver.resolved), notes), bulkDrift), [...shapeFindings, ...derivedRowFindings(rows)]);
+        if (bulkRows) {
+            const bulkDrift = unmappedMembers('UpdateBulkRowCommand', { rows: bulkRows, ...(rowContext ? { rowContext } : {}), ...(relationsByName ? { relationsByName } : {}) });
+            const outcome = await writeInBatches(platform, 'PUT', project, environment, headers, resolvedEntityId, bulkRows, rowContext, relationsByName);
+            if (fileRows)
+                notes.push(`${path} okundu: ${fileRows.length} satır, ${Math.ceil(fileRows.length / bulkBatchSize)} parti.`);
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved(outcome, resolver.resolved), notes), bulkDrift), [...shapeFindings, ...(fileRows ? [] : derivedRowFindings(bulkRows))]);
         }
         const body = { row, ...(localizations ? { localizations } : {}), ...(rowContext ? { rowContext } : {}) };
         const drift = unmappedMembers('UpdateRowCommand', body);
         return attachFindings(withUnmappedMembers(withNormalization(withResolved(await platform.tenant('PUT', project, `/entities/${resolvedEntityId}/row`, { environment, headers, body }), resolver.resolved), notes), drift), shapeFindings);
     }));
+    server.registerTool('row_export', {
+        title: 'Satırları dışa aktar',
+        description: "Bir tablonun satırlarını xlsx / csv / json dosyasına yazar ve dosyayı projenin SÜRÜCÜSÜNE ('Dışa aktarmalar' klasörü) koyar; yanıt yalnız fileId ve sayılardır — dosya içeriği ajanın bağlamına HİÇ girmez, içeriği görmek için file_download kullanın. Kapsam üç şekildedir: 'view' (filtre + sıralama), 'all', 'selected' (rowIds). 5.000 satırın üstünde platform işi arka plana alır ve 202 ile jobId döner; import_status { jobId } ile izlenir, biten işin dosyası result.reportFileId'dedir. CSV UTF-8 BOM'lu yazılır; ayraç ve ondalık bir yerel ayar profilinden gelir (tr-TR `;` · `1,5`, en-US `,` · `1.5`): dışa aktarmada projenin dili seçer, şablonda 'locale' ile seçilir. 'reimportable: true' dosyaya id sütununu ve _zeyrek meta sayfasını ekler: dosya düzenlenip import_analyze → import_plan { mode: 'upsert', keyField: 'id' } ile geri yüklenebilir (Akış C). 'template: true' tablo satırı yazmaz: tablonun alanlarından İKİ SENTETİK örnek satırlı bir şablon üretir ve değiştirilmeden geri yüklenebilir. 'template: true, inline: true' şablonun şeklini (sütunlar, anahtar önerisi, iki satır) yanıta da koyar — toplu yazımdan önce dosyanın nasıl görünmesi gerektiğini indirmeden görmenin yolu budur; satır satır row_create yerine şablon başlıklarıyla CSV → file_upload { text } → import_analyze → import_plan → import_run, reçete platform_guide('entity') §'Dışa aktarma ve geri yükleme'.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            entityId: entityRef,
+            format: z.enum(['xlsx', 'csv', 'json']).optional().describe("Varsayılan 'xlsx'. 'json' iş kuyruğuna alınmaz, satır sayısı ne olursa olsun doğrudan döner."),
+            scope: exportScopeParam,
+            columns: z.enum(['visible', 'all']).optional().describe("'visible' yalnız selectedFields'ta sayılanları, 'all' sistem alanları dahil hepsini yazar; varsayılan 'all'"),
+            selectedFields: z.array(z.string()).optional().describe("columns: 'visible' ile birlikte yazılacak alan SLUG'ları"),
+            relations: z.enum(['display', 'id', 'both']).optional().describe("İlişki sütunu görünen adla mı, id ile mi, ikisiyle mi yazılsın; varsayılan 'display'. reimportable ile 'both' zorunludur ve gateway onu kendisi seçer."),
+            languages: z.enum(['request', 'all']).optional().describe("'all' çok dilli sütunların TÜM dillerini ayrı sütunlara yazar; varsayılan yalnız istek dili"),
+            files: z.enum(['name', 'link']).optional().describe("Dosya sütunu ad olarak mı indirme bağlantısı olarak mı yazılsın; varsayılan 'name'"),
+            reimportable: z.boolean().optional().describe("Dosyaya id sütunu ve _zeyrek meta sayfası ekler; ilişki sütunları ad+id olarak yazılır. Geri yükleme yolu: import_analyze → import_plan { mode: 'upsert', keyField: 'id' }."),
+            template: z.boolean().optional().describe("Tablonun alanlarından iki örnek satırlı şablon; ipuçları veri alanının dışında (xlsx başlık yorumu + `_zeyrek`, json `meta`, csv'de yok); değiştirilmeden geri yüklenebilir. PK, identity, sistem ve artan kod sütunu yoktur; değerler sentetiktir, ilişki sütunu boş ve `manual`dır. scope/columns/selectedFields/relations/languages/files/reimportable yok sayılır."),
+            locale: z.enum(['tr-TR', 'en-US']).optional().describe("Yalnız template ile: csv ayracı, ondalık ve tarih profilini ve inline örneğin yerel ayarını seçer (tr-TR `;` · `1,5` · `dd.MM.yyyy`; en-US `,` · `1.5` · `M/d/yyyy`). Verilmezse projenin varsayılan dili seçer. Dışa aktarmada (template yok) yok sayılır."),
+            inline: z.boolean().optional().describe(`Yalnız template: true ile: şablonun şekli yanıta 'sample { entity, locale, keyField, columns: [{ slug, header, type, required, options?, relationEntity?, matchField?, manual? }], data }' olarak da konur — data iki sentetik satırdır (JSON biçimi: ondalık nokta, tarih yyyy-MM-dd). Örnek ${templateInlineMaxChars} karakteri aşarsa data atlanır, columns kalır. template olmadan istek gitmeden reddedilir.`),
+            download: z.string().min(1).optional().describe("Ayrıca gateway sürecinin yazabildiği bu yerel yola kaydeder; Sürücü'deki kopya yine oluşur.")
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, entityId, format, scope, columns, selectedFields, relations, languages, files, reimportable, template, locale, inline, download }) => {
+        if (inline && !template) {
+            throw new PlatformApiError('row_export: inline yalnız template: true ile kullanılır — satır içi örnek şablonun şeklidir; tablonun gerçek satırlarını görmek için row_list kullanın.');
+        }
+        if (scope?.kind === 'selected' && !(scope.rowIds?.length)) {
+            throw new PlatformApiError("row_export: scope.kind 'selected' verildiğinde rowIds boş olamaz — hangi satırların yazılacağı belirsizdir.");
+        }
+        if ((scope?.rowIds?.length ?? 0) > maxSelectedRowIds) {
+            throw new PlatformApiError(`row_export: ${scope?.rowIds?.length} satır id'si, ${maxSelectedRowIds} sınırının üstünde. Bu kadar satırı seçerek değil filtreyle verin: scope { kind: 'view', filters: [...] }.`);
+        }
+        const resolvedFormat = format ?? 'xlsx';
+        const notes = [];
+        const resolver = new RefResolver(platform, project, environment);
+        const resolvedEntityId = await resolveEntityId(resolver, entityId);
+        const response = template
+            ? await platform.tenantWithHeaders('GET', project, `/entities/${resolvedEntityId}/import/template`, { environment, query: { format: resolvedFormat, locale }, expectBinary: true })
+            : await platform.tenantWithHeaders('POST', project, `/entities/${resolvedEntityId}/export`, {
+                environment,
+                expectBinary: true,
+                body: {
+                    format: resolvedFormat,
+                    scope: {
+                        kind: scope?.kind ?? 'all',
+                        ...(scope?.filters ? { filters: scope.filters } : {}),
+                        ...(scope?.sort ? { sort: { field: scope.sort.field, ascending: scope.sort.ascending ?? true } } : {}),
+                        ...(scope?.rowIds ? { rowIds: scope.rowIds } : {})
+                    },
+                    columns: columns ?? 'all',
+                    ...(selectedFields ? { selectedFields } : {}),
+                    relations: reimportable ? 'both' : relations ?? 'display',
+                    languages: languages ?? 'request',
+                    files: files ?? 'name',
+                    reimportable: reimportable ?? false
+                }
+            });
+        const payload = response.body;
+        if (response.httpStatus === 202) {
+            const started = JSON.parse(payload.bytes.toString('utf8'));
+            return withResolved({
+                jobId: started.data?.jobId,
+                note: "Satır sayısı platformun eşiğini aştı, iş arka plana alındı. import_status { jobId } ile izleyin; tamamlanınca dosya result.reportFileId'dedir ve file_download ile okunur. Gateway beklemez."
+            }, resolver.resolved);
+        }
+        const noteParts = template ? [templateFormatNotes[resolvedFormat], 'İki satır sentetik örnektir — üzerine yazın ya da silin.'] : [];
+        let sample;
+        if (template && inline) {
+            const sampled = await platform.tenant('GET', project, `/entities/${resolvedEntityId}/import/sample`, { environment, query: { locale } });
+            const dto = sampled?.data ?? {};
+            const sampleJson = dto.json ?? '';
+            const sampleColumns = (dto.columns ?? []).map(column => ({
+                slug: column.slug,
+                header: column.header,
+                type: column.type,
+                required: column.required,
+                ...(column.options?.length ? { options: column.options } : {}),
+                ...(column.relationEntity ? { relationEntity: column.relationEntity } : {}),
+                ...(column.matchField && column.relationEntity ? { matchField: column.matchField } : {}),
+                ...(column.manual ? { manual: true } : {})
+            }));
+            const fits = sampleJson.length <= templateInlineMaxChars;
+            sample = {
+                entity: dto.entitySlug,
+                locale: dto.locale,
+                keyField: dto.keyField ?? null,
+                columns: sampleColumns,
+                ...(fits ? { data: JSON.parse(sampleJson || '{}').data ?? [] } : {})
+            };
+            if (!fits) {
+                noteParts.push(`Satır içi örnek ${sampleJson.length} karakter, ${templateInlineMaxChars} sınırının üstünde: sample.data atlandı, sample.columns duruyor. Örnek satırları görmek için şablon dosyasını file_download ile okuyun.`);
+            }
+            const maskedSlugs = sampleColumns.map(column => column.slug ?? '').filter(slug => secretKeyPattern.test(slug));
+            if (fits && maskedSlugs.length > 0) {
+                noteParts.push(`${maskedSlugs.join(', ')} örnek değeri gateway'in gizli alan maskesiyle *** döner — örnek değildir, bu sütuna kendi değerinizi yazın.`);
+            }
+            if (sampleColumns.some(column => column.manual)) {
+                noteParts.push("manual sütunlar boştur: ilişki hücresine hedef tablonun matchField değerini yazın (şablon hedeften satır okumaz).");
+            }
+        }
+        const fileName = exportFileName(response.headers, 'export', resolvedFormat);
+        const folderId = await exportFolderIdAsync(platform, project, environment);
+        const uploaded = await uploadFile(platform, {
+            project,
+            environment,
+            content: payload.bytes.toString('base64'),
+            filename: fileName,
+            contentType: payload.contentType,
+            folderId
+        });
+        const fileId = uploaded?.data?.id;
+        if (download) {
+            await writeFile(resolve(download), payload.bytes);
+            notes.push(`Dosya ayrıca ${resolve(download)} yoluna yazıldı.`);
+        }
+        if (reimportable) {
+            notes.push("Dosya id sütunu ve _zeyrek meta sayfası taşıyor: düzenledikten sonra file_upload → import_analyze → import_plan { mode: 'upsert', keyField: 'id' } ile geri yükleyin.");
+        }
+        if (resolvedFormat === 'csv' && template) {
+            notes.push(`CSV şablon UTF-8 BOM'lu; ayraç, ondalık ve tarih \`locale\` profilinden gelir (tr-TR \`;\` · \`1,5\` · \`dd.MM.yyyy\`, en-US \`,\` · \`1.5\` · \`M/d/yyyy\`)${locale ? `, seçilen ${locale}` : ", locale verilmediği için projenin varsayılan dili seçti"}. Geri yüklerken import_analyze ve import_plan'a aynı locale'i verin; plan analizin locale'ini devralmaz.`);
+        }
+        else if (resolvedFormat === 'csv') {
+            notes.push("CSV UTF-8 BOM'lu yazıldı; ayraç ve ondalık projenin dilinin profilinden gelir (tr → noktalı virgül `;` · `1,5`, diğer diller → virgül `,` · `1.5`). Dışa aktarmada locale seçilemez.");
+        }
+        if (locale && !template) {
+            notes.push('locale yalnız template ile kullanılır; dışa aktarmada yok sayıldı.');
+        }
+        return withNormalization(withResolved({
+            fileId,
+            fileName,
+            bytes: payload.bytes.byteLength,
+            contentType: payload.contentType,
+            folder: exportFolderName,
+            ...(sample ? { sample } : {}),
+            note: [`Dosya Sürücü'de. İçeriği okumak için file_download { id: '${String(fileId)}' }.`, ...noteParts].join(' ')
+        }, resolver.resolved), notes);
+    }));
     server.registerTool('row_delete', {
         title: 'Satır sil',
         description: "Tek satır için 'id', çoklu silme için 'ids' verin. Çok dilli entity'de dil satırlarını platform ana satırdan ÖNCE kendisi siler; eski platform sürümünde yabancı anahtar hatası dönerse önce companion entity'nin satırlarını silin.",

package/dist/tools/screenWrite.js

@@ -1,11 +1,15 @@
 import { invalidScreenEventNames, invalidWidgetTypeNodes, nestedRepeaterNodes, nestedRepeaterMessage, blockSizeNote, heightTypeNote, sizeStringNote } from '../knowledge/normalize.js';
+import { FUNCTIONS_NAMESPACE } from '../knowledge/functionGuards.js';
 import { applyCatalogLayoutRules } from './components.js';
 import { PlatformApiError } from '../platform/errors.js';
 const GUARD_CODES = {
     page: { events: 'PAGE-011', widgets: 'PAGE-012', noun: 'sayfa', tree: 'schema' },
     layout: { events: 'LAY-004', widgets: 'LAY-005', noun: 'layout', tree: 'views' }
 };
-/** JS tanımlayıcısı olmayan `name` alanlarını toplar; ad `const <ad> = Components["<ad>"]` üretimine girer. */
+/**
+ * JS tanımlayıcısı olmayan ya da AYRILMIŞ `name` alanlarını toplar; ad
+ * `const <ad> = Components["<ad>"]` üretimine girer.
+ */
 export function invalidComponentNames(nodes) {
     const found = [];
     for (const node of nodes ?? []) {
@@ -13,6 +17,11 @@ export function invalidComponentNames(nodes) {
         if (typeof name === 'string' && name.length > 0 && !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name.replace(/-/g, ''))) {
             found.push(`'${name}' (${node.elementId ?? '?'})`);
         }
+        else if (typeof name === 'string' && name.replace(/-/g, '') === FUNCTIONS_NAMESPACE) {
+            // K1: preamble her komponent için `const <ad> = Components["<ad>"]` üretir; `Functions` adlı
+            // komponent kullanıcı fonksiyonlarının ad alanını ezer ve sayfadaki her Functions.x() ölür.
+            found.push(`'${name}' (${node.elementId ?? '?'}) — ayrılmış ad: ${FUNCTIONS_NAMESPACE} kullanıcı fonksiyonlarının ad alanıdır (K1)`);
+        }
         found.push(...invalidComponentNames(node.children));
     }
     return found;
@@ -37,7 +46,7 @@ export function assertScreenWriteGuards(kind, screen) {
         throw new PlatformApiError(`Geçersiz widget düğümü (istek gönderilmedi): ${badWidgets.join(' · ')}`, 400);
     const badNames = invalidComponentNames(screen.schema);
     if (badNames.length > 0) {
-        throw new PlatformApiError(`PAGE-009 — komponent adı JS tanımlayıcısı değil (istek gönderilmedi): ${badNames.join(' · ')}. `
+        throw new PlatformApiError(`PAGE-009 — komponent adı JS tanımlayıcısı değil ya da ayrılmış (istek gönderilmedi): ${badNames.join(' · ')}. `
             + 'Runtime her komponent için `const <ad> = Components["<ad>"]` üretir; boşluklu ya da geçersiz bir ad '
             + 'SAYFADAKİ TÜM ifadeleri "Missing initializer in const declaration" ile öldürür (layout adları her sayfaya sızar). '
             + `name alanını elementId ile aynı yaz; okunabilir Türkçe başlık için props.title / props.text / props.label kullan (${codes.noun} ${codes.tree}).`, 400);

package/dist/tools/templates.js

@@ -1,6 +1,30 @@
 import { guid, pagingParams, readOnly, writes, updates } from './common.js';
+import { withNormalization } from '../knowledge/normalize.js';
 import { handle } from '../platform/responses.js';
 import { z } from 'zod';
+/**
+ * `environmentId` verilmediğinde platform PRODUCTION'ı paketler
+ * (`CreateProjectAsTemplateCommand`: `EnvironmentId ??= ActiveEnvironments().First(f => f.IsProduction)`).
+ * Promote edilmemiş projede o environment boştur ve build yine 'success' döner; şablon seed
+ * kayıtlarından ibaret kalır. Çağıran bunu yanıttan görmediği için hangi environment'ın
+ * paketlendiğini adıyla söylüyoruz (2026-09-12 koşusu S-2).
+ */
+async function defaultTemplateEnvironmentNote(platform, projectId) {
+    const fallback = "environmentId verilmedi: platform PRODUCTION environment'ını paketler (varsayılan/development değil). Promote edilmemiş projede şablon boş çıkar; development içeriğini istiyorsanız o environment'ın id'sini açıkça verin.";
+    try {
+        const payload = await platform.org('GET', `/projects/${projectId}`);
+        const environments = Array.isArray(payload?.data?.environments)
+            ? payload.data.environments
+            : [];
+        const production = environments.find(environment => environment.isProduction === true);
+        if (!production)
+            return fallback;
+        return `environmentId verilmedi: platform '${String(production.name)}' (production, id ${String(production.id)}) environment'ını paketler — varsayılan/development environment'ı DEĞİL. Oraya henüz promote etmediyseniz şablon yalnız seed kayıtlarını taşır; development içeriğini paketlemek için o environment'ın id'sini açıkça verin.`;
+    }
+    catch {
+        return fallback;
+    }
+}
 export function registerTemplateTools(server, platform) {
     const config = platform.config;
     server.registerTool('template_list', {
@@ -24,31 +48,34 @@ export function registerTemplateTools(server, platform) {
         description: "Şablonun bir modüldeki kayıtlarını listeler (project_create'in templateOptions.filters'ını doldurmak için).",
         inputSchema: {
             id: guid,
-            module: z.string().describe("Module değeri: entity | microservice | workflow | page | layout | component | query | view …")
+            module: z.string().describe("Module değeri: entity | microservice | workflow | page | layout | component | query | view | variable | global-function (fonksiyonlar, iki kaynak) | flow … (platform Module enum değeri, kebab-case)")
         },
         annotations: readOnly
     }, handle(config, ({ id, module }) => platform.org('GET', `/templates/${id}/items`, { query: { module } })));
     server.registerTool('template_create', {
         title: 'Projeyi şablon olarak yayımla',
-        description: 'Mevcut projeden yeni bir şablon sürümü üretir. Görsel yükleme bu tool\'da desteklenmez (ikili aktarım kapsam dışı).',
+        description: "Mevcut projeden yeni bir şablon sürümü üretir. **Paketlenen environment `environmentId`'dir ve boş bırakılırsa platform PRODUCTION'ı paketler** (`CreateProjectAsTemplateCommand`: `EnvironmentId ??= ActiveEnvironments().First(f => f.IsProduction)`) — 'varsayılan environment' DEĞİL. Henüz promote edilmemiş projede production boştur: build 'success' döner ama şablon yalnız seed kayıtlarını taşır (microfunction/workflow/microservice sıfır). Geliştirmede yazdığınız içeriği paketlemek için development environment id'sini AÇIKÇA verin. Build asenkrondur: yanıt hemen döner, sürüm birkaç saniye sonra template_list'te görünür; içeriği template_items ile doğrulayın. Görsel yükleme bu tool'da desteklenmez (ikili aktarım kapsam dışı).",
         inputSchema: {
             projectId: guid,
             name: z.string().min(1),
             version: z.string().min(1).describe("Sürüm etiketi, ör. '1.0.0'"),
             description: z.string().optional(),
             changeLog: z.string().optional(),
-            environmentId: guid.optional().describe('Hangi environment\'ın içeriği paketlenecek; boşsa varsayılan')
+            environmentId: guid.optional().describe("Hangi environment'ın içeriği paketlenecek. BOŞSA PRODUCTION paketlenir (projenin varsayılan/development environment'ı değil) — development içeriğini şablona koyacaksanız o environment'ın id'sini açıkça verin.")
         },
         annotations: writes
-    }, handle(config, ({ projectId, name, version, description, changeLog, environmentId }) => {
+    }, handle(config, async ({ projectId, name, version, description, changeLog, environmentId }) => {
         const form = new URLSearchParams({ Name: name, Version: version });
+        const normalized = [];
         if (description)
             form.set('Description', description);
         if (changeLog)
             form.set('ChangeLog', changeLog);
         if (environmentId)
             form.set('EnvironmentId', environmentId);
-        return platform.org('POST', `/projects/${projectId}/templates`, { form });
+        else
+            normalized.push(await defaultTemplateEnvironmentNote(platform, projectId));
+        return withNormalization(await platform.org('POST', `/projects/${projectId}/templates`, { form }), normalized);
     }));
     server.registerTool('template_check_updates', {
         title: 'Şablon güncellemesi var mı',

package/dist/tools/workflows.js

@@ -4,7 +4,7 @@ import { evaluatePolicy, enforcePolicy, attachFindings } from '../knowledge/poli
 import { workflowOutline, resolvePart, resolvePatchOperations } from '../knowledge/outlines.js';
 import { patchResult, baseVersionOf } from '../platform/patch.js';
 import { writeDiff, withWriteDiff } from '../platform/writeDiff.js';
-import { policyRules } from '../knowledge/rules.js';
+import { policyRules, microfunctionStepFindings } from '../knowledge/rules.js';
 import { languageHeader } from '../knowledge/languageCodes.js';
 import { handle } from '../platform/responses.js';
 import fastJsonPatch from 'fast-json-patch';
@@ -116,7 +116,10 @@ export function registerWorkflowTools(server, platform) {
         annotations: writes
     }, handle(config, async ({ project, environment, applicationId, definition, policyOverride }) => {
         const normalized = normalizeWorkflowDefinition(definition);
-        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'create', workflowKind: definition.type }, policyOverride));
+        const findings = enforcePolicy([
+            ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'create', workflowKind: definition.type }, policyOverride),
+            ...await microfunctionStepFindings(platform, project, environment, definition, definition.type, policyOverride)
+        ]);
         const drift = unmappedMembers('CreateWorkflowCommand', definition);
         const payload = await platform.tenant('POST', project, `/workflows/${applicationId}`, { environment, body: definition });
         return attachFindings(withUnmappedMembers(withWriteDiff(withNormalization(payload, normalized), writeDiff(definition, payload)), drift), findings);
@@ -128,7 +131,10 @@ export function registerWorkflowTools(server, platform) {
         annotations: updates
     }, handle(config, async ({ project, environment, applicationId, id, definition, policyOverride }) => {
         const normalized = normalizeWorkflowDefinition(definition);
-        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'update', workflowKind: definition.type }, policyOverride));
+        const findings = enforcePolicy([
+            ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'update', workflowKind: definition.type }, policyOverride),
+            ...await microfunctionStepFindings(platform, project, environment, definition, definition.type, policyOverride)
+        ]);
         const drift = unmappedMembers('UpdateWorkflowCommand', definition);
         const payload = await platform.tenant('PUT', project, `/workflows/${applicationId}/${id}`, { environment, body: definition });
         return attachFindings(withUnmappedMembers(withWriteDiff(withNormalization(payload, normalized), writeDiff(definition, payload)), drift), findings);
@@ -145,7 +151,10 @@ export function registerWorkflowTools(server, platform) {
         const resolved = resolvePatchOperations(definition, operations);
         const patched = fastJsonPatch.applyPatch(definition, resolved.operations, true, false).newDocument;
         const normalized = normalizeWorkflowDefinition(patched);
-        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', patched, { operation: 'update', workflowKind: patched.type }, policyOverride));
+        const findings = enforcePolicy([
+            ...evaluatePolicy(config, policyRules, 'workflow', patched, { operation: 'update', workflowKind: patched.type }, policyOverride),
+            ...await microfunctionStepFindings(platform, project, environment, patched, patched.type, policyOverride)
+        ]);
         const drift = introducedUnmappedMembers('UpdateWorkflowCommand', (current?.data ?? current), patched);
         // Gövde değil FARK gönderilir: gateway normalizasyonları da op'a çevrilsin diye net diff
         // okunan kayıt ile son hâl arasından hesaplanır (tam PUT yok, yalnız değişen alanlar yazılır).
@@ -176,12 +185,21 @@ export function registerWorkflowTools(server, platform) {
     }, handle(config, ({ project, environment, id }) => platform.tenant('POST', project, `/workflows/clone/${id}`, { environment })));
     server.registerTool('workflow_preview', {
         title: 'Workflow önizle',
-        description: "Kaydedilmemiş workflow tanımını çalıştırır; kaydetmeden önce her akışı preview ile doğrulayın. definition = PreviewWorkflowCommand gövdesi. Test girdisi 'previewPayload' anahtarıyla verilir ('parameters'/'input' ÇALIŞMAZ), değişkenler 'previewVariables'. previewPayload STRING olmalıdır (JSON.stringify(...) ya da \"({ id: 1 })\") — nesne gönderilirse platform 'Unexpected end of input' ile 500 döner. Preview tek transaction'da koşar ve sonunda ROLLBACK edilir: table create/update step'leri kalıcı satır YAZMAZ (ölçüldü, İK koşusu W-1). Tek istisna code step içindeki dış HTTP çağrılarıdır — onlar geri alınamaz. Davranış kuralları: platform_guide('workflow'). " + constraintSummary('PreviewWorkflowCommand'),
+        description: "Kaydedilmemiş workflow tanımını çalıştırır; kaydetmeden önce her akışı preview ile doğrulayın. definition = PreviewWorkflowCommand gövdesi. Test girdisi 'previewPayload' anahtarıyla verilir ('parameters'/'input' ÇALIŞMAZ), değişkenler 'previewVariables'. previewPayload STRING olmalıdır (JSON.stringify(...) ya da \"({ id: 1 })\") — nesne gönderilirse platform 'Unexpected end of input' ile 500 döner. Akışın parameterDtoId'si YOKSA previewPayload verilmez (platform 400 döner; gateway alanı düşürüp gatewayNormalized ile bildirir). Preview tek transaction'da koşar ve sonunda ROLLBACK edilir: table create/update step'leri kalıcı satır YAZMAZ (ölçüldü, İK koşusu W-1). Tek istisna code step içindeki dış HTTP çağrılarıdır — onlar geri alınamaz. Davranış kuralları: platform_guide('workflow'). " + constraintSummary('PreviewWorkflowCommand'),
         inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid, definition: definitionParam, policyOverride: policyOverrideParam, language: languageParam },
         annotations: writes
     }, handle(config, async ({ project, environment, applicationId, definition, policyOverride, language }) => {
         const normalized = normalizeWorkflowDefinition(definition);
-        const findings = enforcePolicy(evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'preview', workflowKind: definition.type }, policyOverride));
+        // 33/S-6: parameterDtoId olmayan akışa previewPayload gönderilince platform 400 verir
+        // ("'previewPayload' requires a parameter DTO"). Girdisiz akışta alanın anlamı yok — düşürülür.
+        if (!definition.parameterDtoId && definition.previewPayload !== undefined) {
+            delete definition.previewPayload;
+            normalized.push("previewPayload düşürüldü — akışın parameterDtoId'si yok, platform 400 \"'previewPayload' requires a parameter DTO\" verir; girdi gerekiyorsa önce parameterDtoId + parameterBehavior tanımlayın");
+        }
+        const findings = enforcePolicy([
+            ...evaluatePolicy(config, policyRules, 'workflow', definition, { operation: 'preview', workflowKind: definition.type }, policyOverride),
+            ...await microfunctionStepFindings(platform, project, environment, definition, definition.type, policyOverride)
+        ]);
         const payload = await platform.tenant('POST', project, `/workflows/${applicationId}/preview`, { environment, body: definition, headers: languageHeader(language, normalized) });
         return attachFindings(withNormalization(payload, normalized), findings);
     }));