@things-factory/headless-twin 10.0.6 → 10.0.7

package/test/capability-mapping.test.ts

@@ -63,14 +63,14 @@ test('능력 소싱 구조: 4 자원/위치 능력은 카탈로그 타입에서,
 
 test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload 에 실림 (커널→보드 도달)', () => {
   // storable 노드 → occupancy/capacity (+ operable status)
-  const nodeD: any = buildEntityDeltas({ nodes: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] })[0].data
+  const nodeD: any = buildEntityDeltas({ locations: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] })[0].data
   for (const f of stateFieldsOf(['storable'])) assert.ok(f in nodeD, `storable payload.${f}`)
   assert.ok('status' in nodeD, 'operable(노드 status) payload')
 
   // mobile+operable 무버 → location/motion/status
-  const moverD: any = buildEntityDeltas({ movers: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }).find(x => x.tag === 'm')!.data
-  for (const f of stateFieldsOf(['mobile'])) assert.ok(f in moverD, `mobile payload.${f}`)
-  for (const f of stateFieldsOf(['operable'])) assert.ok(f in moverD, `operable payload.${f}`)
+  const equipmentD: any = buildEntityDeltas({ equipment: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }).find(x => x.tag === 'm')!.data
+  for (const f of stateFieldsOf(['mobile'])) assert.ok(f in equipmentD, `mobile payload.${f}`)
+  for (const f of stateFieldsOf(['operable'])) assert.ok(f in equipmentD, `operable payload.${f}`)
 
   // trackable 오더 → progress/held (lifecycle 은 payload 에서 'status' 로 표면화 — 이름-매핑 시임)
   const orderD: any = buildEntityDeltas({ orders: [{ id: 'o', status: 'picking', progress: 0.5, held: false }] }).find(x => x.tag === 'o')!.data
@@ -81,7 +81,7 @@ test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload
 test('시임 문서화 · processable output(양품/불량)은 payload oee.good/scrap 으로 표면화', () => {
   // 계약 stateField = 'output' 이나, 라이브 payload 는 이를 oee(정수%+good/scrap)로 집약해 표면화.
   const d: any = buildEntityDeltas({
-    movers: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, scrapCount: 1 } }]
+    equipment: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, scrapCount: 1 } }]
   }).find(x => x.tag === 'c')!.data
   assert.ok(d.oee, 'processable → payload.oee 존재')
   assert.equal(d.oee.good, 10, 'output.good = oee.good')

package/test/duration-estimators.test.ts

@@ -0,0 +1,144 @@
+/*
+ * 소요시간 추정기 — **상수를 데이터로 바꾸는 두 층(실측 · 거리×속도).**
+ *
+ * 커널 `durationOf` 의 우선순위는 추정기 > 명세 > 상수다. 그 추정기 자리에 호스트가 넣는 두 가지를
+ * 여기서 고정한다. 핵심 규율은 하나다 — **모르면 답하지 않는다**(undefined → 커널이 명세·상수로).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { EQUIPMENT_PROPERTY, buildTravelEstimator, chainEstimators } from '../server/engine/travel-estimator.ts'
+import { DEFAULT_MIN_SAMPLES, buildMeasuredEstimator } from '../server/engine/measured-estimator.ts'
+
+const layout = { dock: { x: 0, y: 0 }, rack: { x: 30, y: 40 } } // 거리 50m
+const equipment = (uom?: string, value = '2') => [
+  { id: 'fk-1', kind: 'forklift', properties: [{ id: EQUIPMENT_PROPERTY.speed, value, ...(uom ? { uom } : {}) }] }
+]
+
+/* ── 거리 × 속도 ────────────────────────────────────────────────────────── */
+
+test('거리와 속도가 있으면 이동시간을 계산한다 — 상수 30초가 아니라 50m/2(m/s)=25초', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.deepEqual(reasons, [])
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000)
+})
+
+test('단위 코드를 표준대로 환산한다 — KMH 는 m/s 가 아니다', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('KMH', '7.2'), unit: 'm' })
+  // 7.2 km/h = 2 m/s → 50m = 25초
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000)
+})
+
+test('단위 없는 속도는 m/s 라고 가정하지 않는다 — 3 이 초속 3m 인지 시속 3km 인지 뜻이 다르다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment(undefined), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('unit of measure')))
+})
+
+test('모르는 단위 코드는 받지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('WAT'), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('unknown speed unit')))
+})
+
+test('좌표가 없으면 만들지 않고 이유를 남긴다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout: {}, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('no location coordinates')))
+})
+
+test('속도를 아무도 선언하지 않으면 거리만으로 시간을 만들지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: [{ id: 'fk-1', kind: 'forklift' }], unit: 'm' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('speed')))
+})
+
+test('좌표 단위가 미터가 아니면 환산을 추측하지 않는다', () => {
+  const { estimator, reasons } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'ft' })
+  assert.equal(estimator, undefined)
+  assert.ok(reasons.some(r => r.includes('not metres')))
+})
+
+test('같은 자리의 작업(처리·체류)은 다루지 않는다 — 거리 0 을 0 초로 만들면 공정 시간이 사라진다', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator!.estimate({ kind: 'cut', fromNode: 'rack', toNode: 'rack', resourceKind: 'forklift' }), undefined)
+})
+
+test('좌표 모르는 노드·속도 모르는 자원종류는 넘긴다(부분 적용)', () => {
+  const { estimator } = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  assert.equal(estimator!.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack-99', resourceKind: 'forklift' }), undefined)
+  assert.equal(estimator!.estimate({ kind: 'spot', fromNode: 'dock', toNode: 'rack', resourceKind: 'hostler' }), undefined)
+  assert.equal(estimator!.estimate({ kind: 'spot', fromNode: 'dock', toNode: 'rack' }), undefined, '자원 종류 미지')
+})
+
+/* ── 실측(이력) ─────────────────────────────────────────────────────────── */
+
+test('작업 종류별 작업시간 p50 을 소요로 배운다 — 리드타임(대기 포함)이 아니라 작업시간', () => {
+  const r = buildMeasuredEstimator([
+    { key: 'putaway', workTime: { count: 40, p50Ms: 47_000 } },
+    { key: 'pick', workTime: { count: 12, p50Ms: 22_500 } }
+  ])
+  assert.deepEqual(r.learned, { putaway: 47_000, pick: 22_500 })
+  assert.deepEqual(r.estimator!.estimate({ kind: 'putaway', fromNode: 'a', toNode: 'b' }), { meanMs: 47_000 })
+  assert.equal(r.estimator!.estimate({ kind: 'unseen', fromNode: 'a', toNode: 'b' }), undefined, '못 배운 종류는 넘긴다')
+})
+
+/* ── 관측된 퍼짐 ────────────────────────────────────────────────────────── */
+
+test('두 꼬리가 있으면 퍼짐까지 배운다 — 평균만 배우면 줄이 생기지 않는다', () => {
+  const r = buildMeasuredEstimator([{ key: 'putaway', workTime: { count: 40, p10Ms: 30_000, p50Ms: 47_000, p90Ms: 80_000 } }])
+  assert.deepEqual(r.spreads, { putaway: { minMs: 30_000, maxMs: 80_000 } })
+  assert.deepEqual(r.estimator!.estimate({ kind: 'putaway', fromNode: 'a', toNode: 'b' }), {
+    meanMs: 47_000,
+    spread: { distribution: 'triangular', minMs: 30_000, maxMs: 80_000, modeMs: 47_000 }
+  })
+})
+
+test('한쪽 꼬리만 있으면 퍼짐을 만들지 않는다 — 아래쪽을 위쪽에서 베끼는 것은 발명이다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 40, p50Ms: 20_000, p90Ms: 40_000 } }])
+  assert.deepEqual(r.spreads, {})
+  assert.deepEqual(r.estimator!.estimate({ kind: 'pick', fromNode: 'a', toNode: 'b' }), { meanMs: 20_000 })
+})
+
+test('구간이 성립하지 않으면 퍼짐 없이 평균만 — 없는 흔들림을 만들지 않는다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 40, p10Ms: 50_000, p50Ms: 20_000, p90Ms: 20_000 } }])
+  assert.deepEqual(r.spreads, {}, 'p10 >= p90 이면 구간이 아니다')
+})
+
+test('표본이 적으면 배우지 않고, 무엇을 버렸는지 밝힌다 — 두 건의 p50 은 현장 값이 아니다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 2, p50Ms: 9_000 } }])
+  assert.equal(r.estimator, undefined)
+  assert.deepEqual(r.skipped, [{ kind: 'pick', count: 2 }])
+  assert.equal(r.minSamples, DEFAULT_MIN_SAMPLES)
+})
+
+test("'unknown' 축은 배우지 않는다 — 종류 모르는 기록을 특정 종류의 근거로 쓰지 않는다", () => {
+  const r = buildMeasuredEstimator([{ key: 'unknown', workTime: { count: 99, p50Ms: 30_000 } }])
+  assert.deepEqual(r.learned, {})
+  assert.equal(r.estimator, undefined)
+})
+
+test('p50 이 0 이면 쓰지 않는다 — 0 초 작업은 측정 실패다', () => {
+  const r = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 50, p50Ms: 0 } }])
+  assert.deepEqual(r.learned, {})
+})
+
+test('그룹이 없으면 빈 결과 — 던지지 않는다', () => {
+  assert.equal(buildMeasuredEstimator(undefined).estimator, undefined)
+  assert.equal(buildMeasuredEstimator([]).estimator, undefined)
+})
+
+/* ── 사슬 — 실측이 계산을 이긴다 ────────────────────────────────────────── */
+
+test('실측이 먼저, 없으면 거리 계산 — 강한 근거가 앞이다', () => {
+  const measured = buildMeasuredEstimator([{ key: 'pick', workTime: { count: 30, p50Ms: 11_000 } }])
+  const travel = buildTravelEstimator({ layout, equipment: equipment('MTS'), unit: 'm' })
+  const chained = chainEstimators([measured.estimator, travel.estimator])!
+  assert.deepEqual(chained.estimate({ kind: 'pick', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), { meanMs: 11_000 }, '실측 우선')
+  assert.equal(chained.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'rack', resourceKind: 'forklift' }), 25_000, '실측 없으면 거리')
+  assert.equal(chained.estimate({ kind: 'putaway', fromNode: 'dock', toNode: 'dock', resourceKind: 'forklift' }), undefined, '둘 다 모르면 넘긴다')
+})
+
+test('빈 사슬은 undefined — 주입하지 않는다(상수로 굴러가는 것이 정직하다)', () => {
+  assert.equal(chainEstimators([undefined, undefined]), undefined)
+})

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`)
   }
 })