@things-factory/headless-twin 10.0.6 → 10.0.7

package/test/kpi-fold.test.ts

@@ -11,6 +11,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { crossGroups, deltaP50, foldKpi, foldKpiBuckets, shiftWindow, type KpiEvent } from '../server/engine/kpi-fold.ts'
+import { judgeTargets, judgeGroupTargets, mergeTargets, scopedTargets } from '../server/engine/kpi-target.ts'
 
 const T0 = Date.parse('2026-07-30T00:00:00Z')
 const at = (sec: number) => new Date(T0 + sec * 1000).toISOString()
@@ -286,7 +287,7 @@ test('축의 합이 전체 처리량과 같다 — 어느 축에서도 건이
     ...three('c', 300, { kind: 'pick', orderId: 'o2', toNode: 'rack-1' })
   ]
   const whole = foldKpi(events, WINDOW)
-  for (const by of ['resource', 'taskKind', 'node', 'order'] as const) {
+  for (const by of ['resource', 'taskKind', 'location', 'order'] as const) {
     const r = foldKpi(events, WINDOW, { groupBy: by })
     const sum = r.groups!.items.reduce((a, g) => a + g.tasks, 0)
     assert.equal(sum, whole.throughput.tasks, `${by} 축의 합`)
@@ -318,7 +319,7 @@ test('노드 축은 가장 최근 도착지 — 진행에 따라 바뀌는 값
     taskAt('a', 'in-progress', 90, { fromNode: 'dock-1', toNode: 'rack-7' }),
     taskAt('a', 'completed', 100, { fromNode: 'dock-1', toNode: 'rack-7' })
   ]
-  const r = foldKpi(events, WINDOW, { groupBy: 'node' })
+  const r = foldKpi(events, WINDOW, { groupBy: 'location' })
   assert.deepEqual(r.groups?.items.map(g => g.key), ['rack-7'])
 })
 
@@ -327,7 +328,7 @@ test('구역 축은 노드→구역 지도를 받아야 낸다 — 지도가 없
   const blind = foldKpi(events, WINDOW, { groupBy: 'area' })
   assert.deepEqual(blind.groups?.items.map(g => [g.key, g.tasks]), [['unknown', 2]], '지도 없으면 unknown 하나')
 
-  const mapped = foldKpi(events, WINDOW, { groupBy: 'area', nodeArea: { 'rack-1': 'zone-a', 'rack-2': 'zone-a' } })
+  const mapped = foldKpi(events, WINDOW, { groupBy: 'area', locationArea: { 'rack-1': 'zone-a', 'rack-2': 'zone-a' } })
   assert.deepEqual(mapped.groups?.items.map(g => [g.key, g.tasks]), [['zone-a', 2]], '두 노드가 한 구역으로 모인다')
 })
 
@@ -467,3 +468,231 @@ test('교차: 비교 구간이 비면 전부 isNew 로 — 없던 것과 줄어
   assert.equal(c.items.every(x => x.isNew === true), true)
   assert.deepEqual(c.disappeared, [])
 })
+
+/* ── 교대 축 ─────────────────────────────────────────────────────────────────
+ *
+ * 3교대처럼 하루를 끊김 없이 덮는 현장에서는 캘린더가 가용 시간을 줄이지 않는다. 그러면 교대 선언이
+ * 무엇을 주는가: **"언제" 를 묻는 축**이다. "어느 교대가 느린가" 는 3교대 공장에서 가장 먼저 나오는
+ * 질문인데, 그 축이 없으면 답이 없었다.
+ *
+ * **저널에는 교대가 없다 — 계산한다.** 이벤트에 교대 이름을 찍어 두면 나중에 교대 시간을 고쳤을 때
+ * **과거가 옛 구분으로 굳어** 다시 셀 수 없다. 완료 시각 + 현장의 시각 기준 + 교대 선언에서 낸다.
+ */
+const SHIFTS_3 = [
+  { id: 'A', fromTime: '06:00', toTime: '14:00' },
+  { id: 'B', fromTime: '14:00', toTime: '22:00' },
+  { id: 'C', fromTime: '22:00', toTime: '06:00', toDayOffset: 1 as const }
+]
+
+/** 하루치 창 — 세 교대가 모두 들어오게. */
+const DAY = { fromMs: T0, toMs: T0 + 24 * 3600 * 1000 }
+
+/** `hour` 시(UTC)에 완료되는 작업 한 건. */
+const doneAtHour = (id: string, hour: number): KpiEvent[] => [
+  task(id, 'created', hour * 3600 - 60),
+  task(id, 'in-progress', hour * 3600 - 30),
+  task(id, 'completed', hour * 3600)
+]
+
+test('교대별로 쪼갠다 — 완료 시각에서 계산한다(저널에 없는 축)', () => {
+  const r = foldKpi(
+    [...doneAtHour('a1', 7), ...doneAtHour('a2', 9), ...doneAtHour('b1', 15), ...doneAtHour('c1', 23)],
+    DAY,
+    { groupBy: 'shift', shifts: SHIFTS_3 }
+  )
+  const by = Object.fromEntries((r.groups?.items ?? []).map(g => [g.key, g.tasks]))
+  assert.deepEqual(by, { A: 2, B: 1, C: 1 })
+  assert.equal(r.groups?.items.reduce((s, g) => s + g.tasks, 0), r.throughput.tasks, '축의 합이 전체와 같다')
+})
+
+test('현장의 시각 기준으로 읽는다 — UTC 로 조용히 가정하지 않는다', () => {
+  const events = [...doneAtHour('t1', 20)] // 절대 20시
+  const utc = foldKpi(events, DAY, { groupBy: 'shift', shifts: SHIFTS_3 })
+  const local = foldKpi(events, DAY, { groupBy: 'shift', shifts: SHIFTS_3, utcOffsetMinutes: -420 })
+  assert.equal(utc.groups?.items[0].key, 'B', 'UTC 20시는 B 교대')
+  assert.equal(local.groups?.items[0].key, 'A', 'Rosarito(UTC−7) 기준으로는 13시 — A 교대다')
+})
+
+test('교대를 선언하지 않은 현장은 unknown — 없는 구분을 지어내지 않는다', () => {
+  const r = foldKpi([...doneAtHour('t1', 7)], DAY, { groupBy: 'shift' })
+  assert.deepEqual((r.groups?.items ?? []).map(g => g.key), ['unknown'])
+})
+
+test('교대 정의를 고치면 과거가 다시 세어진다 — 저널에 찍어 뒀다면 굳었을 것', () => {
+  const events = [...doneAtHour('t1', 7)]
+  const twoShift = [
+    { id: 'DAY', fromTime: '07:00', toTime: '19:00' },
+    { id: 'NIGHT', fromTime: '19:00', toTime: '07:00', toDayOffset: 1 as const }
+  ]
+  assert.equal(foldKpi(events, DAY, { groupBy: 'shift', shifts: SHIFTS_3 }).groups?.items[0].key, 'A')
+  assert.equal(
+    foldKpi(events, DAY, { groupBy: 'shift', shifts: twoShift }).groups?.items[0].key,
+    'DAY',
+    '같은 저널, 다른 교대 정의 → 다시 센다'
+  )
+})
+
+/* ── 목표 대비 판정 ───────────────────────────────────────────────────────────
+ *
+ * 화면과 AI 는 "처리량 345건" 을 정확히 말하지만 **그것이 좋은지 나쁜지는 말할 수 없었다.** 근거가 앞
+ * 구간 비교뿐이라 "어제보다 나아졌다" 가 한계이고, 어제도 나빴으면 쓸모가 없다.
+ *
+ * 판정은 **사실 계산과 섞지 않는다** — 폴드는 목표를 모르고, 판정은 순수 함수로 따로 있다.
+ */
+const kpiOf = (events: KpiEvent[]) => foldKpi(events, DAY)
+
+test('방향은 지표의 성질이다 — 사용자가 반대로 적을 수 없다', () => {
+  const kpi = kpiOf([...doneAtHour('t1', 7), ...doneAtHour('t2', 8)])
+  const [more] = judgeTargets(kpi, [{ metric: 'throughput.tasks', target: 2 }])
+  assert.equal(more.direction, 'higher')
+  assert.equal(more.met, true, '처리량은 목표 이상이면 만족')
+
+  const [faster] = judgeTargets(kpi, [{ metric: 'workTime.p50Ms', target: 60_000 }])
+  assert.equal(faster.direction, 'lower', '시간은 낮을수록 좋다 — 입력이 아니라 지표가 안다')
+  assert.equal(faster.met, true, '실제 30초 ≤ 목표 60초')
+})
+
+test('미달을 미달이라 말한다', () => {
+  const kpi = kpiOf([...doneAtHour('t1', 7)])
+  const [v] = judgeTargets(kpi, [{ metric: 'throughput.tasks', target: 5 }])
+  assert.equal(v.met, false)
+  assert.equal(v.actual, 1)
+  assert.equal(v.ratio, 0.2, '비율은 항상 "1 이상이면 좋다" 로 정규화된다')
+})
+
+test('비율은 방향이 달라도 같은 뜻이다 — 한 화면에서 비교할 수 있게', () => {
+  const kpi = kpiOf([...doneAtHour('t1', 7)])
+  const [slow] = judgeTargets(kpi, [{ metric: 'workTime.p50Ms', target: 15_000 }]) // 실제 30초, 목표 15초
+  assert.equal(slow.met, false)
+  assert.equal(slow.ratio, 0.5, '두 배 느리면 0.5 — 처리량이 절반일 때와 같은 숫자')
+})
+
+test('목표가 없으면 판정하지 않는다', () => {
+  assert.deepEqual(judgeTargets(kpiOf([...doneAtHour('t1', 7)]), []), [])
+  assert.deepEqual(judgeTargets(kpiOf([...doneAtHour('t1', 7)]), undefined), [])
+})
+
+test('값이 없는 지표는 판정하지 않는다 — 0 으로 놓으면 반대로 거짓말한다', () => {
+  const empty = foldKpi([], DAY)
+  /* 이 테스트가 실제로 결함을 잡았다: 분위수는 표본이 없으면 p50Ms: 0 으로 나온다. 그것을 값으로 읽으면
+     시간 지표는 "낮을수록 좋다" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 —
+     미달을 놓치는 것보다 나쁘다(고칠 곳이 있는데 잘하고 있다고 말한다). */
+  assert.deepEqual(judgeTargets(empty, [{ metric: 'workTime.p50Ms', target: 15_000 }]), [])
+  assert.deepEqual(judgeTargets(empty, [{ metric: 'throughput.tasks', target: 10 }]), [], '기록 없음 ≠ 처리량 0')
+})
+
+test('모르는 지표 이름은 짐작해 매핑하지 않는다', () => {
+  assert.deepEqual(judgeTargets(kpiOf([...doneAtHour('t1', 7)]), [{ metric: 'cycleTime.p50' as never, target: 1 }]), [])
+})
+
+/* ── 목표의 범위 (공간 vs 인스턴스) ──────────────────────────────────────────
+ *
+ * 이 규칙은 원래 DB 접근 뒤에 숨어 있어 **화면을 눌러 봐야만** 확인할 수 있었다. 로그인 뒤 화면을
+ * 자동으로 검증할 방법이 없는 프로젝트라 그런 규칙은 조용히 미검증으로 쌓인다 — 그래서 밖으로 뺐다.
+ */
+const row = (metric: string, target: number, scope: { spaceId?: string; instanceId?: string }) => ({
+  metric,
+  target,
+  spaceId: scope.spaceId ?? null,
+  instanceId: scope.instanceId ?? null
+})
+
+test('공간 목표가 그 공간의 모든 트윈에 걸린다', () => {
+  const got = mergeTargets([row('throughput.tasks', 100, { spaceId: 'site-a' })], { spaceId: 'site-a', instanceIds: ['t1', 't2'] })
+  assert.deepEqual(got, [{ metric: 'throughput.tasks', target: 100 }])
+})
+
+test('인스턴스 목표가 공간 목표를 덮는다 — 예외를 표현할 수 있어야 한다', () => {
+  const got = mergeTargets(
+    [row('throughput.tasks', 100, { spaceId: 'site-a' }), row('throughput.tasks', 40, { instanceId: 't2' })],
+    { spaceId: 'site-a', instanceIds: ['t2'] }
+  )
+  assert.deepEqual(got, [{ metric: 'throughput.tasks', target: 40 }], '"이 라인만 다르다" 를 말할 수 있어야 한다')
+})
+
+test('다른 공간·다른 인스턴스의 목표는 새어 들어오지 않는다', () => {
+  const got = mergeTargets(
+    [row('throughput.tasks', 999, { spaceId: 'site-b' }), row('workTime.p50Ms', 999, { instanceId: 'other' })],
+    { spaceId: 'site-a', instanceIds: ['t1'] }
+  )
+  assert.deepEqual(got, [])
+})
+
+test('모르는 지표 이름·숫자 아닌 값은 목표로 세지 않는다', () => {
+  const got = mergeTargets(
+    [row('cycleTime.p50', 10, { spaceId: 'site-a' }), row('throughput.tasks', Number.NaN, { spaceId: 'site-a' })],
+    { spaceId: 'site-a', instanceIds: [] }
+  )
+  assert.deepEqual(got, [], '평가할 수 없는 목표는 "목표 없음" 으로 읽혀 갭을 감춘다 — 아예 세지 않는다')
+})
+
+test('공간을 안 고르고 트윈 하나만 볼 때도 그 인스턴스 목표는 걸린다', () => {
+  const got = mergeTargets([row('waitTime.p50Ms', 5000, { instanceId: 't1' })], { instanceIds: ['t1'] })
+  assert.deepEqual(got, [{ metric: 'waitTime.p50Ms', target: 5000 }])
+})
+
+/* ── 축별 목표 ───────────────────────────────────────────────────────────────
+ *
+ * 구역·교대마다 목표가 다를 수 있다("이 라인만 40건"). 그런데 축 목표는 **전체 목표를 덮지 않는다** —
+ * 다른 질문이기 때문이다: "현장 전체 100건" 과 "용접 구역 30건" 은 동시에 참일 수 있다. 덮게 만들면
+ * 축 하나에 목표를 거는 순간 전체 판정이 사라져 사용자가 "목표를 지웠나?" 를 묻게 된다.
+ */
+const arow = (metric: string, target: number, extra: Record<string, unknown> = {}) => ({
+  metric,
+  target,
+  spaceId: 'site-a',
+  instanceId: null,
+  axis: null,
+  axisKey: null,
+  ...extra
+})
+
+test('축 목표와 전체 목표가 함께 산다 — 덮지 않는다', () => {
+  const got = scopedTargets(
+    [arow('throughput.tasks', 100), arow('throughput.tasks', 30, { axis: 'area', axisKey: 'weld' })],
+    { spaceId: 'site-a', instanceIds: [], axis: 'area' }
+  )
+  assert.deepEqual(got.overall, [{ metric: 'throughput.tasks', target: 100 }], '전체 목표는 그대로 있다')
+  assert.deepEqual(got.byAxisKey.weld, [{ metric: 'throughput.tasks', target: 30 }])
+})
+
+test('지금 보는 축의 목표만 온다 — 다른 축의 목표가 섞이지 않는다', () => {
+  const got = scopedTargets(
+    [arow('throughput.tasks', 30, { axis: 'area', axisKey: 'weld' }), arow('throughput.tasks', 50, { axis: 'shift', axisKey: 'A' })],
+    { spaceId: 'site-a', instanceIds: [], axis: 'shift' }
+  )
+  assert.deepEqual(Object.keys(got.byAxisKey), ['A'])
+})
+
+test('축을 안 보고 있으면 축 목표는 오지 않는다 — 전체만', () => {
+  const got = scopedTargets([arow('throughput.tasks', 30, { axis: 'area', axisKey: 'weld' })], {
+    spaceId: 'site-a',
+    instanceIds: []
+  })
+  assert.deepEqual(got.byAxisKey, {})
+  assert.deepEqual(got.overall, [])
+})
+
+test('축 항목별로 판정한다 — 값이 없는 지표는 판정하지 않는다', () => {
+  const group = {
+    key: 'weld',
+    tasks: 12,
+    leadTime: { count: 12, p50Ms: 90_000 },
+    workTime: { count: 12, p50Ms: 30_000 },
+    waitTime: { count: 0, p50Ms: 0 }
+  }
+  const v = judgeGroupTargets(group, [
+    { metric: 'throughput.tasks', target: 10 },
+    { metric: 'workTime.p50Ms', target: 20_000 },
+    { metric: 'waitTime.p50Ms', target: 5_000 },
+    { metric: 'utilization.ratio', target: 0.8 }
+  ])
+  assert.deepEqual(
+    v.map(x => [x.metric, x.met]),
+    [
+      ['throughput.tasks', true],
+      ['workTime.p50Ms', false]
+    ],
+    '대기시간은 표본이 없어 판정 안 함 · 자원 점유는 축 단위로 뜻이 없어 판정 안 함'
+  )
+})

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')
+})