@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/knowledge/normalize.js

@@ -0,0 +1,1309 @@
+import { logStep } from '../observability/trace.js';
+const SORT_DEFAULT = { name: 'sortField', type: 'sortType', source: 'query-string' };
+const LIMIT_DEFAULT = { name: 'limit', offset: 'offset', source: 'query-string' };
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asObjects(value) {
+    return asArray(value).filter((entry) => Boolean(entry) && typeof entry === 'object');
+}
+function fillJoinPaths(rootEntityId, parentJoins, chain, aliasChains, fixes) {
+    for (const join of asObjects(parentJoins)) {
+        const alias = String(join.alias ?? '');
+        const relationFieldId = String(join.fieldId ?? '');
+        if (!relationFieldId)
+            continue;
+        const nextChain = [...chain, relationFieldId];
+        if (!join.path) {
+            join.path = [rootEntityId, ...nextChain].join('.');
+            fixes.push(`joins['${alias}'].path dolduruldu`);
+        }
+        if (alias)
+            aliasChains.set(alias, nextChain.join('.'));
+        fillJoinPaths(rootEntityId, join.joins, nextChain, aliasChains, fixes);
+    }
+}
+function fillSelectionPaths(parameters, aliasChains, fixes) {
+    for (const key of ['selectFields', 'returnFields', 'filters']) {
+        for (const entry of asObjects(parameters[key])) {
+            const expected = aliasChains.get(String(entry.alias ?? ''));
+            if (expected === undefined || entry.path)
+                continue;
+            entry.path = expected;
+            fixes.push(`${key}['${entry.alias}'.${entry.fieldSlug ?? entry.fieldId}].path dolduruldu`);
+        }
+    }
+}
+function collectJoinAliases(joins, into) {
+    for (const join of asObjects(joins)) {
+        const alias = String(join.alias ?? '');
+        if (alias)
+            into.add(alias);
+        collectJoinAliases(join.joins, into);
+    }
+    return into;
+}
+/**
+ * Kök tablo alias'ı JOIN'in SOL tarafını üretir: `PostgreSqlRelationHandler.HandleJoin`
+ * `ProcessJoinTree(entity, alias, joins)` çağrısında gelen alias'ı doğrudan
+ * `$"{currentAlias}.{relationField.Slug}"` olarak SqlKata'ya verir. Alias boşsa SQL'e `.role_id`
+ * gider, SqlKata onu `""."role_id"` diye tırnaklar ve Postgres **42601 zero-length delimited
+ * identifier** ile reddeder (crm koşumu B-2). Hiçbir yerde varsayılan atanmaz: `Microservice.cs:671`
+ * yalnız ŞEMA üretiminde `Entity.Slug`'a düşer, runtime yolu düşmez. Join'siz adımda hata çıkmaz —
+ * bu yüzden yalnız join varken doldurulur.
+ *
+ * Alias gövdeden türetilebilir: kök alanlar `path` taşımaz ve join alias'ı DEĞİLDİR; kalan tek
+ * alias entity slug'ıdır. Türetilemiyorsa dokunmayız, MS-013/WF-019 block'u devralır.
+ */
+function fillRootAlias(table, fixes) {
+    if (asObjects(table.joins).length === 0)
+        return;
+    if (String(table.alias ?? '').trim() !== '')
+        return;
+    const joinAliases = collectJoinAliases(table.joins, new Set());
+    const candidates = new Set();
+    for (const key of ['selectFields', 'returnFields', 'fields', 'filters']) {
+        for (const entry of asObjects(table[key])) {
+            const alias = String(entry.alias ?? '').trim();
+            if (!alias || joinAliases.has(alias))
+                continue;
+            if (String(entry.path ?? '').trim() !== '')
+                continue;
+            candidates.add(alias);
+        }
+    }
+    if (candidates.size !== 1)
+        return;
+    const [alias] = [...candidates];
+    table.alias = alias;
+    fixes.push(`kök alias '${alias}' olarak dolduruldu — join'li table'da kök alias boşsa SQL'e '.<alan>' gider ve Postgres 42601 (zero-length delimited identifier) döner`);
+}
+/**
+ * Platform sort/limit'i null bırakır ve path'i türetmez; Studio ikisini de guard'sız okur.
+ * Eksik olanları doldurur, dolu olanlara DOKUNMAZ (yanlış değerleri MS-007 block'u yakalar).
+ */
+export function normalizeTableParameters(parameters, fallbackEntityId) {
+    if (!parameters || typeof parameters !== 'object')
+        return [];
+    const table = parameters;
+    const rootEntityId = String(table.entityId ?? fallbackEntityId ?? '');
+    const fixes = [];
+    if (!table.sort) {
+        table.sort = { ...SORT_DEFAULT };
+        fixes.push('sort varsayılanı eklendi');
+    }
+    if (!table.limit) {
+        table.limit = { ...LIMIT_DEFAULT };
+        fixes.push('limit varsayılanı eklendi');
+    }
+    fillRootAlias(table, fixes);
+    if (rootEntityId) {
+        const aliasChains = new Map();
+        fillJoinPaths(rootEntityId, table.joins, [], aliasChains, fixes);
+        fillSelectionPaths(table, aliasChains, fixes);
+    }
+    return fixes;
+}
+export function normalizeMicroserviceDefinition(definition) {
+    if (definition.source !== 'table')
+        return [];
+    return normalizeTableParameters(definition.sourceParameters, definition.entityId);
+}
+export function withNormalization(payload, fixes) {
+    if (fixes.length > 0) {
+        logStep('düzeltme', `gateway ${fixes.length} otomatik düzeltme uyguladı — gövdeye istek gönderilmeden ÖNCE işlendi, yanıta gatewayNormalized olarak eklenir`, fixes);
+    }
+    if (fixes.length === 0 || !payload || typeof payload !== 'object')
+        return payload;
+    return { ...payload, gatewayNormalized: fixes };
+}
+/**
+ * Studio kenarı branch ADIYLA çizer (workflow.helpers.ts:90-110), condition tutamağını
+ * items[].branchId GUID'iyle. İkisi ancak branch.name = branch.id iken eşleşir; ad farklıysa
+ * runtime çalışır ama Studio'da koşul dalları kopuk görünür (klinik K-010). Tamamen
+ * türetilebilir olduğu için lint değil normalizasyon; kalan uyuşmazlığı WF-014 yakalar.
+ */
+function normalizeConditionBranches(step) {
+    const referenced = new Set(asObjects(step.rule?.items).map(item => String(item.branchId ?? '')));
+    const renamed = [];
+    for (const branch of asObjects(step.branches)) {
+        const branchId = String(branch.id ?? '');
+        if (!branchId || !referenced.has(branchId) || branch.name === branchId)
+            continue;
+        renamed.push(`${branch.name ?? '?'} → ${branchId}`);
+        branch.name = branchId;
+    }
+    return renamed;
+}
+const BEHAVIOR_VALUES = new Set(['primitive', 'object', 'array']);
+/**
+ * `CreateWorkflowCommandValidator`: `When(ReturnDtoId.HasValue) → RuleFor(ReturnBehavior).NotEmpty()`
+ * (aynısı ParameterDtoId/ParameterBehavior için). DtoId verip Behavior'ı atlamak
+ * "'Return Behavior' must not be empty" ile ilk denemeyi kırar (crm koşumu B-5) — üstelik
+ * `ngapps://examples/middleware-authenticate` ve rehberin asgari iskeleti alanı göstermiyordu.
+ * Değer tamamen türetilebilir olmadığı için varsayılanı 'object' seçip yanıtta bildiriyoruz:
+ * DTO primitive ise `WorkflowService:445` WrongDtoBehaviorException ile net konuşur, dizi
+ * dönen akışlarda 'array' elle verilir.
+ */
+function fillDtoBehaviors(definition, fixes) {
+    const pairs = [['returnDtoId', 'returnBehavior'], ['parameterDtoId', 'parameterBehavior']];
+    for (const [dtoKey, behaviorKey] of pairs) {
+        const dtoId = definition[dtoKey];
+        const behavior = definition[behaviorKey];
+        if (typeof dtoId !== 'string' || dtoId.trim() === '')
+            continue;
+        if (typeof behavior === 'string' && BEHAVIOR_VALUES.has(behavior))
+            continue;
+        if (behavior !== undefined && behavior !== null && behavior !== '')
+            continue;
+        definition[behaviorKey] = 'object';
+        fixes.push(`${behaviorKey}: 'object' yazıldı — ${dtoKey} verilen gövdede zorunludur (validator: '${behaviorKey} must not be empty'). Akış DİZİ dönüyorsa 'array', DTO primitive ise 'primitive' verin`);
+    }
+}
+export function normalizeWorkflowDefinition(definition) {
+    const fixes = [];
+    const bodies = [definition, definition.automation];
+    fillDtoBehaviors(definition, fixes);
+    for (const body of bodies) {
+        if (!body || typeof body !== 'object')
+            continue;
+        for (const step of asObjects(body.steps)) {
+            const label = String(step.name ?? step.id ?? '?');
+            if (step.type === 'table') {
+                const applied = normalizeTableParameters(step.rule);
+                if (applied.length > 0)
+                    fixes.push(`'${label}': ${applied.join(', ')}`);
+            }
+            if (step.type === 'condition') {
+                const renamed = normalizeConditionBranches(step);
+                if (renamed.length > 0) {
+                    fixes.push(`'${label}': condition branch adları id'leriyle eşitlendi (${renamed.join(', ')}) — Studio kenarları branch adıyla çizer`);
+                }
+            }
+        }
+    }
+    return fixes;
+}
+/**
+ * Sayfa akışında microservice adımının sonucu `machine.setStorage(task.name, …)` ile yazılır ve
+ * sarmalı `isRaw` belirler: false → `{ data, headers, error }`, aksi hâlde ham `response.data`
+ * (microservice.ts:81-90). Studio akışı her okuduğunda isRaw'ı false'a çekip storage ref'lerine
+ * '.data' eklediği (event-actions.mappers.ts:142-181) için tek kararlı bileşim isRaw=false +
+ * '<adım adı>.data'dır; verilmemiş isRaw'ı buna eşitliyoruz ki editörde bir kez açılan akış
+ * sessizce başka bir şeye dönüşmesin. Kalan tutarsızlığı FLOW-009 yakalar.
+ */
+export function normalizeFlowSteps(steps) {
+    const fixes = [];
+    for (const step of asObjects(steps)) {
+        if (step.type !== 'microservice')
+            continue;
+        const args = (step.args ?? {});
+        if (args.isRaw === null || args.isRaw === undefined) {
+            args.isRaw = false;
+            step.args = args;
+            fixes.push(`'${String(step.stepId ?? step.name ?? '?')}': args.isRaw=false yazıldı — storage { data, headers, error } sarmalıdır, setter ref'i '<adım adı>.data' olmalı`);
+        }
+    }
+    return fixes;
+}
+const DEFAULT_STATES = { isSticky: false, isDroppable: false, isScrollable: false, isWrapper: false };
+const REQUIRED_COLLECTIONS = ['events', 'validations', 'stateBindings', 'children'];
+/**
+ * Komponent gövdesinde eksik bırakılan alanlar platformda NullReferenceException 500 üretir:
+ *
+ * - `states`: DesignComponentManagementSchema.ToDomain:47 `States.IsSticky`'yi guard'sız okur;
+ *   Appearance'ın satır 24'te varsayılanı var, States'in yok.
+ * - `events` / `validations` / `stateBindings`: yalnız **micro-op yolunda** zorunlu.
+ *   `page_create` (POST /pages) bunlarsız 200 döner, `PATCH …/schema` NRE verir; canlı deneyde
+ *   üçü birlikte verilince geçti, her biri tek başına verilince patladı (klinik H-005 eki).
+ *
+ * Hiçbiri `page_schema_validate` tarafından yakalanmaz (ValidatePageSchemaQuery ToDomain'e
+ * girmez) — doğrulayıcı "valid" der, yazma patlar. Tamamen türetilebilir olduğu için lint
+ * değil normalizasyon.
+ */
+const PROP_VALUE_TYPES = new Set(['static', 'file', 'flow', 'widget', 'element', 'page', 'code']);
+function isPropShaped(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && PROP_VALUE_TYPES.has(String(value.type));
+}
+function wrapPropDictionaryValues(dictionary) {
+    let wrapped = false;
+    for (const key of Object.keys(dictionary)) {
+        const value = dictionary[key];
+        if (isPropShaped(value)) {
+            wrapped = deepWrapPropData(value.data) || wrapped;
+            continue;
+        }
+        const prop = { type: 'static', ref: null, data: value };
+        dictionary[key] = prop;
+        deepWrapPropData(prop.data);
+        wrapped = true;
+    }
+    return wrapped;
+}
+/**
+ * Platform, bir Prop'un data'sı JSON nesne/diziyse içini HER SEVİYEDE Dictionary<string, Prop>
+ * olarak çözer (DesignComponentManagementSchema.CreateProp) — düz bırakılan iç değer
+ * JsonException verir (kutuphane turu H5: header.navigation icon'u). Dolu ve doğru şekle
+ * dokunulmaz; yalnız Prop olmayan iç değerler static Prop'a sarılır.
+ */
+export function deepWrapPropData(data) {
+    if (Array.isArray(data)) {
+        let wrapped = false;
+        for (const item of data) {
+            if (isPropShaped(item)) {
+                wrapped = deepWrapPropData(item.data) || wrapped;
+            }
+            else if (item && typeof item === 'object') {
+                wrapped = wrapPropDictionaryValues(item) || wrapped;
+            }
+        }
+        return wrapped;
+    }
+    if (data && typeof data === 'object') {
+        return wrapPropDictionaryValues(data);
+    }
+    return false;
+}
+/**
+ * `props` sözlüğünün DEĞERLERİ de Prop'tur (`Dictionary<string, Prop>`); sarmalsız bırakılan bir
+ * prop hata bile vermez, **sessizce boş kaydedilir**: `"style": { "color": "#f00" }` gövdesinde
+ * Newtonsoft `Prop`'un hiçbir alanına denk gelmeyen `color`'ı atar, Type varsayılana (`static`)
+ * düşer, Data null kalır — canlı klinikte `style` prop'u `{"type":"static"}` olarak kaydedildi
+ * (S-001). Primitive bırakılırsa (`"content": "merhaba"`) bu kez deserialize aşamasında 500 gelir.
+ * İkisi de tamamen türetilebilir olduğu için lint değil normalizasyon; Studio'nun
+ * `mapRawPropToSchemaProp`'u (screen-builder/mappers.ts:131) tel üzerinde aynı sarmalı kuruyor.
+ */
+function wrapNodeProps(props) {
+    const wrapped = [];
+    const deepened = [];
+    for (const [name, value] of Object.entries(props)) {
+        if (value === null || value === undefined)
+            continue;
+        if (isPropShaped(value)) {
+            if (deepWrapPropData(value.data))
+                deepened.push(name);
+            continue;
+        }
+        const prop = { type: 'static', ref: null, data: value };
+        props[name] = prop;
+        deepWrapPropData(prop.data);
+        wrapped.push(name);
+    }
+    return { wrapped, deepened };
+}
+/**
+ * Validation gövdesi ÜÇ farklı biçimde dolaşıyordu ve ikisi bozuktu (crm koşumu B-9):
+ *
+ * - `{ name, value, message }` (eski altın örnek) → `ValidationModel.Name` **JsonIgnore**'dur,
+ *   `Type` enum varsayılanına (`Regex`) düşer: alan sessizce regex doğrulamasına dönüşür.
+ * - `{ type: 'maxLength' }` → backend eski enum üyesiyle (`OldMaxLength`) kabul eder ve geri
+ *   okur, ama RUNTIME doğrulayıcı yalnız tireli adları tanır
+ *   (`ng-apps-flow/src/tasks/validation/validation.ts:74` switch → default: return true):
+ *   doğrulama hiç koşmaz. Bu yüzden eski adları kanonik karşılığına çeviriyoruz.
+ * - `message` boş bırakılan validation kullanıcıya hiçbir şey söylemez; doküman 23'te sayfayı
+ *   okunamaz bırakan gövde de buydu. Türetilemez → normalizasyon değil, PAGE-016 block'u.
+ */
+const VALIDATION_CANONICAL_TYPES = ['regex', 'email', 'required', 'max-length', 'min-length', 'max-value', 'min-value', 'value-options'];
+const VALIDATION_TYPE_ALIASES = new Map([
+    ...VALIDATION_CANONICAL_TYPES.map(type => [type.replace(/-/g, ''), type]),
+    ['pattern', 'regex'],
+    ['min', 'min-value'],
+    ['max', 'max-value']
+]);
+const VALIDATION_VALUE_REQUIRED = new Set(['regex', 'max-length', 'min-length', 'max-value', 'min-value', 'value-options']);
+function canonicalValidationType(value) {
+    const key = String(value ?? '').trim().toLowerCase().replace(/[-_\s]/g, '');
+    return key === '' ? undefined : VALIDATION_TYPE_ALIASES.get(key);
+}
+export function normalizeValidationList(validations, label, fixes) {
+    for (const validation of asObjects(validations)) {
+        const declared = validation.type ?? validation.name;
+        const canonical = canonicalValidationType(declared);
+        const name = `${label}.${String(declared ?? '?')}`;
+        if (canonical) {
+            if (validation.type !== canonical) {
+                fixes.push(validation.type === undefined
+                    ? `${name}: 'name' anahtarı 'type: ${canonical}' olarak yazıldı — Name alanı JsonIgnore'dur, type verilmezse validation sessizce regex'e düşer`
+                    : `${name}: validation tipi '${canonical}' olarak yazıldı — runtime doğrulayıcı yalnız tireli adı tanır, eskisi sessizce hiçbir şey doğrulamaz`);
+                validation.type = canonical;
+            }
+            delete validation.name;
+        }
+        if (typeof validation.isActive !== 'boolean') {
+            validation.isActive = true;
+            fixes.push(`${name}: isActive=true yazıldı`);
+        }
+        if (canonical === 'required' && (validation.value === undefined || validation.value === null)) {
+            validation.value = true;
+            fixes.push(`${name}: value=true yazıldı (required)`);
+        }
+    }
+}
+/**
+ * Normalizasyondan SONRA kalan, türetilemeyen eksikler: tanınmayan tip (sessizce regex'e düşer)
+ * ve boş mesaj (kullanıcı neyin yanlış olduğunu göremez). Değer isteyen tiplerde eksik `value`'yu
+ * platform `missing-validation-value` ile yakalıyor, biz de yazmadan önce söylüyoruz.
+ */
+export function validationErrors(validations, label) {
+    const errors = [];
+    for (const validation of asObjects(validations)) {
+        const declared = validation.type ?? validation.name;
+        const canonical = canonicalValidationType(declared);
+        const name = `${label}.${String(declared ?? '?')}`;
+        if (!canonical) {
+            errors.push(`${name}: geçersiz validation tipi — geçerliler: ${VALIDATION_CANONICAL_TYPES.join(' · ')}. Tip verilmeyen ya da tanınmayan validation platformda sessizce 'regex'e düşer.`);
+            continue;
+        }
+        if (typeof validation.message !== 'string' || validation.message.trim() === '') {
+            errors.push(`${name}: 'message' zorunlu — mesajsız validation kullanıcıya hiçbir şey söylemez ve eksik alanlı validation gövdesi sayfayı okunamaz bırakabilir (doküman 23 §B-2).`);
+        }
+        if (VALIDATION_VALUE_REQUIRED.has(canonical) && (validation.value === undefined || validation.value === null || validation.value === '')) {
+            errors.push(`${name}: '${canonical}' tipi 'value' ister (uzunluk/sınır/regex deseni); platform bunu 'missing-validation-value' ile reddeder.`);
+        }
+    }
+    return errors;
+}
+/**
+ * add_component ağacındaki ve set_validations op'larındaki validation gövdelerini birlikte
+ * denetler; page_schema_patch/validate yolunda PAGE-016 mesajını buradan üretiyoruz.
+ */
+export function schemaOpValidationErrors(ops) {
+    const errors = [];
+    const walkNodes = (nodes) => {
+        for (const node of asObjects(nodes)) {
+            errors.push(...validationErrors(node.validations, String(node.elementId ?? node.name ?? node.type ?? '?')));
+            walkNodes(node.children);
+        }
+    };
+    for (const op of asObjects(ops)) {
+        if (op.op === 'set_validations') {
+            errors.push(...validationErrors(op.validations, String(op.target ?? '?')));
+            continue;
+        }
+        if (op.op === 'add_component' && op.component)
+            walkNodes([op.component]);
+    }
+    return errors;
+}
+export function normalizeComponentDefaults(nodes) {
+    const fixed = [];
+    for (const node of asObjects(nodes)) {
+        const missing = [];
+        if (!node.states || typeof node.states !== 'object') {
+            node.states = { ...DEFAULT_STATES };
+            missing.push('states');
+        }
+        for (const key of REQUIRED_COLLECTIONS) {
+            if (Array.isArray(node[key]))
+                continue;
+            node[key] = [];
+            missing.push(key);
+        }
+        if (node.props && typeof node.props === 'object' && !Array.isArray(node.props)) {
+            const { wrapped, deepened } = wrapNodeProps(node.props);
+            if (wrapped.length > 0)
+                missing.push(`prop'lar Prop sarmalına alındı: ${wrapped.join('+')}`);
+            if (deepened.length > 0)
+                missing.push(`iç değerler Prop'a sarıldı: ${deepened.join('+')}`);
+        }
+        normalizeValidationList(node.validations, 'validations', missing);
+        if (missing.length > 0) {
+            fixed.push(`${String(node.elementId ?? node.name ?? node.type ?? '?')} (${missing.join(', ')})`);
+        }
+        fixed.push(...normalizeComponentDefaults(node.children));
+    }
+    return fixed;
+}
+/**
+ * add_component micro-op'unun taşıdığı komponent ağacı da aynı ToDomain yolundan geçer.
+ */
+/**
+ * `replace_prop` micro-op'u Prop DEĞİL ham değer alır: PageSchemaMicroOpApplier.cs:77
+ * `new Prop(PropValueType.Static) { Data = op.Value }` kurar (ifade verilmişse Code). Prop sarmalı
+ * gönderildiğinde sarmalın kendisi `Data`'ya yazılır ve platform onu `Dictionary<string, Prop>`
+ * olarak çözmeye çalışıp **500 JsonException** verir ("could not be converted to Prop. Path: $.type").
+ * add_component'te sarmal ZORUNLU olduğu için bu tuzağa düşmek çok kolay; şekil tamamen
+ * türetilebilir olduğundan lint değil normalizasyon: static sarmalını açıyor, code sarmalını
+ * op'un `expression` alanına taşıyoruz. Diğer prop tipleri (page/file/flow/widget/element) bu
+ * op'la ifade EDİLEMEZ — onlar için PAGE-006 uyarısı üretilir.
+ *
+ * DIŞ sarmalın olmaması İÇ sarmalın da olmaması demek değil: applier'ın kurduğu Prop yine
+ * `ToDomain` → `CreateProp` yolundan geçer ve `Data`'nın içi HER SEVİYEDE
+ * `Dictionary<string, Prop>` olarak çözülür. Klinikte iki biçim de 500 verdi (S-001):
+ * ham `{"backgroundColor":"#f8fafc"}` → `Path: $.backgroundColor`, dış sarmallı
+ * `{"type":"static","data":{"color":"#111827"}}` → `Path: $.color`. Geçen tek biçim,
+ * Studio'nun `mapRawPropToSchemaProp` çıktısının aynısı: dış sarmal YOK, her yaprak sarılı.
+ */
+function normalizeReplacePropValue(op) {
+    const value = op.value;
+    const label = `'${String(op.target ?? '?')}.${String(op.prop ?? '?')}'`;
+    if (!isPropShaped(value)) {
+        if (!deepWrapPropData(value))
+            return [];
+        return [`${label}: value'nun iç değerleri Prop'a sarıldı — op ham değer alır ama platform Data'nın içini her seviyede Dictionary<string, Prop> olarak çözer, sarımsız iç değer 500 JsonException verir`];
+    }
+    const propType = String(value.type);
+    if (propType === 'static') {
+        const data = value.data;
+        op.value = data;
+        const notes = [`${label}: replace_prop value'su Prop sarmalından çıkarıldı — bu op ham değer alır, sarmal gönderilirse platform 500 JsonException verir`];
+        if (deepWrapPropData(data))
+            notes.push(`${label}: value'nun iç değerleri Prop'a sarıldı`);
+        return notes;
+    }
+    if (propType === 'code') {
+        const expression = value.data ?? value.ref;
+        delete op.value;
+        op.expression = expression;
+        return [`${label}: replace_prop code prop'u 'expression' alanına taşındı — kod prop'u value ile değil expression ile verilir`];
+    }
+    return [];
+}
+export function normalizeSchemaOps(ops) {
+    const components = [];
+    const props = [];
+    const validations = [];
+    for (const op of asObjects(ops)) {
+        if (op.op === 'replace_prop') {
+            props.push(...normalizeReplacePropValue(op));
+            continue;
+        }
+        if (op.op === 'set_validations') {
+            normalizeValidationList(op.validations, `'${String(op.target ?? '?')}'`, validations);
+            continue;
+        }
+        if (op.op !== 'add_component' || !op.component)
+            continue;
+        components.push(...normalizeComponentDefaults([op.component]));
+    }
+    return { components, props, validations };
+}
+export function validationNote(fixed) {
+    return fixed.length === 0 ? [] : [`validation gövdeleri düzeltildi (${fixed.join(' · ')})`];
+}
+export function replacePropNote(fixed) {
+    return fixed.length === 0 ? [] : [`replace_prop değerleri düzeltildi (${fixed.join(' · ')})`];
+}
+export const PAGE_CONTAINER_ELEMENT_ID = 'page_container';
+/**
+ * Platformun kendi açtığı sayfalarda (CreatePageWhenApplicationCreatedEventHandler) şemanın kökünde
+ * her zaman bir `page_container` bulunur; Studio komponentleri onun children'ına koyar ve sayfa
+ * düzeyi olayları (page load) ona bağlar. page_create ile açılan sayfa boş şemayla geldiği için
+ * ajan komponentleri köke serpiyor — kapsayıcı dışında kalıyorlar. Şekil qm/klinik'teki gerçek
+ * kayıttan alındı.
+ *
+ * Düzen prop'ları da kurulur (2026-08-25): `ContainerComponent` şemasının `layout` varsayılanı
+ * `grid` → `flex` oldu ve Studio bırakma yolu katalogdaki `definition.defaults`'u düğümün
+ * props'una YAZAR (`ScreenBuilderDroppable.svelte`); sayfa kökünü kuran öbür üreticiler de aynı seti
+ * yazar (Studio `DEFAULT_CONTAINER_LAYOUT_PROPS`, studio-api `generatePageContainer`, platform
+ * `CreatePageWhenApplicationCreatedEventHandler` + `SeedData`). Renderer varsayılanı
+ * BİLMEZ — `isFlexLayout` yalnız düğümün kendi prop'una bakar — bu yüzden gateway'in kurduğu
+ * kapsayıcı da seti açıkça taşır; yoksa Studio'dan açılan sayfa flex, MCP'den açılan ızgara olurdu.
+ */
+export function pageContainerNode() {
+    return {
+        elementId: PAGE_CONTAINER_ELEMENT_ID,
+        kind: 'component',
+        name: PAGE_CONTAINER_ELEMENT_ID,
+        type: 'container',
+        props: {
+            title: { type: 'static', data: '' },
+            layout: { type: 'static', data: 'flex' },
+            direction: { type: 'static', data: 'row' },
+            horizontalAlign: { type: 'static', data: 'left' },
+            verticalAlign: { type: 'static', data: 'top' },
+            size: { type: 'static', data: 'shrink' },
+            gap: { type: 'static', data: 'medium' }
+        },
+        blocks: [{ breakpoint: 1024, size: { h: 24, w: 12 }, position: { x: 0, y: 0 } }],
+        states: { isSticky: false, isDroppable: true, isScrollable: true, isWrapper: true },
+        appearance: { heightType: 'auto', isHidden: false, marginValue: 0, marginType: 'none', paddingType: 'none', paddingValue: 0 },
+        events: [],
+        validations: [],
+        stateBindings: [],
+        children: []
+    };
+}
+/**
+ * `modal` ve `drawer` bu kuralın istisnasıdır: qm'in gerçek kayıtlarında (`[SY] Profil bilgilerim`)
+ * katmanlar `page_container`'ın İÇİNDE değil, şemanın kökünde onun kardeşi olarak durur. Kapsayıcıya
+ * çekilirlerse sayfa içeriğinin akışına girer ve katman olarak açılmazlar.
+ */
+const ROOT_LAYER_TYPES = new Set(['modal', 'drawer']);
+export function ensurePageContainer(schema) {
+    const nodes = asObjects(schema);
+    if (nodes.some(node => node.elementId === PAGE_CONTAINER_ELEMENT_ID))
+        return { schema: nodes, fixes: [] };
+    const container = pageContainerNode();
+    const layers = nodes.filter(node => ROOT_LAYER_TYPES.has(String(node.type ?? '')));
+    container.children = nodes.filter(node => !ROOT_LAYER_TYPES.has(String(node.type ?? '')));
+    const moved = container.children.length;
+    return {
+        schema: [container, ...layers],
+        fixes: [`şemaya '${PAGE_CONTAINER_ELEMENT_ID}' kapsayıcısı eklendi${moved > 0 ? ` ve verdiğiniz ${moved} komponent onun içine alındı` : ''}${layers.length > 0 ? `; ${layers.length} katman (modal/drawer) kökte kapsayıcının kardeşi olarak bırakıldı` : ''}: sayfa komponentleri köke değil bu kapsayıcıya konur, sayfa düzeyi olaylar (page load) da ona bağlanır`]
+    };
+}
+/**
+ * Komponent kataloğunda varsayılan `size`'ı kendi `maxSize`'ını aşan kayıtlar var (`textinput`
+ * default `h:8` / `maxSize.h:5` — P-07 taramasında 19 komponent, NgApps.UI ARC-013). Ajan
+ * `component_get`'teki varsayılanı kopyaladığında doğrulayıcı "Height of 'x' must be between 1
+ * and 5." ile reddediyor; form sayfaları baştan input başına bir hataya düşüyor. Şekil tamamen
+ * türetilebilir olduğu için lint değil normalizasyon: aşan değeri katalogdaki sınıra çekiyoruz.
+ */
+export function clampBlockSizes(nodes, maxSizes) {
+    const clamped = [];
+    for (const node of asObjects(nodes)) {
+        const limit = maxSizes.get(String(node.type ?? ''));
+        for (const block of limit ? asObjects(node.blocks) : []) {
+            const size = block.size;
+            if (!size || typeof size !== 'object')
+                continue;
+            for (const axis of ['w', 'h']) {
+                const value = size[axis];
+                const max = limit?.[axis];
+                if (typeof value !== 'number' || typeof max !== 'number' || value <= max)
+                    continue;
+                size[axis] = max;
+                clamped.push(`${String(node.elementId ?? node.type)} ${axis}:${value}→${max}`);
+            }
+        }
+        clamped.push(...clampBlockSizes(node.children, maxSizes));
+    }
+    return clamped;
+}
+/**
+ * Gövdede `appearance` verilmediğinde platform yüksekliği **fixed**'e sabitler:
+ * `DesignComponentManagementSchema.cs:24` alanı `new(ComponentHeightType.Fixed, …)` ile
+ * başlatır (`ComponentHeightType.Fixed = 0`), yani "alan yok" = "sabit yükseklik". Studio'nun
+ * kendi bırakma yolu bunu ASLA yapmaz: katalogdaki `isDefaultAutoHeight`e bakıp
+ * `heightType: isDefaultAutoHeight ? 'auto' : 'fixed'` yazar
+ * (`ScreenBuilderDroppable.svelte:701`, `store-converter.ts:233`). Katalogda varsayılan
+ * `true`'dur (`ZeyrekComponent.ts:62`); `false` diyen yalnız sekiz tip var — auth-layout, html,
+ * image, layout, qrcode, table, text-editor, video.
+ *
+ * Fark tuvalde görünür ve yıkıcıdır: `fixed` bir düğüm tam `size.h * 10px` çizilir ve
+ * `.draggable__item-component { overflow: hidden }` taşan içeriği KESER
+ * (`DraggableItem.svelte`). `auto` düğümde yükseklik içerikten gelir, ResizeObserver ölçtüğünü
+ * `shrinkOrExpand` ile `blocks[].size.h`e geri yazar ve kardeşleri iter. Yani MCP hattında
+ * ajanın tahmin ettiği `h` bir üst SINIRA dönüşüyor, kartların içi kırpılmış görünüyordu
+ * (ürün sahibi ekran görüntüsü, 2026-08-19: randevu sayfasında üç kartın da içi kesik).
+ *
+ * Ajanın açıkça verdiği `appearance.heightType` korunur; katalogda bulunmayan tip auto sayılır —
+ * platformun kendi varsayılanı odur ve `fixed` tahmininin bedeli kırpma, `auto` tahmininin
+ * bedeli yalnız fazladan yükseklik.
+ */
+export function normalizeHeightTypes(nodes, autoHeights) {
+    const stamped = [];
+    for (const node of asObjects(nodes)) {
+        const appearance = (node.appearance && typeof node.appearance === 'object' && !Array.isArray(node.appearance)
+            ? node.appearance
+            : {});
+        if (appearance.heightType !== 'auto' && appearance.heightType !== 'fixed') {
+            const heightType = autoHeights.get(String(node.type ?? '')) === false ? 'fixed' : 'auto';
+            appearance.heightType = heightType;
+            node.appearance = appearance;
+            stamped.push(`${String(node.elementId ?? node.name ?? node.type ?? '?')}: ${heightType}`);
+        }
+        stamped.push(...normalizeHeightTypes(node.children, autoHeights));
+    }
+    return stamped;
+}
+/**
+ * Kalabalık şemada düğüm başına satır yazmak notu okunmaz kılıyor; asıl bilgi KAÇ düğüme
+ * dokunulduğu ve hangilerinin `fixed` kaldığıdır — kırpma riski yalnız onlarda var.
+ */
+export function heightTypeNote(stamped) {
+    if (stamped.length === 0)
+        return [];
+    const fixed = stamped.filter(entry => entry.endsWith(': fixed')).map(entry => entry.replace(': fixed', ''));
+    const detail = stamped.length > 6
+        ? `${stamped.length} düğüm${fixed.length > 0 ? `; katalog gereği fixed kalan: ${fixed.join(', ')}` : ''}`
+        : stamped.join(', ');
+    return [`appearance.heightType yazıldı (${detail}): platform boş bırakılan appearance'ı 'fixed'e sabitliyor, Studio ise katalogdaki isDefaultAutoHeight'a bakıyor. 'fixed' düğüm tuvalde tam size.h*10px çizilip taşan içeriği kırptığı için katalog varsayılanı gövdeye açıkça yazıldı; bilerek sınırlamak istediğin düğüme appearance.heightType:'fixed' ver`];
+}
+const GRID_COLUMNS = 12;
+const DESKTOP_BREAKPOINT = 1024;
+const DEFAULT_RECT = { x: 0, y: 0, w: 12, h: 6 };
+const MAX_GRID_ROWS = 2000;
+function coordinate(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function desktopBlock(node) {
+    return asObjects(node.blocks).find(block => Number(block.breakpoint) === DESKTOP_BREAKPOINT);
+}
+function rectOf(block) {
+    const position = (block?.position ?? {});
+    const size = (block?.size ?? {});
+    return {
+        x: coordinate(position.x, DEFAULT_RECT.x),
+        y: coordinate(position.y, DEFAULT_RECT.y),
+        w: coordinate(size.w, DEFAULT_RECT.w),
+        h: coordinate(size.h, DEFAULT_RECT.h)
+    };
+}
+function occupancy(items, ignoredElementId) {
+    const rows = Math.min(MAX_GRID_ROWS, Math.max(...items.map(item => item.rect.y + item.rect.h), 1));
+    const matrix = Array.from({ length: rows }, () => new Array(GRID_COLUMNS).fill(undefined));
+    for (const item of items) {
+        if (item.elementId === ignoredElementId)
+            continue;
+        const width = Math.min(GRID_COLUMNS, item.rect.w);
+        const lastColumn = Math.min(GRID_COLUMNS, item.rect.x + width);
+        for (let row = Math.max(0, item.rect.y); row < item.rect.y + item.rect.h; row++) {
+            const cells = matrix[row];
+            if (!cells)
+                continue;
+            for (let column = Math.max(0, item.rect.x); column < lastColumn; column++) {
+                cells[column] = item.elementId;
+            }
+        }
+    }
+    return matrix;
+}
+function overlappingIds(matrix, active) {
+    const width = Math.min(GRID_COLUMNS, active.rect.w);
+    const found = new Set();
+    for (const cells of matrix.slice(Math.max(0, active.rect.y), active.rect.y + active.rect.h)) {
+        for (const elementId of cells.slice(Math.max(0, active.rect.x), active.rect.x + width)) {
+            if (elementId && elementId !== active.elementId)
+                found.add(elementId);
+        }
+    }
+    return [...found];
+}
+/**
+ * `findSiblingsForMove` birebir portu (ng-apps-screen-builder/draggable.element.ts): aktif
+ * komponentin kapladığı hücreleri işgal eden kardeşler onun ALTINA taşınır, taşınan kardeşin
+ * kendi çakışmaları da aynı mesafeyle zincirleme itilir. `visited` zincirin aynı komponente iki
+ * kez girmesini engeller; `nestedDifference`/`distance` üst seviyede ölçülen kaymayı korur ki
+ * yığın açılırken kardeşler arası boşluk büyümesin.
+ */
+function pushOverlappingDown(items, active, visited, nestedDifference = 0) {
+    const data = items.map(item => ({ elementId: item.elementId, rect: { ...item.rect } }));
+    const overlapping = overlappingIds(occupancy(data, active.elementId), active)
+        .map(elementId => data.find(item => item.elementId === elementId))
+        .filter((item) => item !== undefined)
+        .sort((left, right) => left.rect.y - right.rect.y);
+    const moved = [];
+    const bottom = active.rect.y + active.rect.h;
+    let previousElementId = active.elementId;
+    let distance = 0;
+    for (const item of overlapping) {
+        const wasVisited = visited.has(item.elementId);
+        const previousY = item.rect.y;
+        visited.add(item.elementId);
+        if (bottom === previousY)
+            continue;
+        item.rect.y = distance !== 0
+            ? previousY + distance
+            : nestedDifference !== 0
+                ? previousY + nestedDifference
+                : bottom;
+        distance = item.rect.y - previousY;
+        moved.push(item);
+        if (wasVisited)
+            continue;
+        moved.push(...pushOverlappingDown(data.filter(entry => entry.elementId !== previousElementId), item, visited, nestedDifference !== 0 ? nestedDifference : distance));
+        previousElementId = item.elementId;
+    }
+    return moved;
+}
+/**
+ * `moveItem` portu: aktif komponent kendi yerinde kalır (`updateItem` sonda onu geri yazar), yalnız
+ * itilen kardeşlerin ilk sonucu uygulanır — aynı kardeş zincirin farklı dallarından birden çok kez
+ * dönebilir ve ilki geçerlidir.
+ */
+function moveActive(items, active) {
+    const moved = pushOverlappingDown(items, active, new Set());
+    if (moved.length === 0)
+        return items;
+    return items.map(item => (item.elementId === active.elementId
+        ? item
+        : moved.find(entry => entry.elementId === item.elementId) ?? item));
+}
+function reorderSiblings(nodes) {
+    const laidOut = nodes
+        .map((node, index) => ({ node, elementId: typeof node.elementId === 'string' && node.elementId !== '' ? node.elementId : `#${index}` }))
+        .filter(entry => !ROOT_LAYER_TYPES.has(String(entry.node.type ?? '')));
+    if (laidOut.length < 2)
+        return 0;
+    let items = laidOut.map(entry => ({ elementId: entry.elementId, rect: rectOf(desktopBlock(entry.node)) }));
+    for (const entry of laidOut) {
+        const active = items.find(item => item.elementId === entry.elementId);
+        if (active)
+            items = moveActive(items, active);
+    }
+    let moved = 0;
+    for (const [index, entry] of laidOut.entries()) {
+        const item = items[index];
+        const block = desktopBlock(entry.node);
+        const rect = rectOf(block);
+        if (!item || item.rect.y === rect.y)
+            continue;
+        moved++;
+        if (block) {
+            block.position = { x: rect.x, y: item.rect.y };
+            continue;
+        }
+        entry.node.blocks = [...asObjects(entry.node.blocks), {
+                breakpoint: DESKTOP_BREAKPOINT,
+                position: { x: rect.x, y: item.rect.y },
+                size: { w: rect.w, h: rect.h }
+            }];
+    }
+    return moved;
+}
+function reorderPass(nodes) {
+    const siblings = asObjects(nodes);
+    let moved = reorderSiblings(siblings);
+    for (const node of siblings) {
+        moved += reorderPass(node.children);
+    }
+    return moved;
+}
+function collectLayout(nodes, collected) {
+    for (const node of asObjects(nodes)) {
+        const block = desktopBlock(node);
+        collected.push({
+            node,
+            label: String(node.elementId ?? node.name ?? node.type ?? '?'),
+            y: rectOf(block).y,
+            hasBlock: block !== undefined
+        });
+        collectLayout(node.children, collected);
+    }
+}
+/**
+ * Bir geçiş her zaman yetmez: doluluk matrisinde bir hücreyi son yazan komponent öncekini gizler
+ * (`createMatrixFromItemsIgnore`), o yüzden aynı hücrede üçten fazla komponent varken ilk geçiş
+ * çakışmanın bir kısmını görmez. Studio'da bu durum hiç oluşmaz — orada her seferinde TEK komponent
+ * bırakılır — komple şema yazarken oluşur; geçiş kendini yineleyerek sabit noktaya iner. Her geçiş
+ * yalnız aşağı ittiği için tur sayısı sonludur, üst sınır patolojik gövdeye karşı emniyet kemeri.
+ */
+const MAX_REORDER_PASSES = 8;
+/**
+ * Studio'da komponent tuvale bırakıldığında ızgara çakışmasını studio-api'nin sayfa kurma servisi
+ * çözer: `SchemaHelper.mergeComponents` yeni komponenti kardeşlerine ekleyip `reorderComponents` →
+ * `draggableElement.moveItem` ile çakışan kardeşleri aşağı iter (NgApps.UI
+ * `apps/studio-api/src/domain/page/shared/page-schema.helper.ts:28`). Gateway o servisten geçmez —
+ * `page_create`/`page_update` şemayı POST/PUT ile KOMPLE yazar (`page_build` tool'u yok) — bu yüzden
+ * ajanın verdiği koordinatlar olduğu gibi kayda giriyor ve aynı hücreleri isteyen komponentler
+ * Studio tuvalinde üst üste biniyor. Burada aynı algoritma şemanın TAMAMINA uygulanır: en dıştaki
+ * kök dizi ve her `children` dizisi kendi ızgarası olarak ele alınır, o dizideki her komponent
+ * sırayla "bırakılan komponent" kabul edilir ve hücrelerini paylaşan kardeşleri altına iter. Dizinin
+ * kendi sırası ve komponentlerin x/genişlik/yükseklik değerleri değişmez, yalnız desktop block'unun
+ * `position.y` değeri kayar. Tam aynı hücreleri isteyen komponentlerden hangisinin üstte kalacağını
+ * Studio'nun bırakma mantığı belirler (sonra "bırakılan" kendi yerini alır), yani dizi sırası görsel
+ * sıraya birebir çevrilmez — garanti edilen şey çakışmasız ızgara. Çakışma yoksa hiçbir şeye
+ * dokunulmaz (idempotent). Kök seviyesindeki modal/drawer katmanları sayfa akışında durmadığı için
+ * dışarıda bırakılır (bkz. ROOT_LAYER_TYPES).
+ */
+export function reorderSchemaBlocks(nodes) {
+    const before = [];
+    collectLayout(nodes, before);
+    for (let pass = 0; pass < MAX_REORDER_PASSES && reorderPass(nodes) > 0; pass++)
+        continue;
+    return before
+        .filter(entry => rectOf(desktopBlock(entry.node)).y !== entry.y)
+        .map(entry => `${entry.label} y:${entry.y}→${rectOf(desktopBlock(entry.node)).y}${entry.hasBlock ? '' : " (desktop block'u yazıldı)"}`);
+}
+export function reorderNote(moved) {
+    if (moved.length === 0)
+        return [];
+    return [`çakışan komponentler ızgarada aşağı kaydırıldı (${moved.join(', ')}): Studio komponenti tuvale bırakırken bu itmeyi kendi yapar, şema komple yazıldığında o yol çalışmaz ve komponentler tuvalde üst üste binerdi`];
+}
+/**
+ * Studio HER kayıtta `page_container` konumunu (0,0)'a sıfırlar (NgApps.UI `page.mappers.ts`
+ * `mapPageSchemaRaw:44-49`); gateway o mapper'dan geçmediği için ajanın verdiği konum aynen kayda
+ * giriyordu. Layout'lu sayfada sayfa şeması slot'un İÇİNE enjekte edildiğinden (`mapPageLayoutToPreview`)
+ * y≠0 kapsayıcı, slot içinde aşağı kayar ve üstte y×10px boş bant çizilir — "üstte kocaman boşluk,
+ * içerik scroll'da" semptomunun S-1 üreticisi (21 §1). %100 türetilebilir olduğu için lint değil
+ * normalizasyon.
+ */
+export function resetPageContainerPosition(schema) {
+    const container = asObjects(schema).find(node => node.elementId === PAGE_CONTAINER_ELEMENT_ID);
+    if (!container)
+        return [];
+    const block = desktopBlock(container);
+    if (!block)
+        return [];
+    const rect = rectOf(block);
+    if (rect.x === 0 && rect.y === 0)
+        return [];
+    block.position = { x: 0, y: 0 };
+    return [`page_container konumu (${rect.x},${rect.y})→(0,0) sıfırlandı: Studio her kayıtta bunu kendisi yapar (page.mappers.ts mapPageSchemaRaw); sıfırlanmazsa sayfa layout slot'unun içinde aşağı kayar ve üstte boş bant çizilir`];
+}
+/**
+ * Patch hattı kapsayıcıyı DÜZELTEMEZ: `move_component` hedefi `page_container` olamaz (PAGE-006
+ * guard'ı) ve micro-op sözlüğünde blok konumu yazan başka op yok. Kayıtlı sayfada y≠0 kapsayıcı
+ * görülürse tek çıkış yolu `page_update(schema)` — normalizasyon orada çalışır; bu uyarı o yolu
+ * gösterir.
+ */
+export function pageContainerPositionWarning(schema) {
+    const container = asObjects(schema).find(node => node.elementId === PAGE_CONTAINER_ELEMENT_ID);
+    if (!container)
+        return [];
+    const rect = rectOf(desktopBlock(container));
+    if (rect.x === 0 && rect.y === 0)
+        return [];
+    return [`PAGE-010 (uyarı): kayıtlı page_container (${rect.x},${rect.y}) konumunda — Studio bunu (0,0)'da tutar; layout'lu sayfada üstte ~${rect.y * 10}px boş bant çizilir. Düzeltme: page_update'i schema parametresiyle çağırın (gateway konumu otomatik sıfırlar); move_component kapsayıcıya uygulanamaz (PAGE-006)`];
+}
+const LEADING_GAP_ROWS = 4;
+const INTERNAL_GAP_ROWS = 12;
+/**
+ * `layout: 'flex'` verilmiş kapsayıcı mı? Şemada prop değeri `{ type:'static', data:'flex' }`
+ * sarmalıdır (Studio'nun `screen-builder-flex.functions.ts` → `getNodeFlexProps()` fonksiyonu da
+ * `props.<ad>.data` açar); sarmalsız yazılmış gövdeler için ham değer de okunur.
+ * Kaynak: `packages/ng-apps-screen-builder/src/flex-layout.ts` → `isFlexLayout()`.
+ */
+export function isFlexContainer(node) {
+    return staticPropValue(node, 'layout') === 'flex';
+}
+function staticPropValue(node, name) {
+    const props = (node.props ?? {});
+    const value = props[name];
+    if (value !== null && typeof value === 'object')
+        return value.data;
+    return value;
+}
+function gapWalk(parentLabel, children, code, onlyParents, isRoot, warnings, parentIsFlex) {
+    const placed = children
+        .filter(child => !(isRoot && ROOT_LAYER_TYPES.has(String(child.type ?? ''))))
+        .map(child => ({ child, block: desktopBlock(child) }))
+        .filter(entry => entry.block !== undefined)
+        .map(entry => ({ label: String(entry.child.elementId ?? entry.child.name ?? entry.child.type ?? '?'), rect: rectOf(entry.block) }))
+        .sort((a, b) => a.rect.y - b.rect.y);
+    if (!parentIsFlex && (onlyParents === undefined || onlyParents.has(parentLabel)) && placed.length > 0) {
+        const first = placed[0];
+        if (first.rect.y > LEADING_GAP_ROWS) {
+            warnings.push(`${code}: '${parentLabel}' içinde içerik y=${first.rect.y}'te başlıyor ('${first.label}') — üstte ~${first.rect.y * 10}px boş bant çizilir. Sayfa şeması layout slot'unun İÇİNE yerleşir; layout header'ı için boşluk bırakmayın, y'leri 0'dan başlatın (kasıtlı boşluksa yok sayın)`);
+        }
+        let bottom = first.rect.y + first.rect.h;
+        let bottomLabel = first.label;
+        for (const entry of placed.slice(1)) {
+            const gap = entry.rect.y - bottom;
+            if (gap > INTERNAL_GAP_ROWS) {
+                warnings.push(`${code}: '${parentLabel}' içinde '${bottomLabel}' (y ${bottom}'te biter) ile '${entry.label}' (y ${entry.rect.y}) arasında ${gap} satır (~${gap * 10}px) boşluk var — kasıtlı değilse y'leri bitişik verin`);
+            }
+            if (entry.rect.y + entry.rect.h > bottom) {
+                bottom = entry.rect.y + entry.rect.h;
+                bottomLabel = entry.label;
+            }
+        }
+    }
+    for (const child of children) {
+        gapWalk(String(child.elementId ?? child.type ?? '?'), asObjects(child.children), code, onlyParents, false, warnings, isFlexContainer(child));
+    }
+}
+/**
+ * Sayfa/layout düzeyi olay adları sabittir: `mount` ("When page/layout loaded") ve `destroy`
+ * ("When page/layout left") — NgApps.UI `EventActions.svelte:139-150`; destroy akışlarını runtime
+ * sayfadan ayrılmadan koşar (`Runtime.svelte initDestroyGuard`). Platform uydurma adı 200 ile
+ * kaydeder ama runtime eşleştiremez ve bağ sessizce ölü kalır (PAGE-008'in sayfa/layout ikizi).
+ */
+const SCREEN_EVENT_NAMES = new Set(['mount', 'destroy']);
+export function invalidScreenEventNames(events, code) {
+    return asObjects(events)
+        .map(event => String(event.name ?? ''))
+        .filter(name => name !== '' && !SCREEN_EVENT_NAMES.has(name))
+        .map(name => `${code}: sayfa/layout düzeyinde '${name}' diye bir olay YOK — geçerli adlar: mount (yüklendiğinde) · destroy (ayrılırken; temizlik akışları için). Platform kaydı kabul eder ama bağ sessizce ölü kalır.`);
+}
+const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Sayfadaki/layouttaki widget düğümünde `type`, widget KAYDININ ID'sidir — slug değil (NgApps.UI
+ * `page.mappers.ts:187-194`: widget çözümü `widget.id === component.type`). Slug yazılırsa kayıt
+ * 200 döner, render sessizce boş kalır. GUID olmayan type kesin yanlıştır → block.
+ */
+export function invalidWidgetTypeNodes(nodes, code) {
+    const found = [];
+    for (const node of asObjects(nodes)) {
+        if (String(node.kind ?? '') === 'widget' && !GUID_PATTERN.test(String(node.type ?? ''))) {
+            found.push(`${code}: '${node.elementId ?? '?'}' düğümü kind:'widget' ama type ('${node.type ?? ''}') bir widget ID'si değil. Widget sayfaya SLUG ile değil KAYIT ID'siyle konur: component_list'ten widget'ın id'sini alıp type alanına yazın (platform_guide('component') §Widget).`);
+        }
+        found.push(...invalidWidgetTypeNodes(node.children, code));
+    }
+    return found;
+}
+/**
+ * S-2/S-3 üreticileri (21 §1): kapsayıcı içinde büyük öncü boşluk ya da kardeşler arası büyük dikey
+ * bant. Studio'da kullanıcı boşluğu tuvalde görüp düzeltir; MCP hattında kimse görmez. Bilinçli
+ * boşluk meşru olduğu için block değil warn; eşikler 21 §4'te (öncü > 4 satır, ara > 12 satır).
+ * `onlyParents` verilirse boşluk analizi yalnız o kapsayıcılarda yapılır (patch hattı dokunulan
+ * kapsayıcılarla sınırlı kalır, mevcut boşluklar her patch'te yeniden raporlanmaz); ağacın kalanı
+ * yine dolaşılır. `layout: 'flex'` kapsayıcıların İÇİ analiz DIŞIDIR: orada y yalnız sıradır,
+ * boşluk çizilmez (bkz. `isFlexContainer`) — ağaç yine dolaşılır, torunlar analiz edilir.
+ */
+export function verticalGapWarnings(nodes, code, onlyParents) {
+    const warnings = [];
+    gapWalk('kök', asObjects(nodes), code, onlyParents, true, warnings, false);
+    return warnings;
+}
+/**
+ * View gövdesinde alan→tablo bağı **alias** üzerinden kurulur (`ViewSourceMapper.Map`:
+ * `tablesByAlias.GetValueOrDefault(input.ViewEntityAlias) ?? tables.FirstOrDefault()`) ama
+ * OKUMA tarafı (`ViewDto`/`view_get`) alanı `viewEntityId` ile döndürür. Okuduğu şekli geri yazan
+ * ajanın alias'ı boş kalır ve platform **sessizce bütün alanları ilk tabloya** düşürür: çoklu
+ * entity'li view tek entity'ye çöker, üstelik istek 200 döner (17/H2). Türetilebilir olan yarısını
+ * (id → alias) çeviriyoruz; çevrilemeyeni block ediyoruz, çünkü sonucu sessizce yanlış indeks olur.
+ */
+export function normalizeViewDefinition(definition) {
+    const view = (definition ?? {});
+    const entities = asObjects(view.entities);
+    const aliasByEntityId = new Map();
+    const aliases = new Set();
+    for (const entity of entities) {
+        const alias = typeof entity.alias === 'string' ? entity.alias : '';
+        if (alias === '')
+            continue;
+        aliases.add(alias.toLowerCase());
+        if (typeof entity.entityId === 'string')
+            aliasByEntityId.set(entity.entityId, alias);
+    }
+    const fixes = [];
+    const errors = [];
+    for (const field of asObjects(view.fields)) {
+        const alias = typeof field.viewEntityAlias === 'string' ? field.viewEntityAlias : '';
+        const entityId = typeof field.viewEntityId === 'string' ? field.viewEntityId : (typeof field.entityId === 'string' ? field.entityId : '');
+        const label = String(field.alias ?? field.fieldId ?? '?');
+        if (alias !== '') {
+            if (!aliases.has(alias.toLowerCase())) {
+                errors.push(`'${label}' alanının viewEntityAlias'ı ('${alias}') entities listesindeki hiçbir alias ile eşleşmiyor`);
+            }
+            continue;
+        }
+        const resolved = aliasByEntityId.get(entityId);
+        if (resolved) {
+            field.viewEntityAlias = resolved;
+            delete field.viewEntityId;
+            fixes.push(`${label} → '${resolved}'`);
+            continue;
+        }
+        if (entities.length > 1) {
+            errors.push(`'${label}' alanı hangi entity'ye ait belirsiz (viewEntityAlias yok${entityId === '' ? '' : `, viewEntityId '${entityId}' entities listesinde değil`})`);
+        }
+    }
+    if (errors.length > 0) {
+        errors.push(`Alanlar tabloya ALIAS ile bağlanır: entities: [{ entityId, alias }], fields: [{ viewEntityAlias: '<o alias>', fieldId, alias, weight }]. Eşleşmeyen alias platformda hataya değil SESSİZCE ilk tabloya düşmeye yol açar (VIEW-001) — mevcut alias'lar: ${[...aliases].join(', ') || '(yok)'}`);
+    }
+    return { fixes, errors };
+}
+export function viewAliasNote(fixes) {
+    if (fixes.length === 0)
+        return [];
+    return [`view alanlarının entity bağı id'den alias'a çevrildi (${fixes.join(', ')}): yazma tarafı viewEntityAlias ister, okuma tarafı viewEntityId döndürür — alias boş kalsa platform tüm alanları ilk tabloya düşürürdü`];
+}
+/**
+ * Değişken seti tek bir kayıtta yaşar: `CreateAppVariableCommand`/`CreatePageVariableCommand`
+ * yalnız `Data` alanı taşır (Studio uygulama başına ve sayfa başına TEK satır tutar —
+ * `IsVariableExistForApplicationAsync` doluysa create update'e döner). Studio'nun gönderdiği şekil
+ * `data`'nın **JSON string** olmasıdır: "[{\"key\":\"MyTest\",\"value\":{\"isActive\":true}}]".
+ * `Data` tipi `object` olduğu için platform her gövdeyi kabul eder; alan adı tutmayan bir gövde
+ * (name/type/defaultValue gibi) `Data`'yı null bırakır ve istek 200 döner ama HİÇBİR ŞEY yazılmaz
+ * (17/Ç1). Okuma tarafı da aynı string'i geri verir (`AppVariablesDto.Map` → GetRawText).
+ */
+export function parseVariableEntries(data) {
+    const source = typeof data === 'string' ? safeParse(data) : data;
+    return asObjects(source)
+        .filter(entry => typeof entry.key === 'string' && entry.key !== '')
+        .map(entry => ({ key: String(entry.key), value: entry.value }));
+}
+function safeParse(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Uç, seti KOMPLE değiştirir (`OverrideData`) — tek değişken göndermek diğerlerini siler. Gateway
+ * mevcut seti okuyup anahtar bazında birleştirir; `replace: true` verilirse bilinçli olarak ezer.
+ */
+export function mergeVariableEntries(existing, incoming, replace) {
+    if (replace)
+        return { entries: incoming, fixes: [] };
+    const merged = [...existing];
+    const kept = [];
+    for (const entry of incoming) {
+        const index = merged.findIndex(current => current.key === entry.key);
+        if (index === -1) {
+            merged.push(entry);
+            continue;
+        }
+        merged[index] = entry;
+    }
+    for (const entry of existing) {
+        if (!incoming.some(current => current.key === entry.key))
+            kept.push(entry.key);
+    }
+    return {
+        entries: merged,
+        fixes: kept.length > 0
+            ? [`mevcut değişkenler korundu (${kept.join(', ')}): uç seti komple değiştirir, gateway anahtar bazında birleştirdi — kasten silmek için replace: true verin`]
+            : []
+    };
+}
+export function blockSizeNote(clamped) {
+    if (clamped.length === 0)
+        return [];
+    return [`komponent boyutları katalogdaki maxSize'a çekildi (${clamped.join(', ')}): katalog varsayılanı kendi sınırını aşabiliyor, aşan gövde doğrulayıcıdan "must be between" hatasıyla dönerdi`];
+}
+/**
+ * Sayfada page_container varken köke eklenen komponent kapsayıcının DIŞINDA kalır; Studio onu
+ * tuvalde göstermez, sayfa düzeyi olaylar da kapsayıcıya bağlı olduğu için akış dışında kalır.
+ * parent verilmemiş ya da 'root' verilmiş add_component'leri kapsayıcıya yönlendiriyoruz.
+ */
+export function retargetRootAdds(ops, containerElementId) {
+    const retargeted = [];
+    for (const op of asObjects(ops)) {
+        if (op.op !== 'add_component')
+            continue;
+        if (op.parent !== undefined && op.parent !== null && op.parent !== 'root')
+            continue;
+        const component = op.component;
+        if (ROOT_LAYER_TYPES.has(String(component?.type ?? '')))
+            continue;
+        op.parent = containerElementId;
+        retargeted.push(String(component?.elementId ?? '?'));
+    }
+    return retargeted;
+}
+export function rootAddsNote(retargeted, containerElementId) {
+    if (retargeted.length === 0)
+        return [];
+    return [`köke eklenmek istenen komponentler '${containerElementId}' kapsayıcısına alındı (${retargeted.join(', ')}): sayfa komponentleri kapsayıcının içinde durur, kök seviyesi Studio tuvalinin dışıdır`];
+}
+export function componentDefaultsNote(fixed) {
+    if (fixed.length === 0)
+        return [];
+    return [`komponent gövdelerine eksik zorunlu alanlar eklendi (${fixed.join(' · ')}): bunlar olmadan platform NullReferenceException verir ve page_schema_validate bunu yakalamaz`];
+}
+/**
+ * Create yolu junction kaydını açar ama fiziksel tabloyu kurmaz (platform bug'ı P-01,
+ * EntityService.CreateAsync:172-191); update yolu kurar. Bu yüzden m2m/multi-file/multi-enum
+ * alanları create gövdesinden ayrılır, entity onlarsız kurulur, alanlar entity_update ile
+ * eklenir (klinik K-005).
+ */
+export function splitJunctionFields(definition, isJunction) {
+    const fields = asObjects(definition.fields);
+    const deferred = fields.filter(isJunction);
+    if (deferred.length === 0)
+        return { base: definition, deferred: [] };
+    return { base: { ...definition, fields: fields.filter(field => !isJunction(field)) }, deferred };
+}
+/**
+ * `remove_component` şemadan bir dalı çıkarır ama etkisi dalla sınırlı DEĞİLDİR: sayfa
+ * kaydedilirken artık hiçbir komponent olayının, prop'unun ya da sayfa olayının referans vermediği
+ * akışlar platformca KALICI olarak silinir (`PageService.UpdateAsync` → `flowRepository
+ * .DeleteRangeAsync`). Micro-op hattının "yalnız hedefe dokunur" garantisinin tek istisnası budur;
+ * çoğu zaman istenen davranıştır, istenmediğinde ise uyarı tek erken sinyaldir.
+ */
+/**
+ * Repeater içinde repeater arar. ÖLÇÜLDÜ (2026-08-19, anket-admin probe sayfası): iç repeater
+ * OKUMADA çalışır (dış satır başına doğru sayıda iç satır çizilir) ama YAZMA ölüdür —
+ * iç girdiyi değiştirince dış satırın alanı değişmez ve iç repeater'ın `_repeaterValues`'ü null
+ * kalır. Sebep yapısal: şemada iç repeater TEK düğümdür, dış satır başına ayrı düğüm yoktur;
+ * `_repeaterValues` anahtarı iç satır id'sine göredir ve dış satırlar arasında çakışır.
+ * Üstelik tek bir düzenlemeden sonra DOM bozuluyor (ölçümde girdi sayısı 3 → 19) ve ekranda
+ * sürekli "Expression error: Cannot read properties of null" toast'ı çıkıyor.
+ * Doğru desen: iç listeyi tek bir `textarea`'da satır başına bir öğe olarak topla.
+ */
+export function nestedRepeaterNodes(nodes) {
+    const found = [];
+    const walk = (list, insideRepeater) => {
+        for (const node of list) {
+            const isRepeater = node.type === 'repeater';
+            if (isRepeater && insideRepeater)
+                found.push(String(node.elementId ?? node.name ?? '?'));
+            walk(asObjects(node.children), insideRepeater || isRepeater);
+        }
+    };
+    walk(asObjects(nodes), false);
+    return found;
+}
+export function nestedRepeaterMessage(ids) {
+    return `PAGE-013 — repeater içinde repeater (istek gönderilmedi): ${ids.join(' · ')}. `
+        + 'Ölçüldü (2026-08-19): iç repeater OKUMADA çalışır ama girilen değer dış satıra GERİ YAZILMAZ '
+        + '(_repeaterValues null kalır) ve tek düzenlemeden sonra DOM bozulur. Sebep yapısal: şemada iç '
+        + 'repeater tek düğümdür, dış satır başına ayrı düğüm yoktur. Satır içi listeyi tek bir textarea '
+        + "ile topla (satır başına bir öğe) ve kaydederken split('\n') ile böl — platform_guide('page') Kural 1g.";
+}
+/**
+ * `style` prop'u düz CSS STRING verilmiş düğümler. Çalışır (emotion string'i CSS metni sayar) ama
+ * `--ng-*` token ezilemez, iç seçici/pseudo-class yazılamaz ve kabın kendi düzeni bozulabilir —
+ * ölçüm (anket-admin giriş sayfası, 2026-08-19): string içindeki `display:flex` page_container'ın
+ * kolon düzenini ezdi, kart 66px genişlik × 733px yükseklik çizildi.
+ */
+export function stringStyleNodes(nodes) {
+    const found = [];
+    const walk = (list) => {
+        for (const node of list) {
+            const props = (node.props ?? {});
+            const style = props.style;
+            if (style && typeof style.data === 'string' && style.data.includes(':')) {
+                found.push(String(node.elementId ?? node.name ?? '?'));
+            }
+            walk(asObjects(node.children));
+        }
+    };
+    walk(asObjects(nodes));
+    return found;
+}
+export function stringStyleWarning(ids) {
+    if (ids.length === 0)
+        return [];
+    return [`PAGE-014 (uyarı): style prop'u düz CSS STRING verilmiş (${ids.join(', ')}). `
+            + 'Çalışır ama --ng-* tema değişkeni ezemez, iç seçici/pseudo-class yazamazsın ve kabın kendi '
+            + 'düzenini bozabilirsin (ölçüm: string içindeki display:flex page_container\'ı çökertti, kart '
+            + '66px kaldı). style NESNE olmalı: { "borderRadius": "12px", "&__body": { "padding": "20px" } } '
+            + "— platform_guide('page') Kural 1h. Düzen için style'a HİÇ dokunma: kapsayıcının kendi "
+            + "layout:'flex' prop grubu var (Kural 1f-2)."];
+}
+/**
+ * `layout` 'flex' DEĞİLKEN yazılmış flex düzen prop'ları. Renderer bunları yalnız
+ * `isFlexLayout(props)` doğruyken okur (`flex-layout.ts` → `getFlexChildrenStyle`), Studio paneli de
+ * `layout != 'flex'` iken alanları gizler (`component.functions.ts` `_hide` kuralları): ızgara
+ * kapsayıcıya `direction: 'column'` yazmak SESSİZCE hiçbir şey yapmaz — doğrulama duvarı da
+ * susar, çünkü prop katalogda VARDIR (2026-08-25 ölçümü: `page_schema_validate` yedi prop'a da
+ * `valid: true` döndü). Katalog varsayılanına eşit değerler elenir; onlar niyet taşımaz.
+ */
+const FLEX_LAYOUT_DEFAULTS = {
+    direction: 'row',
+    horizontalAlign: 'left',
+    verticalAlign: 'top',
+    size: 'shrink',
+    gap: 'medium',
+    wrap: false
+};
+/** Kapsayıcı düzenini kuran prop kümesi (`ContainerComponent` şeması): `layout` + ona bağlı altı ayar. */
+export const FLEX_LAYOUT_PROP_NAMES = new Set(['layout', ...Object.keys(FLEX_LAYOUT_DEFAULTS)]);
+export function inertFlexPropNodes(nodes) {
+    const found = [];
+    const walk = (list) => {
+        for (const node of list) {
+            if (!isFlexContainer(node)) {
+                const inert = Object.keys(FLEX_LAYOUT_DEFAULTS).filter(name => {
+                    const value = staticPropValue(node, name);
+                    return value !== undefined && value !== null && value !== FLEX_LAYOUT_DEFAULTS[name];
+                });
+                if (inert.length > 0)
+                    found.push(`${String(node.elementId ?? node.name ?? node.type ?? '?')} (${inert.join(', ')})`);
+            }
+            walk(asObjects(node.children));
+        }
+    };
+    walk(asObjects(nodes));
+    return found;
+}
+export function inertFlexPropWarning(entries) {
+    if (entries.length === 0)
+        return [];
+    return [`PAGE-015 (uyarı): flex düzen prop'u verilmiş ama kapsayıcının layout'u 'flex' değil (${entries.join(' · ')}). `
+            + "direction · horizontalAlign · verticalAlign · size · gap · wrap YALNIZ layout:'flex' iken okunur; ızgarada "
+            + "sessizce yok sayılır (istek reddedilmez, prop katalogda vardır). Akış düzeni istiyorsan aynı düğüme "
+            + "layout:'flex' de yaz, istemiyorsan bu prop'ları kaldır — platform_guide('page') Kural 1f-2."];
+}
+export function orphanedFlowWarnings(schema, pageEvents, ops) {
+    const removals = asObjects(ops).filter(op => op.op === 'remove_component');
+    if (removals.length === 0)
+        return [];
+    const nodes = asObjects(schema);
+    const warnings = [];
+    for (const removal of removals) {
+        const target = String(removal.target ?? '');
+        const doomed = findNodeByElementId(nodes, target);
+        if (!doomed)
+            continue;
+        const losing = collectFlowRefs(doomed);
+        if (losing.size === 0)
+            continue;
+        const surviving = new Set();
+        for (const event of asObjects(pageEvents)) {
+            if (typeof event.value === 'string')
+                surviving.add(event.value);
+        }
+        collectFlowRefsExcept(nodes, target, surviving);
+        const orphaned = [...losing].filter(flowId => !surviving.has(flowId));
+        if (orphaned.length > 0) {
+            warnings.push(`'${target}' silinince ona bağlı ${orphaned.length} akış sayfada referanssız kalıyor (${orphaned.join(', ')}) ve platform bunları KALICI olarak siler. Akışı korumak istiyorsan önce başka bir komponente bağla (set_event) ya da flow_get ile gövdesini yedekle.`);
+        }
+    }
+    return warnings;
+}
+function findNodeByElementId(nodes, elementId) {
+    for (const node of nodes) {
+        if (node.elementId === elementId)
+            return node;
+        const found = findNodeByElementId(asObjects(node.children), elementId);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function collectFlowRefs(node) {
+    const found = new Set();
+    const visitProps = (value) => {
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                visitProps(entry);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const record = value;
+        if (record.type === 'flow' && typeof record.ref === 'string')
+            found.add(record.ref);
+        for (const entry of Object.values(record))
+            visitProps(entry);
+    };
+    /**
+     * Bir düğümün akış bağları iki yerdedir: `events[].value` ve `type:'flow'` prop'ları.
+     * Alt ağacı düğüm düğüm gez — `props`'u derin taramak yetmez, çünkü çocuğun `events`
+     * girdisi `{ name, value }` şeklindedir ve `type:'flow'` testine takılmaz. Bu eksik
+     * yüzünden kapsayıcı silindiğinde İÇİNDEKİ butonun click akışı sessizce yok sayılıyordu
+     * (ölçüm: anket-admin giriş sayfası, 2026-08-19 — akış uyarısız silindi).
+     */
+    const visitNode = (current) => {
+        for (const event of asObjects(current.events)) {
+            if (typeof event.value === 'string')
+                found.add(event.value);
+        }
+        visitProps(current.props);
+        for (const child of asObjects(current.children))
+            visitNode(child);
+    };
+    visitNode(node);
+    return found;
+}
+function collectFlowRefsExcept(nodes, skipElementId, into) {
+    for (const node of nodes) {
+        if (node.elementId === skipElementId)
+            continue;
+        for (const flowId of collectFlowRefsShallow(node))
+            into.add(flowId);
+        collectFlowRefsExcept(asObjects(node.children), skipElementId, into);
+    }
+}
+function collectFlowRefsShallow(node) {
+    const found = new Set();
+    for (const event of asObjects(node.events)) {
+        if (typeof event.value === 'string')
+            found.add(event.value);
+    }
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                visit(entry);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const record = value;
+        if (record.type === 'flow' && typeof record.ref === 'string')
+            found.add(record.ref);
+        for (const entry of Object.values(record))
+            visit(entry);
+    };
+    visit(node.props);
+    return found;
+}