@appaflytech/zeyrek-ai-mcp 0.0.6 → 0.0.7

package/dist/knowledge/rules.js

@@ -1,5 +1,8 @@
+import { applyPolicyMode } from './policy.js';
+import { PlatformApiError } from '../platform/errors.js';
 import { reservedTenantTables } from './reservedTables.js';
 import { headersAccessNames, isHeadersAccessGuarded } from './flowGuards.js';
+import { callsItself, functionCallRefs, isValidParameterName, mentionsAwait, nameProblem, sourceOf, callPrefix } from './functionGuards.js';
 import { backendPolicyRules } from './backendConstraints.js';
 const terminalStepTypes = new Set(['response', 'convert', 'revert']);
 const DESCRIPTION_EXEMPT_STEPS = new Set(['start']);
@@ -14,6 +17,7 @@ const stepKindMatrix = {
     workflow: ['workflow', 'automation', 'middleware'],
     email: ['workflow', 'automation', 'middleware'],
     'file-upload': ['workflow', 'automation', 'middleware'],
+    microfunction: ['workflow', 'automation', 'middleware'],
     variable: ['middleware'],
     'set-user': ['middleware'],
     setcookie: ['middleware'],
@@ -97,8 +101,19 @@ const flowBranchNames = {
     start: ['always'],
     microservice: ['always', 'success'],
     confirm: ['yes', 'no', 'always'],
+    function: ['always'],
     end: []
 };
+/**
+ * Gateway'in tanıdığı sayfa akışı adım tipleri — frontend `FlowTaskType` enum'unun aynası
+ * (`ng-apps-flow/src/flow-execution.enums.ts`). `flowBranchNames[type] ?? ['always']` varsayımı
+ * her tipi kabul ettiği için sürüklenme ancak bu AÇIK listeyle ölçülür
+ * (`test/flow-step-parity.test.ts`). Frontend'e yeni tip girince buraya da yazılır.
+ */
+export const knownFlowStepTypes = new Set([
+    'start', 'end', 'query', 'setter', 'download', 'condition', 'redirect', 'setcookie', 'alert', 'confirm',
+    'microservice', 'validation', 'flow-trigger', 'storage', 'navigate', 'code', 'function'
+]);
 const flowFreeBranchTypes = new Set(['condition']);
 /** `condition.types.ts` ConditionArgumentRuleType — motorun tanıdığı üçlü. */
 const conditionRuleTypes = new Set(['if', 'else-if', 'else']);
@@ -205,6 +220,21 @@ function flowCodeExpressions(step) {
     }
     return expressions;
 }
+/**
+ * Kod ifadesi taşıyan her alan: `flowCodeExpressions` + condition kurallarının `expression`ı.
+ * FLOW-025 (`Functions.<ad>` çağrı taraması) bunu tarar; FLOW-011'in taradığı küme değişmez.
+ */
+export function flowExpressionSites(step) {
+    const shaped = step;
+    const sites = flowCodeExpressions(shaped);
+    if (shaped.type === 'condition') {
+        for (const rule of asArray((shaped.args ?? {}).rules).filter((rule) => Boolean(rule) && typeof rule === 'object')) {
+            if (typeof rule.expression === 'string' && rule.expression.trim() !== '')
+                sites.push({ expression: rule.expression, origin: `rules['${String(rule.id ?? '?')}'].expression` });
+        }
+    }
+    return sites;
+}
 const writeOperations = new Set(['create', 'update', 'delete', 'upsert']);
 /** Built-in `roles` entity'si ve slug alanı — SeedData her projeye SABİT id'lerle açar (EntityConstants.cs). */
 const rolesEntityId = '01917ede-88a2-72ea-8397-2619e5d5dca0';
@@ -224,7 +254,7 @@ function writesRolesWithoutSlug(entityId, parameters) {
 }
 const rolesSlugMessage = "Built-in 'roles' entity'sine slug YAZMADAN rol satırı ÜRETİLİYOR (operation create/upsert). Insert 200 döner, satır role_list'te görünür ve page.roleIds ile bağlanır — ama yetkilendirme SLUG karşılaştırır: platformun get-user sorgusu roles+user_roles join'inden slug dizisi üretir ve Authorized(user.roles) o rol için hiçbir zaman tutmaz. fields'a slug'ı ekleyin ('super-admin' slug'ını vermeyin — platform süper yöneticiyi o slug ile arar). Upsert'te slug'ı İFADEYLE üretmeyin: UPDATE yolunda ifade yeniden değerlendirilir ve var olan rolün slug'ı sessizce değişir (MS-016) — üretilen slug'ı yalnız create ucunda yazın. Rolü kullanıcıya bağlamak ayrı bir user_roles satırıdır.";
 const contractKeys = ['returnDtoId', 'parameterDtoId', 'returnBehavior', 'parameterBehavior'];
-const filterOperators = new Set(['eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'contains', 'icontains', 'in', 'notin', 'startswith', 'endswith', 'istartswith', 'iendswith']);
+const filterOperators = new Set(['eq', 'neq', 'lt', 'lte', 'gt', 'gte', 'contains', 'icontains', 'in', 'notin', 'startswith', 'endswith', 'istartswith', 'iendswith', 'isnull', 'isnotnull']);
 function flattenFilterTree(filters) {
     return filters
         .filter((filter) => Boolean(filter) && typeof filter === 'object')
@@ -316,6 +346,8 @@ function unreadSelectFields(step, steps) {
         .map(field => String(field.fieldSlug ?? field.slug ?? ''))
         .filter(slug => slug.length > 0 && !new RegExp(`\\b${escapeForPattern(slug)}\\b`).test(usage));
 }
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const functionsGuide = 'ngapps://guides/functions';
 export const policyRules = [
     {
         id: 'MS-001',
@@ -583,6 +615,38 @@ export const policyRules = [
             });
         }
     },
+    {
+        id: 'WF-MF-001',
+        module: 'workflow',
+        appliesTo: ['create', 'update', 'preview'],
+        sourceRef: "MicrofunctionStep.cs: rule.MicrofunctionId ile kayıt yüklenir, Status != Published ise FailedOutput(MicrofunctionNotPublishedException) — adım hata dalına düşer, akış 200 dönse bile iş yapılmaz. Ölçüldü 2026-09-10 (B4 doğrulaması: taslak fonksiyona bağlı uç 500 MicrofunctionNotPublishedException)",
+        check: definition => {
+            const body = workflowBody(definition);
+            return workflowSteps(body)
+                .filter(step => step.type === 'microfunction')
+                .flatMap((step) => {
+                const rule = (step.rule ?? {});
+                const microfunctionId = rule.microfunctionId;
+                if (!hasText(microfunctionId)) {
+                    return [{
+                            ruleId: 'WF-MF-001',
+                            severity: 'block',
+                            message: `'${stepLabel(step)}' microfunction adımında rule.microfunctionId yok — adım hangi fonksiyonu koşturacağını bilmez. microfunction_list(status: 'published') ile id seçin; argümanlar rule.expression'a yazılır (fonksiyonun parameterDto'su varsa o şemaya göre).`,
+                            guide: 'ngapps://guides/microfunction'
+                        }];
+                }
+                if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(microfunctionId))) {
+                    return [{
+                            ruleId: 'WF-MF-001',
+                            severity: 'block',
+                            message: `'${stepLabel(step)}' adımının rule.microfunctionId'si GUID değil: '${String(microfunctionId)}'. Platform alanı Guid'e çeviremediği için 400 döner.`,
+                            guide: 'ngapps://guides/microfunction'
+                        }];
+                }
+                return [];
+            });
+        }
+    },
     {
         id: 'WF-006',
         module: 'workflow',
@@ -1704,6 +1768,203 @@ export const policyRules = [
                 }];
         })
     },
+    {
+        id: 'FN-001',
+        module: 'function',
+        appliesTo: ['create', 'update'],
+        sourceRef: "GlobalFunctionRules.cs IsValidName(name, source)/IsValidParameterName → 422 GlobalFunctionNameInvalid; function-source.ts isValidName — geçersiz ad iki dünyada da fonksiyonu ATLATIR. Kaynağa özel ayrılmış ad: studio 'Functions' (K1), workflow WorkflowReservedNames (motor globalleri)",
+        check: definition => {
+            const name = String(definition.name ?? '');
+            const source = sourceOf(definition);
+            const findings = [];
+            const problem = nameProblem(definition.name, source);
+            if (problem !== undefined) {
+                findings.push({
+                    ruleId: 'FN-001',
+                    severity: 'block',
+                    message: source === 'workflow'
+                        ? `Fonksiyon adı '${name}' geçersiz: ${problem}. Ad /^[A-Za-z_$][A-Za-z0-9_$]*$/ kalıbına uymalı, JavaScript ayrılmış sözcüğü ve workflow motorunun global adı (system, input, Now, crypto…) olmamalı — platform 422 GlobalFunctionNameInvalid döner.`
+                        : `Fonksiyon adı '${name}' geçersiz: ${problem}. Ad /^[A-Za-z_$][A-Za-z0-9_$]*$/ kalıbına uymalı, JavaScript ayrılmış sözcüğü ve 'Functions' olmamalı — platform 422 GlobalFunctionNameInvalid döner; kayıt bir yolla geçse bile runtime böyle bir adı atlar ve Functions.${name} tanımsız kalır.`,
+                    guide: functionsGuide
+                });
+            }
+            for (const parameter of asArray(definition.parameters).filter(isRecord)) {
+                if (isValidParameterName(parameter.name))
+                    continue;
+                findings.push({
+                    ruleId: 'FN-001',
+                    severity: 'block',
+                    message: `'${name}' fonksiyonunun parametre adı '${String(parameter.name ?? '')}' geçersiz (${nameProblem(parameter.name) ?? 'geçersiz'}) — platform 422 GlobalFunctionNameInvalid döner; runtime geçersiz parametre adlı fonksiyonu TÜMÜYLE atlar.`,
+                    guide: functionsGuide
+                });
+            }
+            return findings;
+        }
+    },
+    {
+        id: 'FN-002',
+        module: 'function',
+        appliesTo: ['create', 'update'],
+        sourceRef: 'CreateGlobalFunctionCommandValidator: parametre adı tekrarı → 422 GlobalFunctionParameterNameDuplicate; bildirim parametreleri konumsal bağlar, aynı ad ikinci değeri gölgeler',
+        check: definition => {
+            const names = asArray(definition.parameters).filter(isRecord).map(parameter => String(parameter.name ?? ''));
+            const duplicates = [...new Set(names.filter((entry, index) => entry !== '' && names.indexOf(entry) !== index))];
+            return duplicates.length === 0
+                ? []
+                : [{
+                        ruleId: 'FN-002',
+                        severity: 'block',
+                        message: `'${String(definition.name ?? '?')}' fonksiyonunda parametre adı tekrar ediyor: ${duplicates.join(', ')} — platform 422 GlobalFunctionParameterNameDuplicate döner. Çağrı konumsaldır (K5); aynı ad iki konumu birden alamaz.`,
+                        guide: functionsGuide
+                    }];
+        }
+    },
+    {
+        id: 'FN-003',
+        module: 'function',
+        appliesTo: ['create', 'update'],
+        sourceRef: 'K15: fonksiyon başka fonksiyonu çağırabilir, tanım sırası önemsiz — kendini çağıran gövde durma koşulu yoksa sonsuz özyinelemedir; runCode RangeError\'ı yutar, sunucuda Jint LimitRecursion henüz yok (B-16, Faz 9)',
+        check: definition => {
+            const name = String(definition.name ?? '');
+            const source = sourceOf(definition);
+            const body = typeof definition.body === 'string' ? definition.body : '';
+            if (name === '' || !callsItself(name, body, source))
+                return [];
+            return [{
+                    ruleId: 'FN-003',
+                    severity: 'warn',
+                    message: `'${name}' gövdesi ${callPrefix(source)}${name}(…) ile KENDİNİ çağırıyor. Durma koşulu yoksa ${source === 'workflow' ? 'Jint sınırsız özyinelemeye girer (B-16 sertleştirmesi Faz 9\'da)' : "tarayıcıda 'Maximum call stack size exceeded' (runCode yutar, hedef prop yazılmaz)"}. Bilinçli özyinelemeyse yok sayın.`,
+                    guide: functionsGuide
+                }];
+        }
+    },
+    {
+        id: 'FN-004',
+        module: 'function',
+        appliesTo: ['create', 'update'],
+        sourceRef: "K6: isAsync istemci semantiğidir — function-source.ts compiles(): await taşıyan senkron gövde derlenmez ve atlanır; {{ }} inline bağlama Promise'i [object Promise] çizer. source:'workflow' senkron Jint motorunda koşar: GlobalFunction.ValidateState isAsync'i reddeder (422 GlobalFunctionAsyncNotAllowed)",
+        check: definition => {
+            const name = String(definition.name ?? '?');
+            const body = typeof definition.body === 'string' ? definition.body : '';
+            const isAsync = definition.isAsync === true;
+            if (isAsync && sourceOf(definition) === 'workflow') {
+                return [{
+                        ruleId: 'FN-004',
+                        severity: 'block',
+                        message: `'${name}' source:'workflow' ama isAsync=true — workflow motoru senkron çalışır, async bildirimin dönüşü Promise olur ve code adımı '[object Promise]' görür; platform 422 GlobalFunctionAsyncNotAllowed döner. isAsync:false yapın; await gerekiyorsa bu bir studio fonksiyonudur.`,
+                        guide: functionsGuide
+                    }];
+            }
+            if (isAsync && !mentionsAwait(body)) {
+                return [{
+                        ruleId: 'FN-004',
+                        severity: 'warn',
+                        message: `'${name}' isAsync=true ama gövdede await yok — async gereksiz ve bedeli var: {{ }} inline bağlamada dönüş Promise'dir ve ekrana '[object Promise]' yazılır. await gerekmiyorsa isAsync:false yapın.`,
+                        guide: functionsGuide
+                    }];
+            }
+            if (!isAsync && mentionsAwait(body)) {
+                return [{
+                        ruleId: 'FN-004',
+                        severity: 'warn',
+                        message: `'${name}' gövdesi await içeriyor ama isAsync=false — senkron function içinde await SyntaxError'dur: tarayıcı gövdeyi derleyemez ve fonksiyonu ATLAR (function-source.ts compiles), sunucu da derleyemediği gövdeyi atlar; Functions.${name} hiçbir yerde tanımlı olmaz. Ya isAsync:true yapın (o zaman yalnız tarayıcıda, function/code adımından çağrılır) ya da await'i kaldırın.`,
+                        guide: functionsGuide
+                    }];
+            }
+            return [];
+        }
+    },
+    {
+        id: 'FN-005',
+        module: 'function',
+        appliesTo: ['create'],
+        sourceRef: "CreateGlobalFunctionCommandValidator When(source): workflow ⇒ applicationId/pageId/scope null (422 GlobalFunctionSourceWorkflowScopeForbidden); studio ⇒ applicationId ve scope zorunlu, scope=page ⇒ pageId (422 GlobalFunctionScopePageRequired), scope=application ⇒ pageId yok (422 GlobalFunctionScopeApplicationPageForbidden)",
+        check: definition => {
+            const name = String(definition.name ?? '?');
+            const source = sourceOf(definition);
+            const has = (key) => definition[key] !== undefined && definition[key] !== null && definition[key] !== '';
+            const block = (message) => ({ ruleId: 'FN-005', severity: 'block', message, guide: functionsGuide });
+            if (source === 'workflow') {
+                const extras = ['applicationId', 'pageId', 'scope'].filter(has);
+                return extras.length === 0
+                    ? []
+                    : [block(`'${name}' source:'workflow' ama ${extras.join(', ')} verilmiş — workflow fonksiyonu TENANT genelidir, uygulamaya/kapsama/sayfaya bağlanmaz (platform 422 GlobalFunctionSourceWorkflowScopeForbidden). Alanları kaldırın; uygulamaya özel bir tarayıcı fonksiyonu istiyorsanız source:'studio'.`)];
+            }
+            if (!has('applicationId'))
+                return [block(`'${name}' source:'studio' ama applicationId yok — studio fonksiyonu bir uygulamaya aittir (platform 422). application_list ile uygulama id'sini verin; tenant geneli bir SUNUCU fonksiyonu istiyorsanız source:'workflow'.`)];
+            if (!has('scope'))
+                return [block(`'${name}' source:'studio' ama scope yok — 'application' (her sayfada) ya da 'page' (tek sayfa, pageId zorunlu) seçin (platform 422).`)];
+            if (definition.scope === 'page' && !has('pageId'))
+                return [block(`'${name}' scope:'page' ama pageId yok — platform 422 GlobalFunctionScopePageRequired verir; page_list ile sayfa id'sini alın.`)];
+            if (definition.scope === 'application' && has('pageId'))
+                return [block(`'${name}' scope:'application' fonksiyonda pageId verilmez — platform 422 GlobalFunctionScopeApplicationPageForbidden verir; sayfaya bağlamak istiyorsanız scope:'page'.`)];
+            return [];
+        }
+    },
+    {
+        id: 'FLOW-024',
+        module: 'flow',
+        appliesTo: ['create', 'update'],
+        sourceRef: 'K9 + B-19: function adımında args.functionId zorunlu ve uygulamada var olmalı (CreateFlowCommandHandler ilk satırında 422 UiFunctionNotFound); tasks/function/function.ts önce id, sonra functionName ile çözer; parameters bildirim sırasına göre ada göre eşlenir',
+        check: definition => flowAllSteps(definition)
+            .filter(step => step.type === 'function')
+            .flatMap(step => {
+            const args = (step.args ?? {});
+            const label = flowStepLabel(step);
+            const findings = [];
+            if (typeof args.functionId !== 'string' || !conditionRuleIdPattern.test(args.functionId)) {
+                findings.push({
+                    ruleId: 'FLOW-024',
+                    severity: 'block',
+                    message: `'${label}' function adımında args.functionId ${args.functionId === undefined || args.functionId === null ? 'yok' : `geçersiz ('${String(args.functionId)}')`} — platform 422 UiFunctionNotFound döner. Gerçek id'yi function_list ile alın; runtime fonksiyonu ÖNCE id ile çözer, functionName yalnız yedektir (K9).`,
+                    guide: functionsGuide
+                });
+            }
+            if (typeof args.functionName !== 'string' || args.functionName.trim() === '') {
+                findings.push({
+                    ruleId: 'FLOW-024',
+                    severity: 'warn',
+                    message: `'${label}' function adımında args.functionName boş — Studio adım özeti 'seçili fonksiyon yok' gösterir ve id çözülemezse ad yedeği de kalmaz. functionName: '<fonksiyon adı>' yazın.`,
+                    guide: functionsGuide
+                });
+            }
+            if (args.parameters !== undefined && args.parameters !== null && !Array.isArray(args.parameters)) {
+                findings.push({
+                    ruleId: 'FLOW-024',
+                    severity: 'block',
+                    message: `'${label}' function adımında args.parameters dizi değil (${typeof args.parameters}) — şekil: [{ name: '<bildirimdeki ad>', value: { type: 'static'|'property'|'storage'|'state'|'code'|'variable'|'page'|'item', ref } }].`,
+                    guide: functionsGuide
+                });
+            }
+            const nameless = asArray(args.parameters).filter(isRecord).filter(parameter => typeof parameter.name !== 'string' || parameter.name.trim() === '');
+            if (nameless.length > 0) {
+                findings.push({
+                    ruleId: 'FLOW-024',
+                    severity: 'block',
+                    message: `'${label}' function adımında ${nameless.length} parametrenin name'i yok — eşleme bildirimdeki ada göre yapılır, adsız parametre hiçbir argümana bağlanmaz.`,
+                    guide: functionsGuide
+                });
+            }
+            return findings;
+        })
+    },
+    {
+        id: 'WF-030',
+        module: 'workflow',
+        appliesTo: ['create', 'update', 'preview'],
+        sourceRef: "2026-09-10 kararı (Owner MR notu, zeyrek-backend docs/global-functions/02 §1): sunucu UI fonksiyonlarını YÜKLEMEZ — WorkflowContext'in 'Functions' ad alanı ve yükleme yolu kaldırıldı. Workflow/middleware/automation ifadesindeki Functions.<ad>(…) çağrısı Jint'te 'Functions is not defined' ile düşer (canlı ölçüldü: workflow_preview code adımı). Sunucuda paylaşılan hesap source:'workflow' fonksiyondur, çıplak adla çağrılır",
+        check: (definition, context) => {
+            const names = [...new Set(functionCallRefs(JSON.stringify(workflowBody(definition, context.workflowKind) ?? {})).map(ref => ref.name))];
+            return names.length === 0
+                ? []
+                : [{
+                        ruleId: 'WF-030',
+                        severity: 'block',
+                        message: `İfadeler ${names.map(name => `Functions.${name}(…)`).join(', ')} çağırıyor ama SUNUCUDA 'Functions' ad alanı YOKTUR (2026-09-10): motor kullanıcı fonksiyonlarını yüklemez, çağrı 'Functions is not defined' ile düşer ve adım hata yoluna girer. Sunucuda paylaşılan hesap source:'workflow' fonksiyondur — function_create source:'workflow' ile tanımlayıp ifadede çıplak adla çağırın ('${names[0]}(…)'). Kullanıcı fonksiyonları yalnız tarayıcıda çalışır ({{ }} bağlaması ve UI flow adımları).`,
+                        guide: functionsGuide
+                    }];
+        }
+    },
     {
         id: 'FLOW-005',
         module: 'flow',
@@ -2479,3 +2740,84 @@ export const policyRules = [
     // tek liste `backendConstraints.ts`'te durur, buradan yalnız politika motoruna katılır.
     ...backendPolicyRules()
 ];
+/**
+ * WF-MF-001'in ikinci yarısı. Bir adımın koşup koşmayacağı yalnız GÖVDEDEN anlaşılamaz: karar
+ * seçilen microfunction'ın YAYIN DURUMUNA bağlıdır ve o durum platformda yaşar. Politika
+ * kuralları senkron ve saf olduğu için bu denetim ayrı durur — gateway `microfunction_get`
+ * ucunu okur, bulguyu aynı `policyFindings` kanalına koyar ve `policyOverride` / `POLICY=warn`
+ * kaçışları (applyPolicyMode) aynen geçerli kalır.
+ *
+ * Okuma başarısız olursa (ağ, yetki, beklenmeyen gövde) kural SUSAR: ön-denetim bir kolaylıktır,
+ * gateway'in kendi arızası yüzünden geçerli bir workflow yazılamaz hâle gelmemeli.
+ */
+export async function microfunctionStepFindings(platform, project, environment, definition, kind, policyOverride = false) {
+    if (platform.config.policyMode === 'off')
+        return [];
+    const steps = workflowSteps(workflowBody(definition, kind))
+        .filter(step => step.type === 'microfunction')
+        .filter(step => hasText((step.rule ?? {}).microfunctionId));
+    if (steps.length === 0)
+        return [];
+    const records = new Map();
+    const findings = [];
+    for (const step of steps) {
+        const rule = (step.rule ?? {});
+        const microfunctionId = String(rule.microfunctionId);
+        if (!records.has(microfunctionId)) {
+            try {
+                const payload = await platform.tenant('GET', project, `/microfunctions/${microfunctionId}`, { environment });
+                records.set(microfunctionId, (payload?.data ?? payload));
+            }
+            catch (error) {
+                records.set(microfunctionId, error instanceof PlatformApiError && error.status === 404 ? 'missing' : 'unreadable');
+            }
+        }
+        const record = records.get(microfunctionId);
+        if (record === undefined || record === 'unreadable')
+            continue;
+        if (record === 'missing') {
+            findings.push({
+                ruleId: 'WF-MF-001',
+                severity: 'block',
+                message: `'${stepLabel(step)}' adımının microfunctionId'si (${microfunctionId}) bu ortamda YOK. Adım kuralı step_rules.microfunction_id ile kayda FK'lıdır: gövde gitseydi platform 400 dönerdi. microfunction_list ile bu ortamdaki kayıtları görün — fonksiyon başka bir dalda/ortamda kalmış olabilir.`,
+                guide: 'ngapps://guides/microfunction'
+            });
+            continue;
+        }
+        const status = String(record.status ?? '');
+        if (status === 'draft' || status === 'publish-failed') {
+            findings.push({
+                ruleId: 'WF-MF-001',
+                severity: 'block',
+                message: `'${stepLabel(step)}' adımı '${String(record.name ?? microfunctionId)}' fonksiyonunu seçiyor ama kaydın durumu '${status}'${status === 'publish-failed' && hasText(record.publishError) ? ` (publishError: ${String(record.publishError)})` : ''}. Step YALNIZ yayındaki kaydı koşturur: MicrofunctionStep kaydı yükleyip Status != Published görünce MicrofunctionNotPublishedException ile FAIL dalına düşer — akış kurulur, kaydedilir ve koşumda sessizce hata yoluna girer. Önce microfunction_publish çağırın ve microfunction_get ile 'published' olduğunu görün.`,
+                guide: 'ngapps://guides/microfunction'
+            });
+            continue;
+        }
+        if (status === 'publishing') {
+            findings.push({
+                ruleId: 'WF-MF-001',
+                severity: 'warn',
+                message: `'${stepLabel(step)}' adımının fonksiyonu ('${String(record.name ?? microfunctionId)}') şu anda yayınlanıyor. Yayın ASENKRONDUR: bu akış şimdi koşarsa adım fail dalına düşer. microfunction_get ile 'published' olduğunu doğrulayın (yayın başarısız olursa durum 'publish-failed' olur).`,
+                guide: 'ngapps://guides/microfunction'
+            });
+        }
+        if (record.hasUnpublishedChanges === true) {
+            findings.push({
+                ruleId: 'WF-MF-001',
+                severity: 'warn',
+                message: `'${String(record.name ?? microfunctionId)}' fonksiyonu yayında ama üstüne yazılmış (hasUnpublishedChanges: true, revision ${String(record.revision ?? '?')} ≠ publishedRevision ${String(record.publishedRevision ?? '?')}). Runtime hâlâ ESKİ sürümü koşuyor — yeni kodu canlıya almak için microfunction_publish çağırın.`,
+                guide: 'ngapps://guides/microfunction'
+            });
+        }
+        if (!hasText(rule.expression) && hasText(record.parameterDtoId)) {
+            findings.push({
+                ruleId: 'WF-MF-001',
+                severity: 'warn',
+                message: `'${stepLabel(step)}' adımında rule.expression boş ama '${String(record.name ?? microfunctionId)}' fonksiyonunun bir parametre DTO'su var (parameterDtoId: ${String(record.parameterDtoId)}). Fonksiyon args olarak boş nesne alır ve kendi alanlarını undefined görür. Argümanları ifadeyle geçirin — şemayı microfunction_get çıktısındaki parameterScheme verir.`,
+                guide: 'ngapps://guides/microfunction'
+            });
+        }
+    }
+    return applyPolicyMode(platform.config, findings, policyOverride);
+}

package/dist/platform/csv.js

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

package/dist/platform/errors.js

@@ -1,6 +1,12 @@
 export class PlatformApiError extends Error {
     status;
     code;
+    /**
+     * Toplu satır yazmasında düşen satırın parti içi indeksi (`BulkRowErrorResponse.rowIndex`).
+     * Mesajda da geçer ama metinden ayıklanamaz: parti döngüsü dosya satır numarasını hesaplamak
+     * için sayıya ihtiyaç duyar, çağıran hangi satırı düzelteceğini ancak öyle bilir.
+     */
+    rowIndex;
     constructor(message, status, code) {
         super(message);
         this.status = status;
@@ -50,6 +56,56 @@ function collectValidationMessages(payload) {
  * hatalı prop'ları sessizce kaydediyordu). Orada op listesi yoktur ve `page_schema_validate` de
  * uygulanmaz — ipucu bu yüzden yola göre ayrışır.
  */
+/**
+ * Merge apply'ın iki 409'u da aynı şeyi söyler: plan artık uygulanabilir değil. Ajan bunu
+ * 'geçici hata, tekrar dene' diye okuyup aynı çağrıyı yollamasın diye yol açıkça yazılır.
+ */
+function mergeHint(path) {
+    if (!/\/merges\//.test(path))
+        return '';
+    return " Üç sebepten biri: çözülmemiş çakışma, ya da plan alındığından beri DALIN veya development’ın değişmesi (MergePlanStaleException) — ikincisinde planın taşıdığı liste eskidir ve uygulansaydı sonradan yapılan iş sessizce düşerdi. merge_get ile planı yeniden okuyun (isStale), bayatsa merge_refresh ile tazeleyin — yeni plan açmanız gerekmez. Aynı merge_apply çağrısını tekrarlamak sonucu değiştirmez.";
+}
+function mergeRevertHint(code) {
+    if (code === 'MergeRevertWindowExpiredException') {
+        return " Geri alma penceresi doldu: pencere kapanınca merge öncesi anlık görüntü de silinir, bu yüzden plan artık geri alınamaz. merge_list status:'applied' ile pencere içindeki bir plan seçin.";
+    }
+    if (code === 'MergePlanNotRevertableException') {
+        return ' Bu plan bir GERİ ALMA planı (kind=revert) ve geri almanın geri alması yoktur. Geri almayı iptal etmek istiyorsanız dalı yeniden merge edin.';
+    }
+    if (code === 'MergePlanNotAppliedException') {
+        return " Plan uygulanmış DEĞİL — durumu mesajda yazıyor (failed / discarded / reverted / planned…). Yalnız 'applied' ve 'applied-with-drift' geri alınabilir; merge_list status:'applied' ile uygun planı seçin. Zaten geri alınmış bir planın durumu 'reverted'dır ve ikinci kez geri alınamaz.";
+    }
+    return '';
+}
+/**
+ * İçe aktarma zinciri dört çağrıdır ve her hata farklı bir adıma geri gönderir: plan süresi
+ * dolduysa analizden, anahtar benzersiz değilse plan gövdesinden, hata oranı yüksekse dosyanın
+ * kendisinden. Kod olmadan mesajlar "422" diye okunur ve ajan aynı çağrıyı tekrarlar.
+ */
+function importHint(code, path) {
+    if (code === 'ImportPlanExpiredException') {
+        return ' Plan bir saat geçerlidir ve süresi doldu (ya da başka bir kullanıcıya ait). import_analyze ile dosyayı yeniden okuyup import_plan ile yeni bir plan üretin — aynı planId bir daha çalışmaz.';
+    }
+    if (code === 'ImportTooManyErrorsException') {
+        return " Satırların yarısından fazlası kuru koşuda düştü. Önce planın `errors` listesine bakın: çoğu zaman tek bir yanlış `locale` ya da yanlış sütun tipi bütün satırları düşürür. Dosya gerçekten böyleyse import_run'ı `force: true` ile çağırın.";
+    }
+    if (code === 'ImportKeyFieldNotUniqueException') {
+        return " Upsert/update anahtarı benzersiz olmalı: alanın kendisi unique/primary key olmalı, ya da tek alanlı bir unique index taşımalı, ya da 'id'/'code' olmalı. entity_get ile alanın `unique` bayrağını doğrulayın.";
+    }
+    if (code === 'ImportRelationMatchFieldNotUniqueException') {
+        return ' Ad → id eşlemesi yalnız hedef tablonun display alanı ya da benzersiz bir alanıyla yapılır; benzersiz olmayan bir alanda aynı ad iki satıra gidebilir ve hangisinin yazılacağı belirsiz olur.';
+    }
+    if (code === 'ImportSheetEmptyException' || code === 'ImportRowLimitExceededException') {
+        return ' `headerRow` doğru mu kontrol edin (0 = başlık yok); satır sınırı aşıldıysa dosyayı sayfalara bölün.';
+    }
+    if (code === 'DataJobNotUndoableException' && path.endsWith('/cancel')) {
+        return ' İş zaten bitmiş (completed / failed / undone / cancelled); iptal edilecek bir şey yok. Tamamlanmış işi geri almak için import_undo.';
+    }
+    if (code === 'DataJobNotUndoableException' && path.endsWith('/undo')) {
+        return ' Yalnız tamamlanmış ve undoAvailableUntil geçmemiş bir içe aktarma geri alınır; mevcut tabloya yalnız ekleme yapan işin penceresi hiç açılmaz. Süren işi durdurmak için import_cancel.';
+    }
+    return '';
+}
 function pageSchemaHint(code, path) {
     if (code === 'PageSchemaVersionConflictException') {
         return ' Sayfa siz okuduktan sonra değişti ve HİÇBİR op uygulanmadı. page_schema_get ile yeniden okuyup planı tazeleyin, yeni `version` değerini `baseVersion` olarak gönderin.';
@@ -133,7 +189,7 @@ export function mapPlatformError(status, payload, context) {
         if (validationMessages.length > 0) {
             return new PlatformApiError(`Doğrulama hatası (${location}): ${validationMessages.join(' ; ')}. Gövde şeması için ilgili ngapps://schemas kaynağına ya da mevcut bir kaydın *_get çıktısına bakın.`, status, code);
         }
-        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}`, status, code);
+        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}${mergeRevertHint(code)}${importHint(code, context.path)}`, status, code);
     }
     if (status === 401) {
         const hint = context.authMode === 'local'
@@ -151,7 +207,7 @@ export function mapPlatformError(status, payload, context) {
         if (context.method !== 'GET' && /\/flows(\/|$)/.test(context.path)) {
             return new PlatformApiError(`Adımda referans verilen kayıt çözümlenemedi (${location}). Bu uçta 404 akışın kendisini DEĞİL bir adım argümanını kastediyor: flow-trigger adımının args'ında ne flowId ne triggerElementId var (ya da triggerElementId sayfadaki hiçbir elementId ile eşleşmiyor), setter adımının iteratees[].element'i bulunamıyor, ya da bir adım silinmiş bir komponente bakıyor. Adım argümanlarını page_schema_get'teki elementId'lerle karşılaştırın; flow-trigger'ın iki geçerli şekli için platform_guide('page') Kural 1c.`, status, code);
         }
-        return new PlatformApiError(`Kayıt bulunamadı (${location}).${environmentHint} id/slug değerini ilgili *_list tool'uyla doğrulayın.`, status, code);
+        return new PlatformApiError(`Kayıt bulunamadı (${location}).${environmentHint} id/slug değerini ilgili *_list tool'uyla doğrulayın.${importHint(code, context.path)}`, status, code);
     }
     if (status === 409 || status === 422) {
         const projectConflictHint = status === 409 && context.method === 'POST' && /\/projects\/?$/.test(context.path)
@@ -159,7 +215,10 @@ export function mapPlatformError(status, payload, context) {
             : '';
         const validationMessages = collectValidationMessages(body);
         const detail = validationMessages.length > 0 ? ` → ${validationMessages.join(' ; ')}` : '';
-        return new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code, context.path)}${bulkRowHint(code)}${versionConflictHint(code, context.path)}`, status, code);
+        const rejected = new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code, context.path)}${bulkRowHint(code)}${importHint(code, context.path)}${versionConflictHint(code, context.path)}${mergeHint(context.path)}`, status, code);
+        if (typeof body.rowIndex === 'number')
+            rejected.rowIndex = body.rowIndex;
+        return rejected;
     }
     const fallbackValidationMessages = collectValidationMessages(body);
     const fallbackDetail = fallbackValidationMessages.length > 0 ? ` → ${fallbackValidationMessages.join(' ; ')}` : '';

package/dist/platform/http.js

@@ -125,6 +125,7 @@ export class Platform {
             ...(authorization === undefined ? {} : { authorization }),
             ...(options.environment ? { 'x-environment': options.environment } : {}),
             ...callerHeaders,
+            'x-client': 'mcp',
             ...(options.mirrorAuthorizationCookie && authorization !== undefined && callerHeaders.cookie === undefined
                 ? { cookie: `NG_AccessToken=${authorization.replace(/^Bearer /, '')}` }
                 : {})