@appaflytech/zeyrek-ai-mcp 0.0.20 → 0.0.22

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/component.md

@@ -34,6 +34,14 @@ component_get   → tek tipin TAM sözleşmesi, üç katman birleşik:
 - **Boyut:** `blocks[].size` katalogdaki `maxSize`'ı aşamaz; yükseklikte
   `appearance.heightType: 'auto'` tercih edilir. Katalog varsayılanı bazı tiplerde kendi
   sınırını aşar — körü körüne kopyalama, gateway kırpar ve bildirir.
+- **Çocuk tarafı flex sözleşmesi — `mode: 'flex'` (2026-09-18):** flex kapta kalan alanı alan
+  öğe komponent değil onu taşıyan düğüm sarmalayıcısıdır ve sarmalayıcının `flex`i ortak
+  katmanda yazılır. `mode` prop'u `'flex'` olan bir çocuk (bugün yalnız `spacer`) kabın ANA
+  ekseninde kalanı ister: sütunda kalan yükseklik, satırda kalan genişlik, sıfır taban (wrap
+  açıkken satırdan düşmez). `appearance.widthType`/`heightType`'tan bağımsızdır ve ana
+  eksende onları yener; kabın ölçüsü o eksende belirli olmalıdır (auto/hug sütunda kalan
+  alan yoktur). Komponentin kendi `style`'ından istenemez — `style`'a `flex` yazma tablosuna
+  bkz. aşağıda.
 
 ### Arayüz metni ve biçimler uygulama dilini izler
 
@@ -105,7 +113,7 @@ Her şema düğümünde iki sözlük vardır; ikisi de ortak render katmanında
 
 | `states` | Anlamı |
 |---|---|
-| `isDroppable` | İçine komponent alır (container/form/repeater true). **Değer kataloğun kararıdır** (`component_list` `droppable` sütunu): Studio kanvası bırakma hedefini bu alandan çözer, bu yüzden gateway yazdığı düğümlerde alanı katalogdan doldurur ve `gatewayNormalized` ile bildirir (PAGE-034). `false` yazılmış bir kabın içine kanvasta bırakma yapılamaz — bilerek kapatmak için `resize_component`/`set_states` |
+| `isDroppable` | İçine komponent alır (container/form/repeater true). **Değer kataloğun kararıdır** (`component_list` `droppable` sütunu): Studio kanvası bırakma hedefini bu alandan çözer, bu yüzden gateway yazdığı düğümlerde alanı katalogdan doldurur ve `gatewayNormalized` ile bildirir (PAGE-036). `false` yazılmış bir kabın içine kanvasta bırakma yapılamaz — bilerek kapatmak için `resize_component`/`set_states` |
 | `isScrollable` | İçeriği kendi alanında kaydırır (sabit yükseklikte `overflow-y: auto`) |
 | `isWrapper` | Sayfanın/layout'un/widget'ın ANA kabı — salt düzen elemanı: `height:100%` + **`min-height:80vh`**, kap başlığı ÇİZİLMEZ. **Yalnız sayfa boyu kaplaması gereken tek kap için kullan:** iç içe kutuya verirsen 720px'lik pencerede o kutu 36px içerikle bile 576px çizilir (ölçüldü, `platform_guide('page')` Kural 1f). Çerçeve/başlık gizlemek için wrapper değil `style` (`border:'none'`) kullan. Kurulmuş bir düğümün bayrağını `resize_component` micro-op'unun `states` alanı değiştirir — düğümü yeniden kurmak gerekmez |
 | `isSticky` | Kaydırmada yerinde kalır (header/sidebar; z-index'i otomatik) |

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

package/dist/resources/guides/getting-started.md

@@ -153,6 +153,21 @@ koda baktığını gizlemek yerine raporlamak.
   (GW-005). Bir argüman kabul edildiyse gateway onu okuyor demektir.
 
 
+## Aynı çağrıyı iki kez yapmak kopya açmaz: `ifExists`
+
+Platform aynı adla ikinci kaydı hata vermeden `"<ad> (1)"` olarak açar. `flow_create`,
+`microservice_create`, `workflow_create` ve `page_create` bu yüzden yazmadan önce aynı ad ya da
+slug'ı (harf duyarsız) arar:
+
+| `ifExists` | Kayıt zaten varsa |
+|---|---|
+| `error` (varsayılan) | Yazmaz; hata mevcut id'yi ve varsa `(n)` sayaçlı kopyaları söyler |
+| `update` | Mevcut kaydı günceller, yanıtta `outcome: 'updated'`. `page_create`'te yalnız verilen alanlar yazılır, şema korunur. `workflow_create`'te mevcut kaydın `type`'ı farklıysa (middleware ↔ automation) yazmaz — tür değişirdi |
+| `duplicate` | Platform davranışı: ikinci kayıt açılır. Platformun eklediği sayaç (ad `' (1)'`, slug `-1`; akışta ikisi de `' (1)'`) kayıp değildir, yanıtta `renamedByPlatform`'dadır |
+
+Betiği yeniden koşturacaksan `ifExists: 'update'` ver; kopyaları elle ayıklayan yardımcı kod
+yazma. Mevcut liste okunamazsa çağrı yazmadan düşer — tekrar dene.
+
 ## Yazdıktan sonra `silentlyDropped` alanına bak
 
 Platformun bir alanı **hatasız yutması** bu depodaki en pahalı hata sınıfı: çağrı 200 döner,
@@ -169,6 +184,26 @@ Gateway yazma tool'larında gönderdiğin gövdeyi kaydedilenle karşılaştır
 ]
 ```
 
+Yazma yanıtında bu liste ve `gatewayNormalized` **kısaltılmış** gelir: aynı yolun düşmeleri tek
+satırda sayıyla toplanır (`selectFields[*].path · kaydedilmedi: 25 öğe — ör. …`). Kayıp sayısı
+`droppedCount`'tadır; sayım 1000 farkta durursa `droppedCountCapped: true` gelir ve sayı "en az"
+demektir. Liste dışı bilgiler (20 satır kesmesi, sıra tabanlı karşılaştırma uyarısı)
+`silentlyDroppedNotes`'tadır ve sayıya girmez. Tam liste gerekiyorsa yazmayı tekrarlama — kaydı `*_get` ile oku,
+sonraki yazmalarda `diagnostics: 'full'` ver. `microservice_*` ve `workflow_*` create/update
+yanıtında `data` yalnız kimlik alanlarını taşır; gövdenin tamamı için `view: 'full'`.
+
+**Betikten toplu yazarken yanıtı olduğu gibi basma.** Otuz yazmanın tam yanıtı çıktı sınırını aşar
+ve dosyaya düşer. Her çağrı için tek satır bas; ayrıntıyı yalnız sorunlu çağrıda bas:
+
+```js
+const r = JSON.parse(result.content[0].text)
+if (result.isError || r.droppedCount > 0) console.log(JSON.stringify({ slug, error: result.isError ? r : undefined, droppedCount: r.droppedCount, silentlyDropped: r.silentlyDropped }))
+else console.log(JSON.stringify({ slug, id: r.data?.id, outcome: r.outcome }))
+```
+
+Yalnız `isError`'a bakma: platform alanı hatasız yutunca çağrı başarılıdır ve kayıp yalnız
+`droppedCount`'ta görünür.
+
 Diff dizi öğelerini indeksle değil KİMLİKLE eşler (`stepId`, `elementId`, `name`, `id`), çünkü
 platform diziyi kendi sırasında geri döndürür. Diff üretilemeyen tek durum, yanıtın kayıt değil
 kabul gövdesi olmasıdır; o zaman alan hiç görünmez ve doğrulamayı `*_get` ile kendin yaparsın.

package/dist/resources/guides/mobile.md

@@ -36,7 +36,8 @@ Mobil uygulamanın bileşen kataloğu ayrıdır (backend satırları `(slug, typ
 şema web sınıfını genişlettiği için prop'ların anlamı oradadır), `mobileKnowledge` (bu bileşenin
 mobil farkları: düşen prop, değişen etkileşim, mobile özgü prop notları) ve `mobileNotes` (bütün
 mobil bileşenlere geçen notlar). Web'de karşılığı olmayan bileşende (`app-bar`, `safe-area`,
-`scroll-view`, `choice-chips`, `tooltip`) bilgi yalnız `mobileKnowledge`'tadır. Olay yükleri
+`scroll-view`, `choice-chips`, `tooltip`, `markdown`, `calendar`, `stack`, `list-item`, `fab`, `timer`,
+`audio`, `lottie`, `webview`) bilgi yalnız `mobileKnowledge`'tadır. Olay yükleri
 (`events[].payload`) önce mobile özgü sözleşmeden okunur (`app-bar.clickAction`, `repeater.swipe`,
 `choice-chips.change`…), yoksa web'inkinden.
 
@@ -54,6 +55,30 @@ mobil bileşenlere geçen notlar). Web'de karşılığı olmayan bileşende (`ap
   uzun içerik için içine `scroll-view`). En-boy oranı yeni
   prop DEĞİLDİR: boyut panelinin `appearance.aspectRatio`'su mobilde kaplara da uygulanır
   (§Yerleşim).
+  İkinci adımda dört bileşen: `markdown` (Markdown çizer, HTML çalıştırmaz; bağlantı `linkClick { href }`)
+  ve `calendar` (satır içi takvim, tek gün ya da aralık; prop adları ve `change` biçimi web
+  `datepicker`ınki) mobile özgüdür; `otpinput` ve `qrcode` web ikizleridir, kuralları web modülünden.
+  Üçüncü adımda dört bileşen daha: `stack` (katmanlar: ilk çocuk taban, üsttekiler yığının 9 noktalı
+  `alignment`ıyla hizalanır — çocukta hiza alanı YOKTUR), `list-item` (satır: baş · başlık · alt başlık ·
+  son; `click`), `fab` (yüzen düğme: sayfanın neresinde olursa olsun ekranın alt köşesinde durur, içerikle
+  kaymaz; `click`, iç rol `__press`) mobile özgüdür; `carousel` web ikizidir (`activeIndex`,
+  `slideChange`) ve mobilde bırakılabilir — çocukları sayfalardır.
+  Dördüncü adım Katalog B'yi kapattı: `timer` (mobile özgü; başlat/duraklat `isRunning`, sıfırlama `value`
+  yazmak; `tick { value }` her saniye, `finish`), `rating`, `multi-select` (değer `{ label, value }`
+  dizisi) ve `toast` web ikizleridir. `toast`ın bildirimi sayfadan bağımsız yaşar (`redirect`ten sonra da
+  görünür), açık modal ya da çekmecenin de üstünde çizilir; akışın tipli `alert` uyarıları cihazda da
+  toast'tur.
+- **Katalog C** (cihaz modüllü bileşenler) medyayla başladı: `video` web ikizidir (cihazda `expo-video`,
+  kanvas ve önizlemede HTML5 `<video>`; `click` yalnız `controls: false` iken), `audio` (oynat/duraklat,
+  ilerleme izi; iç roller `__toggle`, `__track`) ve `lottie` (Lottie JSON ya da `.lottie`) mobile özgüdür.
+  İkisinde çalma `isPlaying` prop'udur: akış `true`/`false` yazar, bileşen `play`/`pause`/`ended` ya da
+  `finish` olayında `{ isPlaying }` yayar ve prop'u gerçeğe döndürür.
+  İkinci adım: `signature` web ikizidir (her vuruşta `change { value }` PNG data URL; vuruş sürerken sayfa
+  kaymaz; iOS'ta itilmiş sayfada sağa vuruş sayfayı kapatır, ARC-116) ve `webview` mobile özgüdür (web
+  `iframe`inin karşılığı): `src` ya da `html`; yüklemeden sonra başka belgeye giden gezinme varsayılan olarak
+  engellenir ve `navigate { url }` yayar, adres yalnız kullanıcının dokunduğu bağlantıda sistem tarayıcısında
+  açılır (`allowNavigation` görünümde açar); sayfa akışa `window.ReactNativeWebView.postMessage(metin)` →
+  `message { data }` ile yazar, yüklenemeyen sayfa `error` yayar.
 - Web'e özgü bileşenlerin mobil karşılığı:
 
 | Web | Mobilde |
@@ -62,7 +87,7 @@ mobil bileşenlere geçen notlar). Web'de karşılığı olmayan bileşende (`ap
 | `popover` | `modal` widget'ı |
 | `pagination` | `repeater` + "daha fazla yükle" düğmesi |
 | `breadcrumb` | yığın gezinmesi (app-bar geri düğmesi) |
-| `iframe` | `button` + `redirect` (`targetBlank`) ile tarayıcıda aç |
+| `iframe` | `webview` (`src` ya da `html`) |
 | `theme-toggle` | cihaz teması |
 
 **Harici bileşen mobilde yoktur** (`MOB-006`): protokol v1 tarayıcı `.mjs` paketidir;
@@ -167,6 +192,30 @@ etiketi ailesini `typographyStyle`'dan alır, alan etiketleri platform yazı tip
   (sekmeler), `ngapps://examples/mobile-app-shell-drawer` (çekmece); üç sayfalık liste → detay → form akışı:
   `ngapps://examples/mobile-list-detail-form`.
 
+## Çok dil
+
+Mobil uygulama web ile **aynı sözlüğü ve aynı motoru** kullanır (plans/mobil-coklu-dil, 2026-09-25):
+`project_update(languages, defaultLanguage)` → prop'u bağla (`set_prop_type(target, prop, 'translation', ref)`)
+→ `translation_update`. Kurulum ve fallback zinciri `platform_guide('translation')`.
+
+- **Dil değiştirici:** `language-selector` mobil katalogdadır (`component_get` → `mobileKnowledge`):
+  `dropdown`un tam ekran `Modal` listesi, tetikleyici `role="combobox"`, seçenekler dilin yerel adıyla
+  (`tr` → Türkçe). Seçim `machine.setLanguage` ile bütün prop'ları yerinde çözer ve cihazda uygulama
+  çapında yayılır: öteki sekmelerin ekranları ve sekme etiketleri de değişir, makine yeniden kurulmaz.
+- **Cihazda boot sırası:** uygulama içi seçim → cihazda kayıtlı seçim (`zeyrek:<app>:lang`) → cihaz dili
+  → projenin varsayılanı. `?lang` CİHAZDA YOKTUR; `/preview`'da vardır, bu yüzden `page_screenshot(language:)`
+  mobil sayfada da çalışır — kanıt için sayfaya seçici koymak gerekmez.
+- **Sekme etiketi:** `properties.mobile.tabs[].label` `t:<anahtar>` ile çevrilir (doğrulama mesajıyla aynı
+  önek); `mobile_app_create` `tabs[].label` de kabul eder. Sayfa adı fallback'i düz kalır.
+- **Çerçeve:** cihazda `alert`/`confirm` düğmeleri (`Tamam`/`Evet`/`Hayır` ↔ `OK`/`Yes`/`No`) uygulama dilini
+  izler; mesaj gövdesi akışın kendi metnidir.
+- **Doğrulama:** `page_screenshot({ language: 'en' })` ikinci dilin karesi;
+  `page_screenshot({ actions: [{ select: '<seçici elementId>', value: 'en' }] })` seçiciyi sürer
+  (`optionsSeen` proje dili sayısıdır); seçici sonrası sekme çubuğunun `t:` etiketleri de aynı karede
+  çevrilir (ölçüldü 2026-09-25: `Ana/Liste`).
+- **Bilinen fark:** mobilde istemci tarafı şema doğrulaması yoktur, `t:` doğrulama mesajı akışta
+  (`Loc()` / `t()`) çözülür.
+
 ## Akış adımları
 
 Motorun kendi adımları (`setter`, `condition`, `microservice`, `code`, `function`, `flow-trigger`,