@things-factory/headless-twin 10.0.5 → 10.0.7

package/test/entity-delta.test.ts

@@ -1,51 +1,182 @@
 /*
  * 호스트 방출 매핑(buildEntityDeltas) 단위 검증 — 씬 컴포넌트가 소비하는 data(tag) payload 계약.
- * held/oee(정수 퍼센트)/오더 집약 등 최근 추가분이 정확히 실리는지(회귀 방지).
+ *
+ * 지키는 것(2026-08-01 재편):
+ *  ① **레퍼런스가 아는 것은 전부 나간다** — 필드를 손으로 골라 담지 않는다. 화이트리스트였을 때
+ *     노드 parentId·작업 전량·물품 전량이 조용히 누락됐다. 계약에 속성이 생기면 자동으로 도달해야 한다.
+ *  ② **표식은 도메인 낱말을 훔치지 않는다** — 엔티티 종류 표식은 `entity`, `kind` 는 도메인 것
+ *     (무버 cutter · 작업 putaway · 오더 workorder).
+ *  ③ **조용히 자르지 않는다** — 물품 집약이 상한에 걸리면 total·truncated 로 밝힌다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { buildEntityDeltas, ORDERS_TAG } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, ITEMS_TAG, ORDERS_TAG, PERSONS_TAG, TASKS_TAG } from '../server/engine/entity-delta.ts'
 
 const byTag = (arr: any[], tag: string) => arr.find(x => x.tag === tag)
 
-test('node delta: occupancy/capacity/status/type', () => {
-  const d = buildEntityDeltas({ nodes: [{ id: 'bin-1', occupancy: 3, capacity: 10, status: 'idle', type: 'storage' }] })
-  assert.deepEqual(byTag(d, 'bin-1').data, { kind: 'node', occupancy: 3, capacity: 10, status: 'idle', type: 'storage' })
+test('노드: 계약의 속성이 전부 나간다 — parentId(소속 구역)를 포함해', () => {
+  const d = buildEntityDeltas({
+    locations: [{ id: 'bin-1', occupancy: 3, capacity: 10, status: 'idle', type: 'storage', parentId: 'zone-a' }]
+  })
+  assert.deepEqual(byTag(d, 'bin-1').data, {
+    entity: 'location',
+    occupancy: 3,
+    capacity: 10,
+    status: 'idle',
+    type: 'storage',
+    parentId: 'zone-a'
+  })
 })
 
-test('mover delta: held(계획정지) + status + OEE 정수 퍼센트 정형화', () => {
+test('표식은 entity, kind 는 도메인 것 — 무버 종류가 표식에 덮이지 않는다', () => {
   const d = buildEntityDeltas({
-    movers: [{ id: 'cutter-1', kind: 'cutter', location: 'cut', status: 'down', held: true, oee: { overall: 0.8234, availability: 0.9, performance: 0.95, quality: 0.96, goodCount: 12, scrapCount: 3, idleMs: 99999 } }]
+    equipment: [{ id: 'cutter-1', kind: 'cutter', location: 'cut', status: 'down', held: true }]
   })
   const m = byTag(d, 'cutter-1').data
-  assert.equal(m.kind, 'mover')
+  assert.equal(m.entity, 'equipment', '표식')
+  assert.equal(m.kind, 'cutter', '도메인 속성 — 예전엔 표식에 덮여 사라졌다')
   assert.equal(m.status, 'down')
   assert.equal(m.held, true)
-  // 정수 퍼센트 + 카운트만(원시 누적 ms 는 제외 — churn 억제)
-  assert.deepEqual(m.oee, { overall: 82, availability: 90, performance: 95, quality: 96, good: 12, scrap: 3 })
 })
 
-test('mover delta: oee 미측정이면 undefined', () => {
-  const d = buildEntityDeltas({ movers: [{ id: 'fk-1', kind: 'forklift', status: 'idle' }] })
+test('무버: OEE 는 정수 퍼센트로 정형화하고 원시 누적은 빼낸다(churn 억제)', () => {
+  const d = buildEntityDeltas({
+    equipment: [
+      {
+        id: 'cutter-1',
+        kind: 'cutter',
+        status: 'down',
+        oee: { overall: 0.8234, availability: 0.9, performance: 0.95, quality: 0.96, goodCount: 12, scrapCount: 3, idleMs: 99999 }
+      }
+    ]
+  })
+  assert.deepEqual(byTag(d, 'cutter-1').data.oee, {
+    overall: 82,
+    availability: 90,
+    performance: 95,
+    quality: 96,
+    good: 12,
+    scrap: 3
+  })
+})
+
+test('무버: oee 미측정이면 실리지 않는다', () => {
+  const d = buildEntityDeltas({ equipment: [{ id: 'fk-1', kind: 'forklift', status: 'idle' }] })
   assert.equal(byTag(d, 'fk-1').data.oee, undefined)
 })
 
-test('order delta + __orders__ 집약(전체 오더)', () => {
+test('작업: 개별 + 집약으로 나간다 — 예전엔 아예 방출되지 않았다', () => {
+  const d = buildEntityDeltas({
+    tasks: [
+      { id: 't1', kind: 'putaway', status: 'in-progress', fromNode: 'dock', toNode: 'rack-1', resourceRef: 'fk-1', orderId: 'o1', progress: 0.4 },
+      { id: 't2', kind: 'pick', status: 'created' }
+    ]
+  })
+  assert.deepEqual(byTag(d, 't1').data, {
+    entity: 'task',
+    kind: 'putaway',
+    status: 'in-progress',
+    fromNode: 'dock',
+    toNode: 'rack-1',
+    resourceRef: 'fk-1',
+    orderId: 'o1',
+    progress: 0.4
+  })
+  const agg = byTag(d, TASKS_TAG).data
+  assert.equal(agg.entity, 'tasks')
+  assert.equal(agg.tasks.length, 2)
+  assert.equal(agg.tasks[0].id, 't1', '집약에는 식별자가 있다')
+  assert.equal(agg.tasks[0].resourceRef, 'fk-1', '집약도 속성을 다 담는다')
+})
+
+test('물품: 개별(태그=epc) + 집약으로 나간다 — 수량·소속 팔레트·만료까지', () => {
+  const d = buildEntityDeltas({
+    items: [{ epc: 'urn:epc:id:sgtin:1.1.1', gtin: 'g1', location: 'rack-1', disposition: 'sellable', parent: 'sscc-1', qty: 40, expiry: 1234 }]
+  })
+  assert.deepEqual(byTag(d, 'urn:epc:id:sgtin:1.1.1').data, {
+    entity: 'item',
+    gtin: 'g1',
+    location: 'rack-1',
+    disposition: 'sellable',
+    parent: 'sscc-1',
+    qty: 40,
+    expiry: 1234
+  })
+  const agg = byTag(d, ITEMS_TAG).data
+  assert.equal(agg.entity, 'items')
+  assert.equal(agg.items[0].epc, 'urn:epc:id:sgtin:1.1.1')
+  assert.equal(agg.items[0].qty, 40)
+  assert.equal(agg.total, 1)
+  assert.equal(agg.truncated, undefined, '상한 안이면 truncated 없음')
+})
+
+test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 조용한 절단 금지', () => {
+  const items = Array.from({ length: ITEMS_AGGREGATE_LIMIT + 7 }, (_, i) => ({ epc: `e${i}`, location: 'rack-1' }))
+  const d = buildEntityDeltas({ items })
+  const agg = byTag(d, ITEMS_TAG).data
+  assert.equal(agg.items.length, ITEMS_AGGREGATE_LIMIT)
+  assert.equal(agg.total, ITEMS_AGGREGATE_LIMIT + 7)
+  assert.equal(agg.truncated, 7)
+  /* 개별 물품은 상한과 무관하게 전부 태그별로 나간다(시그니처 dedup 이 변한 것만 재방송한다). */
+  assert.equal(d.filter(x => x.data?.entity === 'item').length, ITEMS_AGGREGATE_LIMIT + 7)
+})
+
+test('오더: 개별 + 집약, 도메인 kind 유지', () => {
   const d = buildEntityDeltas({
     orders: [
       { id: 'o1', kind: 'workorder', status: 'picking', progress: 0.5, held: false },
-      { id: 'o2', kind: 'workorder', status: 'created', progress: 0, held: true }
+      { id: 'o2', kind: 'outbound', status: 'created', progress: 0, held: true }
     ]
   })
-  assert.ok(byTag(d, 'o1'), '개별 오더도 방출')
+  assert.equal(byTag(d, 'o1').data.kind, 'workorder')
   const agg = byTag(d, ORDERS_TAG).data
-  assert.equal(agg.kind, 'orders')
+  assert.equal(agg.entity, 'orders')
   assert.equal(agg.orders.length, 2)
   assert.equal(agg.orders[1].held, true, '집약에 held 반영')
 })
 
-test('빈 상태 — 집약 태그는 항상 방출(빈 배열)', () => {
-  const agg = byTag(buildEntityDeltas({}), ORDERS_TAG).data
-  assert.deepEqual(agg.orders, [])
+test('계약에 새 속성이 생기면 손대지 않아도 도달한다 — 화이트리스트 재발 방지', () => {
+  /* 이 테스트가 실패하면 누군가 필드를 손으로 골라 담기 시작한 것이다. */
+  const d = buildEntityDeltas({ locations: [{ id: 'n1', occupancy: 0, temperatureC: -18, hazmatClass: '3' }] })
+  const n = byTag(d, 'n1').data
+  assert.equal(n.temperatureC, -18, '알지 못하는 새 속성도 통과해야 한다')
+  assert.equal(n.hazmatClass, '3')
+})
+
+test('undefined 값은 싣지 않는다 — 키 유무가 시그니처를 흔들지 않게', () => {
+  const d = buildEntityDeltas({ equipment: [{ id: 'fk-1', kind: 'forklift', location: undefined, status: 'idle' }] })
+  assert.equal('location' in byTag(d, 'fk-1').data, false)
+})
+
+test('빈 상태 — 집약 태그 셋은 항상 방출(빈 배열)', () => {
+  const d = buildEntityDeltas({})
+  assert.deepEqual(byTag(d, ORDERS_TAG).data.orders, [])
+  assert.deepEqual(byTag(d, TASKS_TAG).data.tasks, [])
+  assert.deepEqual(byTag(d, ITEMS_TAG).data.items, [])
+  assert.equal(byTag(d, ITEMS_TAG).data.total, 0)
+})
+
+/* ── 사람 ────────────────────────────────────────────────────────────────
+ *
+ * 인원은 설비와 별개 엔티티다(고장·설비효율이 아니라 등급·교대로 산다). 같은 통과 규칙을 쓰되
+ * 자기 태그로 나가고, 집약 태그도 따로 둔다 — 인원을 한눈에 보는 소비처가 있기 때문이다.
+ */
+test('사람이 개별 태그로 나간다 — 등급·교대가 그대로', () => {
+  const deltas = buildEntityDeltas({
+    persons: [{ id: 'w1', personnelClass: 'welder-op', status: 'busy', taskId: 't1', offShift: undefined }]
+  })
+  const one = deltas.find(d => d.tag === 'w1')!
+  assert.equal(one.data.entity, 'person')
+  assert.equal(one.data.personnelClass, 'welder-op')
+  assert.equal(one.data.status, 'busy')
+  assert.equal(one.data.taskId, 't1')
+})
+
+test('사람 집약 태그가 항상 나간다 — 선언하지 않은 트윈은 빈 배열(없음과 모름을 구별)', () => {
+  const withNone = buildEntityDeltas({})
+  const agg = withNone.find(d => d.tag === PERSONS_TAG)!
+  assert.deepEqual(agg.data.persons, [])
+  const withTwo = buildEntityDeltas({ persons: [{ id: 'w1' }, { id: 'w2' }] })
+  assert.equal(withTwo.find(d => d.tag === PERSONS_TAG)!.data.persons.length, 2)
 })

package/test/ingest-bench.test.ts

@@ -12,11 +12,11 @@ import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
 
 const T0 = '2026-07-19T00:00:00.000Z'
 const board = (nNodes: number) => ({
-  nodes: Array.from({ length: nNodes }, (_, i) => ({ id: `bin-${i}`, type: 'storage', capacity: 100000 })),
-  movers: []
+  locations: Array.from({ length: nNodes }, (_, i) => ({ id: `bin-${i}`, type: 'storage', capacity: 100000 })),
+  equipment: []
 })
-function envelope(epc: string, node: string): any {
-  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [epc], readPoint: node })
+function envelope(epc: string, location: string): any {
+  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [epc], readPoint: location })
   return { eventId: 'x', eventType: `epcis.${ev.type}`, eventTime: T0, tenantId: 't', data: ev }
 }
 
@@ -52,18 +52,18 @@ test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방
     const t0 = performance.now()
     for (let k = 0; k < iters; k++) buildEntityDeltas(snap)
     const per = (performance.now() - t0) / iters
-    console.log(`  [buildEntityDeltas] @ ${N.toLocaleString()} nodes: ${per.toFixed(3)}ms/call`)
+    console.log(`  [buildEntityDeltas] @ ${N.toLocaleString()} locations: ${per.toFixed(3)}ms/call`)
   }
 })
 
 test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규모', () => {
-  for (const [nodes, items] of [[200, 5000], [1000, 50000], [2000, 100000]]) {
-    const proj = new StateProjector(board(nodes))
-    for (let i = 0; i < items; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % nodes}`))
+  for (const [locations, items] of [[200, 5000], [1000, 50000], [2000, 100000]]) {
+    const proj = new StateProjector(board(locations))
+    for (let i = 0; i < items; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % locations}`))
     const iters = 100
     const t0 = performance.now()
     for (let k = 0; k < iters; k++) buildEntityDeltas(proj.snapshot())
     const per = (performance.now() - t0) / iters
-    console.log(`  [방송1회] ${nodes.toLocaleString()} nodes / ${items.toLocaleString()} items: ${per.toFixed(3)}ms → 최대 ${Math.round(1000 / per).toLocaleString()} 방송/s`)
+    console.log(`  [방송1회] ${locations.toLocaleString()} locations / ${items.toLocaleString()} items: ${per.toFixed(3)}ms → 최대 ${Math.round(1000 / per).toLocaleString()} 방송/s`)
   }
 })

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()
@@ -154,6 +155,28 @@ test('payload 가 envelope 없이 델타만 와도 읽는다 — 저장 형태
   assert.equal(r.workTime.avgMs, 20000)
 })
 
+test('완료가 재전송되면 한 건으로 센다 — 처리량·자원 점유가 부풀려지지 않게', () => {
+  /* 공정 타임라인과 KPI 가 같은 저널을 다르게 짝지어 다른 답을 냈다(타임라인 1건 / KPI 2건).
+   * 두 구현이 있었기 때문이고, 규칙은 하나여야 한다: **완료는 작업당 하나, 나중 것이 사실.** */
+  const r = foldKpi(
+    [
+      task('t1', 'created', 0),
+      task('t1', 'in-progress', 10, 'fk-1'),
+      task('t1', 'completed', 40, 'fk-1'),
+      task('t1', 'completed', 45, 'fk-1') // 재전송
+    ],
+    WINDOW
+  )
+  assert.equal(r.throughput.tasks, 1, '한 건이다')
+  assert.equal(r.workTime.count, 1)
+  assert.equal(r.workTime.avgMs, 35000, '나중 완료(45s) 기준')
+  assert.deepEqual(
+    r.utilization.map(u => [u.resourceId, u.busyMs]),
+    [['fk-1', 35000]],
+    '점유도 한 번만 더한다(예전엔 65초로 부풀려졌다)'
+  )
+})
+
 test('같은 전이가 두 번 와도 착수는 처음 것, 생성은 마지막 것 — 재시도에 흔들리지 않게', () => {
   const r = foldKpi(
     [
@@ -264,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} 축의 합`)
@@ -296,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'])
 })
 
@@ -305,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]], '두 노드가 한 구역으로 모인다')
 })
 
@@ -445,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]
+    ],
+    '대기시간은 표본이 없어 판정 안 함 · 자원 점유는 축 단위로 뜻이 없어 판정 안 함'
+  )
+})