@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/engine/kpi-fold.ts

@@ -25,7 +25,19 @@
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
  * 이 파일은 이제 "접힌 기록 → 창 지표" 만 한다.
  */
-import { foldTaskRecords, activeShiftAt, type TaskFacets, type WorkCalendarEntry } from '@operato/twin-kernel'
+import {
+  ENERGY_EVENT,
+  attributeEnergy,
+  electricityCost,
+  energyIntensity,
+  energyOfWindows,
+  foldTaskRecords,
+  activeShiftAt,
+  type ElectricityCost,
+  type TariffDeclaration,
+  type TaskFacets,
+  type WorkCalendarEntry
+} from '@operato/twin-kernel'
 
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
@@ -83,6 +95,113 @@ export interface KpiResult {
   window: { fromMs: number; toMs: number }
   /** 창 안에 **완료된** 건수 — 성과는 완료 시점으로 센다(시작 시점으로 세면 진행 중인 것이 섞인다). */
   throughput: { tasks: number; orders: number }
+  /**
+   * 에너지 — **이 창의 전력량과 원단위.** 에너지 트윈이 없으면 `undefined`(0 이 아니다).
+   *
+   * ── 왜 KPI 폴드 안에 있나 (2026-08-14, §10 7단계) ─────────────────────────
+   * 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서 나눈 값이다. 질의를 따로 두면 두 창을 맞추는
+   * 일이 소비처의 몫이 되고, 어긋난 두 사실을 나눈 숫자는 아무것도 뜻하지 않는다(커널의 규칙이 그것을
+   * 거절한다). 같은 폴드 안에 두면 창이 하나뿐이라 어긋날 수 없다.
+   *
+   * 분자는 **저널의 구간 마감 사건**에서 온다(`energy.demand.window`) — 커널 상태가 아니라 저널이므로
+   * 멈춘 트윈·과거 구간에도 답할 수 있다.
+   */
+  energy?: {
+    /** 이 창의 전력량. 셀 수 있는 구간이 없으면 `undefined`. */
+    kWh?: number
+    /**
+     * 이 창의 **최대수요**(kW)와 그것이 난 구간의 시작.
+     *
+     * 전력량과 다른 질문이다: 전력량은 요금의 사용량 부분이고, 최대수요는 **기본요금**과 계약 위반을
+     * 정한다. 평균으로 갈음할 수 없어서 커널이 구간의 최대들 중 가장 큰 값을 따로 낸다.
+     */
+    peakKW?: number
+    peakStartMs?: number
+    /**
+     * 그 피크 구간에서 **설비가 끌어당긴** 최대(발전·방전 차감 전)와 그 차이(깎인 양).
+     *
+     * 요금은 계통 수요(`peakKW`)로 매겨지지만, 「무엇이 그 수요를 만들었나」와 「무엇이 덜어냈나」는
+     * 이 두 수의 간격이 답한다. 발전·축전을 선언하지 않은 현장에서는 없다(차감할 것이 없다).
+     */
+    peakGrossKW?: number
+    shavedKW?: number
+    /** 파생의 근거 — 구간 평균부하 × 길이(`mean-kw`). */
+    basis: string
+    /** 센 구간 수 · 못 센 구간 수(계측이 끊긴 구간) — 조용히 자르지 않는다. */
+    counted: number
+    skipped: number
+    /** 완료 오더당 전력량 — 답할 수 없으면 `null` 과 이유. */
+    intensity: { value: number | null; unit?: string; reason?: string }
+    /**
+     * 배전 계통의 **자리별 몫** — 「이 분기가 얼마 썼나」.
+     *
+     * ── 이것은 측정이 아니라 배분이다 ──────────────────────────────────────
+     * 저널에 있는 에너지 사실은 **현장 총량 한 줄**이다(뿌리 계량기 합). 계량기별 구간 사실이 없으므로
+     * 자리별 몫은 **나눈 것**이고, 무엇으로 나눴는지(`weightKind`)를 값과 함께 낸다. 근거를 감추면
+     * 나눈 숫자가 잰 숫자와 같은 무게로 읽힌다 — CBAM·ESG 보고에서 첫 질문에 깨지는 지점이다.
+     *
+     * 가중치는 **작업 가동시간**이다. 정격(kW)으로 나누지 않는다: 시뮬 트윈의 총부하가 정격의 합으로
+     * 파생되므로, 그 총량을 다시 정격으로 나누면 넣은 값이 그대로 나오는 동어반복이 된다.
+     *
+     * 그래서 이 값에는 **가정이 하나 실려 있다**: 전기가 가동시간에 비례한다. 공조·조명처럼 공정에
+     * 붙지 않는 부하도 그 비율에 섞인다 — 화면이 그 문장을 함께 말해야 한다.
+     */
+    byFeeder?: {
+      /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(조용히 버리지 않는다). */
+      key: string
+      kWh: number
+      /**
+       * 이 몫의 근거 — **커널이 정한다.**
+       *
+       * 선언된 부하가 여럿이면 배분(`apportioned`)이다. 선언된 부하가 **하나뿐인** 현장에서는 커널이
+       * 「그 계량기는 그것만 잰다」고 읽어 `measured` 를 낸다 — 모델이 그렇게 말했으므로 그것도 사실이다.
+       * 우리가 어느 쪽으로도 낙인찍지 않는다.
+       */
+      basis: 'apportioned' | 'measured'
+      /**
+       * 무엇으로 나눴나 — **배분일 때만** 있다.
+       *
+       * 분기마다 계량기가 있는 현장에서는 나누지 않는다(그 값이 곧 계량이다). 그때 이 칸을
+       * `runtimeMs` 로 채우면 「가동시간으로 나눴다」는 없는 사실을 말하게 된다.
+       */
+      weightKind?: 'runtimeMs'
+      /** 이 자리의 몫이 전체의 얼마였나 — 배분일 때만. */
+      weightShare?: number
+      /**
+       * **피크가 찍힌 순간** 이 분기가 얼마였나(kW) — 요금이 걸린 수다.
+       *
+       * 창의 평균이나 합이 아니다: 최대수요를 낸 구간의 그 순간 값이다(다른 순간을 섞으면 「어느 분기를
+       * 깎아야 피크가 내려가나」의 답이 흐려진다). 그 구간에 이 분기의 표본이 없었으면 **없다**.
+       */
+      peakKW?: number
+    }[]
+    /**
+     * 나누지 못한 양과 그 이유 — **조용히 0 으로 만들지 않는다.**
+     * `no-weights` = 그 창에 돌아간 자원이 없다(가동시간이 전부 0). 그러면 총량은 그대로 남는다.
+     */
+    unattributedKWh?: number
+    /**
+     * 왜 나누지 못했나(커널 코드) — `no-weights`(가동시간이 전부 0) · `no-consumers`(덮는 대상 미선언) ·
+     * `not-submetered`(뿌리에서 재었으나 하위 계량이 덮지 않는 부분 — 결손이 아니라 계량 범위의 사실).
+     */
+    unattributedReason?: string
+    /**
+     * 분기 계량의 합이 뿌리 계량보다 **큰** 양 — 두 계량기의 회계가 다르다는 사실이다.
+     *
+     * 값을 깎아 맞추지 않는다: 그것은 계량을 우리가 고쳐 쓰는 일이고, 어느 쪽이 맞는지는 현장이 안다.
+     */
+    submeterExcessKWh?: number
+    /**
+     * 배분에서 **빠진 자원 수** — 그 창에 가동 기록이 없는 설비다. 0kWh 를 주지 않는 대신 몇 대가
+     * 빠졌는지 센다(대기전력이 있는 설비에서 0 은 곧 거짓이다).
+     */
+    excludedResources?: number
+    /**
+     * 이 창의 전기요금 — **청구서가 아니다.** 계산과 그 한계(TOU·래칫·최소청구액 미모델)는 커널
+     * (`electricityCost`)이 갖고 여기서는 나른다. 단가가 없으면 `reason: 'no-tariff'` 로 온다.
+     */
+    cost?: ElectricityCost
+  }
   /** 리드타임 — 생성(created)에서 완료까지. 사용자가 체감하는 소요 시간. */
   leadTime: DurationStats
   /** 작업시간 — 착수(in-progress)에서 완료까지. 대기를 뺀 실작업. */
@@ -114,6 +233,188 @@ export interface KpiResult {
   groups?: { by: KpiGroupBy; items: KpiGroup[]; truncated?: number; truncatedTasks?: number }
 }
 
+/**
+ * 창의 전력량을 **배전 계통의 자리별로 나눈다** — 근거를 함께.
+ *
+ * ── 왜 커널 함수를 쓰나 ─────────────────────────────────────────────────────
+ * 「나눌 근거가 없으면 나누지 않는다」·「합은 보존된다」·「몫이 0 이면 0kWh 를 주지 않는다」는 규칙이
+ * 커널의 `attributeEnergy` 에 이미 있다. 여기서 다시 쓰면 두 벌이 되고, 그때부터 두 화면이 다른 합을
+ * 말한다. 이 함수가 하는 일은 **재료를 모아 넘기고 답을 자리별로 묶는 것**뿐이다.
+ *
+ * ── 가중치는 가동시간이다 ───────────────────────────────────────────────────
+ * 정격(kW)으로 나누지 않는다: 시뮬 트윈의 총부하가 정격의 합에서 파생되므로 그 총량을 다시 정격으로
+ * 나누면 넣은 값이 그대로 나온다(새 정보 0의 동어반복). 가동시간은 **저널이 관측한 사실**이다.
+ *
+ * 자리를 모르는 자원은 `unknown` 으로 모인다 — 빼면 합이 줄고, 아무 자리에 넣으면 거짓이 된다.
+ */
+function feederShares(
+  kWh: number | undefined,
+  utilization: { resourceId: string; busyMs: number }[],
+  resourceFeeder?: Record<string, string>
+): Partial<NonNullable<KpiResult['energy']>> {
+  /* 선언이 없으면 분해하지 않는다 — 자리를 모르는 채 나눈 숫자는 아무 것의 몫도 아니다. */
+  if (!resourceFeeder || !Object.keys(resourceFeeder).length) return {}
+  if (kWh === undefined || !(kWh > 0)) return {}
+
+  /*
+   * ── 풀이 **무엇을 덮는지 사실대로** 말한다 (2026-08-17) ────────────────────
+   *
+   * 처음에는 「그 창에 돌아간 자원」만 덮는다고 넘겼다. 그러자 돌아간 자원이 하나인 창에서 커널이
+   * 그것을 **`measured`(전용 계량)** 로 판정했다 — 커널의 규칙은 옳다(「덮는 소비처가 하나면 그
+   * 계량기는 그것만 잰다는 선언이다」). 틀린 것은 내 선언이었다: 현장 계량기는 돌아간 것만 재지 않는다.
+   *
+   * 그래서 **선언된 부하 전부**를 덮는다고 말한다(`resourceFeeder` 의 키가 곧 그 선언이다).
+   * 그러면 그 창에 돌지 않은 설비는 몫 0 으로 **배분에서 빠지고 그 수가 보고된다** — 0kWh 를 주는
+   * 대신 「이 설비는 이 창에 가동 기록이 없다」를 말하는 쪽이다.
+   */
+  /*
+   * 덮는 대상은 **선언된 부하 ∪ 그 창에 돌아간 자원**이다.
+   *
+   * 선언만 쓰면, 돌았는데 전기 계통에 선언되지 않은 설비의 몫이 나머지 설비에 얹힌다 — 그 설비가
+   * 안 쓴 전기를 쓴 것으로 만든다. 돌아간 것만 쓰면, 선언됐지만 쉰 설비가 사라져 「이 창에 안 돌았다」를
+   * 말할 수 없다. 둘을 합해야 두 사실이 다 남는다(자리를 모르는 몫은 `unknown` 으로 모인다).
+   */
+  const busyOf = new Map(utilization.map(u => [u.resourceId, u.busyMs]))
+  const ids = new Set<string>([...Object.keys(resourceFeeder), ...busyOf.keys()])
+  const consumers = [...ids].map(id => ({ id, weight: busyOf.get(id) ?? 0 }))
+  if (!consumers.length) return {}
+
+  const r = attributeEnergy({
+    pools: [{ meterId: 'site', kWh, consumerIds: consumers.map(c => c.id) }],
+    consumers,
+    weightKind: 'runtimeMs'
+  })
+
+  const byKey = new Map<string, { kWh: number; weightShare: number; apportioned: boolean }>()
+  for (const sh of r.shares) {
+    /* 자리를 모르면 `unknown` — 그 몫이 있다는 사실은 남기고, 어디의 것인지는 지어내지 않는다. */
+    const key = resourceFeeder[sh.consumerId] ?? 'unknown'
+    const cur = byKey.get(key) ?? { kWh: 0, weightShare: 0, apportioned: false }
+    cur.kWh += sh.kWh
+    cur.weightShare += sh.weightShare ?? 0
+    /* **근거는 커널이 정한다.** 여기서 낙인찍으면 커널이 「쟀다」고 한 것을 「나눴다」고 바꿔 말하거나
+       그 반대가 된다. 섞이면 약한 쪽(배분)으로 적는다 — 강한 주장을 올려 잡지 않는다. */
+    if (sh.basis === 'apportioned') cur.apportioned = true
+    byKey.set(key, cur)
+  }
+
+  const byFeeder = [...byKey.entries()]
+    .map(([key, v]) => ({
+      key,
+      kWh: v.kWh,
+      basis: (v.apportioned ? 'apportioned' : 'measured') as 'apportioned' | 'measured',
+      weightKind: 'runtimeMs' as const,
+      weightShare: v.weightShare
+    }))
+    .sort((a, b) => b.kWh - a.kWh)
+
+  const un = r.unattributed.reduce((sum, u) => sum + u.kWh, 0)
+  return {
+    ...(byFeeder.length ? { byFeeder } : {}),
+    ...(un > 0 ? { unattributedKWh: un, unattributedReason: r.unattributed[0]?.reason } : {}),
+    ...(r.excluded.length ? { excludedResources: r.excluded.length } : {})
+  }
+}
+
+/**
+ * 분기별 전력량을 **계량으로** 읽는다 — 계량이 있으면 배분하지 않는다.
+ *
+ * ── 왜 필요했나 (2026-08-18) ────────────────────────────────────────────────
+ * 실 게이트웨이는 분기마다 계량기를 보낸다. 그런데 화면은 「나누지 못함」으로 답하고 있었다 — 여기에
+ * 가동시간 배분 경로만 있었기 때문이다. 계량이 있는데 배분으로 말하면 **근거를 실제보다 약하게** 보고하는
+ * 것이고, 그 위에 세운 SEU 판단이 무거운 값을 놓친다. 미러 트윈에는 설비 가동 기록조차 없어서
+ * (원천이 계량만 준다) 그 경로로는 분기별 값이 영원히 나오지 않았다.
+ *
+ * 값의 출처는 커널이 구간 마감 사실에 실어 주는 **지점별 몫**이다(적산의 뺄셈). 표본을 직접 읽지 않는
+ * 이유는 조회 상한이다 — 계측은 초당 여러 건이라 표본으로는 창을 채우기 전에 상한에 걸린다.
+ *
+ * 나머지(뿌리 − 분기 합)는 **버리지도 얹지도 않는다**: 수전 직결 부하·손실·계량되지 않은 회로가 그
+ * 차이이므로, 어느 분기에 얹으면 그 분기가 쓰지 않은 전기를 쓴 것으로 만든다. 커널의 `remainder` 풀로
+ * 넘겨 「하위 계량이 덮지 않는다」로 남긴다.
+ *
+ * 분기 계량 합이 뿌리보다 크면(회계가 다른 두 계량기) **그 사실을 낸다** — 값을 깎아 맞추면 계량을
+ * 우리가 고쳐 쓰는 것이다.
+ */
+function measuredFeeders(
+  windows: readonly {
+    startMs: number
+    endMs: number
+    maxKW?: number
+    points: { id: string; kWh: number; root: boolean }[]
+    pointsAtPeak?: { id: string; kW: number }[]
+  }[],
+  range: { startMs: number; endMs: number },
+  totalKWh: number | undefined,
+  meterFeeder?: Record<string, string>
+): Partial<NonNullable<KpiResult['energy']>> | undefined {
+  if (!meterFeeder || !Object.keys(meterFeeder).length) return undefined
+  if (totalKWh === undefined || !(totalKWh > 0)) return undefined
+
+  /* 창에 온전히 든 구간만 — 전체 전력량과 같은 규칙이어야 몫과 합이 같은 창을 말한다. */
+  const byFeederKWh = new Map<string, number>()
+  let sawPoints = false
+  for (const w of windows) {
+    if (!(w.startMs >= range.startMs && w.endMs <= range.endMs)) continue
+    for (const p of w.points ?? []) {
+      const feeder = meterFeeder[p.id]
+      if (!feeder) continue // 뿌리 계량기·모르는 지점 — 분기의 몫이 아니다
+      sawPoints = true
+      byFeederKWh.set(feeder, (byFeederKWh.get(feeder) ?? 0) + p.kWh)
+    }
+  }
+  if (!sawPoints) return undefined // 계량이 없으면 이 경로를 쓰지 않는다(배분으로 돌아간다)
+
+  const feeders = [...byFeederKWh.entries()].filter(([, kWh]) => kWh > 0)
+  if (!feeders.length) return undefined
+  const submetered = feeders.reduce((sum, [, kWh]) => sum + kWh, 0)
+  const remainder = totalKWh - submetered
+
+  const r = attributeEnergy({
+    pools: [
+      ...feeders.map(([feeder, kWh]) => ({ meterId: `${feeder}:meter`, kWh, consumerIds: [feeder] })),
+      ...(remainder > 0 ? [{ meterId: 'root:remainder', kWh: remainder, consumerIds: [], remainder: true }] : [])
+    ],
+    consumers: feeders.map(([feeder]) => ({ id: feeder }))
+  })
+
+  /*
+   * ── 피크를 만든 분기 (2026-08-18) ─────────────────────────────────────────
+   *
+   * 요금은 kW 로 매겨지므로 「어느 분기를 깎아야 피크가 내려가나」가 실무의 질문이다. 그 답은 **피크가
+   * 찍힌 구간의 그 순간** 값이고, 창 안의 여러 구간을 더하거나 평균하면 뜻이 사라진다(다른 순간의 값을
+   * 섞는 것이다). 그래서 **최대수요를 낸 구간 하나**만 골라 그 순간의 지점 값을 쓴다.
+   */
+  const peakWindow = windows
+    .filter(w => w.startMs >= range.startMs && w.endMs <= range.endMs && Number.isFinite(Number(w.maxKW)))
+    .reduce<(typeof windows)[number] | undefined>((best, w) => (!best || Number(w.maxKW) > Number(best.maxKW) ? w : best), undefined)
+  const peakOf = new Map<string, number>()
+  for (const p of peakWindow?.pointsAtPeak ?? []) {
+    const feeder = meterFeeder[p.id]
+    if (!feeder) continue // 뿌리 계량기·모르는 지점 — 분기의 몫이 아니다
+    peakOf.set(feeder, (peakOf.get(feeder) ?? 0) + p.kW)
+  }
+
+  const byFeeder = r.shares
+    .map(sh => ({
+      key: sh.consumerId,
+      kWh: sh.kWh,
+      basis: sh.basis,
+      weightKind: undefined,
+      weightShare: undefined,
+      /* 피크 순간의 값이 없으면 만들지 않는다 — 그 구간에 이 분기의 표본이 없었다는 뜻이다. */
+      ...(peakOf.has(sh.consumerId) ? { peakKW: peakOf.get(sh.consumerId) } : {})
+    }))
+    .sort((a, b) => b.kWh - a.kWh) as NonNullable<KpiResult['energy']>['byFeeder']
+
+  const un = r.unattributed.reduce((sum, u) => sum + u.kWh, 0)
+  return {
+    ...(byFeeder?.length ? { byFeeder } : {}),
+    ...(un > 0 ? { unattributedKWh: un, unattributedReason: r.unattributed[0]?.reason } : {}),
+    /* 분기 합이 뿌리를 넘었다 — 두 계량기의 회계가 다르다는 사실이다(깎아 맞추지 않는다). */
+    ...(remainder < 0 ? { submeterExcessKWh: -remainder } : {})
+  }
+}
+
 /** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
 export interface KpiFoldOptions {
   groupBy?: KpiGroupBy
@@ -122,6 +423,31 @@ export interface KpiFoldOptions {
    * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(조용히 다른 축으로 바꾸지 않는다).
    */
   locationArea?: Record<string, string>
+  /**
+   * 자원 → **배전 계통의 자리**(분기·수전) 지도.
+   *
+   * ── 왜 밖에서 오나 ───────────────────────────────────────────────────────
+   * 이벤트에는 전기 계통이 없다. 「이 설비가 어느 분기에서 먹는가」는 에너지 트윈의 모델이 아는
+   * 선언이고(설비 하나에 사실 둘 — 공장에서는 자원, 전기에서는 부하), 그 선언을 읽는 것은 호출부의 일이다.
+   *
+   * 없으면 분기 분해를 **하지 않는다** — 자리를 모르는 채 나누면 그 숫자는 아무 것의 몫도 아니다.
+   */
+  resourceFeeder?: Record<string, string>
+  /**
+   * **계량 지점 → 그것이 재는 분기** 지도.
+   *
+   * 있으면 분기별 전력량을 계량으로 읽는다(배분보다 강한 근거). 이 지도는 모델의 선언에서 오고
+   * (계량기의 자리), 그것을 읽는 것은 호출부의 일이다 — 폴드는 저널만 본다.
+   */
+  meterFeeder?: Record<string, string>
+  /**
+   * 선언된 **전기요금 단가** — 수를 금액으로 바꾸는 유일한 입력.
+   *
+   * 이벤트에는 요금이 없다. 단가는 현장의 계약이고(에너지 트윈 모델의 수전 자리에 선언한다), 그것을
+   * 읽는 것은 호출부의 일이다. 없으면 금액을 만들지 않는다 — 짐작한 단가로 낸 금액은 숫자가 있다는
+   * 것만으로 사람을 결정으로 밀어붙인다.
+   */
+  tariff?: TariffDeclaration
   /**
    * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
    * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).
@@ -295,6 +621,35 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     }
   }
 
+  /*
+   * 에너지 — 창에 **온전히 든** 구간 마감 사건만 센다(걸친 구간은 커널 규칙이 뺀다).
+   * 사건이 하나도 없으면 이 트윈에는 에너지가 없는 것이므로 블록 자체를 내지 않는다.
+   */
+  const demandWindows = events
+    .filter(e => e.eventType === ENERGY_EVENT.demandWindow)
+    .map(e => {
+      const d = e.payload?.data ?? e.payload ?? {}
+      /* 최대(`maxKW`)도 함께 넘긴다 — 요금이 걸리는 수는 평균이 아니라 최대다.
+         총부하(`grossMaxKW`)는 「무엇이 깎였나」를 되짚는 축이다(발전·방전 차감 전). */
+      return {
+        startMs: Number(d.startMs),
+        endMs: Number(d.endMs),
+        meanKW: Number(d.meanKW),
+        maxKW: Number(d.maxKW),
+        grossMaxKW: Number(d.grossMaxKW),
+        /* 지점별 몫 — 계량이 분기에 있으면 그 값은 **측정**이다(배분이 아니다). 커널이 계층 판정
+           (`root`)까지 실어 주므로 여기서 같은 규칙을 다시 쓰지 않는다. */
+        points: (Array.isArray(d.points) ? d.points : [])
+          .map((p: any) => ({ id: String(p?.id ?? ''), kWh: Number(p?.kWh), root: p?.root === true }))
+          .filter((p: any) => p.id && Number.isFinite(p.kWh)),
+        /* 피크가 찍힌 순간의 지점별 kW — 요금이 걸린 수는 kW 다(전력량이 큰 분기와 피크를 만든 분기는 다르다). */
+        pointsAtPeak: (Array.isArray(d.pointsAtPeak) ? d.pointsAtPeak : [])
+          .map((p: any) => ({ id: String(p?.id ?? ''), kW: Number(p?.kW) }))
+          .filter((p: any) => p.id && Number.isFinite(p.kW))
+      }
+    })
+    .filter(w => Number.isFinite(w.startMs) && Number.isFinite(w.endMs))
+
   const leads: number[] = []
   const works: number[] = []
   const waits: number[] = []
@@ -336,6 +691,39 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
   return {
     window: { fromMs: window.fromMs, toMs: window.toMs },
     throughput: { tasks: tasksInWindow, orders: completedOrders },
+    ...(demandWindows.length
+      ? (() => {
+          const e = energyOfWindows(demandWindows, { startMs: window.fromMs, endMs: window.toMs })
+          /* 분모는 **완료 오더**다(대당 전력). 창에 완료가 없으면 커널 규칙이 「정의되지 않음」으로 답한다. */
+          const i = energyIntensity({
+            kWh: e.kWh,
+            energyWindow: e.window,
+            denominator: { kind: 'output', value: completedOrders, window: e.window }
+          })
+          return {
+            energy: {
+              ...(e.kWh !== undefined ? { kWh: e.kWh } : {}),
+              /* 이 창의 최대수요 — 계약 대비 판정이 보는 수다(전력량과 같은 구간 집합에서 왔다). */
+              ...(e.peakKW !== undefined ? { peakKW: e.peakKW, peakStartMs: e.peakStartMs } : {}),
+              /* 깎인 양은 **같은 구간의 두 수**의 차이다 — 여기서 한 번만 계산해 두 곳이 갈라지지 않게. */
+              ...(e.peakGrossKW !== undefined && e.peakKW !== undefined
+                ? { peakGrossKW: e.peakGrossKW, ...(e.peakGrossKW > e.peakKW ? { shavedKW: e.peakGrossKW - e.peakKW } : {}) }
+                : {}),
+              basis: e.basis,
+              counted: e.counted,
+              skipped: e.skipped,
+              intensity:
+                i.value === null
+                  ? { value: null, reason: (i as any).reason }
+                  : { value: i.value, unit: (i as any).unit },
+              ...(measuredFeeders(demandWindows, { startMs: window.fromMs, endMs: window.toMs }, e.kWh, options.meterFeeder) ??
+                feederShares(e.kWh, utilization, options.resourceFeeder)),
+              /* 금액은 같은 창의 전력량·최대수요에서 나온다 — 창이 하나뿐이라 어긋날 수 없다. */
+              ...(options.tariff ? { cost: electricityCost({ kWh: e.kWh, peakKW: e.peakKW, tariff: options.tariff }) } : {})
+            }
+          }
+        })()
+      : {}),
     leadTime: stats(leads),
     workTime: stats(works),
     waitTime: stats(waits),