@appaflytech/zeyrek-ai-mcp 0.0.16 → 0.0.18

package/README.md

@@ -31,10 +31,10 @@ ekleyin:
       "command": "npx",
       "args": ["-y", "@appaflytech/zeyrek-ai-mcp@latest", "--stdio"],
       "env": {
-        "ORG_API_BASE_URL": "https://new-zeyrek.glomil.com/api/org",
-        "TENANT_API_BASE_URL": "https://new-zeyrek.glomil.com/api",
-        "ORGANIZATION": "new-zeyrek",
-        "HOST_SUFFIX": "glomil.com",
+        "ORG_API_BASE_URL": "http://localhost:17000",
+        "TENANT_API_BASE_URL": "http://localhost:15000",
+        "ORGANIZATION": "zeyrek-test",
+        "HOST_SUFFIX": "zeyrek.local",
         "DEFAULT_ENVIRONMENT": "development",
         "USERNAME": "admin@zeyrek.com",
         "PASSWORD": "parolanız",
@@ -49,10 +49,10 @@ Claude Code'da komutla eklemek isterseniz:
 
 ```bash
 claude mcp add zeyrek-ai \
-  -e ORG_API_BASE_URL=https://new-zeyrek.glomil.com/api/org \
-  -e TENANT_API_BASE_URL=https://new-zeyrek.glomil.com/api \
+  -e ORG_API_BASE_URL=http://localhost:17000 \
+  -e TENANT_API_BASE_URL=http://localhost:15000 \
   -e ORGANIZATION=new-zeyrek \
-  -e HOST_SUFFIX=glomil.com \
+  -e HOST_SUFFIX=zeyrek.local \
   -e DEFAULT_ENVIRONMENT=development \
   -e USERNAME=admin@zeyrek.com \
   -e PASSWORD='parolanız' \
@@ -87,9 +87,9 @@ hiç yazmayıp çalışma dizininize `PASSWORD=...` içeren bir `.env` koyun.
 
 | Değişken | Örnek | Not |
 |---|---|---|
-| `ORG_API_BASE_URL` | `https://new-zeyrek.glomil.com/api/org` | Organization.API kökü |
-| `TENANT_API_BASE_URL` | `https://new-zeyrek.glomil.com/api` | Tenant.API kökü |
-| `ORGANIZATION` | `new-zeyrek` | Org subdomain'i; istekler `Host: {ORGANIZATION}.{HOST_SUFFIX}` ile gider |
+| `ORG_API_BASE_URL` | `http://localhost:17000` | Organization.API kökü |
+| `TENANT_API_BASE_URL` | `http://localhost:15000` | Tenant.API kökü |
+| `ORGANIZATION` | `zeyrek-test` | Org subdomain'i; istekler `Host: {ORGANIZATION}.{HOST_SUFFIX}` ile gider |
 | `DEFAULT_ENVIRONMENT` | `development` | Gömülü varsayılanı **yoktur**; boşsa sunucu açılmaz |
 | `USERNAME` + `PASSWORD` | | `AUTH_MODE=local` için; `/connect/token` ile takas edilir |
 | `TOKEN` | | `USERNAME`/`PASSWORD` yerine hazır Bearer JWT verilebilir |
@@ -113,8 +113,9 @@ hiç yazmayıp çalışma dizininize `PASSWORD=...` içeren bir `.env` koyun.
 | `STUDIO_BASE_URL` | — | Yalnız `page_screenshot`: Studio arayüzünün kök adresi |
 | `SCREENSHOT_BROWSER_PATH` | — | `page_screenshot` için sistemdeki Chromium ikilisi (verilmezse playwright-core'un indirdiği tarayıcı) |
 
-Tam liste ve yorumlu şablon: pakete dahil edilen `.env.example` (lokal profil) ve
-`.env.production.example` (uzak profil).
+Tam liste ve yorumlu şablon: pakete dahil edilen `.env.example` (lokal profil). Uzak
+kurulumlara dağıtım insanın ve CI'ın işidir; AI lokal dışına çıkmaz
+([../docs/ortam.md](../docs/ortam.md)).
 
 ### Bilinmesi gereken üç davranış
 
@@ -250,7 +251,7 @@ ve `src/` yoktur.
 ```bash
 cd zeyrek-mcp
 npm install
-cp .env.example ../.env      # uzak profil için: cp .env.production.example ../.env
+cp .env.example ../.env      # hedef her zaman lokal stack
 npm run dev                  # HTTP · npm run start:stdio ile stdio
 ```
 

package/dist/knowledge/rules.js

@@ -422,6 +422,8 @@ export function rawQueryParameterNames(rawQuery) {
 }
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 const functionsGuide = 'ngapps://guides/functions';
+/** FN-006: bu kadar dolu satırdan uzun gövde yorumsuz kalmaz; tek satırlık `return` yorum istemez. */
+const FUNCTION_COMMENT_MIN_LINES = 5;
 export const policyRules = [
     {
         id: 'MS-001',
@@ -2032,6 +2034,25 @@ export const policyRules = [
             return [];
         }
     },
+    {
+        id: 'FN-006',
+        module: 'function',
+        appliesTo: ['create', 'update'],
+        sourceRef: "Kullanıcı isteği 2026-09-18: ajan fonksiyon yazarken gövdeye ne yaptığını söyleyen yorum koyar; Studio editörü yorumu yeşil italik çizer. Gövde kendi satırına sarılır (function-source.ts, GlobalFunction.cs AppendLine), '//' kapanış parantezini yutmaz",
+        check: definition => {
+            const name = String(definition.name ?? '?');
+            const body = typeof definition.body === 'string' ? definition.body : '';
+            const lineCount = body.split('\n').filter(line => line.trim() !== '').length;
+            if (lineCount < FUNCTION_COMMENT_MIN_LINES || /(^|\s)\/\/|\/\*/m.test(body))
+                return [];
+            return [{
+                    ruleId: 'FN-006',
+                    severity: 'warn',
+                    message: `'${name}' gövdesi ${lineCount} satır ama hiç yorum yok. Başa ne yaptığını, parametreleri ve dönüşü söyleyen kısa bir '//' yorumu, açık olmayan adımların üstüne de birer satır yorum ekleyin; kodu tekrar eden yorum yazmayın.`,
+                    guide: functionsGuide
+                }];
+        }
+    },
     {
         id: 'FLOW-024',
         module: 'flow',

package/dist/platform/diagnostics.js

@@ -0,0 +1,85 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { z } from 'zod';
+const activeMode = new AsyncLocalStorage();
+const MAX_NOTES = 8;
+const MAX_NOTE_CHARS = 240;
+const MAX_DROPS = 5;
+export const diagnosticsParam = z.enum(['compact', 'full']).optional().describe("Yanıttaki gatewayNormalized / silentlyDropped listelerinin boyu. compact (varsayılan): aynı not tekilleşir, uzun not kısalır (en fazla 8); aynı yolun düşmeleri tek satırda sayıyla toplanır (en fazla 5 grup); droppedCount her zaman tam sayıdır. full: listelerin tamamı.");
+export function runWithDiagnostics(mode, run) {
+    return activeMode.run(mode, run);
+}
+/**
+ * Tanılama listeleri her yazma çağrısında yanıta girer ve aynı gerekçe cümlesi çağrı başına tekrar
+ * eder. Kırpma yalnız GÖRÜNÜMÜ küçültür: `silentlyDropped` "kaydedildi mi" sorusunun tek kanıtı olduğu
+ * için liste hiçbir zaman sessizce boşalmaz — toplam sayı ve kalan satır sayısı yanıtta kalır, tam
+ * liste gateway günlüğünde (`sessiz düşme` / `düzeltme` adımları) durur.
+ *
+ * Kip bağlamı olmayan çağrı (okuma ve silme tool'ları, doğrudan `toolResult` kullanan testler) tam
+ * listeyi görür; kısaltma yalnız `diagnostics` parametresini taşıyan yazma tool'larında devreye girer.
+ */
+export function compactDiagnostics(payload) {
+    if (activeMode.getStore() !== 'compact')
+        return payload;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    const record = payload;
+    const notes = Array.isArray(record.gatewayNormalized) ? record.gatewayNormalized.map(String) : undefined;
+    const drops = Array.isArray(record.silentlyDropped) ? record.silentlyDropped.map(String) : undefined;
+    if (notes === undefined && drops === undefined)
+        return payload;
+    const hidden = [];
+    const result = { ...record };
+    if (notes !== undefined) {
+        const counts = new Map();
+        for (const note of notes)
+            counts.set(note, (counts.get(note) ?? 0) + 1);
+        const unique = [...counts.entries()].map(([note, count]) => {
+            const shortened = note.length > MAX_NOTE_CHARS ? `${note.slice(0, MAX_NOTE_CHARS - 1)}…` : note;
+            return count > 1 ? `${shortened} (×${count})` : shortened;
+        });
+        const shortenedCount = notes.filter(note => note.length > MAX_NOTE_CHARS).length;
+        const kept = unique.slice(0, MAX_NOTES);
+        result.gatewayNormalized = unique.length > MAX_NOTES ? [...kept, `… ${unique.length - MAX_NOTES} not daha`] : kept;
+        if (unique.length > MAX_NOTES)
+            hidden.push(`${unique.length - MAX_NOTES} not`);
+        if (shortenedCount > 0)
+            hidden.push(`${shortenedCount} notun gerekçesi kısaltıldı`);
+    }
+    if (drops !== undefined) {
+        const droppedCount = typeof record.droppedCount === 'number' ? record.droppedCount : drops.length;
+        const grouped = groupDrops(drops, record.droppedCountCapped === true || droppedCount > drops.length);
+        const kept = grouped.slice(0, MAX_DROPS);
+        if (grouped.length !== drops.length)
+            hidden.push('benzer düşme satırları toplandı');
+        if (grouped.length > MAX_DROPS)
+            hidden.push(`${grouped.length - MAX_DROPS} düşme grubu`);
+        result.silentlyDropped = grouped.length > MAX_DROPS ? [...kept, `… ${grouped.length - MAX_DROPS} grup daha`] : kept;
+        result.droppedCount = droppedCount;
+    }
+    if (hidden.length === 0)
+        return result;
+    return { ...result, diagnosticsNote: "Kısaltıldı; yazmayı tekrarlamayın. Tam liste: sonraki çağrıda diagnostics:'full'." };
+}
+/**
+ * Aynı yolun farklı öğelerindeki düşmeler (`selectFields[fieldId=a].path`, `selectFields[fieldId=b].path`, …)
+ * aynı sorunu tekrar eder. Seçici ve indeks `[*]`'a indirgenir, grup tek satırda sayıyla ve bir örnekle
+ * döner. Listedeki HER satır kayıptır (sıra uyarısı ve kesme bilgisi `silentlyDroppedNotes`'tadır ve
+ * buraya hiç girmez); micro-op satırları (`add_component 'x': …`) da kendi yolu altında gruplanır.
+ * Liste kesildiyse ya da sayım tavana vurduysa grup sayısı "en az" diye yazılır.
+ */
+function groupDrops(drops, partial) {
+    const groups = new Map();
+    for (const line of drops) {
+        const separator = line.indexOf(': ');
+        const path = separator === -1 ? line : line.slice(0, separator);
+        const outcome = line.includes(' ↔ ') ? (line.endsWith('kaydedilen yok') ? ' · kaydedilmedi' : ' · farklı kaydedildi') : '';
+        const pattern = `${path.replace(/\[[^\]]*\]/g, '[*]')}${outcome}`;
+        groups.set(pattern, [...(groups.get(pattern) ?? []), line]);
+    }
+    return [...groups.entries()].map(([pattern, lines]) => {
+        if (lines.length === 1)
+            return lines[0];
+        const example = lines[0].length > 160 ? `${lines[0].slice(0, 159)}…` : lines[0];
+        return `${pattern}: ${partial ? 'en az ' : ''}${lines.length} öğe — ör. ${example}`;
+    });
+}

package/dist/platform/ifExists.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { PlatformApiError } from './errors.js';
+/**
+ * `ifExists` parametresi. Aynı ad ya da slug'la ikinci kaydın `"<ad> (1)"` olarak açılması platformun
+ * ürün kararıdır (akış, sayfa, workflow ve microservice servisleri aynı sayaç kuralını uygular) ve
+ * değişmez. MCP ajanı çağrıyı tekrar edebildiği için varsayılan "yazma, mevcut id'yi söyle"dir.
+ */
+export function ifExistsParam(noun, updateNote) {
+    return z.enum(['error', 'update', 'duplicate']).default('error').describe(`Aynı ad ya da slug'da (büyük/küçük harf duyarsız) ${noun} varsa ne olacağı. 'error' (varsayılan): yazmaz, mevcut kaydın id'sini döner. 'update': ${updateNote}. 'duplicate': platformun ürün davranışı — ikinci kayıt açılır, platform ada/slug'a ' (1)' sayacını ekler (Studio'daki 'New … (1)' ile aynı kural).`);
+}
+const upper = (value) => String(value ?? '').toUpperCase();
+const isPresent = (value) => value !== undefined && value !== null && String(value) !== '';
+/**
+ * Var-mı kapısı (FLOW-026 ve kardeşleri). Aday araması platformda harfe duyarlıdır; gateway bilinçli
+ * olarak harf duyarsız karşılaştırır. Var-mı okuması başarısız olursa çağrı düşer — okuyamadığı
+ * listeyi boş sayan kontrol tam da zaman aşımında kopya üretirdi.
+ */
+export async function existingMatch(options) {
+    const { code, noun, where, name, slug, id, idParam, ifExists } = options;
+    const slugCounter = (options.slugSuffix ?? 'dash') === 'dash' ? "'-1'" : "' (1)'";
+    if (ifExists === 'duplicate')
+        return undefined;
+    if (!name && !slug)
+        return undefined;
+    let records;
+    try {
+        records = await options.list();
+    }
+    catch (error) {
+        throw new PlatformApiError(`${code}: mevcut ${noun} kayıtları okunamadı, ${noun} YAZILMADI (${error instanceof Error ? error.message : String(error)}). Liste okunmadan yazmak aynı adla ikinci kayıt açabilir; ${options.listTool} ile tekrar deneyin ya da bilerek ikinci kayıt istiyorsanız ifExists:'duplicate' verin.`);
+    }
+    const matches = records.filter(record => (name !== undefined && name !== '' && upper(record.name) === upper(name)) ||
+        (slug !== undefined && slug !== '' && upper(record.slug) === upper(slug)));
+    const [match] = matches;
+    if (match === undefined)
+        return undefined;
+    const describe = (record) => `${String(record.id)} ('${String(record.name)}', slug '${String(record.slug)}')`;
+    const copyPattern = name
+        ? new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} \\(\\d+\\)$`, 'i')
+        : undefined;
+    const copies = copyPattern ? records.filter(record => copyPattern.test(String(record.name ?? ''))) : [];
+    const copyNote = copies.length > 0
+        ? ` ${where[0].toUpperCase()}${where.slice(1)} bu adın sayaçlı eşleri de var: ${copies.map(describe).join(' · ')} — ${options.copyCheck}.`
+        : '';
+    if (ifExists === 'error') {
+        throw new PlatformApiError(`${code}: ${where} aynı ad ya da slug'da ${noun} zaten var: ${matches.map(describe).join(' · ')}. İstek gönderilmedi — gönderilseydi platform ürün kuralı gereği ikinci bir ${noun} açardı (çakışan ada ' (1)', slug'a ${slugCounter} sayacı eklenerek; yalnız harf farkı varsa sayaçsız). Mevcut kaydı güncellemek için aynı çağrıyı ifExists:'update' ile tekrarlayın; bilerek ikinci kayıt istiyorsanız ifExists:'duplicate'.${copyNote}`, 409);
+    }
+    if (matches.length > 1) {
+        throw new PlatformApiError(`${code}: ad ve slug farklı kayıtlara çıkıyor (${matches.map(describe).join(' · ')}); hangisinin güncelleneceği belirsiz, istek gönderilmedi. ${options.updateTool} kullanın.${copyNote}`, 409);
+    }
+    // Eşleşme tipten bağımsızdır (platform sayacı tipe bakmaz), ama 'update' tipi farklı kaydın üstüne
+    // yazarsa kaydın türü değişir: backend PUT'ta tipi de yazar ve middleware automation'a dönüşür (R-1).
+    const kind = options.kind;
+    if (kind !== undefined && isPresent(kind.value) && isPresent(match[kind.key]) && upper(match[kind.key]) !== upper(kind.value)) {
+        throw new PlatformApiError(`${code}: aynı ad ya da slug'daki mevcut kayıt ${describe(match)} ${kind.key}='${String(match[kind.key])}'; gönderilen gövde ${kind.key}='${String(kind.value)}'. ifExists:'update' kaydın türünü değiştirirdi — istek gönderilmedi. Farklı ad/slug seçin ya da bilerek ikinci kayıt istiyorsanız ifExists:'duplicate'.${copyNote}`, 409);
+    }
+    if (id !== undefined && id.toLowerCase() !== String(match.id).toLowerCase()) {
+        throw new PlatformApiError(`${code}: verilen ${idParam} (${id}) aynı adlı mevcut kayıtla (${describe(match)}) çelişiyor; istek gönderilmedi. Mevcut kaydı güncellemek için ${idParam}'yi vermeyin ya da ${String(match.id)} verin.`, 409);
+    }
+    return match;
+}
+const LIST_PAGE_LENGTH = 200;
+const LIST_PAGE_LIMIT = 50;
+/**
+ * Uygulama düzeyindeki liste uçlarını (`GET /microservices|workflows|pages/{app}`) sonuna kadar okur.
+ * Arama terimi kullanılmaz: platformun `searchTerm`'ü slug'ı kapsamayabilir ve eksik liste kopya açar.
+ *
+ * Platform sayfaları kararlı sırada vermiyor (R-3): bir kayıt iki sayfada gelip başka biri hiç
+ * gelmeyebilir. İlk yanıttaki `meta.totalData` okunan TEKİL id sayısıyla tutmazsa liste tutarsızdır ve
+ * hata atılır — çağıran yazmaz. `meta` taşımayan eski yanıtta denetim yapılamaz.
+ */
+export async function listAll(platform, project, environment, path) {
+    const records = [];
+    let expected;
+    for (let pageIndex = 0; pageIndex < LIST_PAGE_LIMIT; pageIndex++) {
+        const payload = await platform.tenant('GET', project, path, { environment, query: { pageIndex, pageLength: LIST_PAGE_LENGTH } });
+        if (!Array.isArray(payload?.data))
+            throw new PlatformApiError('liste yanıtında data dizisi yok');
+        if (pageIndex === 0 && typeof payload.meta?.totalData === 'number')
+            expected = payload.meta.totalData;
+        records.push(...payload.data);
+        if (payload.data.length < LIST_PAGE_LENGTH || (expected !== undefined && records.length >= expected)) {
+            const unique = new Set(records.map(record => String(record.id).toLowerCase())).size;
+            if (expected !== undefined && unique !== expected) {
+                throw new PlatformApiError(`liste tutarsız okundu: platform ${expected} kayıt dedi, sayfalardan ${unique} tekil kayıt geldi (${records.length - unique} tekrar) — sayfa sırası kararlı değil`);
+            }
+            return records;
+        }
+    }
+    throw new PlatformApiError(`liste ${LIST_PAGE_LENGTH * LIST_PAGE_LIMIT} kaydı aştı, tamamı okunamadı`);
+}
+/**
+ * `ifExists:'duplicate'` yazmasında platform ada ' (n)', slug'a '-n' (akışta ' (n)') ekler. Bu fark kayıp
+ * değildir (Gözlem 1): kalıba uyan alan karşılaştırmadan ÖNCE gönderilen gövdede kaydedilen değerle
+ * değiştirilir ve `renamedByPlatform`'a gider. Kalıba uymayan fark gövdede kalır, yani yine kayıptır.
+ */
+export function platformRename(sent, saved, slugSuffix) {
+    const record = saved && typeof saved === 'object' && !Array.isArray(saved) ? saved : {};
+    const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const renamed = {};
+    const adjusted = { ...sent };
+    for (const key of ['name', 'slug']) {
+        const given = sent[key];
+        const stored = record[key];
+        if (typeof given !== 'string' || typeof stored !== 'string' || given === stored)
+            continue;
+        const pattern = key === 'slug' && slugSuffix === 'dash'
+            ? new RegExp(`^${escape(given)}-\\d+$`)
+            : new RegExp(`^${escape(given)} \\(\\d+\\)$`);
+        if (!pattern.test(stored))
+            continue;
+        renamed[key] = stored;
+        adjusted[key] = stored;
+    }
+    return Object.keys(renamed).length === 0 ? { sent: adjusted } : { sent: adjusted, renamed };
+}
+export function withRename(payload, renamed) {
+    if (renamed === undefined || !payload || typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    return { ...payload, renamedByPlatform: renamed };
+}
+/**
+ * Yazma yanıtına `outcome` ekler; ajan kaydın yeni mi açıldığını yoksa güncellendiğini mi tek alandan okur.
+ */
+export function withOutcome(payload, existing) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    return { ...payload, outcome: existing === undefined ? 'created' : 'updated' };
+}

package/dist/platform/responses.js

@@ -1,3 +1,4 @@
+import { compactDiagnostics } from './diagnostics.js';
 import { logError, logStep } from '../observability/trace.js';
 import { PlatformApiError, describeErrorBody } from './errors.js';
 import { PolicyBlockError } from '../knowledge/policy.js';
@@ -139,7 +140,7 @@ function asStructured(payload) {
     return { data: payload };
 }
 export function toolResult(payload, config, expectFailure) {
-    const pruned = prune(payload);
+    const pruned = prune(compactDiagnostics(payload));
     const { payload: safe, masked, tokenRefs } = maskSecrets(pruned);
     const runtimeErrors = runtimeErrorSummary(safe);
     if (runtimeErrors.length > 0) {

package/dist/platform/strictArguments.js

@@ -1,4 +1,15 @@
 import { z } from 'zod';
+import { diagnosticsParam, runWithDiagnostics } from './diagnostics.js';
+/**
+ * `writes`/`updates` açıklamalı ama KAYIT yazmayan tool'lar: çalıştırma, önizleme, dışa aktarma, indirme,
+ * bağlantı testi. Yanıtlarında yazma tanılaması (silentlyDropped) yoktur; parametre yalnız tool listesini
+ * büyütür. Yeni böyle bir tool eklenirse buraya yazılır — `test/diagnostics.test.ts` listeyi kilitler.
+ */
+const NON_WRITING_TOOLS = new Set([
+    'microservice_execute', 'microservice_preview', 'microservice_debug', 'query_preview', 'workflow_preview',
+    'automation_preview', 'automation_trigger', 'row_export', 'file_download', 'microfunction_invoke',
+    'microfunction_runtime_test_connection'
+]);
 function isRawShape(value) {
     if (!value || typeof value !== 'object' || '_def' in value)
         return false;
@@ -19,14 +30,23 @@ export function rejectUnknownArguments(server) {
     server.registerTool = ((name, config, callback) => {
         if (!isRawShape(config.inputSchema))
             return registerTool(name, config, callback);
-        const shape = config.inputSchema;
+        // Yazma tool'ları tanılama kipini alır; parametre handler'a ULAŞMAZ (gövdeyi `...rest` ile
+        // platforma geçiren tool'larda sızardı), yalnız toolResult'ın okuduğu bağlama konur.
+        const writesDiagnostics = config.annotations?.readOnlyHint === false && config.annotations.destructiveHint !== true && !NON_WRITING_TOOLS.has(name);
+        const shape = writesDiagnostics ? { ...config.inputSchema, diagnostics: diagnosticsParam } : config.inputSchema;
+        const run = writesDiagnostics
+            ? ((args, extra) => {
+                const { diagnostics, ...rest } = args ?? {};
+                return runWithDiagnostics(diagnostics === 'full' ? 'full' : 'compact', () => callback(rest, extra));
+            })
+            : callback;
         const accepted = Object.keys(shape).join(', ');
         const inputSchema = z.object(shape, {
             errorMap: (issue, context) => issue.code === 'unrecognized_keys'
                 ? { message: `${name} şu üst düzey argümanları tanımıyor: ${issue.keys.map(key => `'${key}'`).join(', ')}. Tanınmayan alan sessizce yok sayılmaz — çağrı hiç gönderilmedi. Bu tool'un okuduğu alanlar: ${accepted}.` }
                 : { message: context.defaultError }
         }).strict();
-        return registerTool(name, { ...config, inputSchema }, callback);
+        return registerTool(name, { ...config, inputSchema }, run);
     });
     return server;
 }

package/dist/platform/writeDiff.js

@@ -1,15 +1,17 @@
 import { PROP_VALUE_TYPES } from '../knowledge/normalize.js';
 import { logStep } from '../observability/trace.js';
 const maxDrops = 20;
+const maxCollected = 1000;
 const maxDepth = 12;
 const missing = Symbol('missing');
 /**
  * Platformun kendi doldurduğu alanlar. Yalnız gönderilen tarafta da varsalar (patch yolunda gövde
  * okunup geri yazılır) fark üretirlerdi ve bu fark hep gürültüdür: `audit.updatedAt` her yazmada
- * değişir. 09-05 koşusunda `microservice_patch` yanıtındaki iki satırdan biri buydu.
+ * değişir. 09-05 koşusunda `microservice_patch` yanıtındaki iki satırdan biri buydu. `version` iyimser
+ * eşzamanlılık sayacıdır: okunan belge geri yazılınca platform onu artırır, fark her zaman gürültüdür.
  */
 const serverManagedKeys = new Set([
-    'audit', 'createdAt', 'updatedAt', 'createdUserId', 'createdUserName', 'updatedUserId', 'updatedUserName'
+    'audit', 'createdAt', 'updatedAt', 'createdUserId', 'createdUserName', 'updatedUserId', 'updatedUserName', 'version'
 ]);
 /**
  * Platformun KENDİ ürettiği kimlik. Gönderilen id kaydedilenden farklıysa bu bir kayıp değildir:
@@ -50,6 +52,29 @@ export const unstoredKeys = new Set(['fieldSlug']);
 const canonicalValues = {
     type: [['string', 'text']]
 };
+export function emptyWriteDiff() {
+    return { dropped: [], normalized: [], droppedCount: 0, droppedCountCapped: false, notes: [] };
+}
+function addDrop(sink, line) {
+    if (sink.droppedCount >= maxCollected) {
+        sink.droppedCountCapped = true;
+        return;
+    }
+    sink.dropped.push(line);
+    sink.droppedCount++;
+}
+/** Listeyi `maxDrops` satırda keser; sayı ve tavan bilgisi notlara yazılır. */
+function finishReport(sink) {
+    if (sink.dropped.length > maxDrops) {
+        const total = sink.droppedCountCapped ? `en az ${sink.droppedCount}` : `toplam ${sink.droppedCount}`;
+        sink.dropped = sink.dropped.slice(0, maxDrops);
+        sink.notes.push(`ilk ${maxDrops} fark listelendi, ${total} — gövdeyi *_get ile okuyup karşılaştırın.`);
+    }
+    else if (sink.droppedCountCapped) {
+        sink.notes.push(`sayım en az ${sink.droppedCount} farkta durdu.`);
+    }
+    return sink;
+}
 /**
  * Yolun son alan adı; `tags[0]` ya da `fields[fieldId=x]` gibi indeks/anahtar ekini atar.
  */
@@ -81,11 +106,11 @@ function lookup(saved, key) {
     return Object.hasOwn(record, key) ? record[key] : missing;
 }
 function compare(sent, saved, path, sink, depth) {
-    if (sink.dropped.length >= maxDrops || depth > maxDepth)
+    if (sink.droppedCountCapped || depth > maxDepth)
         return;
     if (Array.isArray(sent)) {
         if (saved === missing) {
-            sink.dropped.push(`${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
+            addDrop(sink, `${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
             return;
         }
         const key = Array.isArray(saved) ? identityKeyFor(sent) : undefined;
@@ -103,18 +128,18 @@ function compare(sent, saved, path, sink, depth) {
             }
             return;
         }
-        const before = sink.dropped.length;
+        const before = sink.droppedCount;
         sent.forEach((entry, index) => compare(entry, lookup(saved, index), `${path}[${index}]`, sink, depth + 1));
         // Sıra tabanlı karşılaştırmada "değişmiş" görünen öğe aslında yer değiştirmiş olabilir. Tek
         // elemanlı dizide sıra farkı imkânsız olduğu için not düşülmez (2026-09-06 · S-1).
-        if (Array.isArray(saved) && sent.length > 1 && saved.length > 1 && sink.dropped.length > before) {
-            sink.dropped.splice(before, 0, `${path}: (sıra tabanlı karşılaştırma — anahtar yok) aşağıdaki farklar platform diziyi başka sırada sakladıysa yanıltıcıdır`);
+        if (Array.isArray(saved) && sent.length > 1 && saved.length > 1 && sink.droppedCount > before) {
+            sink.notes.push(`${path}: (sıra tabanlı karşılaştırma — anahtar yok) aşağıdaki farklar platform diziyi başka sırada sakladıysa yanıltıcıdır`);
         }
         return;
     }
     if (sent && typeof sent === 'object') {
         if (saved === missing) {
-            sink.dropped.push(`${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
+            addDrop(sink, `${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
             return;
         }
         for (const [key, entry] of Object.entries(sent)) {
@@ -130,7 +155,7 @@ function compare(sent, saved, path, sink, depth) {
     if (unstoredKeys.has(field) && (saved === missing || saved === null))
         return;
     if (saved === missing) {
-        sink.dropped.push(`${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
+        addDrop(sink, `${path}: gönderilen ${render(sent)} ↔ kaydedilen yok`);
         return;
     }
     if (sent === saved)
@@ -141,7 +166,7 @@ function compare(sent, saved, path, sink, depth) {
         sink.normalized.push(`${path}: gönderilen ${render(sent)} platformun kanonik adıyla ${render(saved)} olarak saklandı — eşdeğer, kayıp değil`);
         return;
     }
-    sink.dropped.push(`${path}: gönderilen ${render(sent)} ↔ kaydedilen ${render(saved)}`);
+    addDrop(sink, `${path}: gönderilen ${render(sent)} ↔ kaydedilen ${render(saved)}`);
 }
 /**
  * Sol taraf platforma GİDEN gövdedir (gateway normalizasyonu uygulandıktan sonrası), sağ taraf
@@ -152,8 +177,8 @@ function compare(sent, saved, path, sink, depth) {
  * İki liste döner: `dropped` gerçekten kaybolan alanlar, `normalized` platformun kanonik adıyla
  * sakladığı eşdeğerler. İkincisi `gatewayNormalized`a gider, uyarıya değil.
  */
-export function writeDiff(sent, saved, aliases = {}) {
-    const sink = { dropped: [], normalized: [] };
+export function writeDiff(sent, saved, aliases = {}, finish = true) {
+    const sink = emptyWriteDiff();
     if (!sent || typeof sent !== 'object')
         return sink;
     const wrapper = saved && typeof saved === 'object' && !Array.isArray(saved)
@@ -171,19 +196,16 @@ export function writeDiff(sent, saved, aliases = {}) {
     if (keys.length > 0 && shared.length === 0)
         return sink;
     compare(comparable, root, '', sink, 0);
-    if (sink.dropped.length >= maxDrops) {
-        sink.dropped.push(`… ilk ${maxDrops} fark listelendi, daha fazla fark var — gövdeyi *_get ile okuyup karşılaştırın.`);
-    }
-    return sink;
+    return finish ? finishReport(sink) : sink;
 }
 export function silentlyDropped(sent, saved, aliases = {}) {
     return writeDiff(sent, saved, aliases).dropped;
 }
 export function withWriteDiff(payload, diff) {
-    const drops = Array.isArray(diff) ? diff : diff.dropped;
-    const normalized = Array.isArray(diff) ? [] : diff.normalized;
+    const drops = diff.dropped;
+    const normalized = diff.normalized ?? [];
     if (drops.length > 0) {
-        logStep('sessiz düşme ⚠', `${drops.length} alan gönderildi ama kayda geçmedi — platform hata vermeden yok saydı, yanıta silentlyDropped olarak eklenir`, drops);
+        logStep('sessiz düşme ⚠', `${diff.droppedCount}${diff.droppedCountCapped ? '+' : ''} alan gönderildi ama kayda geçmedi — platform hata vermeden yok saydı, yanıta silentlyDropped olarak eklenir`, [...drops, ...diff.notes]);
     }
     if (normalized.length > 0) {
         logStep('düzeltme', `platform ${normalized.length} alanı kanonik adıyla sakladı — eşdeğer, yanıta gatewayNormalized olarak eklenir`, normalized);
@@ -195,7 +217,9 @@ export function withWriteDiff(payload, diff) {
     const existing = payload.gatewayNormalized;
     return {
         ...payload,
-        ...(drops.length > 0 ? { silentlyDropped: drops } : {}),
+        ...(drops.length > 0 ? { silentlyDropped: drops, droppedCount: diff.droppedCount } : {}),
+        ...(drops.length > 0 && diff.droppedCountCapped ? { droppedCountCapped: true } : {}),
+        ...(drops.length > 0 && diff.notes.length > 0 ? { silentlyDroppedNotes: diff.notes } : {}),
         ...(normalized.length > 0
             ? { gatewayNormalized: [...(Array.isArray(existing) ? existing : []), ...normalized] }
             : {})
@@ -247,9 +271,9 @@ function findByElementId(nodes, elementId) {
  * yanıt yalnız `appliedPatch` olduğu için karşılaştırma yamadan SONRA okunan şemaya dayanır.
  */
 export function schemaOpDrops(schema, ops) {
+    const drops = { dropped: [], droppedCount: 0, droppedCountCapped: false, notes: [] };
     if (!Array.isArray(ops))
-        return [];
-    const drops = [];
+        return drops;
     for (const op of ops) {
         if (op.op === 'add_component') {
             const component = (op.component ?? {});
@@ -258,12 +282,10 @@ export function schemaOpDrops(schema, ops) {
             if (!elementId)
                 continue;
             if (!saved) {
-                drops.push(`add_component '${elementId}': komponent şemada bulunamadı — yama 200 döndü ama düğüm kaydedilmemiş.`);
+                addDrop(drops, `add_component '${elementId}': komponent şemada bulunamadı — yama 200 döndü ama düğüm kaydedilmemiş.`);
                 continue;
             }
-            for (const entry of silentlyDropped(unwrapProps(component), unwrapProps(saved))) {
-                drops.push(`add_component '${elementId}' → ${entry}`);
-            }
+            mergeNested(drops, writeDiff(unwrapProps(component), unwrapProps(saved), {}, false), `add_component '${elementId}' → `);
             continue;
         }
         if (op.op === 'replace_prop' && typeof op.target === 'string' && typeof op.prop === 'string') {
@@ -272,13 +294,18 @@ export function schemaOpDrops(schema, ops) {
                 continue;
             const props = (saved.props ?? {});
             if (!Object.hasOwn(props, op.prop)) {
-                drops.push(`replace_prop '${op.target}.${op.prop}': prop şemada yok — değer kaydedilmemiş.`);
+                addDrop(drops, `replace_prop '${op.target}.${op.prop}': prop şemada yok — değer kaydedilmemiş.`);
                 continue;
             }
-            for (const entry of silentlyDropped({ [op.prop]: unwrapProps(op.value) }, { [op.prop]: unwrapProps(props[op.prop]) })) {
-                drops.push(`replace_prop '${op.target}' → ${entry}`);
-            }
+            mergeNested(drops, writeDiff({ [op.prop]: unwrapProps(op.value) }, { [op.prop]: unwrapProps(props[op.prop]) }, {}, false), `replace_prop '${op.target}' → `);
         }
     }
-    return drops.slice(0, maxDrops);
+    return finishReport(drops);
+}
+/** İç karşılaştırmanın satırlarını, sayısını ve notlarını dış rapora önekle taşır; kesme en dışta yapılır. */
+function mergeNested(target, nested, prefix) {
+    for (const line of nested.dropped)
+        addDrop(target, `${prefix}${line}`);
+    target.droppedCountCapped = target.droppedCountCapped || nested.droppedCountCapped;
+    target.notes.push(...nested.notes.map(note => `${prefix}${note}`));
 }

package/dist/platform/writeView.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const recordWriteViewParam = z.enum(['outline', 'full']).optional().describe("Yanıttaki kaydın biçimi. outline (VARSAYILAN): data yalnız kimlik alanlarını taşır (id, name, slug, version ve türüne göre url/httpMethod/source/type) — gönderdiğiniz gövdenin yankısı bağlama tekrar girmez; 'kaydedildi mi' kanıtı silentlyDropped/droppedCount'tadır. full: platformun döndürdüğü gövde aynen gelir.");
+/**
+ * Create/update yanıtı platformun kaydettiği tanımın TAMAMINI döner; ajan aynı turda o gövdeyi
+ * kendisi göndermiştir. Kırpma yalnız bağımsız doğrulama yolu olan yerde yapılır: bu tool'larda
+ * `writeDiff` tam yanıt üzerinden ÖNCE hesaplanır, projeksiyon ondan sonra uygulanır.
+ */
+export function outlineWrite(payload, view, keys) {
+    if (view === 'full' || !payload || typeof payload !== 'object' || Array.isArray(payload))
+        return payload;
+    const record = payload;
+    const data = record.data;
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return payload;
+    const source = data;
+    return { ...record, data: Object.fromEntries(['id', 'name', 'slug', 'version', ...keys].filter(key => Object.hasOwn(source, key)).map(key => [key, source[key]])) };
+}

package/dist/resources/guides/functions.md

@@ -105,14 +105,16 @@ globalThis["toplamHesapla"] = function (fiyat, adet) {       // studio: Function
   "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
   "parameters": [ { "name": "fiyat", "type": "number", "required": true },
                   { "name": "adet",  "type": "number", "defaultValue": 1 } ],
-  "body": "return fiyat * adet;" }
+  "body": "// fiyat × adet; adet verilmezse 1 sayılır
+return fiyat * adet;" }
 
 // tarayıcı
 { "source": "studio", "applicationId": "<app id>", "scope": "application",
   "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
   "isAsync": false,
   "parameters": [ … aynı liste … ],
-  "body": "return fiyat * adet;" }
+  "body": "// fiyat × adet; adet verilmezse 1 sayılır
+return fiyat * adet;" }
 ```
 
 Gövde **düz deyimlerdir** — `function (…) { }` sarmalı ya da arrow yazılmaz; `return` serbesttir,
@@ -128,6 +130,33 @@ sözdizimi hatası `422 GlobalFunctionBodyInvalid` ile ve ayrıştırıcı mesaj
 | FN-004 | `source:'workflow'` + `isAsync:true` | **block** — motor senkron, 422 `GlobalFunctionAsyncNotAllowed` |
 | FN-004 | studio: `isAsync:true` ama `await` yok · `isAsync:false` ama `await` var | warn — ilki gereksiz async (inline `[object Promise]`), ikincisi **derlenmeyen gövde**: fonksiyon atlanır |
 | FN-005 | Kaynak/kapsam tutarsız: workflow'a `applicationId`/`scope`/`pageId`; studio'ya `applicationId` ya da `scope` yok; `page` kapsamına `pageId` yok; `application` kapsamına `pageId` var | **block** — platform 422 |
+| FN-006 | 5+ dolu satırlı gövdede hiç yorum yok | warn — baş yorumu ekleyin (§Gövdede yorum) |
+
+### Gövdede yorum (FN-006)
+
+Gövdeyi okuyan bir sonraki kişi (insan ya da ajan) fonksiyonu Studio'nun Functions drawer'ında
+açar; yorumlar orada **yeşil italik** çizilir ve koddan ayrı okunur. Bu yüzden her gövde yorum taşır:
+
+- **Baş yorumu** — ilk satırlar: fonksiyon ne yapar, parametrelerin anlamı ve birimi, ne döner.
+  Tek satırlık `return` gövdesinde bile bir satır yeterlidir.
+- **Adım yorumu** — yalnız açık olmayan adımların üstüne: iş kuralı, sınır durumu, neden bu yol.
+  Kodu tekrar eden yorum yazılmaz (`// toplamı döndür` + `return toplam` gürültüdür).
+- `//` kullanın; `/* */` çok satırlı açıklama için serbest. Gövde kendi satırına sarıldığı için
+  son satırdaki `//` kapanış parantezini yutmaz.
+
+```js
+// KDV dahil sepet toplamı. satirlar: [{ fiyat, adet }], oran: 0.2 gibi ondalık.
+// Boş sepette 0 döner; tutar kuruş hassasiyetinde yuvarlanır.
+const araToplam = satirlar.reduce((toplam, satir) => toplam + satir.fiyat * satir.adet, 0)
+
+// İndirim KDV'den ÖNCE uygulanır (muhasebe kuralı)
+const indirimli = araToplam * (1 - (indirim ?? 0))
+
+return Math.round(indirimli * (1 + oran) * 100) / 100
+```
+
+5 ya da daha fazla dolu satırlı ve hiç yorumu olmayan gövde **FN-006** uyarısı alır; kayıt yine
+yapılır.
 
 Studio kaydı sonrası bağlı sayfaların çalışma paketi `Pages.Updated` ile yeniden kurulur (B-11):
 `/dev` yolu yeni gövdeyi hemen, `/view` yolu önbellek tazelenince gösterir. Workflow kaydı önbellek