@appaflytech/zeyrek-ai-mcp 0.0.28 → 0.0.30

package/dist/knowledge/connectDataBind.js

@@ -0,0 +1,819 @@
+import { connectDataShapeIssues, connectedPropKeys, selectedPaths, toWildcardPath } from './connectDataDefinition.js';
+import { deepWrapPropData } from './normalize.js';
+export const CONNECT_DATA_DEFAULT_PAGE_SIZE = 25;
+export const CONNECT_DATA_PREVIEW_LIMIT = 50;
+const PROTECTED_OPERATORS = ['eq', 'neq', 'in', 'notin'];
+const EDIT_KEYS = ['create', 'update', 'delete', 'bulk'];
+/**
+ * CD-017: anonim sayfada yazmaya açık bağlantı. Backend yazmada kimliği yalnız anonim OLMAYAN sayfada ister
+ * (`ExecuteConnectDataBehavior`): anonim sayfada oturumsuz ziyaretçi yazar — basit projede her zaman, kompleks projede
+ * politika anonim özneye izin veriyorsa.
+ */
+export function anonymousWriteFindings(isPageAnonymous, edit) {
+    const open = ['create', 'update', 'delete'].filter(key => edit?.[key] === true);
+    return isPageAnonymous && open.length
+        ? [{ ruleId: 'CD-017', severity: 'warn', message: `Sayfa anonim (isAnonymous) ve bağlantı yazmaya açık (${open.join(', ')}): oturumsuz ziyaretçi bu tabloya yazabilir — basit projede her zaman, kompleks projede politika anonim özneye izin veriyorsa. Yazma gerekmiyorsa edit'i kapatın ya da sayfayı oturumlu yapın.` }]
+        : [];
+}
+export const SAME_SOURCE_BINDING_LIMIT = 5;
+/**
+ * CD-010: sayfada aynı kaynağa 5+ bağlantı (bu bağlantı dahil) — runtime her bağlantı için ayrı okuma yapar, sayfa
+ * açılışında o kadar istek gider. Bağlanan prop sayılmaz, yerine bu çağrı bir kez sayılır (yeniden bağlama).
+ */
+export function sameSourceFindings(nodes, sourceId, element, prop) {
+    const others = [...connectedPropKeys(nodes)]
+        .filter(key => key !== `${element}.${prop}`)
+        .filter(key => {
+        const [target = '', ...path] = key.split('.');
+        const ref = readPropValue(findSchemaNode(nodes, target)?.props, path.join('.'))?.ref;
+        return ref?.source?.id === sourceId;
+    });
+    return others.length + 1 >= SAME_SOURCE_BINDING_LIMIT
+        ? [{ ruleId: 'CD-010', severity: 'warn', message: `Sayfada aynı kaynağa ${others.length + 1} bağlantı (${[...others, `${element}.${prop}`].join(', ')}): runtime her bağlantı için ayrı istek atar, sayfa açılışı o kadar okur. Aynı satırları gösteren bileşenler için alan seçimini daraltın ya da bağlantı sayısını azaltın.` }]
+        : [];
+}
+/**
+ * CD-011 uyarı dalı: tanımda lookup ayarı olan ilişki alanının hedef tablosunu bu kullanıcı okuyamıyor
+ * (`relation.targetReadable: false`) — hücre kilitli çizilir, lookup açılmaz; ayar bu kullanıcı için etkisiz.
+ */
+export function lookupReadabilityFindings(definition, describe) {
+    return (definition.fields ?? [])
+        .filter(field => field.lookup && describe.fields.find(item => item.slug === field.slug)?.relation?.targetReadable === false)
+        .map(field => ({ ruleId: 'CD-011', severity: 'warn', message: `'${field.slug}' için lookup ayarı var ama bu kullanıcı hedef tabloyu okuyamıyor (relation.targetReadable: false): hücre kilitli çizilir, lookup açılmaz. Hedef tabloya okuma izni verin ya da lookup ayarını kaldırın.` }));
+}
+/**
+ * CD-006: tanımda açık düzenleme eylemine ya da editable alana bu öznenin politikası izin vermiyorsa ayar
+ * etkisizdir — runtime 403 (`ConnectDataWriteDisabled` değil, PEP: `entity.<op>` / `AccessFieldWriteDenied`).
+ */
+export function editFindings(edit, describe) {
+    const findings = [];
+    for (const key of EDIT_KEYS) {
+        if (edit?.[key] === true && describe.write && describe.write[key] === false) {
+            findings.push({ ruleId: 'CD-006', severity: 'warn', message: `edit.${key} açık ama politika bu kullanıcıya ${key} izni vermiyor — ayar etkisiz, runtime 403 döner.` });
+        }
+    }
+    for (const slug of edit?.editable ?? []) {
+        const field = describe.fields.find(item => item.slug === slug);
+        // Politikanın gizlediği alan kabiliyetin fields'ında hiç yoktur, yalnız hidden[]'dadır: find boş döndüğü için
+        // eskiden sessizce atlanıyordu (39/M-17).
+        if (!field && (describe.hidden ?? []).includes(slug)) {
+            findings.push({ ruleId: 'CD-006', severity: 'warn', message: `'${slug}' editable ama politika bu alanı bu kullanıcıdan gizliyor (hidden) — kolon çizilmez, hücre açılmaz, yazma 403 AccessFieldWriteDenied döner.` });
+            continue;
+        }
+        if (field && field.canWrite === false && !field.isKey) {
+            findings.push({ ruleId: 'CD-006', severity: 'warn', message: `'${slug}' editable ama bu kullanıcı için canWrite yok — hücre düzenlemeye açılmaz, yazma 403 AccessFieldWriteDenied döner.` });
+        }
+    }
+    return findings;
+}
+/**
+ * 38/M-13: CD-006 ve CD-011 uyarıları kabiliyete bakar; bağlama gateway kimliğiyle (yönetici) okuduğu için ikisi
+ * hiç çıkmıyordu. `asUserId` verildiğinde aynı iki kural o kullanıcının kabiliyetiyle ikinci kez koşar; mesaj
+ * hangi gözle üretildiğini söyler (yönetici gözündeki aynı uyarıyla karışmasın).
+ */
+export function userEyeFindings(definition, describe, userId) {
+    const edit = definition.behavior?.edit;
+    return [...editFindings(edit, describe), ...lookupReadabilityFindings(definition, describe)]
+        .map(finding => ({ ...finding, message: `kullanıcı ${userId} gözüyle: ${finding.message}` }));
+}
+/** İndeksli prop yolunun kaydı: `series.1.data` → `series[].data`. */
+export function resolveConnectable(connectData, propPath) {
+    return connectData?.props?.[toWildcardPath(propPath)] ?? undefined;
+}
+const ROLE_FIELD_TYPES = {
+    any: null,
+    string: ['string'],
+    number: ['number'],
+    boolean: ['boolean'],
+    date: ['date', 'datetime'],
+    parent: ['relation', 'guid']
+};
+const SCALAR_FIELD_TYPES = ['string', 'number', 'date', 'datetime', 'time', 'boolean', 'guid'];
+/**
+ * Rolün kabul ettiği alan tipleri (CD-016 uyarısı; öneri listesinden gevşek): metin rolü her skaler değeri gösterir
+ * (anahtar `guid` dahil), ilişki/dosya nesnesini göstermez; sayı/boolean/tarih rolü kendi tipini, üst kayıt rolü
+ * anahtar tiplerini ister. `null` her tipi kabul eder.
+ */
+const ROLE_ACCEPTED_TYPES = {
+    any: null,
+    string: SCALAR_FIELD_TYPES,
+    number: ['number'],
+    boolean: ['boolean'],
+    date: ['date', 'datetime'],
+    parent: ['relation', 'guid', 'string', 'number']
+};
+/** Eşlenen kök alanın tipi rolü besleyemiyorsa `{ type, expected }`; yol (`sube.ad`) ve kaynakta olmayan alan denetlenmez. */
+export function roleTypeMismatch(roleType, slug, fields) {
+    const accepted = ROLE_ACCEPTED_TYPES[roleType ?? 'any'] ?? null;
+    const field = slug.includes('.') ? undefined : fields.find(item => item.slug === slug);
+    return accepted && field && !accepted.includes(field.type) ? { type: field.type, expected: accepted } : null;
+}
+/** Tanım filtresindeki tekil koşulların alan yolları (grup içleri dahil). */
+export function filterFieldPaths(filter) {
+    if (!filter)
+        return [];
+    if (filter.filterType === 'group')
+        return (Array.isArray(filter.children) ? filter.children : []).flatMap(child => filterFieldPaths(child));
+    return typeof filter.field === 'string' ? [filter.field] : [];
+}
+/**
+ * `fixDrift`: kökü düşen alana giden koşullar filtreden çıkar, boşalan grup düşer, kök boşalırsa `null` — tanım
+ * filtresi silinmiş alanı işaret ettikçe backend 422 verir.
+ */
+export function dropFilterPaths(filter, isDropped) {
+    if (!filter)
+        return null;
+    if (filter.filterType === 'group') {
+        const children = (Array.isArray(filter.children) ? filter.children : [])
+            .map(child => dropFilterPaths(child, isDropped))
+            .filter((child) => child !== null);
+        return children.length ? { ...filter, children } : null;
+    }
+    return typeof filter.field === 'string' && isDropped(filter.field) ? null : filter;
+}
+/** Rol türüne uyan, politikada gizli olmayan alanlar. */
+export function roleCandidates(roleType, fields) {
+    const types = ROLE_FIELD_TYPES[roleType] ?? null;
+    return fields.filter(field => field.access !== 'hidden' && (types === null || types.includes(field.type)));
+}
+const KEY_ROLES = ['value', 'key', 'id'];
+const DISPLAY_ROLES = ['label', 'name', 'title', 'text', 'category'];
+/**
+ * Rol eşleme önerisi (Studio sihirbazıyla aynı kural): rol adıyla aynı slug; `value/key/id` ←
+ * birincil anahtar (rol türü sayı/boolean/tarih değilse — grafiğin `value`'su ölçüdür, anahtar değil);
+ * `label/name/title/text/category` ← görünen alan;
+ * `parent` ← kaynağa işaret eden ilişki. Türündeki ilk kullanılmamış alana düşme YALNIZ zorunlu
+ * rollerde yapılır: dropdown'un `caption` / `isDisabled` gibi isteğe bağlı rolleri ilgisiz bir alana
+ * eşlenmez.
+ */
+export function defaultMapping(connectable, describe) {
+    const roles = {};
+    const used = new Set();
+    const visible = describe.fields.filter(field => field.access !== 'hidden');
+    const required = connectable?.required ?? [];
+    for (const [role, roleType] of Object.entries(connectable?.roles ?? {})) {
+        const candidates = roleCandidates(roleType, describe.fields);
+        const bySlug = candidates.find(field => field.slug === role);
+        const byRole = KEY_ROLES.includes(role) && !['number', 'boolean', 'date'].includes(roleType) && describe.source?.primaryKey
+            ? visible.find(field => field.slug === describe.source?.primaryKey)
+            : DISPLAY_ROLES.includes(role) && describe.source?.display
+                ? visible.find(field => field.slug === describe.source?.display)
+                : roleType === 'parent' && required.includes(role)
+                    ? candidates.find(field => field.relation?.targetEntityId === describe.source?.id)
+                    : undefined;
+        const fallback = roleType === 'parent' || !required.includes(role) ? undefined : candidates.find(field => !field.isKey && !used.has(field.slug));
+        const chosen = bySlug ?? byRole ?? fallback;
+        if (chosen) {
+            roles[role] = chosen.slug;
+            used.add(chosen.slug);
+        }
+    }
+    return roles;
+}
+/**
+ * Alan tipi → öğenin tip/biçim seçeneklerinde aranan değerler, öncelik sırasıyla (Studio
+ * `FIELD_LIST_TYPE_CANDIDATES` aynası). Bileşen kendi seçeneklerini bildirir, ilk sunulan kazanır.
+ */
+export const FIELD_LIST_TYPE_CANDIDATES = {
+    string: ['text'],
+    number: ['number'],
+    boolean: ['switch', 'boolean'],
+    date: ['date'],
+    datetime: ['datetime', 'date'],
+    time: ['time', 'text'],
+    guid: ['text'],
+    relation: ['relation', 'tag', 'text'],
+    file: ['file', 'text'],
+    enum: ['tag', 'text']
+};
+/** Motorun tek okumada döndürdüğü en çok satır (backend `page.limit` üst sınırı). */
+export const CONNECT_DATA_READ_ALL_PAGE_SIZE = 1000;
+/**
+ * Sayfalama yüzeyi olmayan bileşen (bileşen tanımında `isPaginated` yok — grafik, dropdown, kart…) tanımın ilk
+ * sayfasını değil kaynağın bütün sonucunu çizer (39/03 U-5, Studio `pageForSurface` aynası): açık `pageSize`
+ * verilmediyse sayfa boyu tek okuma tavanıdır, kayıtlı tanımın eski sayfa boyu (25) de ezilir. Sayfalanan bileşende
+ * ve tanımı bilinmeyen bileşende `undefined` — sayfa boyu girdiden ya da kayıtlı tanımdan gelir.
+ */
+export function readAllPageSize(definitionProps, requested) {
+    if (requested !== undefined)
+        return requested;
+    const props = Array.isArray(definitionProps) ? definitionProps : null;
+    return props && !props.some(prop => prop?.name === 'isPaginated') ? CONNECT_DATA_READ_ALL_PAGE_SIZE : undefined;
+}
+/** Bileşen tanımındaki liste prop'unun öğe prop'ları (`fieldsFrom` hedefi). */
+export function fieldListItemProps(definitionProps, fieldsFrom) {
+    const props = Array.isArray(definitionProps) ? definitionProps : [];
+    const target = props.find(prop => prop?.name === fieldsFrom);
+    return (Array.isArray(target?.props) ? target.props : []).filter(prop => typeof prop?.name === 'string');
+}
+const firstItemProp = (itemProps, names) => names.map(name => itemProps.find(prop => prop.name === name)).find(Boolean);
+/**
+ * Seçili yollardan liste öğeleri (Studio `fieldListFromSource` aynası): öğe şemasının bildiği adlar
+ * doldurulur — ad (`name/field/key/value`), başlık (`label/title/header`), tip (`type/format`, bileşenin
+ * sunduğu seçeneklerden), sıralanabilir, filtrelenebilir. Öğe şeması bilinmiyorsa `name/label/type`.
+ * Expand yolu (`sube.ad`) kaynak describe'ında yoksa metin kolonu olur.
+ */
+export function columnsFromDescribe(describe, paths, itemProps = [], filterable) {
+    const schema = itemProps.length > 0 ? itemProps : [{ name: 'name' }, { name: 'label' }, { name: 'type' }, { name: 'isSortable' }, { name: 'isFilterable' }];
+    return paths.map(path => {
+        const field = describe.fields.find(item => item.slug === path) ?? { slug: path, name: path, type: 'string', access: 'plain' };
+        const item = {};
+        const nameProp = firstItemProp(schema, ['name', 'field', 'key', 'value']);
+        const labelProp = firstItemProp(schema, ['label', 'title', 'header']);
+        const typeProp = firstItemProp(schema, ['type', 'format']);
+        const sortProp = firstItemProp(schema, ['isSortable', 'sortable']);
+        const filterProp = firstItemProp(schema, ['isFilterable', 'filterable']);
+        if (nameProp)
+            item[nameProp.name] = field.slug;
+        if (labelProp)
+            item[labelProp.name] = field.name || field.slug;
+        if (typeProp) {
+            const offered = (typeProp.options ?? []).map(option => String(option.value));
+            const candidates = field.enum?.length ? FIELD_LIST_TYPE_CANDIDATES.enum : FIELD_LIST_TYPE_CANDIDATES[field.type];
+            const match = (candidates ?? ['text']).find(candidate => offered.length === 0 || offered.includes(candidate));
+            if (match)
+                item[typeProp.name] = match;
+        }
+        if (sortProp && field.sortable)
+            item[sortProp.name] = true;
+        // 38/M-5: kolonun filtre düğmesi tanımın behavior.filterable'ına bağlıdır — platform listede olmayan alanın
+        // filtresini ConnectDataFilterNotAllowed ile reddeder (ConnectDataService.EnsureFilterAllowed; boş liste = hiçbiri).
+        if (filterProp && field.canFilter && (field.operators ?? []).length > 0 && (filterable === undefined || filterable.includes(field.slug)))
+            item[filterProp.name] = true;
+        return item;
+    });
+}
+/**
+ * CD-002 — filtre ağacındaki her koşulun alanı kaynağın süzülebilir alanı mı, işleci kabiliyetin
+ * listesinde mi (korumalı alanda yalnız eq/neq/in/notin). `filterable` verilirse (runtime/preview
+ * isteği) alan orada da olmalı; tanım filtresi için verilmez.
+ */
+export function filterFindings(filter, describe, filterable) {
+    const findings = [];
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (node.filterType === 'group' || Array.isArray(node.children) && !node.field) {
+            for (const child of node.children ?? [])
+                visit(child);
+            return;
+        }
+        const slug = String(node.field ?? '');
+        const field = describe.fields.find(item => item.slug === slug && item.access !== 'hidden');
+        const operators = field?.operators ?? [];
+        if (!field && slug.includes('.'))
+            return;
+        if (!field || field.canFilter === false) {
+            findings.push({ ruleId: 'CD-002', severity: 'block', message: `'${slug}' bu kaynakta süzülebilir bir alan değil${field ? '' : ' (yok ya da politikada gizli)'}.` });
+        }
+        else if (filterable && !filterable.includes(slug)) {
+            findings.push({ ruleId: 'CD-002', severity: 'block', message: `'${slug}' tanımın behavior.filterable listesinde değil; platform ConnectDataFilterNotAllowed ile reddeder. Filtrelenebilir: ${filterable.join(' · ') || '(boş)'}.` });
+        }
+        else if (node.operator && !operators.includes(node.operator)) {
+            findings.push({ ruleId: 'CD-002', severity: 'block', message: `'${slug}' için '${node.operator}' işleci izinli değil. İzinli: ${operators.join(' · ')}${field.isProtected ? ' (korumalı alan: yalnız ' + PROTECTED_OPERATORS.join('/') + ')' : ''}.` });
+        }
+    };
+    visit(filter);
+    return findings;
+}
+/**
+ * CD-002 sıralama mesajı kaynak türüne göre (38/M-7): query kaynağında da "microservice kaynağında…" yazıyordu.
+ * query/view/workflow sıralamayı hiç desteklemez (CD-013 aynı çağrıda ayrıca söyler).
+ */
+function unsortableReason(kind) {
+    if (kind === 'microservice')
+        return "microservice kaynağında uç bu alanda sıralama sunmuyor (dinamik filtre kapalı ya da alan dönüş şemasında sıralanamaz); tasarım anı 422 'connect-data-source-feature-unsupported'. Sıralanabilir bir alan seçin.";
+    if (kind === 'entity')
+        return "entity kaynağında tanım sıralaması denetlenmez ve korumalı/sıralanamaz kolonun üstünde anlamsız bir sıra üretir (kullanıcı aynı alanla sıralarsa istek 422 'ConnectDataFilterNotAllowed' alır). Sıralanabilir bir alan seçin.";
+    return `${kind} kaynağı sunucuda sıralamaz (CD-013): tanıma sort yazılmaz — platform 422 'connect-data-source-feature-unsupported' verir. Sıralamayı kaldırın; satırlar kaynağın kendi sırasıyla gelir (query'de ORDER BY), bileşen client kipte tarayıcıda sıralar.`;
+}
+/**
+ * Girdi + kabiliyet + bağlanabilir prop kaydından tanım. Block bulgusu varsa tanım yine döner
+ * (dryRun'da görülsün) ama çağıran yazmaz.
+ */
+export function buildDefinition(input, describe, connectable, connectablePaths = [], itemProps = []) {
+    const findings = [];
+    const block = (ruleId, message) => { findings.push({ ruleId, severity: 'block', message }); };
+    const warn = (ruleId, message) => { findings.push({ ruleId, severity: 'warn', message }); };
+    const visible = describe.fields.filter(field => field.access !== 'hidden');
+    const visibleSlugs = visible.map(field => field.slug);
+    const primaryKey = describe.source?.primaryKey ?? undefined;
+    const isListComponent = Boolean(connectable?.fieldsFrom);
+    if (!connectable) {
+        block('CD-001', `Bu prop veri kaynağına bağlanamaz. Bağlanabilir prop'lar: ${connectablePaths.join(' · ') || '(yok — component_get.connectData boş)'}.`);
+    }
+    const removed = new Set((describe.drift ?? []).filter(item => item.removed && item.was).map(item => String(item.was)));
+    const isDrifted = (path) => Boolean(input.fixDrift) && removed.has(path.split('.')[0] ?? path);
+    const keptSlugs = (slugs) => slugs?.filter(slug => !isDrifted(slug));
+    const roles = Object.fromEntries(Object.entries(input.roles ?? defaultMapping(connectable, describe)).filter(([, slug]) => !isDrifted(slug)));
+    for (const role of connectable?.required ?? []) {
+        if (roles[role])
+            continue;
+        const roleType = connectable?.roles?.[role] ?? 'any';
+        const candidates = roleCandidates(roleType, describe.fields).map(field => field.slug);
+        block('CD-001', `'${role}' rolü zorunlu ama eşlenemedi. Aday alanlar: ${candidates.join(', ') || '(yok)'} — roles: { ${role}: '<alan>' } verin.`);
+    }
+    for (const [role, slug] of Object.entries(roles)) {
+        if (connectable?.roles && !(role in connectable.roles))
+            block('CD-001', `'${role}' bu prop'un rolü değil. Roller: ${Object.keys(connectable.roles).join(' · ')}.`);
+        if (!visibleSlugs.includes(slug.split('.')[0] ?? slug))
+            block('CD-004', `'${role}' rolü kaynakta olmayan ya da politikada gizli '${slug}' alanına eşlenmiş.`);
+        const mismatch = roleTypeMismatch(connectable?.roles?.[role], slug, describe.fields);
+        if (mismatch)
+            warn('CD-016', `'${role}' rolü ${connectable?.roles?.[role]} bekliyor ama '${slug}' ${mismatch.type}: bileşen değeri beklediği gibi çizmeyebilir. Uyan tipler: ${mismatch.expected.join(' · ')}.`);
+    }
+    if ((describe.drift ?? []).some(item => item.idMissing)) {
+        warn('CD-008', 'Tanım alan KİMLİĞİ taşımıyor (eski bağlantı): alan yalnız adıyla bulunur, kaynakta yeniden adlandırma izlenemez ve sayfa sessizce boş kolona düşer. Bu çağrı tanımı kimliklerle yeniden yazar.');
+    }
+    const requestedFields = keptSlugs(input.fields) ?? [];
+    for (const slug of requestedFields) {
+        if (!visibleSlugs.includes(slug))
+            block('CD-004', `'${slug}' kaynakta yok ya da politikada gizli. Alanlar: ${visibleSlugs.join(' · ')}.`);
+    }
+    const referencedRoots = [...(input.fields ?? []), ...(input.edit?.editable ?? []), ...(input.filterable ?? []), ...(input.searchable ?? []), ...(input.sort ?? []).map(item => item.field), ...Object.values(input.roles ?? {}), ...Object.keys(input.expand ?? {}), ...filterFieldPaths(input.filter)]
+        .map(path => path.split('.')[0] ?? path);
+    for (const slug of [...new Set(referencedRoots)].filter(item => removed.has(item))) {
+        warn('CD-008', `'${slug}' kaynaktan silinmiş (drift)${input.fixDrift ? ' — fixDrift ile tanımdan düşürüldü (alanlar, expand, filtre koşulları, editable, filterable/searchable, sıralama ve roller)' : '; fixDrift: true ile düşürün'}.`);
+    }
+    const roleRoots = Object.values(roles).map(path => path.split('.')[0] ?? path);
+    const roots = input.fields
+        ? requestedFields.filter(slug => visibleSlugs.includes(slug))
+        : isListComponent
+            ? visible.map(field => field.slug)
+            : [...new Set([...(primaryKey && visibleSlugs.includes(primaryKey) ? [primaryKey] : []), ...roleRoots.filter(slug => visibleSlugs.includes(slug))])];
+    for (const [relation, targets] of Object.entries(input.expand ?? {})) {
+        const field = visible.find(item => item.slug === relation);
+        if (!field?.relation)
+            block('CD-004', `expand yalnız ilişki alanında: '${relation}' ilişki değil ya da yok.`);
+        if (!targets.length)
+            block('CD-004', `'${relation}' expand listesi boş.`);
+    }
+    const fieldEntries = [...roots, ...Object.keys(input.expand ?? {}).filter(slug => !roots.includes(slug) && !isDrifted(slug))].map(slug => {
+        const field = describe.fields.find(item => item.slug === slug);
+        const expand = input.expand?.[slug];
+        return {
+            ...(field?.fieldId ? { id: field.fieldId } : {}),
+            slug,
+            ...(expand?.length ? { expand: expand.map(target => ({ slug: target })) } : {})
+        };
+    });
+    const display = describe.source?.display ?? undefined;
+    const displayField = visible.find(field => field.slug === display);
+    const sort = input.sort?.filter(item => !isDrifted(item.field)) ?? (displayField?.sortable && roots.includes(displayField.slug) ? [{ field: displayField.slug, ascending: true }] : []);
+    const switches = Object.fromEntries(EDIT_KEYS.map(key => [key, input.edit?.[key] === true]));
+    const anyEdit = EDIT_KEYS.some(key => switches[key]);
+    const writableRoots = roots.filter(slug => {
+        const field = describe.fields.find(item => item.slug === slug);
+        return Boolean(field?.canWrite) && !field?.isKey && field?.type !== 'file';
+    });
+    if (EDIT_KEYS.filter(key => key !== 'bulk').some(key => switches[key]) && describe.source?.isSystem)
+        block('CD-003', `Sistem tablosu '${describe.source.slug ?? describe.source.id}' düzenlemeye açılamaz: edit anahtarlarını kapatın.`);
+    for (const finding of editFindings({ ...switches, editable: input.edit?.editable }, describe))
+        warn(finding.ruleId, finding.message);
+    // CD-018 (38/M-4): platform kaydı 422 connect-data-editable-file ile reddeder (ConnectDataService.ValidateSourcesAsync);
+    // dryRun bunu görmüyordu ve gerçek yazmada ilk kez öğreniliyordu. Dosya hücresi bağlı bileşende salt okunurdur.
+    for (const slug of (keptSlugs(input.edit?.editable) ?? []).filter(item => describe.fields.find(field => field.slug === item)?.type === 'file')) {
+        block('CD-018', `'${slug}' dosya alanı: edit.editable'a konamaz — bağlı bileşen dosyayı satır içinde yazmaz, platform kaydı 422 connect-data-editable-file ile reddeder. '${slug}'i editable'dan çıkarın; dosyayı file_upload + row_update (ya da bir microservice) yazar.`);
+    }
+    for (const slug of [...(keptSlugs(input.filterable) ?? []), ...(keptSlugs(input.searchable) ?? [])]) {
+        const field = describe.fields.find(item => item.slug === slug);
+        if (field && (field.canFilter === false || (field.operators ?? []).length === 0)) {
+            block('CD-002', `'${slug}' süzülemez (canFilter yok ya da işleç yok); filterable/searchable'a konamaz.`);
+        }
+    }
+    for (const item of sort) {
+        const field = describe.fields.find(entry => entry.slug === item.field);
+        if (field && field.sortable === false) {
+            block('CD-002', `'${item.field}' bu kaynakta sıralanamaz (sortable yok): ${unsortableReason(input.source.kind)}`);
+        }
+    }
+    for (const slug of keptSlugs(input.searchable) ?? []) {
+        const field = describe.fields.find(item => item.slug === slug);
+        if (field && field.canFilter !== false && (field.type !== 'string' || field.isProtected || !(field.operators ?? []).includes('icontains'))) {
+            block('CD-002', `'${slug}' aranamaz: arama yalnız korumasız, içerir (icontains) işleci olan metin alanında çalışır — platform bu alanı aramada YOK SAYAR (geçerli hiç alan kalmazsa 422 ConnectDataFilterNotAllowed). Aranabilir bir metin alanı seçin.`);
+        }
+    }
+    const definition = {
+        version: 1,
+        source: { kind: input.source.kind, id: input.source.id, ...(input.source.slug ?? describe.source?.slug ? { slug: input.source.slug ?? describe.source?.slug } : {}) },
+        fields: fieldEntries,
+        filter: input.fixDrift ? dropFilterPaths(input.filter, isDrifted) : input.filter ?? null,
+        sort,
+        page: { mode: input.pageMode ?? (describe.source?.pageMode === 'client' ? 'client' : 'offset'), limit: input.pageSize ?? CONNECT_DATA_DEFAULT_PAGE_SIZE },
+        language: input.language ?? 'request',
+        mapping: { roles, ...(isListComponent ? { columns: roots.map(slug => ({ field: slug })) } : {}) },
+        behavior: {
+            filterable: keptSlugs(input.filterable) ?? [],
+            searchable: keptSlugs(input.searchable) ?? [],
+            edit: {
+                ...switches,
+                saveMode: input.edit?.saveMode ?? 'row',
+                editable: keptSlugs(input.edit?.editable) ?? (anyEdit ? writableRoots : []),
+                defaults: input.edit?.defaults ?? {},
+                writeMode: input.edit?.writeMode ?? 'atomic'
+            },
+            refresh: { afterWrite: input.refresh?.afterWrite ?? 'reload', poll: input.refresh?.poll ?? null }
+        },
+        ...(input.params && Object.keys(input.params).length > 0 ? { params: input.params } : {})
+    };
+    const declaredParameters = (describe.source?.parameters ?? []).map(parameter => parameter.name);
+    for (const name of Object.keys(input.params ?? {}).filter(item => !declaredParameters.some(declared => declared.toLowerCase() === item.toLowerCase()))) {
+        block('CD-013', `params.${name}: '${describe.source?.slug ?? describe.source?.id}' böyle bir parametre almaz. Alınanlar: ${declaredParameters.join(' · ') || '(yok)'} (describe source.parameters; sayfalama, sıralama, dinamik filtre ve dil parametreleri motorundur).`);
+    }
+    if (input.pageMode && input.pageMode !== 'client' && describe.source?.pageMode === 'client') {
+        block('CD-013', `page.mode '${input.pageMode}': '${describe.source.slug ?? describe.source.id}' sunucuda sayfalamaz (describe source.pageMode client), motor offset/cursor okumaz. Tek seçenek 'client'.`);
+    }
+    if (describe.source?.pageMode === 'client') {
+        warn('CD-007', `'${describe.source.slug ?? describe.source.id}' sunucuda sayfalamaz (page.mode client): runtime satırları tek okumada (en çok 1000) alır, bileşenin süzme, arama ve sayfalaması tarayıcıda yapılır; sunucuya offset yok sayılır, 1000'den büyük sonuç eksik görünür.`);
+    }
+    if (roles.category && roles.value && !connectable?.fieldsFrom) {
+        warn('CD-015', `Rol eşlemesi bileşenin çizim ayarlarını kapsamaz: kategori ('${roles.category}') satır başına tekrar ediyorsa bileşenin 'aggregate' ayarı 'none' olduğu sürece her satır ayrı nokta çizilir — toplamak için aggregate'i (sum/avg/count) elle ayarlayın.`);
+    }
+    if (roles.children) {
+        warn('CD-009', `Ağaç (children ← '${roles.children}'): runtime tüm satırları tek istekte okur, tavan 1000; daha büyük tabloda ağaç eksik çizilir ve üstü gelmeyen satır köke düşer.`);
+    }
+    if (input.filter)
+        findings.push(...filterFindings(input.filter, describe));
+    for (const issue of connectDataShapeIssues(definition))
+        block(issue.code, `${issue.path}: ${issue.message} (${issue.rule})`);
+    const columns = isListComponent
+        ? input.columns === undefined || input.columns === 'auto'
+            ? columnsFromDescribe(describe, selectedPaths(definition).filter(path => roots.includes(path)), itemProps, definition.behavior?.filterable ?? [])
+            : input.columns
+        : null;
+    return { definition, columns, findings };
+}
+/** Tanımın filtre değerlerinde ve `params`'ında geçen `$ad` sayfa durumu adları (screen-builder `stateReferenceNames` aynası). */
+export function stateReferenceNames(definition) {
+    const names = [];
+    const add = (value) => {
+        if (typeof value === 'string' && /^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value) && !names.includes(value.slice(1)))
+            names.push(value.slice(1));
+    };
+    const walk = (filter) => {
+        if (!filter)
+            return;
+        if (filter.filterType === 'group')
+            filter.children?.forEach(walk);
+        else
+            add(filter.value);
+    };
+    walk(definition.filter);
+    Object.values(definition.params ?? {}).forEach(add);
+    return names;
+}
+/**
+ * CD-014: `$ad` sayfa ya da uygulama değişkenlerinde (page_state) yoksa runtime değeri `null` gönderir — filtre hiçbir
+ * satırı eşlemez, parametre boş gider. Değişken listesi okunamadıysa (`null`) bulgu üretilmez.
+ */
+export function stateReferenceFindings(definition, stateNames) {
+    if (!stateNames)
+        return [];
+    return stateReferenceNames(definition)
+        .filter(name => !stateNames.includes(name))
+        .map(name => ({ ruleId: 'CD-014', severity: 'warn', message: `'$${name}' sayfa/uygulama değişkenlerinde yok (page_state): runtime değeri null gönderir. variable_create ile tanımlayın ya da adı düzeltin. Tanımlılar: ${stateNames.join(' · ') || '(yok)'}.` }));
+}
+/** Önizleme isteğinin `params`'ında karşılığı olmayan `$ad` adları — platform bunları null bağlar. */
+export function unboundStateNames(definition, params) {
+    return stateReferenceNames(definition).filter(name => !Object.hasOwn(params ?? {}, name));
+}
+/**
+ * CD-014 önizleme dalı (38/M-8): runtime `$ad`'ı sayfa durumundan doldurur, `/connect-data/preview` doldurmaz —
+ * değer `request.params`'tan gelmezse null bağlanır ve parametreli query `WHERE fiyat >= NULL` ile 0 satır döner;
+ * yanıt bunu hiçbir yerde söylemiyordu. Sayfa değişkeni okunabildiyse başlangıç değeri öneri olarak yazılır.
+ */
+export function previewStateFindings(names, state) {
+    return names.map(name => {
+        const entry = state?.find(item => item.key === name);
+        const hint = entry === undefined
+            ? ''
+            : ` Sayfa/uygulama değişkeninin başlangıç değeri ${JSON.stringify(entry.value)}: request.params: { ${name}: ${JSON.stringify(entry.value)} } ile runtime'ın ilk açılışını önizlersiniz.`;
+        return { ruleId: 'CD-014', severity: 'warn', message: `'$${name}' önizleme isteğinde değersiz: runtime değeri sayfa durumundan doldurur, önizleme doldurmaz — request.params.${name} verilmezse platform null bağlar ve sonuç sessizce boş ya da eksik döner.${hint}` };
+    });
+}
+/** Prop microservice'e çevrilmişse (`{ version: 1, microserviceId }`, b-34) microservice id'si. */
+export function microserviceReferenceId(ref) {
+    const value = ref;
+    return value && typeof value === 'object' && !value.source && typeof value.microserviceId === 'string' ? value.microserviceId : null;
+}
+/**
+ * Kolon öğeleri her seviyede Prop'a sarılır (Studio `mapRawPropToSchemaProp` biçimi): `colorMap` gibi
+ * iç içe dizi/nesne değerleri de sarılır, zaten sarmal (`{ type, data }`) değerlere dokunulmaz —
+ * platform düz iç değeri JsonException ile reddeder (normalize S-001).
+ */
+export function staticListItems(items) {
+    const wrapped = structuredClone(items);
+    deepWrapPropData(wrapped);
+    return wrapped;
+}
+/**
+ * Var olan bağlantıyı yeniden bağlarken verilmeyen parçalar kayıtlı tanımdan taşınır: alanlar (liste
+ * bileşeninde kolon sırası), expand, roller, filtre, sıralama, sayfa boyu, dil, filtre/arama
+ * listeleri, düzenleme ve yenileme. Kaynak değiştiyse hiçbir şey taşınmaz. `keepColumns`: alan listesi
+ * aynı kaldı ve `columns` verilmedi — kolon listesi yeniden yazılmaz (genişlik, biçim, başlık korunur).
+ * `fixDrift` verildiyse kolonlar HER ZAMAN yeniden yazılır: alan listesi girdide hâlâ ölü alanı
+ * taşıdığı için burada "değişmedi" görünür, tanımdan düşme daha sonra (`buildDefinition`) olur ve
+ * kolon listesi dokunulmazsa bileşen silinmiş alanın kolonunu çizmeye devam ederdi (koşu bulgusu S-7).
+ */
+export function inputFromExisting(input, existing) {
+    if (!existing?.source || existing.source.id !== input.source.id)
+        return { input, keepColumns: false };
+    const existingFields = (existing.mapping?.columns?.length
+        ? existing.mapping.columns.map(column => String(column.field ?? ''))
+        : (existing.fields ?? []).map(field => field.slug)).filter(slug => slug && !slug.includes('.'));
+    const existingExpand = Object.fromEntries((existing.fields ?? [])
+        .filter(field => field.expand?.length)
+        .map(field => [field.slug, (field.expand ?? []).map(item => item.slug)]));
+    const edit = existing.behavior?.edit;
+    const existingEdit = edit
+        ? {
+            create: edit.create ?? false,
+            update: edit.update ?? false,
+            delete: edit.delete ?? false,
+            bulk: edit.bulk ?? false,
+            ...(edit.saveMode === 'row' || edit.saveMode === 'cell' || edit.saveMode === 'batch' ? { saveMode: edit.saveMode } : {}),
+            editable: [...(edit.editable ?? [])],
+            defaults: { ...(edit.defaults ?? {}) },
+            ...(edit.writeMode ? { writeMode: edit.writeMode } : {})
+        }
+        : undefined;
+    const merged = {
+        ...input,
+        fields: input.fields ?? existingFields,
+        expand: input.expand ?? (Object.keys(existingExpand).length > 0 ? existingExpand : undefined),
+        roles: input.roles ?? (Object.keys(existing.mapping?.roles ?? {}).length > 0 ? { ...(existing.mapping?.roles ?? {}) } : undefined),
+        filter: input.filter !== undefined ? input.filter : existing.filter ?? null,
+        sort: input.sort ?? (existing.sort ?? []).map(item => ({ field: item.field, ascending: item.ascending })),
+        pageSize: input.pageSize ?? existing.page?.limit,
+        params: input.params ?? (existing.params && Object.keys(existing.params).length > 0 ? { ...existing.params } : undefined),
+        language: input.language ?? existing.language ?? undefined,
+        filterable: input.filterable ?? [...(existing.behavior?.filterable ?? [])],
+        searchable: input.searchable ?? [...(existing.behavior?.searchable ?? [])],
+        edit: input.edit ? { ...existingEdit, ...input.edit } : existingEdit,
+        refresh: input.refresh ?? (existing.behavior?.refresh
+            ? {
+                ...(existing.behavior.refresh.afterWrite === 'reload' || existing.behavior.refresh.afterWrite === 'merge' ? { afterWrite: existing.behavior.refresh.afterWrite } : {}),
+                poll: existing.behavior.refresh.poll ?? null
+            }
+            : undefined)
+    };
+    const keepColumns = input.columns === undefined && !input.fixDrift && JSON.stringify(merged.fields) === JSON.stringify(existingFields) && JSON.stringify(merged.expand ?? {}) === JSON.stringify(existingExpand);
+    return { input: merged, keepColumns };
+}
+/** Describe'ın bildirdiği yeniden adlandırmalar (kayıtlı yol → güncel yol); silinen alan girmez. */
+export function renamesFromDrift(drift) {
+    return Object.fromEntries((drift ?? [])
+        .filter(item => !item.removed && item.was && item.now && item.was !== item.now)
+        .map(item => [String(item.was), String(item.now)]));
+}
+export function invertRenames(renames) {
+    return Object.fromEntries(Object.entries(renames).map(([recorded, current]) => [current, recorded]));
+}
+/** Yolun yeni adı: tam eşleşme, sonra en uzun yeniden adlanmış önek (backend `RenamePath`, screen-builder `renamePath` aynası). */
+export function renamePath(path, renames) {
+    const has = (key) => Object.prototype.hasOwnProperty.call(renames, key);
+    if (!path || Object.keys(renames).length === 0)
+        return path;
+    if (has(path))
+        return renames[path];
+    for (let cut = path.lastIndexOf('.'); cut > 0; cut = path.lastIndexOf('.', cut - 1)) {
+        if (has(path.slice(0, cut)))
+            return renames[path.slice(0, cut)] + path.slice(cut);
+    }
+    return path;
+}
+/**
+ * Tanımdaki bütün alan yollarını yeniden adlandırır (backend `WithRenamedPaths` aynası): alan/expand slug'ları, filtre,
+ * sıralama, roller, kolon eşlemesi, filterable/searchable, editable ve varsayılan anahtarları; lookup hedefe göredir, kalır.
+ * Kaynakta yeniden adlanan alan tanımda `id` ile eşleşir: bağlama güncel adlarla kurulur, kayıtlı adlarla yazılır.
+ */
+export function renameDefinitionPaths(definition, renames) {
+    if (Object.keys(renames).length === 0)
+        return definition;
+    const rename = (path) => renamePath(path, renames);
+    const renameFields = (fields, prefix) => fields?.map(field => {
+        if (!field?.slug)
+            return field;
+        const path = prefix === null ? field.slug : `${prefix}.${field.slug}`;
+        const expand = renameFields(field.expand, path);
+        return { ...field, slug: rename(path).split('.').pop() ?? field.slug, ...(expand ? { expand } : {}) };
+    });
+    const renameFilter = (filter) => !filter
+        ? filter
+        : { ...filter, ...(typeof filter.field === 'string' ? { field: rename(filter.field) } : {}), ...(filter.children ? { children: filter.children.map(child => renameFilter(child)) } : {}) };
+    const edit = definition.behavior?.edit;
+    return {
+        ...definition,
+        fields: renameFields(definition.fields, null) ?? [],
+        ...(definition.filter !== undefined ? { filter: renameFilter(definition.filter) } : {}),
+        ...(definition.sort ? { sort: definition.sort.map(item => ({ ...item, field: rename(item.field) })) } : {}),
+        ...(definition.mapping
+            ? {
+                mapping: {
+                    ...definition.mapping,
+                    ...(definition.mapping.roles ? { roles: Object.fromEntries(Object.entries(definition.mapping.roles).map(([role, path]) => [role, rename(path)])) } : {}),
+                    ...(definition.mapping.columns ? { columns: definition.mapping.columns.map(column => (typeof column.field === 'string' ? { ...column, field: rename(column.field) } : column)) } : {})
+                }
+            }
+            : {}),
+        ...(definition.behavior
+            ? {
+                behavior: {
+                    ...definition.behavior,
+                    ...(definition.behavior.filterable ? { filterable: definition.behavior.filterable.map(rename) } : {}),
+                    ...(definition.behavior.searchable ? { searchable: definition.behavior.searchable.map(rename) } : {}),
+                    ...(edit
+                        ? {
+                            edit: {
+                                ...edit,
+                                ...(edit.editable ? { editable: edit.editable.map(rename) } : {}),
+                                ...(edit.defaults ? { defaults: Object.fromEntries(Object.entries(edit.defaults).map(([path, value]) => [rename(path), value])) } : {})
+                            }
+                        }
+                        : {})
+                }
+            }
+            : {})
+    };
+}
+/**
+ * Yeniden bağlamada kurulan tanıma kayıtlı tanımın alan ayrıntıları taşınır: aynı slug'lı alanın kimliği, `lookup`
+ * ayarı ve expand alt alanlarının kimlikleri (girdi bunları taşımaz; taşınmazsa lookup ayarı sessizce kaybolurdu).
+ */
+export function carryFieldDetails(definition, previous) {
+    if (!previous)
+        return definition;
+    return {
+        ...definition,
+        fields: definition.fields.map(field => {
+            const saved = (previous.fields ?? []).find(item => item.slug === field.slug);
+            if (!saved)
+                return field;
+            return {
+                ...(field.id ?? saved.id ? { id: field.id ?? saved.id } : {}),
+                ...field,
+                ...(field.expand ? { expand: field.expand.map(child => (child.id || !saved.expand?.find(item => item.slug === child.slug)?.id ? child : { id: saved.expand.find(item => item.slug === child.slug)?.id, ...child })) } : {}),
+                ...(!field.lookup && saved.lookup ? { lookup: saved.lookup } : {})
+            };
+        })
+    };
+}
+/** Expand alt alanlarına, tanımla alınan describe'ın bildirdiği hedef alan kimliklerini yazar (`sube.ad` → fieldId). */
+export function stampExpandIds(definition, describe) {
+    const stamp = (fields, prefix) => fields?.map(child => {
+        const path = `${prefix}.${child.slug}`;
+        const fieldId = describe.fields.find(item => item.slug === path)?.fieldId;
+        const expand = stamp(child.expand, path);
+        return { ...(child.id || !fieldId ? {} : { id: fieldId }), ...child, ...(expand ? { expand } : {}) };
+    });
+    return { ...definition, fields: definition.fields.map(field => (field.expand ? { ...field, expand: stamp(field.expand, field.slug) } : field)) };
+}
+/** Kabiliyetin alanları tanımın KAYITLI adlarıyla (describe drift'i): kayıtlı adla yazılmış filtre ve satırlar bununla denetlenir. */
+export function capabilityUnderRecordedNames(describe) {
+    const recorded = invertRenames(renamesFromDrift(describe.drift));
+    return Object.keys(recorded).length === 0 ? describe : { ...describe, fields: describe.fields.map(field => ({ ...field, slug: renamePath(field.slug, recorded) })) };
+}
+/** Bind girdisindeki yolları (alanlar, roller, expand, filtre, sıralama, filterable/searchable, edit) yeniden adlandırır. */
+export function renameBindInput(input, renames) {
+    if (Object.keys(renames).length === 0)
+        return input;
+    const rename = (path) => renamePath(path, renames);
+    const renameFilter = (filter) => ({
+        ...filter,
+        ...(typeof filter.field === 'string' ? { field: rename(filter.field) } : {}),
+        ...(Array.isArray(filter.children) ? { children: filter.children.map(renameFilter) } : {})
+    });
+    return {
+        ...input,
+        ...(input.fields ? { fields: input.fields.map(rename) } : {}),
+        ...(input.roles ? { roles: Object.fromEntries(Object.entries(input.roles).map(([role, path]) => [role, rename(path)])) } : {}),
+        ...(input.expand ? { expand: Object.fromEntries(Object.entries(input.expand).map(([field, targets]) => [rename(field), targets])) } : {}),
+        ...(input.filter ? { filter: renameFilter(input.filter) } : {}),
+        ...(input.sort ? { sort: input.sort.map(item => ({ ...item, field: rename(item.field) })) } : {}),
+        ...(input.filterable ? { filterable: input.filterable.map(rename) } : {}),
+        ...(input.searchable ? { searchable: input.searchable.map(rename) } : {}),
+        ...(input.edit
+            ? {
+                edit: {
+                    ...input.edit,
+                    ...(input.edit.editable ? { editable: input.edit.editable.map(rename) } : {}),
+                    ...(input.edit.defaults ? { defaults: Object.fromEntries(Object.entries(input.edit.defaults).map(([path, value]) => [rename(path), value])) } : {})
+                }
+            }
+            : {})
+    };
+}
+/** Üretilen kolonların alan adı prop'larını (name/field/key/value) yeniden adlandırır: kolonlar sayfanın gördüğü kayıtlı adla yazılır. */
+export function renameColumnItems(columns, renames) {
+    return columns?.map(item => Object.fromEntries(Object.entries(item).map(([key, value]) => [key, ['name', 'field', 'key', 'value'].includes(key) && typeof value === 'string' ? renamePath(value, renames) : value]))) ?? null;
+}
+/**
+ * Kayıtlı kolon listesini yeni seçimle birleştirir (screen-builder `mergeSchemaFieldList` aynası): seçili kalan alanın
+ * kolonu yerinde ve ayarlarıyla durur, seçimden çıkan kaynak alanının kolonu düşer, kaynakta olmayan kolon kalır,
+ * yeni alanlar sona eklenir. Kayıtlı liste yoksa üretilen döner.
+ */
+export function mergeColumnItems(saved, generated, sourceNames) {
+    const savedItems = saved?.data;
+    if (!Array.isArray(savedItems))
+        return generated;
+    const items = staticListItems(savedItems);
+    const nameOf = (item) => {
+        const key = ['name', 'field', 'key', 'value'].find(name => typeof item?.[name]?.data === 'string');
+        return key ? String((item?.[key]).data) : undefined;
+    };
+    const wanted = generated.map(nameOf);
+    const kept = items.filter(item => {
+        const name = nameOf(item);
+        return name === undefined || wanted.includes(name) || !sourceNames.includes(name);
+    });
+    const keptNames = kept.map(nameOf);
+    return [...kept, ...generated.filter(item => !keptNames.includes(nameOf(item)))];
+}
+/**
+ * Pano/seçenek listesi olan bileşende (kanban `columns`) rolün enum değerlerinden kolonlar: bağlanan
+ * prop'tan BAŞKA, `value` ve `label` isteyen bağlanabilir prop hedeftir; öğe anahtarları o prop'un
+ * kendi rollerinden gelir (`value`/`label`/`color`). Kaynağın enum'u yoksa ya da böyle bir prop yoksa
+ * hiçbir şey yazılmaz — bileşenin örnek kolonları kalır ve kartlar hiçbir kolona düşmez (koşu bulgusu S-3).
+ */
+export function enumOptionItems(connectData, propPath, definition, describe) {
+    const target = Object.entries(connectData?.props ?? {}).find(([path, entry]) => path !== propPath && (entry.required ?? []).includes('value') && (entry.required ?? []).includes('label'));
+    if (!target)
+        return undefined;
+    const roles = definition.mapping?.roles ?? {};
+    const slug = roles.column ?? Object.values(roles).find(field => (describe.fields.find(item => item.slug === field)?.enum ?? []).length > 0);
+    const values = describe.fields.find(item => item.slug === slug)?.enum ?? [];
+    if (values.length === 0)
+        return undefined;
+    const keys = Object.keys(target[1].roles ?? {});
+    return {
+        prop: target[0],
+        items: values.map(value => ({
+            ...(keys.includes('value') ? { value: value.value } : {}),
+            ...(keys.includes('label') ? { label: value.label || value.value } : {}),
+            ...(keys.includes('color') && value.color ? { color: value.color } : {})
+        }))
+    };
+}
+/**
+ * Pano kolonu seçenekleri yeniden bağlamada kayıtlı listeyle birleşir (M-6): sıra ve küme enum değerlerinden gelir
+ * (kaynaktan silinen değer düşer, yenisi eklenir); aynı `value`'lu kayıtlı öğenin öbür alanları (elle girilmiş
+ * `wipLimit`, başlık, renk) korunur. Kayıtlı liste yoksa üretilen liste olduğu gibi (sarmallı) döner.
+ */
+export function mergeOptionItems(saved, items) {
+    const savedItems = (Array.isArray(saved?.data) ? saved.data : [])
+        .filter((item) => Boolean(item) && typeof item === 'object' && !Array.isArray(item));
+    const valueOf = (value) => (value && typeof value === 'object' && !Array.isArray(value) && 'data' in value ? value.data : value);
+    return staticListItems(items).map((wrapped, index) => {
+        const previous = savedItems.find(item => String(valueOf(item.value)) === String(items[index]?.value));
+        if (!previous)
+            return wrapped;
+        const { value: _value, ...kept } = previous;
+        return { ...wrapped, ...staticListItems([kept])[0] };
+    });
+}
+/**
+ * Tek batch: bağla (`set_connect_data`), liste bileşeninde öğe listesini, `fields` kaydı olan
+ * bileşende kardeş alan adı prop'larını yaz. Sıra önemlidir: bağlama önce. `merge` verilirse kolon listesi kayıtlı
+ * listeyle birleştirilir (aynı kaynağa yeniden bağlama: sıra ve kolon ayarları korunur).
+ */
+export function bindOps(target, propPath, definition, connectable, columns, includeColumns = true, merge, options) {
+    const ops = [{ op: 'set_connect_data', target, path: propPath, ref: definition }];
+    if (connectable?.fieldsFrom && columns && includeColumns) {
+        ops.push({ op: 'replace_prop', target, prop: connectable.fieldsFrom, value: merge ? mergeColumnItems(merge.saved, staticListItems(columns), merge.sourceNames) : staticListItems(columns) });
+    }
+    if (options)
+        ops.push({ op: 'replace_prop', target, prop: options.prop, value: staticListItems(options.items) });
+    for (const [role, prop] of Object.entries(connectable?.fields ?? {})) {
+        const field = definition.mapping?.roles?.[role];
+        if (field)
+            ops.push({ op: 'replace_prop', target, prop, value: field });
+    }
+    return ops;
+}
+/** Şema ağacında elementId ile düğüm. */
+export function findSchemaNode(nodes, elementId) {
+    for (const node of nodes ?? []) {
+        if (node.elementId === elementId)
+            return node;
+        const found = findSchemaNode(Array.isArray(node.children) ? node.children : [], elementId);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Prop yolundaki değer: sarmal (`{ type, data }`) ara adımlarda `data`'sından geçilir, dizi öğesi
+ * (anahtarları sarmal düz nesne) olduğu gibi okunur — `series.1.data`'nın son `data`'sı öğenin prop'udur.
+ */
+export function readPropValue(props, propPath) {
+    let current = props;
+    for (const [index, segment] of propPath.split('.').entries()) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        const holder = index > 0 && typeof current.type === 'string' ? current.data : current;
+        if (holder === null || typeof holder !== 'object')
+            return undefined;
+        current = Array.isArray(holder) ? holder[Number(segment)] : holder[segment];
+    }
+    return current && typeof current === 'object' ? current : undefined;
+}