@appaflytech/zeyrek-ai-mcp 0.0.4 → 0.0.6

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/errors.js

@@ -45,8 +45,12 @@ 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) {
+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 +58,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 +101,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 +114,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.';
@@ -117,7 +159,7 @@ 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);
+        return new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code, context.path)}${bulkRowHint(code)}${versionConflictHint(code, context.path)}`, status, code);
     }
     const fallbackValidationMessages = collectValidationMessages(body);
     const fallbackDetail = fallbackValidationMessages.length > 0 ? ` → ${fallbackValidationMessages.join(' ; ')}` : '';

package/dist/platform/http.js

@@ -5,6 +5,17 @@ import { TokenProvider } from './token.js';
 import { randomUUID } from 'node:crypto';
 import { request } from 'undici';
 export const requestAuthStorage = new AsyncLocalStorage();
+const hiddenResponseHeaders = new Set(['set-cookie', 'authorization', 'proxy-authorization']);
+/**
+ * Sayfalı tablo akışları `Total-Count` header'ına bağlı ama execute ailesi yalnız gövdeyi
+ * döndürüyordu; sözleşme hiçbir tool'dan doğrulanamıyordu (İK koşusu M-8). Gizli header'lar
+ * her koşulda elenir.
+ */
+export function responseHeadersForTool(raw) {
+    return Object.fromEntries(Object.entries(raw)
+        .map(([name, value]) => [name.toLowerCase(), Array.isArray(value) ? value.join(', ') : value])
+        .filter((entry) => typeof entry[1] === 'string' && !hiddenResponseHeaders.has(entry[0])));
+}
 function buildMultipart(parts, boundary) {
     const chunks = [];
     for (const part of parts) {
@@ -70,6 +81,18 @@ export class Platform {
         });
         return outcome.body;
     }
+    /**
+     * `tenant` gibi davranır (4xx/5xx atar) ama yanıt başlıklarını da verir. `tenantRaw` bu iş için
+     * kullanılamaz: o hata durumunda atmaz, yani satır yazma yolunda 400'ü başarı gibi döndürürdü.
+     * Satır araçları başlığa bakmak zorunda — `X-Unmapped-Members` platformun `localizations`
+     * alanını tanımadığını söyleyen tek işaret (sözleşme D6, gateway eski platformda companion'a düşer).
+     */
+    async tenantWithHeaders(method, project, path, options = {}) {
+        return this.send('tenant', method, `/${this.resolveProject(project)}${path}`, {
+            ...options,
+            environment: this.resolveEnvironment(options.environment)
+        });
+    }
     async tenantRaw(method, project, path, options = {}) {
         return this.send('tenant', method, `/${this.resolveProject(project)}${path}`, {
             ...options,
@@ -95,12 +118,16 @@ export class Platform {
         const url = new URL(`${baseUrl}${path}`);
         appendQuery(url, options.query);
         const callerHeaders = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+        const authorization = callerHeaders.authorization ?? (options.anonymous ? undefined : await this.authorizationHeader());
         const headers = {
             host: `${this.config.organization}.${this.config.hostSuffix}`,
             accept: 'application/json',
-            ...(callerHeaders.authorization || options.anonymous ? {} : { authorization: await this.authorizationHeader() }),
+            ...(authorization === undefined ? {} : { authorization }),
             ...(options.environment ? { 'x-environment': options.environment } : {}),
-            ...callerHeaders
+            ...callerHeaders,
+            ...(options.mirrorAuthorizationCookie && authorization !== undefined && callerHeaders.cookie === undefined
+                ? { cookie: `NG_AccessToken=${authorization.replace(/^Bearer /, '')}` }
+                : {})
         };
         let body;
         if (options.multipart) {
@@ -127,6 +154,7 @@ export class Platform {
         let statusCode;
         let payload;
         let responseBytes = 0;
+        let responseHeaders = {};
         try {
             const response = await request(url, {
                 method: method,
@@ -135,6 +163,7 @@ export class Platform {
                 signal: AbortSignal.timeout(this.config.requestTimeoutMs)
             });
             statusCode = response.statusCode;
+            responseHeaders = responseHeadersForTool(response.headers);
             if (options.expectBinary && statusCode < 400) {
                 const bytes = Buffer.from(await response.body.arrayBuffer());
                 responseBytes = bytes.byteLength;
@@ -164,9 +193,9 @@ export class Platform {
             return this.send(api, method, path, options, raw, true);
         }
         if (raw)
-            return { httpStatus: statusCode, body: payload ?? null };
+            return { httpStatus: statusCode, body: payload ?? null, headers: responseHeaders };
         if (statusCode >= 400)
             throw mapPlatformError(statusCode, payload, context);
-        return { httpStatus: statusCode, body: payload ?? { success: true } };
+        return { httpStatus: statusCode, body: payload ?? { success: true }, headers: responseHeaders };
     }
 }

package/dist/platform/patch.js

@@ -0,0 +1,27 @@
+export function patchResult(response, fallback) {
+    const envelope = response && typeof response === 'object'
+        ? (response.data ?? response)
+        : {};
+    const written = envelope.data && typeof envelope.data === 'object'
+        ? envelope.data
+        : fallback;
+    return {
+        // Sayı olarak gelen bir newVersion JSON.parse sırasında ZATEN yuvarlanmıştır
+        // (6.4e16 > MAX_SAFE_INTEGER): geri gönderilirse her patch 409 verir, boş bırakmak dürüst.
+        newVersion: typeof envelope.newVersion === 'string' ? envelope.newVersion : '',
+        applied: typeof envelope.applied === 'number' ? envelope.applied : 0,
+        data: written
+    };
+}
+/**
+ * `baseVersion` PATCH gövdesinde ZORUNLU. Okunan kayıtta `version` yoksa platform 422 döndürür;
+ * ajanın hatayı gateway'e değil eksik alana bağlayabilmesi için burada erken ve açık patlıyoruz.
+ */
+export function baseVersionOf(definition, readTool) {
+    const version = definition.version;
+    if (typeof version === 'string' && version.length > 0)
+        return version;
+    if (typeof version === 'number')
+        return String(version);
+    throw new Error(`Okunan kayıtta 'version' alanı yok; PATCH 'baseVersion' olmadan gönderilemez. ${readTool} çıktısında 'version' görünmüyorsa platform sürümü bu ucu desteklemiyordur.`);
+}