@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/entity-delta.test.ts

@@ -11,14 +11,14 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, ITEMS_TAG, ORDERS_TAG, PERSONS_TAG, TASKS_TAG } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, itemsTag, ordersTag, personsTag, tasksTag, energyTag } from '../shared/entity-delta.ts'
 
 const byTag = (arr: any[], tag: string) => arr.find(x => x.tag === tag)
 
 test('노드: 계약의 속성이 전부 나간다 — parentId(소속 구역)를 포함해', () => {
   const d = buildEntityDeltas({
     locations: [{ id: 'bin-1', occupancy: 3, capacity: 10, status: 'idle', type: 'storage', parentId: 'zone-a' }]
-  })
+  }, 't1')
   assert.deepEqual(byTag(d, 'bin-1').data, {
     entity: 'location',
     occupancy: 3,
@@ -32,7 +32,7 @@ test('노드: 계약의 속성이 전부 나간다 — parentId(소속 구역)
 test('표식은 entity, kind 는 도메인 것 — 무버 종류가 표식에 덮이지 않는다', () => {
   const d = buildEntityDeltas({
     equipment: [{ id: 'cutter-1', kind: 'cutter', location: 'cut', status: 'down', held: true }]
-  })
+  }, 't1')
   const m = byTag(d, 'cutter-1').data
   assert.equal(m.entity, 'equipment', '표식')
   assert.equal(m.kind, 'cutter', '도메인 속성 — 예전엔 표식에 덮여 사라졌다')
@@ -50,7 +50,7 @@ test('무버: OEE 는 정수 퍼센트로 정형화하고 원시 누적은 빼
         oee: { overall: 0.8234, availability: 0.9, performance: 0.95, quality: 0.96, goodCount: 12, scrapCount: 3, idleMs: 99999 }
       }
     ]
-  })
+  }, 't1')
   assert.deepEqual(byTag(d, 'cutter-1').data.oee, {
     overall: 82,
     availability: 90,
@@ -62,7 +62,7 @@ test('무버: OEE 는 정수 퍼센트로 정형화하고 원시 누적은 빼
 })
 
 test('무버: oee 미측정이면 실리지 않는다', () => {
-  const d = buildEntityDeltas({ equipment: [{ id: 'fk-1', kind: 'forklift', status: 'idle' }] })
+  const d = buildEntityDeltas({ equipment: [{ id: 'fk-1', kind: 'forklift', status: 'idle' }] }, 't1')
   assert.equal(byTag(d, 'fk-1').data.oee, undefined)
 })
 
@@ -72,7 +72,7 @@ test('작업: 개별 + 집약으로 나간다 — 예전엔 아예 방출되지
       { 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' }
     ]
-  })
+  }, 't1')
   assert.deepEqual(byTag(d, 't1').data, {
     entity: 'task',
     kind: 'putaway',
@@ -83,7 +83,7 @@ test('작업: 개별 + 집약으로 나간다 — 예전엔 아예 방출되지
     orderId: 'o1',
     progress: 0.4
   })
-  const agg = byTag(d, TASKS_TAG).data
+  const agg = byTag(d, tasksTag('t1')).data
   assert.equal(agg.entity, 'tasks')
   assert.equal(agg.tasks.length, 2)
   assert.equal(agg.tasks[0].id, 't1', '집약에는 식별자가 있다')
@@ -93,7 +93,7 @@ test('작업: 개별 + 집약으로 나간다 — 예전엔 아예 방출되지
 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 }]
-  })
+  }, 't1')
   assert.deepEqual(byTag(d, 'urn:epc:id:sgtin:1.1.1').data, {
     entity: 'item',
     gtin: 'g1',
@@ -103,7 +103,7 @@ test('물품: 개별(태그=epc) + 집약으로 나간다 — 수량·소속 팔
     qty: 40,
     expiry: 1234
   })
-  const agg = byTag(d, ITEMS_TAG).data
+  const agg = byTag(d, itemsTag('t1')).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)
@@ -113,8 +113,8 @@ test('물품: 개별(태그=epc) + 집약으로 나간다 — 수량·소속 팔
 
 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
+  const d = buildEntityDeltas({ items }, 't1')
+  const agg = byTag(d, itemsTag('t1')).data
   assert.equal(agg.items.length, ITEMS_AGGREGATE_LIMIT)
   assert.equal(agg.total, ITEMS_AGGREGATE_LIMIT + 7)
   assert.equal(agg.truncated, 7)
@@ -128,9 +128,9 @@ test('오더: 개별 + 집약, 도메인 kind 유지', () => {
       { id: 'o1', kind: 'workorder', status: 'picking', progress: 0.5, held: false },
       { id: 'o2', kind: 'outbound', status: 'created', progress: 0, held: true }
     ]
-  })
+  }, 't1')
   assert.equal(byTag(d, 'o1').data.kind, 'workorder')
-  const agg = byTag(d, ORDERS_TAG).data
+  const agg = byTag(d, ordersTag('t1')).data
   assert.equal(agg.entity, 'orders')
   assert.equal(agg.orders.length, 2)
   assert.equal(agg.orders[1].held, true, '집약에 held 반영')
@@ -138,23 +138,23 @@ test('오더: 개별 + 집약, 도메인 kind 유지', () => {
 
 test('계약에 새 속성이 생기면 손대지 않아도 도달한다 — 화이트리스트 재발 방지', () => {
   /* 이 테스트가 실패하면 누군가 필드를 손으로 골라 담기 시작한 것이다. */
-  const d = buildEntityDeltas({ locations: [{ id: 'n1', occupancy: 0, temperatureC: -18, hazmatClass: '3' }] })
+  const d = buildEntityDeltas({ locations: [{ id: 'n1', occupancy: 0, temperatureC: -18, hazmatClass: '3' }] }, 't1')
   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' }] })
+  const d = buildEntityDeltas({ equipment: [{ id: 'fk-1', kind: 'forklift', location: undefined, status: 'idle' }] }, 't1')
   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)
+  const d = buildEntityDeltas({}, 't1')
+  assert.deepEqual(byTag(d, ordersTag('t1')).data.orders, [])
+  assert.deepEqual(byTag(d, tasksTag('t1')).data.tasks, [])
+  assert.deepEqual(byTag(d, itemsTag('t1')).data.items, [])
+  assert.equal(byTag(d, itemsTag('t1')).data.total, 0)
 })
 
 /* ── 사람 ────────────────────────────────────────────────────────────────
@@ -165,7 +165,7 @@ test('빈 상태 — 집약 태그 셋은 항상 방출(빈 배열)', () => {
 test('사람이 개별 태그로 나간다 — 등급·교대가 그대로', () => {
   const deltas = buildEntityDeltas({
     persons: [{ id: 'w1', personnelClass: 'welder-op', status: 'busy', taskId: 't1', offShift: undefined }]
-  })
+  }, 't1')
   const one = deltas.find(d => d.tag === 'w1')!
   assert.equal(one.data.entity, 'person')
   assert.equal(one.data.personnelClass, 'welder-op')
@@ -174,9 +174,179 @@ test('사람이 개별 태그로 나간다 — 등급·교대가 그대로', ()
 })
 
 test('사람 집약 태그가 항상 나간다 — 선언하지 않은 트윈은 빈 배열(없음과 모름을 구별)', () => {
-  const withNone = buildEntityDeltas({})
-  const agg = withNone.find(d => d.tag === PERSONS_TAG)!
+  const withNone = buildEntityDeltas({}, 't1')
+  const agg = withNone.find(d => d.tag === personsTag('t1'))!
   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)
+  const withTwo = buildEntityDeltas({ persons: [{ id: 'w1' }, { id: 'w2' }] }, 't1')
+  assert.equal(withTwo.find(d => d.tag === personsTag('t1'))!.data.persons.length, 2)
+})
+
+/*
+ * ── 에너지 (EMS 6단계) ──────────────────────────────────────────────────────
+ *
+ * 계측은 `state.energy` 에 산다 — 자원 축이 아니다. 이 매핑이 없으면 보드에 놓은 계량기가 값을
+ * 받지 못하고 **영원히 빈 모습**이 된다(컴포넌트는 있는데 데이터가 없는, 눈에 안 보이는 결함).
+ */
+test('계량 지점의 마지막 관측이 그 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [
+          { id: 'meter-incoming', kW: 1200.5, kWh: 98_000, powerFactor: 0.95, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 3 },
+          { id: 'meter-quiet', samplesInWindow: 0 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+  const m = deltas.find(d => d.tag === 'meter-incoming')!
+  assert.equal(m.data.entity, 'meter')
+  assert.equal(m.data.kW, 1200.5)
+  assert.equal(m.data.measuredAt, '2026-08-14T09:01:00.000Z', '시각을 함께 낸다 — 화면이 계측 끊김을 스스로 안다')
+
+  /* 값이 없는 지점: 키를 넣지 않는다(0 으로 만들면 「전기를 안 썼다」가 된다). */
+  const q = deltas.find(d => d.tag === 'meter-quiet')!
+  assert.equal('kW' in q.data, false)
+  assert.equal(q.data.samplesInWindow, 0, '받은 표본 수는 사실이다')
+})
+
+test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의 사실이 아니다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [],
+        contractKW: 4000,
+        open: { startMs: 1, endMs: 2, samples: 1, maxKW: 4200 },
+        peakSince: { kW: 4200, windowStartMs: 1 },
+        closed: Array.from({ length: 20 }, (_, i) => ({ startMs: i, endMs: i + 1, samples: 1, maxKW: 100 + i })),
+        closedTotal: 137
+      }
+    },
+    'ems-1'
+  )
+  const agg = deltas.find(d => d.tag === energyTag('ems-1'))!
+  assert.ok(agg, '집약 태그가 있어야 한다')
+  assert.equal(agg.data.contractKW, 4000)
+  assert.equal(agg.data.peakSince.kW, 4200)
+  /* 하루치를 매 방송에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
+  assert.equal(agg.data.recent.length, 8)
+  assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
+})
+
+test('에너지가 없는 트윈은 에너지 태그를 내지 않는다 — 없는 것을 만들지 않는다', () => {
+  const deltas = buildEntityDeltas({ locations: [], equipment: [] }, 'wms-1')
+  assert.equal(deltas.some(d => d.tag === energyTag('wms-1')), false)
+  assert.equal(deltas.some(d => d.data?.entity === 'meter'), false)
+})
+
+test('자리에도 에너지가 실린다 — 능력이 「잰다」고 말하는데 값이 없던 자리', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [
+        { id: 'incoming-1', type: 'incoming' },
+        { id: 'feeder-a', type: 'feeder' },
+        { id: 'feeder-b', type: 'feeder' }
+      ],
+      equipment: [
+        { id: 'm-main', kind: 'meter', homeLocation: 'incoming-1' },
+        { id: 'm-a1', kind: 'meter', homeLocation: 'feeder-a' },
+        { id: 'm-a2', kind: 'meter', homeLocation: 'feeder-a' }
+      ],
+      energy: {
+        points: [
+          { id: 'm-main', kW: 3800, kWh: 1000, atMs: Date.parse('2026-08-14T09:00:00.000Z'), samplesInWindow: 3 },
+          { id: 'm-a1', kW: 1000, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 2 },
+          { id: 'm-a2', kW: 600, atMs: Date.parse('2026-08-14T09:02:00.000Z'), samplesInWindow: 1 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+
+  const incoming = deltas.find(d => d.tag === 'incoming-1')!.data
+  assert.equal(incoming.entity, 'location', '자리 payload 를 덮지 않고 합친다')
+  assert.equal(incoming.kW, 3800)
+  assert.deepEqual(incoming.meters, ['m-main'], '어느 계량기에서 온 수인지 되짚을 수 있어야 한다')
+
+  /* 자리에 계량기가 둘이면 그 자리의 수는 둘의 합이고, 나이는 **가장 최근**이다. */
+  const a = deltas.find(d => d.tag === 'feeder-a')!.data
+  assert.equal(a.kW, 1600)
+  assert.equal(a.samplesInWindow, 3)
+  assert.equal(a.measuredAt, '2026-08-14T09:02:00.000Z')
+  assert.deepEqual(a.meters, ['m-a1', 'm-a2'])
+
+  /* 계량기가 없는 자리는 예전 그대로 — 에너지 키를 만들지 않는다(0 은 「안 썼다」가 된다). */
+  const b = deltas.find(d => d.tag === 'feeder-b')!.data
+  assert.equal('kW' in b, false)
+  assert.equal('meters' in b, false)
+})
+
+test('자리를 모르는 계량기는 자리에 실리지 않는다 — 설비 태그로만 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [],
+      energy: { points: [{ id: 'm-orphan', kW: 500, samplesInWindow: 1 }], closed: [], closedTotal: 0 }
+    },
+    'ems-1'
+  )
+  assert.equal('kW' in deltas.find(d => d.tag === 'incoming-1')!.data, false)
+  assert.equal(deltas.find(d => d.tag === 'm-orphan')!.data.kW, 500, '설비 태그로는 나간다')
+})
+
+/*
+ * ── 능력 넷의 값이 컴포넌트까지 간다 (2026-08-15) ───────────────────────────
+ * 보드에 놓인 컴포넌트는 `data(tag)` 로만 값을 받는다. 커널이 값을 들고 있어도 이 페이로드에 실리지
+ * 않으면 화면은 영원히 「—」다 — 실제로 그 부류를 두 번 겪었다(스냅샷 투영이 필드를 빠뜨렸고,
+ * 값의 시각을 버렸다).
+ *
+ * 그래서 **설비 태그의 payload** 를 직접 못 박는다: 값과 그 값의 나이가 함께 실려야 한다.
+ */
+test('발전·저장·감축·개폐 값과 그 나이가 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [
+        { id: 'pv-1', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle', generatedKW: 210, exportKW: 40, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'ess-1', kind: 'battery', homeLocation: 'incoming-1', status: 'idle', soc: 62, chargeKW: 0, dischargeKW: 85, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'load-1', kind: 'curtailable-load', homeLocation: 'incoming-1', status: 'busy', curtailable: true, minKW: 30, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'cb-1', kind: 'breaker', homeLocation: 'incoming-1', status: 'idle', position: 'closed', measuredAt: '2026-08-15T09:00:00.000Z' }
+      ]
+    },
+    'ems-1'
+  )
+  const by = Object.fromEntries(deltas.map(d => [d.tag, d.data as any]))
+
+  assert.equal(by['pv-1'].generatedKW, 210)
+  assert.equal(by['pv-1'].exportKW, 40)
+  assert.equal(by['ess-1'].soc, 62)
+  assert.equal(by['ess-1'].dischargeKW, 85)
+  assert.equal(by['load-1'].curtailable, true)
+  assert.equal(by['load-1'].minKW, 30)
+  assert.equal(by['cb-1'].position, 'closed')
+  /* 나이가 없으면 화면이 멈춘 값을 지금 값처럼 그린다 — 네 컴포넌트가 모두 이 키를 읽는다. */
+  for (const id of ['pv-1', 'ess-1', 'load-1', 'cb-1']) {
+    assert.equal(by[id].measuredAt, '2026-08-15T09:00:00.000Z', `${id}: 값의 나이가 함께 가야 한다`)
+  }
+})
+
+test('값이 없는 설비에는 그 키를 만들지 않는다 — 0 으로 그리면 「안 쓴다」가 된다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [{ id: 'pv-2', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle' }]
+    },
+    'ems-1'
+  )
+  const pv = deltas.find(d => d.tag === 'pv-2')!.data as any
+  assert.equal('generatedKW' in pv, false)
+  assert.equal('measuredAt' in pv, false)
 })

package/test/event-time-column.test.ts

@@ -0,0 +1,67 @@
+/*
+ * eventTime 이 **날짜 컬럼**이라는 사실을 지킨다.
+ *
+ * ── 왜 있나 (2026-08-08) ────────────────────────────────────────────────────
+ * 예전에는 문자열 컬럼이었고, "UTC ISO 만 들어오니 사전식 비교가 맞는다" 는 전제 위에서 정렬·범위
+ * 질의가 돌았다. 그 전제는 컬럼 어디에도 적혀 있지 않았다.
+ *
+ * 날짜 컬럼으로 바꾸면서 **조용한 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
+ * (`2026-08-07 11:00:00.000`)으로 저장하는데, 화면은 ISO 문자열(`…T11:00:00.000Z`)을 보낸다.
+ * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 조용히
+ * 비어 버리고, 사용자는 "그 시간에 아무 일도 없었다" 로 읽는다.
+ *
+ * 그래서 두 가지를 못 박는다: 저장 형식이 실제로 그렇다는 것과, 경계에서 날짜로 옮기면 걸린다는 것.
+ * 이 검사가 깨지면 typeorm/드라이버의 거동이 바뀐 것이므로 변환 지점을 다시 봐야 한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { DataSource, EntitySchema, Between } = req('typeorm')
+
+const Ev = new EntitySchema({
+  name: 'ev',
+  tableName: 'ev',
+  columns: {
+    id: { primary: true, type: 'int', generated: true },
+    eventTime: { type: 'datetime', nullable: true }
+  }
+})
+
+async function seeded() {
+  const ds = new DataSource({ type: 'sqlite', database: ':memory:', entities: [Ev], synchronize: true })
+  await ds.initialize()
+  const repo = ds.getRepository('ev')
+  await repo.save([
+    { eventTime: new Date('2026-08-07T11:00:00.000Z') },
+    { eventTime: new Date('2026-08-07T13:00:00.000Z') }
+  ])
+  return { ds, repo }
+}
+
+test('sqlite 는 datetime 을 공백 구분 형식으로 저장한다 — ISO 문자열과 사전식으로 어긋난다', async () => {
+  const { ds } = await seeded()
+  const raw = await ds.query('select eventTime from ev order by id')
+  assert.match(raw[0].eventTime, /^\d{4}-\d{2}-\d{2} /, '공백 구분이 아니면 이 검사의 전제가 바뀐 것이다')
+  assert.ok(!String(raw[0].eventTime).includes('T'), 'T 가 들어가면 ISO 와 같은 형식이므로 함정이 사라진 것이다')
+  await ds.destroy()
+})
+
+test('ISO 문자열을 그대로 넘기면 **조용히 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
+  const { ds, repo } = await seeded()
+  const rows = await repo.find({
+    where: { eventTime: Between('2026-08-07T10:00:00.000Z', '2026-08-07T12:00:00.000Z') }
+  })
+  assert.equal(rows.length, 0, '이 검사가 깨졌다면 드라이버가 문자열을 받아 주게 된 것 — 변환 지점을 재검토할 것')
+  await ds.destroy()
+})
+
+test('경계에서 날짜로 옮기면 제대로 걸린다 — 질의 전에 반드시 변환한다', async () => {
+  const { ds, repo } = await seeded()
+  const rows = await repo.find({
+    where: { eventTime: Between(new Date('2026-08-07T10:00:00.000Z'), new Date('2026-08-07T12:00:00.000Z')) }
+  })
+  assert.equal(rows.length, 1)
+  await ds.destroy()
+})

package/test/forecast-metrics.test.ts

@@ -0,0 +1,71 @@
+/*
+ * 예측 지표 — **스냅샷에서 무엇을 세는가.**
+ *
+ * 여기서 틀리면 예측 그래프가 조용히 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
+ * 「없음」과 「0」이 같은 그림이 되기 쉬워서, 그 경계를 명시로 잡아 둔다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { FORECAST_METRICS, metricsForKind } from '../dist-server/service/twin-forecast/forecast-metrics.js'
+
+test('물류 지표 — 기존 여섯은 그대로 센다', () => {
+  const s = {
+    items: [1, 2, 3],
+    locations: [{ occupancy: 2 }, { occupancy: 5 }],
+    tasks: [{}, {}],
+    orders: [{ status: 'shipped' }, { status: 'picking' }, { status: 'cancelled' }]
+  }
+  assert.equal(FORECAST_METRICS.items(s), 3)
+  assert.equal(FORECAST_METRICS.occupancy(s), 7)
+  assert.equal(FORECAST_METRICS.tasks(s), 2)
+  assert.equal(FORECAST_METRICS.orders(s), 3)
+  assert.equal(FORECAST_METRICS.shipped(s), 1)
+  /* 취소는 백로그가 아니다 — 대기와 취소를 같이 세면 「안 빠지는 일감」이 부풀려진다. */
+  assert.equal(FORECAST_METRICS.backlog(s), 1)
+})
+
+test('에너지 지표 — 커널이 낸 값을 그대로 읽는다(다시 계산하지 않는다)', () => {
+  const s = {
+    energy: {
+      peakSince: { kW: 812 },
+      open: { meanKW: 300, projectedKW: 455, projectionBasis: 'mean-so-far' },
+      closed: [{ overContract: true }, { overContract: false }, { overContract: true }]
+    }
+  }
+  assert.equal(FORECAST_METRICS.peakKW(s), 812)
+  assert.equal(FORECAST_METRICS.projectedKW(s), 455)
+  assert.equal(FORECAST_METRICS.overWindows(s), 2)
+})
+
+test('투영이 아직 없으면 지금까지의 평균으로 — 0 으로 떨어뜨리지 않는다', () => {
+  assert.equal(FORECAST_METRICS.projectedKW({ energy: { open: { meanKW: 120 } } }), 120)
+})
+
+test('에너지가 없는 스냅샷 — 세 지표 모두 0(그리지 않을 값이지, 관측한 0 이 아니다)', () => {
+  assert.equal(FORECAST_METRICS.peakKW({ items: [] }), 0)
+  assert.equal(FORECAST_METRICS.projectedKW({ items: [] }), 0)
+  assert.equal(FORECAST_METRICS.overWindows({ items: [] }), 0)
+})
+
+test('계약을 모르면 초과 구간은 0 — overContract 가 없는 구간을 초과로 세지 않는다', () => {
+  const s = { energy: { closed: [{ maxKW: 900 }, { maxKW: 1200 }] } }
+  assert.equal(FORECAST_METRICS.overWindows(s), 0)
+})
+
+test('종류별 지표 목록 — 에너지 트윈에는 물류 지표가 섞이지 않는다', () => {
+  const ems = metricsForKind('ems')
+  assert.deepEqual(ems, ['projectedKW', 'peakKW', 'overWindows'])
+  assert.equal(ems.includes('items' as any), false)
+  assert.equal(metricsForKind('wms').includes('items'), true)
+  /* 종류를 모르면 물류로 — 기존 트윈(kind 미선언)이 지표를 잃지 않는다. */
+  assert.equal(metricsForKind(undefined).includes('items'), true)
+})
+
+test('목록의 모든 키가 실제로 계산 가능하다 — 화면에 뜨는데 서버가 모르는 지표는 없다', () => {
+  for (const kind of ['ems', 'wms', 'mes', 'yms']) {
+    for (const key of metricsForKind(kind)) {
+      assert.equal(typeof (FORECAST_METRICS as any)[key], 'function', `${kind}:${key}`)
+    }
+  }
+})

package/test/forecast-tuning.test.ts

@@ -0,0 +1,42 @@
+/*
+ * 예측 틱 크기 — **지평선이 정하고, 양끝은 묶인다.**
+ *
+ * 이 규칙이 틀리면 예측이 조용히 비싸지거나(1초 고정 시절 9,000틱·28.5초) 조용히 성글어진다
+ * (짧은 작업이 한 틱에 삼켜진다). 둘 다 화면에는 그럴듯한 숫자로 나오므로 시험이 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { forecastStepMs, TARGET_TICKS_PER_RUN, MAX_STEP_MS, MIN_STEP_MS } from '../dist-server/service/twin-forecast/forecast-tuning.js'
+
+test('기본 지평선(5분)은 5초 단위 — 실측으로 1초와 답이 같고 5배 싸다', () => {
+  assert.equal(forecastStepMs(300_000), 5_000)
+})
+
+test('짧은 지평선은 더 잘게 — 1분이면 1초', () => {
+  assert.equal(forecastStepMs(60_000), 1_000)
+})
+
+test('아주 짧아도 커널 시각 단위 아래로 내려가지 않는다', () => {
+  assert.equal(forecastStepMs(5_000), MIN_STEP_MS)
+  assert.equal(forecastStepMs(0), MIN_STEP_MS)
+  assert.equal(forecastStepMs(Number.NaN), MIN_STEP_MS)
+})
+
+test('아무리 길어도 상한을 넘지 않는다 — 짧은 작업이 한 틱에 삼켜진다', () => {
+  assert.equal(forecastStepMs(2 * 60 * 60_000), MAX_STEP_MS)
+  assert.equal(forecastStepMs(24 * 60 * 60_000), MAX_STEP_MS)
+})
+
+test('틱 크기는 초 단위로 떨어진다 — 3,333ms 는 사람도 화면도 설명할 수 없다', () => {
+  for (const h of [100_000, 200_000, 333_000, 777_000]) {
+    assert.equal(forecastStepMs(h) % 1000, 0, `${h}ms`)
+  }
+})
+
+test('상한에 걸리지 않는 구간에서는 목표 틱 수 근처로 돈다', () => {
+  for (const h of [60_000, 120_000, 300_000, 600_000]) {
+    const ticks = h / forecastStepMs(h)
+    assert.ok(ticks >= TARGET_TICKS_PER_RUN * 0.8 && ticks <= TARGET_TICKS_PER_RUN * 1.25, `${h}ms → ${ticks}틱`)
+  }
+})

package/test/gap-analytics.test.ts

@@ -52,11 +52,38 @@ test('learnedCalibration — biasShift=평균오차, 편향 제거로 정확도
   assert.equal(learn.accAfter, 100, '일정 편향을 완전 제거 → 잔차 0 → 100%')
 })
 
-test('aggregatePoints — 공동배치 인덱스별 합산(공장 총량)', () => {
-  const a = [pt(2, 30), pt(4, 30)]
-  const b = [pt(1, 20), pt(2, 20)]
-  const agg = aggregatePoints([a, b])
-  assert.equal(agg.length, 2)
-  assert.equal(agg[0].actual, 50, '실제 30+20')
-  assert.equal(agg[0].error, agg[0].actual - agg[0].p50, 'error = 실제−예측(합산 후 재계산)')
+/* 같은 격자 위의 점 — vantage 를 명시한다(예전 헬퍼는 t 를 늘 0 으로 두어 시간축을 전혀 시험하지 않았다). */
+const at = (t: number, error: number, actual = 100) => ({ ...pt(error, actual), t })
+
+test('aggregatePoints — 공동배치 합산(공장 총량)', () => {
+  const a = [at(10, 2, 30), at(20, 4, 30)]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a, b])
+  assert.equal(points.length, 2)
+  assert.equal(droppedVantages, 0)
+  assert.equal(points[0].actual, 50, '실제 30+20')
+  assert.equal(points[0].t, 10, '합산점의 시각은 그 vantage 다')
+  assert.equal(points[0].error, points[0].actual - points[0].p50, 'error = 실제−예측(합산 후 재계산)')
+})
+
+test('한 트윈이 못 잰 vantage 는 통째로 뺀다 — 빠진 트윈을 0 으로 세지 않는다', () => {
+  /*
+   * 예전에는 `max` 길이로 돌며 있는 것만 더했다. 그래서 이 경우 t=20 의 공장 총량이 20(b 뿐)으로
+   * 나왔다 — a 가 그 시각에 아무것도 안 했다는 뜻이 아니라, **못 쟀다**는 뜻인데도.
+   * 공장 합계 곡선이 꼬리에서 아래로 꺾이고, 그 곡선으로 예측 정확도를 판정했다.
+   */
+  const a = [at(10, 2, 30), null]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a as any, b])
+  assert.equal(points.length, 1, '모두가 값을 가진 vantage 만 남는다')
+  assert.equal(points[0].t, 10)
+  assert.equal(droppedVantages, 1, '뺀 개수를 돌려줘야 화면이 "2점 중 1점" 이라고 말할 수 있다')
+})
+
+test('길이가 다르면 뒤쪽은 뺀다 — 남은 트윈만의 합을 공장 총량이라 부르지 않는다', () => {
+  const a = [at(10, 2, 30)]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a, b])
+  assert.equal(points.length, 1)
+  assert.equal(droppedVantages, 1)
 })

package/test/ingest-bench.test.ts

@@ -1,6 +1,6 @@
 /*
  * 커널 인제스트 인터페이스 부하 실측(가정 아닌 측정) — Face1/커널 동기 인터페이스의 처리량 특성.
- * apply(이벤트 흡수) · snapshot(전체 투영) · buildEntityDeltas(방송 payload) 의 비용을 규모별로 잰다.
+ * apply(이벤트 흡수) · snapshot(전체 투영) · buildEntityDeltas(방송 payload, 't1') 의 비용을 규모별로 잰다.
  * 결론은 design/integration/ingest-scale.md §커널 인터페이스에 스펙으로 반영.
  * (순수 커널+호스트 매핑, shell 무관 → node:test.)
  */
@@ -8,10 +8,10 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { StateProjector, objectEvent, BIZSTEP, DISP } from '@operato/twin-kernel'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const T0 = '2026-07-19T00:00:00.000Z'
-const board = (nNodes: number) => ({
+const model = (nNodes: number) => ({
   locations: Array.from({ length: nNodes }, (_, i) => ({ id: `bin-${i}`, type: 'storage', capacity: 100000 })),
   equipment: []
 })
@@ -23,7 +23,7 @@ function envelope(epc: string, location: string): any {
 test('bench: apply 처리량(이벤트 흡수)', () => {
   const nNodes = 200
   const M = 200_000
-  const proj = new StateProjector(board(nNodes))
+  const proj = new StateProjector(model(nNodes))
   const t0 = performance.now()
   for (let i = 0; i < M; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % nNodes}`))
   const dt = performance.now() - t0
@@ -33,7 +33,7 @@ test('bench: apply 처리량(이벤트 흡수)', () => {
 
 test('bench: snapshot 비용 vs item 수 (전체 O(N) 재구성)', () => {
   for (const N of [1000, 10000, 50000]) {
-    const proj = new StateProjector(board(200))
+    const proj = new StateProjector(model(200))
     for (let i = 0; i < N; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % 200}`))
     const iters = 200
     const t0 = performance.now()
@@ -45,12 +45,12 @@ test('bench: snapshot 비용 vs item 수 (전체 O(N) 재구성)', () => {
 
 test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방출)', () => {
   for (const N of [100, 1000, 5000]) {
-    const proj = new StateProjector(board(N))
+    const proj = new StateProjector(model(N))
     for (let i = 0; i < N * 5; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % N}`))
     const snap = proj.snapshot()
     const iters = 200
     const t0 = performance.now()
-    for (let k = 0; k < iters; k++) buildEntityDeltas(snap)
+    for (let k = 0; k < iters; k++) buildEntityDeltas(snap, 't1')
     const per = (performance.now() - t0) / iters
     console.log(`  [buildEntityDeltas] @ ${N.toLocaleString()} locations: ${per.toFixed(3)}ms/call`)
   }
@@ -58,11 +58,11 @@ test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방
 
 test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규모', () => {
   for (const [locations, items] of [[200, 5000], [1000, 50000], [2000, 100000]]) {
-    const proj = new StateProjector(board(locations))
+    const proj = new StateProjector(model(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())
+    for (let k = 0; k < iters; k++) buildEntityDeltas(proj.snapshot(), 't1')
     const per = (performance.now() - t0) / iters
     console.log(`  [방송1회] ${locations.toLocaleString()} locations / ${items.toLocaleString()} items: ${per.toFixed(3)}ms → 최대 ${Math.round(1000 / per).toLocaleString()} 방송/s`)
   }