@things-factory/headless-twin 10.0.17 → 10.0.18

package/server/engine/canonical-ingest.ts

@@ -1,11 +1,5 @@
-import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestEnergyGenerationRecords,
-  ingestEnergyUsagePeriodRecords, ingestEnergyBillRecords, ingestOperationalRecords,
-  isAggregationRecord, isTransformationRecord,
-  isEnergyRecord, isEnergyEquipmentRecord, isEnergyGenerationRecord, isEnergyUsagePeriodRecord, isEnergyBillRecord,
-  isOperationalRecord, type AdapterRule, type EnergyRecord,
-  isMasterDataRecord, ingestMasterData,
-  type EnergyEquipmentRecord, type EnergyGenerationRecord, type EnergyUsagePeriodRecord, type EnergyBillRecord,
-  type OperationalRecord, type IngestResult, type MasterDataRecord } from '@operato/twin-kernel'
+import { type CanonicalRecord, type CanonicalAggregationRecord, type CanonicalTransformationRecord, type AdapterRule, type EnergyRecord, type EnergyEquipmentRecord, type EnergyGenerationRecord, type EnergyUsagePeriodRecord, type EnergyBillRecord, type EnergyTariffBasisRecord, type EnergyGenerationPriceRecord, type EnergyGenerationPeriodRecord, type OperationalRecord, type IngestResult, type MasterDataRecord } from '@operato/ops-contract'
+import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestEnergyGenerationRecords, ingestEnergyUsagePeriodRecords, ingestEnergyBillRecords, ingestEnergyTariffBasisRecords, ingestEnergyGenerationPriceRecords, ingestEnergyGenerationPeriodRecords, ingestOperationalRecords, isAggregationRecord, isTransformationRecord, isEnergyRecord, isEnergyEquipmentRecord, isEnergyGenerationRecord, isEnergyUsagePeriodRecord, isEnergyBillRecord, isEnergyTariffBasisRecord, isEnergyGenerationPriceRecord, isEnergyGenerationPeriodRecord, isOperationalRecord, isMasterDataRecord, ingestMasterData } from '@operato/ops-contract'
 
 /*
  * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).
@@ -16,6 +10,7 @@ import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestEnergy
  *   에너지 계량 { meterId, kW?, kWh?, … } · 설비 에너지 { equipmentId, generatedKW?, soc?, … }
  *   발전 적산   { equipmentId, kWh, kWhSince?, … }
  *   사용 구간   { meterId, from, to, kWh, unitPrice?, basis?, … }  · 청구서 { from, to, total?, … }
+ *   요금 기준   { from, to, billingDemandKW?, demandChargePerKW?, currency }
  *   담김(적재) { parentID, childEPCs[] | childQuantityList[], action, bizStep, … }
  *   운영 사실 { taskId | moverId | personId | assetId | orderId, status, … }  // vocabulary-guard: allow 저널 와이어 필드
  * 커널은 objectEvent 구성 + EPCIS 검증(위반=오염 차단) + 봉투 래핑만(방언 없음).
@@ -116,78 +111,16 @@ const TWIN_INGEST_RULES: AdapterRule[] = [
   }
 ]
 
-/** 개체 관측 — 물건 하나가 어디서 무엇이 됐나. */
-export interface CanonicalRecord {
-  /**
-   * 개체 하나의 식별자. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는 자재(밀가루 3.5kg)는
-   * 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 커널 매핑이 거부한다.
-   */
-  epc?: string
-  /**
-   * 클래스와 수량 — `{ epcClass, quantity, uom? }`. **잔량 절대값을 싣는다**(「얼마 뺐다」가 아니라
-   * 「얼마 남았다」). 그래야 사건 하나를 놓쳐도 다음 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다.
-   *
-   * 담김(`childQuantityList`)이 하루 먼저 이 자리를 받았다 — 그때와 같은 이유다. 원본이 비직렬 수량을
-   * 말할 길이 없어서, 그것이 주된 경로인 시스템(식품 제조 MES)은 라이브를 낼 수 없었다. 커널의
-   * 관측 리듀서는 처음부터 이 값을 읽었고 문만 없었다.
-   */
-  quantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  action: string // ADD | OBSERVE | DELETE
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
-
-/**
- * 담김 관측 — **부모와 자식**으로 말한다. 자리 필드는 개체 관측과 같은 이름이다(문자열).
- *
- * 이름은 표준의 것을 그대로 쓴다(`parentID`·`childEPCs`) — 여기서 다시 지으면 매핑이 번역이 되고,
- * 같은 사실에 두 어휘가 생긴다.
- */
-/**
- * 변환 관측 — **무엇으로 무엇이 되었나.** 입력과 출력이 **한 사실에 함께** 있어야 계보가 남는다.
- *
- * 따로 보내면(「이 로트가 없어졌다」와 「이 제품이 생겼다」) 그 둘을 이을 근거가 없다. 그래서 표준이
- * 한 사건에 둘을 담고, 우리 레코드도 같은 모양이다.
- *
- * 이름은 **표준의 것을 그대로** 쓴다(`inputQuantityList` 등). 갈래 판정이 이 이름으로 이루어지므로
- * 커넥터 낱말(`consumed`·`produced`)로 담으면 판정되지 않는다 — 커넥터가 정규 이름으로 담아 보내고
- * 매핑은 그 안에서 값을 고른다.
+/*
+ * 정규 레코드 셋(`CanonicalRecord` · `CanonicalTransformationRecord` · `CanonicalAggregationRecord`)은
+ * **계약으로 옮겼다**(2026-08-30, `@operato/ops-contract` 0.2.0).
  *
- * **없는 쪽은 필드를 만들지 않는다.** 빈 배열을 실으면 「없다」고 말하는 것이 된다. 소실(N→0)과
- * 생성(0→N)도 표준이 인정하는 변환이다.
+ * 여기 있던 이유는 소비 방식 때문이었다 — EPCIS 는 커널의 범용 어댑터를 지나서 타입을 요구하지 않았다.
+ * 그런데 모양 자체는 EPCIS 2.0 의 필드 이름이고 호스트의 것이 아니다. 이제 MES 가 이 모양 그대로
+ * 보낸다.
  *
- * `transformationID` 가 한 오더의 여러 단계를 잇는다 — 소비를 먼저 알고 산출을 나중에 알게 되는 원본에서
- * 그 둘을 묶는 유일한 자리다.
+ * **매핑 룰(`TWIN_INGEST_RULES`)은 여기 남는다** — 이 모양을 EPCIS 사건으로 옮기는 정책이지 모양이 아니다.
  */
-export interface CanonicalTransformationRecord {
-  /** 개체로 소비된 것. */
-  inputEPCList?: string[]
-  /** 클래스와 수량으로 소비된 것 — 로트 단위 소비가 이 자리다. */
-  inputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  outputEPCList?: string[]
-  outputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  /** 한 오더의 여러 단계를 잇는 식별자. */
-  transformationID?: string
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
-
-export interface CanonicalAggregationRecord {
-  parentID: string
-  /** 개체로 담긴 자식. 수량으로만 담겼으면 없다(둘 중 하나는 있어야 한다). */
-  childEPCs?: string[]
-  /** 수량으로 담긴 자식 — `{ epcClass, quantity, uom? }`. 값의 옳고 그름은 커널 검증이 본다. */
-  childQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  action: string // ADD(담다) | DELETE(풀다) | OBSERVE
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
 
 /** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
 export function ingestCanonicalRecords(
@@ -212,7 +145,17 @@ export function ingestCanonicalRecords(
     | undefined
     | null,
   tenantId: string,
-  defaultEventTime: string
+  defaultEventTime: string,
+  /**
+   * **이 사실들이 어느 트윈의 것인가** — 마감된 구간 사실의 이름에 쓰인다(커널 §`SubjectBasis`).
+   *
+   * 커널은 도메인으로 서므로 자기가 어느 트윈인지 모른다. 그런데 설비 번호·계량 지점 번호는 트윈
+   * 안에서만 통하는 이름표라, 한 도메인에 현장이 둘이면 서로 다른 설비의 같은 날이 한 사실이 된다.
+   * 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳤다.
+   *
+   * 주지 않으면 이름표를 그대로 쓰고 `twin-local` 로 표시된다 — 겹칠 수 있다는 뜻이다.
+   */
+  scope?: { scopeId?: string; identityOf?: (kind: 'equipment' | 'meter', localId: string) => string | undefined }
 ): CanonicalIngestResult {
   const arr = Array.isArray(records) ? records : records ? [records] : []
   /*
@@ -254,6 +197,23 @@ export function ingestCanonicalRecords(
    */
   const usagePeriods = arr.filter(isEnergyUsagePeriodRecord) as unknown as EnergyUsagePeriodRecord[]
   const bills = arr.filter(isEnergyBillRecord) as unknown as EnergyBillRecord[]
+  /*
+   * 여덟째 어휘 — **그 주기에 적용되는 요금 기준**. 커널 0.7.76 이 이 문을 열었다.
+   *
+   * ★ 청구서와 겹친다. 청구서가 `billingDemandKW` 를 실을 수 있고, 그러면 두 판정이 다 참이다.
+   * 그때 요금 기준 문으로 보내면 「금액은 이 문이 받지 않는다」로 거부된다 — 정산이 통째로
+   * 사라진다. 그래서 청구서인 것을 뺀다. 커널에서 배타로 만들어 달라고 올렸다.
+   */
+  const tariffBases = arr.filter(r => isEnergyTariffBasisRecord(r) && !isEnergyBillRecord(r)) as unknown as EnergyTariffBasisRecord[]
+  /*
+   * 아홉째 어휘 — **발전 단가**. 낸 것에 매겨지는 1kWh 당 값이고 날마다 바뀐다(커널 0.7.79).
+   *
+   * 다른 문과 겹치지 않는다: 계량 지점이나 설비 id 가 있으면 이 문이 아니고(커널이 배타로 막는다),
+   * 요금적용전력·기본요금 단가가 없으므로 요금 기준도 아니다.
+   */
+  const generationPrices = arr.filter(isEnergyGenerationPriceRecord) as unknown as EnergyGenerationPriceRecord[]
+  /* 마감된 발전 기간 — 지난 기록 채우기가 쓴다. 적산의 문과 배타다(구간이 있으면 이쪽). */
+  const generationPeriods = arr.filter(isEnergyGenerationPeriodRecord) as unknown as EnergyGenerationPeriodRecord[]
   const energy = arr.filter(r => isEnergyRecord(r) && !isEnergyUsagePeriodRecord(r)) as EnergyRecord[]
   /* 세 번째 어휘 — 설비가 낸 자기 에너지 상태(발전·저장·감축 여지·개폐 위치). 계량과 갈라 두는
      이유는 커널에 적혀 있다: 계량은 구간에 누적되고, 이것들은 그 설비의 지금이다. */
@@ -276,6 +236,16 @@ export function ingestCanonicalRecords(
    * 아는 상태가 남았다(같은 화면이 두 구동에서 다른 것을 말한다).
    */
   const operational = arr.filter(isOperationalRecord) as OperationalRecord[]
+  /*
+   * ── 이 목록은 **어휘를 더할 때마다 함께 늘어야 한다** (2026-08-30) ─────────
+   *
+   * EPCIS 갈래는 「나머지 전부」다. 새 어휘를 빼 주지 않으면 그 레코드가 제 문으로 가면서
+   * **EPCIS 문으로도 들어가** 거부된다. 받아들여지기도 하고 거부되기도 하는 상태가 되어,
+   * 유입 장부의 거부 수가 늘고 사람이 그것을 진짜 결함으로 읽는다.
+   *
+   * 실제로 발전 단가를 더할 때 그렇게 됐다. 목록을 손으로 지키는 대신 시험이 지킨다
+   * (§`canonical-ingest-vocabularies` — 어휘마다 한 문으로만 가는지).
+   */
   const epcis = arr.filter(
     r =>
       !isEnergyRecord(r) &&
@@ -283,6 +253,9 @@ export function ingestCanonicalRecords(
       !isEnergyGenerationRecord(r) &&
       !isEnergyUsagePeriodRecord(r) &&
       !isEnergyBillRecord(r) &&
+      !isEnergyTariffBasisRecord(r) &&
+      !isEnergyGenerationPriceRecord(r) &&
+      !isEnergyGenerationPeriodRecord(r) &&
       !isOperationalRecord(r) &&
       !isMasterDataRecord(r)
   ) as (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord)[]
@@ -336,19 +309,28 @@ export function ingestCanonicalRecords(
         { tenantId, defaultEventTime, eventTimePath: 'eventTime' }
       )
     : { accepted: [], rejected: [] }
-  const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] }
+  const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime, ...scope }) : { accepted: [], rejected: [] }
   const equipmentResult = energyEquipment.length
-    ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime })
+    ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
   const usageResult = usagePeriods.length
-    ? ingestEnergyUsagePeriodRecords(usagePeriods, { tenantId, defaultEventTime })
+    ? ingestEnergyUsagePeriodRecords(usagePeriods, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const billResult = bills.length ? ingestEnergyBillRecords(bills, { tenantId, defaultEventTime, ...scope }) : { accepted: [], rejected: [] }
+  const tariffBasisResult = tariffBases.length
+    ? ingestEnergyTariffBasisRecords(tariffBases, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const generationPeriodResult = generationPeriods.length
+    ? ingestEnergyGenerationPeriodRecords(generationPeriods, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const generationPriceResult = generationPrices.length
+    ? ingestEnergyGenerationPriceRecords(generationPrices, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
-  const billResult = bills.length ? ingestEnergyBillRecords(bills, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] }
   const generationResult = energyGeneration.length
-    ? ingestEnergyGenerationRecords(energyGeneration, { tenantId, defaultEventTime })
+    ? ingestEnergyGenerationRecords(energyGeneration, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
   const operationalResult = operational.length
-    ? ingestOperationalRecords(operational, { tenantId, defaultEventTime })
+    ? ingestOperationalRecords(operational, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
 
   /* 거부분을 합쳐 돌려준다 — 어느 어휘에서 거부됐는지는 이유 문구가 말한다. */
@@ -359,7 +341,10 @@ export function ingestCanonicalRecords(
       ...equipmentResult.accepted,
       ...generationResult.accepted,
       ...usageResult.accepted,
+      ...generationPriceResult.accepted,
+      ...generationPeriodResult.accepted,
       ...billResult.accepted,
+      ...tariffBasisResult.accepted,
       ...operationalResult.accepted
     ],
     rejected: [
@@ -369,6 +354,9 @@ export function ingestCanonicalRecords(
       ...generationResult.rejected,
       ...usageResult.rejected,
       ...billResult.rejected,
+      ...tariffBasisResult.rejected,
+      ...generationPriceResult.rejected,
+      ...generationPeriodResult.rejected,
       ...operationalResult.rejected,
       ...master.rejected
     ],

package/server/engine/energy-topology.ts

@@ -17,7 +17,7 @@
  * 자리를 모르는 설비, 계량기가 없는 자리, 계량이 덮지 않는 몫은 **각자 자기 칸으로** 나온다. 그림에서
  * 사라지면 사용자는 자기 현장이 다 그려졌다고 믿는다.
  */
-import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/twin-kernel'
+import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/ops-contract'
 
 /** 계통의 한 구간(수전·분기·구역) — 자리 하나가 곧 구간이다. */
 export interface TopologySegment {

package/server/engine/kpi-fold.ts

@@ -25,20 +25,9 @@
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
  * 이 파일은 이제 "계산한 기록 → 창 지표" 만 한다.
  */
-import {
-  ENERGY_EVENT,
-  attributeEnergy,
-  electricityCost,
-  energyIntensity,
-  energyOfWindows,
-  foldTaskRecords,
-  isOrderTerminal,
-  activeShiftAt,
-  type ElectricityCost,
-  type TariffDeclaration,
-  type TaskFacets,
-  type WorkCalendarEntry
-} from '@operato/twin-kernel'
+import { attributeEnergy, electricityCost, energyIntensity, energyOfWindows, foldTaskRecords, type ElectricityCost, type TariffDeclaration, type TaskFacets } from '@operato/twin-kernel'
+import { type WorkCalendarEntry } from '@operato/ops-contract'
+import { ENERGY_EVENT, isOrderTerminal, activeShiftAt } from '@operato/ops-contract'
 
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
@@ -158,6 +147,35 @@ export interface KpiResult {
       partial: number
       /** 설비별 몫 — 이것은 **측정**이다(배분이 아니다). 각 설비의 적산에서 왔다. */
       byEquipment: { id: string; kWh: number }[]
+      /**
+       * **이 창에 다 들어오지 않아 더하지 못한 기간** — 조용히 버리지 않는다.
+       *
+       * 더하는 것은 창에 온전히 든 기간뿐이다(걸친 기간을 더하면 다른 날 값이 이 창의 값인 척한다).
+       * 그런데 하루 단위 기간은 「지금부터 24시간 전」 창에 온전히 드는 일이 거의 없다 — 창이 한낮에서
+       * 시작하기 때문이다. 그래서 어제 발전량이 저널에 멀쩡히 있는데 화면이 비었고, 사용자는 그것을
+       * 「발전량이 없다」로 읽었다(2026-08-30 실측).
+       *
+       * 이 값이 있으면 화면은 **「이 구간에 다 들어오지 않은 기간이 있다」**를 말해야 한다.
+       */
+      notCounted?: { periods: number; kWh: number; earliestStart: string; latestEnd: string }
+      /**
+       * 이용률 — 만든 양 ÷ (정격 × 그 기간의 시간).
+       *
+       * **어느 정격으로 나눴는지를 함께 낸다.** 변환기를 낀 발전은 직류 정격이 교류보다 크고,
+       * 직류로 나눠 보여 주는 시스템이 실제로 있다. 밝히지 않으면 두 화면의 수가 두 배 달라도
+       * 왜 다른지 말할 수 없다.
+       *
+       * 창 전체가 아니라 **센 기간들의 길이**로 나눈다 — 하루치 하나만 센 24시간 창에서 창 길이로
+       * 나누면 그 하루가 창 전체에 걸쳐 있었던 것처럼 작아진다.
+       */
+      capacityFactor?: { value: number; ratedKW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location'; hours: number }
+      /**
+       * 낸 것의 값 — 기간마다 그때의 단가로 매긴다.
+       *
+       * **모든 기간에 단가가 있을 때만** 금액을 만든다. 일부만 매기고 더하면 그 합이 창 전체의 값인
+       * 척한다 — 못 매긴 기간 수를 함께 낸다.
+       */
+      revenue?: { amount: number; currency: string; priced: number; unpriced: number }
     }
     /**
      * `kWh` 가 어느 회계에서 왔나.
@@ -182,9 +200,18 @@ export interface KpiResult {
      */
     billingDemand?: {
       kW: number
-      from: 'bill' | 'carried-forward' | 'declaration'
+      from: 'tariff-basis' | 'bill' | 'carried-forward' | 'declaration'
       declaredKW?: number
       stale?: boolean
+      /**
+       * 이 창에서 관측한 최고 수요가 그 기준을 넘었다 — **다음 주기의 기본요금이 오른다.**
+       *
+       * 계약 초과와 다른 값이다. 계약 초과는 지금 줄이면 되고, 이것은 이미 정해진 결과다.
+       *
+       * `observedTo` 는 이 최고값이 언제까지의 것인지다. 최고 수요는 구간이 마감되어야 오므로
+       * 넘은 것을 뒤늦게 안다 — 그 한계를 화면이 말할 수 있어야 한다.
+       */
+      exceeded?: { peakKW: number; overKW: number; observedTo: string }
     }
     /**
      * 밖에서 마감되어 온 사용 구간 — 계량 표본이 없는 현장의 유일한 근거다.
@@ -487,10 +514,42 @@ function generatedOfPeriods(
     observedFromMs: number
     observedToMs: number
   }[],
-  range: { startMs: number; endMs: number }
+  range: { startMs: number; endMs: number },
+  /** 이용률의 분모 — 없으면 이용률을 내지 않는다(0 이나 짐작을 만들지 않는다). */
+  rated?: { kW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location' },
+  /** 기간마다 적용할 단가 — 기간을 덮는 것을 쓴다. 없으면 금액을 만들지 않는다. */
+  prices?: readonly { startMs: number; endMs: number; unitPrice: number; currency: string }[]
 ): Partial<NonNullable<KpiResult['energy']>> {
   const inside = periods.filter(g => g.startMs >= range.startMs && g.endMs <= range.endMs)
-  if (!inside.length) return {}
+
+  /*
+   * ── **걸친 기간을 조용히 버리지 않는다** (2026-08-30) ──────────────────────
+   *
+   * 더하는 것은 창에 **온전히 들어온 기간**뿐이다. 그것이 맞는 셈이다 — 걸친 기간을 더하면 다른 날의
+   * 값이 이 창의 값인 척한다.
+   *
+   * 그런데 버린 것을 말하지 않았다. 하루 단위 기간은 「지금부터 24시간 전」 창에 온전히 들어오는 일이
+   * 거의 없다(창이 한낮에서 시작하므로). 그래서 어제 발전량이 저널에 멀쩡히 있는데 화면이 비었고,
+   * 사용자는 그것을 **「발전량이 없다」**로 읽었다. 실측으로 그 일이 났다.
+   *
+   * 이제 걸친 것을 세어 함께 낸다. 화면이 「이 창에 다 들어오지 않은 기간이 있다」를 말할 수 있다.
+   */
+  const straddling = periods.filter(
+    g => !(g.startMs >= range.startMs && g.endMs <= range.endMs) && g.endMs > range.startMs && g.startMs < range.endMs
+  )
+  const notCounted = straddling.length
+    ? {
+        periods: straddling.length,
+        kWh: straddling.reduce((a, g) => a + g.kWh, 0),
+        earliestStart: new Date(Math.min(...straddling.map(g => g.startMs))).toISOString(),
+        latestEnd: new Date(Math.max(...straddling.map(g => g.endMs))).toISOString()
+      }
+    : undefined
+
+  if (!inside.length) {
+    /* 온전히 들어온 것이 없다 — 그래도 걸친 것이 있으면 그 사실을 낸다(빈 값과 「없음」은 다르다). */
+    return notCounted ? { generated: { kWh: 0, counted: 0, partial: 0, byEquipment: [], notCounted } } : {}
+  }
 
   const byEquipment = new Map<string, number>()
   let partial = 0
@@ -501,14 +560,48 @@ function generatedOfPeriods(
     if (!coveredFrom || !coveredTo) partial++
   }
 
+  const kWh = inside.reduce((a, g) => a + g.kWh, 0)
+  /*
+   * 이용률의 분모는 **센 기간들의 길이**다. 창 길이로 나누면, 하루치 하나만 센 24시간 창에서 그 하루가
+   * 창 전체에 걸쳐 있었던 것처럼 작아진다.
+   */
+  const hours = inside.reduce((a, g) => a + (g.endMs - g.startMs) / 3_600_000, 0)
+  const capacityFactor =
+    rated && rated.kW > 0 && hours > 0
+      ? { value: kWh / (rated.kW * hours), ratedKW: rated.kW, basis: rated.basis, from: rated.from, hours }
+      : undefined
+
+  /*
+   * 낸 것의 값 — 기간마다 **그 기간을 덮는 단가**로 매긴다. 걸친 단가는 쓰지 않는다: 하루 단가로
+   * 이틀치를 매기면 그 절반은 다른 날의 값이 된다.
+   *
+   * 모든 기간에 단가가 있을 때만 금액을 만든다. 일부만 매기고 더하면 그 합이 창 전체의 값인 척한다.
+   */
+  let amount = 0
+  let priced = 0
+  let currency: string | undefined
+  for (const g of inside) {
+    const p = (prices ?? []).find(x => x.startMs <= g.startMs && x.endMs >= g.endMs)
+    if (!p) continue
+    amount += g.kWh * p.unitPrice
+    priced++
+    currency = currency ?? p.currency
+  }
+  const unpriced = inside.length - priced
+  const revenue = priced > 0 && unpriced === 0 && currency ? { amount, currency, priced, unpriced } : undefined
+
   return {
     generated: {
-      kWh: inside.reduce((a, g) => a + g.kWh, 0),
+      kWh,
       counted: inside.length,
       partial,
       byEquipment: [...byEquipment.entries()]
         .map(([id, kWh]) => ({ id, kWh }))
-        .sort((a, b) => b.kWh - a.kWh)
+        .sort((a, b) => b.kWh - a.kWh),
+      ...(capacityFactor ? { capacityFactor } : {}),
+      ...(revenue ? { revenue } : {}),
+      /* 이 창에 다 들어오지 않아 더하지 못한 기간 — 있으면 화면이 그것을 말한다. */
+      ...(notCounted ? { notCounted } : {})
     }
   }
 }
@@ -560,30 +653,47 @@ function usageOfPeriods(
  */
 function billingDemandOf(
   billsInWindow: readonly { endMs: number; billingDemandKW: number }[],
+  tariffBasis: { billingDemandKW?: number } | undefined,
   lastBill: { billingDemandKW?: number } | undefined,
-  declaredKW: number | undefined
+  declaredKW: number | undefined,
+  /** 이 창에서 관측한 최고 수요와 그 값이 언제까지의 것인지 — 사용 구간의 `maxKW` 에서 온다. */
+  observedPeak?: { kW: number; toMs: number }
 ): NonNullable<KpiResult['energy']>['billingDemand'] | undefined {
   const declared = Number.isFinite(Number(declaredKW)) ? Number(declaredKW) : undefined
   const withValue = billsInWindow.filter(b => Number.isFinite(b.billingDemandKW))
   const fromBill = withValue.length ? withValue.reduce((a, x) => (x.endMs > a.endMs ? x : a)).billingDemandKW : undefined
   const carried = Number.isFinite(Number(lastBill?.billingDemandKW)) ? Number(lastBill?.billingDemandKW) : undefined
+  /* 이 주기에 적용되는 기준이 가장 먼저다 — 청구서는 끝난 기간의 것이다. */
+  const fromBasis = Number.isFinite(Number(tariffBasis?.billingDemandKW)) ? Number(tariffBasis?.billingDemandKW) : undefined
 
   const picked =
-    fromBill !== undefined
-      ? { kW: fromBill, from: 'bill' as const }
-      : carried !== undefined
-        ? { kW: carried, from: 'carried-forward' as const }
-        : declared !== undefined
-          ? { kW: declared, from: 'declaration' as const }
-          : undefined
+    fromBasis !== undefined
+      ? { kW: fromBasis, from: 'tariff-basis' as const }
+      : fromBill !== undefined
+        ? { kW: fromBill, from: 'bill' as const }
+        : carried !== undefined
+          ? { kW: carried, from: 'carried-forward' as const }
+          : declared !== undefined
+            ? { kW: declared, from: 'declaration' as const }
+            : undefined
   if (!picked) return undefined
 
   /* 선언이 있는데 청구서와 다르면 그 사실을 낸다 — 낡은 선언은 스스로 말해야 한다. */
   const stale = picked.from !== 'declaration' && declared !== undefined && declared !== picked.kW
+  const exceeded =
+    observedPeak && observedPeak.kW > picked.kW
+      ? {
+          peakKW: observedPeak.kW,
+          overKW: observedPeak.kW - picked.kW,
+          observedTo: new Date(observedPeak.toMs).toISOString()
+        }
+      : undefined
+
   return {
     ...picked,
     ...(declared !== undefined ? { declaredKW: declared } : {}),
-    ...(stale ? { stale: true } : {})
+    ...(stale ? { stale: true } : {}),
+    ...(exceeded ? { exceeded } : {})
   }
 }
 
@@ -720,6 +830,26 @@ function measuredFeeders(
 }
 
 /** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
+/*
+ * ── 같은 사실이 두 벌 있어도 한 번만 센다 (2026-08-30) ──────────────────────
+ *
+ * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81). 그런데 저널에 이미 여러 벌 적힌 것이 있다 —
+ * 쓰는 자리에서 막기 전에 들어간 것들이다(실측: 어느 날의 발전 단가가 세 벌).
+ *
+ * 지난 기록을 지우지 않는다 — 저널은 일어난 일의 기록이다. 대신 **읽을 때 한 번만 센다.**
+ * 그러지 않으면 그 구간의 수익·사용량이 그 횟수만큼 세어진다.
+ */
+function onceById<T extends { payload?: any }>(rows: readonly T[]): T[] {
+  const seen = new Set<string>()
+  return rows.filter(r => {
+    const id = (r as any)?.payload?.eventId
+    if (typeof id !== 'string' || !id) return true
+    if (seen.has(id)) return false
+    seen.add(id)
+    return true
+  })
+}
+
 export interface KpiFoldOptions {
   groupBy?: KpiGroupBy
   /**
@@ -729,6 +859,24 @@ export interface KpiFoldOptions {
    * 커널 상태에서 읽어 넘긴다.
    */
   lastBill?: { to: string; billingDemandKW?: number }
+  /**
+   * 이 트윈이 이어받고 있는 **요금 기준** — 이 주기에 적용되는 값(§`ENERGY_EVENT.tariffBasis`).
+   *
+   * 청구서보다 먼저다. 청구서는 끝난 기간의 정산이라 이번 주기의 기준을 말하지 않는다.
+   */
+  tariffBasis?: { from: string; billingDemandKW?: number }
+  /**
+   * 이 트윈의 **발전 정격**과 그 근거 — 이용률의 분모(§ 커널 `generationRated`).
+   *
+   * 모델의 선언에서 오므로 호출부가 읽어 넘긴다. 폴드는 저널만 본다.
+   */
+  generationRated?: { kW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location' }
+  /**
+   * 이 트윈이 이어받고 있는 **발전 단가** — 창 밖의 단가도 이 창에 적용될 수 있다.
+   *
+   * 창 안의 단가 사실이 먼저다. 이것은 그 창에 단가가 없을 때 쓴다.
+   */
+  generationPrice?: { from: string; to: string; unitPrice: number; currency: string }
   /**
    * 노드 → 구역 지도. **이벤트에는 구역이 없다**(노드까지만 있다) — 스냅샷·마스터가 아는 값이라
    * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(알리지 않고 다른 축으로 바꾸지 않는다).
@@ -1024,8 +1172,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
    *
    * 관측 구간(`observedFrom`·`observedTo`)을 함께 읽는다 — 값의 근거가 얼마나 덮였는지가 그 둘에 있다.
    */
-  const generationPeriods = events
-    .filter(e => e.eventType === ENERGY_EVENT.generationPeriod)
+  const generationPeriods = onceById(events.filter(e => e.eventType === ENERGY_EVENT.generationPeriod))
     .map(e => {
       const d = e.payload?.data ?? e.payload ?? {}
       return {
@@ -1042,8 +1189,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
   /*
    * 밖에서 마감되어 온 사용 구간 — 구간 마감과 같은 규칙으로 **창에 온전히 든 것만** 센다.
    */
-  const usagePeriods = events
-    .filter(e => e.eventType === ENERGY_EVENT.usagePeriod)
+  const usagePeriods = onceById(events.filter(e => e.eventType === ENERGY_EVENT.usagePeriod))
     .map(e => {
       const d = e.payload?.data ?? e.payload ?? {}
       return {
@@ -1052,6 +1198,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
         startMs: Date.parse(String(d.from ?? '')),
         endMs: Date.parse(String(d.to ?? '')),
         unitPrice: Number(d.unitPrice),
+        maxKW: Number(d.maxKW),
         currency: d.currency ? String(d.currency) : undefined,
         basis: d.basis ? String(d.basis) : 'unstated'
       }
@@ -1059,8 +1206,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     .filter(u => u.meterId && Number.isFinite(u.kWh) && Number.isFinite(u.startMs) && Number.isFinite(u.endMs))
 
   /* 청구서 — 창에 온전히 든 것 중 가장 늦게 끝난 것 하나. */
-  const bills = events
-    .filter(e => e.eventType === ENERGY_EVENT.bill)
+  const bills = onceById(events.filter(e => e.eventType === ENERGY_EVENT.bill))
     .map(e => {
       const d = e.payload?.data ?? e.payload ?? {}
       return {
@@ -1077,6 +1223,19 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     })
     .filter(b => Number.isFinite(b.startMs) && Number.isFinite(b.endMs))
 
+  /* 발전 단가 — 기간마다 그때의 값이다(날마다 바뀐다). */
+  const generationPrices = onceById(events.filter(e => e.eventType === ENERGY_EVENT.generationPrice))
+    .map(e => {
+      const d = e.payload?.data ?? e.payload ?? {}
+      return {
+        startMs: Date.parse(String(d.from ?? '')),
+        endMs: Date.parse(String(d.to ?? '')),
+        unitPrice: Number(d.unitPrice),
+        currency: String(d.currency ?? '')
+      }
+    })
+    .filter(p => Number.isFinite(p.startMs) && Number.isFinite(p.endMs) && Number.isFinite(p.unitPrice) && p.currency)
+
   const leads: number[] = []
   const works: number[] = []
   const waits: number[] = []
@@ -1140,10 +1299,17 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
            * 다른 단가가 사라지고, 「피크를 깎아 얼마를 아끼나」가 그 차이 위에 선다.
            */
           /* 요금적용전력은 청구서가 먼저다 — 선언은 청구가 오지 않는 현장의 몫이다. */
+          /* 이 창의 최고 수요 — 사용 구간이 실어 온 값 중 가장 큰 것(원본 계량기가 잰 값이다). */
+          const peaks = usagePeriods
+            .filter(u => u.startMs >= window.fromMs && u.endMs <= window.toMs && Number.isFinite(u.maxKW))
+            .map(u => ({ kW: u.maxKW as number, toMs: u.endMs }))
+          const observedPeak = peaks.length ? peaks.reduce((a, x) => (x.kW > a.kW ? x : a)) : undefined
           const billingDemand = billingDemandOf(
             bills.filter(b => Number.isFinite(b.billingDemandKW)).map(b => ({ endMs: b.endMs, billingDemandKW: b.billingDemandKW })),
+            options.tariffBasis,
             options.lastBill,
-            options.tariff?.billingDemandKW
+            options.tariff?.billingDemandKW,
+            observedPeak
           )
           const cost = options.tariff
             ? electricityCost({
@@ -1176,7 +1342,24 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
                 feederShares(e.kWh, utilization, options.resourceFeeder)),
               /* 금액은 같은 창의 전력량·최대수요에서 나온다 — 창이 하나뿐이라 어긋날 수 없다. */
               ...(cost ? { cost } : {}),
-              ...generatedOfPeriods(generationPeriods, { startMs: window.fromMs, endMs: window.toMs }),
+              ...generatedOfPeriods(
+                generationPeriods,
+                { startMs: window.fromMs, endMs: window.toMs },
+                options.generationRated,
+                /* 창 안의 단가 사실이 먼저이고, 없으면 이어받은 마지막 단가를 쓴다. */
+                generationPrices.length
+                  ? generationPrices
+                  : options.generationPrice
+                    ? [
+                        {
+                          startMs: Date.parse(options.generationPrice.from),
+                          endMs: Date.parse(options.generationPrice.to),
+                          unitPrice: options.generationPrice.unitPrice,
+                          currency: options.generationPrice.currency
+                        }
+                      ]
+                    : []
+              ),
               /* 청구서는 사실이다 — 우리 계산을 덮지 않고 나란히 둔다(§`billOfWindow`). */
               ...(() => {
                 const b = billOfWindow(bills, { startMs: window.fromMs, endMs: window.toMs }, cost as any)