@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/kpi-fold.test.ts

@@ -1,9 +1,9 @@
 /*
- * 업무 KPI 폴드 검증 — 저널을 접어 시간창 지표를 만드는 규칙을 고정한다.
+ * 업무 KPI 폴드 검증 — 저널을 계산해 시간창 지표를 만드는 규칙을 고정한다.
  *
  * 무엇을 지키는가:
  *  ① **성과는 완료 시점으로 센다** — 시작 시점으로 세면 진행 중인 것이 섞여 처리량이 부풀려진다.
- *  ② **셈에서 빠진 것을 밝힌다**(unpaired) — 시작 이벤트를 못 찾은 완료를 조용히 버리면 평균이 거짓이 된다.
+ *  ② **셈에서 빠진 것을 밝힌다**(unpaired) — 시작 이벤트를 못 찾은 완료를 알리지 않고 버리면 평균이 거짓이 된다.
  *  ③ **없는 것을 0 으로 꾸미지 않는다** — 저널이 비었으면 eventsSeen 0 으로 그 사실이 보인다.
  *  ④ 시간축은 eventTime 차분 — sim 클록 오프셋이 있어도 차분은 정확하다.
  */
@@ -82,7 +82,7 @@ test('분위수: p50·p90 을 낸다(작은 표본에서 과장하지 않는다)
   assert.equal(r.workTime.p90Ms, 10000)
 })
 
-test('시작 이벤트를 못 찾은 완료는 unpaired 로 밝힌다 — 평균에서 조용히 빠지지 않게', () => {
+test('시작 이벤트를 못 찾은 완료는 unpaired 로 밝힌다 — 평균에서 오류 없이 빠지지 않게', () => {
   const r = foldKpi([task('t1', 'completed', 30)], WINDOW)
   assert.equal(r.throughput.tasks, 1, '완료는 센다')
   assert.equal(r.leadTime.count, 0, '리드타임은 계산할 수 없다')
@@ -159,7 +159,7 @@ test('오더 완료: 양이 답한다 — 낱말이 진행 중이라 말해도',
 test('오더 완료: 같은 오더를 한 번만 센다 — 폴링 원본이 다시 보내도', () => {
   /*
    * 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수 있다(결함이 아니라 폴링의 성질).
-   * 사건마다 세면 처리량이 조용히 부풀려진다 — 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있었고
+   * 사건마다 세면 처리량이 알리지 않고 부풀려진다 — 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있었고
    * 오더만 없었다.
    */
   const r = foldKpi([order('o1', 'completed', 10), order('o1', 'completed', 20), order('o2', 'completed', 30)], WINDOW)
@@ -233,7 +233,7 @@ test('같은 전이가 두 번 와도 착수는 처음 것, 생성은 마지막
 })
 
 /* ── 구간 쪼개기(추세) ─────────────────────────────────────────────────────
- * 화면의 추세선이 여기서 나온다. 조회는 한 번이고 창만 바꿔 다시 접는다.
+ * 화면의 추세선이 여기서 나온다. 조회는 한 번이고 창만 바꿔 다시 계산한다.
  */
 test('구간 쪼개기: N 등분해 구간별 처리량을 낸다', () => {
   /* 1시간 창을 4등분(15분씩). 각 구간에 한 건씩 완료되게 놓는다. */
@@ -336,7 +336,7 @@ test('축의 합이 전체 처리량과 같다 — 어느 축에서도 건이
   }
 })
 
-test('축의 값이 없던 건은 unknown 으로 모인다 — 조용히 버리지 않는다', () => {
+test('축의 값이 없던 건은 unknown 으로 모인다 — 알리지 않고 버리지 않는다', () => {
   const events = [...three('a', 100, { kind: 'move', resourceRef: 'fk-1' }), ...three('b', 200, { kind: 'move' })]
   const r = foldKpi(events, WINDOW, { groupBy: 'resource' })
   assert.deepEqual(r.groups?.items.map(g => g.key).sort(), ['fk-1', 'unknown'])
@@ -374,7 +374,7 @@ test('구역 축은 노드→구역 지도를 받아야 낸다 — 지도가 없
   assert.deepEqual(mapped.groups?.items.map(g => [g.key, g.tasks]), [['zone-a', 2]], '두 노드가 한 구역으로 모인다')
 })
 
-test('축이 많으면 잘라내고 잘린 축의 수와 그 안의 건수를 함께 알린다 — 조용한 절단 금지', () => {
+test('축이 많으면 잘라내고 잘린 축의 수와 그 안의 건수를 함께 알린다 — 들어온 것이 없는 절단 금지', () => {
   /* 축마다 건수를 다르게 둔다: 축의 수만 알리면 "그 외 20개" 가 20건인지 60건인지 알 수 없다. */
   const events: KpiEvent[] = []
   let t = 0
@@ -403,7 +403,7 @@ test('짝을 못 찾은 건도 축에서 센다 — 건수는 세고 소요만
 })
 
 /* ── 시간 비교 ──────────────────────────────────────────────────────────────
- * "29초" 만으로는 좋아졌는지 나빠졌는지 알 수 없다. 창을 옮겨 한 번 더 접는 규칙을 고정한다.
+ * "29초" 만으로는 좋아졌는지 나빠졌는지 알 수 없다. 창을 옮겨 한 번 더 계산 규칙을 고정한다.
  */
 test('직전 구간: 같은 길이로 바로 앞 — 경계가 맞물린다(겹치거나 벌어지지 않게)', () => {
   const w = shiftWindow(WINDOW.fromMs, WINDOW.toMs, 'previous')
@@ -431,7 +431,7 @@ test('중앙값 차이: 한쪽이 결측이면 차이는 없다 — 0 으로 내
   assert.equal(deltaP50(missing, measured), undefined)
 })
 
-test('비교: 옮긴 창으로 접으면 앞 구간의 성과가 나온다 — 같은 폴드, 창만 다르다', () => {
+test('비교: 옮긴 창으로 계산하면 앞 구간의 성과가 나온다 — 같은 폴드, 창만 다르다', () => {
   /* 현재 구간에 2건, 직전 구간에 1건. */
   const events = [
     ...three('now-1', 100, { kind: 'move' }),
@@ -500,7 +500,7 @@ test('교차: 지금만 있는 축은 isNew — delta 를 건수와 같게 적
   assert.equal(nw.prevTasks, undefined)
 })
 
-test('교차: 사라진 축을 따로 알린다 — 멈춘 구역이 표에서 조용히 빠지지 않게', () => {
+test('교차: 사라진 축을 따로 알린다 — 멈춘 구역이 표에서 오류 없이 빠지지 않게', () => {
   const c = crossGroups([g('pick', 5)], [g('pick', 5), g('putaway', 12)])
   assert.deepEqual(c.disappeared, [{ key: 'putaway', tasks: 12 }])
 })
@@ -547,7 +547,7 @@ test('교대별로 쪼갠다 — 완료 시각에서 계산한다(저널에 없
   assert.equal(r.groups?.items.reduce((s, g) => s + g.tasks, 0), r.throughput.tasks, '축의 합이 전체와 같다')
 })
 
-test('현장의 시각 기준으로 읽는다 — UTC 로 조용히 가정하지 않는다', () => {
+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 })
@@ -630,7 +630,7 @@ test('모르는 지표 이름은 짐작해 매핑하지 않는다', () => {
 /* ── 목표의 범위 (공간 vs 인스턴스) ──────────────────────────────────────────
  *
  * 이 규칙은 원래 DB 접근 뒤에 숨어 있어 **화면을 눌러 봐야만** 확인할 수 있었다. 로그인 뒤 화면을
- * 자동으로 검증할 방법이 없는 프로젝트라 그런 규칙은 조용히 미검증으로 쌓인다 — 그래서 밖으로 뺐다.
+ * 자동으로 검증할 방법이 없는 프로젝트라 그런 규칙은 알리지 않고 미검증으로 쌓인다 — 그래서 밖으로 뺐다.
  */
 const row = (metric: string, target: number, scope: { spaceId?: string; instanceId?: string }) => ({
   metric,
@@ -788,7 +788,7 @@ test('그 창에 완료가 없으면 원단위는 정의되지 않는다 — 전
 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, '조용히 빼면 이 합이 그 창의 전부인 줄 읽는다')
+  assert.equal(r.energy?.skipped, 1, '알리지 않고 빼면 이 합이 그 창의 전부인 줄 읽는다')
 })
 
 test('창에 걸친 구간은 세지 않는다 — 부분을 비례로 자르면 추정이 하나 더 생긴다', () => {
@@ -1134,7 +1134,7 @@ test('피크 구간에 표본이 없던 분기는 피크 값을 만들지 않는
  * ── 완료로 읽지 못한 오더 상태 낱말을 **센다** (2026-08-23) ──────────────────
  *
  * 오더의 상태 어휘는 계약이 도메인에 넘긴 것이라(`picking`·`shipped`·`FINISHED`…) 이 폴드는 「완료로
- * 읽히는 표현」을 동의어 목록으로 받는다. 그 대가는 **목록에 없는 낱말이 조용히 0 으로 세어진다**는 것이다.
+ * 읽히는 표현」을 동의어 목록으로 받는다. 그 대가는 **목록에 없는 낱말이 알리지 않고 0 으로 세어진다**는 것이다.
  *
  * 실제로 그랬다: `finished` 가 빠져 있어 첫 실 시스템의 완료 오더가 전부 0 이었고, 사람이 화면을 보고
  * 의심해서야 드러났다. 목록을 넓히는 것으로는 다음 원본을 막지 못한다 — 그래서 **못 읽은 것을 센다.**
@@ -1174,3 +1174,255 @@ test('상태를 말하지 않은 사건은 여기 오지 않는다 — 그것은
   const r = foldKpi([{ eventType: 'order.status', eventTime: at(10), payload: { data: { orderId: 'o-1' } } }], WINDOW)
   assert.deepEqual(r.orderStatusNotCounted, {})
 })
+
+/* ── 밖에서 마감되어 온 사용 구간과 청구서 (2026-08-29) ────────────────────
+ *
+ * ★ 계량 표본이 오지 않는 현장이 있다. 원본이 「이 구간에 X 썼다」를 이미 마감해 준다.
+ *   그 값을 쓰지 않으면 그 현장의 화면은 영영 빈손이다.
+ *
+ * 두 회계를 **더하지 않는다** — 같은 전기를 두 번 센다.
+ */
+
+const usagePeriod = (kWh: number, fromSec: number, toSec: number, extra: Record<string, unknown> = {}): KpiEvent => ({
+  eventType: 'energy.usage.period',
+  eventTime: at(toSec),
+  payload: { data: { meterId: 'incoming-1', from: at(fromSec), to: at(toSec), kWh, ...extra } }
+})
+
+test('★ 계량 표본이 없어도 사용 구간으로 답한다 — 근거를 밝힌다', () => {
+  const k = foldKpi([usagePeriod(474.48, 0, 1800, { basis: 'provider' }), usagePeriod(471.6, 1800, 3600, { basis: 'provider' })], WINDOW)
+  assert.equal(k.energy?.kWh, 474.48 + 471.6)
+  assert.equal(k.energy?.kWhBasis, 'usage-period')
+  assert.equal(k.energy?.usage?.counted, 2)
+  assert.deepEqual(k.energy?.usage?.byBasis, [{ basis: 'provider', counted: 2 }])
+})
+
+test('창에 걸친 구간은 세지 않는다 — 반만 세면 합이 창을 넘는다', () => {
+  const k = foldKpi([usagePeriod(100, -1800, 1800)], WINDOW)
+  assert.equal(k.energy?.usage, undefined)
+})
+
+test('★ 구간마다 제 단가로 매긴다 — 단일 단가로 접지 않는다', () => {
+  /* 새벽 87.3 · 낮 222.3 — 하나로 접으면 「피크를 깎아 얼마를 아끼나」가 사라진다. */
+  const k = foldKpi(
+    [
+      usagePeriod(100, 0, 1800, { unitPrice: 87.3, currency: 'KRW', basis: 'provider' }),
+      usagePeriod(100, 1800, 3600, { unitPrice: 222.3, currency: 'KRW', basis: 'provider' })
+    ],
+    WINDOW,
+    { tariff: { energyChargePerKWh: 140.2, currency: 'KRW' } } as any
+  )
+  assert.equal(k.energy?.usage?.charge, 100 * 87.3 + 100 * 222.3)
+  assert.equal((k.energy?.cost as any)?.energyCharge, 100 * 87.3 + 100 * 222.3, '구간별 단가가 이긴다')
+  assert.ok(!(k.energy?.cost as any)?.notModeled.includes('tou'))
+})
+
+test('일부만 단가를 실었으면 요금을 만들지 않고 그 수를 낸다', () => {
+  const k = foldKpi(
+    [usagePeriod(100, 0, 1800, { unitPrice: 87.3, currency: 'KRW' }), usagePeriod(100, 1800, 3600)],
+    WINDOW
+  )
+  assert.equal(k.energy?.usage?.charge, undefined, '있는 것만 더하면 그 합이 창의 요금인 척한다')
+  assert.equal(k.energy?.usage?.unpriced, 1)
+})
+
+test('★ 청구서는 사실로 나란히 둔다 — 창이 다르면 견주지 않는다', () => {
+  const bill: KpiEvent = {
+    eventType: 'energy.bill',
+    eventTime: at(3600),
+    payload: { data: { from: at(600), to: at(3000), total: 1_000_000, currency: 'KRW', billingDemandKW: 1650 } }
+  }
+  const k = foldKpi([bill], WINDOW)
+  assert.equal(k.energy?.bill?.total, 1_000_000)
+  assert.equal(k.energy?.bill?.billingDemandKW, 1650)
+  assert.equal(k.energy?.bill?.matchesWindow, false, '한 달 청구서를 하루 창의 값과 빼면 아무것도 뜻하지 않는다')
+  assert.equal(k.energy?.bill?.ourTotalMinusBilled, undefined)
+})
+
+test('★ 창이 청구 주기와 같으면 우리 계산과의 차이를 낸다 — 0 이 아니면 우리가 틀렸다', () => {
+  const bill: KpiEvent = {
+    eventType: 'energy.bill',
+    eventTime: at(3600),
+    payload: { data: { from: at(0), to: at(3600), total: 100_000, currency: 'KRW' } }
+  }
+  const k = foldKpi([bill, usagePeriod(1_000, 0, 3600, { unitPrice: 87.3, currency: 'KRW' })], WINDOW, {
+    tariff: { energyChargePerKWh: 87.3, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.bill?.matchesWindow, true)
+  assert.equal(k.energy?.bill?.diff?.total, 1_000 * 87.3 - 100_000)
+})
+
+test('★ 총액이 없는 청구서도 항목별로 견준다 — 실제 첫 청구서에 기본요금만 있었다', () => {
+  const bill: KpiEvent = {
+    eventType: 'energy.bill',
+    eventTime: at(3600),
+    payload: { data: { from: at(0), to: at(3600), demandCharge: 13_728_000, currency: 'KRW', billingDemandKW: 1650 } }
+  }
+  const k = foldKpi([bill], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1_650, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.bill?.diff?.demandCharge, 0, '요금적용전력으로 매기면 청구서와 같다')
+  assert.equal(k.energy?.bill?.diff?.total, undefined, '한쪽에 없는 항목은 견주지 않는다')
+})
+
+test('요금적용전력을 선언하지 않으면 기본요금이 어긋나는 것이 드러난다', () => {
+  const bill: KpiEvent = {
+    eventType: 'energy.bill',
+    eventTime: at(3600),
+    payload: { data: { from: at(0), to: at(3600), demandCharge: 13_728_000, currency: 'KRW' } }
+  }
+  /* 선언이 없으면 커널은 창의 피크로 조건부 값을 낸다 — 그 차이가 그대로 나온다. */
+  const peakWindow: KpiEvent = {
+    eventType: 'energy.demand.window',
+    eventTime: at(1800),
+    payload: { data: { startMs: T0 + 900_000, endMs: T0 + 1_800_000, maxKW: 600, meanKW: 600, samples: 4 } }
+  }
+  const k = foldKpi([bill, peakWindow], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, currency: 'KRW' }
+  } as any)
+  const d = k.energy?.bill?.diff?.demandCharge
+  assert.ok(d !== undefined && d !== 0, `어긋남이 드러나야 한다: ${d}`)
+})
+
+/* ── 요금적용전력은 청구서가 먼저다 (2026-08-29) ───────────────────────────
+ *
+ * ★ 그 값은 최근 몇 달의 최고 수요로 **매달 다시 정해진다.** 선언에 박아 두면 사람이 매달
+ *   갱신해야 하고, 안 하면 낡은 값으로 기본요금이 조용히 틀린다.
+ */
+
+const billEvent = (fromSec: number, toSec: number, data: Record<string, unknown>): KpiEvent => ({
+  eventType: 'energy.bill',
+  eventTime: at(toSec),
+  payload: { data: { from: at(fromSec), to: at(toSec), currency: 'KRW', ...data } }
+})
+
+test('★ 창을 덮는 청구서가 있으면 그 값으로 매긴다', () => {
+  const k = foldKpi([billEvent(0, 3600, { demandCharge: 1, billingDemandKW: 1650 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1200, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.kW, 1650)
+  assert.equal(k.energy?.billingDemand?.from, 'bill')
+  assert.equal((k.energy?.cost as any)?.demandCharge, 1650 * 8_320, '선언 1200 이 아니라 청구서 1650 으로 매긴다')
+})
+
+test('★ 선언이 청구서와 다르면 낡았다고 말한다 — 감추면 아무도 다시 읽지 않는다', () => {
+  const k = foldKpi([billEvent(0, 3600, { demandCharge: 1, billingDemandKW: 1650 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1200, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.declaredKW, 1200)
+  assert.equal(k.energy?.billingDemand?.stale, true)
+})
+
+test('선언과 청구서가 같으면 낡았다고 하지 않는다', () => {
+  const k = foldKpi([billEvent(0, 3600, { demandCharge: 1, billingDemandKW: 1650 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.stale, undefined)
+})
+
+test('★ 창에 청구서가 없으면 마지막 청구서의 값을 이어 쓴다 — 요금 제도가 그렇게 군다', () => {
+  const k = foldKpi([usagePeriod(100, 0, 3600, { unitPrice: 87.3, currency: 'KRW' })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, currency: 'KRW' },
+    lastBill: { to: at(-86400), billingDemandKW: 1650 }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.kW, 1650)
+  assert.equal(k.energy?.billingDemand?.from, 'carried-forward')
+  assert.equal((k.energy?.cost as any)?.demandBasis, 'billing-demand')
+})
+
+test('청구가 오지 않는 현장은 선언을 쓴다', () => {
+  const k = foldKpi([usagePeriod(100, 0, 3600, { unitPrice: 87.3, currency: 'KRW' })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 900, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.from, 'declaration')
+  assert.equal(k.energy?.billingDemand?.kW, 900)
+  assert.equal(k.energy?.billingDemand?.stale, undefined)
+})
+
+test('셋 다 없으면 이 칸을 만들지 않는다 — 빈 값을 지어내지 않는다', () => {
+  const k = foldKpi([usagePeriod(100, 0, 3600, { unitPrice: 87.3, currency: 'KRW' })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand, undefined)
+})
+
+test('★ 관측한 최고가 청구 기준을 넘으면 얼마나 넘었는지와 언제까지의 값인지를 낸다', () => {
+  /* 기본요금은 이 값으로 다시 정해진다 — 지금 줄여도 되돌아가지 않는다. */
+  const k = foldKpi([usagePeriod(400, 0, 1800, { maxKW: 1200 }), usagePeriod(400, 1800, 3600, { maxKW: 1700 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' }
+  } as any)
+  const e = k.energy?.billingDemand?.exceeded
+  assert.equal(e?.peakKW, 1700)
+  assert.equal(e?.overKW, 50)
+  assert.equal(e?.observedTo, at(3600), '이 최고값이 언제까지의 것인지')
+})
+
+test('넘지 않으면 그 칸을 만들지 않는다', () => {
+  const k = foldKpi([usagePeriod(400, 0, 3600, { maxKW: 1200 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.exceeded, undefined)
+})
+
+test('청구서가 말한 기준으로 넘었는지 본다 — 선언이 아니다', () => {
+  const k = foldKpi([usagePeriod(400, 0, 3600, { maxKW: 1300 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' },
+    lastBill: { to: at(-86400), billingDemandKW: 1200 }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.kW, 1200)
+  assert.equal(k.energy?.billingDemand?.exceeded?.overKW, 100)
+})
+
+/* ── 이용률 (2026-08-30) ───────────────────────────────────────────────────
+ *
+ * ★ 분모가 어느 정격인지가 값의 뜻을 바꾼다. 붙어 있는 원본은 직류로 나눠 2.2% 를 보여 주는데,
+ *   교류로 나누면 4.08% 다. 같은 발전소를 두 화면에서 보는 사람이 두 배 다른 수를 본다.
+ *
+ * 그래서 커널은 교류를 먼저 쓰되(계통으로 나가는 양은 교류 정격을 넘을 수 없다) **어느 쪽으로
+ * 나눴는지를 값과 함께 낸다.**
+ */
+
+const generationPeriod = (kWh: number, fromSec: number, toSec: number): KpiEvent => ({
+  eventType: 'energy.generation.period',
+  eventTime: at(toSec),
+  payload: {
+    data: { equipmentId: 'inv-1', kWh, periodStart: at(fromSec), periodEnd: at(toSec), observedFrom: at(fromSec), observedTo: at(toSec) }
+  }
+})
+
+test('★ 이용률은 만든 양 ÷ (정격 × 그 기간의 시간)', () => {
+  /* 한 시간에 63.8kWh · 정격 127.6kW → 50% */
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW, {
+    generationRated: { kW: 127.6, basis: 'ac', from: 'location' }
+  } as any)
+  const cf = k.energy?.generated?.capacityFactor
+  assert.equal(cf?.value, 0.5)
+  assert.equal(cf?.ratedKW, 127.6)
+  assert.equal(cf?.hours, 1)
+})
+
+test('★ 어느 정격으로 나눴는지 함께 낸다 — 두 화면의 수가 달라도 이유를 말할 수 있게', () => {
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW, {
+    generationRated: { kW: 234.35, basis: 'dc', from: 'location' }
+  } as any)
+  assert.equal(k.energy?.generated?.capacityFactor?.basis, 'dc')
+  assert.equal(k.energy?.generated?.capacityFactor?.from, 'location')
+})
+
+test('★ 창 길이가 아니라 센 기간들의 길이로 나눈다', () => {
+  /*
+   * 한 시간짜리 기간 하나만 센 창에서 창 길이(1시간)로 나누는 것과 같지만, 기간이 창보다 짧으면
+   * 달라진다. 창 길이로 나누면 그 기간이 창 전체에 걸쳐 있었던 것처럼 작아진다.
+   */
+  const k = foldKpi([generationPeriod(63.8, 0, 1800)], WINDOW, {
+    generationRated: { kW: 127.6, basis: 'ac', from: 'location' }
+  } as any)
+  assert.equal(k.energy?.generated?.capacityFactor?.hours, 0.5)
+  assert.equal(k.energy?.generated?.capacityFactor?.value, 1, '30분에 정격만큼 만들었으면 100%다')
+})
+
+test('정격이 없으면 이용률을 내지 않는다 — 0 이나 짐작을 만들지 않는다', () => {
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW)
+  assert.equal(k.energy?.generated?.capacityFactor, undefined)
+  assert.equal(k.energy?.generated?.kWh, 63.8, '발전량 자체는 그대로 낸다')
+})

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

@@ -7,7 +7,7 @@
  *  · 브로드캐스팅 — 서버가 주기마다 전 단계를 계산해 밀어 준다. 자리가 트윈당 최대 200개고 지표가 6개라
  *    태그가 1,200개가 된다. **모델에 카드를 하나도 안 놓아도 계산은 돈다.**
  *  · 질의 — 카드가 필요할 때 묻는다. **모델에 놓인 카드 수만큼만** 든다. 시각(`toTime`)도 물을 수 있어
- *    타임라인과 맞고, 공간 단위 합산(여러 트윈을 한 번에 접기)은 질의에만 있다.
+ *    타임라인과 맞고, 공간 단위 합산(여러 트윈을 한 번에 계산)은 질의에만 있다.
  *
  * 질의로 정하려면 **한 번의 비용**을 알아야 한다. 카드 20장이 30초마다 물으면 감당되는지가 결정을
  * 가른다. 짐작하지 않고 잰다.
@@ -82,7 +82,7 @@ before(async () => {
   const d = await ds.getRepository(Domain).save({ name: 'kpi-bench', subdomain: 'kpi-bench' } as any)
   domainId = d.id
 
-  /* 자리 계층 — 자리 200개를 구역 4개에 나눠 붙인다(구역 단위 접기 비용도 재려면 부모가 있어야 한다). */
+  /* 자리 계층 — 자리 200개를 구역 4개에 나눠 붙인다(구역 단위 계산 비용도 재려면 부모가 있어야 한다). */
   const locations = Array.from({ length: LOCATIONS }, (_, i) => ({
     id: `loc-${i}`,
     type: 'storage',
@@ -125,6 +125,6 @@ test('bench: 구간 성과 폴드 한 번의 비용 vs 창 안의 작업 수', a
     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 (직렬 상한 — 실제로는 한 번 접어 나눠 쓸 수 있다)`)
+    console.log(`    카드 20장 동시  ${(plain * 20).toFixed(0)}ms (직렬 상한 — 실제로는 한 번 계산해 나눠 쓸 수 있다)`)
   }
 })

package/test/live-cursor-wiring.test.ts

@@ -1,7 +1,7 @@
 /*
  * ★ 읽기 커서는 **부르는 쪽이 자리를 가리켜야** 이어진다 — 커넥터는 그 이름을 알 수 없다.
  *
- * ── 무엇이 조용히 끊겨 있었나 (2026-08-23) ──────────────────────────────────
+ * ── 무엇이 알리지 않고 끊겨 있었나 (2026-08-23) ──────────────────────────────────
  * 커서를 저장할 컬럼과 계약을 만들고 배선까지 했는데, **한 번도 저장되지 않았다.** 저장할 자리를
  * `cfg`·`site` 에서 찾으려 했기 때문이다.
  *
@@ -12,7 +12,7 @@
  * 원본은 그것을 모른다. 커넥터가 채울 수 없는 값을 커넥터에서 읽으려 한 것이 잘못이었다.
  *
  * 그리고 그 실패는 **로그로는 말했다** — 「this feed does not say which reference it reads from」.
- * 그 한 줄로 다른 레인이 바로 짚었다(조용히 넘기지 않은 것이 값을 했다). 그러나 로그는 사람이 볼 때만
+ * 그 한 줄로 다른 레인이 바로 짚었다(알리지 않고 넘기지 않은 것이 값을 했다). 그러나 로그는 사람이 볼 때만
  * 값이 있다. 배선이 다시 끊기면 이 시험이 먼저 말한다.
  *
  * ── 왜 「늘었나」로 확인하면 안 되나 ────────────────────────────────────────
@@ -44,10 +44,10 @@ test('커서를 저장할 자리는 부르는 쪽이 가리킨다 — cfg·site
   assert.match(code, /startReferenceLiveFeed/, '대상 함수가 남아 있다')
 })
 
-test('모든 호출처가 그 이름을 넘긴다 — 한 곳만 빠져도 그 경로는 조용히 창이 미끄러진다', () => {
+test('모든 호출처가 그 이름을 넘긴다 — 한 곳만 빠져도 그 경로는 알리지 않고 창이 미끄러진다', () => {
   /*
    * 호출처가 둘이고 **둘 다** `TwinReference` 를 들고 있다(부팅 재개 · 인제스트 직후 기동).
-   * 하나만 넘기면 그 경로로 세워진 트윈만 커서를 잃고, 그 차이는 오류 없이 조용하다.
+   * 하나만 넘기면 그 경로로 세워진 트윈만 커서를 잃고, 그 차이는 오류 없이 들어온 것이 없다.
    */
   const calls = [...codeOf(LIVE).matchAll(/startReferenceLiveFeed\(([^)]*)\)/g)].map(m => m[1])
   const resolverCalls = [...codeOf(RESOLVER).matchAll(/startReferenceLiveFeed\([\s\S]{0,200}?\)/g)].map(m => m[0])
@@ -58,7 +58,7 @@ test('모든 호출처가 그 이름을 넘긴다 — 한 곳만 빠져도 그
   }
 })
 
-test('이름이 없으면 조용히 돌지 않는다 — 말한다', () => {
+test('이름이 없으면 알리지 않고 돌지 않는다 — 말한다', () => {
   /*
    * 커서 없이 도는 것은 「창이 매번 미끄러진다」는 뜻이고, 그 손실은 오류 없이 사라진다. 그래서 그
    * 사실을 로그로 말한다 — 실제로 그 한 줄이 이 결함을 찾아냈다.
@@ -82,6 +82,6 @@ test('커서는 레퍼런스의 것이다 — 인스턴스마다 두지 않는
 })
 
 test('저장 실패를 삼키지 않는다', () => {
-  /* 조용히 실패하면 다음 재기동에서 창이 다시 미끄러지고, 이 컬럼을 만든 이유가 사라진다. */
+  /* 오류 없이 실패하면 다음 재기동에서 창이 다시 미끄러지고, 이 컬럼을 만든 이유가 사라진다. */
   assert.match(codeOf(LIVE), /live cursor not saved/, '저장 실패를 말한다')
 })

package/test/live-kernel-facts.test.ts

@@ -65,7 +65,7 @@ test('커널이 낸 사실도 브로드캐스팅을 예약한다 — 피크·마
 
 /*
  * ── 구조 전환도 브로드캐스팅한다 (2026-08-18) ───────────────────────────────────────
- * 화면이 보는 것 상당수가 구조에서 파생된다(계약 대비 판정·주목 신호·자리 색). 구조 전환이 조용히
+ * 화면이 보는 것 상당수가 구조에서 파생된다(계약 대비 판정·주목 신호·자리 색). 구조 전환이 알리지 않고
  * 끝나면 지도 레일은 다음 계측 표본이 올 때까지 옛 화면을 들고 있고, 헤더 배지는 폴링으로 먼저 알아
  * 「배지엔 있고 목록엔 없는」 어긋난 화면이 된다(실화면에서 봤다).
  */
@@ -101,18 +101,18 @@ test('과거 화면의 「지금」은 잘라 낸 뒤의 마지막 사실이다
   const body = methodOf('recover')
   /* 예전에는 전량(rows)의 마지막 시각을 썼다 — 물어본 시점보다 뒤의 이벤트라 과거 화면이 미래를
      기준으로 「늦었다」를 판정할 수 있었다. 이제 rows 는 이미 잘린 것이다. */
-  assert.match(body, /const wanted = rows/, '자른 것과 접는 것이 같아야 한다')
+  assert.match(body, /const wanted = rows/, '자른 것과 계산하는 것이 같아야 한다')
 })
 
 /*
- * ── 재개점에서 이어 접는다 (2026-08-18) ──────────────────────────────────────
- * 접은 결과는 이미 남기고 있었지만, 그 지점의 **재개점**(리듀서 내부 상태 전부 + 가동 누적기)이 없어서
- * 이벤트가 하나만 늘어도 0부터 다시 접어야 했다. 동치는 커널 시험이 증명한다(0부터 == 재개점 + 꼬리).
- * 여기서는 **호스트가 그 씨앗을 실제로 쓰는지**를 지킨다 — 배선이 사라지면 지름길은 조용히 사라진다.
+ * ── 재개점에서 이어서 계산한다 (2026-08-18) ──────────────────────────────────────
+ * 계산한 결과는 이미 남기고 있었지만, 그 지점의 **재개점**(리듀서 내부 상태 전부 + 가동 누적기)이 없어서
+ * 이벤트가 하나만 늘어도 0부터 다시 계산해야 했다. 동치는 커널 시험이 증명한다(0부터 == 재개점 + 꼬리).
+ * 여기서는 **호스트가 그 씨앗을 실제로 쓰는지**를 지킨다 — 배선이 사라지면 지름길은 오류 없이 사라진다.
  */
 test('폴드가 재개점을 쓰고, 새 재개점을 함께 남긴다', () => {
   const body = methodOf('recover')
-  assert.match(body, /replayFrom\(model, resume\.fold\.reducer/, '씨앗이 있으면 꼬리만 접는다')
+  assert.match(body, /replayFrom\(model, resume\.fold\.reducer/, '씨앗이 있으면 꼬리만 계산한다')
   assert.match(body, /revision: MoreThan\(from\)/, '읽는 것도 그 뒤만')
   assert.match(body, /oee\.restore\(resume\.fold\.oee\)/, '가동 누적기도 이어받는다(없으면 가용률이 작아진다)')
   assert.match(body, /replayWithCheckpoint\(/, '씨앗이 없을 때도 새 재개점을 만든다')
@@ -122,7 +122,7 @@ test('폴드가 재개점을 쓰고, 새 재개점을 함께 남긴다', () => {
 test('씨앗을 좁게 쓴다 — 캐시가 사실을 이기지 않는다', () => {
   const body = methodOf('recover')
   /* 지금을 물었을 때만·구조가 그대로일 때만. 시간여행은 목표 이전 재개점이 필요하고(사슬은 다음 단계),
-     구조가 바뀌면 그 경계에서 갈라 접어야 한다. */
+     구조가 바뀌면 그 경계에서 갈라 계산해야 한다. */
   assert.match(body, /asOfNowRead && tip && cachedForResume && cachedForResume\.fold/, '지금 읽기에만 쓴다')
   assert.match(body, /\(cachedForResume\.structureRev \?\? null\) === tip\.structureRev/, '구조가 같을 때만 쓴다')
   assert.match(body, /segments\.length <= 1/, '구조가 갈린 폴드에는 쓰지 않는다')
@@ -131,10 +131,10 @@ test('씨앗을 좁게 쓴다 — 캐시가 사실을 이기지 않는다', () =
 /*
  * ── 재개점 **사슬** (2026-08-18) ─────────────────────────────────────────────
  * 최신 재개점 하나로는 과거를 도울 수 없다 — 그것은 언제나 목표보다 뒤에 있다. 그래서 지점을 여러 개
- * 남기고, 과거를 물으면 **목표 직전** 지점에서 접는다. 지점은 각각 상태 전체를 들고 있어 무겁기 때문에
- * 눈금(리비전 간격)을 넘을 때만 남기고 최근 몇 개만 든다 — 더 과거는 0부터 접는다(알려진 한계).
+ * 남기고, 과거를 물으면 **목표 직전** 지점에서 계산한다. 지점은 각각 상태 전체를 들고 있어 무겁기 때문에
+ * 눈금(리비전 간격)을 넘을 때만 남기고 최근 몇 개만 든다 — 더 과거는 0부터 계산한다(알려진 한계).
  */
-test('과거 읽기는 목표 직전 지점에서 접는다 — 사슬을 쓴다', () => {
+test('과거 읽기는 목표 직전 지점에서 계산한다 — 사슬을 쓴다', () => {
   const body = methodOf('recover')
   assert.match(body, /this\.chainSeedFor\(domainId, instanceId, \{/, '과거 씨앗을 사슬에서 고른다')
   assert.match(body, /structureCount <= 1/, '구조가 갈린 트윈에서는 쓰지 않는다')

package/test/live-mirror-parity.test.ts

@@ -11,7 +11,9 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { WmsKernel, StateProjector, deriveAttentions, computeOee } from '@operato/twin-kernel'
+import { WmsKernel, StateProjector, deriveAttentions } from '@operato/twin-kernel'
+/* OEE 공식은 계약에 있다 — 시뮬·미러·MES 셋이 같은 것을 부른다. */
+import { computeOee } from '@operato/ops-contract'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
 import { buildEntityDeltas } from '../shared/entity-delta.ts'
 import { withLiveAttentions } from '../server/engine/live-attentions.ts'
@@ -209,12 +211,13 @@ test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE
    * 없앴다. 이제 창을 모르면 잰 시간이 없으므로, 재생산에는 창이 함께 와야 한다. 라이브 공급자가
    * 실제로 하는 일이 그것이다(누적기는 첫 이벤트 시각을 창으로 낸다).
    */
-  const planned = o.runMs + o.setupMs + o.downMs + o.idleMs
+  const planned = o.runMs + o.setupMs + o.downMs + o.delayMs
   const derived = computeOee(
     { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, scrapCount: o.scrapCount, metricsSinceMs: 0 },
     planned
   )
-  const near = (a: number, b: number) => Math.abs(a - b) < 1e-6
+  /* 세 비율은 근거가 없으면 없다 — 양쪽 다 없는 것도 재생산이다(계약 0.5.0). */
+  const near = (a?: number, b?: number) => (a == null && b == null) || (a != null && b != null && Math.abs(a - b) < 1e-6)
   assert.ok(near(derived.availability, o.availability), `availability 재생산 (${derived.availability} vs ${o.availability})`)
   assert.ok(near(derived.performance, o.performance), 'performance 재생산')
   assert.ok(near(derived.quality, o.quality), 'quality 재생산')
@@ -247,7 +250,7 @@ test('★ withLiveAttentions 는 채널을 하나도 떨어뜨리지 않는다(
 
 /*
  * ── 되짚은 상태에도 신호가 있어야 한다 (2026-08-05) ────────────────────────
- * 라이브·시뮬은 커널이 신호를 스스로 내지만, 저널을 접는 경로는 프로젝터 상태만 낸다 — 신호 키가
+ * 라이브·시뮬은 커널이 신호를 스스로 내지만, 저널을 계산하는 경로는 프로젝터 상태만 낸다 — 신호 키가
  * 아예 없었다. 지도는 `snap.attentions` 를 읽으므로 **과거를 되짚으면 주의 레일이 텅 비었고**,
  * 기동돼 있지 않은 트윈을 보는 화면도 같았다. 실 저널로 재 보니 `rosarito-wms` 는 246건이 비어 있었다.
  *
@@ -260,7 +263,7 @@ test('★ 프로젝터 폴드 상태에는 신호 키가 없다 — 보강이
   const proj = new StateProjector(model)
   for (const env of events) proj.apply(env)
   const raw: any = proj.snapshot()
-  assert.equal(raw.attentions, undefined, '접은 상태는 신호를 스스로 내지 않는다(커널이 아니다)')
+  assert.equal(raw.attentions, undefined, '계산한 상태는 신호를 스스로 내지 않는다(커널이 아니다)')
 })
 
 test('★ 보강하면 다시 계산한 상태에도 신호가 있다 — 지도의 주의 레일이 비지 않게', () => {
@@ -274,6 +277,6 @@ test('★ 보강하면 다시 계산한 상태에도 신호가 있다 — 지도
     tasks: []
   }
   const out = withLiveAttentions(st)
-  assert.ok((out.attentions ?? []).length > 0, '접은 상태에서도 규칙이 신호를 낸다')
+  assert.ok((out.attentions ?? []).length > 0, '계산한 상태에서도 규칙이 신호를 낸다')
   assert.equal(out.attentions![0].kind, 'bottleneck')
 })

package/test/load-meter.test.ts

@@ -84,7 +84,7 @@ test('경고는 쿨다운을 둔다 — 느린 트윈이 매 틱 경고하면
   const slow = 900
 
   assert.equal(judgeCycle(m, slow, TICK, 1000).warn, true, '처음엔 말한다')
-  assert.equal(judgeCycle(m, slow, TICK, 2000).warn, false, '쿨다운 안에는 조용히')
+  assert.equal(judgeCycle(m, slow, TICK, 2000).warn, false, '쿨다운 안에는 알리지 않고')
   assert.equal(judgeCycle(m, slow, TICK, 1000 + WARN_COOLDOWN_MS).warn, true, '쿨다운이 지나면 다시')
 
   assert.equal(m.overBudget, 3, '말하지 않아도 세기는 한다')