@things-factory/board-ai 10.0.0-beta.108

package/dist-client/server/service/validation/tool-validation.js

@@ -0,0 +1,193 @@
+import { validateComponentPatch, validateComponent, validateBoardPatch } from './board-model-schema';
+import { buildSetFillOps } from '../styling/fill-tools';
+import { buildSetStrokeOps } from '../styling/stroke-tools';
+import { buildSetTextOps, buildSetFontOps } from '../styling/text-tools';
+import { buildSetShadowOps, buildSetOpacityOps, buildSetVisibleOps } from '../styling/effect-tools';
+import { buildSetMaterialOps, buildSetShadowPropertiesOps } from '../styling/material-tools';
+import { buildClearStyleOps } from '../styling/clear-tools';
+import { buildCopyStyleOps } from '../styling/copy-tools';
+/**
+ * write tool 의 args 사전 검증.
+ *
+ * 정책:
+ *   - styling tool: 해당 build* 함수가 errors 반환 — 그대로 LLM 한테
+ *   - modifyComponentByRefid: ComponentPatchSchema 로 검증 (raw fallback 영역)
+ *   - addComponent: ComponentSchema 로 검증
+ *   - 그 외: 기존 dispatcher 의 자체 검증에 위임 (재시도 보장 X)
+ */
+export function validateWriteToolCall(tc, components = []) {
+    const args = tc.arguments ?? {};
+    // Styling tool 들 — 각 build 함수가 detailed errors 반환
+    switch (tc.name) {
+        case 'setFill': {
+            const r = buildSetFillOps(args);
+            if (r.errors.length > 0)
+                return {
+                    valid: false,
+                    errors: r.errors,
+                    suggestion: setFillSuggestion()
+                };
+            return { valid: true };
+        }
+        case 'setStroke': {
+            const r = buildSetStrokeOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setText': {
+            const r = buildSetTextOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setFont': {
+            const r = buildSetFontOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setShadow': {
+            const r = buildSetShadowOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setOpacity': {
+            const r = buildSetOpacityOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setVisible': {
+            const r = buildSetVisibleOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setMaterial': {
+            const r = buildSetMaterialOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'setShadowProperties': {
+            const r = buildSetShadowPropertiesOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'clearStyle': {
+            const r = buildClearStyleOps(args);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        case 'copyStyle': {
+            const r = buildCopyStyleOps(args, components);
+            if (r.errors.length > 0)
+                return { valid: false, errors: r.errors };
+            return { valid: true };
+        }
+        // raw fallback — schema 검증
+        case 'modifyComponentByRefid': {
+            if (typeof args.refid !== 'number') {
+                return { valid: false, errors: ['refid (number) is required'] };
+            }
+            if (!args.patch || typeof args.patch !== 'object') {
+                return { valid: false, errors: ['patch (object) is required'] };
+            }
+            const v = validateComponentPatch(args.patch);
+            if (!v.valid) {
+                return {
+                    valid: false,
+                    errors: formatValidationErrors(v),
+                    suggestion: modifyPatchSuggestion()
+                };
+            }
+            return { valid: true };
+        }
+        case 'addComponent': {
+            const v = validateComponent(args);
+            if (!v.valid) {
+                return {
+                    valid: false,
+                    errors: formatValidationErrors(v)
+                };
+            }
+            return { valid: true };
+        }
+        case 'modifyBoard': {
+            // 보드 root partial 검증 — fillStyle/shadow 같은 nested 의 strict schema 가
+            // unknown key (e.g. fillStyle.gradientStops 같은 stale 이름) 를 거부.
+            // 이게 마지막 방어선 — 다른 styling tool 에서 학습된 vocabulary 가 leak 되면 catch.
+            if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch)) {
+                return { valid: false, errors: ['patch (object) is required'] };
+            }
+            const v = validateBoardPatch(args.patch);
+            if (!v.valid) {
+                return {
+                    valid: false,
+                    errors: formatValidationErrors(v),
+                    suggestion: modifyBoardSuggestion()
+                };
+            }
+            return { valid: true };
+        }
+        case 'replaceBoard': {
+            // 보드 통째 교체 — 영속 직전 가장 강력한 검증 필요. components 까지 한 번에
+            // 검사. 자식 컴포넌트의 fillStyle.gradientStops 같은 stale 키도 즉시 catch.
+            // (BoardPatchSchema 는 component 도 array 로 통과시키되 ComponentSchema 가
+            // strict styling sub-objects 로 stale 차단.)
+            const v = validateBoardPatch(args);
+            if (!v.valid) {
+                return {
+                    valid: false,
+                    errors: formatValidationErrors(v),
+                    suggestion: modifyBoardSuggestion()
+                };
+            }
+            return { valid: true };
+        }
+        // 그 외 — 기존 dispatcher 검증에 위임
+        default:
+            return { valid: true };
+    }
+}
+function modifyBoardSuggestion() {
+    return ('modifyBoard 의 patch 는 things-scene 의 model-layer 가 인식하는 root key 만 사용. ' +
+        'fillStyle / strokeStyle / shadow 같은 nested object 의 안쪽 필드는 canonical 이름 (colorStops 등) 정확히 사용. ' +
+        'rect 등 자식 컴포넌트 변경은 modifyComponentByRefid 로 분리.');
+}
+function formatValidationErrors(v) {
+    if (v.valid || !v.errors)
+        return [];
+    return v.errors.map(e => `${e.path || '<root>'}: ${e.message}`);
+}
+/**
+ * setFill 정정 가이드 — 자주 실수하는 패턴 + 올바른 예시.
+ */
+function setFillSuggestion() {
+    return [
+        'Valid setFill patterns:',
+        "  - Solid: { refids:[35], mode:'solid', color:'#ff0000' }",
+        "  - Gradient: { refids:[35], mode:'gradient', gradientType:'linear', " +
+            "colorStops:[{position:0,color:'#ff0000'},{position:1,color:'#0000ff'}], rotation:90 }",
+        "  - Pattern: { refids:[35], mode:'pattern', image:'url' }",
+        "  - Partial color update: { refids:[35], color:'green' }  // mode 미지정",
+        'Notes:',
+        '  - rotation 은 degrees 로 입력 (서버가 라디안으로 변환해 fillStyle.rotation 에 저장)',
+        '  - colorStops 는 { position: 0..1, color: hex/rgb/named } 객체 배열',
+        '  - 옛 이름 (colors / stops / gradientStops) 사용 금지 — engine canonical 은 colorStops'
+    ].join('\n');
+}
+function modifyPatchSuggestion() {
+    return [
+        'modifyComponentByRefid is the raw fallback — prefer specific styling tools (setFill/setStroke/setText/setFont/setShadow/setMaterial/setOpacity/setVisible) for any styling change.',
+        'If you must use raw modify:',
+        '  - fillStyle string (solid) or {type:"gradient",gradientType,colorStops:[{position,color}]} or {type:"pattern",image,...}',
+        '  - shadow {color, offsetX, offsetY, blur}  (CSS box-shadow / Canvas 표준 이름)',
+        '  - lineDash STRING preset only (NOT number array)'
+    ].join('\n');
+}
+//# sourceMappingURL=tool-validation.js.map

package/dist-client/server/service/validation/tool-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-validation.js","sourceRoot":"","sources":["../../../../server/service/validation/tool-validation.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAWzD;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,EAAc,EACd,aAAiC,EAAE;IAEnC,MAAM,IAAI,GAAG,EAAE,CAAC,SAAS,IAAI,EAAE,CAAA;IAE/B,kDAAkD;IAClD,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,eAAe,CAAC,IAAW,CAAC,CAAA;YACtC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBACrB,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,UAAU,EAAE,iBAAiB,EAAE;iBAChC,CAAA;YACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAW,CAAC,CAAA;YACxC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,eAAe,CAAC,IAAW,CAAC,CAAA;YACtC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,eAAe,CAAC,IAAW,CAAC,CAAA;YACtC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAW,CAAC,CAAA;YACxC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAW,CAAC,CAAA;YACzC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAW,CAAC,CAAA;YACzC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAW,CAAC,CAAA;YAC1C,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,CAAC,GAAG,2BAA2B,CAAC,IAAW,CAAC,CAAA;YAClD,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAW,CAAC,CAAA;YACzC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAW,EAAE,UAAU,CAAC,CAAA;YACpD,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;YAClE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QAED,2BAA2B;QAC3B,KAAK,wBAAwB,CAAC,CAAC,CAAC;YAC9B,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACnC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAA;YACjE,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAA;YACjE,CAAC;YACD,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAC5C,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;oBACjC,UAAU,EAAE,qBAAqB,EAAE;iBACpC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAA;YACjC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;iBAClC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,oEAAoE;YACpE,+DAA+D;YAC/D,kEAAkE;YAClE,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC/E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAA;YACjE,CAAC;YACD,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACxC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;oBACjC,UAAU,EAAE,qBAAqB,EAAE;iBACpC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,oDAAoD;YACpD,6DAA6D;YAC7D,kEAAkE;YAClE,0CAA0C;YAC1C,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;YAClC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;oBACjC,UAAU,EAAE,qBAAqB,EAAE;iBACpC,CAAA;YACH,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACxB,CAAC;QAED,6BAA6B;QAC7B;YACE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC1B,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB;IAC5B,OAAO,CACL,yEAAyE;QACzE,iGAAiG;QACjG,iDAAiD,CAClD,CAAA;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,CAAmB;IACjD,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACnC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAA;AACjE,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB;IACxB,OAAO;QACL,yBAAyB;QACzB,2DAA2D;QAC3D,uEAAuE;YACrE,uFAAuF;QACzF,2DAA2D;QAC3D,uEAAuE;QACvE,QAAQ;QACR,qEAAqE;QACrE,iEAAiE;QACjE,iFAAiF;KAClF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,SAAS,qBAAqB;IAC5B,OAAO;QACL,oLAAoL;QACpL,6BAA6B;QAC7B,4HAA4H;QAC5H,6EAA6E;QAC7E,oDAAoD;KACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC","sourcesContent":["/**\n * Write tool 의 사전 검증 — agentic loop 의 retry 메커니즘.\n *\n * 흐름:\n *   1. LLM 이 write tool 호출\n *   2. 본 함수가 args 검증 (styling tool 의 build* 함수 또는 schema 직접)\n *   3. 실패 시 errors 반환 → caller 가 tool_result 에 error 메시지 담아 LLM 한테\n *   4. LLM 다음 turn 에서 정정 후 재호출 (자기 회복)\n *\n * 이게 silent 데이터 손상을 막는 마지막 능동 방어선. 검증 통과한 args 만 누적\n * → patch 로 변환되므로 깨진 데이터가 영속까지 못 감.\n */\nimport type { AIToolCall } from '@things-factory/ai-client-base'\nimport {\n  validateComponentPatch,\n  validateComponent,\n  validateBoardPatch,\n  type ValidationResult\n} from './board-model-schema'\nimport { buildSetFillOps } from '../styling/fill-tools'\nimport { buildSetStrokeOps } from '../styling/stroke-tools'\nimport { buildSetTextOps, buildSetFontOps } from '../styling/text-tools'\nimport {\n  buildSetShadowOps,\n  buildSetOpacityOps,\n  buildSetVisibleOps\n} from '../styling/effect-tools'\nimport {\n  buildSetMaterialOps,\n  buildSetShadowPropertiesOps\n} from '../styling/material-tools'\nimport { buildClearStyleOps } from '../styling/clear-tools'\nimport { buildCopyStyleOps } from '../styling/copy-tools'\n\nexport interface ToolValidationResult {\n  /** 검증 통과 — 누적 진행 가능 */\n  valid: boolean\n  /** 실패 시 LLM 한테 보일 에러 메시지 (자기 회복 정보 포함) */\n  errors?: string[]\n  /** LLM 한테 정정 가이드 — 가능한 경우 어떤 형식이 맞는지 */\n  suggestion?: string\n}\n\n/**\n * write tool 의 args 사전 검증.\n *\n * 정책:\n *   - styling tool: 해당 build* 함수가 errors 반환 — 그대로 LLM 한테\n *   - modifyComponentByRefid: ComponentPatchSchema 로 검증 (raw fallback 영역)\n *   - addComponent: ComponentSchema 로 검증\n *   - 그 외: 기존 dispatcher 의 자체 검증에 위임 (재시도 보장 X)\n */\nexport function validateWriteToolCall(\n  tc: AIToolCall,\n  components: ReadonlyArray<any> = []\n): ToolValidationResult {\n  const args = tc.arguments ?? {}\n\n  // Styling tool 들 — 각 build 함수가 detailed errors 반환\n  switch (tc.name) {\n    case 'setFill': {\n      const r = buildSetFillOps(args as any)\n      if (r.errors.length > 0)\n        return {\n          valid: false,\n          errors: r.errors,\n          suggestion: setFillSuggestion()\n        }\n      return { valid: true }\n    }\n    case 'setStroke': {\n      const r = buildSetStrokeOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setText': {\n      const r = buildSetTextOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setFont': {\n      const r = buildSetFontOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setShadow': {\n      const r = buildSetShadowOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setOpacity': {\n      const r = buildSetOpacityOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setVisible': {\n      const r = buildSetVisibleOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setMaterial': {\n      const r = buildSetMaterialOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'setShadowProperties': {\n      const r = buildSetShadowPropertiesOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'clearStyle': {\n      const r = buildClearStyleOps(args as any)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n    case 'copyStyle': {\n      const r = buildCopyStyleOps(args as any, components)\n      if (r.errors.length > 0) return { valid: false, errors: r.errors }\n      return { valid: true }\n    }\n\n    // raw fallback — schema 검증\n    case 'modifyComponentByRefid': {\n      if (typeof args.refid !== 'number') {\n        return { valid: false, errors: ['refid (number) is required'] }\n      }\n      if (!args.patch || typeof args.patch !== 'object') {\n        return { valid: false, errors: ['patch (object) is required'] }\n      }\n      const v = validateComponentPatch(args.patch)\n      if (!v.valid) {\n        return {\n          valid: false,\n          errors: formatValidationErrors(v),\n          suggestion: modifyPatchSuggestion()\n        }\n      }\n      return { valid: true }\n    }\n    case 'addComponent': {\n      const v = validateComponent(args)\n      if (!v.valid) {\n        return {\n          valid: false,\n          errors: formatValidationErrors(v)\n        }\n      }\n      return { valid: true }\n    }\n    case 'modifyBoard': {\n      // 보드 root partial 검증 — fillStyle/shadow 같은 nested 의 strict schema 가\n      // unknown key (e.g. fillStyle.gradientStops 같은 stale 이름) 를 거부.\n      // 이게 마지막 방어선 — 다른 styling tool 에서 학습된 vocabulary 가 leak 되면 catch.\n      if (!args.patch || typeof args.patch !== 'object' || Array.isArray(args.patch)) {\n        return { valid: false, errors: ['patch (object) is required'] }\n      }\n      const v = validateBoardPatch(args.patch)\n      if (!v.valid) {\n        return {\n          valid: false,\n          errors: formatValidationErrors(v),\n          suggestion: modifyBoardSuggestion()\n        }\n      }\n      return { valid: true }\n    }\n    case 'replaceBoard': {\n      // 보드 통째 교체 — 영속 직전 가장 강력한 검증 필요. components 까지 한 번에\n      // 검사. 자식 컴포넌트의 fillStyle.gradientStops 같은 stale 키도 즉시 catch.\n      // (BoardPatchSchema 는 component 도 array 로 통과시키되 ComponentSchema 가\n      // strict styling sub-objects 로 stale 차단.)\n      const v = validateBoardPatch(args)\n      if (!v.valid) {\n        return {\n          valid: false,\n          errors: formatValidationErrors(v),\n          suggestion: modifyBoardSuggestion()\n        }\n      }\n      return { valid: true }\n    }\n\n    // 그 외 — 기존 dispatcher 검증에 위임\n    default:\n      return { valid: true }\n  }\n}\n\nfunction modifyBoardSuggestion(): string {\n  return (\n    'modifyBoard 의 patch 는 things-scene 의 model-layer 가 인식하는 root key 만 사용. ' +\n    'fillStyle / strokeStyle / shadow 같은 nested object 의 안쪽 필드는 canonical 이름 (colorStops 등) 정확히 사용. ' +\n    'rect 등 자식 컴포넌트 변경은 modifyComponentByRefid 로 분리.'\n  )\n}\n\nfunction formatValidationErrors(v: ValidationResult): string[] {\n  if (v.valid || !v.errors) return []\n  return v.errors.map(e => `${e.path || '<root>'}: ${e.message}`)\n}\n\n/**\n * setFill 정정 가이드 — 자주 실수하는 패턴 + 올바른 예시.\n */\nfunction setFillSuggestion(): string {\n  return [\n    'Valid setFill patterns:',\n    \"  - Solid: { refids:[35], mode:'solid', color:'#ff0000' }\",\n    \"  - Gradient: { refids:[35], mode:'gradient', gradientType:'linear', \" +\n      \"colorStops:[{position:0,color:'#ff0000'},{position:1,color:'#0000ff'}], rotation:90 }\",\n    \"  - Pattern: { refids:[35], mode:'pattern', image:'url' }\",\n    \"  - Partial color update: { refids:[35], color:'green' }  // mode 미지정\",\n    'Notes:',\n    '  - rotation 은 degrees 로 입력 (서버가 라디안으로 변환해 fillStyle.rotation 에 저장)',\n    '  - colorStops 는 { position: 0..1, color: hex/rgb/named } 객체 배열',\n    '  - 옛 이름 (colors / stops / gradientStops) 사용 금지 — engine canonical 은 colorStops'\n  ].join('\\n')\n}\n\nfunction modifyPatchSuggestion(): string {\n  return [\n    'modifyComponentByRefid is the raw fallback — prefer specific styling tools (setFill/setStroke/setText/setFont/setShadow/setMaterial/setOpacity/setVisible) for any styling change.',\n    'If you must use raw modify:',\n    '  - fillStyle string (solid) or {type:\"gradient\",gradientType,colorStops:[{position,color}]} or {type:\"pattern\",image,...}',\n    '  - shadow {color, offsetX, offsetY, blur}  (CSS box-shadow / Canvas 표준 이름)',\n    '  - lineDash STRING preset only (NOT number array)'\n  ].join('\\n')\n}\n"]}