@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/knowledge/schemaGuard.js

@@ -0,0 +1,199 @@
+import { unstoredKeys } from '../platform/writeDiff.js';
+import { logStep } from '../observability/trace.js';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+const schemasDirectory = join(dirname(fileURLToPath(import.meta.url)), '..', 'resources', 'schemas');
+const documents = new Map();
+/**
+ * Yazma gövdesindeki TANINMAYAN anahtarı platform sessizce yok sayar: `isUnique` gönderilen bir
+ * index UNIQUE OLMADAN kurulur, istek 200 döner (ölçüldü 2026-09-07, `ENT-013`).
+ *
+ * Backend bunun için `X-Unmapped-Members` başlığını yazıyor ama kanal olarak KULLANILAMAZ:
+ * yalnız İLK eşleşmeyen anahtarı bildiriyor ve gateway'in GET→PUT gidiş-dönüşü gövdeye yedi
+ * yapısal anahtar koyuyor (`slug` · `datasourceId` · `primaryKey` · `type` · `applications` ·
+ * `automationCount` · `audit`). Sırada `slug` önce geldiği için başlık sıradan bir `entity_patch`
+ * çağrısında hep `slug` der ve ajanın yazdığı `indexes[0].isUnique` ASLA görünmez — kanal
+ * sinyali maskeler (g-03 Adım 0 ölçümü).
+ *
+ * Bu yüzden denetim gateway'in kendi taşıdığı şemalardan yapılır: çevrimdışı çalışır, TÜM
+ * anahtarları görür ve `introducedUnmappedMembers` sayesinde ajanın yazdığını gateway'in
+ * taşıdığından ayırabilir.
+ */
+function schemaDocument(command) {
+    if (documents.has(command))
+        return documents.get(command);
+    // Ad dosya yoluna giriyor: dizin dışına çıkan ya da uzantı taşıyan bir değer okunmaz.
+    const document = /^[A-Za-z0-9_]+$/.test(command)
+        ? (() => {
+            try {
+                return JSON.parse(readFileSync(join(schemasDirectory, `${command}.json`), 'utf8'));
+            }
+            catch {
+                return undefined;
+            }
+        })()
+        : undefined;
+    documents.set(command, document);
+    return document;
+}
+/** `$ref` ya da tek elemanlı `allOf: [{ $ref }]` sarmalının hedef adı; ikincisi Swashbuckle'ın kısıt/nullable eklenmiş referans için ürettiği biçimdir. */
+function referenceName(node) {
+    if (!node || typeof node !== 'object')
+        return undefined;
+    const record = node;
+    if (typeof record.$ref === 'string')
+        return record.$ref.replace('#/components/schemas/', '');
+    const allOf = record.allOf;
+    if (Array.isArray(allOf) && allOf.length === 1)
+        return referenceName(allOf[0]);
+    return undefined;
+}
+function resolve(document, node) {
+    if (!node || typeof node !== 'object')
+        return undefined;
+    const record = node;
+    const reference = record.$ref;
+    if (typeof reference === 'string') {
+        // Üretilen şemalarda tek biçim var: '#/components/schemas/<tam ad>'.
+        const name = reference.replace('#/components/schemas/', '');
+        const components = document.components?.schemas;
+        const target = components?.[name];
+        return target && typeof target === 'object' ? target : undefined;
+    }
+    // FluentValidation kısıtları swagger'a aktığından beri (2026-09-08) referanslı bir özellik
+    // `allOf: [{ $ref }]` + kendi anahtarları (nullable, minLength…) şeklinde gelebiliyor; hedef
+    // çözülür, özelliğin kendi anahtarları üstüne yazılır.
+    const allOf = record.allOf;
+    if (Array.isArray(allOf) && allOf.length === 1) {
+        const inner = resolve(document, allOf[0]);
+        const { allOf: _dropped, ...own } = record;
+        return inner ? { ...inner, ...own } : undefined;
+    }
+    return record;
+}
+function walk(document, schema, value, path, into) {
+    if (!schema || !value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        const items = resolve(document, schema.items);
+        value.forEach((entry, index) => walk(document, items, entry, `${path}[${index}]`, into));
+        return;
+    }
+    const properties = schema.properties;
+    if (!properties)
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        const child = path === '' ? key : `${path}.${key}`;
+        // `additionalProperties: false` olmayan bir düğümde serbest anahtar meşrudur (ör. `properties`
+        // alanı gibi şemasız sözlükler) — orada susmak yanlış alarmı önler.
+        if (!Object.hasOwn(properties, key)) {
+            // `writeDiff`'in gerekçeli istisnaları burada da geçerli: gateway'in bilerek gönderdiği,
+            // platformun `fieldId`'den çözüp saklamadığı kolaylık alanları hata değildir. Tek küme
+            // tutulur — ikiye ayrılırsa ayrışırlar.
+            if (schema.additionalProperties === false && !unstoredKeys.has(key))
+                into.push(child);
+            continue;
+        }
+        walk(document, resolve(document, properties[key]), entry, child, into);
+    }
+}
+/**
+ * `command` üretilen şema dosyasının adıdır (`ngapps://schemas/<command>`); bilinmeyen ad
+ * sessizce boş liste döner — şema yoksa iddia da yoktur.
+ */
+export function unmappedMembers(command, body) {
+    const document = schemaDocument(command);
+    if (!document)
+        return [];
+    const found = [];
+    walk(document, document.schema, body, '', found);
+    return found;
+}
+/**
+ * Yamanın GETİRDİĞİ eşleşmeyen anahtarları döner. Gateway'in GET'ten taşıdığı yapısal alanlar iki
+ * tarafta da bulunduğu için elenir; geriye yalnız çağıranın eklediği kalır.
+ */
+export function introducedUnmappedMembers(command, before, after) {
+    const existing = new Set(unmappedMembers(command, before));
+    return unmappedMembers(command, after).filter(member => !existing.has(member));
+}
+/**
+ * Yanıt yan kanalı (`runtimeErrors` · `gatewayMasked` · `silentlyDropped` ile aynı desen).
+ * Alan adı `secretKeyPattern` ile eşleşmemeli, yoksa değeri sessizce `***` olur — GW-001 dersi;
+ * `entities.test.ts` bunu yanıt üzerinde doğruluyor.
+ */
+export function withUnmappedMembers(payload, members) {
+    if (members.length === 0 || !payload || typeof payload !== 'object')
+        return payload;
+    logStep('şema ✕', `${members.length} anahtar komut şemasında yok — platform onları sessizce yok sayar`, members);
+    return {
+        ...payload,
+        unmappedMembers: members,
+        unmappedMembersNote: "Bu anahtarlar gönderdiğiniz komutun şemasında YOK: platform onları hata vermeden YOK SAYAR, yani o alanlar kaydedilmedi. Doğru adlar için ngapps://schemas kaynağına bakın."
+    };
+}
+const numericKinds = ['minLength', 'maxLength', 'minimum', 'maximum', 'minItems'];
+function limitOf(path, schema, required) {
+    const limit = { path };
+    if (required)
+        limit.required = true;
+    for (const kind of numericKinds) {
+        if (typeof schema[kind] === 'number')
+            limit[kind] = schema[kind];
+    }
+    if (typeof schema.pattern === 'string' && schema.pattern !== '')
+        limit.pattern = schema.pattern;
+    return Object.keys(limit).length > 1 ? limit : undefined;
+}
+function collectSchemaLimits(document, schema, path, chain, into) {
+    const properties = schema?.properties;
+    if (!schema || !properties)
+        return;
+    const required = new Set(Array.isArray(schema.required) ? schema.required.map(String) : []);
+    for (const [key, raw] of Object.entries(properties)) {
+        const childPath = path === '' ? key : `${path}.${key}`;
+        const child = resolve(document, raw);
+        if (!child)
+            continue;
+        const limit = limitOf(childPath, child, required.has(key));
+        if (limit)
+            into.push(limit);
+        if (child.type === 'array') {
+            const items = resolve(document, child.items);
+            if (!items)
+                continue;
+            const itemLimit = limitOf(`${childPath}[]`, items, false);
+            if (itemLimit)
+                into.push(itemLimit);
+            const itemsName = referenceName(child.items);
+            // Özyineli tip (FieldDto.fields → FieldDto) bir kez yürünür; katalog da yalnız ilk seviyeyi tanır.
+            if (itemsName !== undefined && chain.includes(itemsName))
+                continue;
+            collectSchemaLimits(document, items, `${childPath}[]`, itemsName !== undefined ? [...chain, itemsName] : chain, into);
+            continue;
+        }
+        const childName = referenceName(raw);
+        if (childName !== undefined && chain.includes(childName))
+            continue;
+        collectSchemaLimits(document, child, childPath, childName !== undefined ? [...chain, childName] : chain, into);
+    }
+}
+/** Şema dokümanındaki (`{ schema, components }`) bütün alan kısıtlarını katalog yol notasyonuyla (`fields[].name`) döner. */
+export function schemaLimitsOf(document) {
+    if (!document)
+        return [];
+    const found = [];
+    const rootName = referenceName(document.schema);
+    collectSchemaLimits(document, resolve(document, document.schema), '', rootName !== undefined ? [rootName] : [], found);
+    return found;
+}
+/**
+ * Paketlenmiş swagger şemasından FluentValidation kaynaklı kısıtlar (`MicroElements.Swashbuckle.FluentValidation`,
+ * backend 2026-09-08): NotEmpty → required (+ minLength 1), MaximumLength → maxLength, Matches → pattern,
+ * InclusiveBetween → minimum/maximum. `npm run generate-schemas` yenilenmeden eski şemada kısıt yoktur ve
+ * bu liste boş döner — o durumda `backendConstraints.ts` kataloğu tek başına konuşur.
+ */
+export function schemaLimits(command) {
+    return schemaLimitsOf(schemaDocument(command));
+}

package/dist/knowledge/styleResolve.js

@@ -156,7 +156,8 @@ export const STYLE_GROUP_FIELDS = {
         'borderBottom',
         'borderLeft',
         'shadow',
-        'contentOverflow'
+        'contentOverflow',
+        'opacity'
     ],
     typographyStyle: [
         'textColor',
@@ -171,6 +172,8 @@ export const STYLE_GROUP_FIELDS = {
     ],
     hoverStyle: ['background', 'borderColor', 'shadow', 'lift', 'transitionMs']
 };
+/** `overflowTarget` için "kökün kendisi" işareti (frontend `ROOT_TARGET` kopyası). */
+export const ROOT_TARGET = '&';
 export function composeTypedStyle(input, ext) {
     const groups = {};
     if (isPlainObject(input.surfaceStyle)) {
@@ -198,8 +201,19 @@ export function composeTypedStyle(input, ext) {
                 groups.border = `1px ${surface.borderStyle || 'solid'} ${surface.borderColor || DEFAULT_DIVIDER_COLOR}`;
             }
         }
+        // Opaklık yüzdedir (eski Surface bloğuyla aynı sözleşme): 100 ve boş
+        // yazılmaz, aralık dışı yok sayılır.
+        const opacity = asNumber(surface.opacity);
+        if (opacity !== undefined && opacity >= 0 && opacity < 100) {
+            groups.opacity = String(opacity / 100);
+        }
+        // `ROOT_TARGET` (`&`) kökün kendisidir: kendi derleyicisi olmayan kaplarda
+        // yüzey düğüm kutusuna yazılır ve kaydırılan da odur.
         if (isSet(surface.contentOverflow) && ext?.overflowTarget) {
-            nest(groups, ext.overflowTarget, { overflow: surface.contentOverflow });
+            if (ext.overflowTarget === ROOT_TARGET)
+                groups.overflow = surface.contentOverflow;
+            else
+                nest(groups, ext.overflowTarget, { overflow: surface.contentOverflow });
         }
     }
     if (isPlainObject(input.typographyStyle)) {
@@ -414,6 +428,44 @@ export const TYPED_STYLE_COMPONENTS = {
         omit: { hoverStyle: ['borderColor'] }
     }
 };
+/**
+ * Kendi derleyicisi OLMAYAN kap bileşenleri (2026-09-04): şemalarında
+ * `surfaceStyle` grubu var ama bileşen prop'u okumaz — render katmanı yüzeyi
+ * düğüm kutusuna (`.ng-app__node-item`) genel yolla yazar, taşma kökün
+ * kendisine gider (`packages/ng-apps-ui/src/style-groups/node-surface.ts`).
+ * Bu tipler `TYPED_STYLE_COMPONENTS`'a GİRMEZ: `style` kaçış kanalı onlarda
+ * eski birleşik kaskadla (tema+preset+own) çözülmeye devam eder.
+ */
+export const NODE_SURFACE_TYPES = new Set([
+    'table',
+    'datatable',
+    'form',
+    'collapsible-container',
+    'drawer',
+    'modal',
+    'popover',
+    'tabs',
+    'stepper',
+    'repeater',
+    'html',
+    'file-viewer',
+    'document-editor',
+    'layout',
+    'layout-region',
+    'layout-shell',
+    'qm-content',
+    'qm-sidebar',
+    'auth-layout'
+]);
+const NODE_SURFACE_EXTENSION = { overflowTarget: ROOT_TARGET };
+/** Düğüm kutusuna inen yüzey; kap tipi değilse ya da grup boşsa yok. */
+export function composeNodeSurfaceStyle(type, surfaceStyle) {
+    if (!type || !NODE_SURFACE_TYPES.has(type))
+        return undefined;
+    if (!isPlainObject(surfaceStyle))
+        return undefined;
+    return composeTypedStyle({ surfaceStyle }, NODE_SURFACE_EXTENSION);
+}
 /** text derlemesi — testler ve dış tüketiciler için sarmalayıcı. */
 export function composeTextStyle(input) {
     return composeTypedStyle(input, TYPED_STYLE_COMPONENTS.text.ext);
@@ -467,9 +519,16 @@ export function resolveNodeStyleReport(node, source) {
         own: isPlainObject(ownStyle) ? Object.keys(ownStyle).filter(key => key !== STYLE_PRESET_KEY).length > 0 : Boolean(ownStyle)
     };
     if (!config) {
-        // Kayıtsız tip: eski birleşik kaskad.
+        // Kayıtsız tip: eski birleşik kaskad. Kap tiplerinde tipli yüzey grubu
+        // düğüm kutusuna ayrıca iner; rapor onu kaskadın ÜSTÜNE koyar (kutu,
+        // bileşenin kökünü sarar).
         const cascaded = resolveNodeStyle(ownStyle, source, node.type);
-        return cascaded === undefined ? { styleLayers: layers } : { resolvedStyle: cascaded, styleLayers: layers };
+        const nodeSurface = composeNodeSurfaceStyle(node.type, rawProp(props, 'surfaceStyle'));
+        const typedLayers = nodeSurface ? { ...layers, typedGroups: ['surfaceStyle'] } : layers;
+        const resolved = cascaded === undefined && nodeSurface === undefined
+            ? undefined
+            : deepMergeStyle((cascaded ?? {}), nodeSurface ?? {});
+        return resolved === undefined ? { styleLayers: typedLayers } : { resolvedStyle: resolved, styleLayers: typedLayers };
     }
     // Tipli komponent gruplar boşken de tipli yoldan geçer: uzantı emekli
     // prop'ları okuyabilir (text'in isBold/align/color takma adı) ve K4 sırası

package/dist/observability/trace.js

@@ -1,11 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { secretKeyPattern } from '../platform/secrets.js';
 const defaultDirectory = join(process.cwd(), 'logs');
 const activeTrace = new AsyncLocalStorage();
 const activeRequest = new AsyncLocalStorage();
 const inFlight = new Set();
-const secretKeyPattern = /pass|secret|token|authorization|api[-_]?key|credential|connectionstring/i;
 const detailIndent = 26;
 let level = 'off';
 let logFile;
@@ -180,6 +180,25 @@ function renderTrace(trace, outcome) {
     lines.push('');
     return `${lines.join('\n')}\n`;
 }
+/**
+ * `runtimeErrors` kayıtlarını DÜZ METNE çevirir. Eskiden `runtimeErrors.map(String)` yazılıyordu
+ * ve nesne `[object Object]`e düşüyordu: 2026-09-06 koşusunda tool mesajı hangi adımın neden
+ * düştüğünü söylemiyordu, oysa doğru cümle aynı yanıtın içinde duruyordu (`S-4`).
+ *
+ * Yalnız İLK hata yazılır ve kalan sayılır — mesaj bir özet satırıdır, liste değil. Kullanıcı
+ * verisi taşıyabildiği için cümle 300 karakterde kesilir; tamamı günlüktedir.
+ */
+export function describeRuntimeErrors(errors) {
+    const first = (errors[0] ?? {});
+    const where = [first.step?.name, first.element ? `${first.element}${first.property ? `.${first.property}` : ''}` : undefined]
+        .filter(Boolean)
+        .join(' → ');
+    const message = typeof first.message === 'string' && first.message.length > 0
+        ? first.message
+        : JSON.stringify(first);
+    const rest = errors.length > 1 ? ` (+${errors.length - 1} hata daha)` : '';
+    return `${where ? `${where} — ` : ''}${clip(message, 300)}${rest} · tamamı günlükte`;
+}
 function describeResult(result) {
     const call = result;
     const text = Array.isArray(call?.content)
@@ -187,9 +206,14 @@ function describeResult(result) {
         : '';
     if (call?.isError)
         return { ok: false, summary: clip(text, 400) };
-    const runtimeErrors = call?.structuredContent?.runtimeErrors;
+    const structured = call?.structuredContent;
+    const runtimeErrors = structured?.runtimeErrors;
     if (Array.isArray(runtimeErrors) && runtimeErrors.length > 0) {
-        return { ok: false, summary: `çalışma anı hatası (platform HTTP 200 döndü): ${clip(runtimeErrors.map(String).join(' | '), 400)}` };
+        // Kasıtlı negatif test bir kusur değil bir KANIT: çağıran beklediğini söylediyse satır
+        // başarılı sayılır ve ölçüm aracının plansız hata oranını şişirmez (S-4).
+        return structured?.expectedFailure === true
+            ? { ok: true, summary: `beklenen çalışma anı hatası (negatif test): ${describeRuntimeErrors(runtimeErrors)}` }
+            : { ok: false, summary: `çalışma anı hatası (platform HTTP 200 döndü): ${describeRuntimeErrors(runtimeErrors)}` };
     }
     const effect = summarizeEffect(text);
     return { ok: true, summary: `${Buffer.byteLength(text, 'utf8')} B yanıt${effect ? ` · ${effect}` : ''}` };

package/dist/platform/csv.js

@@ -0,0 +1,123 @@
+/**
+ * Gateway'in kendi minimal RFC 4180 okuyucusu. `packages/ng-apps-ui`'daki `csv-parse.ts`
+ * kopyalanmaz: o dosya tarayıcı için yazılmıştır ve bu proje frontend workspace'ine dahil
+ * değildir (sözleşme D5) — kopya iki yerde birden bozulurdu.
+ *
+ * Değerler HEP string döner. Tip dönüşümü backend'in işidir: `1.234,56` ile `1,234.56` arasındaki
+ * fark kültüre bağlıdır ve gateway istek kültürünü bilmez.
+ */
+/**
+ * Ayraç ilk satırdan tahmin edilir. Türkçe Excel `;` ile yazar ve o dosyalarda virgül ONDALIK
+ * AYRACIDIR — yanlış tahmin `1,5` değerini iki sütuna böler, hem de sessizce.
+ */
+export function detectDelimiter(firstLine) {
+    let semicolons = 0;
+    let commas = 0;
+    let quoted = false;
+    for (const character of firstLine) {
+        if (character === '"')
+            quoted = !quoted;
+        else if (quoted)
+            continue;
+        else if (character === ';')
+            semicolons += 1;
+        else if (character === ',')
+            commas += 1;
+    }
+    return semicolons > commas ? ';' : ',';
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function firstLineOf(text) {
+    let quoted = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const character = text[index];
+        if (character === '"')
+            quoted = !quoted;
+        else if (!quoted && (character === '\n' || character === '\r'))
+            return text.slice(0, index);
+    }
+    return text;
+}
+/**
+ * Satır satır hücre dizisi. Tırnaklı hücre ayraç ve satır sonu taşıyabilir, `""` tek tırnaktır;
+ * tamamen boş satırlar atılır — Excel'in dosya sonuna bıraktığı boş satır aksi hâlde her alanı
+ * boş bir kayıt üretirdi.
+ */
+export function parseCsv(text, delimiter) {
+    const content = stripBom(text);
+    const separator = delimiter ?? detectDelimiter(firstLineOf(content));
+    const rows = [];
+    let row = [];
+    let value = '';
+    let quoted = false;
+    let index = 0;
+    const endValue = () => {
+        row.push(value);
+        value = '';
+    };
+    const endRow = () => {
+        endValue();
+        if (row.some(cell => cell.length > 0))
+            rows.push(row);
+        row = [];
+    };
+    while (index < content.length) {
+        const character = content[index];
+        if (quoted) {
+            if (character === '"') {
+                if (content[index + 1] === '"') {
+                    value += '"';
+                    index += 2;
+                    continue;
+                }
+                quoted = false;
+                index += 1;
+                continue;
+            }
+            value += character;
+            index += 1;
+            continue;
+        }
+        if (character === '"' && value.length === 0) {
+            quoted = true;
+            index += 1;
+            continue;
+        }
+        if (character === separator) {
+            endValue();
+            index += 1;
+            continue;
+        }
+        if (character === '\r' || character === '\n') {
+            endRow();
+            index += character === '\r' && content[index + 1] === '\n' ? 2 : 1;
+            continue;
+        }
+        value += character;
+        index += 1;
+    }
+    if (value.length > 0 || row.length > 0)
+        endRow();
+    return rows;
+}
+/**
+ * Başlık satırını anahtar yapan satır sözlükleri. Başlık boş olan sütun atlanır (Excel'in sağa
+ * doğru uzattığı boş sütunlar aksi hâlde `''` anahtarlı bir alan üretirdi) ve fazladan hücre
+ * taşıyan satır kırpılır.
+ */
+export function csvRows(text, delimiter) {
+    const grid = parseCsv(text, delimiter);
+    if (grid.length === 0)
+        return [];
+    const headers = (grid[0] ?? []).map(header => header.trim());
+    return grid.slice(1).map(cells => {
+        const row = {};
+        headers.forEach((header, column) => {
+            if (header.length > 0)
+                row[header] = cells[column] ?? '';
+        });
+        return row;
+    });
+}

package/dist/platform/errors.js

@@ -1,6 +1,12 @@
 export class PlatformApiError extends Error {
     status;
     code;
+    /**
+     * Toplu satır yazmasında düşen satırın parti içi indeksi (`BulkRowErrorResponse.rowIndex`).
+     * Mesajda da geçer ama metinden ayıklanamaz: parti döngüsü dosya satır numarasını hesaplamak
+     * için sayıya ihtiyaç duyar, çağıran hangi satırı düzelteceğini ancak öyle bilir.
+     */
+    rowIndex;
     constructor(message, status, code) {
         super(message);
         this.status = status;
@@ -45,8 +51,62 @@ function collectValidationMessages(payload) {
  * Sayfa şeması patch'inin üç reddi de "hiçbir op uygulanmadı" anlamına gelir (uygulayıcı önce tüm
  * op'ları bellekte işler, tek hata bile tüm komutu düşürür) — ajanın kısmi uygulama varsayıp
  * planın kalanını göndermesi bu yüzden yanlış olur.
+ *
+ * Aynı duvar 2026-09-08'den beri sayfa/layout KURMA yolunda da koşuyor (P1-2: layout hattı aynı
+ * hatalı prop'ları sessizce kaydediyordu). Orada op listesi yoktur ve `page_schema_validate` de
+ * uygulanmaz — ipucu bu yüzden yola göre ayrışır.
  */
-function pageSchemaHint(code) {
+/**
+ * Merge apply'ın iki 409'u da aynı şeyi söyler: plan artık uygulanabilir değil. Ajan bunu
+ * 'geçici hata, tekrar dene' diye okuyup aynı çağrıyı yollamasın diye yol açıkça yazılır.
+ */
+function mergeHint(path) {
+    if (!/\/merges\//.test(path))
+        return '';
+    return " Üç sebepten biri: çözülmemiş çakışma, ya da plan alındığından beri DALIN veya development’ın değişmesi (MergePlanStaleException) — ikincisinde planın taşıdığı liste eskidir ve uygulansaydı sonradan yapılan iş sessizce düşerdi. merge_get ile planı yeniden okuyun (isStale), bayatsa merge_refresh ile tazeleyin — yeni plan açmanız gerekmez. Aynı merge_apply çağrısını tekrarlamak sonucu değiştirmez.";
+}
+function mergeRevertHint(code) {
+    if (code === 'MergeRevertWindowExpiredException') {
+        return " Geri alma penceresi doldu: pencere kapanınca merge öncesi anlık görüntü de silinir, bu yüzden plan artık geri alınamaz. merge_list status:'applied' ile pencere içindeki bir plan seçin.";
+    }
+    if (code === 'MergePlanNotRevertableException') {
+        return ' Bu plan bir GERİ ALMA planı (kind=revert) ve geri almanın geri alması yoktur. Geri almayı iptal etmek istiyorsanız dalı yeniden merge edin.';
+    }
+    if (code === 'MergePlanNotAppliedException') {
+        return " Plan uygulanmış DEĞİL — durumu mesajda yazıyor (failed / discarded / reverted / planned…). Yalnız 'applied' ve 'applied-with-drift' geri alınabilir; merge_list status:'applied' ile uygun planı seçin. Zaten geri alınmış bir planın durumu 'reverted'dır ve ikinci kez geri alınamaz.";
+    }
+    return '';
+}
+/**
+ * İçe aktarma zinciri dört çağrıdır ve her hata farklı bir adıma geri gönderir: plan süresi
+ * dolduysa analizden, anahtar benzersiz değilse plan gövdesinden, hata oranı yüksekse dosyanın
+ * kendisinden. Kod olmadan mesajlar "422" diye okunur ve ajan aynı çağrıyı tekrarlar.
+ */
+function importHint(code, path) {
+    if (code === 'ImportPlanExpiredException') {
+        return ' Plan bir saat geçerlidir ve süresi doldu (ya da başka bir kullanıcıya ait). import_analyze ile dosyayı yeniden okuyup import_plan ile yeni bir plan üretin — aynı planId bir daha çalışmaz.';
+    }
+    if (code === 'ImportTooManyErrorsException') {
+        return " Satırların yarısından fazlası kuru koşuda düştü. Önce planın `errors` listesine bakın: çoğu zaman tek bir yanlış `locale` ya da yanlış sütun tipi bütün satırları düşürür. Dosya gerçekten böyleyse import_run'ı `force: true` ile çağırın.";
+    }
+    if (code === 'ImportKeyFieldNotUniqueException') {
+        return " Upsert/update anahtarı benzersiz olmalı: alanın kendisi unique/primary key olmalı, ya da tek alanlı bir unique index taşımalı, ya da 'id'/'code' olmalı. entity_get ile alanın `unique` bayrağını doğrulayın.";
+    }
+    if (code === 'ImportRelationMatchFieldNotUniqueException') {
+        return ' Ad → id eşlemesi yalnız hedef tablonun display alanı ya da benzersiz bir alanıyla yapılır; benzersiz olmayan bir alanda aynı ad iki satıra gidebilir ve hangisinin yazılacağı belirsiz olur.';
+    }
+    if (code === 'ImportSheetEmptyException' || code === 'ImportRowLimitExceededException') {
+        return ' `headerRow` doğru mu kontrol edin (0 = başlık yok); satır sınırı aşıldıysa dosyayı sayfalara bölün.';
+    }
+    if (code === 'DataJobNotUndoableException' && path.endsWith('/cancel')) {
+        return ' İş zaten bitmiş (completed / failed / undone / cancelled); iptal edilecek bir şey yok. Tamamlanmış işi geri almak için import_undo.';
+    }
+    if (code === 'DataJobNotUndoableException' && path.endsWith('/undo')) {
+        return ' Yalnız tamamlanmış ve undoAvailableUntil geçmemiş bir içe aktarma geri alınır; mevcut tabloya yalnız ekleme yapan işin penceresi hiç açılmaz. Süren işi durdurmak için import_cancel.';
+    }
+    return '';
+}
+function pageSchemaHint(code, path) {
     if (code === 'PageSchemaVersionConflictException') {
         return ' Sayfa siz okuduktan sonra değişti ve HİÇBİR op uygulanmadı. page_schema_get ile yeniden okuyup planı tazeleyin, yeni `version` değerini `baseVersion` olarak gönderin.';
     }
@@ -54,10 +114,42 @@ function pageSchemaHint(code) {
         return ' Sayfa şeması başka bir aktörün kilidinde (kilit sahibi mesajda; kilit 60 sn sonra kendiliğinden düşer). Bekleyip tekrar deneyin — aynı anda iki yazar olduğunda kaybeden taraf sessizce ezilmesin diye kilit var.';
     }
     if (code === 'PageSchemaValidationException') {
-        return ' Op listesi doğrulama duvarına takıldı ve HİÇBİR op uygulanmadı (hepsi ya da hiçbiri). Alan hatalarını düzeltip tek çağrıda tekrar gönderin; planı önce page_schema_validate ile kuru koşturabilirsiniz.';
+        return path.endsWith('/schema')
+            ? ' Op listesi doğrulama duvarına takıldı ve HİÇBİR op uygulanmadı (hepsi ya da hiçbiri). Alan hatalarını düzeltip tek çağrıda tekrar gönderin; planı önce page_schema_validate ile kuru koşturabilirsiniz.'
+            : ' Gövde doğrulama duvarına takıldı ve HİÇBİR ŞEY KAYDEDİLMEDİ. Yukarıdaki her satır bir düğüm/prop adresi ve kabul edilen değer listesi taşır — prop adlarını component_get ile doğrulayıp gövdeyi tek çağrıda düzeltin.';
     }
     return '';
 }
+/**
+ * Toplu satır yazma tek transaction: platform hangi satırın düştüğünü mesajda söyler
+ * (`Row {n} could not be written: …`), ama "geri kalanı yazıldı mı" sorusunu söylemez. Ajan
+ * kısmi yazma varsayıp yalnız düşen satırı yeniden göndermesin diye all-or-nothing burada yazılı.
+ */
+function bulkRowHint(code) {
+    if (code === 'BulkRowFailedException') {
+        return " Toplu yazma TEK TRANSACTION: bu çağrıdan HİÇBİR satır yazılmadı (yalnız id sekansı ilerledi). Mesajdaki satır numarası 0'dan başlar ve gönderdiğiniz `rows` dizisinin indeksidir. O satırı düzeltip TÜM diziyi yeniden gönderin.";
+    }
+    if (code === 'BulkRowLimitException') {
+        return ' Diziyi 1000 satırlık parçalara bölüp sırayla gönderin; her parça kendi transaction\'ında yazılır.';
+    }
+    return '';
+}
+/**
+ * PATCH uçlarında `baseVersion` zorunlu ve kayıt okumanızdan beri değiştiyse HİÇBİR op uygulanmaz.
+ * Ajanın "tekrar dene" refleksi burada yanlış: aynı ops'u yeni sürümle göndermek başkasının
+ * yazdığını ezer, önce yeniden okunmalı.
+ */
+function versionConflictHint(code, path) {
+    if (code !== 'AggregateVersionConflictException')
+        return '';
+    const readTool = /\/entities(\/|$)/.test(path) ? 'entity_get'
+        : /\/workflows(\/|$)/.test(path) ? 'workflow_get'
+            : /\/flows(\/|$)/.test(path) ? 'flow_get'
+                : /\/layouts(\/|$)/.test(path) ? 'layout_get'
+                    : /\/microservices(\/|$)/.test(path) ? 'microservice_get'
+                        : 'ilgili *_get';
+    return ` Kayıt siz okuduktan sonra değişti ve HİÇBİR op uygulanmadı (mesajdaki beklenen/mevcut sürüm). ${readTool} ile yeniden okuyup patch'i güncel hâle göre kurun, yeni \`version\` değerini \`baseVersion\` olarak gönderin — aynı ops'u eski sürümle tekrar göndermek aradaki değişikliği ezer.`;
+}
 /**
  * Bilinen platform bug'larını ajanın tool yüzeyinden teşhis edebilmesi için desen eşlemesi
  * (klinik turu dersi: teşhis DB'ye/koda inmeden yapılabilmeli — görev G-09).
@@ -65,6 +157,12 @@ function pageSchemaHint(code) {
 function diagnoseKnownFailure(status, message, code, context) {
     if (status !== 500)
         return '';
+    // 2026-09-08'e kadar ExceptionHandler bu istisnayı eşlemiyordu ve slug çakışması 500 dönüyordu
+    // (3. koşu S-1 / P3-7); yeni build 409 verir, gateway de POST'tan önce project_list ile arar
+    // (PRJ-001). Bu dal eski build'e karşı kalır.
+    if (code === 'DatabaseNameAlreadyExistsException' || message.includes('already has this database name')) {
+        return " Sebep: proje slug'ı bu organizasyonda zaten kullanımda (veritabanı adı zeyrek_<org>_<slug> tekildir). Çalışan backend bu durumu 409 yerine 500 ile bildiren eski bir build; başka bir slug seçin ya da project_list ile mevcut projeyi bulun (PRJ-001).";
+    }
     if (context.path.includes('/row') && message.includes('Sequence contains no matching element')) {
         return " Muhtemel sebep: entity bir application'a bağlı değil — entity_patch ile applicationIds ekleyin (PLT-004).";
     }
@@ -72,7 +170,7 @@ function diagnoseKnownFailure(status, message, code, context) {
         return " Bilinen sınır (K-005/P-01): m2m, çoklu dosya ya da çoklu enum alanı entity_create gövdesindeyken platform junction KAYDINI açar ama fiziksel tabloyu kurmaz. Alanı entity_patch ile yeniden ekleyin; gateway'in entity_create'i bunu artık kendisi iki aşamaya bölüyor, elle kurulmuş eski kayıtlar etkilenir.";
     }
     if (message.includes('cannot be tracked') || message.includes('already being tracked')) {
-        return " Bilinen sınır (K-006/P-02): operation:'get' tipli microservice'te PUT, izlenen Application grafiği yüzünden 500 veriyor. Geçici yol: microservice_delete + microservice_create ile yeniden kurun (gövdeyi önce microservice_get ile alın).";
+        return " Bilinen sınır (K-006/P-02): operation:'get' tipli microservice'te PUT, izlenen Application grafiği yüzünden 500 veriyordu. Regresyon 2026-08-16'da düzeltildi ve 2026-09-01'de canlı doğrulandı (İK koşusu M-9) — bu hatayı hâlâ görüyorsanız çalışan sürüm düzeltmeden eskidir. O sürümde geçici yol: microservice_delete + microservice_create ile yeniden kurun (gövdeyi önce microservice_get ile alın).";
     }
     if (code === 'RowValidationFailed' || message.includes('RowValidationFailed')) {
         return ' Gövdedeki alanlar doğru görünüyorsa muhtemel sebep istemcinin body alanını düşürmesidir (K-002): microservice_execute/debug çağrısında body bir NESNE ya da nesne DİZİSİ olmalı; boş gövdeyle gönderildiyse istemci şemayı desteklemiyor olabilir.';
@@ -91,7 +189,7 @@ export function mapPlatformError(status, payload, context) {
         if (validationMessages.length > 0) {
             return new PlatformApiError(`Doğrulama hatası (${location}): ${validationMessages.join(' ; ')}. Gövde şeması için ilgili ngapps://schemas kaynağına ya da mevcut bir kaydın *_get çıktısına bakın.`, status, code);
         }
-        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}`, status, code);
+        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}${mergeRevertHint(code)}${importHint(code, context.path)}`, status, code);
     }
     if (status === 401) {
         const hint = context.authMode === 'local'
@@ -109,7 +207,7 @@ export function mapPlatformError(status, payload, context) {
         if (context.method !== 'GET' && /\/flows(\/|$)/.test(context.path)) {
             return new PlatformApiError(`Adımda referans verilen kayıt çözümlenemedi (${location}). Bu uçta 404 akışın kendisini DEĞİL bir adım argümanını kastediyor: flow-trigger adımının args'ında ne flowId ne triggerElementId var (ya da triggerElementId sayfadaki hiçbir elementId ile eşleşmiyor), setter adımının iteratees[].element'i bulunamıyor, ya da bir adım silinmiş bir komponente bakıyor. Adım argümanlarını page_schema_get'teki elementId'lerle karşılaştırın; flow-trigger'ın iki geçerli şekli için platform_guide('page') Kural 1c.`, status, code);
         }
-        return new PlatformApiError(`Kayıt bulunamadı (${location}).${environmentHint} id/slug değerini ilgili *_list tool'uyla doğrulayın.`, status, code);
+        return new PlatformApiError(`Kayıt bulunamadı (${location}).${environmentHint} id/slug değerini ilgili *_list tool'uyla doğrulayın.${importHint(code, context.path)}`, status, code);
     }
     if (status === 409 || status === 422) {
         const projectConflictHint = status === 409 && context.method === 'POST' && /\/projects\/?$/.test(context.path)
@@ -117,7 +215,10 @@ export function mapPlatformError(status, payload, context) {
             : '';
         const validationMessages = collectValidationMessages(body);
         const detail = validationMessages.length > 0 ? ` → ${validationMessages.join(' ; ')}` : '';
-        return new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code)}`, status, code);
+        const rejected = new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code, context.path)}${bulkRowHint(code)}${importHint(code, context.path)}${versionConflictHint(code, context.path)}${mergeHint(context.path)}`, status, code);
+        if (typeof body.rowIndex === 'number')
+            rejected.rowIndex = body.rowIndex;
+        return rejected;
     }
     const fallbackValidationMessages = collectValidationMessages(body);
     const fallbackDetail = fallbackValidationMessages.length > 0 ? ` → ${fallbackValidationMessages.join(' ; ')}` : '';