@things-factory/headless-twin 10.0.7 → 10.0.9

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 } from '../server/engine/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,9 @@ 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)
 })

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.)
  */
@@ -50,7 +50,7 @@ test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방
     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`)
   }
@@ -62,7 +62,7 @@ test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규
     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`)
   }

package/test/ingest-space.test.ts

@@ -0,0 +1,50 @@
+/*
+ * 인제스트 공간 판정 — "이 현장에 더한다" 가 조용히 빗나가지 않게.
+ *
+ * 엔진 본체는 DB·TypeORM 을 물고 있어 단위테스트로 부를 수 없다. 그래서 **결정만** 순수 모듈로
+ * 떼어 놓고 여기서 본다(엔진은 공간 존재 여부를 조회해 넘기는 일만 한다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveIngestSpace, collidingIds, INGEST_SPACE_NOT_FOUND } from '../server/service/reference/ingest-space.ts'
+
+test('고르지 않으면 마스터가 파생한 공간으로 — 지금까지의 거동을 바꾸지 않는다', () => {
+  for (const req of [undefined, null, '', '   ']) {
+    const c = resolveIngestSpace('hatiolab-wms-site', req as any, false)
+    assert.deepEqual(c, { spaceId: 'hatiolab-wms-site', joined: false }, `요청=${JSON.stringify(req)}`)
+  }
+})
+
+test('기존 현장을 고르면 그 공간으로 들어가고 합치기로 표시된다', () => {
+  const c = resolveIngestSpace('trailer-yard-new-site', 'rosarito-site', true)
+  assert.deepEqual(c, { spaceId: 'rosarito-site', joined: true })
+})
+
+test('마스터가 이미 그 공간이면 합치기가 아니다 — 같은 공간의 재인제스트다', () => {
+  const c = resolveIngestSpace('rosarito-site', 'rosarito-site', true)
+  assert.deepEqual(c, { spaceId: 'rosarito-site', joined: false })
+})
+
+test('없는 현장은 거절한다 — 조용히 새 공간을 만들지 않는다', () => {
+  /* 여기서 새 공간을 만들어 주면 사용자는 합쳤다고 믿고 화면은 따로 논다. 그때는 이미 양쪽에
+     이벤트가 쌓여 있어 손으로 합치는 것이 훨씬 비싸다. */
+  assert.throws(
+    () => resolveIngestSpace('a-site', 'typo-site', false),
+    (e: any) => e.code === INGEST_SPACE_NOT_FOUND && /typo-site/.test(e.message)
+  )
+})
+
+test('앞뒤 공백은 다듬는다 — 사용자가 붙여 넣은 id 로 거절당하지 않게', () => {
+  const c = resolveIngestSpace('a-site', '  rosarito-site  ', true)
+  assert.equal(c.spaceId, 'rosarito-site')
+})
+
+test('같은 id 를 쓰는 것들을 찾아낸다 — 합쳐지는 것을 모르고 지나가지 않게', () => {
+  const existing = [{ id: 'a-yard' }, { id: 'a-dock' }]
+  const incoming = [{ id: 'a-yard' }, { id: 'a-line' }, { id: 'a-dock' }]
+  assert.deepEqual(collidingIds(existing, incoming), ['a-dock', 'a-yard'], '정렬된 교집합')
+  assert.deepEqual(collidingIds(existing, [{ id: 'a-line' }]), [], '겹치지 않으면 빈 배열')
+  assert.deepEqual(collidingIds(undefined, undefined), [], '없는 쪽은 빈 것으로 본다')
+  assert.deepEqual(collidingIds([{}, { id: '' }], [{ id: '' }]), [], 'id 없는 항목은 세지 않는다')
+})

package/test/knob-defaults.test.ts

@@ -0,0 +1,72 @@
+/*
+ * 노브 기본값 — **조용히 아무것도 안 하는 트윈**이 만들어지지 않게.
+ *
+ * 기본값을 아는 곳은 노브 스키마(계약)인데 그것을 적용하는 곳이 위자드뿐이었다. 그래서 화면을 거치지
+ * 않는 호출자가 파라미터를 일부만 주면 템플릿 안에서 발생률이 0 이 되고, 이벤트를 하나도 만들지 않는
+ * 트윈이 아무 말 없이 생겼다(실제로 밟았고 템플릿이 깨진 것으로 오진했다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { applyKnobDefaults, filledKnobKeys } from '../server/service/reference/knob-defaults.ts'
+
+const KNOBS = [
+  { key: 'id', default: 'wms-new' },
+  { key: 'inboundRate', default: 40 },
+  { key: 'outboundRate', default: 30 },
+  { key: 'geo', default: { lat: 37.5, lon: 127.0 } },
+  { key: 'noDefault' } // 기본값을 선언하지 않은 노브
+]
+
+test('빠진 노브를 기본값으로 채운다 — 부분 파라미터 호출이 죽은 트윈을 만들지 않게', () => {
+  const out = applyKnobDefaults(KNOBS, { id: 'mine' })
+  assert.equal(out.id, 'mine', '준 값은 그대로')
+  assert.equal(out.inboundRate, 40)
+  assert.equal(out.outboundRate, 30)
+  assert.deepEqual(out.geo, { lat: 37.5, lon: 127.0 })
+  assert.ok(!('noDefault' in out), '기본값 없는 노브는 만들어 내지 않는다')
+})
+
+test('0 은 덮지 않는다 — "자극 없이 구조만" 이라는 선언을 뒤집지 않게', () => {
+  /* falsy 로 판정해 덮으면 발생률 0(도착 없음)이 40 으로 바뀐다. 없는 것과 0 은 다르다. */
+  const out = applyKnobDefaults(KNOBS, { inboundRate: 0, outboundRate: 0 })
+  assert.equal(out.inboundRate, 0)
+  assert.equal(out.outboundRate, 0)
+})
+
+test('빈 문자열·false 도 뜻 있는 값이라 덮지 않는다', () => {
+  const out = applyKnobDefaults([{ key: 'name', default: 'New site' }, { key: 'flag', default: true }], { name: '', flag: false })
+  assert.equal(out.name, '')
+  assert.equal(out.flag, false)
+})
+
+test('null 은 "주지 않음" 으로 본다 — JSON·GraphQL 경로가 그렇게 보낸다', () => {
+  const out = applyKnobDefaults(KNOBS, { inboundRate: null as any })
+  assert.equal(out.inboundRate, 40)
+})
+
+test('선언 밖 파라미터는 손대지 않는다 — 템플릿의 폴백 경로를 끊지 않게', () => {
+  /* 템플릿은 `geo` 대신 `lat`/`lon` 을 읽는 폴백을 가진다. 모르는 키를 걷어내면 그 경로가 끊긴다. */
+  const out = applyKnobDefaults(KNOBS, { lat: 1, lon: 2 })
+  assert.equal(out.lat, 1)
+  assert.equal(out.lon, 2)
+})
+
+test('입력을 바꾸지 않는다 — 호출자의 객체가 몰래 변하면 추적이 어렵다', () => {
+  const given = { id: 'mine' }
+  applyKnobDefaults(KNOBS, given)
+  assert.deepEqual(given, { id: 'mine' })
+})
+
+test('노브가 없거나 파라미터가 없어도 무너지지 않는다', () => {
+  assert.deepEqual(applyKnobDefaults(null, { a: 1 }), { a: 1 })
+  assert.deepEqual(applyKnobDefaults(KNOBS, null).inboundRate, 40)
+  assert.deepEqual(applyKnobDefaults(undefined, undefined), {})
+})
+
+test('무엇을 채웠는지 알린다 — 준 적 없는 값으로 만들어진 것을 밝히게', () => {
+  assert.deepEqual(filledKnobKeys(KNOBS, { id: 'mine', inboundRate: 0 }), ['outboundRate', 'geo'],
+    '준 것과 0 은 채운 목록에 없다')
+  assert.deepEqual(filledKnobKeys(KNOBS, null), ['id', 'inboundRate', 'outboundRate', 'geo'])
+  assert.deepEqual(filledKnobKeys(KNOBS, { id: 'a', inboundRate: 1, outboundRate: 2, geo: {} }), [], '다 주면 빈 목록')
+})

package/test/kpi-baseline-db.test.ts

@@ -0,0 +1,214 @@
+/*
+ * ★ 여러 구간 동시 비교 — **실 DB로 배관을 넘어 본다.**
+ *
+ * 분포 산수는 `kpi-baseline.test.ts`(순수)가 지킨다. 여기서 지키는 것은 **호스트 배관**이다:
+ * 창을 하루씩 뒤로 옮겨 **각 창을 따로 읽는가** · 그 창을 같은 규칙으로 접는가 · 지표 값을 정본 표
+ * (`TWIN_METRIC`)로 꺼내는가 · 기록 없는 날을 결측으로 남기는가.
+ *
+ * 이 배관은 **경계를 넘어야만** 틀리는 것이 드러난다. 실제로 앱의 시뮬 트윈은 저널이 두 시간 남짓이라
+ * "지난 7일" 을 물어도 과거 창이 모두 비어 있어(정직하게 자리를 거부한다) 분포 경로를 한 번도 밟지
+ * 못했다. 그래서 여러 날에 걸친 저널을 손으로 심어 그 경로를 통과시킨다.
+ *
+ * 실 엔티티·실 네이밍 전략의 sqlite in-memory 스키마에 **빌드 산출물**을 실행한다.
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌려야 반영된다.**
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { computeTwinKpi } = req('../dist-server/engine/index.js')
+const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'baseline-probe'
+const MS_DAY = 24 * 60 * 60_000
+
+/** 창의 끝 — 고정 시각을 쓴다(테스트가 벽시계에 흔들리지 않게). */
+const TO = Date.parse('2026-03-10T10:00:00.000Z')
+const FROM = TO - 60 * 60_000
+
+/**
+ * 완료 한 건 = 시작 + 완료 두 줄. 소요시간이 짝맞춤에서 나오므로 둘 다 필요하다.
+ * 완료 시각이 창 안에 들면 그 창의 성과로 센다.
+ */
+function taskRows(dayBack: number, count: number, workMs: number, revBase: number) {
+  const rows: any[] = []
+  const endBase = TO - dayBack * MS_DAY - 60_000 // 창 끝 1분 전에 완료
+  for (let i = 0; i < count; i++) {
+    const taskId = `t-${dayBack}-${i}`
+    const done = endBase - i * 1000
+    const started = done - workMs
+    rows.push(
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2,
+        eventType: 'task.status',
+        eventTime: new Date(started).toISOString(),
+        payload: { data: { taskId, status: 'in-progress', resourceRef: 'fk-1' } }
+      },
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2 + 1,
+        eventType: 'task.status',
+        eventTime: new Date(done).toISOString(),
+        /* 완료 어휘는 **커널이 소유한다**(`foldTaskRecords`) — 'done' 이 아니라 'completed' 다.
+           처음에 'done' 으로 심었더니 창은 잡히는데 건수가 0 이었다(이 DB 스펙이 그것을 잡았다). */
+        payload: { data: { taskId, status: 'completed', resourceRef: 'fk-1' } }
+      }
+    )
+  }
+  return rows
+}
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'baseline-test', subdomain: 'baseline-test' } as any)
+  domainId = d.id
+
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'wms',
+    status: 'stopped',
+    board: { locations: [{ id: 'dock', type: 'dock', capacity: 10 }], equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }] }
+  } as any)
+
+  /*
+   * 지금 창 20건 · 어제 40건 · 그제 60건 · **3일 전은 기록 없음** · 4일 전 80건.
+   * 3일 전을 비워 두는 것이 이 스펙의 요점이다 — 그 날이 결측으로 남고 분포에서 빠지는지 본다
+   * (조용히 빼면 "지난 4일" 이 실제로는 3일이었다는 것을 아무도 모른다).
+   */
+  const rows = [
+    ...taskRows(0, 20, 30_000, 1000),
+    ...taskRows(1, 40, 40_000, 3000),
+    ...taskRows(2, 60, 50_000, 6000),
+    ...taskRows(4, 80, 60_000, 9000)
+  ]
+  await ds.getRepository(TwinEvent).save(rows)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+const kpi = (periods: number, stride?: 'day' | 'week') =>
+  computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(FROM).toISOString(),
+    toTime: new Date(TO).toISOString(),
+    baseline: { periods, ...(stride ? { stride } : {}) }
+  })
+
+test('과거 창을 하루씩 따로 읽어 분포를 만든다', async () => {
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(out.baseline.stride, 'day')
+  assert.equal(out.baseline.periods, 4)
+  assert.equal(tasks.current, 20, '지금 창')
+  /* 어제 40 · 그제 60 · 3일 전 없음 · 4일 전 80. */
+  assert.deepEqual([tasks.min, tasks.median, tasks.max], [40, 60, 80])
+})
+
+test('기록 없는 날을 **결측으로 남긴다** — 요청한 창 수와 측정된 수를 함께 답한다', async () => {
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.requested, 4)
+  assert.equal(tasks.measuredCount, 3, '3일 전은 기록이 없다')
+  assert.equal(tasks.samples.length, 4, '창 자체는 네 개 모두 돌려준다')
+  assert.deepEqual(tasks.samples.map((s: any) => s.measured), [true, true, false, true])
+  assert.deepEqual(tasks.samples.map((s: any) => s.value), [40, 60, undefined, 80])
+})
+
+test('처리량이 지난 며칠 중 가장 낮으면 worst — 이 축이 답하려던 질문', async () => {
+  /* 예전에는 "어제보다 나아졌나" 까지만 답할 수 있었다. 지금 창(20)은 어제(40)보다도 낮고
+     최근 어느 날보다도 낮다 — 그것을 한 번에 말할 수 있어야 한다. */
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.standing, 'worst')
+  assert.equal(tasks.rank, 1, '오름차순 첫째')
+  assert.equal(tasks.rankOf, 4, '표본 3 + 현재 1')
+})
+
+test('방향은 지표가 안다 — 작업시간이 가장 짧으면 best', async () => {
+  const out: any = await kpi(4)
+  const work = out.baseline.metrics.find((m: any) => m.metric === 'workTime.p50Ms')
+
+  assert.equal(work.current, 30_000)
+  assert.deepEqual([work.min, work.max], [40_000, 60_000])
+  assert.equal(work.standing, 'best', '짧을수록 좋다')
+})
+
+test('구간 수를 줄이면 그만큼만 본다 — 창을 지어내지 않는다', async () => {
+  const out: any = await kpi(1)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.requested, 1)
+  assert.equal(tasks.measuredCount, 1)
+  /* 표본 하나는 분포가 아니다. */
+  assert.equal(tasks.noPosition, 'too-few-samples')
+  assert.equal(tasks.standing, undefined)
+})
+
+test('주 단위는 같은 요일을 본다 — 하루 전 기록에 걸리지 않는다', async () => {
+  const out: any = await kpi(2, 'week')
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(out.baseline.stride, 'week')
+  /* 심어 둔 기록은 최근 나흘뿐이라 지난주 같은 요일에는 아무것도 없다 — 지어내지 않는다. */
+  assert.equal(tasks.measuredCount, 0)
+  assert.equal(tasks.noPosition, 'too-few-samples')
+})
+
+test('요청하지 않으면 분포를 만들지 않는다 — 조회가 공짜가 아니다', async () => {
+  const out: any = await computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(FROM).toISOString(),
+    toTime: new Date(TO).toISOString()
+  })
+
+  assert.equal(out.baseline, undefined)
+})
+
+test('지금 창에 기록이 없어도 분포는 낸다 — 그때가 가장 알고 싶은 순간이다', async () => {
+  /* 심어 둔 기록이 없는 시각을 창으로 잡는다(3일 전). 평소엔 일이 있었는데 지금 없다 = 멈춘 신호. */
+  const quietTo = TO - 3 * MS_DAY
+  const out: any = await computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(quietTo - 60 * 60_000).toISOString(),
+    toTime: new Date(quietTo).toISOString(),
+    baseline: { periods: 2 }
+  })
+
+  assert.equal(out.measured, false, '지금 창에는 측정할 기록이 없다')
+  assert.ok(out.baseline, '그래도 분포는 낸다')
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+  assert.equal(tasks.measuredCount, 1, '4일 전 하루만 걸린다(5일 전은 기록 없음)')
+  assert.equal(tasks.samples.find((s: any) => s.measured).value, 80)
+})