@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/master-to-twin.test.ts

@@ -1,6 +1,6 @@
 /*
- * masterToTwin — 모델→board 토폴로지 변환 시임. 템플릿/레퍼런스 master → board{locations,equipment,layout,spaceId}+space.
- * 스트림라인의 "모델링→board" 연결부: 템플릿(build)이 낸 master 를 커널이 소비할 BoardDef 로 바꾼다.
+ * masterToTwin — 모델→model 토폴로지 변환 시임. 템플릿/레퍼런스 master → model{locations,equipment,layout,spaceId}+space.
+ * 스트림라인의 "모델링→board" 연결부: 템플릿(build)이 낸 master 를 커널이 소비할 TwinModelDef 로 바꾼다.
  * role(location/area/both) 분기·footprint→layout·spaceId 파생·미지 타입 경고를 고정.
  */
 import { test } from 'node:test'
@@ -26,41 +26,45 @@ const wmsMaster = () => ({
 })
 
 test('locations role → 노드/영역 분기, equipment → 무버', () => {
-  const { board, spaceContent } = masterToTwin(wmsMaster())
-  assert.deepEqual(board.locations.map((n: any) => n.id).sort(), ['dock-recv', 'dock-ship', 'rack-1', 'rack-2'], '노드=role location')
+  const { model, spaceContent } = masterToTwin(wmsMaster())
+  assert.deepEqual(model.locations.map((n: any) => n.id).sort(), ['dock-recv', 'dock-ship', 'rack-1', 'rack-2'], '노드=role location')
   assert.equal(spaceContent.areas.length, 1, '영역=role area')
   assert.equal(spaceContent.areas[0].id, 'a-dc')
-  assert.deepEqual(board.equipment, [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv', mtbfMs: undefined, mttrMs: undefined, gs1Id: undefined }], '마스터 equipment→보드 equipment(homeLocationId→homeLocation, gs1Id 통과)')
-  assert.equal(board.locations.find((n: any) => n.id === 'rack-1').capacity, 60, 'capacity 전달')
-  assert.equal(board.locations.find((n: any) => n.id === 'dock-recv').parentId, undefined, 'parentId 없으면 undefined')
+  assert.deepEqual(model.equipment, [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv', mtbfMs: undefined, mttrMs: undefined, gs1Id: undefined }], '마스터 equipment→보드 equipment(homeLocationId→homeLocation, gs1Id 통과)')
+  assert.equal(model.locations.find((n: any) => n.id === 'rack-1').capacity, 60, 'capacity 전달')
+  assert.equal(model.locations.find((n: any) => n.id === 'dock-recv').parentId, undefined, 'parentId 없으면 undefined')
 })
 
 test('coordinate-free: footprint 없으면 layout 비어있음(미배치 → A2)', () => {
-  const { board } = masterToTwin(wmsMaster())
-  assert.deepEqual(board.layout, {}, '좌표 없는 master → layout {}')
+  const { model } = masterToTwin(wmsMaster())
+  assert.deepEqual(model.layout, {}, '좌표 없는 master → layout {}')
 })
 
 test('footprint 있으면 layout = 중심좌표', () => {
   const m = wmsMaster()
   ;(m.locations[1] as any).footprint = { x: 10, y: 20, w: 4, h: 6 } // dock-recv
-  const { board } = masterToTwin(m)
-  assert.deepEqual(board.layout['dock-recv'], { x: 12, y: 23 }, '중심 = x+w/2, y+h/2')
-  assert.equal(board.layout['rack-1'], undefined, 'footprint 없는 노드는 layout 없음')
+  const { model } = masterToTwin(m)
+  assert.deepEqual(model.layout['dock-recv'], { x: 12, y: 23 }, '중심 = x+w/2, y+h/2')
+  assert.equal(model.layout['rack-1'], undefined, 'footprint 없는 노드는 layout 없음')
 })
 
 test('spaceId: 명시 시 참조, 없으면 source 파생 (공동배치 시임)', () => {
-  assert.equal(masterToTwin(wmsMaster()).board.spaceId, 'wh-seoul-site', '없으면 {source}-site')
+  assert.equal(masterToTwin(wmsMaster()).model.spaceId, 'wh-seoul-site', '없으면 {source}-site')
   const shared = wmsMaster()
   ;(shared.space as any).spaceId = 'rosarito-site'
-  assert.equal(masterToTwin(shared).board.spaceId, 'rosarito-site', '명시 시 공유(다시스템 co-location)')
+  assert.equal(masterToTwin(shared).model.spaceId, 'rosarito-site', '명시 시 공유(다시스템 co-location)')
 })
 
 test('미지 노드 타입 경고 — 카탈로그 있으면 검증(버리진 않음)', () => {
   const m = wmsMaster()
   ;(m.locations as any).push({ id: 'weird', type: '__unknown__', role: 'location', capacity: 1 })
   const withCat = masterToTwin(m, DOMAIN_CATALOG)
-  assert.ok(withCat.warnings.some(w => w.includes('__unknown__')), '미지 타입 경고')
-  assert.ok(withCat.board.locations.some((n: any) => n.id === 'weird'), '경고해도 노드는 유지(반영 우선)')
+  /* 경고는 프로즈가 아니라 **코드+파라미터**다(화면이 다섯 언어로 렌더한다) — 문구가 아니라 계약을 본다. */
+  assert.ok(
+    withCat.warnings.some(w => w.code === 'unknown-location-type' && w.params?.type === '__unknown__'),
+    `미지 타입 경고: ${JSON.stringify(withCat.warnings)}`
+  )
+  assert.ok(withCat.model.locations.some((n: any) => n.id === 'weird'), '경고해도 노드는 유지(반영 우선)')
   // 정상 타입만이면 경고 0
   assert.equal(masterToTwin(wmsMaster(), DOMAIN_CATALOG).warnings.length, 0, '알려진 타입만 → 경고 0')
   // 카탈로그 없으면 검증 생략
@@ -70,8 +74,8 @@ test('미지 노드 타입 경고 — 카탈로그 있으면 검증(버리진
 test("role 'both' 는 노드·영역 양쪽에 등장(도크 도어 등)", () => {
   const m = wmsMaster()
   ;(m.locations as any).push({ id: 'dock-door-1', type: 'dock-door', role: 'both', name: '도어1', capacity: 1 })
-  const { board, spaceContent } = masterToTwin(m)
-  assert.ok(board.locations.some((n: any) => n.id === 'dock-door-1'), 'both → 노드')
+  const { model, spaceContent } = masterToTwin(m)
+  assert.ok(model.locations.some((n: any) => n.id === 'dock-door-1'), 'both → 노드')
   assert.ok(spaceContent.areas.some((a: any) => a.id === 'dock-door-1'), 'both → 영역')
 })
 
@@ -107,7 +111,7 @@ test('현장 물질화(#4): 표현도 geo 도 없으면 빈 표현 + 경고(정
   const { spaceContent, warnings } = masterToTwin(m)
   assert.equal(spaceContent.representations.length, 0, '합성 불가')
   assert.ok(
-    warnings.some((w: string) => w.includes('no viewable representation')),
+    warnings.some(w => w.code === 'no-viewable-representation'),
     '뷰 없는 공간 경고 표면화'
   )
 })
@@ -115,7 +119,7 @@ test('현장 물질화(#4): 표현도 geo 도 없으면 빈 표현 + 경고(정
 /* ── 공정 명세 통과 (ISA-95 OperationsSegment) ──────────────────────────────
  *
  * 시뮬레이션의 소요·수율이 커널 상수였던 것을 데이터로 옮기는 경로의 마지막 한 칸: 마스터가 명세를
- * 말하면 board 를 통해 커널까지 **손대지 않고** 간다. 기간은 표준 표기(ISO 8601)로 그대로 흐른다 —
+ * 말하면 model 를 통해 커널까지 **손대지 않고** 간다. 기간은 표준 표기(ISO 8601)로 그대로 흐른다 —
  * 여기서 밀리초로 바꾸면 표준과 어긋나고, 커널이 다시 해석할 기회를 잃는다.
  */
 const mesMaster = () => ({
@@ -138,19 +142,19 @@ const mesMaster = () => ({
   ]
 })
 
-test('공정 명세가 board 로 그대로 통과한다 — 표준 표기 유지, 값 변형 없음', () => {
-  const { board, warnings } = masterToTwin(mesMaster(), DOMAIN_CATALOG)
-  assert.equal((board as any).operations.length, 1)
-  const op = (board as any).operations[0]
+test('공정 명세가 model 로 그대로 통과한다 — 표준 표기 유지, 값 변형 없음', () => {
+  const { model, warnings } = masterToTwin(mesMaster(), DOMAIN_CATALOG)
+  assert.equal((model as any).operations.length, 1)
+  const op = (model as any).operations[0]
   assert.equal(op.duration, 'PT25M', 'ISO 8601 기간을 밀리초로 바꾸지 않는다')
   assert.deepEqual(op.variability, { distribution: 'triangular', min: 'PT20M', max: 'PT35M', mode: 'PT24M' })
   assert.deepEqual(op.parameters, [{ id: 'yield', value: '0.995' }])
   assert.equal(warnings.length, 0)
 })
 
-test('명세를 주지 않으면 키를 만들지 않는다 — 빈 배열로 "선언했다" 고 말하지 않는다', () => {
-  const { board } = masterToTwin(wmsMaster(), DOMAIN_CATALOG)
-  assert.equal('operations' in (board as any), false)
+test('명세를 전달하지 않으면 키를 만들지 않는다 — 빈 배열을 "선언했다" 로 보고하지 않는다', () => {
+  const { model } = masterToTwin(wmsMaster(), DOMAIN_CATALOG)
+  assert.equal('operations' in (model as any), false)
 })
 
 test('내용 없는 명세는 경고한다 — 선언했는데 아무 말도 하지 않는 명세는 침묵하지 않는다', () => {
@@ -158,7 +162,7 @@ test('내용 없는 명세는 경고한다 — 선언했는데 아무 말도 하
   m.operations = [{ key: 'cut', label: 'cutting', intent: 'process' }]
   const { warnings } = masterToTwin(m, DOMAIN_CATALOG)
   assert.ok(
-    warnings.some(w => w.includes('cut') && w.includes('kernel defaults')),
+    warnings.some(w => w.code === 'operation-without-duration' && w.params?.operation === 'cut'),
     `기본값으로 굴러갈 것을 알린다: ${JSON.stringify(warnings)}`
   )
 })
@@ -168,20 +172,108 @@ test('내용 없는 명세는 경고한다 — 선언했는데 아무 말도 하
  * `capacity` 한 필드가 저장 용량과 처리 능력을 겸하던 것을 갈랐다. 인제스트도 두 축을 따로 실어야
  * 커널이 "20개를 쌓아 두지만 한 번에 한 대만 깎는다" 를 표현할 수 있다. 교대도 같다.
  */
-test('처리 능력과 교대가 board 로 통과한다 — 저장 용량과 섞이지 않는다', () => {
+test('처리 능력과 교대가 model 로 통과한다 — 저장 용량과 섞이지 않는다', () => {
   const m: any = mesMaster()
   m.locations[1].parallelism = 1 // cut-1: 저장 4, 동시 처리 1
   m.equipment[0].window = { startHour: 8, endHour: 18 }
-  const { board } = masterToTwin(m, DOMAIN_CATALOG)
-  const location = (board as any).locations.find((n: any) => n.id === 'cut-1')
+  const { model } = masterToTwin(m, DOMAIN_CATALOG)
+  const location = (model as any).locations.find((n: any) => n.id === 'cut-1')
   assert.equal(location.capacity, 4, '저장 용량')
   assert.equal(location.parallelism, 1, '처리 능력 — 다른 축')
-  assert.deepEqual((board as any).equipment[0].window, { startHour: 8, endHour: 18 })
+  assert.deepEqual((model as any).equipment[0].window, { startHour: 8, endHour: 18 })
 })
 
-test('선언하지 않으면 키를 만들지 않는다 — 미지정과 0 을 뭉개지 않는다', () => {
-  const { board } = masterToTwin(mesMaster(), DOMAIN_CATALOG)
-  const location = (board as any).locations.find((n: any) => n.id === 'cut-1')
+test('선언하지 않으면 키를 만들지 않는다 — 미지정과 0 을 같게 다루지 않는다', () => {
+  const { model } = masterToTwin(mesMaster(), DOMAIN_CATALOG)
+  const location = (model as any).locations.find((n: any) => n.id === 'cut-1')
   assert.equal('parallelism' in location, false)
-  assert.equal('window' in (board as any).equipment[0], false)
+  assert.equal('window' in (model as any).equipment[0], false)
+})
+
+/*
+ * ★ **이름이 첫 문에서 사라지고 있었다.**
+ *
+ * 인제스트가 자리·설비·사람·자산을 보드로 옮길 때 `name` 을 빼고 있었다. 그러면 모델에도 없고,
+ * 모델에서 그리는 투영 행에도 없으므로 **어떤 화면도 이름을 만들 수 없다** — 목록·표·관계 그림이
+ * 전부 `cut-station` 같은 id 를 찍었다. 표면마다 따로 나타나지만 결함은 이 한 자리다.
+ *
+ * 업무키를 따로 두는 설계(식별자는 원본이 정한다)에서는 **이름을 함께 싣는 것이 그 설계의 절반**이다.
+ * 나누기만 하고 이름을 빼면 화면에 남는 것은 id 뿐이다.
+ */
+test('이름이 보드로 통과한다 — 업무키를 나눈 설계의 나머지 절반', () => {
+  const m: any = mesMaster()
+  m.locations[1].name = '프레임 절단'
+  m.equipment[0].name = '절단기 1호'
+  const { model } = masterToTwin(m, DOMAIN_CATALOG)
+  const location = (model as any).locations.find((n: any) => n.id === 'cut-1')
+  assert.equal(location.name, '프레임 절단', '자리 이름이 모델에 실려야 한다')
+  assert.equal((model as any).equipment[0].name, '절단기 1호', '설비 이름이 모델에 실려야 한다')
+})
+
+test('이름 없는 원본은 이름 없이 통과한다 — id 를 이름으로 베끼지 않는다', () => {
+  const m: any = mesMaster()
+  delete m.locations[1].name // 이름을 말하지 않는 원본
+  const { model } = masterToTwin(m, DOMAIN_CATALOG)
+  const location = (model as any).locations.find((n: any) => n.id === 'cut-1')
+  /* 키 자체를 만들지 않는다: id 를 넣어 두면 "이름이 있다" 가 거짓이 되고, 화면은 이름 없음을
+     알아볼 수 없게 된다(그러면 "이름을 지어 주세요" 라고 말할 수도 없다). */
+  assert.equal('name' in location, false, '원본이 이름을 말하지 않았으면 키가 없어야 한다')
+})
+
+/*
+ * ★ 검사 명세가 모델로 통과한다 — **참조가 가리킬 대상이 실린다.**
+ *
+ * 자원은 예전부터 `testSpecificationIds` 로 시험을 가리킬 수 있었지만 가리켜지는 대상이 없었다. 인제스트가
+ * 명세를 흘리면 축이 서 있어도 여전히 허공을 가리킨다 — 그래서 이 문에서 통과를 못 박는다.
+ *
+ * 표시명은 `name` 으로 옮긴다(등급과 같은 규칙) — 그러지 않으면 화면의 "설명" 열에 이름이 앉는다.
+ */
+test('검사 명세가 모델로 통과한다 — 표시명은 name 으로', () => {
+  const m: any = mesMaster()
+  m.testSpecifications = [{ id: 'weld-cert', description: 'twin.x.test.weld', version: '2026.1' }]
+  const { model } = masterToTwin(m, DOMAIN_CATALOG) as any
+  const specs = (model as any).testSpecifications
+  assert.equal(specs?.length, 1, '명세가 모델에 실려야 한다')
+  assert.equal(specs[0].id, 'weld-cert')
+  assert.equal(specs[0].name, 'twin.x.test.weld', '표시명은 name 자리에 온다(어휘를 하나로)')
+  assert.equal('description' in specs[0], false, '두 자리에 같은 값을 두지 않는다')
+  assert.equal(specs[0].version, '2026.1', '판이 남아야 한다 — 어느 판으로 검증했나')
+})
+
+test('선언하지 않으면 키를 만들지 않는다 — 빈 배열을 "선언했다" 로 보고하지 않는다', () => {
+  const { model } = masterToTwin(mesMaster(), DOMAIN_CATALOG) as any
+  assert.equal('testSpecifications' in (model as any), false)
+})
+
+/*
+ * ── 자리의 속성이 커널까지 간다 (2026-08-14, EMS 4단계) ─────────────────────
+ *
+ * 에너지 커널은 계약전력을 **자리 속성**(`contract.kW`)에서 읽고, 없으면 계약 대비 판정을 아예
+ * 하지 않는다. 그래서 이 통과가 끊기면 결과가 「오류 없이 판정만 사라지는」 모양이 된다 — 화면에는
+ * 트윈이 정상으로 보이고 피크 경고만 영원히 오지 않는다. 눈으로는 보이지 않는 부류다.
+ *
+ * 실제로 처음에는 끊겨 있었다(타입만 열고 변환을 잇지 않았다).
+ */
+test('자리의 속성을 모델로 통과시킨다 — 계약전력이 커널에 닿는 유일한 길', () => {
+  const m = {
+    source: 'ems-1',
+    system: 'ems' as const,
+    siteName: '공장',
+    space: { width: 10, depth: 10 },
+    locations: [
+      {
+        id: 'incoming-1',
+        type: 'incoming',
+        role: 'location' as const,
+        capacity: 0,
+        properties: [{ id: 'contract.kW', value: '4000', dataType: 'xs:double', uom: 'KWT' }]
+      },
+      { id: 'feeder-1', type: 'feeder', role: 'location' as const, capacity: 0 }
+    ]
+  }
+  const { model } = masterToTwin(m as any)
+  const incoming = model.locations.find((l: any) => l.id === 'incoming-1') as any
+  assert.deepEqual(incoming.properties, m.locations[0].properties, '손대지 않고 나른다')
+  const feeder = model.locations.find((l: any) => l.id === 'feeder-1') as any
+  assert.equal('properties' in feeder, false, '없는 것을 빈 배열로 만들지 않는다(모름과 없음을 섞지 않는다)')
 })

package/test/model-basis.test.ts

@@ -11,7 +11,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { BASIS_TOLERANCE, describeModelBasis, modelBasisChanged } from '../server/engine/model-basis.ts'
+import { BASIS_TOLERANCE, describeModelBasis, modelBasisChanged, toleranceOf } from '../server/engine/model-basis.ts'
 
 test('같은 근거면 바뀌지 않았다 — 키 순서에 흔들리지 않는다', () => {
   assert.equal(
@@ -84,3 +84,58 @@ test('사람이 읽는 요약을 낸다 — 로그에서 왜 달라졌는지 눈
   assert.equal(describeModelBasis({}), 'kernel defaults only')
   assert.equal(describeModelBasis(undefined), 'unknown')
 })
+
+/*
+ * ★ 허용오차는 **그 공정이 선언한 변동폭에서 나온다.**
+ *
+ * 단일 10% 잣대는 두 방향으로 틀렸다. 우리 트레일러 템플릿의 용접은 변동폭을 `PT55M~PT1H35M`
+ * (선언 소요 `PT1H10M` 기준 −21%~+36%)로 스스로 선언한다 — 10% 관문은 그 공정의 **정상 변동조차**
+ * "다른 모델" 로 판정해 보정을 끊는다. 반대로 1% 변동도 치명적인 공정에는 10% 가 너무 느슨하다.
+ *
+ * 도메인 설정을 새로 만들지 않는다: 얼마나 흔들리는 것이 정상인지는 **현장이 이미 선언했다.**
+ */
+const weld = (durationMs: number) => ({
+  measured: { weld: durationMs },
+  declared: [{ key: 'weld', duration: 'PT1H10M', variability: { distribution: 'triangular', min: 'PT55M', max: 'PT1H35M', mode: 'PT1H5M' } }]
+})
+
+test('선언된 변동폭 안의 흔들림은 같은 모델이다 — 10% 잣대는 정상 변동을 끊었다', () => {
+  const base = 70 * 60_000 // PT1H10M
+  /* 반폭 = (95분 − 55분)/2 / 70분 ≈ 28.6%. 20% 흔들림은 그 안이다 — 예전 잣대(10%)로는 끊겼다. */
+  assert.equal(modelBasisChanged(weld(base), weld(base * 1.2)), false, '정상 변동으로 학습이 무효화되면 안 된다')
+  /* 변동폭이 실제로 허용오차로 읽히는지 — 반폭 ≈ 28.6%. 이 값이 안 나오면 위 단언이 우연히 통과한다. */
+  const tol = toleranceOf(weld(base).declared).weld
+  assert.ok(tol > 0.28 && tol < 0.29, `선언에서 읽은 허용오차가 ${tol} 다`)
+})
+
+test('선언된 변동폭을 넘으면 다른 모델이다 — 넓혔다고 아무 변화나 삼키지 않는다', () => {
+  const base = 70 * 60_000
+  assert.equal(modelBasisChanged(weld(base), weld(base * 1.6)), true, '60% 변화는 정상 변동이 아니다')
+})
+
+test('정밀 공정은 더 좁게 판정한다 — 1% 변동이 치명적인 현장이 있다', () => {
+  const precise = (ms: number) => ({
+    measured: { grind: ms },
+    declared: [{ key: 'grind', duration: 'PT10M', variability: { distribution: 'uniform', min: 'PT9M54S', max: 'PT10M6S' } }]
+  })
+  const base = 10 * 60_000
+  /* 반폭 = 6초/10분 = 1%. 5% 흔들림은 이 공정에서 다른 모델이다 — 단일 10% 잣대는 삼켰다. */
+  assert.equal(modelBasisChanged(precise(base), precise(base * 1.05)), true, '느슨한 잣대가 정밀 공정의 변화를 삼켰다')
+  assert.equal(modelBasisChanged(precise(base), precise(base * 1.005)), false, '선언한 변동폭 안은 같은 모델이다')
+})
+
+test('선언이 침묵하면 기본값으로 떨어진다 — 없는 것을 지어내지 않는다', () => {
+  const quiet = (ms: number) => ({ measured: { pack: ms }, declared: [{ key: 'pack', duration: 'PT5M' }] })
+  const base = 5 * 60_000
+  assert.equal(modelBasisChanged(quiet(base), quiet(base * 1.05)), false, '기본 10% 안')
+  assert.equal(modelBasisChanged(quiet(base), quiet(base * 1.3)), true, '기본 10% 밖')
+})
+
+test('변동폭이 바뀌면 다른 모델이다 — 판정의 잣대가 조용히 바뀌지 않게', () => {
+  const a = weld(70 * 60_000)
+  const b = {
+    measured: { weld: 70 * 60_000 },
+    declared: [{ key: 'weld', duration: 'PT1H10M', variability: { distribution: 'triangular', min: 'PT30M', max: 'PT3H', mode: 'PT1H5M' } }]
+  }
+  assert.equal(modelBasisChanged(a, b), true, '변동폭 선언이 바뀌었는데 같은 모델이라고 하면 잣대가 조용히 바뀐다')
+})

package/test/model-vocabulary.test.ts

@@ -0,0 +1,114 @@
+/*
+ * 저장된 모델의 어휘 세대 흡수 — **빈 공장으로 읽히지 않게.**
+ *
+ * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
+ * 모델러의 엔티티 목록이 통째로 비어 있었다. **오류는 없었다.** 저장된 모델가 옛 어휘(`nodes`/`movers`)
+ * 인데 화면과 호스트가 새 어휘를 읽었기 때문이다. 같은 원인이 구조 서명(`N[]M[]` — 서로 다른 두 공장이
+ * 같아 보인다)·주행 추정기·설비 동기까지 조용히 망가뜨리고 있었다.
+ *
+ * 그래서 **DB에서 읽는 순간** 한 번 정규화한다. 이 테스트가 지키는 것은 그 정규화가 ① 세 세대를 다
+ * 흡수하고 ② 나머지 속성을 하나도 잃지 않고 ③ 새 모델에는 아무 일도 하지 않는 것이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { readFileSync } from 'node:fs'
+
+import { modelColumnTransformer, canonicalModel } from '../server/engine/model-vocabulary.ts'
+
+const LOC = [{ id: 'dock', type: 'dock', capacity: 10 }]
+const EQ = [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }]
+
+test('가장 오래된 세대(nodes·movers)를 흡수한다 — 사용자가 본 증상의 원인', () => {
+  const out = canonicalModel({ nodes: LOC, movers: EQ, spaceId: 'site-1' })
+
+  assert.deepEqual(out.locations, LOC)
+  assert.deepEqual(out.equipment, EQ)
+})
+
+test('중간 세대(equipmentList)도 흡수한다 — 세 세대가 저장돼 있다', () => {
+  const out = canonicalModel({ nodes: LOC, equipmentList: EQ })
+
+  assert.deepEqual(out.equipment, EQ)
+})
+
+test('옛 키를 **내보내지 않는다** — 소비처가 두 어휘를 다시 보지 않게', () => {
+  const out: any = canonicalModel({ nodes: LOC, movers: EQ, equipmentList: [] })
+
+  for (const k of ['nodes', 'movers', 'equipmentList']) assert.equal(k in out, false, `${k} 가 남았다`)
+})
+
+test('나머지 속성을 하나도 잃지 않는다 — 곁가지로 보이는 값이 전제다', () => {
+  /* 이 도메인에서 사소한 속성은 없다: 좌표·시각기준·명세는 소요시간·교대·생산의 전제다. */
+  const model = {
+    nodes: LOC,
+    movers: EQ,
+    spaceId: 'site-1',
+    areaId: 'zone-a',
+    layout: { dock: { x: 1, y: 2 } },
+    utcOffsetMinutes: 540,
+    unit: 'm',
+    productionSpec: { definition: { operations: [] } },
+    operations: [{ id: 'op-1' }]
+  }
+  const out: any = canonicalModel(model)
+
+  for (const k of ['spaceId', 'areaId', 'layout', 'utcOffsetMinutes', 'unit', 'productionSpec', 'operations']) {
+    assert.deepEqual(out[k], (model as any)[k], `${k} 가 사라졌다`)
+  }
+})
+
+test('새 어휘 모델에는 아무 일도 하지 않는다 — 멱등', () => {
+  const model = { locations: LOC, equipment: EQ, spaceId: 'site-1' }
+
+  const once: any = canonicalModel(model)
+  const twice: any = canonicalModel(once)
+
+  assert.deepEqual(once, model)
+  assert.deepEqual(twice, once)
+})
+
+test('컬렉션이 없으면 빈 배열이 된다 — 소비처가 `?? []` 를 다시 적지 않게', () => {
+  const out = canonicalModel({ spaceId: 'site-1' })
+
+  assert.deepEqual(out.locations, [])
+  assert.deepEqual(out.equipment, [])
+})
+
+test('모델이 아닌 것은 그대로 통과시킨다 — 모양을 짐작해 고치지 않는다', () => {
+  for (const v of [null, undefined, 0, '', 'board', [1, 2]]) {
+    assert.deepEqual(canonicalModel(v as any), v as any, JSON.stringify(v))
+  }
+})
+
+test('변환기는 **읽을 때만** 정규화한다 — 쓰기는 준 그대로', () => {
+  const old = { nodes: LOC, movers: EQ }
+
+  assert.deepEqual(modelColumnTransformer.from(old).equipment, EQ)
+  /* 쓰기를 손대면 "저장된 것" 과 "준 것" 이 달라져 추적이 어려워진다. 읽기가 정규화되므로 다음 저장에서
+     자연히 새 어휘가 된다. */
+  assert.equal(modelColumnTransformer.to(old), old)
+})
+
+test('두 옛 모델이 구조적으로 구별된다 — 서명이 빈 문자열로 축약되지 않는다', () => {
+  /* 정규화 전에는 둘 다 `locations: undefined` 라 서명이 `N[]M[]` 로 같았다(변경 감지가 죽는다). */
+  const a = canonicalModel({ nodes: [{ id: 'a', type: 'dock', capacity: 1 }], movers: [] })
+  const b = canonicalModel({ nodes: [{ id: 'b', type: 'storage', capacity: 9 }], movers: [] })
+
+  assert.notDeepEqual(a.locations, b.locations)
+  assert.equal(a.locations.length, 1)
+  assert.equal(b.locations.length, 1)
+})
+
+test('보드를 저장하는 엔티티가 **변환기를 달고 있다** — 결선이 빠지면 순수 모듈은 그린인데 화면은 빈다', () => {
+  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 조용히 빠질 수 있으므로
+     기계가 지킨다. 새 엔티티가 보드를 담게 되면 여기 함께 올린다. */
+  const owners = ['server/service/twin-instance/twin-instance.ts', 'server/service/twin-structure/twin-structure.ts']
+
+  for (const rel of owners) {
+    const src = readFileSync(new URL('../' + rel, import.meta.url).pathname, 'utf-8')
+    const boardColumn = src.split('\n').find(l => l.includes('@Column') && l.includes('transformer'))
+    assert.ok(boardColumn, `${rel}: model 컬럼에 transformer 가 없다`)
+    assert.match(boardColumn as string, /modelColumnTransformer/, `${rel}: 다른 변환기가 달려 있다`)
+  }
+})

package/test/move-space.test.ts

@@ -0,0 +1,149 @@
+/*
+ * 기존 트윈을 다른 현장으로 가져오기 — 판정이 잃을 것을 말하는지 본다.
+ *
+ * 엔진 본체는 DB 를 물고 있어 단위테스트로 부를 수 없다. 그래서 **결정만** 순수 모듈로 떼어 놓고
+ * 여기서 본다(엔진은 사실을 조회해 넘기는 일만 한다 — `ingest-space` 와 같은 구조).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { judgeMoveTwinSpace, judgeDetachTwinSpace } from '../server/service/twin-space/move-space.ts'
+
+/** 잃을 것이 없는 가장 단순한 이전 — 같은 시간대, 구역 참조 없음, 옛 표현 없음. */
+const CLEAN = {
+  instanceId: 'wms-a',
+  fromSpaceId: 'wms-a-site',
+  toSpaceId: 'rosarito-site',
+  toSpaceExists: true,
+  fromTimezone: 'America/Los_Angeles',
+  toTimezone: 'America/Los_Angeles'
+}
+
+test('잃을 것이 없으면 경고도 없다 — 정상 경로를 시끄럽게 만들지 않는다', () => {
+  const j = judgeMoveTwinSpace(CLEAN)
+  assert.equal(j.refusal, undefined)
+  assert.deepEqual(j.warnings, [])
+})
+
+test('없는 현장으로는 옮기지 않는다 — 조용히 새 공간을 만들지 않는다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, toSpaceExists: false })
+  assert.equal(j.refusal?.code, 'space-not-found')
+  assert.equal(j.refusal?.params?.spaceId, 'rosarito-site')
+})
+
+test('같은 현장으로 옮기는 것은 거절한다 — 할 일이 없는데 쓴 것처럼 답하지 않는다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, toSpaceId: 'wms-a-site' })
+  assert.equal(j.refusal?.code, 'same-space')
+})
+
+test('없는 트윈은 거절한다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, instanceId: undefined })
+  assert.equal(j.refusal?.code, 'twin-not-found')
+})
+
+test('벤치 사본은 옮기지 않는다 — 무엇의 측정인지 말할 수 없게 된다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, purpose: 'bench' })
+  assert.equal(j.refusal?.code, 'bench-copy')
+})
+
+test('현장이 없던 트윈도 옮길 수 있다 — 옛 트윈을 고칠 길을 막지 않는다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, fromSpaceId: undefined, fromTimezone: undefined, toTimezone: undefined })
+  assert.equal(j.refusal, undefined)
+})
+
+test('새 공간에 없는 구역을 가리키는 로케이션은 소속이 끊긴다고 말한다', () => {
+  const j = judgeMoveTwinSpace({
+    ...CLEAN,
+    areaRefs: ['bldg-1', 'floor-2', undefined, 'bldg-1', ''],
+    toAreaIds: ['floor-2']
+  })
+  const w = j.warnings.find(x => x.code === 'areas-left-behind')
+  assert.ok(w, '끊기는 소속을 말해야 한다')
+  assert.equal(w.params?.count, 1, '중복·빈 값은 세지 않는다')
+  assert.equal(w.params?.areas, 'bldg-1')
+  assert.equal(j.refusal, undefined, '막지는 않는다 — 새 공간에서 구역을 다시 그리는 것이 정상이다')
+})
+
+test('구역이 모두 새 공간에 있으면 그 경고는 없다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, areaRefs: ['bldg-1'], toAreaIds: ['bldg-1', 'floor-2'] })
+  assert.equal(j.warnings.find(x => x.code === 'areas-left-behind'), undefined)
+})
+
+test('시간대가 다르면 말한다 — 같은 저널이 다른 시각으로 읽힌다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, fromTimezone: 'Asia/Seoul', toTimezone: 'America/Los_Angeles' })
+  const w = j.warnings.find(x => x.code === 'timezone-differs')
+  assert.ok(w)
+  assert.equal(w.params?.from, 'Asia/Seoul')
+  assert.equal(w.params?.to, 'America/Los_Angeles')
+})
+
+test('시간대를 선언하지 않은 공간도 다름으로 센다 — 모르는 것을 같다고 하지 않는다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, fromTimezone: 'Asia/Seoul', toTimezone: undefined })
+  assert.ok(j.warnings.find(x => x.code === 'timezone-differs'))
+})
+
+test('옛 공간의 표현은 남는다고 말한다 — 그 화면에서 이 트윈이 사라진다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, fromRepresentationCount: 3 })
+  const w = j.warnings.find(x => x.code === 'representations-left-behind')
+  assert.ok(w)
+  assert.equal(w.params?.count, 3)
+  assert.equal(w.params?.spaceId, 'wms-a-site')
+})
+
+test('실행 중 + 시간대 변화면 재기동 뒤에 적용된다고 말한다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, running: true, fromTimezone: 'Asia/Seoul', toTimezone: 'UTC' })
+  assert.ok(j.warnings.find(x => x.code === 'running'))
+})
+
+test('실행 중이지만 시간대가 같으면 말할 것이 없다 — 없는 걱정을 만들지 않는다', () => {
+  const j = judgeMoveTwinSpace({ ...CLEAN, running: true })
+  assert.equal(j.warnings.find(x => x.code === 'running'), undefined)
+})
+
+test('거절이면 경고를 함께 내지 않는다 — 일어나지 않을 일을 설명하지 않는다', () => {
+  const j = judgeMoveTwinSpace({
+    ...CLEAN,
+    toSpaceExists: false,
+    areaRefs: ['bldg-1'],
+    toAreaIds: [],
+    fromRepresentationCount: 2,
+    fromTimezone: 'Asia/Seoul',
+    toTimezone: 'UTC'
+  })
+  assert.ok(j.refusal)
+  assert.deepEqual(j.warnings, [])
+})
+
+/* ── 현장에서 떼기 ─────────────────────────────────────────────────────────── */
+
+test('현장이 없는 트윈은 뗄 것이 없다 — 아무 일도 없는데 했다고 답하지 않는다', () => {
+  const j = judgeDetachTwinSpace({ instanceId: 'wms-a', fromSpaceId: undefined })
+  assert.equal(j.refusal?.code, 'no-space')
+})
+
+test('벤치 사본은 떼지 않는다 — 무엇의 측정인지 말할 수 없게 된다', () => {
+  const j = judgeDetachTwinSpace({ instanceId: 'bench-1', fromSpaceId: 'rosarito-site', purpose: 'bench' })
+  assert.equal(j.refusal?.code, 'bench-copy')
+})
+
+test('떼면 볼 무대가 없어진다고 반드시 말한다 — 사용자가 고장으로 읽지 않게', () => {
+  const j = judgeDetachTwinSpace({ instanceId: 'wms-a', fromSpaceId: 'rosarito-site' })
+  assert.equal(j.refusal, undefined)
+  assert.ok(j.warnings.find(w => w.code === 'no-stage'), '무대가 없어진다는 말은 언제나 있다')
+})
+
+test('옛 현장의 표현과 시간 기준을 말한다 — 남는 것을 밝힌다', () => {
+  const j = judgeDetachTwinSpace({
+    instanceId: 'wms-a',
+    fromSpaceId: 'rosarito-site',
+    fromRepresentationCount: 2,
+    fromTimezone: 'America/Los_Angeles'
+  })
+  assert.equal(j.warnings.find(w => w.code === 'representations-left-behind')?.params?.count, 2)
+  assert.equal(j.warnings.find(w => w.code === 'timebase-kept')?.params?.timezone, 'America/Los_Angeles')
+})
+
+test('시간대를 선언하지 않은 현장이면 시간 기준을 말하지 않는다 — 없는 사실을 만들지 않는다', () => {
+  const j = judgeDetachTwinSpace({ instanceId: 'wms-a', fromSpaceId: 'rosarito-site' })
+  assert.equal(j.warnings.find(w => w.code === 'timebase-kept'), undefined)
+})