@things-factory/headless-twin 10.0.5 → 10.0.7

package/test/live-mirror-parity.test.ts

@@ -4,7 +4,7 @@
  *
  * 결론(검증됨):
  *  - 핵심 관측 상태(점유·용량·위치·아이템 = "사진에 찍힌 것")는 이벤트만으로 재구성 → sim↔live **완전 일치**.
- *  - 파생 지표(mover OEE·node status = "계산해서 만든 통계")는 이벤트에 없음 → live 미러엔 **부재**.
+ *  - 파생 지표(설비 OEE·location status = "계산해서 만든 통계")는 이벤트에 없음 → live 미러엔 **부재**.
  *    이는 라우팅 결함이 아니라(통로는 온전), live 에서 파생 지표를 **누가 생산하나**의 데이터원 결정 사항.
  *    (실 텔레메트리 / projector 계산 / 별도 분석 층 — face2-inbound-live §6, reference-management P3.)
  */
@@ -25,11 +25,11 @@ const master = () => ({
   space: { width: 90, depth: 40, unit: 'm' },
   locations: [
     { id: 'a-dc', type: 'warehouse', role: 'area' as const, name: '창고' },
-    { id: 'dock-recv', type: 'dock', role: 'node' as const, capacity: 100 },
-    { id: 'rack-1', type: 'storage', role: 'node' as const, capacity: 60 },
-    { id: 'rack-2', type: 'storage', role: 'node' as const, capacity: 60 },
-    { id: 'staging', type: 'staging', role: 'node' as const, capacity: 80 },
-    { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, capacity: 100 }
+    { id: 'dock-recv', type: 'dock', role: 'location' as const, capacity: 100 },
+    { id: 'rack-1', type: 'storage', role: 'location' as const, capacity: 60 },
+    { id: 'rack-2', type: 'storage', role: 'location' as const, capacity: 60 },
+    { id: 'staging', type: 'staging', role: 'location' as const, capacity: 80 },
+    { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, capacity: 100 }
   ],
   equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }]
 })
@@ -52,11 +52,21 @@ function runSim() {
 const sortByTag = (arr: any[]) => [...arr].sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0))
 
 /** 파생/sim-계산 필드 제거 → "핵심 관측 상태"만 남긴다.
- *  node.status = 커널 기본값(파생), mover.oee = 커널 계산 지표(파생). 이벤트에 없어 live 미러 부재. */
+ *  location.status = 커널 기본값(파생), equipment.oee = 커널 계산 지표(파생). 이벤트에 없어 live 미러 부재. */
+/**
+ * 설계상 두 구동이 다른 자리만 걷어낸다 — **여기 없는 차이는 결함이다.**
+ *
+ * 엔티티 마커가 `kind` → `entity` 로 바뀌었을 때(도메인 kind 를 마커가 덮어쓰던 문제) 이 필터가
+ * 따라가지 못해 **아무것도 걸러내지 못하고 있었다.** 그래서 실패가 "정합성 결함" 처럼 보였다.
+ *
+ * 지금 남는 차이는 하나뿐이다:
+ *  · `oee` — 시뮬은 자기가 계측하고, 라이브는 **호스트**가 이벤트를 적분해 채운다(withLiveOee).
+ *    커널 층에서만 비대칭이고 호스트가 닫는다(커널 적합성 하네스도 같은 예외를 선언한다).
+ * (`location.status` 는 예외였다가 해소됐다 — 저장값이 아니라 포화도 파생이라 두 구동이 같은 값을 낸다.)
+ */
 const coreOnly = (d: any) => {
   const c = { ...d }
-  if (c.kind === 'node') delete c.status
-  if (c.kind === 'mover') delete c.oee
+  if (c.entity === 'equipment') delete c.oee
   return c
 }
 
@@ -92,10 +102,10 @@ function runSimRich() {
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const, name: '창고' },
-      { id: 'dock-recv', type: 'dock', role: 'node' as const, capacity: 100 },
-      { id: 'rack-1', type: 'storage', role: 'node' as const, capacity: 6 }, // 소용량 → 병목
-      { id: 'staging', type: 'staging', role: 'node' as const, capacity: 80 },
-      { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, capacity: 100 }
+      { id: 'dock-recv', type: 'dock', role: 'location' as const, capacity: 100 },
+      { id: 'rack-1', type: 'storage', role: 'location' as const, capacity: 6 }, // 소용량 → 병목
+      { id: 'staging', type: 'staging', role: 'location' as const, capacity: 80 },
+      { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, capacity: 100 }
     ],
     equipment: [
       { id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv', mtbfMs: 5000, mttrMs: 8000 }, // 고장
@@ -127,9 +137,9 @@ test('명시: 파생 층(attentions·OEE·motion·clock)은 live 미러 부재/
   assert.equal(sim.attentions.length > 0 && (live.attentions?.length ?? 0), 0, 'live: attentions 부재 — computeAttentions 를 미러 State 에 재적용해야 복원')
 
   // 2) OEE(계산 지표) — 시간 누적. live 부재.
-  const simFk = sim.movers.find((x: any) => x.id === 'fk-1')
-  const liveFk = live.movers.find((x: any) => x.id === 'fk-1')
-  assert.ok(simFk?.oee, 'sim: mover OEE 계산됨')
+  const simFk = sim.equipment.find((x: any) => x.id === 'fk-1')
+  const liveFk = live.equipment.find((x: any) => x.id === 'fk-1')
+  assert.ok(simFk?.oee, 'sim: 설비 OEE 계산됨')
   assert.equal(liveFk?.oee, undefined, 'live: OEE 부재(시간 누적 지표)')
 
   // 3) simClockMs(sim 클럭) — live 는 실시간이 클럭원.
@@ -150,7 +160,7 @@ test('★ derive 층: computeAttentions 를 projector 미러에 재적용 →
   const { sim, live } = runSimRich()
 
   // (a) 순수 함수가 커널 자체 attentions 를 재현 — 추출 정확성(sim state 로 호출 == 커널 계산 관측기반).
-  const simDerivedKinds = new Set(deriveAttentions({ movers: sim.movers, nodes: sim.nodes, orders: sim.orders }).map(a => a.kind))
+  const simDerivedKinds = new Set(deriveAttentions({ equipment: sim.equipment, locations: sim.locations, orders: sim.orders }).map(a => a.kind))
   for (const a of sim.attentions ?? []) {
     if (['breakdown', 'bottleneck', 'hold'].includes(a.kind)) {
       assert.ok(simDerivedKinds.has(a.kind), `순수 함수가 sim 관측기반 attention '${a.kind}' 재현`)
@@ -159,7 +169,7 @@ test('★ derive 층: computeAttentions 를 projector 미러에 재적용 →
 
   // (b) ★ projector 미러 State 에 재적용 → live 원본엔 없던 attentions 복원.
   assert.equal(live.attentions?.length ?? 0, 0, 'live projector 원본엔 attentions 없음(계산 안 함)')
-  const liveKinds = new Set(deriveAttentions({ movers: live.movers, nodes: live.nodes, orders: live.orders }).map(a => a.kind))
+  const liveKinds = new Set(deriveAttentions({ equipment: live.equipment, locations: live.locations, orders: live.orders }).map(a => a.kind))
   assert.ok(liveKinds.has('breakdown') || liveKinds.has('bottleneck'),
     'derive 재적용 → live 에 관측기반 attention(breakdown/bottleneck) 복원')
 })
@@ -181,7 +191,7 @@ test('★ withLiveAttentions: projector 미러 스냅샷에 attentions 보강 (a
  */
 test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE 재생산 (live=텔레메트리/누적기 카운터 + 공식)', () => {
   const { sim } = runSimRich()
-  const m = sim.movers.find((x: any) => x.oee && (x.oee.runMs > 0 || x.oee.downMs > 0)) ?? sim.movers.find((x: any) => x.oee)
+  const m = sim.equipment.find((x: any) => x.oee && (x.oee.runMs > 0 || x.oee.downMs > 0)) ?? sim.equipment.find((x: any) => x.oee)
   assert.ok(m?.oee, 'sim 무버 oee 존재')
   const o = m.oee
 
@@ -197,3 +207,27 @@ test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE
   assert.ok(near(derived.quality, o.quality), 'quality 재생산')
   assert.ok(near(derived.overall, o.overall), 'overall 재생산')
 })
+
+/*
+ * ── 배선 감시: 라이브가 커널에 **모든 채널을 넘기는가** ──────────────────────
+ *
+ * 규칙(deriveAttentions)은 커널 테스트가 지킨다. 지켜지지 않던 것은 **배선**이다 —
+ * `withLiveAttentions` 가 채널 하나를 안 넘기면 같은 공장이 시뮬에서는 막혔다고 하고 라이브에서는
+ * 멀쩡하다고 답한다. 규칙은 멀쩡하니 규칙 테스트는 통과하고, 어긋남은 아무 데서도 안 잡힌다.
+ * (`tasks` 를 새로 넣을 때 실제로 그럴 뻔했다.)
+ *
+ * 그래서 채널마다 신호가 하나씩 나오는 상태를 만들고, **넷이 다 나오는지** 본다. 앞으로 채널이
+ * 하나 더 늘고 라이브 배선만 빠지면 여기서 깨진다.
+ */
+test('★ withLiveAttentions 는 채널을 하나도 떨어뜨리지 않는다(설비·자리·오더·작업)', () => {
+  const state = {
+    nowTime: '2026-03-02T12:00:00.000Z',
+    equipment: [{ id: 'rbt-1', status: 'down', location: 'wc-1' }],
+    locations: [{ id: 'wc-1', capacity: 2, occupancy: 2 }],
+    orders: [{ id: 'ord-1', held: true, status: 'released' }],
+    tasks: Array.from({ length: 8 }, (_, i) => ({ id: `t${i}`, kind: 'paint', status: 'created' }))
+  }
+  const kinds = new Set((withLiveAttentions(state as any).attentions ?? []).map((a: any) => a.kind))
+  for (const expected of ['breakdown', 'bottleneck', 'hold', 'work-backlog'])
+    assert.ok(kinds.has(expected), `라이브 배선이 '${expected}' 채널을 떨어뜨렸다 — 넘긴 것: ${[...kinds].join(', ') || '없음'}`)
+})

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

@@ -1,7 +1,7 @@
 /*
- * masterToTwin — 모델→board 토폴로지 변환 시임. 템플릿/레퍼런스 master → board{nodes,movers,layout,spaceId}+space.
+ * masterToTwin — 모델→board 토폴로지 변환 시임. 템플릿/레퍼런스 master → board{locations,equipment,layout,spaceId}+space.
  * 스트림라인의 "모델링→board" 연결부: 템플릿(build)이 낸 master 를 커널이 소비할 BoardDef 로 바꾼다.
- * role(node/area/both) 분기·footprint→layout·spaceId 파생·미지 타입 경고를 고정.
+ * role(location/area/both) 분기·footprint→layout·spaceId 파생·미지 타입 경고를 고정.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -17,22 +17,22 @@ const wmsMaster = () => ({
   space: { width: 90, depth: 40, unit: 'm', geo: { lat: 37.5, lon: 127.0, rotation: 0 } },
   locations: [
     { id: 'a-dc', type: 'warehouse', role: 'area' as const, name: '창고' },
-    { id: 'dock-recv', type: 'dock', role: 'node' as const, name: '입고 도크', capacity: 100 },
-    { id: 'rack-1', type: 'storage', role: 'node' as const, name: '랙1', parentId: 'a-dc', capacity: 60 },
-    { id: 'rack-2', type: 'storage', role: 'node' as const, name: '랙2', parentId: 'a-dc', capacity: 60 },
-    { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, name: '출고 도크', capacity: 100 }
+    { id: 'dock-recv', type: 'dock', role: 'location' as const, name: '입고 도크', capacity: 100 },
+    { id: 'rack-1', type: 'storage', role: 'location' as const, name: '랙1', parentId: 'a-dc', capacity: 60 },
+    { id: 'rack-2', type: 'storage', role: 'location' as const, name: '랙2', parentId: 'a-dc', capacity: 60 },
+    { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, name: '출고 도크', capacity: 100 }
   ],
   equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }]
 })
 
 test('locations role → 노드/영역 분기, equipment → 무버', () => {
   const { board, spaceContent } = masterToTwin(wmsMaster())
-  assert.deepEqual(board.nodes.map((n: any) => n.id).sort(), ['dock-recv', 'dock-ship', 'rack-1', 'rack-2'], '노드=role node')
+  assert.deepEqual(board.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.movers, [{ id: 'fk-1', kind: 'forklift', homeNode: 'dock-recv', mtbfMs: undefined, mttrMs: undefined, gs1Id: undefined }], 'equipment→mover(homeLocationId→homeNode, gs1Id 통과)')
-  assert.equal(board.nodes.find((n: any) => n.id === 'rack-1').capacity, 60, 'capacity 전달')
-  assert.equal(board.nodes.find((n: any) => n.id === 'dock-recv').parentId, undefined, 'parentId 없으면 undefined')
+  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')
 })
 
 test('coordinate-free: footprint 없으면 layout 비어있음(미배치 → A2)', () => {
@@ -57,10 +57,10 @@ test('spaceId: 명시 시 참조, 없으면 source 파생 (공동배치 시임)'
 
 test('미지 노드 타입 경고 — 카탈로그 있으면 검증(버리진 않음)', () => {
   const m = wmsMaster()
-  ;(m.locations as any).push({ id: 'weird', type: '__unknown__', role: 'node', capacity: 1 })
+  ;(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.nodes.some((n: any) => n.id === 'weird'), '경고해도 노드는 유지(반영 우선)')
+  assert.ok(withCat.board.locations.some((n: any) => n.id === 'weird'), '경고해도 노드는 유지(반영 우선)')
   // 정상 타입만이면 경고 0
   assert.equal(masterToTwin(wmsMaster(), DOMAIN_CATALOG).warnings.length, 0, '알려진 타입만 → 경고 0')
   // 카탈로그 없으면 검증 생략
@@ -71,7 +71,7 @@ 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.nodes.some((n: any) => n.id === 'dock-door-1'), 'both → 노드')
+  assert.ok(board.locations.some((n: any) => n.id === 'dock-door-1'), 'both → 노드')
   assert.ok(spaceContent.areas.some((a: any) => a.id === 'dock-door-1'), 'both → 영역')
 })
 
@@ -111,3 +111,77 @@ test('현장 물질화(#4): 표현도 geo 도 없으면 빈 표현 + 경고(정
     '뷰 없는 공간 경고 표면화'
   )
 })
+
+/* ── 공정 명세 통과 (ISA-95 OperationsSegment) ──────────────────────────────
+ *
+ * 시뮬레이션의 소요·수율이 커널 상수였던 것을 데이터로 옮기는 경로의 마지막 한 칸: 마스터가 명세를
+ * 말하면 board 를 통해 커널까지 **손대지 않고** 간다. 기간은 표준 표기(ISO 8601)로 그대로 흐른다 —
+ * 여기서 밀리초로 바꾸면 표준과 어긋나고, 커널이 다시 해석할 기회를 잃는다.
+ */
+const mesMaster = () => ({
+  source: 'plant-1',
+  system: 'mes' as const,
+  siteName: '공장',
+  space: { width: 100, depth: 50, geo: { lat: 32.3, lon: -117.0 } },
+  locations: [
+    { id: 'a-prod', type: 'factory', role: 'area' as const, name: '생산' },
+    { id: 'cut-1', type: 'cut-station', role: 'location' as const, name: '절단', capacity: 4 }
+  ],
+  equipment: [{ id: 'mch-1', kind: 'cutter', homeLocationId: 'cut-1' }],
+  operations: [
+    {
+      key: 'cut', label: 'cutting', intent: 'process' as const, locationType: 'cut-station', resourceType: 'cutter',
+      duration: 'PT25M',
+      variability: { distribution: 'triangular' as const, min: 'PT20M', max: 'PT35M', mode: 'PT24M' },
+      parameters: [{ id: 'yield', value: '0.995' }]
+    }
+  ]
+})
+
+test('공정 명세가 board 로 그대로 통과한다 — 표준 표기 유지, 값 변형 없음', () => {
+  const { board, warnings } = masterToTwin(mesMaster(), DOMAIN_CATALOG)
+  assert.equal((board as any).operations.length, 1)
+  const op = (board 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 m: any = mesMaster()
+  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')),
+    `기본값으로 굴러갈 것을 알린다: ${JSON.stringify(warnings)}`
+  )
+})
+
+/* ── 처리 능력·교대 통과 ─────────────────────────────────────────────────
+ *
+ * `capacity` 한 필드가 저장 용량과 처리 능력을 겸하던 것을 갈랐다. 인제스트도 두 축을 따로 실어야
+ * 커널이 "20개를 쌓아 두지만 한 번에 한 대만 깎는다" 를 표현할 수 있다. 교대도 같다.
+ */
+test('처리 능력과 교대가 board 로 통과한다 — 저장 용량과 섞이지 않는다', () => {
+  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')
+  assert.equal(location.capacity, 4, '저장 용량')
+  assert.equal(location.parallelism, 1, '처리 능력 — 다른 축')
+  assert.deepEqual((board 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')
+  assert.equal('parallelism' in location, false)
+  assert.equal('window' in (board as any).equipment[0], false)
+})

package/test/model-basis.test.ts

@@ -0,0 +1,86 @@
+/*
+ * 모델 근거 비교 — **배운 모델에만 보정을 적용하기 위한 관문.**
+ *
+ * 배경: 예측 출력 보정(P3.2)은 "그때 모델이 이만큼 치우쳐 있다" 를 배운다. 소요시간 추정기(실측·거리)
+ * 와 공정 명세가 들어오면서 모델 자체가 바뀔 수 있게 됐고, 그러면 옛 편향을 그대로 밀어 주는 **이중
+ * 보정**이 생긴다. 근거가 달라졌으면 적용하지 않는다(그리고 그 사실을 응답에 싣는다).
+ *
+ * 비교를 **상대 허용오차**로 하는 이유: 양자화 지문은 버킷 경계에 걸린 값이 1초 드리프트로도 달라져
+ * "작은 드리프트로 학습을 무효화하지 않는다" 는 목적을 경계에서 못 지킨다. 비율은 어디서든 같다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { BASIS_TOLERANCE, describeModelBasis, modelBasisChanged } from '../server/engine/model-basis.ts'
+
+test('같은 근거면 바뀌지 않았다 — 키 순서에 흔들리지 않는다', () => {
+  assert.equal(
+    modelBasisChanged({ measured: { pick: 22_000, putaway: 47_000 } }, { measured: { putaway: 47_000, pick: 22_000 } }),
+    false
+  )
+})
+
+test('작은 드리프트는 같은 모델 — 경계에서도 성립한다(버킷이 아니라 비율)', () => {
+  /* 47.0 → 47.9 (약 1.9%): 5초 버킷이면 45↔50 으로 갈렸을 값이다. */
+  assert.equal(modelBasisChanged({ measured: { putaway: 47_000 } }, { measured: { putaway: 47_900 } }), false)
+  /* 허용오차 경계 바로 아래·위 */
+  assert.equal(modelBasisChanged({ measured: { p: 100_000 } }, { measured: { p: 105_000 } }), false, '5%')
+  assert.equal(modelBasisChanged({ measured: { p: 100_000 } }, { measured: { p: 130_000 } }), true, '30%')
+})
+
+test('실측이 실제로 달라지면 다른 모델 — 30초 작업이 47초가 되면 옛 보정은 무효', () => {
+  assert.equal(modelBasisChanged({ measured: { putaway: 30_000 } }, { measured: { putaway: 47_000 } }), true)
+})
+
+test('새로 배운 종류·사라진 종류는 다른 모델 — 값이 없다가 생긴 것도 변화다', () => {
+  assert.equal(modelBasisChanged({ measured: { pick: 20_000 } }, { measured: { pick: 20_000, putaway: 47_000 } }), true)
+  assert.equal(modelBasisChanged({ measured: { pick: 20_000, putaway: 47_000 } }, { measured: { pick: 20_000 } }), true)
+})
+
+test('속도가 바뀌면 다른 모델 — 이동시간 모델이 바뀐 것이다', () => {
+  assert.equal(modelBasisChanged({ speeds: { forklift: 2 } }, { speeds: { forklift: 4 } }), true)
+  assert.equal(modelBasisChanged({ speeds: { forklift: 2 } }, { speeds: { forklift: 2.05 } }), false)
+})
+
+test('선언 명세가 바뀌면 다른 모델 — 표기 원문을 그대로 비교한다', () => {
+  assert.equal(
+    modelBasisChanged({ declared: [{ key: 'cut', duration: 'PT25M' }] }, { declared: [{ key: 'cut', duration: 'PT30M' }] }),
+    true
+  )
+  assert.equal(
+    modelBasisChanged({ declared: [{ key: 'cut', duration: 'PT25M' }] }, { declared: [{ key: 'cut', duration: 'PT25M' }] }),
+    false
+  )
+})
+
+test('소요 없는 선언은 모델을 바꾸지 않는다', () => {
+  assert.equal(modelBasisChanged({ declared: [{ key: 'cut' }] }, { declared: [] }), false)
+})
+
+test('뜻 없는 값은 근거가 아니다 — 0·음수·NaN 은 무시한다', () => {
+  assert.equal(modelBasisChanged({ measured: { pick: 0 } }, {}), false)
+  assert.equal(modelBasisChanged({ measured: { pick: NaN } }, { speeds: { f: -1 } }), false)
+})
+
+test('한쪽 근거를 모르면 판정하지 않는다 — 모르는 것을 근거로 학습을 끊지 않는다', () => {
+  assert.equal(modelBasisChanged(undefined, { measured: { pick: 20_000 } }), false)
+  assert.equal(modelBasisChanged({ measured: { pick: 20_000 } }, undefined), false)
+})
+
+test('세 재료가 섞이지 않는다 — 같은 이름이 다른 재료에 있으면 다른 모델', () => {
+  assert.equal(modelBasisChanged({ measured: { x: 10_000 } }, { speeds: { x: 10_000 } }), true)
+})
+
+test('허용오차는 조절 가능하고 기본값이 명시돼 있다', () => {
+  assert.equal(BASIS_TOLERANCE, 0.1)
+  assert.equal(modelBasisChanged({ measured: { p: 100 } }, { measured: { p: 130 } }, 0.5), false, '느슨하게 주면 같은 모델')
+})
+
+test('사람이 읽는 요약을 낸다 — 로그에서 왜 달라졌는지 눈으로 본다', () => {
+  const d = describeModelBasis({ measured: { putaway: 47_000 }, speeds: { forklift: 2 }, declared: [{ key: 'cut', duration: 'PT25M' }] })
+  assert.match(d, /measured\(putaway=47s\)/)
+  assert.match(d, /speed\(forklift=2m\/s\)/)
+  assert.match(d, /declared\(cut=PT25M\)/)
+  assert.equal(describeModelBasis({}), 'kernel defaults only')
+  assert.equal(describeModelBasis(undefined), 'unknown')
+})

package/test/oee-accumulator.test.ts

@@ -21,10 +21,10 @@ function runSimCollect() {
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const },
-      { id: 'dock-recv', type: 'dock', role: 'node' as const, capacity: 100 },
-      { id: 'rack-1', type: 'storage', role: 'node' as const, capacity: 60 },
-      { id: 'staging', type: 'staging', role: 'node' as const, capacity: 80 },
-      { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, capacity: 100 }
+      { id: 'dock-recv', type: 'dock', role: 'location' as const, capacity: 100 },
+      { id: 'rack-1', type: 'storage', role: 'location' as const, capacity: 60 },
+      { id: 'staging', type: 'staging', role: 'location' as const, capacity: 80 },
+      { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, capacity: 100 }
     ],
     equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv', mtbfMs: 5000, mttrMs: 8000 }]
   }
@@ -41,7 +41,7 @@ function runSimCollect() {
 
 test('★ OEE 누적기: downMs 정확 · busyMs=run+setup · 근사 OEE 유효', () => {
   const { events, snap } = runSimCollect()
-  const simOee = snap.movers.find((x: any) => x.id === 'fk-1')?.oee
+  const simOee = snap.equipment.find((x: any) => x.id === 'fk-1')?.oee
   assert.ok(simOee, 'sim fk-1 oee 존재')
   assert.ok(simOee.downMs > 0, '시나리오가 고장(down) 유발 — 검증 의미 있음')
 
@@ -82,20 +82,20 @@ test('★ OEE 누적기: quality.output 델타 소비 → quality 정확 (good/s
   assert.ok(Math.abs(oee.quality - 0.8) < 1e-9, 'quality = good/(good+scrap) = 0.8 (텔레메트리 없이 이벤트로 도출)')
 })
 
-test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live mover payload 에 oee 포함 (원 갭 종료)', () => {
+test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비 payload 에 oee 포함 (원 갭 종료)', () => {
   const { events, board } = runSimCollect()
   const proj = new StateProjector(board)
   const acc = new OeeAccumulator()
   for (const e of events) { proj.apply(e); acc.apply(e) }
 
   const rawLive = proj.snapshot() as any
-  // 원 갭: projector 미러 mover 엔 oee 없음.
-  assert.equal(rawLive.movers.find((m: any) => m.id === 'fk-1')?.oee, undefined, 'projector 미러엔 oee 부재(원 갭)')
+  // 원 갭: projector 미러 설비엔 oee 없음.
+  assert.equal(rawLive.equipment.find((m: any) => m.id === 'fk-1')?.oee, undefined, 'projector 미러엔 oee 부재(원 갭)')
 
   // withLiveOee 로 보강 → buildEntityDeltas payload 에 oee 포함(sim 과 동일 형상 = 보드 OEE 컴포넌트 live 렌더).
   const enriched = withLiveOee(rawLive, acc)
   const fk = buildEntityDeltas(enriched).find(d => d.tag === 'fk-1')!.data as any
-  assert.ok(fk.oee, 'withLiveOee 후 mover data(tag) payload 에 oee 포함 — live OEE 갭 종료')
+  assert.ok(fk.oee, 'withLiveOee 후 설비 data(tag) payload 에 oee 포함 — live OEE 갭 종료')
   // buildEntityDeltas shapeOee = 정수 퍼센트(0-100), raw ms 제외.
   assert.ok(fk.oee.overall >= 0 && fk.oee.overall <= 100, 'oee.overall ∈ [0,100] 정수 퍼센트')
   assert.ok(fk.oee.availability < 100, 'availability < 100 (고장 시간 반영 — 누적기 downMs)')

package/test/scale-twin-bench.test.ts

@@ -1,6 +1,6 @@
 /*
  * 스케일 테스트 트윈 벤치 — 미국 공장(WMS+MES+YMS) 형태를 대규모로 스케일업, 5종 동기 엔티티 전부 부하.
- * 동기 엔티티 = nodes·items(재고)·movers·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
+ * 동기 엔티티 = locations·items(재고)·equipment·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
  * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송)·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
@@ -15,7 +15,7 @@ const T0 = '2026-07-20T00:00:00.000Z'
 const MB = (b: number) => Math.round(b / 1048576)
 
 /** 미국 공장형 대규모 master 생성: 건물>층>존 area 계층 + 노드(storage/dock/station) + 무버(forklift/cutter/welder/hostler). */
-function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: number; nodesPerZone: number; movers: number }) {
+function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: number; nodesPerZone: number; equipment: number }) {
   const locations: any[] = []
   let nodeN = 0
   for (let b = 0; b < tier.buildings; b++) {
@@ -27,57 +27,57 @@ function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: numbe
         locations.push({ id: zid, type: 'zone', role: 'area', name: `존 ${b}-${f}-${z}`, parentId: `bld-${b}-flr-${f}` })
         for (let n = 0; n < tier.nodesPerZone; n++) {
           const t = n % 4 === 0 ? 'dock' : n % 4 === 1 ? 'staging' : 'storage'
-          locations.push({ id: `nd-${nodeN}`, type: t, role: 'node', name: `노드 ${nodeN}`, parentId: zid, capacity: 500, footprint: { x: nodeN % 100, y: (nodeN / 100) | 0, w: 1, h: 1 } })
+          locations.push({ id: `nd-${nodeN}`, type: t, role: 'location', name: `노드 ${nodeN}`, parentId: zid, capacity: 500, footprint: { x: nodeN % 100, y: (nodeN / 100) | 0, w: 1, h: 1 } })
           nodeN++
         }
       }
     }
   }
   const KINDS = ['forklift', 'cutter', 'welder', 'hostler']
-  const equipment = Array.from({ length: tier.movers }, (_, i) => ({ id: `mv-${i}`, kind: KINDS[i % 4], homeLocationId: `nd-${i % nodeN}` }))
+  const equipment = Array.from({ length: tier.equipment }, (_, i) => ({ id: `mv-${i}`, kind: KINDS[i % 4], homeLocationId: `nd-${i % nodeN}` }))
   return {
     master: { source: 'scale-us', system: 'wms' as const, siteName: 'US 공장(스케일)', space: { width: 500, depth: 300, unit: 'm', geo: { lat: 32.7, lon: -117.1 } }, locations, equipment },
-    nodeCount: nodeN,
+    locationCount: nodeN,
     areaCount: locations.filter(l => l.role === 'area').length
   }
 }
 
-function itemEnv(i: number, node: string): any {
-  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [`urn:epc:id:sscc:0614141.${i}`], readPoint: node })
+function itemEnv(i: number, location: string): any {
+  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [`urn:epc:id:sscc:0614141.${i}`], readPoint: location })
   return { eventId: `i${i}`, eventType: `epcis.${ev.type}`, eventTime: T0, tenantId: 't', data: ev }
 }
-const moverEnv = (id: string, kind: string, loc: string): any => ({ eventId: id, eventType: OP_EVENT.equipment, eventTime: T0, tenantId: 't', data: { moverId: id, kind, status: 'running', location: loc } })
+const equipmentEnv = (id: string, kind: string, loc: string): any => ({ eventId: id, eventType: OP_EVENT.equipment, eventTime: T0, tenantId: 't', data: { moverId: id, kind, status: 'running', location: loc } })
 const taskEnv = (id: string, to: string): any => ({ eventId: id, eventType: OP_EVENT.task, eventTime: T0, tenantId: 't', data: { taskId: id, kind: 'move', status: 'in-progress', toNode: to } })
 const orderEnv = (id: string): any => ({ eventId: id, eventType: OP_EVENT.order, eventTime: T0, tenantId: 't', data: { orderId: id, kind: 'inbound', status: 'in-progress', requested: 100, fulfilled: 50 } })
 
 const TIERS = {
-  medium: { buildings: 3, floorsPer: 3, zonesPer: 4, nodesPerZone: 8, movers: 80, items: 30000, tasks: 2000, orders: 500 },
-  large: { buildings: 6, floorsPer: 4, zonesPer: 6, nodesPerZone: 12, movers: 300, items: 120000, tasks: 10000, orders: 2000 }
+  medium: { buildings: 3, floorsPer: 3, zonesPer: 4, nodesPerZone: 8, equipment: 80, items: 30000, tasks: 2000, orders: 500 },
+  large: { buildings: 6, floorsPer: 4, zonesPer: 6, nodesPerZone: 12, equipment: 300, items: 120000, tasks: 10000, orders: 2000 }
 }
 
 for (const [name, tier] of Object.entries(TIERS)) {
   test(`스케일 트윈 [${name}] — 구조 생성 + 5종 엔티티 부하 실측`, () => {
     // 1) 구조 생성(masterToTwin) — 노드·무버·area 계층
-    const { master, nodeCount, areaCount } = bigMaster(tier)
+    const { master, locationCount, areaCount } = bigMaster(tier)
     let t = performance.now()
     const { board, spaceContent } = masterToTwin(master)
     const tMaster = performance.now() - t
-    console.log(`\n  [${name}] 구조: 노드 ${nodeCount.toLocaleString()} · 무버 ${tier.movers} · area ${areaCount}(계층) · masterToTwin ${tMaster.toFixed(0)}ms`)
-    assert.equal(board.nodes.length, nodeCount)
+    console.log(`\n  [${name}] 구조: 노드 ${locationCount.toLocaleString()} · 무버 ${tier.equipment} · area ${areaCount}(계층) · masterToTwin ${tMaster.toFixed(0)}ms`)
+    assert.equal(board.locations.length, locationCount)
     assert.equal((spaceContent.areas ?? []).length, areaCount, 'area 계층 생성')
 
     const proj = new StateProjector(board)
-    const movers = board.movers as any[]
+    const equipment = board.equipment as any[]
 
-    // 2) apply 처리량 — 5종 혼합(items·movers·tasks·orders)
+    // 2) apply 처리량 — 5종 혼합(items·equipment·tasks·orders)
     t = performance.now()
-    for (let i = 0; i < tier.items; i++) proj.apply(itemEnv(i, `nd-${i % nodeCount}`))
-    for (let i = 0; i < tier.movers; i++) proj.apply(moverEnv(movers[i].id, movers[i].kind, `nd-${i % nodeCount}`))
-    for (let i = 0; i < tier.tasks; i++) proj.apply(taskEnv(`tk-${i}`, `nd-${i % nodeCount}`))
+    for (let i = 0; i < tier.items; i++) proj.apply(itemEnv(i, `nd-${i % locationCount}`))
+    for (let i = 0; i < tier.equipment; i++) proj.apply(equipmentEnv(equipment[i].id, equipment[i].kind, `nd-${i % locationCount}`))
+    for (let i = 0; i < tier.tasks; i++) proj.apply(taskEnv(`tk-${i}`, `nd-${i % locationCount}`))
     for (let i = 0; i < tier.orders; i++) proj.apply(orderEnv(`or-${i}`))
-    const total = tier.items + tier.movers + tier.tasks + tier.orders
+    const total = tier.items + tier.equipment + tier.tasks + tier.orders
     const tApply = performance.now() - t
-    console.log(`  [${name}] apply: ${total.toLocaleString()} 이벤트(items+movers+tasks+orders) ${tApply.toFixed(0)}ms = ${Math.round((total / tApply) * 1000).toLocaleString()} ev/s`)
+    console.log(`  [${name}] apply: ${total.toLocaleString()} 이벤트(items+equipment+tasks+orders) ${tApply.toFixed(0)}ms = ${Math.round((total / tApply) * 1000).toLocaleString()} ev/s`)
 
     // 3) snapshot(전체 투영) — 5종 전부
     let s: any
@@ -85,7 +85,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     t = performance.now()
     for (let k = 0; k < iters; k++) s = proj.snapshot()
     const tSnap = (performance.now() - t) / iters
-    console.log(`  [${name}] snapshot: ${tSnap.toFixed(2)}ms/call (items ${s.items.length.toLocaleString()}·nodes ${s.nodes.length.toLocaleString()}·movers ${s.movers.length}·tasks ${s.tasks.length}·orders ${s.orders.length}) → 최대 ${Math.round(1000 / tSnap).toLocaleString()} snap/s`)
+    console.log(`  [${name}] snapshot: ${tSnap.toFixed(2)}ms/call (items ${s.items.length.toLocaleString()}·locations ${s.locations.length.toLocaleString()}·equipment ${s.equipment.length}·tasks ${s.tasks.length}·orders ${s.orders.length}) → 최대 ${Math.round(1000 / tSnap).toLocaleString()} snap/s`)
 
     // 4) 방송 payload(buildEntityDeltas)
     t = performance.now()
@@ -95,7 +95,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     console.log(`  [${name}] heap: ${MB(process.memoryUsage().heapUsed)}MB`)
 
     // 정합 sanity
-    assert.equal(s.movers.length, tier.movers)
+    assert.equal(s.equipment.length, tier.equipment)
     assert.equal(s.orders.length, tier.orders)
     assert.ok(s.items.length > 0)
   })

package/test/spec-coverage.test.ts

@@ -0,0 +1,113 @@
+/*
+ * 시뮬 명세 자격 판정 — **"이 예측으로 무엇을 말할 수 있나" 를 숫자로 가른다.**
+ *
+ * 배경: 공정 소요가 커널 상수였을 때와 현장 명세로 굴렸을 때가 응답에서 똑같이 "p50 168" 로 보였다.
+ * 그 둘을 구별하지 못하면 상대 비교용 숫자가 절대 예측처럼 읽힌다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { classifySpecCoverage, readSpecCoverage } from '../server/engine/spec-coverage.ts'
+
+test('전부 기본값이면 상대 비교만 — 절대 시각을 주장할 근거가 없다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'default' },
+      { kind: 'pick', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'relative')
+  assert.equal(r!.declaredDurations, 0)
+  assert.equal(r!.defaultDurations, 2)
+})
+
+test('전부 선언되면 절대 예측 시도 가능 — 단 정확도는 별개(이름이 capable 이다)', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'cut', duration: 'declared', variability: 'triangular', parameters: ['yield'] },
+      { kind: 'weld', duration: 'declared', variability: 'uniform' }
+    ]
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+  assert.equal(r!.varyingDurations, 2)
+})
+
+test('섞이면 partial — 한쪽만 접지된 사실을 감추지 않는다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'cut', duration: 'declared' },
+      { kind: 'paint', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'partial')
+  assert.equal(r!.declaredDurations, 1)
+  assert.equal(r!.defaultDurations, 1)
+})
+
+test('변동 없는 선언은 varying 0 — 고정값이면 대기·병목이 과소평가된다는 신호', () => {
+  const r = classifySpecCoverage({ operations: [{ kind: 'cut', duration: 'declared' }] })
+  assert.equal(r!.varyingDurations, 0)
+  const c = classifySpecCoverage({ operations: [{ kind: 'cut', duration: 'declared', variability: 'constant' }] })
+  assert.equal(c!.varyingDurations, 0, 'constant 는 변동이 아니다')
+})
+
+test('관측된 작업이 없으면 판정하지 않는다 — 모름을 relative 로 단정하지 않는다', () => {
+  assert.equal(classifySpecCoverage({ operations: [] }), undefined)
+  assert.equal(classifySpecCoverage({} as any), undefined)
+})
+
+test('커널이 보고 API 를 갖지 않으면 undefined — "전부 기본값" 이라 단정하지 않는다', () => {
+  assert.equal(readSpecCoverage({}), undefined)
+  assert.equal(readSpecCoverage(undefined), undefined)
+})
+
+test('커널 보고가 던져도 예측을 깨지 않는다', () => {
+  assert.equal(readSpecCoverage({ specCoverage: () => { throw new Error('boom') } }), undefined)
+})
+
+test('커널 보고를 그대로 분류한다 — 카운트를 다시 세지 않고 준 값을 존중', () => {
+  const r = readSpecCoverage({
+    specCoverage: () => ({
+      operations: [{ kind: 'cut', duration: 'declared', parameters: ['yield'] }],
+      declaredDurations: 1,
+      defaultDurations: 0
+    })
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+  assert.deepEqual(r!.operations[0].parameters, ['yield'])
+})
+
+/* ── 실측이 들어오면 자격이 한 칸 올라간다 ─────────────────────────────── */
+
+test('전부 이력에서 온 소요면 calibrated — 선언은 사람이 적은 값, 이것은 일어난 값', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'pick', duration: 'measured' }
+    ]
+  })
+  assert.equal(r!.qualification, 'calibrated')
+  assert.equal(r!.measuredDurations, 2)
+})
+
+test('실측과 선언이 섞이면 absolute-capable — 상수가 없으면 시각을 말할 수 있다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'cut', duration: 'declared' }
+    ]
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+})
+
+test('상수가 하나라도 섞이면 partial — 실측이 있어도 감추지 않는다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'pick', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'partial')
+  assert.equal(r!.measuredDurations, 1)
+  assert.equal(r!.defaultDurations, 1)
+})