@appaflytech/zeyrek-ai-mcp 0.0.28 → 0.0.30

package/dist/platform/errors.js

@@ -7,6 +7,11 @@ export class PlatformApiError extends Error {
      * için sayıya ihtiyaç duyar, çağıran hangi satırı düzelteceğini ancak öyle bilir.
      */
     rowIndex;
+    /**
+     * Platformun ham `message`'ı (yalnız 403'te doldurulur). `message` gateway ipucunu da taşır ve ipucunda
+     * izin slug'ları geçer ('entity.reveal grant'i'); `accessDecision` izni ondan okursa yanlış izin yazar.
+     */
+    apiMessage;
     constructor(message, status, code) {
         super(message);
         this.status = status;
@@ -32,9 +37,12 @@ function collectValidationMessages(payload) {
                 continue;
             const record = entry;
             const isPageSchemaShape = 'rule' in record || 'componentId' in record || 'suggestions' in record;
+            const isDefinitionFindingShape = 'path' in record && 'message' in record && 'code' in record;
             messages.push(isPageSchemaShape
                 ? formatPageSchemaError(record)
-                : `${record.key ?? '?'}: ${record.value ?? ''}`);
+                : isDefinitionFindingShape
+                    ? `${String(record.path)} [${String(record.code)}]: ${String(record.message)}`
+                    : `${record.key ?? '?'}: ${record.value ?? ''}`);
         }
     }
     else if (payload.errors && typeof payload.errors === 'object') {
@@ -106,6 +114,39 @@ function importHint(code, path) {
     }
     return '';
 }
+function processHint(code, path) {
+    if (code === 'DefinitionInvalid' && /\/bpm\/definitions\/[^/]+\/override(\/|$)/.test(path))
+        return " Uyarlama platform doğrulamasından geçmedi; yukarıdaki path [kod] satırlarına bakın. RegionLocked/ParamNotEditable: yol uyarlamaya kapalı — process_override_get yanıtındaki editableScopes'a göre kurun (bölge çocuğu '/nodes[id=<bölge>]/nodes[id=<adım>]/<alan>'); RoleUnknown/WorkflowUnknown: referans bu ortamda yok. Kurallar platform_guide('bpm') §Uyarlama.";
+    if (code === 'TaskAlreadyClaimed')
+        return ' Görev başkası tarafından üstlenildi ya da siz okuduktan sonra değişti. process_task_get ile yeniden okuyup güncel version değeriyle tekrar deneyin; görev başkasındaysa eylem sizin değildir.';
+    if (code === 'TaskStateTransitionNotAllowed')
+        return " Görevin durumu bu eylemi almıyor (ör. waiting-info iken approve, tamamlanmış görevde claim). process_task_get'teki state ve actions listesine bakın.";
+    if (code === 'TaskCommentRequired')
+        return " Bu karar yorum ister (düğümün commentRequired kuralı). Aynı çağrıyı 'comment' ile tekrarlayın.";
+    if (code === 'UndoWindowClosed')
+        return " Geri alma penceresi kapandı ya da karardan sonra başka bir insan görevi açıldı; geri alma yerine process_instance_update ya da yeni karar gerekir.";
+    if (code === 'InstanceStateTransitionNotAllowed')
+        return " Örnek bu durumda bu müdahaleyi almaz (ör. tamamlanmış örneği askıya alma). process_instance_get ile state'i okuyun.";
+    if (code === 'WithdrawNotAllowed')
+        return " Tanımın withdrawPolicy'si geri çekmeye izin vermiyor ya da ilk karar verilmiş.";
+    if (code === 'DefinitionInvalid')
+        return " Tanım platform doğrulamasından geçmedi; yukarıdaki path [kod] satırlarını düzeltip process_definition_preview ile yeniden doğrulayın.";
+    if (code === 'OpenTasksExist')
+        return " Kullanıcının ya da birimin açık süreç görevi var. process_handover_preview ile kalemleri görün, process_handover_create ile devredin; sonra işlemi tekrarlayın.";
+    if (code === 'HandoverIncomplete')
+        return " Kararı olmayan görev grupları mesajda. Her assigned-tasks / candidate-tasks kalemi için karar verin ya da force:true ile geri dönüşü kabul edin: assigned-tasks yöneticiye (yoksa admin-queue), candidate-tasks gruba (aday kalmazsa admin-queue).";
+    if (code === 'DelegationOverlap')
+        return " Aynı kişinin bu aralık ve süreç filtresiyle çakışan vekaleti var. process_delegation_list ile görüp bitirin ya da aralığı değiştirin.";
+    if (code === 'DelegationChainNotAllowed')
+        return " Vekalet zincirlenemez: ya vekil aynı aralıkta kendi görevlerini devretmiş ya da vekaleti veren kişi o aralıkta başkasının vekili. Başka vekil ya da aralık seçin.";
+    if (code === 'PublishApprovalRequired')
+        return " Tanım dört göz yayın politikasında (publishPolicy: four-eyes) ve ortamda process-publish süreci kurulu. Aynı çağrıyı process_definition_publish { reason } ile tekrarlayın: yayın isteği açılır, onaylanınca sürüm aktif olur.";
+    if (code === 'ScenarioFailed')
+        return " Tanım requireGreenScenarios: true ve adı geçen senaryo bu taslağın sağlamasında yeşil koşmadı. process_scenario_execute { definitionId } ile koşun, sapmaları giderin (ya da senaryoyu process_scenario_update ile güncelleyin), sonra yeniden yayınlayın.";
+    if (code === 'BatchOperationNotUndoable')
+        return " Yalnız tamamlanmış reassign / extend-due işlemleri bir kez geri alınır; start ve cancel geri alınamaz.";
+    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.';
@@ -142,12 +183,20 @@ function bulkRowHint(code) {
 function versionConflictHint(code, path) {
     if (code !== 'AggregateVersionConflictException')
         return '';
-    const readTool = /\/entities(\/|$)/.test(path) ? 'entity_get'
-        : /\/workflows(\/|$)/.test(path) ? 'workflow_get'
-            : /\/flows(\/|$)/.test(path) ? 'flow_get'
-                : /\/layouts(\/|$)/.test(path) ? 'layout_get'
-                    : /\/microservices(\/|$)/.test(path) ? 'microservice_get'
-                        : 'ilgili *_get';
+    if (/\/bpm\/tasks(\/|$)/.test(path)) {
+        return ' Görev siz okuduktan sonra değişti (başka biri üstlendi ya da karar verdi) ve eylem UYGULANMADI. process_task_get ile yeniden okuyun; görev hâlâ size açıksa güncel `version` değeriyle eylemi tekrarlayın, değilse eylem sizin değildir.';
+    }
+    if (/\/bpm\/definitions\/[^/]+\/override(\/|$)/.test(path)) {
+        return ' Uyarlama ya da aktif sürüm siz okuduktan sonra değişti (başka bir yönetici kaydetti ya da geliştirici yeni sürüm yayınladı) ve HİÇBİR op yazılmadı. process_override_get ile yeniden okuyun; conflictState conflicted ise patch yeni sürüme göre kurulmalı. process_override_update aynı çağrıda güncel sürümü okur — patch güncel uyarlamaya uyuyorsa çağrıyı tekrarlayın.';
+    }
+    const readTool = /\/bpm\/definitions(\/|$)/.test(path) ? 'process_definition_get'
+        : /\/bpm\/instances(\/|$)/.test(path) ? 'process_instance_get'
+            : /\/entities(\/|$)/.test(path) ? 'entity_get'
+                : /\/workflows(\/|$)/.test(path) ? 'workflow_get'
+                    : /\/flows(\/|$)/.test(path) ? 'flow_get'
+                        : /\/layouts(\/|$)/.test(path) ? 'layout_get'
+                            : /\/microservices(\/|$)/.test(path) ? 'microservice_get'
+                                : 'ilgili *_get';
     return ` Kayıt siz okuduktan sonra değişti ve HİÇBİR op uygulanmadı (mesajdaki beklenen/mevcut sürüm). ${readTool} ile yeniden okuyup patch'i güncel hâle göre kurun, yeni \`version\` değerini \`baseVersion\` olarak gönderin — aynı ops'u eski sürümle tekrar göndermek aradaki değişikliği ezer.`;
 }
 /**
@@ -177,6 +226,69 @@ function diagnoseKnownFailure(status, message, code, context) {
     }
     return '';
 }
+/**
+ * Erişim politikası ve alan koruması hataları `InvalidParameterException` kodu altında gelir ve
+ * ayırt edici anahtar MESAJDADIR (`AccessScopeNotSupported: entity.create`); koşul ve koruma
+ * hatalarının bir kısmı ise kendi exception adını `code`'da taşır. İkisi de burada tek sözlükle
+ * bir sonraki adıma çevrilir (rol yönetim şeması g-21).
+ */
+const accessErrorHints = [
+    ['ConnectDataDefinitionInvalid', " Bağlantı tanımı platform şemasına uymuyor (bilinmeyen anahtar, bozuk enum ya da eksik alan) — mesajdaki yolu düzeltin; kural adları connect-data-* (PAGE-035 · CD-004). Tanım şekli: platform_guide('page') §Kural 1c-3."],
+    ['ConnectDataPropNotConnected', " Bu prop veri kaynağına bağlı değil — önce connect_data_bind (ya da page_schema_patch set_connect_data) ile bağlayın; bir prop'un bağlantısını connect_data_get okur."],
+    ['ConnectDataFilterNotAllowed', " Filtre, arama ya da sıralama bu bağlantıda izinli değil: alan tanımın behavior.filterable/searchable listesinde olmalı ve işleç connect_data_describe'daki operators içinde; korumalı alanda yalnız eq · neq · in · notin, korumalı alan sıralanmaz; tanım filtresindeki $parametre params ile verilmeli (CD-002)."],
+    ['ConnectDataFieldNotEditable', " Alan tanımda seçili ama bağlantı ucundan yazılamaz: edit.editable listesinde değil ya da dosya alanı (dosya bu uçtan hiç yazılmaz). Yazılacaksa connect_data_bind { edit: { editable: [..., '<alan>'] } }; dosyayı file_upload ile yükleyip satırı row_update ile güncelleyin."],
+    ['ConnectDataFieldNotSelected', " İstenen alan tanımın seçtiği alanlardan değil (fields/expand), lookup ilişki alanında değil ya da yazılan alan edit.editable listesinde değil (expand yolu hiç yazılamaz) — connect_data_get ile tanıma bakın; gerekirse connect_data_bind ile alanı ekleyin ya da edit.editable'a koyun."],
+    ['ConnectDataWriteDisabled', " Tanımda bu yazma eylemi kapalı (behavior.edit) ya da edit.bulk kapalıyken birden çok satır/kimlik gönderildi — politika izin verse bile motor reddeder. Açmak için connect_data_bind { edit: { <op>: true } } (toplu için bulk: true)."],
+    ['ConnectDataWriteModeNotAllowed', " Tanımın edit.writeMode'u atomic: satırların hepsi ya da hiçbiri yazılır. Kısmi yazma (satır başına errors[]) için connect_data_bind { edit: { writeMode: 'partial' } }, ya da isteği mode göndermeden atın."],
+    ['yet: partial.', " Kısmi yazma (mode partial) yalnız built-in veritabanındaki entity'de çalışır — savepoint harici datasource bağlantısını kapsamaz. Bu kaynakta atomic yazın (mode göndermeyin, tanımda writeMode: 'atomic')."],
+    ['yet: create.', " Bu kaynak türü YAZMAZ: create/update/delete yalnız entity kaynağında çalışır (query · view · workflow · microservice okur). Yazma gereken ekranı entity kaynağına bağlayın, ya da yazmayı bir flow adımına bırakın."],
+    ['yet: update.', " Bu kaynak türü YAZMAZ: create/update/delete yalnız entity kaynağında çalışır (query · view · workflow · microservice okur). Yazma gereken ekranı entity kaynağına bağlayın, ya da yazmayı bir flow adımına bırakın."],
+    ['yet: delete.', " Bu kaynak türü YAZMAZ: create/update/delete yalnız entity kaynağında çalışır (query · view · workflow · microservice okur). Yazma gereken ekranı entity kaynağına bağlayın, ya da yazmayı bir flow adımına bırakın."],
+    ['yet: lookup.', " Lookup yalnız entity kaynağında çalışır: ilişki hücresinin hedef tablosu entity'dir. Query/view/workflow/microservice kaynağında ilişki seçimi yoktur."],
+    ['yet: datasource.', " Harici datasource (REST) kaynağı motorda YOK (b-33 kapsam dışı): platformda kayıtlı yürütücüsü yoktur. entity · query · view · workflow · microservice türlerinden birini seçin."],
+    ['ConnectDataSourceUnsupported', " Kaynak bağlanabilir değil. Başlıca nedenler: uca middleware bağlı, yazan tablo/sistem ucu, dönüş şeması yok (workflow'a dizi dönen çıktı DTO'su, query'ye çalıştırılmış örnek gerekir), sorgu salt-okunur tek SELECT değil ya da kaynak zaten connectData microservice'i (tanımı doğrudan bağlayın, connect_data_get ile okuyun). Mesajın sonundaki değer bir op adıysa (create/update/delete/lookup) neden kaynağın bağlanabilirliği değil o işlemi desteklememesidir. connect_data_describe kaynağın ne yapabildiğini söyler."],
+    ['ConnectDataMicroserviceInUse', " Bu connectData microservice'i başka bir prop'ta, başka bir sayfada ya da bir flow'da kullanılıyor: connect_data_detach tanımı geri koyup microservice'i silmek ister. Kullanımları dependency_graph ile bulup kaldırın, sonra yeniden deneyin."],
+    ['ConnectDataRelationTargetNotFound', " İlişki alanına yazılan hedef kimlik hedef tabloda yok ya da bu kullanıcı onu göremiyor — yanıtın field'ı düşen alanı söyler. Var olan bir kimliği alanın lookup'ıyla seçin (connect_data_execute op: 'lookup', field: '<alan>'); m2m listesinde her kimlik ayrı denetlenir."],
+    ['ConnectDataSourceFailed', " Kaynak (query/view/workflow/microservice) çalışırken düştü — hata kaynağın kendisinden gelir: microservice_execute / query_preview / workflow_preview ile kaynağı tek başına koşturup gerçek nedeni görün."],
+    ['ProtectionOperatorNotAllowed', " Korumalı alanda yalnız eq · neq · in · notin · isnull · isnotnull kullanılır; şifreli modda eşitlik için alanın protection.exactSearch'ü açık olmalı (PROT-001). Kısmi arama için türetilmiş alan — platform_guide('access') §'Arama ve sıralama'."],
+    ['ProtectionSortNotAllowed', " Korumalı alana göre sıralanamaz (PROT-002); başka bir alana ya da türetilmiş alana göre sıralayın."],
+    ['ProtectionFieldTypeNotSupported', " Koruma yalnız düz METİN alana konur — ilişki, sayı, çok dilli, birincil anahtar ve identity alanı korunamaz (PROT-003)."],
+    ['ProtectionDisplayFieldNotAllowed', " Display alanı korunamaz: ilişkilerde görünen ad olarak her yerde düz dönerdi (PROT-003). Önce başka bir alanı display yapın."],
+    ['ProtectionDerived', " Türetilmiş alan derivedFromFieldId + derivationRule ister; slice length > 0, regex pattern derlenmeli (PROT-004)."],
+    ['ProtectionChangeNotAllowed', " Var olan alanın korumasını entity_update / entity_patch değiştiremez; dolu satırlar arka plan işiyle dönüştürülür — entity_protection_update (202 + jobId, ilerleme import_status)."],
+    ['ProtectionMigrationInProgress', " Bu entity'de koruma işi sürüyor; ilerlemeyi GET /{proje}/DataJobs/{id} ile izleyin. İş hata verdiyse AYNI isteği aynı gövdeyle tekrar göndermek kaldığı yerden devam ettirir."],
+    ['ProtectionKeyUnavailable', " Ortamda alan koruması anahtarı yapılandırılmamış — insan işi: docs/ortam.md §Alan koruması anahtarları."],
+    ['AccessScopeRequiresOwnerFields', " Entity'de sys_owner_user_id / sys_owner_unit_id yok (ACC-003): owner-fields işi (POST /{proje}/DataJobs/owner-fields/{datasourceId}) ya da scope: 'all' + koşul."],
+    ['AccessResourceUnknown', " Anahtar kaynak kataloğunda yok — access_resource_list ile 'key' değerini alın (K-31); katalog entity/sayfa yazıldıkça kendiliğinden eşitlenir."],
+    ['AccessConditionInvalid', " Koşul alanı grant'in entity'sinin korumasız, kataloğa girmiş bir alanı olmalı ve değer işlece uymalı (ACC-001/ACC-002) — alanlar: access_resource_list { type: 'field' }."],
+    ['AccessScopeNotSupported', " Kapsam yalnız entity.read/update/delete/export/reveal/reassign izinlerinde (ACC-001)."],
+    ['AccessFieldAccessNotSupported', " fieldAccess yalnız 'field.read' izninde (ACC-001)."],
+    ['AccessDenyFieldAccessNotSupported', " Reddet grant'i alan erişimi taşımaz; kapsam ve koşul taşıyabilir, o zaman yalnız satır süzer (ACC-001) — koşulsuz scope: 'all' hariç, o kapsamsız gibi keser (ACC-042)."],
+    ['AccessOverrideRequiresUserWithEndDate', " overridesDeny yalnız subjectType 'user' ve dolu endsAt ile yazılır (ACC-009)."],
+    ['OrganizationPositionSeatOccupied', " Tek koltuklu pozisyonda aynı dönemde başka bir kalıcı atama var; vekâlet için assignmentType 'acting', kalıcı ikinci kişi için pozisyonu isMultiSeat yapın (TB-96, ORG-003)."],
+    ['OrganizationStructureNodeInUse', " Düğüm DOLU. BİRİM için: altında aktif alt birim ya da aktif pozisyon var. POZİSYON için ÜÇ sebepten biri: koltukta oturan kullanıcı, o pozisyona bağlı (idari ya da işlevsel) başka bir aktif pozisyon, ya da pozisyonu managerPositionId olarak gösteren bir birim — mesaj hangisi olduğunu söylemez. Sıra yapraktan köke: user_position_replace ile koltukları boşalt → yöneticiyi gösteren birimi organization_unit_update ile managerPositionId'siz yaz → ast pozisyonları organization_position_deactivate → alt birimler → organization_unit_deactivate. Durumu organization_tree_get (includeInactive: true) ve user_position_list gösterir."],
+    ['UserPositionPeriodInvalid', " Atamanın endsAt'i startsAt'ten sonra olmalı (ORG-003)."],
+    ['UserPositionPrimaryDuplicate', " Bir kullanıcının en çok bir birincil ataması olur (ORG-003)."],
+    ['RevealReasonTooShort', " Gerekçe projenin asgari uzunluğunun altında; project_get → revealReasonMinLength (TB-98, ACC-010). Reddedilen deneme denetim defterine REVEAL-DENIED olarak düşer."],
+    ['EnforcementOffRequiresConfirmation', " off'a geçiş korumalı alanları herkese açık yapar ve satır kapsamını kaldırır; bilinçliyseniz confirm: true (TB-99, ACC-007)."],
+    ['AccessConditionRequiresScope', " Koşul yalnız kapsamla birlikte yazılır; saf koşul için scope: 'all' (K-11, ACC-001)."],
+    ['AccessPermissionUnknown', " İzin slug'ı katalogda yok — access_permission_list (katalog yalnız kompleks projede dolu)."],
+    ['AccessPolicySlugDuplicate', ' Politika slug\'ı projede tekildir; access_policy_list ile mevcut politikayı bulun.'],
+    ['EntityHasNoOwnerFields', " Entity'de sahiplik alanı (sys_owner_user_id / sys_owner_unit_id) yok, devredilecek bir sahiplik de yok: owner-fields işi (POST /{proje}/DataJobs/owner-fields/{datasourceId}) alanları açar. Basit projede bu alanlar hiç kurulmaz."],
+    ['OwnershipFieldNotWritable', " Sahiplik alanı satır güncellemesiyle yazılmaz (ORG-006): row_reassign kullanın, ya da uygulama kullanıcısının kapsamıyla devretmek için systemOperation 'entity.row.reassign' olan bir uç + microservice_execute { asUser }."],
+    ['UserCannotTransferToSelf', " Silinen kullanıcının kayıtları yine kendisine devredilemez: transferToUserId başka bir kullanıcı olmalı, ya da hiç verilmemeli (o zaman sahiplik birime düşer)."],
+    ['OrganizationStructureParentInactive', " Üst düğüm pasifken alt düğüm etkinleştirilemez: kökten yaprağa ilerleyin — önce üst birimi organization_unit_activate ile, pozisyonda ise önce birimi, sonra idari/işlevsel üst pozisyonu organization_position_activate ile açın."],
+    ['OrganizationSchemaRootCount', " Şema taslağında TEK kök birim olur: parentId'siz ikinci birim reddedilir. organization_schema_get ile kökü bulup yeni birimi onun (ya da bir altının) parentId'si ile açın."],
+    ['OrganizationSchemaCycle', " Taslakta döngü var: bir birim/pozisyon kendi atasını ebeveyn gösteriyor. organization_schema_get ile zinciri izleyin."],
+    ['OrganizationSchemaDuplicate', " Taslakta aynı kod (birim/pozisyon) ya da aynı rol slug'ı iki kez geçiyor; kodlar şema genelinde tekildir."],
+    ['OrganizationSchemaReference', " Taslakta çözülemeyen referans var: pozisyonun unitId/roleId'si ya da birimin managerPositionId'si taslakta olmayan bir düğümü gösteriyor. Önce hedefi ekleyin, sonra gösteren düğümü yazın."],
+    ['SystemEntityWriteNotAllowed', " Organizasyon ve erişim tabloları genel satır yoluyla yazılmaz (ORG-001) — platform_guide('access') §'Organizasyon ağacı'."]
+];
+function accessHint(code, message) {
+    const text = `${code ?? ''} ${message ?? ''}`;
+    const found = accessErrorHints.find(([key]) => text.includes(key));
+    return found ? found[1] : '';
+}
 const MaxErrorCauseWalk = 32;
 const MaxErrorPathShown = 6;
 const MaxErrorTextLength = 400;
@@ -262,16 +374,45 @@ 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.'}${mergeRevertHint(code)}${importHint(code, context.path)}`, status, code);
+        return new PlatformApiError(`Geçersiz istek (${location}): ${apiMessage ?? 'API gövdeyi reddetti.'}${mergeRevertHint(code)}${importHint(code, context.path)}${accessHint(code, apiMessage)}`, status, code);
     }
     if (status === 401) {
+        // Uygulama oturumu 401'i gateway kimliğinin değil uygulama kullanıcısının sorunudur; USERNAME/PASSWORD
+        // ipucu burada yanlış yere baktırırdı (g-31).
+        if (code === 'AppSessionRequiredException' || code === 'AppSessionInvalidException') {
+            return new PlatformApiError(`Uygulama oturumu ${code === 'AppSessionRequiredException' ? 'yok' : 'geçersiz ya da süresi dolmuş'} (${location}): ${apiMessage ?? ''} Kompleks proje + enforce ortamda oturumsuz her uç ve sayfa isteği 401 döner. Parolasız kullanıcı gözü için aynı çağrıyı asUserId: '<users satır id'si>' ile tekrarlayın (development/dal); oturum açılmış üye için access_session_create ile giriş yapıp tokenRefs'teki tok_… değerini asUser olarak verin.`, status, code);
+        }
+        // Yanlış e-posta/parola 2026-09-22'den beri kendi kodunu taşır (backend ADR 0004, K-3): oturum
+        // hatası değildir, yenileme ya da gateway parolası ipucu yanlış yere baktırırdı.
+        if (code === 'AppSignInFailedException') {
+            return new PlatformApiError(`Uygulama girişi reddedildi (${location}): e-posta ya da parola yanlış, ya da kullanıcı bu projenin 'users' tablosunda yok. ${apiMessage ?? ''} Yeni kompleks projede users boş gelir — platform_guide('getting-started') §'Kompleks projede ilk kullanıcı'. Hız sınırı 5 dk'da 10 denemedir; tekrar denemeden önce kimlik bilgisini doğrulayın.`, status, code);
+        }
+        if (code === 'ReauthenticationRequiredException') {
+            return new PlatformApiError(`İmza için yeniden kimlik doğrulaması reddedildi (${location}): password (verildiyse email de) görevi imzalayan kullanıcının gerçek parolası olmalı; gateway token'ı yenilemez, istek tekrarlanmadı (BPM-018).`, status, code);
+        }
         const hint = context.authMode === 'local'
             ? 'Gateway konfigürasyonundaki USERNAME/PASSWORD doğru mu kontrol edin.'
             : 'İstemciden geçirilen Authorization header süresi dolmuş olabilir; yeni token alıp MCP kaydını güncelleyin.';
         return new PlatformApiError(`Kimlik doğrulanamadı (${location}). ${hint}`, status, code);
     }
     if (status === 403) {
-        return new PlatformApiError(`Yetki yok (${location}). Token'ın sahibi bu işlem için yetkili değil.`, status, code);
+        if (code === 'PublishApprovalRequired') {
+            return new PlatformApiError(`Yayın dört göz onayı istiyor (${location}) [PublishApprovalRequired].${processHint(code, context.path)}`, status, code);
+        }
+        const runtimeHint = code === 'CsrfTokenMismatchException'
+            ? " Oturum çerezle geldi ve durum değiştiren istekte X-ZY-CSRF yok: asUser kullanın (Bearer'lı istek CSRF istemez)."
+            : code === 'AccessQueryNotScopedException'
+                ? ' Sorgu kapsamlı/korumalı bir tabloya dokunuyor: kullanıcıya özel veri için table kaynağı, tüm veriyi özetleyen rapor için sorguda isUnrestricted (ACC-005).'
+                : code === 'AccessFieldWriteDeniedException' || code === 'AccessFilterDeniedException' || code === 'AccessRevealDeniedException'
+                    ? ' Alan erişimi reddetti: access_preview fieldAccess (canWrite · canFilter); reveal için kapsamlı entity.reveal grant\'i.'
+                    : code === 'AccessOverridePermissionRequiredException'
+                        ? " Bu istek bir kullanıcı istisnasını yazıyor, genişletiyor ya da istisna taşıyan politikanın grant'lerine dokunuyor; access.override.manage izni gerekir (ACC-009)."
+                        : context.api === 'tenant' && code === 'ForbiddenException'
+                            ? ' Karar motoru reddetti; mesaj HANGİ iznin reddettiğini bilinçli olarak söylemez. Nedenini access_preview { userId, permission, resourceKey } ile sorun.'
+                            : '';
+        const forbidden = new PlatformApiError(`Yetki yok (${location}). Token'ın sahibi bu işlem için yetkili değil.${runtimeHint}${runtimeHint ? '' : accessHint(code, apiMessage)}`, status, code);
+        forbidden.apiMessage = apiMessage;
+        return forbidden;
     }
     if (status === 404) {
         const environmentHint = context.environment
@@ -280,6 +421,17 @@ 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);
         }
+        // Yalnız ConnectData kodlarının ipucu bu dala girer: Access*/Protection* kodlarıyla gelen bir 404
+        // buradan geçerse environment/import ipuçlarını ve '*_list ile doğrulayın' yönlendirmesini kaybeder (S8 incelemesi M-10).
+        const connectDataHint = code?.startsWith('ConnectData') ? accessHint(code, apiMessage) : '';
+        if (connectDataHint || (context.method === 'POST' && /\/connect-data\/[^/]+\/[^/]+\//.test(context.path))) {
+            return new PlatformApiError(`Kayıt bulunamadı (${location}): ${apiMessage ?? ''}${connectDataHint || " Bağlantı ucunda 404: uygulama/sayfa slug'ı ya da elementId yolu çözmüyor, veya yazılan satır ya da ilişki hedefi bu öznenin kapsamında değil (K-16). Kapsamdaki satırları connect_data_execute op: 'list' (aynı asUser) ile görün; ilişki hedefini op: 'lookup' ile seçin."}`, status, code);
+        }
+        // İlişki hedefi yok (o2m RelationTargetRowNotFound, m2m ManyToManyTargetRowNotFound): kayıt/environment değil,
+        // gövdedeki bir ilişki kimliği düşüyor — mesaj alanın adını taşır (38/U-6).
+        if (code && /^(RelationTargetRowNotFound|ManyToManyTargetRowNotFound)(Exception)?$/.test(code)) {
+            return new PlatformApiError(`İlişki hedefi bulunamadı (${location}): ${apiMessage ?? ''} Gövdedeki ilişki alanına yazılan kimlik hedef tabloda yok; var olan kimlikleri hedef entity'de row_list ile alın (m2m alanı tam liste bekler: ['<id>', …]). Hiçbir satır yazılmadı.`, 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) {
@@ -288,7 +440,7 @@ export function mapPlatformError(status, payload, context) {
             : '';
         const validationMessages = collectValidationMessages(body);
         const detail = validationMessages.length > 0 ? ` → ${validationMessages.join(' ; ')}` : '';
-        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);
+        const rejected = new PlatformApiError(`İş kuralı reddetti (${location}): ${apiMessage ?? 'çakışma'}${code ? ` [${code}]` : ''}${detail}${projectConflictHint}${pageSchemaHint(code, context.path)}${processHint(code, context.path)}${bulkRowHint(code)}${importHint(code, context.path)}${versionConflictHint(code, context.path)}${mergeHint(context.path)}${accessHint(code, apiMessage)}`, status, code);
         if (typeof body.rowIndex === 'number')
             rejected.rowIndex = body.rowIndex;
         return rejected;

package/dist/platform/http.js

@@ -6,6 +6,20 @@ import { randomUUID } from 'node:crypto';
 import { request } from 'undici';
 export const requestAuthStorage = new AsyncLocalStorage();
 const hiddenResponseHeaders = new Set(['set-cookie', 'authorization', 'proxy-authorization']);
+/**
+ * g-08: yürütme yanıtının varsayılan başlıkları — işin okuduğu olanlar. `total-count` sayfalı tablo
+ * akışlarının sözleşmesidir (İK koşusu M-8), `location` yönlendirmenin, `x-request-id`/`traceparent`
+ * platform günlüğünde aynı isteği bulmanın anahtarıdır. Cloudflare ve sunucu başlıkları (`cf-ray`,
+ * `server`, `alt-svc`, `date` …) ajan bağlamında yer kaplıyordu ve hiçbir karar onlara bakmıyordu.
+ */
+const essentialResponseHeaders = new Set(['content-type', 'content-length', 'content-disposition', 'location', 'total-count', 'x-request-id', 'traceparent']);
+export function headersForMode(headers, mode) {
+    if (mode === 'none')
+        return undefined;
+    if (mode === 'all')
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => essentialResponseHeaders.has(name)));
+}
 /**
  * Sayfalı tablo akışları `Total-Count` header'ına bağlı ama execute ailesi yalnız gövdeyi
  * döndürüyordu; sözleşme hiçbir tool'dan doğrulanamıyordu (İK koşusu M-8). Gizli header'lar
@@ -153,13 +167,15 @@ export class Platform {
             body = JSON.stringify(options.body);
         }
         const startedAt = Date.now();
-        logStep('istek →', `${method} ${url.href} · ${api} api${options.environment ? ` · env=${options.environment}` : ''}${options.anonymous ? ' · ANONİM (Authorization header YOK)' : ''}${isRetry ? ' · 401 sonrası tekrar' : ''}`, logsDetail() && (options.multipart || options.form || options.body !== undefined)
-            ? [`gövde: ${renderJson(options.multipart
-                    ? describeMultipart(options.multipart)
-                    : options.form
-                        ? Object.fromEntries(options.form)
-                        : options.body)}`]
-            : []);
+        logStep('istek →', `${method} ${url.href} · ${api} api${options.environment ? ` · env=${options.environment}` : ''}${options.anonymous ? ' · ANONİM (Authorization header YOK)' : ''}${isRetry ? ' · 401 sonrası tekrar' : ''}`, options.hideRequestBody === true
+            ? ['gövde: (gizli — kimlik bilgisi taşıyor, günlüğe yazılmaz)']
+            : logsDetail() && (options.multipart || options.form || options.body !== undefined)
+                ? [`gövde: ${renderJson(options.multipart
+                        ? describeMultipart(options.multipart)
+                        : options.form
+                            ? Object.fromEntries(options.form)
+                            : options.body)}`]
+                : []);
         let statusCode;
         let payload;
         let responseBytes = 0;
@@ -196,7 +212,12 @@ export class Platform {
         logStep('yanıt ←', `HTTP ${statusCode} · ${Date.now() - startedAt} ms · ${responseBytes} B`, statusCode >= 400 || logsDetail()
             ? [`gövde: ${options.expectBinary && statusCode < 400 ? `<ikili içerik · ${responseBytes} B>` : renderJson(payload)}`]
             : []);
-        if (statusCode === 401 && this.config.authMode === 'local' && !isRetry && !options.anonymous) {
+        // Çağıranın kendi Authorization'ı (asUser), imza yeniden kimlik doğrulaması ya da uygulama girişinin yanlış
+        // parolası (AppSignInFailedException, access.session.create — 2026-09-22) 401'i gateway token'ının süresiyle
+        // ilgili değildir: tekrar aynı reddi alır, üstelik parola denemesi iki kez sayılır (Faz 8 incelemesi).
+        const retriesWithFreshToken = callerHeaders.authorization === undefined
+            && !['ReauthenticationRequiredException', 'AppSignInFailedException'].includes(String(payload?.code));
+        if (statusCode === 401 && this.config.authMode === 'local' && !isRetry && !options.anonymous && retriesWithFreshToken) {
             this.tokens.invalidate();
             logStep('token ⟳', 'token reddedildi — önbellek boşaltıldı, istek yeni token ile bir kez daha denenecek');
             return this.send(api, method, path, options, raw, true);

package/dist/platform/impersonation.js

@@ -0,0 +1,45 @@
+import { PlatformApiError } from './errors.js';
+/** `NgApps.Infrastructure/Domain/HttpHeaders.cs` `ImpersonatedUserId`. */
+export const IMPERSONATED_USER_HEADER = 'impersonated-user-id';
+/**
+ * 38/M-1 — kompleks projede parolasız kullanıcı gözü. `AppSessionMiddleware` (Tenant.API, satır 76)
+ * production DIŞINDA, kimliği doğrulanmış platform isteği bu başlığı taşırsa ve istekte geçerli bir
+ * uygulama jetonu YOKSA uygulama öznesini o kullanıcı olarak kurar; `UserMiddleware` başlığı
+ * production'da Execute eyleminde düşürür. Bu yüzden:
+ *
+ * - `asUser` (uygulama jetonu) ile birlikte verilemez: jeton geçerliyse platform başlığı hiç okumaz ve
+ *   istek jetonun sahibi olarak gider — hangi kimliğin kazandığı çağırana belirsiz kalırdı.
+ * - Runtime aracında production hedefi istek gitmeden durur: başlık orada düşürülür ve istek SESSİZCE
+ *   gateway'in yönetici kimliğiyle giderdi.
+ * - Kullanıcı projede yoksa platform başlığı yine sessizce yok sayar (`userRepository.FindByIdAsync`
+ *   null) — aynı sessiz düşme; gateway kimliği bir kez okur (GET /users/{id}).
+ */
+export async function impersonationHeaders(platform, tool, project, environment, input, options) {
+    const { asUserId } = input;
+    if (asUserId === undefined)
+        return undefined;
+    if (input.asUser !== undefined) {
+        throw new PlatformApiError(`${tool}: asUserId ile asUser birlikte verilemez — asUser geçerli bir uygulama jetonuysa platform impersonated-user-id başlığını okumaz ve istek jetonun sahibi olarak gider. Parolasız kullanıcı gözü için yalnız asUserId, oturum açılmış üye için yalnız asUser verin.`, 400);
+    }
+    if (input.anonymous === true) {
+        throw new PlatformApiError(`${tool}: asUserId ile anonymous: true birlikte verilemez — biri kimliksiz isteği, diğeri belirli bir kullanıcının gözünü ister.`, 400);
+    }
+    if (input.ownAuthorization === true) {
+        throw new PlatformApiError(`${tool}: asUserId ile headers.Authorization birlikte verilemez — kendi jetonunuzla giden istekte platform başlığı değil jetonun sahibini özne yapar. Birini seçin.`, 400);
+    }
+    if (options.runtime && platform.resolveEnvironment(environment) === 'production') {
+        throw new PlatformApiError(`${tool}: asUserId production'da kullanılamaz — platform impersonated-user-id başlığını production'da düşürür ve istek sessizce gateway'in yönetici kimliğiyle giderdi. Kullanıcı gözüyle doğrulamayı development'ta (ya da bir dalda) yapın; production'da o kullanıcı olarak sınamak için access_session_create + asUser.`, 400);
+    }
+    let user;
+    try {
+        user = (await platform.tenant('GET', project, `/users/${encodeURIComponent(asUserId)}`, { environment }))?.data;
+    }
+    catch (error) {
+        if (!(error instanceof PlatformApiError) || error.status !== 404)
+            throw error;
+    }
+    if (!user) {
+        throw new PlatformApiError(`${tool}: asUserId '${asUserId}' bu projede bir kullanıcı değil — platform tanımadığı kimliği sessizce yok sayar ve istek gateway'in kimliğiyle giderdi. Kullanıcı id'sini user_list ile doğrulayın.`, 404);
+    }
+    return { [IMPERSONATED_USER_HEADER]: asUserId };
+}

package/dist/platform/jsonArray.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/*
+ * Bazı MCP istemcileri dizi parametresini JSON METNİ olarak gönderir ve bunu parametre adına göre
+ * tutarsız yapar: `page_schema_patch` aynı gövdeyi `ops` ile kabul edip `operations` ile
+ * "Expected array, received string" diye reddediyordu; `flow_create` `steps`'i kabul edip
+ * `errorSteps`'i reddediyordu (Senaryo 02 koşusu, S2-26 / TB-118). Şema tarafında metni çözersek
+ * hangi adın kullanıldığı ve istemcinin ne yaptığı önemsizleşir.
+ */
+export function jsonArray(schema) {
+    return z.preprocess(value => {
+        if (typeof value !== 'string')
+            return value;
+        const trimmed = value.trim();
+        if (!trimmed.startsWith('['))
+            return value;
+        try {
+            const parsed = JSON.parse(trimmed);
+            return Array.isArray(parsed) ? parsed : value;
+        }
+        catch {
+            return value;
+        }
+    }, schema);
+}

package/dist/platform/responses.js

@@ -1,8 +1,36 @@
 import { compactDiagnostics } from './diagnostics.js';
+import { argumentNotes } from './argumentAliases.js';
+import { tokenTtlMinutes } from './tokenVault.js';
 import { logError, logStep } from '../observability/trace.js';
 import { PlatformApiError, describeErrorBody } from './errors.js';
 import { PolicyBlockError } from '../knowledge/policy.js';
 import { maskSecrets } from './secrets.js';
+const STACK_FRAMES_KEPT = 3;
+/**
+ * Platformun hata gövdesindeki `stackTrace` yüzlerce satırdır ve çağıranın işine yarayan kısmı
+ * ilk birkaç karedir: hatayı atan servis ve satır. Tamamını taşımak uzun bir koşuda bağlamın
+ * büyük bölümünü yer (2026-09-19 senaryo koşusunda tek 404 ~4 bin token). Gateway izi ilk
+ * STACK_FRAMES_KEPT kareye indirir ve kaç karenin düştüğünü söyler; tam iz platform günlüğündedir.
+ */
+export function collapseStackTraces(value) {
+    if (Array.isArray(value))
+        return value.map(collapseStackTraces);
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === 'stackTrace' && typeof entry === 'string') {
+                const frames = entry.split('\n');
+                result[key] = frames.length <= STACK_FRAMES_KEPT
+                    ? entry
+                    : `${frames.slice(0, STACK_FRAMES_KEPT).join('\n')}\n   … (+${frames.length - STACK_FRAMES_KEPT} kare gateway tarafından kırpıldı; tam iz platform günlüğünde)`;
+                continue;
+            }
+            result[key] = collapseStackTraces(entry);
+        }
+        return result;
+    }
+    return value;
+}
 export function prune(value) {
     if (Array.isArray(value))
         return value.map(prune);
@@ -140,7 +168,7 @@ function asStructured(payload) {
     return { data: payload };
 }
 export function toolResult(payload, config, expectFailure) {
-    const pruned = prune(compactDiagnostics(payload));
+    const pruned = collapseStackTraces(prune(compactDiagnostics(payload)));
     const { payload: safe, masked, tokenRefs } = maskSecrets(pruned);
     const runtimeErrors = runtimeErrorSummary(safe);
     if (runtimeErrors.length > 0) {
@@ -162,15 +190,17 @@ export function toolResult(payload, config, expectFailure) {
         ...(runtimeErrors.length > 0 ? { runtimeErrors } : {}),
         ...(runtimeErrors.length > 0 && expectFailure === true ? { expectedFailure: true } : {}),
         ...(masked.length > 0 ? { gatewayMasked: masked } : {}),
-        ...(Object.keys(tokenRefs).length > 0 ? { tokenRefs, tokenRefNote: "Maskelenen JWT'ler gateway içinde tutuldu; bu referansları page_screenshot / page_runtime_get 'asUser' alanına verebilirsiniz (15 dk geçerli). Jetonun kendisi yanıta ve günlüğe hiç girmez." } : {}),
-        ...(truncated ? { truncated: true, truncationNote: 'Liste, yanıt boyutu sınırı nedeniyle kırpıldı; sayfalama ya da daha dar filtre kullanın.' } : {})
+        ...(Object.keys(tokenRefs).length > 0 ? { tokenRefs, tokenRefNote: `Maskelenen JWT'ler gateway içinde tutuldu; bu referansları microservice_execute / microservice_debug / page_runtime_get / page_screenshot 'asUser' alanına verebilirsiniz (${tokenTtlMinutes()} dk geçerli; kompleks projede referans access_session_create'ten gelir). Jetonun kendisi yanıta ve günlüğe hiç girmez.` } : {}),
+        ...(truncated ? { truncated: true, truncationNote: 'Liste, yanıt boyutu sınırı nedeniyle kırpıldı; sayfalama ya da daha dar filtre kullanın.' } : {}),
+        ...(argumentNotes().aliasesApplied.length > 0 ? { aliasesApplied: argumentNotes().aliasesApplied } : {}),
+        ...(argumentNotes().bodyFile ? { bodyFile: argumentNotes().bodyFile } : {})
     };
     return {
         content: [{ type: 'text', text: JSON.stringify(enriched) }],
         structuredContent: enriched
     };
 }
-export function toolError(error) {
+export function toolError(error, expectFailure) {
     logError(error);
     // Politika durdurması bilinçli bir karardır, "beklenmeyen" değil (33/S-5).
     const message = error instanceof PlatformApiError || error instanceof PolicyBlockError
@@ -178,8 +208,12 @@ export function toolError(error) {
         : error instanceof Error
             ? `Beklenmeyen gateway hatası: ${error.message}`
             : `Beklenmeyen gateway hatası: ${String(error)}`;
+    // Kasıtlı negatif testte (bayat version 409, yetkisiz kişi 403) platform hatası da bir KANITTIR:
+    // ölçüm aracı bu satırı plansız hata saymasın diye işaret taşınır.
+    const isExpectedPlatformError = expectFailure === true && (error instanceof PlatformApiError || error instanceof PolicyBlockError);
     return {
         content: [{ type: 'text', text: message }],
+        ...(isExpectedPlatformError ? { structuredContent: { expectedFailure: true } } : {}),
         isError: true
     };
 }
@@ -195,7 +229,7 @@ export function handle(config, run) {
             return toolResult(await run(args), config, expectFailure);
         }
         catch (error) {
-            return toolError(error);
+            return toolError(error, args?.expectFailure === true);
         }
     };
 }

package/dist/platform/schemaReadMemory.js

@@ -0,0 +1,60 @@
+/**
+ * Sayfa okumalarının belleği. İki soru cevaplar:
+ *
+ * - "Bu sayfa sürümü kırpık okundu mu" (ZM-28, PAGE-042): `page_schema_get(mode:'full',
+ *   allowTruncated:true)` sığmayan şemayı kırparak döndüğünde anahtar işaretlenir; aynı sürümü
+ *   `baseVersion` olarak veren `page_schema_patch` uyarı taşır — plan, düşen düğümleri görmeden
+ *   yapılmış olabilir.
+ * - "Bu gateway sayfanın hangi sürümünü en son gördü" (PAGE-043, `plans/mobil-plantcare-acigi`
+ *   g-05): `page_get`, `page_schema_get`, `page_schema_patch`'in `newVersion`'ı ve `page_update`'in
+ *   kendi yazdığı sürüm hatırlanır; `page_update` `baseVersion` verilmediğinde onu gönderir. Hiç
+ *   okunmamış sayfaya sürümsüz tam gövde yazılmaz.
+ *
+ * SÜREÇ İÇİNDEDİR ve yalnız anahtar/sürüm tutar (gövde yok); `CaptureMemory` ile aynı halka:
+ * yeniden yazılan anahtar sona gider, en eskisi düşer.
+ */
+export function schemaReadKey(project, environment, pageId, version) {
+    return `${project}/${environment}/${pageId}@${version}`;
+}
+export function pageReadKey(project, environment, pageId) {
+    return `${project}/${environment}/${pageId}`;
+}
+export class SchemaReadMemory {
+    limit;
+    truncated = new Set();
+    versions = new Map();
+    constructor(limit = 200) {
+        this.limit = limit;
+    }
+    rememberVersion(key, version) {
+        this.versions.delete(key);
+        this.versions.set(key, version);
+        while (this.versions.size > this.limit) {
+            const oldest = this.versions.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.versions.delete(oldest);
+        }
+    }
+    lastVersion(key) {
+        return this.versions.get(key);
+    }
+    markTruncated(key) {
+        this.truncated.delete(key);
+        this.truncated.add(key);
+        while (this.truncated.size > this.limit) {
+            const oldest = this.truncated.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.truncated.delete(oldest);
+        }
+    }
+    wasTruncated(key) {
+        return this.truncated.has(key);
+    }
+}
+/**
+ * SÜREÇ düzeyinde tek bellek: HTTP taşıması her POST için yeni bir gateway sunucusu kurduğundan
+ * (`sharedCaptureMemory` notu) okuma ile yazma ayrı `registerPageTools` çağrılarında koşar.
+ */
+export const sharedSchemaReadMemory = new SchemaReadMemory();

package/dist/platform/secrets.js

@@ -3,6 +3,13 @@
  * anahtarları da yakalıyordu. Günlükte zararsızdı, tool yanıtında veri kaybı olurdu.
  */
 export const secretKeyPattern = /password|passwd|secret|token|authorization|api[-_]?key|credential|connection[-_]?string/i;
+/**
+ * Sırrın DEĞERİNİ değil adını, yerini ya da türünü taşıyan anahtarlar: `credentialRef`, `tokenUrl`,
+ * `apiKeyHeader`, `secretFields`, `credentialKind`. Maskelenirlerse süreç tanımındaki
+ * `connector.credentialRef` get → update turunda `***` olarak geri yazılır ve düğüm kasayı bulamaz
+ * (BPM-017, Faz 8 incelemesi). Yalnız yanıt maskesinde uygulanır; günlük maskesi (`trace.ts`) geniş kalır.
+ */
+export const secretNameKeyPattern = /(ref|refs|url|uri|header|fields|kind|name|names|id|ids)$/i;
 import { looksLikeJwt, rememberToken } from './tokenVault.js';
 const maskedValue = '***';
 const maxPaths = 20;
@@ -16,7 +23,7 @@ function walk(value, path, masked, refs, depth) {
         const result = {};
         for (const [key, entry] of Object.entries(value)) {
             const child = path === '' ? key : `${path}.${key}`;
-            if (secretKeyPattern.test(key) && entry !== null && entry !== undefined && entry !== '') {
+            if (secretKeyPattern.test(key) && !secretNameKeyPattern.test(key) && entry !== null && entry !== undefined && entry !== '') {
                 if (masked.length < maxPaths)
                     masked.push(child);
                 // Maskelenen değer bir JWT ise kimlik testinin yolu kapanmasın: jeton kasada tutulur ve
@@ -38,3 +45,12 @@ export function maskSecrets(payload) {
     const tokenRefs = {};
     return { payload: walk(payload, '', masked, tokenRefs, 0), masked, tokenRefs };
 }
+/**
+ * Serbest METİNDEKİ kimlik parçaları (konsol satırı, hata yığını): JWT biçimli dize ve `Bearer …`.
+ * `maskSecrets` anahtar adına bakar; tarayıcı konsolu anahtarsız düz metin taşır (g-06).
+ */
+export function maskSecretText(text) {
+    return text
+        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${maskedValue}`)
+        .replace(/\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, maskedValue);
+}