@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/kpi-fold.test.ts

@@ -552,7 +552,7 @@ test('방향은 지표의 성질이다 — 사용자가 반대로 적을 수 없
   assert.equal(faster.met, true, '실제 30초 ≤ 목표 60초')
 })
 
-test('미달을 미달이라 말한다', () => {
+test('미달을 미달로 판정한다', () => {
   const kpi = kpiOf([...doneAtHour('t1', 7)])
   const [v] = judgeTargets(kpi, [{ metric: 'throughput.tasks', target: 5 }])
   assert.equal(v.met, false)
@@ -572,7 +572,7 @@ test('목표가 없으면 판정하지 않는다', () => {
   assert.deepEqual(judgeTargets(kpiOf([...doneAtHour('t1', 7)]), undefined), [])
 })
 
-test('값이 없는 지표는 판정하지 않는다 — 0 으로 놓으면 반대로 거짓말한다', () => {
+test('값이 없는 지표는 판정하지 않는다 — 0 으로 놓으면 판정이 반대로 뒤집힌다', () => {
   const empty = foldKpi([], DAY)
   /* 이 테스트가 실제로 결함을 잡았다: 분위수는 표본이 없으면 p50Ms: 0 으로 나온다. 그것을 값으로 읽으면
      시간 지표는 "낮을수록 좋다" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 —
@@ -696,3 +696,394 @@ test('축 항목별로 판정한다 — 값이 없는 지표는 판정하지 않
     '대기시간은 표본이 없어 판정 안 함 · 자원 점유는 축 단위로 뜻이 없어 판정 안 함'
   )
 })
+
+/*
+ * ── 에너지 원단위 (§10 7단계) ───────────────────────────────────────────────
+ *
+ * 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서 나눈 값이다. 그래서 별도 질의가 아니라 이 폴드
+ * 안에 있다 — 창이 하나뿐이면 어긋날 수 없다.
+ *
+ * 분자는 저널의 **구간 마감 사건**에서 온다(커널 상태가 아니라 저널이므로 멈춘 트윈·과거 구간에도
+ * 답한다). 그 값이 파생임을 `basis` 가 말하고, 못 센 구간 수를 함께 낸다.
+ */
+const T = Date.parse('2026-08-14T00:00:00.000Z')
+const q = 15 * 60_000
+const win = (startMs: number, endMs: number, meanKW?: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, ...(meanKW !== undefined ? { meanKW } : {}) } }
+})
+const orderDone = (atMs: number) => ({
+  eventType: 'order.status',
+  eventTime: new Date(atMs).toISOString(),
+  payload: { data: { status: 'completed' } }
+})
+
+test('에너지 사건이 없으면 에너지 블록을 내지 않는다 — 없는 것을 만들지 않는다', () => {
+  const r = foldKpi([orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy, undefined)
+})
+
+test('구간 마감에서 전력량과 대당 원단위를 낸다 — 같은 창이므로 어긋날 수 없다', () => {
+  const r = foldKpi(
+    [win(T, T + q, 400), win(T + q, T + 2 * q, 400), orderDone(T + 60_000), orderDone(T + q + 60_000)],
+    { fromMs: T, toMs: T + 2 * q }
+  )
+  assert.equal(r.energy?.kWh, 200, '400kW × 0.25h × 2구간')
+  assert.equal(r.energy?.basis, 'mean-kw', '파생임을 밝힌다')
+  assert.equal(r.energy?.counted, 2)
+  assert.equal(r.energy?.intensity.value, 100, '200kWh ÷ 완료 2건')
+  assert.equal(r.energy?.intensity.unit, 'kWh/unit')
+})
+
+test('그 창에 완료가 없으면 원단위는 정의되지 않는다 — 전력량은 그대로 낸다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.kWh, 100, '전력량은 사실이다')
+  assert.equal(r.energy?.intensity.value, null)
+  assert.equal(r.energy?.intensity.reason, 'zero-denominator', '무한으로 내지 않는다')
+})
+
+test('계측이 끊긴 구간은 세지 않고 몇 개를 못 셌는지 말한다', () => {
+  const r = foldKpi([win(T, T + q, 400), win(T + q, T + 2 * q), orderDone(T + 60_000)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.counted, 1)
+  assert.equal(r.energy?.skipped, 1, '조용히 빼면 이 합이 그 창의 전부인 줄 읽는다')
+})
+
+test('창에 걸친 구간은 세지 않는다 — 부분을 비례로 자르면 추정이 하나 더 생긴다', () => {
+  const r = foldKpi([win(T, T + q, 400), win(T + q, T + 2 * q, 400)], { fromMs: T, toMs: T + q + 60_000 })
+  assert.equal(r.energy?.counted, 1)
+  assert.equal(r.energy?.kWh, 100)
+})
+
+/*
+ * ── 창의 최대수요 (2026-08-17) ──────────────────────────────────────────────
+ *
+ * 전력량은 요금의 사용량 부분이고, 최대수요는 **기본요금과 계약 위반**을 정한다. 평균으로 갈음하면
+ * 계약을 넘긴 창이 「안 넘겼다」로 보고된다 — 15분 평균 400kW 인 창의 최대가 1,200kW 일 수 있다.
+ */
+const winMax = (startMs: number, endMs: number, meanKW: number, maxKW: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, meanKW, maxKW } }
+})
+
+test('창의 최대수요는 구간 최대들 중 가장 큰 값이다 — 평균으로 갈음하지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 620), winMax(T + q, T + 2 * q, 400, 1180)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.kWh, 200)
+  assert.equal(r.energy?.peakKW, 1180)
+  assert.equal(r.energy?.peakStartMs, T + q, '언제였는지도 답할 수 있어야 한다')
+})
+
+test('구간이 최대를 싣지 않으면 최대수요는 없다 — 0 도 평균도 아니다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.kWh, 100)
+  assert.equal(r.energy?.peakKW, undefined)
+})
+
+/*
+ * ── 에너지 목표 (2026-08-17) ────────────────────────────────────────────────
+ *
+ * 값은 폴드가 내고 있었는데 목표를 걸 수 있는 어휘에 없었다 — 그래서 화면은 「1,240kWh」를 보이면서도
+ * 그것이 계약 안쪽인지 말하지 못했다. 방향은 셋 다 「낮을수록 좋다」로 못 박혀 있다.
+ */
+test('최대수요 목표 — 계약 상한을 넘겼는지 판정한다', () => {
+  const kpi = foldKpi([winMax(T, T + q, 400, 1180)], { fromMs: T, toMs: T + q })
+  const [v] = judgeTargets(kpi, [{ metric: 'energy.peakKW', target: 800 }])
+  assert.equal(v.direction, 'lower', '많이 쓸수록 좋은 에너지 목표는 없다')
+  assert.equal(v.actual, 1180)
+  assert.equal(v.met, false, '계약 800kW 를 넘겼다')
+})
+
+test('전력량·원단위에도 목표를 건다', () => {
+  const kpi = foldKpi([win(T, T + q, 400), orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  const [kwh] = judgeTargets(kpi, [{ metric: 'energy.kWh', target: 120 }])
+  assert.equal(kwh.actual, 100)
+  assert.equal(kwh.met, true)
+  const [per] = judgeTargets(kpi, [{ metric: 'energy.intensity', target: 80 }])
+  assert.equal(per.actual, 100, '100kWh ÷ 완료 1건')
+  assert.equal(per.met, false)
+})
+
+test('에너지를 못 잰 창은 판정하지 않는다 — 0 으로 읽으면 안 쓴 것이 만점이 된다', () => {
+  const kpi = foldKpi([orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  assert.equal(judgeTargets(kpi, [{ metric: 'energy.kWh', target: 120 }]).length, 0)
+  assert.equal(judgeTargets(kpi, [{ metric: 'energy.peakKW', target: 800 }]).length, 0)
+  /* 원단위는 분모가 없어 `null` 로 온다 — 그것도 판정 대상이 아니다. */
+  const noOrders = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(noOrders.energy?.intensity.value, null)
+  assert.equal(judgeTargets(noOrders, [{ metric: 'energy.intensity', target: 80 }]).length, 0)
+})
+
+/*
+ * ── 분기별 몫 (2026-08-17) ──────────────────────────────────────────────────
+ *
+ * 저널의 에너지 사실은 **현장 총량 한 줄**이다. 그래서 자리별 몫은 잰 것이 아니라 **나눈 것**이고,
+ * 그 사실을 값과 함께 내야 한다. 이 검사가 지키는 것: 합 보존 · 근거 표시 · 모르는 자리를 지어내지
+ * 않기 · 선언이 없으면 분해하지 않기.
+ */
+const runs = (taskId: string, resource: string, fromSec: number, toSec: number) => [
+  { eventType: 'task.status', eventTime: new Date(T + fromSec * 1000).toISOString(), payload: { data: { taskId, status: 'in-progress', resourceRef: resource } } },
+  { eventType: 'task.status', eventTime: new Date(T + toSec * 1000).toISOString(), payload: { data: { taskId, status: 'completed', resourceRef: resource } } }
+]
+
+test('분기별 몫 — 가동시간에 비례해 나누고, 합은 총량을 지킨다', () => {
+  /* press 300초 · weld 100초 → 3:1. 총량 100kWh. */
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300), ...runs('t2', 'weld-1', 0, 100)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' } })
+  assert.equal(r.energy?.kWh, 100)
+  const by = r.energy?.byFeeder ?? []
+  assert.equal(by.length, 2)
+  const press = by.find(x => x.key === 'feeder-press')!
+  const weld = by.find(x => x.key === 'feeder-weld')!
+  assert.ok(Math.abs(press.kWh - 75) < 1e-6, `press ${press.kWh}`)
+  assert.ok(Math.abs(weld.kWh - 25) < 1e-6, `weld ${weld.kWh}`)
+  /* 합 보존 — 이것이 깨지면 어딘가에서 전기가 사라지거나 생겨난 것이고, 그 위 모든 원단위가 거짓이다. */
+  const sum = by.reduce((a, x) => a + x.kWh, 0) + (r.energy?.unattributedKWh ?? 0)
+  assert.ok(Math.abs(sum - 100) < 1e-6, `합 ${sum}`)
+})
+
+test('몫에는 근거가 붙는다 — 여럿을 나눈 것이면 배분이라고 말한다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300), ...runs('t2', 'weld-1', 0, 100)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' } })
+  const row = r.energy!.byFeeder![0]
+  assert.equal(row.basis, 'apportioned')
+  assert.equal(row.weightKind, 'runtimeMs')
+  assert.ok(row.weightShare > 0)
+})
+
+/*
+ * 선언된 부하가 **하나뿐인** 현장 — 커널은 「그 계량기는 그것만 잰다」고 읽는다(모델이 그렇게 말했다).
+ * 우리가 그것을 배분으로 낙인찍지 않는다: 처음에는 하드코딩으로 그렇게 했고, 그건 커널이 판정한 것을
+ * 화면에서 바꿔 말하는 짓이었다. 반대로 「돌아간 자원만 덮는다」고 거짓 선언을 넘기면 여럿인 현장에서도
+ * 이 경로로 빠져 배분이 측정으로 보고된다 — 그것이 실제로 처음의 결함이었다.
+ */
+test('선언된 부하가 하나면 커널의 판정을 그대로 옮긴다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press' } })
+  assert.equal(r.energy!.byFeeder![0].basis, 'measured')
+})
+
+test('돌지 않은 설비는 0kWh 를 받지 않고, 몇 대가 빠졌는지 센다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, {
+    resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld', 'paint-1': 'feeder-paint' }
+  })
+  const keys = (r.energy!.byFeeder ?? []).map(x => x.key)
+  assert.deepEqual(keys, ['feeder-press'], '가동 기록이 없는 자리는 행을 만들지 않는다(0 을 지어내지 않는다)')
+  assert.equal(r.energy!.excludedResources, 2, '빠진 설비 수를 밝힌다')
+})
+
+test('자리를 모르는 자원은 unknown 으로 모인다 — 빼지도, 아무 분기에 넣지도 않는다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 200), ...runs('t2', 'ghost-1', 0, 200)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press' } })
+  const by = r.energy!.byFeeder!
+  assert.ok(by.some(x => x.key === 'unknown'), '모르는 자리를 지어내지 않는다')
+  const sum = by.reduce((a, x) => a + x.kWh, 0)
+  assert.ok(Math.abs(sum - 100) < 1e-6, '모르는 몫까지 합해 총량을 지킨다')
+})
+
+test('선언이 없으면 분해하지 않는다 — 자리를 모르는 채 나눈 숫자는 아무 것의 몫도 아니다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.byFeeder, undefined)
+  assert.equal(r.energy?.kWh, 100, '총량은 그대로 낸다')
+})
+
+test('그 창에 아무도 돌지 않았으면 나누지 않고 이유를 낸다', () => {
+  /* 부하가 둘 이상 선언된 현장 — 나눌 대상은 있는데 몫이 없다. */
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q }, {
+    resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' }
+  })
+  assert.equal(r.energy?.byFeeder, undefined, '가동 기록이 없으면 나눌 근거가 없다')
+  assert.equal(r.energy?.unattributedReason, 'no-weights')
+  assert.equal(r.energy?.unattributedKWh, 100, '나누지 못한 양은 그대로 남는다(0 으로 만들지 않는다)')
+  assert.equal(r.energy?.kWh, 100)
+})
+
+/*
+ * ── 금액 (2026-08-17) ───────────────────────────────────────────────────────
+ *
+ * 트윈은 「최대수요 328kW」까지 말하고 멈춰 있었다. 피크를 깎는 일이 돈이 되는 이유가 요금의 구조에
+ * 있으므로(사용량 + 기본요금) 단가를 선언하면 금액이 나온다. 계산은 커널이 하고 폴드는 나른다 —
+ * 이 검사는 **같은 창의 값에서 나오는지**와 **단가가 없을 때 지어내지 않는지**를 본다.
+ */
+test('단가를 선언하면 이 창의 금액이 나온다 — 전력량과 최대수요 각각에서', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 1000)], { fromMs: T, toMs: T + q }, {
+    tariff: { energyChargePerKWh: 0.1, demandChargePerKW: 20, currency: 'USD' }
+  })
+  assert.equal(r.energy?.kWh, 100)
+  assert.equal(r.energy?.peakKW, 1000)
+  const c: any = r.energy?.cost
+  assert.equal(c.energyCharge, 10, '100kWh × 0.1')
+  assert.equal(c.demandCharge, 20_000, '1,000kW × 20')
+  assert.equal(c.currency, 'USD')
+  assert.equal(c.demandBasis, 'window-peak-as-period-peak', '기본요금의 조건이 값과 함께 온다')
+})
+
+test('단가를 선언하지 않으면 금액을 만들지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 1000)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.cost, undefined)
+})
+
+test('최대수요를 못 잰 창은 기본요금을 지어내지 않는다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q }, { tariff: { demandChargePerKW: 20, energyChargePerKWh: 0.1 } })
+  const c: any = r.energy?.cost
+  assert.equal(c.energyCharge, 10)
+  assert.equal(c.demandCharge, undefined)
+})
+
+test('에너지 사실이 없는 창에는 금액도 없다 — 0 원이라고 말하지 않는다', () => {
+  const r = foldKpi([orderDone(T + 1000)], { fromMs: T, toMs: T + q }, { tariff: { demandChargePerKW: 20 } })
+  assert.equal(r.energy, undefined)
+})
+
+/*
+ * ── 깎인 양 (2026-08-17) ────────────────────────────────────────────────────
+ *
+ * 요금은 계통 수요로 매겨지고, 그 수요를 만든 것은 설비 부하다. 두 수의 간격이 곧 태양광·배터리가
+ * 덜어낸 몫이다 — 그것이 피크 셰이빙의 값이다. **같은 구간의 두 수**여야 차이가 뜻을 갖는다.
+ */
+const winNet = (startMs: number, endMs: number, meanKW: number, maxKW: number, grossMaxKW?: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, meanKW, maxKW, ...(grossMaxKW !== undefined ? { grossMaxKW } : {}) } }
+})
+
+test('피크 구간의 총부하와 깎인 양을 낸다', () => {
+  const r = foldKpi([winNet(T, T + q, 300, 400, 600), winNet(T + q, T + 2 * q, 500, 900, 1200)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.peakKW, 900)
+  assert.equal(r.energy?.peakGrossKW, 1200)
+  assert.equal(r.energy?.shavedKW, 300, '1,200 − 900 — 그 순간 계통에서 덜어낸 몫')
+})
+
+test('깎인 것이 없으면 그 값을 만들지 않는다 — 0 을 성과로 적지 않는다', () => {
+  const r = foldKpi([winNet(T, T + q, 300, 400, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.peakGrossKW, 400)
+  assert.equal(r.energy?.shavedKW, undefined)
+})
+
+test('총부하를 싣지 않은 옛 구간은 그대로 — 순수요와 같다고 단정하지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 900)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.peakKW, 900)
+  assert.equal(r.energy?.peakGrossKW, undefined)
+  assert.equal(r.energy?.shavedKW, undefined)
+})
+
+/*
+ * ── 분기 계량이 있으면 배분하지 않는다 (2026-08-18) ───────────────────────────
+ * 실 게이트웨이는 분기마다 계량기를 보낸다. 그런데 화면은 「나누지 못함」으로 답했다 — 폴드에 가동시간
+ * 배분 경로만 있었기 때문이다. 미러 트윈에는 설비 가동 기록조차 없어(원천이 계량만 준다) 그 경로로는
+ * 분기별 값이 영원히 나오지 않았다.
+ */
+const windowFact = (startMs: number, points: { id: string; kWh: number; root?: boolean }[], meanKW = 400) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(startMs + 900_000).toISOString(),
+  instanceId: 'ems-1',
+  payload: {
+    data: {
+      startMs,
+      endMs: startMs + 900_000,
+      meanKW,
+      maxKW: meanKW,
+      samples: 30,
+      points: points.map(p => ({ id: p.id, kWh: p.kWh, ...(p.root ? { root: true } : {}) }))
+    }
+  }
+})
+
+test('분기별 값이 계량에서 온다 — 근거는 measured, 가동시간 이야기를 하지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T00:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [
+    { id: 'meter-incoming', kWh: 100, root: true },
+    { id: 'meter-a', kWh: 40 },
+    { id: 'meter-b', kWh: 30 }
+  ]) as any], { fromMs: t0, toMs: t0 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const e = r.energy!
+  const byKey = new Map((e.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.kWh, 40)
+  assert.equal(byKey.get('feeder-a')?.basis, 'measured')
+  assert.equal(byKey.get('feeder-a')?.weightKind, undefined, '나누지 않았으니 무엇으로 나눴다고 말하지 않는다')
+  assert.equal(byKey.get('feeder-b')?.kWh, 30)
+})
+
+test('하위 계량이 덮지 않는 나머지를 남긴다 — 어느 분기에 얹지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T01:00:00.000Z')
+  /* 구간 평균 400kW × 0.25h = 100kWh 가 총량이고, 분기 합은 70 이다. */
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 30 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' } })
+  const e = r.energy!
+  assert.equal(Math.round(e.kWh!), 100)
+  assert.equal(Math.round(e.unattributedKWh!), 30)
+  assert.equal(e.unattributedReason, 'not-submetered', '「선언이 없다」가 아니라 「계량이 덮지 않는다」')
+  const sum = (e.byFeeder ?? []).reduce((s, f) => s + f.kWh, 0) + (e.unattributedKWh ?? 0)
+  assert.ok(Math.abs(sum - e.kWh!) < 1e-6, `합이 보존된다(${sum} vs ${e.kWh})`)
+})
+
+test('분기 합이 뿌리를 넘으면 그 사실을 낸다 — 깎아 맞추지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T02:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 90 }, { id: 'meter-b', kWh: 30 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' } })
+  const e = r.energy!
+  assert.equal(Math.round(e.submeterExcessKWh!), 20, '120 − 100')
+  assert.equal(e.byFeeder?.find(f => f.key === 'feeder-a')?.kWh, 90, '계량값은 그대로 남는다')
+})
+
+test('계량 지도가 없으면 예전 배분 경로 그대로 — 거동을 바꾸지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T03:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 40 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { resourceFeeder: { 'press-1': 'feeder-a', 'press-2': 'feeder-b' } })
+  const e = r.energy!
+  /* 선언된 부하가 둘인데 가동 기록이 없으니 나눌 몫이 없다 — 총량은 그대로 남고 이유가 붙는다(예전 거동). */
+  assert.equal(e.unattributedReason, 'no-weights')
+  assert.equal(e.byFeeder, undefined, '계량 경로를 타지 않았다')
+})
+
+test('피크를 만든 분기를 그 순간의 kW 로 답한다 — 전력량 큰 분기와 다를 수 있다', () => {
+  const t0 = Date.parse('2026-08-18T06:00:00.000Z')
+  const t1 = t0 + 900_000
+  /* 두 구간: 앞 구간이 전력량은 크지만(a 가 꾸준히), 피크는 뒤 구간에서 b 가 만든다. */
+  const w0 = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t1).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t0, endMs: t1, meanKW: 400, maxKW: 500, samples: 30,
+      points: [{ id: 'meter-a', kWh: 80 }, { id: 'meter-b', kWh: 20 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 450 }, { id: 'meter-b', kW: 50 }] } }
+  }
+  const w1 = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t1 + 900_000).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t1, endMs: t1 + 900_000, meanKW: 300, maxKW: 900, samples: 30,
+      points: [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 35 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 300 }, { id: 'meter-b', kW: 600 }] } }
+  }
+  const r = foldKpi([w0, w1] as any, { fromMs: t0, toMs: t1 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const byKey = new Map((r.energy?.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.kWh, 120, '전력량은 a 가 크다')
+  /* 피크 값은 **최대수요를 낸 구간 하나**에서 온다 — 두 구간을 섞으면 다른 순간의 값을 더하는 것이다. */
+  assert.equal(byKey.get('feeder-b')?.peakKW, 600, '피크를 만든 것은 b 다')
+  assert.equal(byKey.get('feeder-a')?.peakKW, 300)
+})
+
+test('피크 구간에 표본이 없던 분기는 피크 값을 만들지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T07:00:00.000Z')
+  const w = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t0 + 900_000).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t0, endMs: t0 + 900_000, meanKW: 200, maxKW: 300, samples: 10,
+      points: [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 10 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 300 }] } }
+  }
+  const r = foldKpi([w] as any, { fromMs: t0, toMs: t0 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const byKey = new Map((r.energy?.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.peakKW, 300)
+  assert.equal(byKey.get('feeder-b')?.peakKW, undefined, '그 순간 값을 모르면 만들지 않는다')
+})

package/test/kpi-query-bench.test.ts

@@ -0,0 +1,130 @@
+/*
+ * 구간 성과 질의 비용 측정 — **방송이냐 질의냐를 숫자로 정한다.**
+ *
+ * ── 왜 재는가 (2026-08-06) ─────────────────────────────────────────────────
+ * 성과 카드를 여러 단계(공간·트윈·구역·자리·설비)에 붙이려 한다. 두 방법이 있다.
+ *
+ *  · 방송 — 서버가 주기마다 전 단계를 계산해 밀어 준다. 자리가 트윈당 최대 200개고 지표가 6개라
+ *    태그가 1,200개가 된다. **모델에 카드를 하나도 안 놓아도 계산은 돈다.**
+ *  · 질의 — 카드가 필요할 때 묻는다. **모델에 놓인 카드 수만큼만** 든다. 시각(`toTime`)도 물을 수 있어
+ *    타임라인과 맞고, 공간 단위 합산(여러 트윈을 한 번에 접기)은 질의에만 있다.
+ *
+ * 질의로 정하려면 **한 번의 비용**을 알아야 한다. 카드 20장이 30초마다 물으면 감당되는지가 결정을
+ * 가른다. 짐작하지 않고 잰다.
+ *
+ * 빌드 산출물을 실행한다 — **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { test, before, after } from 'node:test'
+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 = 'kpi-bench'
+const TO = Date.parse('2026-03-10T10:00:00.000Z')
+const WINDOW_MIN = 60
+
+/** 자리 200개 — 실측한 최대 규모(트윈당 자리 최대 200, 평균 19). */
+const LOCATIONS = 200
+/** 창 안의 완료 작업 수 — 한 건이 두 줄(시작·완료)이라 이벤트는 두 배가 된다. */
+const TASK_COUNTS = [500, 2_000, 10_000]
+
+function taskRows(count: number, revBase: number) {
+  const rows: any[] = []
+  for (let i = 0; i < count; i++) {
+    const done = TO - 60_000 - (i % (WINDOW_MIN * 60)) * 1000
+    const started = done - 30_000
+    const at = `loc-${i % LOCATIONS}`
+    rows.push(
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2,
+        eventType: 'task.status',
+        eventTime: new Date(started).toISOString(),
+        payload: { data: { taskId: `t-${i}`, status: 'in-progress', resourceRef: 'fk-1', locationRef: at } }
+      },
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2 + 1,
+        eventType: 'task.status',
+        eventTime: new Date(done).toISOString(),
+        payload: { data: { taskId: `t-${i}`, status: 'completed', resourceRef: 'fk-1', locationRef: at } }
+      }
+    )
+  }
+  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: 'kpi-bench', subdomain: 'kpi-bench' } as any)
+  domainId = d.id
+
+  /* 자리 계층 — 자리 200개를 구역 4개에 나눠 붙인다(구역 단위 접기 비용도 재려면 부모가 있어야 한다). */
+  const locations = Array.from({ length: LOCATIONS }, (_, i) => ({
+    id: `loc-${i}`,
+    type: 'storage',
+    capacity: 10,
+    parentId: `area-${i % 4}`
+  }))
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'wms',
+    realityMode: 'sim-experiment', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
+    purpose: 'operational',
+    status: 'stopped',
+    model: { locations, equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'loc-0' }] }
+  } as any)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+const ms = async (fn: () => Promise<any>) => {
+  const t = process.hrtime.bigint()
+  await fn()
+  return Number(process.hrtime.bigint() - t) / 1e6
+}
+
+test('bench: 구간 성과 폴드 한 번의 비용 vs 창 안의 작업 수', async () => {
+  let seeded = 0
+  for (const count of TASK_COUNTS) {
+    await ds.getRepository(TwinEvent).save(taskRows(count - seeded, seeded * 2 + 1000))
+    seeded = count
+
+    const args = { domainId, instanceId: INSTANCE, toTime: new Date(TO).toISOString(), windowMinutes: WINDOW_MIN }
+    await computeTwinKpi(args) // 워밍업(연결·스키마 캐시)
+
+    const plain = await ms(() => computeTwinKpi(args))
+    const byArea = await ms(() => computeTwinKpi({ ...args, groupBy: 'area' }))
+
+    console.log(`  작업 ${count.toLocaleString()}건(이벤트 ${(count * 2).toLocaleString()}줄) · 자리 ${LOCATIONS}개`)
+    console.log(`    폴드 1회        ${plain.toFixed(1)}ms`)
+    console.log(`    구역별 폴드 1회 ${byArea.toFixed(1)}ms`)
+    console.log(`    카드 20장 동시  ${(plain * 20).toFixed(0)}ms (직렬 상한 — 실제로는 한 번 접어 나눠 쓸 수 있다)`)
+  }
+})