@things-factory/ai-assistant 10.1.24 → 10.1.26

package/docs/session-controller.md

@@ -41,7 +41,7 @@ Shared chat accepts synchronous `contextProvider(): {systemPrompt?, hostContext?
 
 `autoAskRequestId` distinguishes repeated identical user requests; generate it per user submission, not per render. Without it, legacy text-based deduplication remains.
 
-`board-edit-patch` and `board-action-execute` include local `detail.requestBase = {version: 1, sessionId, hostContext, modelFingerprint}`. `assistantModelFingerprint` returns a deterministic JSON signature, not a security hash. Undefined models have no signature. Hosts must validate target identity and compare the current model signature before applying a proposal. This metadata is not persisted into restored history; missing metadata is not proof that a historical proposal is safe. The framework captures the evidence but does not implement product-specific application guards.
+`scene-edit-patch` and `scene-action-execute` include local `detail.requestBase = {version: 1, sessionId, hostContext, modelFingerprint}`. `assistantModelFingerprint` returns a deterministic JSON signature, not a security hash. Undefined models have no signature. Hosts must validate target identity and compare the current model signature before applying a proposal. This metadata is not persisted into restored history; missing metadata is not proof that a historical proposal is safe. The framework captures the evidence but does not implement product-specific application guards.
 
 Figure browser verification after toolbar migration: selected old session, reset to session 3, observed sessions 1 and 2 retained; screenshot confirmed aligned controls. Models were not edited. Plant runtime validation is owned by its development task. Legacy Board forwarding has source-contract coverage, not full Board browser coverage.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.24",
+  "version": "10.1.26",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -29,10 +29,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.20",
-    "@things-factory/auth-base": "^10.1.24",
+    "@things-factory/ai-client-base": "^10.1.26",
+    "@things-factory/auth-base": "^10.1.26",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.20",
+    "@things-factory/shell": "^10.1.26",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "0d88a504e0ffa63cd91279b88c6998d4bf1b3d86"
+  "gitHead": "151bda14d899442c6846532ddded1e2bfe23a2f5"
 }

package/server/index.ts

@@ -26,3 +26,4 @@
  * 설계 정본은 `things-factory/docs/design/ai-modules.md`.
  */
 export * from './service/index.js'
+import './tool-registry-boot-report.js'

package/server/service/assistant-chat-resolver.ts

@@ -37,6 +37,7 @@ import { buildLlmHistory } from './chat-message/llm-history.js'
 import { publishChatMessage } from './chat-message/chat-message-publish.js'
 import { publishSessionActivity } from './chat-session/session-activity-publish.js'
 import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
+import { toolAccessFor } from './tool-access.js'
 
 /**
  * How many stored messages reach the model.
@@ -79,7 +80,7 @@ class AssistantChatInput {
   @Field(() => [String], {
     nullable: true,
     description:
-      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omit to allow every registered category. An empty list allows none — a plain conversation.'
+      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omitted or empty allows none — a plain conversation. A tool that declares a privilege is offered only to a caller who holds it.'
   })
   toolCategories?: string[]
 
@@ -292,6 +293,7 @@ export class AssistantChatResolver {
       messages: conversation as any,
       systemPrompt: input.systemPrompt,
       toolCategories: input.toolCategories,
+      toolAccess: toolAccessFor(context),
       hostContext: input.hostContext,
       state: context.state,
       model: input.model,

package/server/service/index.ts

@@ -9,6 +9,7 @@ import { entities as ChatSessionParticipantEntities } from './chat-session-parti
 export * from './types.js'
 export * from './chat-session-resolver.js'
 export * from './assistant-chat-resolver.js'
+export * from './tool-access.js'
 export * from './subscribe-auth.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
 export * from './chat-session/session-anchor.js'

package/server/service/tool-access.test.ts

@@ -0,0 +1,48 @@
+/*
+ * What this guards: a registered tool is asked the same question its GraphQL door asks.
+ *
+ * The tool declares `{ category, privilege }`; `@privilege` on the door runs `checkPermission`
+ * with the request's user, domain, address safety and prohibited list. If this passed fewer of
+ * those — say, dropped `unsafeIP` — the tool would be a softer way into the same door.
+ */
+const mockCheckPermission = jest.fn()
+jest.mock('@things-factory/auth-base', () => ({ checkPermission: (...a: any[]) => mockCheckPermission(...a) }))
+
+import { toolAccessFor } from './tool-access'
+
+const state = {
+  domain: { id: 'dom-1' },
+  user: { id: 'u-1' },
+  unsafeIP: true,
+  prohibitedPrivileges: [{ category: 'board-import', privilege: 'mutation' }]
+}
+
+beforeEach(() => mockCheckPermission.mockReset())
+
+it('★ asks checkPermission with the declared privilege and everything the door would pass', async () => {
+  mockCheckPermission.mockResolvedValue(true)
+
+  const allowed = await toolAccessFor({ state })({ category: 'board-import', privilege: 'mutation', owner: true })
+
+  expect(allowed).toBe(true)
+  expect(mockCheckPermission).toHaveBeenCalledWith(
+    { category: 'board-import', privilege: 'mutation', owner: true, super: undefined },
+    state.user,
+    state.domain,
+    true,
+    state.prohibitedPrivileges
+  )
+})
+
+it('a refusal is a refusal', async () => {
+  mockCheckPermission.mockResolvedValue(false)
+  expect(await toolAccessFor({ state })({ category: 'board-import', privilege: 'query' })).toBe(false)
+})
+
+it('★ a request with no user or no domain holds no privilege, and auth is not asked', async () => {
+  const privilege = { category: 'board-import', privilege: 'query' }
+  expect(await toolAccessFor({ state: { domain: state.domain } })(privilege)).toBe(false)
+  expect(await toolAccessFor({ state: { user: state.user } })(privilege)).toBe(false)
+  expect(await toolAccessFor(undefined)(privilege)).toBe(false)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})

package/server/service/tool-access.ts

@@ -0,0 +1,27 @@
+/*
+ * Who may use a registered tool — the request's answer to `ToolAccessCheck`.
+ *
+ * `ai-client-base` decides *which* tools a conversation may use but does not know auth, so the
+ * conversation doors hand it this. A tool declares the same `{ category, privilege }` its GraphQL
+ * door uses (A1, 2026-09-17), and this asks exactly what `@privilege` on that door would ask: the
+ * same `checkPermission`, with the request's user, domain, address safety and prohibited list.
+ * Asking anything looser here would make the tool a second, softer way into that door.
+ */
+import { checkPermission } from '@things-factory/auth-base'
+import type { ToolAccessCheck, ToolPrivilege } from '@things-factory/ai-client-base'
+
+export function toolAccessFor(context: { state?: any } | undefined): ToolAccessCheck {
+  const { domain, user, unsafeIP, prohibitedPrivileges } = context?.state ?? {}
+
+  return async (privilege: ToolPrivilege) => {
+    /* No caller, no answer — a request without a user or domain holds no privilege. */
+    if (!user || !domain) return false
+    return !!(await checkPermission(
+      { category: privilege.category, privilege: privilege.privilege, owner: privilege.owner, super: privilege.super },
+      user,
+      domain,
+      unsafeIP,
+      prohibitedPrivileges
+    ))
+  }
+}

package/server/tool-registry-boot-report.test.ts

@@ -0,0 +1,18 @@
+jest.mock('@things-factory/env', () => ({ logger: { warn: jest.fn() } }))
+
+import { formatToolRegistryWarnings } from './tool-registry-boot-report'
+
+it('★ groups the recorded omissions by code and names every tool', () => {
+  const lines = formatToolRegistryWarnings([
+    { code: 'tool-privilege-undeclared', params: { category: 'twin-authoring', tool: 'bindTwinEntity', kind: 'write' }, message: '' },
+    { code: 'tool-privilege-undeclared', params: { category: 'x-ops', tool: 'runThing', kind: 'external' }, message: '' }
+  ])
+
+  expect(lines).toEqual([
+    '[ai-assistant] tool-privilege-undeclared ×2: twin-authoring/bindTwinEntity(write), x-ops/runThing(external)'
+  ])
+})
+
+it('says nothing when every tool is declared', () => {
+  expect(formatToolRegistryWarnings([])).toEqual([])
+})

package/server/tool-registry-boot-report.ts

@@ -0,0 +1,26 @@
+/*
+ * At boot, say which registered tools are not yet what the tool contract requires (A1 stage one).
+ *
+ * Registration no longer refuses a tool that changes something without declaring its privilege —
+ * refusing would stop apps whose tools predate the field. The registry records each omission as a
+ * code instead. This prints that list once, after every module has registered, grouped by code,
+ * so the person starting the server sees which tools still need a declaration. When the list is
+ * empty across the apps, registration becomes a refusal and this report goes away.
+ */
+import { logger } from '@things-factory/env'
+import { getToolRegistryWarnings, type ToolRegistryWarning } from '@things-factory/ai-client-base'
+
+/** One line per code: the code, how many, and which tools. Empty when there is nothing to report. */
+export function formatToolRegistryWarnings(warnings: ReadonlyArray<ToolRegistryWarning>): string[] {
+  const byCode = new Map<string, string[]>()
+  for (const warning of warnings) {
+    const tools = byCode.get(warning.code) ?? []
+    tools.push(`${warning.params.category}/${warning.params.tool}(${warning.params.kind})`)
+    byCode.set(warning.code, tools)
+  }
+  return [...byCode].map(([code, tools]) => `[ai-assistant] ${code} ×${tools.length}: ${tools.join(', ')}`)
+}
+
+process.on('bootstrap-module-start' as any, () => {
+  for (const line of formatToolRegistryWarnings(getToolRegistryWarnings())) logger.warn(line)
+})

package/test/assistant-request-context.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
-import { test } from 'node:test'
 import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { assistantAutoAskKey, assistantModelFingerprint, assistantRecentSessions } from '../client/utils/assistant-request-context.ts'
 
 test('model signature ignores object key order but detects nested edits and array order', () => {
@@ -21,7 +21,7 @@ test('recent tabs retain the selected older conversation without mutating the in
   assert.deepEqual(assistantRecentSessions([], '', 5), [])
 })
 test('send captures current context before optimistic input and attaches request base to edit events', () => {
-  const chat = readFileSync(new URL('../client/components/assistant-chat.ts', import.meta.url), 'utf8')
+  const chat = readFileSync(join(__dirname, '../client/components/assistant-chat.ts'), 'utf8')
   const send = chat.slice(chat.indexOf('private async send()'))
   assert.ok(send.indexOf('this.contextProvider?.()') < send.indexOf('// optimistic'))
   assert.match(send, /modelFingerprint: assistantModelFingerprint\(liveBoard\)/)

package/test/assistant-session-controller.test.ts

@@ -1,5 +1,4 @@
 import assert from 'node:assert/strict'
-import { test } from 'node:test'
 import { AssistantSessionController, type AssistantSession, type AssistantSessionTarget } from '../client/utils/assistant-session-controller.ts'
 
 const target = (id: string, scope = 'user:domain'): AssistantSessionTarget => ({ scope, anchorType: 'figure', anchorId: id })

package/test/assistant-session-toolbar.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
-import { test } from 'node:test'
-const read = (file: string) => readFileSync(new URL(file, import.meta.url), 'utf8')
+import { join } from 'node:path'
+const read = (file: string) => readFileSync(join(__dirname, file), 'utf8')
 const toolbar = read('../client/components/assistant-session-toolbar.ts')
 test('toolbar emits domain-neutral intent and never calls persistence APIs', () => {
   for (const event of ['assistant-session-select', 'assistant-session-reset', 'assistant-session-retry']) assert.ok(toolbar.includes(event))

package/client/utils/board-edit-patch.ts

@@ -1,374 +0,0 @@
-/**
- * Client-side BoardEditPatch types + applier.
- *
- * NOTE: 동일 정의가 server/service/types.ts + apply-patch.ts 에 있음.
- * client 번들이 server 코드를 import 하지 않도록 분리. 변경 시 양쪽 동기화 필요.
- */
-
-/**
- * 컴포넌트 타깃팅은 항상 `refid` (things-scene universal numeric handle).
- * `id` 는 데이터 바인딩 이름이며 unique 가 아니므로 targeting 에 사용하지 않는다.
- *
- * 보드는 최상위 부모 — 자체 속성 (fillStyle / width / height / name 등) 을 갖고,
- * `modifyBoard` 로 변경. 자식 컴포넌트 변경 (`modify`) 와 분리.
- *
- * Phase 2 — Scene 조작 op (align/distribute/group/ungroup/zorder). model 차원
- * 시뮬레이션은 noop 이고 things-scene API 가 정본.
- */
-export type AlignDirection =
-  | 'left'
-  | 'right'
-  | 'center'
-  | 'top'
-  | 'middle'
-  | 'bottom'
-
-export type DistributeAxis = 'horizontal' | 'vertical'
-
-export type ZorderDirection = 'front' | 'back' | 'forward' | 'backward'
-
-/**
- * Sugar layout — `arrange` op 의 layout 종류.
- * Server-side types.ts 의 ArrangeLayout 와 일치 — drift test 가 검증.
- */
-export type ArrangeLayout =
-  | { type: 'grid'; cols: number; gap?: number; anchor?: { left: number; top: number } }
-  | {
-      type: 'row'
-      gap?: number
-      anchor?: { left: number; top: number }
-      align?: 'start' | 'center' | 'end'
-    }
-  | {
-      type: 'column'
-      gap?: number
-      anchor?: { left: number; top: number }
-      align?: 'start' | 'center' | 'end'
-    }
-
-export type BoardEditOp =
-  | { op: 'add'; component: any }
-  | { op: 'remove'; refid: number }
-  | { op: 'modify'; refid: number; patch: any }
-  | { op: 'modifyBoard'; patch: any }
-  | { op: 'replace'; board: any }
-  | { op: 'align'; refids: number[]; direction: AlignDirection }
-  | { op: 'distribute'; refids: number[]; axis: DistributeAxis }
-  | { op: 'group'; refids: number[] }
-  | { op: 'ungroup'; refid: number }
-  | { op: 'zorder'; refid: number; direction: ZorderDirection }
-  | { op: 'arrange'; refids: number[]; layout: ArrangeLayout }
-
-/**
- * C-1 — Scene 조작 action (ephemeral). 모델 변경 X, undo 영향 X.
- * 호스트가 board-action-execute 이벤트로 받아서 things-scene API 직접 호출.
- */
-export type BoardActionOp =
-  | { action: 'selectComponents'; refids: number[] }
-  | { action: 'centerToComponent'; refid: number; animated?: boolean }
-  | { action: 'fitToView'; mode?: 'fit' | 'ratio' | 'width' | 'height' }
-  | { action: 'setSceneMode'; mode: 'edit' | 'view' }
-  | { action: 'highlightComponents'; refids: number[] }
-
-export interface BoardEditPatch {
-  ops: BoardEditOp[]
-  summary: string
-  confidence: number
-}
-
-export interface PatchApplyReport {
-  /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
-  board: any
-  /** 실제로 보드를 바꾼 op 들. */
-  applied: BoardEditOp[]
-  /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
-  missed: BoardEditOp[]
-}
-
-const EMPTY_BOARD = { width: 1000, height: 600, components: [] as any[] }
-
-/**
- * Patch 를 BoardModel 에 적용 (pure, board 를 mutate 하지 않음).
- */
-export function applyBoardEditPatch(board: any | undefined, patch: BoardEditPatch): any {
-  return applyBoardEditPatchVerbose(board, patch).board
-}
-
-/**
- * Verbose 변형 — 각 op 의 적용 여부를 보고.
- *
- * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다. LLM 이 잘못된
- * id 를 만들어 보내면 사용자에게 "수정했습니다" 라고 답하지만 실제로는 아무 변화도
- * 없는 상황이 발생 — 호스트가 missed 를 보고 사용자에게 경고할 수 있도록 별도
- * entry point 제공.
- */
-export function applyBoardEditPatchVerbose(
-  board: any | undefined,
-  patch: BoardEditPatch
-): PatchApplyReport {
-  let result: any = board ?? EMPTY_BOARD
-  const applied: BoardEditOp[] = []
-  const missed: BoardEditOp[] = []
-
-  for (const op of patch.ops) {
-    if (SCENE_ONLY_OPS.has(op.op)) {
-      // scene-only — model 차원 noop, scene 차원 적용. applied 분류.
-      applied.push(op)
-      continue
-    }
-    const next = applyOp(result, op)
-    // componentsUnchanged 는 components 배열 동일 + width/height/fillStyle 동일 만 본다.
-    // modify / remove 의 silent no-op (ghost refid) 검출 전용 — modifyBoard 가 sky
-    // 등 다른 root 키만 바꿀 때 false negative 로 missed 분류되는 회귀 방지.
-    const componentMutating = op.op === 'modify' || op.op === 'remove'
-    if (next === result || (componentMutating && componentsUnchanged(result, next))) {
-      missed.push(op)
-    } else {
-      applied.push(op)
-      result = next
-    }
-  }
-
-  return { board: result, applied, missed }
-}
-
-function componentsUnchanged(prev: any, next: any): boolean {
-  // applyOp 는 항상 새 객체를 만든다. 따라서 reference 비교가 안 되고 내용 비교 필요.
-  // components 는 map/filter 결과 reference 도 다를 수 있으므로 length + 요소 ref 비교.
-  const a = prev.components ?? []
-  const b = next.components ?? []
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) return false
-  }
-  return prev.width === next.width && prev.height === next.height && prev.fillStyle === next.fillStyle
-}
-
-const SCENE_ONLY_OPS = new Set<BoardEditOp['op']>([
-  'align',
-  'distribute',
-  'group',
-  'ungroup',
-  'zorder',
-  'arrange'
-])
-
-function applyOp(board: any, op: BoardEditOp): any {
-  switch (op.op) {
-    case 'replace':
-      return op.board
-    case 'add':
-      return { ...board, components: [...(board.components || []), op.component] }
-    case 'remove':
-      // 자식 (group/container 안) refid 도 매칭 — deep search.
-      return {
-        ...board,
-        components: removeComponentDeep(board.components || [], op.refid)
-      }
-    case 'modify':
-      // 자식 refid 도 매칭 — group/container 안의 컴포넌트 수정 가능.
-      return {
-        ...board,
-        components: modifyComponentDeep(board.components || [], op.refid, op.patch)
-      }
-    case 'modifyBoard': {
-      const patch = { ...(op.patch || {}) }
-      delete patch.components // 자식 변경은 별도 op
-      return mergeComponent(board, patch) // 최상위 board 자체에 deep-merge
-    }
-    case 'align':
-    case 'distribute':
-    case 'group':
-    case 'ungroup':
-    case 'zorder':
-    case 'arrange':
-      // scene-only — model 차원 noop. things-scene API 가 정본.
-      return board
-    default:
-      return board
-  }
-}
-
-/**
- * 주어진 board 상태에서 op 의 inverse 를 계산.
- *
- * Revert 기능 — patch 적용 직전 board + op 로 역연산을 만든다. 호스트가
- * 누적해두면 나중에 역순 실행만으로 복원.
- *
- * add 의 inverse 는 새로 발급될 refid 를 알아야 → 모델 단계에서 계산 불가.
- * 호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것.
- */
-export function computeInverseOp(board: any, op: BoardEditOp): BoardEditOp | null {
-  if (!board) return null
-  const components = board.components ?? []
-
-  switch (op.op) {
-    case 'add':
-      return null
-
-    case 'remove': {
-      // 자식 refid 도 매칭 (deep search)
-      const target = findComponentDeep(components, op.refid)
-      if (!target) return null
-      return { op: 'add', component: JSON.parse(JSON.stringify(target)) }
-    }
-
-    case 'modify': {
-      // 자식 refid 도 매칭 (deep search)
-      const target = findComponentDeep(components, op.refid)
-      if (!target) return null
-      const oldValues: any = {}
-      for (const k of Object.keys(op.patch || {})) {
-        const v = (target as any)[k]
-        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
-      }
-      return { op: 'modify', refid: op.refid, patch: oldValues }
-    }
-
-    case 'modifyBoard': {
-      const oldValues: any = {}
-      const patch = op.patch || {}
-      for (const k of Object.keys(patch)) {
-        if (k === 'components') continue
-        const v = (board as any)[k]
-        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
-      }
-      return { op: 'modifyBoard', patch: oldValues }
-    }
-
-    case 'replace':
-      return { op: 'replace', board: JSON.parse(JSON.stringify(board)) }
-
-    case 'zorder': {
-      // forward ↔ backward / front ↔ back. front/back 의 inverse 는 정확하지
-      // 않을 수 있음 (best-effort) — 정확 inverse 는 호스트가 zorder 직전 index
-      // 를 캡처해서 명시 modify 시퀀스로 만들어야.
-      const opp: Record<string, 'front' | 'back' | 'forward' | 'backward'> = {
-        forward: 'backward',
-        backward: 'forward',
-        front: 'back',
-        back: 'front'
-      }
-      const dir = opp[op.direction]
-      if (!dir) return null
-      return { op: 'zorder', refid: op.refid, direction: dir }
-    }
-
-    case 'align':
-    case 'distribute':
-    case 'group':
-    case 'ungroup':
-    case 'arrange':
-      // scene 호출 후에야 변경 결과 알 수 있음. 호스트가 직접 inverse 만든다.
-      return null
-
-    default:
-      return null
-  }
-}
-
-/**
- * 컴포넌트에 부분 patch 를 적용 (deep merge).
- * threeD 등 nested object 는 deep merge — 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
- *
- * patch 내 `null` 의 시맨틱 — **"이 키를 제거하라"**:
- *   - fillStyle/strokeStyle 처럼 `string | object | undefined` 인 필드는 null 로
- *     set 하면 typeof null === 'object' 함정에 빠져 다운스트림 (3D 텍스처 등) 이 크래시.
- *   - computeInverseOp 가 base 에 키가 없던 (`undefined`) 경우 inverse 를 null 로
- *     발급하므로, 이 시맨틱과 정확히 일치 — inverse 가 자연스럽게 올바로 동작.
- *
- * host (board-modeller-page) 에서 things-scene 의 component.set(merged) 호출 전에 사용.
- */
-export function mergeComponent(base: any, patch: any): any {
-  const out: any = { ...base }
-  for (const key of Object.keys(patch)) {
-    const patchVal = patch[key]
-    if (patchVal === null) {
-      delete out[key]
-    } else if (isPlainObject(base[key]) && isPlainObject(patchVal)) {
-      out[key] = deepMerge(base[key], patchVal)
-    } else {
-      out[key] = patchVal
-    }
-  }
-  return out
-}
-
-function deepMerge(a: any, b: any): any {
-  const out: any = { ...a }
-  for (const key of Object.keys(b)) {
-    const bv = b[key]
-    if (bv === null) {
-      delete out[key]
-    } else if (isPlainObject(a[key]) && isPlainObject(bv)) {
-      out[key] = deepMerge(a[key], bv)
-    } else {
-      out[key] = bv
-    }
-  }
-  return out
-}
-
-function isPlainObject(v: any): boolean {
-  return v !== null && typeof v === 'object' && !Array.isArray(v)
-}
-
-// ── 자식 컴포넌트 (group/container 안) 까지 매칭 — deep search ─
-// server/service/apply-patch.ts 와 동일 로직. drift test 가 동등성 보장.
-
-function findComponentDeep(components: any[], refid: number): any | undefined {
-  for (const c of components) {
-    if (!c) continue
-    if (c.refid === refid) return c
-    if (Array.isArray(c.components) && c.components.length > 0) {
-      const sub = findComponentDeep(c.components, refid)
-      if (sub) return sub
-    }
-  }
-  return undefined
-}
-
-function modifyComponentDeep(components: any[], refid: number, patch: any): any[] {
-  let changed = false
-  const out = components.map(c => {
-    if (!c) return c
-    if (c.refid === refid) {
-      changed = true
-      return mergeComponent(c, patch)
-    }
-    if (Array.isArray(c.components) && c.components.length > 0) {
-      const updated = modifyComponentDeep(c.components, refid, patch)
-      if (updated !== c.components) {
-        changed = true
-        return { ...c, components: updated }
-      }
-    }
-    return c
-  })
-  return changed ? out : components
-}
-
-function removeComponentDeep(components: any[], refid: number): any[] {
-  let changed = false
-  const out: any[] = []
-  for (const c of components) {
-    if (!c) {
-      out.push(c)
-      continue
-    }
-    if (c.refid === refid) {
-      changed = true
-      continue
-    }
-    if (Array.isArray(c.components) && c.components.length > 0) {
-      const updated = removeComponentDeep(c.components, refid)
-      if (updated !== c.components) {
-        changed = true
-        out.push({ ...c, components: updated })
-        continue
-      }
-    }
-    out.push(c)
-  }
-  return changed ? out : components
-}