@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/tools/rows.js

@@ -1,7 +1,212 @@
-import { guid, projectParam, environmentParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
+import { findLocalizationCompanion, localizationRows, platformIgnoredLocalizations } from '../knowledge/localization.js';
+import { guid, entityRef, resolveEntityId, withResolved, projectParam, environmentParam, languageParam, pagingParams, readOnly, writes, updates, destructive } from './common.js';
+import { unmappedMembers, withUnmappedMembers } from '../knowledge/schemaGuard.js';
+import { withNormalization } from '../knowledge/normalize.js';
+import { RefResolver } from '../platform/refs.js';
+import { attachFindings, evaluatePolicy, enforcePolicy } from '../knowledge/policy.js';
+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)");
+/**
+ * `row_*` DBMS düzeyi bir satır yüzeyidir; var olan satır kümesinden TÜRETİLEN satırları
+ * (geçmiş, hareket, log, junction, backfill) gövdede taşımak onun işi değildir — 2026-09-05'te
+ * 802, 2026-09-06'da 552 satır bu yüzden elle yazıldı (`B-34`, `B-50`) ve ikinci koşunun 65
+ * dakikasının ~21'i buraya gitti. Eşik büyük tutuldu: bulgu her toplu yazmada bağırırsa koşunun
+ * sinyal oranını kendisi düşürür, bu yüzden yalnız "elle taşınamayacak kadar büyük" dizilerde
+ * konuşur ve cümlesi KOŞULLUDUR — dışarıdan gelen veriyi (içe aktarma, kullanıcı girdisi)
+ * yazan çağıranı suçlamaz.
+ */
+const DERIVED_ROW_THRESHOLD = 50;
+function derivedRowFindings(rows) {
+    if (!rows || rows.length < DERIVED_ROW_THRESHOLD)
+        return [];
+    return [{
+            ruleId: 'ROW-001',
+            severity: 'warn',
+            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()
+    .describe("Dil kodu → çok dilli alan değerleri; ör. { tr: { name: 'Yıllık izin' }, en: { name: 'Annual leave' } }. Verilen her dil upsert edilir, verilmeyen dile dokunulmaz. Dil kodu projenin dil listesinde değilse platform 400 döner ve ana satır da yazılmaz.");
 export function registerRowTools(server, platform) {
     const config = platform.config;
     server.registerTool('row_list', {
@@ -10,106 +215,335 @@ export function registerRowTools(server, platform) {
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            entityId: guid,
+            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
         },
         annotations: readOnly
-    }, handle(config, async ({ project, environment, entityId, ...body }) => {
-        const payload = await platform.tenant('POST', project, `/entities/${entityId}/row/list`, { environment, body });
+    }, handle(config, async ({ project, environment, entityId, language, ...body }) => {
+        const notes = [];
+        const headers = languageHeader(language, notes);
+        const resolver = new RefResolver(platform, project, environment);
+        const resolvedEntityId = await resolveEntityId(resolver, entityId);
+        const payload = await platform.tenant('POST', project, `/entities/${resolvedEntityId}/row/list`, { environment, body, headers });
         const wanted = body.selectedFields ?? [];
-        if (!wanted.length || !payload || typeof payload !== 'object' || Array.isArray(payload))
-            return payload;
-        const rows = payload.data;
-        if (!Array.isArray(rows))
-            return payload;
-        const keep = new Set([...wanted.map(field => field.toLowerCase()), 'id']);
-        return {
+        const rows = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload.data : undefined;
+        if (!wanted.length || !Array.isArray(rows))
+            return withNormalization(withResolved(payload, resolver.resolved), notes);
+        /**
+         * 'localizations' keep listesine girmezse includeTranslations'ın getirdiği çeviriler tam da
+         * onları isteyen çağrıda kırpılırdı: iki parametre birlikte verildiğinde sessizce boşa çıkar.
+         */
+        const keep = new Set([...wanted.map(field => field.toLowerCase()), 'id', ...(body.includeTranslations ? ['localizations'] : [])]);
+        return withNormalization(withResolved({
             ...payload,
             data: rows.map(row => row && typeof row === 'object' && !Array.isArray(row)
                 ? Object.fromEntries(Object.entries(row).filter(([key]) => keep.has(key.toLowerCase())))
                 : row)
-        };
+        }, resolver.resolved), notes);
     }));
     server.registerTool('row_get', {
         title: 'Satır getir',
         description: 'Tek satırı id ile getirir.',
-        inputSchema: { project: projectParam, environment: environmentParam, entityId: guid, id: z.string().min(1) },
+        inputSchema: { project: projectParam, environment: environmentParam, entityId: entityRef, id: z.string().min(1), language: languageParam, includeTranslations: includeTranslationsParam },
         annotations: readOnly
-    }, handle(config, ({ project, environment, entityId, id }) => platform.tenant('GET', project, `/entities/${entityId}/row/${encodeURIComponent(id)}`, { environment })));
+    }, handle(config, async ({ project, environment, entityId, id, language, includeTranslations }) => {
+        const notes = [];
+        const headers = languageHeader(language, notes);
+        const resolver = new RefResolver(platform, project, environment);
+        const resolvedEntityId = await resolveEntityId(resolver, entityId);
+        const payload = await platform.tenant('GET', project, `/entities/${resolvedEntityId}/row/${encodeURIComponent(id)}`, { environment, headers, ...(includeTranslations ? { query: { includeTranslations: true } } : {}) });
+        return withNormalization(withResolved(payload, resolver.resolved), notes);
+    }));
     server.registerTool('row_create', {
         title: 'Satır ekle',
-        description: "Tek satır için 'row', çoklu ekleme için 'rows' verin (ikisi birden verilmez).",
+        description: "Tek satır için 'row', çoklu ekleme için 'rows' verin (ikisi birden verilmez). Çoklu dilli entity'de 'localizations: { tr: {…}, en: {…} }' ile dil satırlarını da aynı çağrıda yazar: companion entity'yi ve FK'yı gateway bulur (yalnız 'row' ile). 'rows' TEK TRANSACTION'da yazılır: bir satır doğrulamadan düşerse HİÇBİRİ yazılmaz ve hata hangi satır indeksinin düştüğünü söyler. Automation'lar satır BAŞINA tetiklenir — sync (isQueue:true) automation'lar aynı transaction'da satır satır koşar, biri düşerse toplu yazma geri alınır. Tek çağrıda en çok 1000 satır. SINIR: row_* bir veritabanı yönetim yüzeyidir — satırları GÖVDEDE taşır. VAR OLAN satırlardan türetilen bir küme (geçmiş/hareket/log/junction, backfill) bu yola AİT DEĞİLDİR; onu tek bir kayıtlı 'INSERT … SELECT' sorgusu + query kaynaklı uç yazar, reçete platform_guide('entity') §'Toplu ve türetilmiş satır'. Toplu ucun id döndürmesine GÜVENMEYİN: 2026-09-07 ölçümünde boş gövde döndü (2026-09-05'te anahtar listesi dönüyordu, fark B-63) — id gerekiyorsa ardından row_list çekin. TOPLU eklemede dil değerlerini satırın KENDİ içine koyun ('rows: [{ kod: 'A1', localizations: { tr: {…} } }]') — üst düzey 'localizations' toplu uçta hangi satıra ait olduğunu söyleyemez. 'row' içine düz çok dilli slug yazarsanız değer İSTEK DİLİ için kaydedilir — dili 'language' ile seçin.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            entityId: guid,
+            entityId: entityRef,
             row: rowValues.optional(),
-            rows: z.array(z.record(z.unknown())).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, ({ project, environment, entityId, row, rows }) => {
-        if (row && rows)
-            throw new Error("'row' ve 'rows' birlikte verilemez.");
-        if (rows)
-            return platform.tenant('POST', project, `/entities/${entityId}/row/bulk`, { environment, body: { rows } });
-        if (row)
-            return platform.tenant('POST', project, `/entities/${entityId}/row`, { environment, body: { row } });
-        throw new Error("'row' ya da 'rows' parametrelerinden biri zorunlu.");
+    }, 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 (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 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 (bulkRows) {
+            const bulkEntityId = await resolveEntityId(resolver, entityId);
+            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 } : {}) };
+        const drift = unmappedMembers('CreateRowCommand', body);
+        const response = await platform.tenantWithHeaders('POST', project, `/entities/${resolvedEntityId}/row`, { environment, headers, body });
+        const created = response.body;
+        if (!wantedLocalizations || !platformIgnoredLocalizations(response.headers)) {
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved(created, resolver.resolved), notes), drift), shapeFindings);
+        }
+        notes.push("platform 'localizations' alanını tanımıyor (X-Unmapped-Members); dil satırlarını gateway companion entity'ye yazdı.");
+        const entity = await resolver.entity(entityId);
+        let mainRowId = created.data?.id;
+        try {
+            // Satır sözlüğü alan SLUG'larıyla anahtarlanır ve PK slug'ı 'id' olmak ZORUNDA değildir
+            // (CreateRowCommandHandler `entityDto.PrimaryKey()` kullanır). 'id' yoksa gerçek PK'yı
+            // bulmadan yazmak FK'sı NULL dil satırları üretir ve bunu başarı diye raporlardı.
+            if (mainRowId === undefined || mainRowId === null) {
+                const primaryKey = (await resolver.entityFields(entity)).find(field => field.primaryKey);
+                mainRowId = primaryKey ? created.data?.[primaryKey.slug] : undefined;
+            }
+            if (mainRowId === undefined || mainRowId === null) {
+                throw new Error("Ana satır yazıldı ama yanıtta birincil anahtar okunamadı; dil satırları FK'sız yazılmadı (FK'sı boş satır sessiz yanlış olurdu).");
+            }
+            const companion = await findLocalizationCompanion(resolver, entity);
+            const localizationBatch = localizationRows(companion, mainRowId, wantedLocalizations);
+            await platform.tenant('POST', project, `/entities/${companion.entityId}/row/bulk`, { environment, body: { rows: localizationBatch } });
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved({ ...created, localizations: { entityId: companion.entityId, languages: Object.keys(wantedLocalizations), count: localizationBatch.length } }, resolver.resolved), notes), drift), shapeFindings);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return attachFindings(withUnmappedMembers(withNormalization(withResolved({ ...created, localizationsFailed: { mainRowId, error: message, note: 'Ana satır YAZILDI, dil satırları yazılamadı; gateway geri alamaz. Ya companion entity\'ye row_create ile elle yazın ya da ana satırı row_delete ile silip tekrar deneyin.' } }, resolver.resolved), notes), drift), shapeFindings);
+        }
     }));
     server.registerTool('row_update', {
         title: 'Satır güncelle',
-        description: "Tek satır için 'row', çoklu güncelleme için 'rows' verin; satır id alanı gövdede olmalıdır.",
+        description: "Tek satır için 'row', çoklu güncelleme için 'rows' verin; satır id alanı gövdede olmalıdır. 'rows' TEK TRANSACTION'da yazılır: bir satır düşerse HİÇBİRİ yazılmaz ve hata hangi satır indeksinin düştüğünü söyler. Automation'lar satır BAŞINA tetiklenir — sync (isQueue:true) automation'lar aynı transaction'da satır satır koşar. Tek çağrıda en çok 1000 satır. Aynı sınır row_create'te olduğu gibi geçerlidir: var olan satırlardan HESAPLANAN toplu güncelleme (durum/toplam/damga backfill'i) kayıtlı bir 'UPDATE … FROM' sorgusuna aittir — platform_guide('entity') §'Toplu ve türetilmiş satır'. Çeviri güncellemek için 'localizations: { tr: {…}, en: {…} }' verin — ana satır hiç değişmese de yalnız çeviriler yazılabilir. TOPLU güncellemede aynı nesne satırın KENDİ içine konur ('rows: [{ id: 1, localizations: { tr: {…} } }]'); 'row' içindeki düz çok dilli slug İSTEK DİLİNE yazılır.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            entityId: guid,
+            entityId: entityRef,
             row: rowValues.optional(),
-            rows: z.array(z.record(z.unknown())).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, ({ project, environment, entityId, row, rows }) => {
-        if (row && rows)
-            throw new Error("'row' ve 'rows' birlikte verilemez.");
-        if (rows)
-            return platform.tenant('PUT', project, `/entities/${entityId}/row/bulk`, { environment, body: { rows } });
-        if (row)
-            return platform.tenant('PUT', project, `/entities/${entityId}/row`, { environment, body: { row } });
-        throw new Error("'row' ya da 'rows' parametrelerinden biri zorunlu.");
+    }, 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 (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 (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.",
+        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.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            entityId: guid,
+            entityId: entityRef,
             id: z.string().optional(),
             ids: z.array(z.union([z.string(), z.number()])).optional()
         },
         annotations: destructive
-    }, handle(config, ({ project, environment, entityId, id, ids }) => {
+    }, handle(config, async ({ project, environment, entityId, id, ids }) => {
         if (id && ids)
             throw new Error("'id' ve 'ids' birlikte verilemez.");
+        if (!id && !ids)
+            throw new Error("'id' ya da 'ids' parametrelerinden biri zorunlu.");
+        const resolver = new RefResolver(platform, project, environment);
+        const resolvedEntityId = await resolveEntityId(resolver, entityId);
         if (ids)
-            return platform.tenant('POST', project, `/entities/${entityId}/row/bulk/delete`, { environment, body: { rowIds: ids } });
-        if (id)
-            return platform.tenant('DELETE', project, `/entities/${entityId}/row/${encodeURIComponent(id)}`, { environment });
-        throw new Error("'id' ya da 'ids' parametrelerinden biri zorunlu.");
+            return withResolved(await platform.tenant('POST', project, `/entities/${resolvedEntityId}/row/bulk/delete`, { environment, body: { rowIds: ids } }), resolver.resolved);
+        return withResolved(await platform.tenant('DELETE', project, `/entities/${resolvedEntityId}/row/${encodeURIComponent(String(id))}`, { environment }), resolver.resolved);
     }));
     server.registerTool('row_next_code', {
         title: 'Sıradaki kodu üret',
-        description: 'Incremental tipli alan için sıradaki kodu döner.',
+        description: "Incremental tipli alan için sıradaki kodu döner ve sayacı İLERLETMEZ (persist:false) — kodun nasıl görüneceğini kaydetmeden görmek için. Gövde row_create'in Incremental alanına yazdığınız nesneyle aynıdır: { prefix, separator, counter, digitCount }. 'counter' ve 'digitCount' platform tarafında ZORUNLUDUR (GetNextIncrementalCodeQueryValidator: NotEmpty) — eksik verilirse istek 400 döner, bu yüzden gateway de ikisini zorunlu tutar.",
         inputSchema: {
             project: projectParam,
             environment: environmentParam,
-            entityId: guid,
+            entityId: entityRef,
             fieldId: guid,
-            prefix: z.string().optional(),
-            separator: z.string().optional(),
-            digitCount: z.number().int().optional()
+            prefix: z.string().optional().describe("Kodun önüne gelen sabit ('EMP')"),
+            separator: z.string().optional().describe("Önek ile sayaç arasındaki ayraç ('-'); verilmezse boş"),
+            counter: z.number().int().min(1).describe('Sayacın BAŞLANGIÇ değeri — platform zorunlu tutar (NotEmpty, yani 0 kabul edilmez). Alanın kayıtlı sayacını bilmiyorsanız entity_get ile alanın tanımına bakın.'),
+            digitCount: z.number().int().min(1).describe("Sayacın basamak sayısı (4 → '0006'); platform zorunlu tutar (NotEmpty)")
         },
         annotations: readOnly
-    }, handle(config, ({ project, environment, entityId, ...body }) => platform.tenant('POST', project, `/entities/${entityId}/row/next-code`, { environment, body })));
+    }, handle(config, async ({ project, environment, entityId, ...body }) => {
+        const resolver = new RefResolver(platform, project, environment);
+        const resolvedEntityId = await resolveEntityId(resolver, entityId);
+        return withResolved(await platform.tenant('POST', project, `/entities/${resolvedEntityId}/row/next-code`, { environment, body }), resolver.resolved);
+    }));
 }