@flextudio/scenario 0.1.0

package/contract-data/schema/v1/patterns/_base.materialize.mjs

@@ -0,0 +1,1181 @@
+// _base.materialize.mjs
+// ─────────────────────────────────────────────────────────────────────────────
+// 패턴 dispatcher + 트리 walker.
+//
+// LLM 이 emit 한 시나리오 (raw control + pattern invocation 의 혼합) 를 받아
+// 모든 pattern invocation 을 그 패턴의 materializer 로 치환한 풀 메타데이터로
+// 변환한다. 결과는 engine schema 검증 통과 가능한 상태가 된다.
+//
+// 입력 shape (development.md §2):
+// - 패턴 호출:   { "<patternName>": { ...props } }   ← 키 1개, 값 객체.
+// - 원시 컨트롤:  { "ControlType": "InputText", ... }
+// - 원시 그룹:    { "ContentsType": "Group", Contents: [...] }
+// - 그 외:       Step 메타데이터(StepName/BottomButtons/Next/...) 또는 ScenarioMeta
+//                — 항상 raw passthrough.
+//
+// 처리 규칙:
+// 1. 트리 walk 는 `Contents` (Group children) 와 `Dialog.Layouts[*].Controls`
+//    배열에만 들어간다. FontStyle/BorderStyle 등 raw 스타일 객체에는 descend 하지
+//    않음 (단일 키가 우연히 패턴 이름과 충돌하는 false positive 방지).
+// 2. ID 카운터는 입력의 max `f_N` Id 에서 시작 → raw 가 미리 박은 ID 와 겹치지 않음.
+// 3. 패턴 materializer 가 throw 하면 path + 메시지를 errors 에 모아 반환. 트리는
+//    계속 walk (다른 노드 에러도 한 번에 보고).
+// 4. 동일 이름이 여러 tier 에 있으면 registry 로드 시 throw (전역 유일).
+// 5. 단일 key 객체인데 알려진 패턴 이름이 아니면 raw 로 간주하고 그 안의 컨테이너
+//    필드를 계속 walk — 시나리오 구조상 ScenarioMeta / 비-Contents 객체일 수도 있어서
+//    permissive.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { applyDesign } from "../design-system/materialize.mjs";
+import { makeGroup } from "./_base.controls.mjs";
+import { generateId } from "./_base.id.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PATTERN_TIERS = Object.freeze(["atom", "molecule", "organism"]);
+
+// Step 의 세 가지 children 컨테이너 — schema 가 모두 Group[] 만 받음.
+const STEP_CONTAINER_KEYS = Object.freeze([
+  "Contents",
+  "FixedContentsTop",
+  "FixedContentsBottom",
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry (lazy load + cache)
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _registry = null;
+
+async function loadRegistry() {
+  if (_registry) return _registry;
+  const reg = new Map();
+  for (const tier of PATTERN_TIERS) {
+    const dir = join(__dirname, tier);
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".materialize.mjs")) continue;
+      if (entry.startsWith("_")) continue; // _base.materialize.mjs etc.
+      const name = entry.slice(0, -".materialize.mjs".length);
+      if (reg.has(name)) {
+        const existing = reg.get(name);
+        throw new Error(
+          `_base.materialize: pattern name conflict — '${name}' 가 ${existing.tier} 와 ${tier} 양쪽에 존재. 패턴 이름은 전역 유일.`,
+        );
+      }
+      const mod = await import(pathToFileURL(join(dir, entry)).href);
+      if (typeof mod.default !== "function") {
+        throw new Error(
+          `_base.materialize: ${tier}/${entry} 에 default export (materialize fn) 없음.`,
+        );
+      }
+      reg.set(name, { tier, materialize: mod.default });
+    }
+  }
+  _registry = reg;
+  return reg;
+}
+
+/** 테스트 / 외부 introspection 용. */
+export async function getPatternRegistry() {
+  return await loadRegistry();
+}
+
+/** 테스트 hot-reload 용 — 다음 호출에서 다시 스캔. */
+export function _resetRegistryForTest() {
+  _registry = null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ID counter helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ID_RE = /^f_([1-9][0-9]*)$/;
+
+function findMaxId(obj, max = 0) {
+  if (!obj || typeof obj !== "object") return max;
+  if (Array.isArray(obj)) {
+    for (const v of obj) max = findMaxId(v, max);
+    return max;
+  }
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "Id" && typeof v === "string") {
+      const m = ID_RE.exec(v);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > max) max = n;
+      }
+    } else if (v && typeof v === "object") {
+      max = findMaxId(v, max);
+    }
+  }
+  return max;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tree walker / dispatcher
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 단일 노드 처리:
+ * - 패턴 호출이면 materializer 호출 후 결과 반환.
+ * - 그렇지 않으면 raw 로 보고 컨테이너 필드만 재귀.
+ */
+// LLM 디버깅에 유용한 props 스냅샷 — 너무 길면 잘라낸다.
+function propsSnapshot(props, maxChars = 240) {
+  if (props == null) return null;
+  let s;
+  try {
+    s = JSON.stringify(props);
+  } catch {
+    return "<unserializable>";
+  }
+  if (s.length <= maxChars) return s;
+  return s.slice(0, maxChars - 1) + "…";
+}
+
+// 컨트롤 enum 의 흔한 변형(대소문자·확실한 동의어)을 정본으로 정규화.
+// 모델이 개념은 맞고 토큰만 틀리게 쓰는 케이스('money'→'Money', 'ckey'→'LabelCKey')를
+// 결정적으로 교정 — validate write-back 으로 스튜디오엔 정본이 기록된다.
+// 엄격 allowlist: (1) 대소문자만 다른 정본, (2) 명시 동의어 만 교정. 미매칭은 원본 유지
+// (스키마가 정상적으로 잡음). 모호한 값(LabelType:'labelvalue' = labeltext? LabelCKey?
+// / InputType:'money' = MaskType? InputNumber?)은 의도 추정 불가라 교정 대상 제외.
+const ENUM_CANONICAL = {
+  LabelType: { canon: ["labeltext", "LabelCKey"], synonyms: { ckey: "LabelCKey" } },
+  MaskType: { canon: ["Time", "Money", "Date", "Phone"], synonyms: {} },
+  // Calendar SelectType — 모델이 일반/CSS 어휘(one/single, range/period)를 쓰는 케이스.
+  // canon: SingleDate(단일) / FromTo(기간). enum=["SingleDate","FromTo"].
+  SelectType: {
+    canon: ["SingleDate", "FromTo"],
+    synonyms: { one: "SingleDate", single: "SingleDate", date: "SingleDate", range: "FromTo", period: "FromTo", fromto: "FromTo" },
+  },
+};
+
+function canonicalizeControlEnums(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  if (!("ControlType" in node)) return node;
+  let out = node;
+  for (const [field, spec] of Object.entries(ENUM_CANONICAL)) {
+    const v = node[field];
+    if (typeof v !== "string" || v === "") continue;
+    if (spec.canon.includes(v)) continue; // 이미 정본
+    const lc = v.toLowerCase();
+    const caseMatch = spec.canon.find((c) => c.toLowerCase() === lc); // 대소문자만 다름
+    const fixed = caseMatch ?? spec.synonyms[lc]; // 또는 명시 동의어
+    if (fixed && fixed !== v) {
+      if (out === node) out = { ...node };
+      out[field] = fixed;
+    }
+  }
+  return out;
+}
+
+// Label LabelType ↔ 채운 필드 정합 — LabelType 과 실제 채운 필드(labeltext/LabelCKey)가
+// 불일치하면 채워진 필드 기준으로 LabelType 을 교정. Label 의 allOf if/then
+// (LabelType='labeltext'→labeltext required / 'LabelCKey'→LabelCKey required) 위반은
+// 상위 Control union 의 oneOf 를 통째로 탈락시켜 형제마다 'must match exactly one
+// schema in oneOf' cascade 를 일으킨다 (관측: LabelType='labeltext' 인데 labeltext 없이
+// LabelCKey 만 채움). 결정적 정합 — 채워진 필드가 단일하게 가리킬 때만.
+//  - LabelCKey 채워짐 + labeltext 비어있음 → LabelType:"LabelCKey"
+//  - labeltext 채워짐 + LabelCKey 비어있음 → LabelType:"labeltext"
+//  - 둘 다 채워짐 / 둘 다 비어있음 → 모호 → 손대지 않음 (schema 가 잡게).
+function canonicalizeLabelType(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  if (node.ControlType !== "Label") return node;
+  const filled = (v) => typeof v === "string" && v.length > 0;
+  const hasText = filled(node.labeltext);
+  const hasCkey = filled(node.LabelCKey);
+  let want = null;
+  if (hasCkey && !hasText) want = "LabelCKey";
+  else if (hasText && !hasCkey) want = "labeltext";
+  if (want && node.LabelType !== want) return { ...node, LabelType: want };
+  return node;
+}
+
+// Items 원소 표준키 외 strip — Combo/RadioBox/CheckBox 의 인라인 `Items[]` 원소는
+// 스키마상 ItemName/ItemValue(+CheckBox ItemValueDel) 만 정의. additionalProperties:true
+// 라 기본 검증은 통과하나 strict 변종(unevaluatedProperties:false)에서 막힌다
+// (strict-fields). 모델이 스펙의 실데이터 필드(예: bizUnitName/bizUnitCode)를 Items 에
+// 직접 박는 케이스 — 관측상 ItemName/ItemValue 와 값이 중복이라 손실 없이 제거.
+//  - 표준키(ItemName/ItemValue/ItemValueDel) 만 남김. 실데이터 다중 컬럼은 DataSource(Grid)로.
+const ITEM_STD_KEYS = new Set(["ItemName", "ItemValue", "ItemValueDel"]);
+// ★ Combo/Search 의 인라인 데이터는 본체가 아니라 자식(ComboList/List)의 Items 에
+//   온다 — 실제 strict-fields frontier 가 ComboList.Items 였으므로 자식 호스트 포함.
+const ITEM_STD_HOSTS = new Set(["Combo", "ComboList", "RadioBox", "CheckBox", "List"]);
+function canonicalizeItemFields(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  if (!("ControlType" in node) || !Array.isArray(node.Items)) return node;
+  if (!ITEM_STD_HOSTS.has(node.ControlType)) return node;
+  let changed = false;
+  const items = node.Items.map((it) => {
+    if (!it || typeof it !== "object" || Array.isArray(it)) return it;
+    if (Object.keys(it).every((k) => ITEM_STD_KEYS.has(k))) return it;
+    changed = true;
+    const clean = {};
+    for (const k of Object.keys(it)) if (ITEM_STD_KEYS.has(k)) clean[k] = it[k];
+    return clean;
+  });
+  return changed ? { ...node, Items: items } : node;
+}
+
+// 입력(편집) 컨트롤 후손 탐지 — detail(읽기전용) vs update(수정) 판정용.
+// Contents 서브트리(자식 Group 포함)에 편집 컨트롤이 하나라도 있으면 true.
+const EDIT_CONTROLS = new Set([
+  "InputText", "InputNumber", "InputDate", "InputMask", "MultiInputBox",
+  "Combo", "Search", "CheckBox", "RadioBox", "InputFile",
+]);
+function hasEditableDescendant(node) {
+  let found = false;
+  const walk = (n) => {
+    if (found || !n || typeof n !== "object") return;
+    if (Array.isArray(n)) { for (const c of n) walk(c); return; }
+    if (typeof n.ControlType === "string" && EDIT_CONTROLS.has(n.ControlType)) { found = true; return; }
+    if (Array.isArray(n.Contents)) for (const c of n.Contents) walk(c);
+  };
+  if (Array.isArray(node.Contents)) for (const c of node.Contents) walk(c);
+  return found;
+}
+
+// DataConnection 정본화 — 스튜디오 canonical 은 단일 객체
+// `{TargetType:'category', DataUsage, CategoryName, ...}`. 모델이 intent 예제를
+// 따라 단일원소 배열 `[{...}]` 로 쓰거나 TargetType 을 누락하는 케이스를 결정적으로
+// 교정 (validate write-back 으로 스튜디오엔 정본 기록).
+//  - 단일원소 배열 → 그 객체로 unwrap. (0개/다중 원소는 비정상 → 스키마가 잡게 둠.)
+//  - TargetType 누락/빈값 → const 'category' 주입 (유일 허용값이라 항상 안전).
+//  - DataUsage 조건부 필수 주입 (schema allOf if/then = 스튜디오 property-data.js):
+//    default→UseNewSector:true+OnlyIfNoSector:true / new→UseNewSector:true /
+//    detail|update→UseTargetSector:true+TargetSector:{} / query→추가 없음.
+//    모델이 DataUsage 만 적고 짝 필드를 빠뜨리는 케이스를 정본으로(누락 시만 주입).
+//  - ★ DataUsage 무관 공통: TargetSector.Filters 가 채워져 있으면 UseTargetSector:true 보장.
+//    UseTargetSector 가 켜져있지 않으면 런타임이 Filters 를 무시하고 카테고리 전체 섹터를
+//    전송한다 (data-objects.md §1, events.schema.json UseFilter 와 동치). 특히 query 에서
+//    부분 필터링(Parent/Custom/Condition) 시 모델이 Filters 만 넣고 UseTargetSector 를
+//    빠뜨리는 케이스 — 필터가 무시되어 조회가 전체로 새는 문제를 결정적으로 교정.
+function canonicalizeDataConnection(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const orig = node.DataConnection;
+  if (orig == null) return node;
+  let dc = orig;
+  let changed = false;
+  if (Array.isArray(dc)) {
+    if (dc.length === 1 && dc[0] && typeof dc[0] === "object" && !Array.isArray(dc[0])) {
+      dc = dc[0];
+      changed = true;
+    } else {
+      return node; // 0개/다중 원소 배열 → 스키마가 정상적으로 거부
+    }
+  }
+  if (typeof dc !== "object" || Array.isArray(dc)) return node;
+  // 이후 필드 보강은 복사본 work 에 (orig 불변 보장).
+  const work = { ...dc };
+  if (typeof work.TargetType !== "string" || work.TargetType === "") {
+    work.TargetType = "category";
+    changed = true;
+  }
+  // DataUsage 조건부 필수 (누락 시에만 주입; 기존 값 보존).
+  const du = typeof work.DataUsage === "string" ? work.DataUsage : "";
+  const ensure = (k, v) => { if (!(k in work)) { work[k] = v; changed = true; } };
+  if (du === "default") { ensure("UseNewSector", true); ensure("OnlyIfNoSector", true); }
+  else if (du === "new") { ensure("UseNewSector", true); }
+  else if (du === "detail" || du === "update") {
+    ensure("UseTargetSector", true);
+    // detail/update 는 선택된 1건(activeSector)을 가져와야 한다 — TargetSector.Filters 에
+    // Status:["active"] 가 있어야 데이터가 흐른다. 빈 객체({})만 주입하면 상세/수정 화면이 비어버린다.
+    // 기존에 Filters 가 채워져 있으면(Status/Parent 등) 보존, 없거나 비어있을 때만 Status:active 주입.
+    const ts = work.TargetSector;
+    const hasFilters = ts && typeof ts === "object" && Array.isArray(ts.Filters) && ts.Filters.length > 0;
+    if (!hasFilters) {
+      work.TargetSector = {
+        ...(ts && typeof ts === "object" ? ts : {}),
+        Filters: [{ FilterType: "Status", Status: ["active"] }],
+      };
+      changed = true;
+    }
+    // detail(읽기전용) vs update(수정) 교정: 둘 다 activeSector 를 받고 구조가 같다 — 차이는 편집 가능 여부뿐.
+    // 그룹 후손에 편집 컨트롤이 있으면 update, 없으면(Label 등 표시만) detail 로 결정적 교정.
+    const want = hasEditableDescendant(node) ? "update" : "detail";
+    if (work.DataUsage !== want) { work.DataUsage = want; changed = true; }
+  }
+  // flat DCParentKey/DCChildKey 교정 — 이 키들은 DataConnection 최상위가 아니라
+  //  TargetSector.Filters 의 Parent 필터 안에 들어가야 한다 (운영 메타 4/4·schema sectorFilter
+  //  Parent 분기가 정본). 모델이 new 용 `DCLinkCkey.DCLinkItems[{DCParentKey,DCChildKey}]` 와
+  //  query 용 `Parent` 필터를 혼동해 DC 최상위에 flat 으로 두는 케이스를 결정적으로 이전:
+  //   - Parent 필터가 있으면 그 안의 빈 키만 flat 값으로 채우고(필터 우선), DC 의 flat 키 제거.
+  //   - Parent 필터가 없고 DataUsage:query 면 Parent 필터를 생성해 채운다.
+  //   - new+UseDCLink 는 DCLinkCkey.DCLinkItems 영역이므로 대상 아님 (건드리지 않음).
+  {
+    const flatP = typeof work.DCParentKey === "string" ? work.DCParentKey : undefined;
+    const flatC = typeof work.DCChildKey === "string" ? work.DCChildKey : undefined;
+    const isDcLinkNew = du === "new" && work.UseDCLink === true;
+    if ((flatP !== undefined || flatC !== undefined) && !isDcLinkNew) {
+      const ts = (work.TargetSector && typeof work.TargetSector === "object" && !Array.isArray(work.TargetSector))
+        ? { ...work.TargetSector } : {};
+      const filters = Array.isArray(ts.Filters) ? ts.Filters.slice() : [];
+      let pIdx = filters.findIndex((f) => f && typeof f === "object" && f.FilterType === "Parent");
+      if (pIdx >= 0 || du === "query") {
+        if (pIdx < 0) { filters.push({ FilterType: "Parent" }); pIdx = filters.length - 1; }
+        const pf = { ...filters[pIdx] };
+        if ((pf.DCParentKey === undefined || pf.DCParentKey === "") && flatP !== undefined) pf.DCParentKey = flatP;
+        if ((pf.DCChildKey === undefined || pf.DCChildKey === "") && flatC !== undefined) pf.DCChildKey = flatC;
+        filters[pIdx] = pf;
+        ts.Filters = filters;
+        work.TargetSector = ts;
+        delete work.DCParentKey;
+        delete work.DCChildKey;
+        changed = true;
+      }
+    }
+  }
+  // 공통: TargetSector.Filters 사용 시 UseTargetSector:true 필수 (DataUsage 무관 — query 의 부분
+  // 필터링 포함). 미설정/false 모두 교정 — Filters 가 실재하면 스위치가 켜져 있어야 필터가 적용된다.
+  // detail/update 는 위에서 이미 ensure 했으므로 idempotent.
+  {
+    const ts = work.TargetSector;
+    const hasFilters = ts && typeof ts === "object" && Array.isArray(ts.Filters) && ts.Filters.length > 0;
+    if (hasFilters && work.UseTargetSector !== true) { work.UseTargetSector = true; changed = true; }
+  }
+  return changed ? { ...node, DataConnection: work } : node;
+}
+
+// AllowExtensions 정본화 — 스키마는 소문자 확장자 배열(`^[a-z0-9]+$`)을 요구하나
+// 모델이 콤마 문자열("jpg,jpeg,png,pdf")로 쓰는 케이스를 결정적으로 교정.
+//  - 문자열 → 콤마 분리 + trim + 소문자 → 배열 (확장자는 대소문자 무관, 스키마는 소문자).
+//  - 이미 배열이거나 분리 결과가 비면 원본 유지(스키마가 잡게).
+function canonicalizeAllowExtensions(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const v = node.AllowExtensions;
+  if (typeof v !== "string") return node;
+  const arr = v.split(",").map((s) => s.trim().toLowerCase()).filter((s) => s.length > 0);
+  if (arr.length === 0) return node;
+  return { ...node, AllowExtensions: arr };
+}
+
+// InputFile InnerCKey 정본화 — Attributes.InnerCKey 는 [no-inner-block] 정책으로
+// 스키마가 무조건 차단(input-file.schema.json: "InnerCKey": false → 'boolean schema
+// is false'). 모델이 본체 FlexKey.ckey(또는 Ckeys)를 이미 채우고도 InnerCKey 를
+// 중복으로 다는 케이스가 잦다(관측: FlexFile + FlexKey.ckey==InnerCKey). 결정적 strip.
+//  - 손실 방지: 모듈별 1차 저장 필드가 비어 있을 때만 InnerCKey 값을 이관(필드 복사,
+//    발명 아님 — canonicalizeComboKeys 의 Ckeys 복사와 동류). 이미 채워져 있으면 제거만.
+//  - InputFile 한정 (InnerCKey:false 가 input-file.schema.json 에만 정의 — 타 컨트롤은
+//    additionalProperties:true 라 에러 없음).
+function canonicalizeInputFileInnerCKey(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  if (node.ControlType !== "InputFile") return node;
+  const attrs = node.Attributes;
+  if (!attrs || typeof attrs !== "object" || Array.isArray(attrs)) return node;
+  if (!("InnerCKey" in attrs)) return node;
+  const { InnerCKey, ...rest } = attrs;
+  const val = typeof InnerCKey === "string" ? InnerCKey.trim() : "";
+  if (val) {
+    const mod = node.Module || "FlexFile";
+    if (mod === "KsystemFile" || mod === "KsystemPayPDF") {
+      // 1차 저장 = Ckeys 배열
+      if (!Array.isArray(rest.Ckeys) || rest.Ckeys.length === 0) rest.Ckeys = [val];
+    } else {
+      // FlexFile / HostingFolder / ServerkitFile → FlexKey.ckey
+      const fk = (rest.FlexKey && typeof rest.FlexKey === "object" && !Array.isArray(rest.FlexKey))
+        ? rest.FlexKey : {};
+      if (typeof fk.ckey !== "string" || fk.ckey === "") rest.FlexKey = { ...fk, ckey: val };
+    }
+  }
+  return { ...node, Attributes: rest };
+}
+
+// Combo/Search 본체 Ckeys ↔ 자식 ComboList/List Ckeys 동기화 ([ds-key] 1차 원인).
+// 모델이 본체 Ckeys 만 채우고 자식 Ckeys 를 비우는 케이스 — 자식이 비어있고 본체가
+// 채워져 있으면 본체 Ckeys 를 자식에 복사 (combo.md: 자식 Ckeys = 본체 Ckeys 동일).
+// 둘 다 채워졌는데 다르면 모호 → 손대지 않음(스키마 [ds-key] 가 잡음).
+const DIALOG_INNER_TYPE = { Combo: "ComboList", Search: "List" };
+function canonicalizeComboKeys(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const innerType = DIALOG_INNER_TYPE[node.ControlType];
+  if (!innerType) return node;
+  const body = node.Ckeys;
+  if (!Array.isArray(body) || body.length === 0) return node; // 본체 기준 없으면 동기화 안 함
+  const layouts = node?.Dialog?.Layouts;
+  if (!Array.isArray(layouts)) return node;
+  let changed = false;
+  const newLayouts = layouts.map((layout) => {
+    if (!layout || !Array.isArray(layout.Controls)) return layout;
+    let lc = false;
+    const controls = layout.Controls.map((c) => {
+      if (c && c.ControlType === innerType && (!Array.isArray(c.Ckeys) || c.Ckeys.length === 0)) {
+        lc = true; changed = true;
+        return { ...c, Ckeys: [...body] };
+      }
+      return c;
+    });
+    return lc ? { ...layout, Controls: controls } : layout;
+  });
+  return changed ? { ...node, Dialog: { ...node.Dialog, Layouts: newLayouts } } : node;
+}
+
+// Combo/Search 데이터바인딩 보정 2종 (기존 필드 복사 — 발명 아님):
+//  1. display-key 보정 ([display-key] cross-check) — 본체가 표시값을 못 정하는 케이스.
+//     needsDisplay 컨텍스트(Search 본체 항상 / Combo 는 자식 ComboList UseDataSource!==false)
+//     에서 DisplayType!=='DisplayValue'(표현식은 발명 불가) + CtrlDisplayCkey 비어있으면
+//     본체 Ckeys 의 표시키(마지막 원소 = [값키,표시키])를 CtrlDisplayCkey 로 등록.
+//  2. DataSourceName 본체→자식 (Combo 한정 — Search 본체엔 DataSourceName 없음, 자식 List 가 원천).
+//     본체에 DataSourceName 있고 자식 ComboList 에 없으면 복사 (자식 required 누락 방지).
+function canonicalizeDialogDataBinding(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const innerType = DIALOG_INNER_TYPE[node.ControlType];
+  if (!innerType) return node;
+  let out = node;
+  const mut = () => { if (out === node) out = { ...node }; };
+  const layouts = node?.Dialog?.Layouts;
+  const filled = (v) => typeof v === "string" && v.length > 0;
+
+  // needsDisplay (checkDisplayCkey 와 동일 기준)
+  let needsDisplay = node.ControlType === "Search";
+  if (node.ControlType === "Combo" && Array.isArray(layouts)) {
+    for (const layout of layouts) for (const inner of (layout?.Controls ?? [])) {
+      if (inner && inner.ControlType === "ComboList" && inner.UseDataSource !== false) needsDisplay = true;
+    }
+  }
+
+  // 1. display-key 보정
+  if (needsDisplay) {
+    const dt = node.DisplayType;
+    if (dt !== "DisplayValue" && !filled(node.CtrlDisplayCkey) &&
+        (dt === "CtrlDisplayCkey" || !filled(node.DisplayValue)) &&
+        Array.isArray(node.Ckeys) && node.Ckeys.length > 0) {
+      const disp = node.Ckeys[node.Ckeys.length - 1]; // [값키, 표시키]
+      if (typeof disp === "string" && disp !== "") { mut(); out.CtrlDisplayCkey = disp; }
+    }
+  }
+
+  // 1b. 고정모드(ComboList UseDataSource:false) — 본체 CtrlDisplayCkey 를 자식 SaveNameKey/SaveValueKey 와 정합.
+  //     "보여지는 콜렉션키(CtrlDisplayCkey) ↔ 저장 name 키(SaveNameKey)" 연결을 결정적으로 보장.
+  //     누락이면 SaveNameKey(없으면 SaveValueKey)로 채우고, 불일치면 교정 (기존 필드 복사 — 발명 아님).
+  //     고정모드는 needsDisplay 제외라 보정 1 이 안 건드림 → 여기서 별도 처리.
+  //     ★ DisplayValue:"" fallback 컨벤션 폐기(combo.md §고정데이터) — 런타임의 SaveNameKey 자동표시
+  //       의존을 제거하고 CtrlDisplayCkey 를 명시 채워, 비워두면 선택 후 본체가 빈 칸이 되는 문제 차단.
+  if (node.ControlType === "Combo" && Array.isArray(layouts) && node.DisplayType !== "DisplayValue") {
+    // 비어있을 때 채우는 건 DisplayValue 표현식이 없을 때만 (보정 1 과 동일 가드 — 표현식 표시 의도 보존).
+    const dt = node.DisplayType;
+    const canFill = dt === "CtrlDisplayCkey" || !filled(out.DisplayValue);
+    for (const layout of layouts) for (const inner of (layout?.Controls ?? [])) {
+      if (inner && inner.ControlType === "ComboList" && inner.UseDataSource === false) {
+        const snk = filled(inner.SaveNameKey) ? inner.SaveNameKey : null;
+        const svk = filled(inner.SaveValueKey) ? inner.SaveValueKey : null;
+        const fallback = snk || svk;
+        if (!fallback) continue; // SaveKey 둘 다 비면 채울 원본이 없음 ([combo-fixed] 가 별도로 잡음)
+        const cur = out.CtrlDisplayCkey;
+        const matched = cur === snk || cur === svk;
+        if (filled(cur)) {
+          // 채워져 있는데 SaveKey 와 불일치 → 교정 (표시 정합).
+          if (!matched) { mut(); out.CtrlDisplayCkey = fallback; }
+        } else if (canFill) {
+          // 비어있고 DisplayValue 표현식도 없음 → SaveNameKey 로 채워 표시키↔저장키 연결 확정.
+          mut(); out.CtrlDisplayCkey = fallback;
+        }
+      }
+    }
+  }
+
+  // 2. DataSourceName 본체→자식 (Combo)
+  const bodyDsn = node.DataSourceName;
+  if (filled(bodyDsn) && Array.isArray(layouts)) {
+    let changedL = false;
+    const newLayouts = layouts.map((layout) => {
+      if (!layout || !Array.isArray(layout.Controls)) return layout;
+      let lc = false;
+      const controls = layout.Controls.map((c) => {
+        if (c && c.ControlType === innerType && !filled(c.DataSourceName)) {
+          lc = true; changedL = true;
+          return { ...c, DataSourceName: bodyDsn };
+        }
+        return c;
+      });
+      return lc ? { ...layout, Controls: controls } : layout;
+    });
+    if (changedL) { mut(); out.Dialog = { ...node.Dialog, Layouts: newLayouts }; }
+  }
+  return out;
+}
+
+// Dialog host 자식(ComboList/List) 의 결정적·안전한 정본화. 기존 canonicalizer
+// 와 동일한 기준 — 데이터 의존적 값을 "발명" 하지 않고, 구조 신호 또는 모델이
+// 이미 명세한 필드만 사용한다. (CollectionMapper 처럼 원본 필드명을 알아야 하는
+// 매핑은 손대지 않고 schema 가 에러로 남긴다.)
+//  1. Fixed ComboList: Items 보유 + DataSourceName 없음 + UseDataSource!==false
+//     → UseDataSource:false. combo.md — 누락 시 런타임이 DataSource 모드로 오인해
+//     Items 를 무시하고 CollectionMapper 를 요구한다. Items 존재가 Fixed 의 확정
+//     신호라 발명이 아닌 구조 판정.
+//  2. KeywordSearchCkey (List, UseKeywordSearch:true, 누락): 모델이 이미 명세한
+//     표시 필드(Title) — 통상 검색 대상도 표시 필드 — 또는 자식/본체 Ckeys[0] 로
+//     채움. 기존 필드 복사라 발명 아님 (canonicalizeComboKeys 의 Ckeys 복사와 동류).
+function canonicalizeDialogInner(node) {
+  const innerType = DIALOG_INNER_TYPE[node?.ControlType];
+  if (!innerType) return node;
+  const layouts = node?.Dialog?.Layouts;
+  if (!Array.isArray(layouts)) return node;
+  const hostCkeys = Array.isArray(node.Ckeys) ? node.Ckeys : [];
+  let changed = false;
+  const newLayouts = layouts.map((layout) => {
+    if (!layout || !Array.isArray(layout.Controls)) return layout;
+    let lc = false;
+    const controls = layout.Controls.map((c) => {
+      if (!c || typeof c !== "object" || c.ControlType !== innerType) return c;
+      let out = c;
+      const set = (k, v) => { if (out === c) out = { ...c }; out[k] = v; lc = true; changed = true; };
+
+      // 1. Fixed ComboList → UseDataSource:false
+      const isFixed = Array.isArray(c.Items) && c.Items.length > 0 && !c.DataSourceName;
+      if (isFixed && c.UseDataSource !== false) set("UseDataSource", false);
+
+      // 2. KeywordSearchCkey (List)
+      if (innerType === "List" && c.UseKeywordSearch === true &&
+          (typeof c.KeywordSearchCkey !== "string" || c.KeywordSearchCkey === "")) {
+        const ckeys = (Array.isArray(c.Ckeys) && c.Ckeys.length) ? c.Ckeys : hostCkeys;
+        const kw = (typeof c.Title === "string" && c.Title) ? c.Title : (ckeys[0] || "");
+        if (kw) set("KeywordSearchCkey", kw);
+      }
+      return out;
+    });
+    return lc ? { ...layout, Controls: controls } : layout;
+  });
+  return changed ? { ...node, Dialog: { ...node.Dialog, Layouts: newLayouts } } : node;
+}
+
+// Dialog.Layouts 원소 ContentsType strip — Combo 의 Dialog(ComboList 호스트) Layout
+// 원소는 `Controls` 만 두는 게 정본 형태. 모델이 `"ContentsType":"Layout"` 을 붙이는
+// 케이스를 제거(스키마상 optional 이라 검증은 통과하나 정본 형태가 아님). Controls 등
+// 나머지 키는 그대로 보존.
+//  - ★ Combo 한정 — InputDate(calendarDialog) / Search(searchDialog) 의 Layout 원소는
+//    ContentsType:"Layout" 이 정본이므로 건드리지 않는다.
+function canonicalizeDialogLayout(node) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  if (node.ControlType !== "Combo") return node;
+  const layouts = node?.Dialog?.Layouts;
+  if (!Array.isArray(layouts)) return node;
+  let changed = false;
+  const newLayouts = layouts.map((L) => {
+    if (L && typeof L === "object" && !Array.isArray(L) && "ContentsType" in L) {
+      changed = true;
+      const { ContentsType, ...rest } = L;
+      return rest;
+    }
+    return L;
+  });
+  return changed ? { ...node, Dialog: { ...node.Dialog, Layouts: newLayouts } } : node;
+}
+
+// boolean 문자열 정본화 — 스튜디오 boolean 토글을 모델이 문자열 "true"/"false"
+// 로 쓰는 케이스를 결정적으로 교정 (schema 는 boolean 요구 → "false" 는
+// 'must be boolean' 에러). boolean 으로 쓰이는 필드명은 Use*/Is*/is* 접두 +
+// 소수 예외(아래) 로 수렴(property-data.js createXxx EditControl 진실원본).
+//  - 이름이 매칭되고 값이 정확히 "true"/"false"(공백/대소문자 무시) 일 때만 coerce.
+//    (Caption 등 자유 텍스트 오염 방지 — 이름 가드 + 값 가드 이중 안전장치.)
+//  - 전체 트리 deep-walk (style 하위객체·Contents·Dialog 등 모든 깊이 포함).
+const BOOL_FIELD_EXTRA = new Set([
+  "ExternalDB", "FlexWrap", "MatchText", "NotSeperateInnerBlock",
+  "OnlyIfNoSector", "SetCategory",
+]);
+function isBooleanFieldName(k) {
+  return /^(Use|Is|is)/.test(k) || BOOL_FIELD_EXTRA.has(k);
+}
+function coerceBooleansDeep(value) {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = value.map((v) => {
+      const r = coerceBooleansDeep(v);
+      if (r !== v) changed = true;
+      return r;
+    });
+    return changed ? next : value;
+  }
+  if (value && typeof value === "object") {
+    let changed = false;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (typeof v === "string" && isBooleanFieldName(k)) {
+        const t = v.trim().toLowerCase();
+        if (t === "true") { out[k] = true; changed = true; continue; }
+        if (t === "false") { out[k] = false; changed = true; continue; }
+      }
+      const r = coerceBooleansDeep(v);
+      if (r !== v) changed = true;
+      out[k] = r;
+    }
+    return changed ? out : value;
+  }
+  return value;
+}
+
+// display 토큰 정본화 — `{=Field}` 는 단일 중괄호 display 토큰(Caption/labeltext 등에서
+// 컬렉션 키 바인딩). 모델이 i18n 토큰 `{{...}}` 과 혼동해 `{{=Field}}` 처럼 이중 중괄호로
+// 쓰는 케이스를 결정적으로 `{=Field}` 로 교정. = 로 시작하는 이중 중괄호만 대상이라
+// 순수 i18n 토큰(`{{KEY}}`, = 없음)은 건드리지 않는다. 전체 트리 deep-walk.
+function normalizeDisplayTokensDeep(value) {
+  if (typeof value === "string") {
+    if (!value.includes("{{=")) return value;
+    const fixed = value.replace(/\{\{=([^{}]*)\}\}/g, "{=$1}");
+    return fixed !== value ? fixed : value;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = value.map((v) => { const r = normalizeDisplayTokensDeep(v); if (r !== v) changed = true; return r; });
+    return changed ? next : value;
+  }
+  if (value && typeof value === "object") {
+    let changed = false;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) { const r = normalizeDisplayTokensDeep(v); if (r !== v) changed = true; out[k] = r; }
+    return changed ? out : value;
+  }
+  return value;
+}
+
+// GridHeader 정본화 — Grid DataSource 의 GridHeader 는 컬럼 키 문자열 배열
+// ["fCode", ...] 가 정본. 모델이 [{Key,Title}] 객체 배열로 쓰는 케이스를 키
+// 배열로 교정 (Title 은 컨트롤 라벨에서 표현 — 헤더는 키 매핑 전용).
+//  - 객체 원소가 하나라도 있을 때만 변환. 이미 문자열 배열이면 그대로.
+//  - Key 누락/빈 문자열 원소는 드롭(스키마가 빈 배열을 잡게).
+function normalizeGridHeaders(scenario) {
+  const ds = scenario?.DataSources;
+  if (!ds || typeof ds !== "object" || Array.isArray(ds)) return scenario;
+  let changed = false;
+  const out = {};
+  for (const [name, src] of Object.entries(ds)) {
+    if (
+      src && typeof src === "object" && !Array.isArray(src) &&
+      src.DataSourceType === "Grid" && Array.isArray(src.GridHeader) &&
+      src.GridHeader.some((h) => h && typeof h === "object" && !Array.isArray(h))
+    ) {
+      const keys = src.GridHeader
+        .map((h) => (h && typeof h === "object" && !Array.isArray(h)) ? h.Key : h)
+        .filter((k) => typeof k === "string" && k.length > 0);
+      out[name] = { ...src, GridHeader: keys };
+      changed = true;
+    } else {
+      out[name] = src;
+    }
+  }
+  return changed ? { ...scenario, DataSources: out } : scenario;
+}
+
+// DataSource 객체 구조 정본화 — 모델이 컨트롤 습관을 scenario.DataSources 에 전이하는
+// 케이스를 결정적으로 교정 (관측: DataSourceType:"Fixed" 인데 FixedItems 대신 Items +
+// DataSource 객체 안에 잉여 DataSourceName → dataSourceFixed required 위반으로 oneOf
+// 전 분기 탈락 'must match exactly one schema').
+//  1. 잉여 DataSourceName strip — DataSources 맵의 키가 이미 이름이라 객체 안 키는
+//     어느 DataSourceType 에도 미정의(잉여). 모든 타입에서 제거.
+//  2. Fixed: Items(배열) → FixedItems  (FixedItems 없고 Items 만 있을 때 리네임).
+//  3. Grid:  Items(배열) → GridItems   (GridItems 없고 Items 만 있을 때 리네임).
+function canonicalizeDataSources(scenario) {
+  const ds = scenario?.DataSources;
+  if (!ds || typeof ds !== "object" || Array.isArray(ds)) return scenario;
+  let changed = false;
+  const out = {};
+  for (const [name, src] of Object.entries(ds)) {
+    if (!src || typeof src !== "object" || Array.isArray(src)) { out[name] = src; continue; }
+    let s = src;
+    const mut = () => { if (s === src) s = { ...src }; };
+    // 1. 잉여 DataSourceName
+    if ("DataSourceName" in s) { mut(); delete s.DataSourceName; changed = true; }
+    // 2. Fixed: Items → FixedItems
+    if (s.DataSourceType === "Fixed" && !Array.isArray(s.FixedItems) && Array.isArray(s.Items)) {
+      mut(); s.FixedItems = s.Items; delete s.Items; changed = true;
+    }
+    // 3. Grid: Items → GridItems
+    if (s.DataSourceType === "Grid" && !Array.isArray(s.GridItems) && Array.isArray(s.Items)) {
+      mut(); s.GridItems = s.Items; delete s.Items; changed = true;
+    }
+    out[name] = s;
+  }
+  return changed ? { ...scenario, DataSources: out } : scenario;
+}
+
+// ScenarioTitle 정본화 — scenario.schema.json 이 const "" (가비지 슬롯, 실제 표시명은
+// fScenarioName). 모델이 화면 제목을 ScenarioTitle 에 채우는 케이스를 결정적으로 "" 로.
+function normalizeScenarioConstants(scenario) {
+  if (!scenario || typeof scenario !== "object" || Array.isArray(scenario)) return scenario;
+  if ("ScenarioTitle" in scenario && scenario.ScenarioTitle !== "") {
+    return { ...scenario, ScenarioTitle: "" };
+  }
+  return scenario;
+}
+
+// BottomButton 정본화 (bottom-buttons.schema.json) — 모델이 일반 컨트롤/Step 습관을
+// BottomButton 에 과적용하는 결정적 케이스 3종을 BottomButton 노드 한정으로 교정:
+//  (a) 잉여 토글 strip — `UseEvents`/`UseClickEvent` 는 BottomButton 에 미정의
+//      (Events:{Click:...} 단독이 canonical, 73-76행). 컨트롤/Step 에선 유효 → 전역 금지.
+//  (b) Prev 주입 — `MoveTo`∈{Prev,Prev_ReStart} 면 top-level `Prev` 필수
+//      (if/then). 누락 시 canonical 빈 객체 `{MoveStepOrder:[]}` 주입.
+//  (c) Next 슬롯 정본화 — `Next.Step{N}` 슬롯 값은 canonical 빈 문자열 `""`.
+//      모델이 객체(`{Condition,MoveTo,Direction}`)를 넣는 케이스를 `""` 로 (MoveStepOrder 배열 유지).
+function normalizeBottomButtons(scenario) {
+  const steps = scenario?.Steps;
+  if (!steps || typeof steps !== "object" || Array.isArray(steps)) return scenario;
+  let changed = false;
+  const newSteps = {};
+  for (const [stepId, step] of Object.entries(steps)) {
+    const bb = step?.BottomButtons;
+    if (!Array.isArray(bb)) { newSteps[stepId] = step; continue; }
+    let stepChanged = false;
+    const cleaned = bb.map((b) => {
+      if (!b || typeof b !== "object" || Array.isArray(b)) return b;
+      let out = b;
+      const mut = () => { if (out === b) out = { ...b }; };
+      // (a) 잉여 토글
+      for (const tog of ["UseEvents", "UseClickEvent"]) {
+        if (tog in out) { mut(); delete out[tog]; }
+      }
+      // (b) Prev 주입
+      if ((out.MoveTo === "Prev" || out.MoveTo === "Prev_ReStart") &&
+          !(out.Prev && typeof out.Prev === "object" && !Array.isArray(out.Prev))) {
+        mut(); out.Prev = { MoveStepOrder: [] };
+      }
+      // (c) Next 슬롯 객체 → ""
+      if (out.Next && typeof out.Next === "object" && !Array.isArray(out.Next)) {
+        let nx = out.Next;
+        for (const [k, v] of Object.entries(out.Next)) {
+          if (/^Step[1-9][0-9]*$/.test(k) && typeof v !== "string") {
+            if (nx === out.Next) nx = { ...out.Next };
+            nx[k] = "";
+          }
+        }
+        if (nx !== out.Next) { mut(); out.Next = nx; }
+      }
+      if (out !== b) stepChanged = true;
+      return out;
+    });
+    if (stepChanged) { newSteps[stepId] = { ...step, BottomButtons: cleaned }; changed = true; }
+    else newSteps[stepId] = step;
+  }
+  return changed ? { ...scenario, Steps: newSteps } : scenario;
+}
+
+function materializeNode(node, ctx, registry, path, errors, counters) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+
+  // raw control / raw group 우선 — 패턴 이름 검사 전에 단정.
+  if ("ControlType" in node || node.ContentsType === "Group") {
+    counters.rawPassed += 1;
+    // design 키 expand — 자식 컨테이너 재귀 전에 처리해 raw style fields 가
+    // 머지된 노드를 가지고 walk 한다. (design 키 자체는 결과에서 제거.)
+    const {
+      control: expanded,
+      sourceMap: designSm,
+      errors: designErrors,
+    } = applyDesign(node, path);
+    if (designErrors.length > 0) {
+      errors.push(...designErrors);
+    }
+    if (Object.keys(designSm).length > 0) {
+      counters.designsApplied += 1;
+      ctx.designSourceMaps[path] = designSm;
+    }
+    // 컨트롤 enum + DataConnection + AllowExtensions + InputFile InnerCKey + Combo Ckeys + Dialog 자식
+    // 정본화 — 자식 재귀 전에. (canonicalizeComboKeys 가 host→자식 Ckeys 동기화를
+    // 먼저 한 뒤 canonicalizeDialogInner 가 그 Ckeys 를 활용.)
+    const normalized = canonicalizeDialogLayout(
+      canonicalizeDialogInner(
+        canonicalizeDialogDataBinding(
+          canonicalizeComboKeys(
+            canonicalizeItemFields(
+              canonicalizeInputFileInnerCKey(
+                canonicalizeAllowExtensions(
+                  canonicalizeDataConnection(canonicalizeLabelType(canonicalizeControlEnums(expanded))),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+    return recurseContainer(normalized, ctx, registry, path, errors, counters);
+  }
+
+  // 단일 key 객체 → 패턴 후보.
+  const keys = Object.keys(node);
+  if (keys.length === 1) {
+    const patternName = keys[0];
+    const entry = registry.get(patternName);
+    if (entry) {
+      const props = node[patternName];
+      if (!props || typeof props !== "object" || Array.isArray(props)) {
+        errors.push({
+          kind: "materialize",
+          phase: "props-shape",
+          path,
+          patternName,
+          tier: entry.tier,
+          propsSnapshot: propsSnapshot(props),
+          message: `pattern '${patternName}' 의 props 가 객체가 아님 (받은 타입: ${Array.isArray(props) ? "array" : typeof props}).`,
+          hint: `호출 shape: { "${patternName}": { ...props } }. props 는 반드시 plain object — array / string / null 불가.`,
+          nextStep: `get_pattern({ name: "${patternName}" }) 로 정확한 props 스키마 확인.`,
+        });
+        return null;
+      }
+      let result;
+      try {
+        result = entry.materialize(props, ctx);
+      } catch (e) {
+        errors.push({
+          kind: "materialize",
+          phase: "factory-throw",
+          path,
+          patternName,
+          tier: entry.tier,
+          propsSnapshot: propsSnapshot(props),
+          message: `pattern '${patternName}' (${entry.tier}) materialize 실패: ${e.message}`,
+          hint: e.message?.includes("unknown")
+            ? `enum / 미등록 값일 가능성 — 에러 메시지의 값 vs 스키마 enum 비교.`
+            : e.message?.includes("필수") || e.message?.includes("required")
+              ? `필수 prop 누락 — 에러 메시지의 prop 이름 확인.`
+              : `pattern 의 materializer 가 props 를 거부함 — 에러 메시지 참고.`,
+          nextStep: `get_pattern({ name: "${patternName}", tier: "${entry.tier}" }) 로 properties/required/allOf 확인 후 props 재구성.`,
+        });
+        return null;
+      }
+      counters.patternsApplied += 1;
+      // 패턴 결과는 fully-materialized 라 추가 walk 불필요 (development.md §6).
+      return result;
+    }
+    // 단일 key 인데 알려진 패턴이 아님 → raw 객체로 간주 (false-positive 방지).
+    // 예: ScenarioMeta, dataConnection 의 단일 카테고리 키 등.
+    // 단, "패턴처럼 보이는" 단일 key 가 actually raw 일 때 LLM 이 헷갈리지 않도록
+    // 후보 제안은 응답에 직접 푸시하지 않고 (raw 처리 우선) recurse 만 함.
+    return recurseContainer(node, ctx, registry, path, errors, counters);
+  }
+
+  // 다중 key 객체 → raw passthrough, 컨테이너 필드만 재귀.
+  return recurseContainer(node, ctx, registry, path, errors, counters);
+}
+
+/**
+ * Raw 객체의 컨테이너 필드(Contents / Dialog.Layouts[*].Controls)만 좁게 재귀.
+ * 일반 속성 객체(FontStyle 등)에는 들어가지 않는다.
+ */
+function recurseContainer(node, ctx, registry, path, errors, counters) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  const out = { ...node };
+
+  if (Array.isArray(out.Contents)) {
+    out.Contents = out.Contents.map((c, i) =>
+      materializeNode(c, ctx, registry, `${path}.Contents[${i}]`, errors, counters),
+    );
+  }
+
+  // Step 의 FixedContentsTop/Bottom 도 walking — 그 안에 박힌 pattern invocation
+  // 도 materialize. (Group 노드는 이 키들을 갖지 않으므로 if 가드로 안전.)
+  for (const key of ["FixedContentsTop", "FixedContentsBottom"]) {
+    if (Array.isArray(out[key])) {
+      out[key] = out[key].map((c, i) =>
+        materializeNode(c, ctx, registry, `${path}.${key}[${i}]`, errors, counters),
+      );
+    }
+  }
+
+  if (out.Dialog && typeof out.Dialog === "object" && Array.isArray(out.Dialog.Layouts)) {
+    out.Dialog = {
+      ...out.Dialog,
+      Layouts: out.Dialog.Layouts.map((layout, li) => {
+        if (!layout || typeof layout !== "object" || !Array.isArray(layout.Controls)) {
+          return layout;
+        }
+        return {
+          ...layout,
+          Controls: layout.Controls.map((c, ci) =>
+            materializeNode(
+              c,
+              ctx,
+              registry,
+              `${path}.Dialog.Layouts[${li}].Controls[${ci}]`,
+              errors,
+              counters,
+            ),
+          ),
+        };
+      }),
+    };
+  }
+
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Auto-wrap — Step 컨테이너 children 의 Control 결과를 Group 으로 감싼다.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Step.{Contents, FixedContentsTop, FixedContentsBottom} 은 schema 가
+ * Group[] 만 받음 (scenario.schema.json / step.schema.json 의
+ * `items: { $ref: "group.schema.json" }`).
+ *
+ * 그런데 atom 패턴 (button, badge, checkbox, switch, segmented-radio) 은
+ * Control (Label / CheckBox / RadioBox) 을 emit 한다. molecule 패턴은 Group 을
+ * emit 해서 OK. LLM 이 raw Control 을 Step.Contents 에 직접 박는 경우도 동일 문제.
+ *
+ * 해결: Step 컨테이너 entry 위치에서 결과가 Control 이면 단일-자식 Group 으로
+ * 자동 wrap. molecule 결과 (이미 Group) 와 raw Group 은 통과.
+ *
+ * Wrap Group 의 ContentsName: `Wrap${ControlName||"Auto"}` 로 의미 부여.
+ */
+function autoWrapStepChild(node, ctx) {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return node;
+  // 이미 Group → wrap 불필요.
+  if (node.ContentsType === "Group") return node;
+  // Control 이 아니면 (예: null, 잘못된 노드) → 통과 — schema 가 알아서 거부.
+  if (!node.ControlType) return node;
+
+  const baseName = String(node.ControlName || node.ControlName2 || "Auto");
+  return {
+    ...makeGroup({ name: `Wrap${baseName}`, children: [node] }),
+    Id: generateId(ctx),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public: 시나리오 전체 materialize
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 시나리오 JSON 을 받아 mixed input 을 풀 메타데이터로 변환.
+ *
+ * 동작:
+ * - 시나리오 루트 객체는 그대로 보존 (Steps, ScenarioMeta, ServiceBinding 등 키 유지).
+ * - Steps[*].Contents 와 Steps[*].Contents[*] 의 하위 컨테이너 (Group.Contents,
+ *   Dialog.Layouts[*].Controls) 를 walk 하면서 pattern invocation 을 치환.
+ * - Step-level 메타데이터 (StepName, BottomButtons, Next 등) 와 ScenarioMeta 는
+ *   touch 안 함 (development.md §2: 항상 raw).
+ *
+ * 응답:
+ *   {
+ *     scenario: <materialized>,
+ *     report: { patternsRegistered, patternsApplied, startMaxId, endMaxId, generatedIds },
+ *     errors: [ { kind:"materialize", path, patternName?, tier?, message }, ... ]
+ *   }
+ *
+ * errors 가 비어있지 않더라도 부분 결과 (scenario) 는 반환 — 호출자가 fail-fast
+ * 정책으로 검증 단계 진입 여부 결정.
+ */
+export async function materializeScenario(scenario) {
+  let registry;
+  try {
+    registry = await loadRegistry();
+  } catch (e) {
+    return {
+      scenario,
+      report: { patternsRegistered: 0, patternsApplied: 0, startMaxId: 0, endMaxId: 0, generatedIds: 0 },
+      errors: [
+        {
+          kind: "materialize",
+          path: "$",
+          message: `registry load failed: ${e.message}`,
+        },
+      ],
+    };
+  }
+
+  if (!scenario || typeof scenario !== "object" || Array.isArray(scenario)) {
+    return {
+      scenario,
+      report: { patternsRegistered: registry.size, patternsApplied: 0, startMaxId: 0, endMaxId: 0, generatedIds: 0 },
+      errors: [
+        {
+          kind: "materialize",
+          path: "$",
+          message: "scenario 는 object 여야 함.",
+        },
+      ],
+    };
+  }
+
+  const errors = [];
+  const counters = {
+    patternsApplied: 0,
+    rawPassed: 0,
+    autoWrapped: 0,
+    designsApplied: 0,
+  };
+  const startMaxId = findMaxId(scenario);
+  const ctx = {
+    idCounter: { current: startMaxId },
+    designSourceMaps: {},
+  };
+
+  const out = { ...scenario };
+  if (out.Steps && typeof out.Steps === "object" && !Array.isArray(out.Steps)) {
+    const newSteps = {};
+    for (const [stepId, step] of Object.entries(out.Steps)) {
+      if (!step || typeof step !== "object" || Array.isArray(step)) {
+        newSteps[stepId] = step;
+        continue;
+      }
+      // 1) 각 Step 의 children (Contents / FixedContentsTop / FixedContentsBottom)
+      //    + Dialog 의 pattern invocation 을 materialize.
+      const materialized = recurseContainer(
+        step,
+        ctx,
+        registry,
+        `Steps.${stepId}`,
+        errors,
+        counters,
+      );
+      // 2) Step 의 세 가지 children 컨테이너는 schema 가 Group[] 만 받으므로
+      //    Control 결과 (atom 패턴 출력 또는 raw Control) 를 Group 으로 자동 wrap.
+      for (const key of STEP_CONTAINER_KEYS) {
+        if (!Array.isArray(materialized[key])) continue;
+        materialized[key] = materialized[key].map((item) => {
+          const wrapped = autoWrapStepChild(item, ctx);
+          if (wrapped !== item) counters.autoWrapped += 1;
+          return wrapped;
+        });
+      }
+      // 3) BottomButtons 는 ControlType/Group 이 아니라 recurseContainer 의 design
+      //    expand 를 안 탄다. design 키가 residual 로 남으므로 (strict 'design' 미정의)
+      //    여기서 applyDesign 으로 raw 스타일 키(Width/BgStyle/...)로 expand.
+      if (Array.isArray(materialized.BottomButtons)) {
+        materialized.BottomButtons = materialized.BottomButtons.map((b, i) => {
+          if (!b || typeof b !== "object" || Array.isArray(b) || !("design" in b)) return b;
+          const p = `Steps.${stepId}.BottomButtons.${i}`;
+          const { control, sourceMap, errors: dErrs } = applyDesign(b, p);
+          if (dErrs.length > 0) errors.push(...dErrs);
+          if (Object.keys(sourceMap).length > 0) {
+            counters.designsApplied += 1;
+            ctx.designSourceMaps[p] = sourceMap;
+          }
+          return control;
+        });
+      }
+      newSteps[stepId] = materialized;
+    }
+    out.Steps = newSteps;
+  }
+
+  // 전체 트리 후처리 — boolean 문자열 coerce + display 토큰({{=}}→{=}) + Grid
+  //   GridHeader 키배열 + ScenarioTitle const + BottomButton(토글/Prev/Next 슬롯) 정본화.
+  const finalized = normalizeScenarioConstants(
+    normalizeBottomButtons(
+      canonicalizeDataSources(normalizeGridHeaders(normalizeDisplayTokensDeep(coerceBooleansDeep(out)))),
+    ),
+  );
+
+  const endMaxId = ctx.idCounter.current;
+  return {
+    scenario: finalized,
+    report: {
+      patternsRegistered: registry.size,
+      patternsApplied: counters.patternsApplied,
+      rawNodesPassed: counters.rawPassed,
+      autoWrapped: counters.autoWrapped,
+      designsApplied: counters.designsApplied,
+      designSourceMaps: ctx.designSourceMaps,
+      startMaxId,
+      endMaxId,
+      generatedIds: endMaxId - startMaxId,
+    },
+    errors,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public: 단편 (Group / Control / Step / Scenario / pattern invocation) materialize
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * validate_fragment 가 호출하는 경량 materialize. shape 자동 판별:
+ *
+ *  - Scenario (Steps 키 보유) → materializeScenario 위임.
+ *  - Step (Contents / FixedContentsTop / FixedContentsBottom 중 하나 이상 보유,
+ *    ContentsType:'Group' 도 아니고 ControlType 도 없음) → 세 컨테이너 walking +
+ *    Control 결과 autoWrap.
+ *  - Group / Control / 단일-key pattern invocation → materializeNode 한 번.
+ *
+ * materializeScenario 와 동일한 errors / report shape 으로 응답.
+ */
+export async function materializeFragment(node) {
+  let registry;
+  try {
+    registry = await loadRegistry();
+  } catch (e) {
+    return {
+      fragment: node,
+      report: { patternsRegistered: 0, patternsApplied: 0, rawNodesPassed: 0, autoWrapped: 0, designsApplied: 0, designSourceMaps: {}, startMaxId: 0, endMaxId: 0, generatedIds: 0 },
+      errors: [
+        { kind: "materialize", path: "$", message: `registry load failed: ${e.message}` },
+      ],
+    };
+  }
+
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return {
+      fragment: node,
+      report: { patternsRegistered: registry.size, patternsApplied: 0, rawNodesPassed: 0, autoWrapped: 0, designsApplied: 0, designSourceMaps: {}, startMaxId: 0, endMaxId: 0, generatedIds: 0 },
+      errors: [
+        { kind: "materialize", path: "$", message: "fragment 는 object 여야 함." },
+      ],
+    };
+  }
+
+  // Scenario 전체가 들어온 경우 — materializeScenario 위임 (Steps 워킹 + autoWrap).
+  if (node.Steps && typeof node.Steps === "object" && !Array.isArray(node.Steps)) {
+    const r = await materializeScenario(node);
+    return { fragment: r.scenario, report: r.report, errors: r.errors };
+  }
+
+  const errors = [];
+  const counters = {
+    patternsApplied: 0,
+    rawPassed: 0,
+    autoWrapped: 0,
+    designsApplied: 0,
+  };
+  const startMaxId = findMaxId(node);
+  const ctx = {
+    idCounter: { current: startMaxId },
+    designSourceMaps: {},
+  };
+
+  // Step 모양 판별 — 컨테이너 키가 있는데 Group/Control 식별자는 없음.
+  const isStepShape =
+    !("ControlType" in node) &&
+    node.ContentsType !== "Group" &&
+    (Array.isArray(node.Contents) ||
+      Array.isArray(node.FixedContentsTop) ||
+      Array.isArray(node.FixedContentsBottom));
+
+  let out;
+  if (isStepShape) {
+    out = recurseContainer(node, ctx, registry, "$", errors, counters);
+    for (const key of STEP_CONTAINER_KEYS) {
+      if (!Array.isArray(out[key])) continue;
+      out[key] = out[key].map((item) => {
+        const wrapped = autoWrapStepChild(item, ctx);
+        if (wrapped !== item) counters.autoWrapped += 1;
+        return wrapped;
+      });
+    }
+  } else {
+    out = materializeNode(node, ctx, registry, "$", errors, counters);
+  }
+
+  const endMaxId = ctx.idCounter.current;
+  return {
+    fragment: normalizeDisplayTokensDeep(coerceBooleansDeep(out)),
+    report: {
+      patternsRegistered: registry.size,
+      patternsApplied: counters.patternsApplied,
+      rawNodesPassed: counters.rawPassed,
+      autoWrapped: counters.autoWrapped,
+      designsApplied: counters.designsApplied,
+      designSourceMaps: ctx.designSourceMaps,
+      startMaxId,
+      endMaxId,
+      generatedIds: endMaxId - startMaxId,
+    },
+    errors,
+  };
+}