@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/engine/kpi-query.ts

@@ -15,9 +15,12 @@
  * 어떤 기준을 썼는지는 결과의 `window.basis` 로 밝힌다 — 숨기면 사용자가 숫자를 오해한다.
  */
 import { twinWarn } from './log.js'
+import { mergeStreams } from '../service/twin-journal/event-type-split-shape.js'
+import { hydratedDate } from './read-time.js'
 import { Between, In } from 'typeorm'
 
-import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY, type TariffDeclaration } from '@operato/twin-kernel'
+import { type TariffDeclaration } from '@operato/twin-kernel'
+import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY } from '@operato/ops-contract'
 
 import { getReadRepository, getRepository } from '@things-factory/shell'
 
@@ -49,20 +52,49 @@ import { MAX_BASELINE_PERIODS, baselineWindows, summarizeBaseline, type Baseline
  * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
  * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
  */
-const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window']
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill', 'energy.generation.price']
 
-/** 한 번에 접을 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
+/** 한 번에 계산할 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000
 
+/**
+ * 종류를 나눠 물을 때 만들 갈래 수의 상한 — 대상 × 종류.
+ *
+ * 갈래마다 상한(`MAX_EVENTS`)까지 받아야 합친 결과가 정확하다(§`mergeStreams`). 그래서 갈래가 늘면
+ * 메모리가 그만큼 든다. 셋(종류) × 둘(트윈)까지는 최악에 12만 행이고, 그 이상은 예전 한 질의로 간다 —
+ * 느리지만 답은 같다.
+ */
+/*
+ * ── 나눠 물을 수 있는 갈래의 최대 (2026-08-30 실측) ──────────────────────────
+ *
+ * 6 이었다. 그런데 **한 현장에 트윈이 여럿인 것이 이 제품의 정상**이다(창고·공정·야드가 한 현실을
+ * 각각 본다). 트윈 3개 × 종류 6가지 = 18 이라 조건에 안 걸렸고, 한 질의로 떨어졌다.
+ *
+ * 같은 창·같은 행으로 두 모양을 쟀다(hatio-us, order.status 345만 건이 있는 하루):
+ *
+ *   한 질의(종류 IN + 시각순)   ix_twin_event_1 로 그 날 전체를 걷는다   25.987초 · 20,000건(잘림)
+ *   갈래 하나(종류 정확일치)     ix_twin_event_7 이 순서까지 준다          0.286초
+ *
+ * 91배다. 그리고 25초를 기다린 끝에 나오는 값이 **잘린 값**이다 — 사용자는 그 사실을 25초 뒤에 본다.
+ *
+ * ── 늘리는 대가 ────────────────────────────────────────────────────────────
+ * 갈래마다 상한까지 받아야 합칠 때 정확하므로(§`mergeStreams`), 갈래가 많으면 그만큼 든다.
+ * 최악은 `갈래 수 × MAX_EVENTS` 행이다. 다만 그 최악은 **모든 갈래가 창을 가득 채울 때**이고,
+ * 그때는 어차피 결과가 잘린다(그 사실은 `capped` 로 나간다).
+ *
+ * 32 는 트윈 4개 × 종류 8가지를 덮는다. 어휘가 더 늘면 이 수를 다시 재고 정한다.
+ */
+const KPI_MAX_SPLIT = 32
+
 export interface TwinKpiInput {
   domainId: string
   /** 한 트윈. `spaceId` 와 둘 중 하나는 있어야 한다. */
   instanceId?: string
   /**
-   * 한 **공간** — 그 공간에서 가동 중인 트윈 전부를 **한 번에 접는다**.
+   * 한 **공간** — 그 공간에서 가동 중인 트윈 전부를 **한 번에 계산한다**.
    *
-   * 트윈별로 접어 평균을 다시 평균하면 분위수가 거짓이 된다(p90 의 평균은 p90 이 아니다).
-   * 그래서 이벤트를 모아 **한 번** 접는다. 사용자는 "부산 창고" 를 보고, 그 안에 트윈이 몇 개든
+   * 트윈별로 계산해 평균을 다시 평균하면 분위수가 거짓이 된다(p90 의 평균은 p90 이 아니다).
+   * 그래서 이벤트를 모아 **한 번** 계산한다. 사용자는 "부산 창고" 를 보고, 그 안에 트윈이 몇 개든
    * 합쳐서 본다(헤더 트윈 셀렉터를 없앤 결정과 같은 규율).
    */
   spaceId?: string
@@ -76,14 +108,14 @@ export interface TwinKpiInput {
   lookbackMinutes?: number
   /**
    * 창을 N 등분해 **구간별 값도** 함께 낸다(추세용). 1~48, 기본 0(쪼개지 않음).
-   * 조회는 한 번이고 접기만 N 번 반복한다 — 폴드가 순수하므로 값싸다.
+   * 조회는 한 번이고 계산만 N 번 반복한다 — 폴드가 순수하므로 값싸다.
    */
   buckets?: number
   /**
    * 같은 사실을 **다른 관점으로** 쪼갠다: 자원별·작업종류별·도착지점별·오더별·구역별.
    *
    * 고정된 한 렌즈만 낼 수 있으면 "구역별로는 어떤가" 라는 질문에 화면도 AI 도 답할 수 없다.
-   * 축은 조회 인자 하나이고, 접기는 순수 함수라 축을 하나 더 보는 값이 거의 없다.
+   * 축은 조회 인자 하나이고, 계산는 순수 함수라 축을 하나 더 보는 값이 거의 없다.
    */
   groupBy?: KpiGroupBy
   /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 함께 알린다. */
@@ -92,12 +124,12 @@ export interface TwinKpiInput {
    * **무엇과 비교할 것인가** — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday).
    *
    * 숫자 하나로는 좋아졌는지 나빠졌는지 알 수 없다("29초" 가 개선인지 악화인지). 창만 옮겨 한 번 더
-   * 접으면 되므로(폴드는 순수) 값싸다. 비교 구간에 기록이 없으면 **delta 를 만들지 않는다** —
+   * 계산하면 되므로(폴드는 순수) 값싸다. 비교 구간에 기록이 없으면 **delta 를 만들지 않는다** —
    * 없는 것을 0% 로 그리면 "변화 없음" 이라는 거짓이 된다.
    */
   compareTo?: 'previous' | 'yesterday'
   /**
-   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 접어 **분포**와 그 안의 자리를 낸다.
+   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 계산해 **분포**와 그 안의 자리를 낸다.
    *
    * `compareTo` 는 한 구간만 봐서 판단이 "어제보다 나아졌다" 에서 멈춘다 — 어제도 나빴으면 쓸모가 없다.
    * 최근 며칠의 같은 시간대를 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
@@ -122,7 +154,7 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
   /**
    * 조회가 **상한에 걸렸는가**(구간이 너무 커서 일부만 읽었을 수 있다).
    *
-   * true 면 이 구간의 숫자는 **하한**이다 — 실제로는 더 있었을 수 있다. 조용히 잘라내면 숫자가 조용히
+   * true 면 이 구간의 숫자는 **하한**이다 — 실제로는 더 있었을 수 있다. 알리지 않고 잘라내면 숫자가 알리지 않고
    * 작아지고 사용자는 그것을 성과 하락으로 읽는다. 구간을 좁혀 다시 물어야 한다.
    */
   eventsCapped?: boolean
@@ -132,9 +164,9 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
    */
   measured: boolean
   note?: string
-  /** 무엇을 집계했나 — 공간이면 합쳐 접은 트윈 목록을 밝힌다(숫자의 출처를 숨기지 않는다). */
+  /** 무엇을 집계했나 — 공간이면 합쳐 계산한 트윈 목록을 밝힌다(숫자의 출처를 숨기지 않는다). */
   /**
-   * 무엇을 집계했나 — 공간이면 합쳐 접은 트윈 목록.
+   * 무엇을 집계했나 — 공간이면 합쳐 계산한 트윈 목록.
    *
    * `restartPolicies` 는 **이 숫자가 무엇의 성과인지**를 말한다: mirror(실제 시스템을 반영) ·
    * `resume`(이어지는 가상 세계) · `reset`(재현 실험 사본). 같은 "345건" 이 현실의 실적일 수도, 시뮬레이션의
@@ -152,7 +184,7 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
    */
   targets?: TargetVerdict[]
   /**
-   * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 접은 앞 구간과의 차이.
+   * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 계산한 앞 구간과의 차이.
    *
    * `measured:false` 면 그 구간에 기록이 없다는 뜻이고 `delta` 는 없다(0 이 아니다).
    * delta 는 **현재 − 비교구간** 이다. 좋고 나쁨은 판단하지 않는다 — 처리량은 클수록 좋고 소요는
@@ -212,7 +244,7 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
- * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * **집계에서 오류 없이 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
  * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
  */
 /**
@@ -338,7 +370,7 @@ async function locationAreaMap(
  *
  * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
  * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
- * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ * 밝힌다(알리지 않고 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
  */
 async function tariffOf(
   domainId: string,
@@ -357,11 +389,14 @@ async function tariffOf(
       }
       const d = num(EMS_PROPERTY.demandChargePerKW)
       const e = num(EMS_PROPERTY.energyChargePerKWh)
+      /* 요금적용전력 — 있으면 기본요금이 조건부 파생이 아니라 사실이 된다(§`electricityCost`). */
+      const b = num(EMS_PROPERTY.billingDemandKW)
       const cur = props.get(EMS_PROPERTY.currency)
       if (d === undefined && e === undefined) continue
       found.push({
         ...(d !== undefined ? { demandChargePerKW: d } : {}),
         ...(e !== undefined ? { energyChargePerKWh: e } : {}),
+        ...(b !== undefined ? { billingDemandKW: b } : {}),
         ...(cur ? { currency: String(cur) } : {})
       })
     }
@@ -369,7 +404,11 @@ async function tariffOf(
   if (!found.length) return {}
   const first = found[0]
   const same = found.every(
-    t => t.demandChargePerKW === first.demandChargePerKW && t.energyChargePerKWh === first.energyChargePerKWh && t.currency === first.currency
+    t =>
+      t.demandChargePerKW === first.demandChargePerKW &&
+      t.energyChargePerKWh === first.energyChargePerKWh &&
+      t.billingDemandKW === first.billingDemandKW &&
+      t.currency === first.currency
   )
   return { tariff: first, ...(same ? {} : { conflict: true }) }
 }
@@ -435,11 +474,86 @@ async function resourceFeederMap(
 }
 
 /**
- * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 접는다.
+ * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 처리한다.
  *
  * 여러 트윈이 한 공간에 있으면 **각 트윈의 뿌리를 나란히** 둔다(하나로 합치면 없는 결선을 그리게 된다).
  * 에너지 트윈이 없으면 만들지 않는다 — 빈 그림은 고장으로 읽힌다.
  */
+/**
+ * 이 트윈들이 이어받고 있는 **마지막 청구서** — 요금적용전력의 우선 근거.
+ *
+ * 저널이 아니라 상태에서 읽는 이유: 청구는 한 달에 한 번이라 하루 창의 조회에는 걸리지 않는다.
+ * 그런데 그 값은 **그 창에도 적용된다**(요금 제도가 그렇게 군다). 커널이 재기동에서도 이어받으므로
+ * 상태가 그 자리다.
+ *
+ * 트윈이 여럿이면 가장 늦게 끝난 것을 쓴다 — 현장 하나에 청구가 여럿이면 그것은 다른 문제이고,
+ * 여기서 골라 감추지 않는다.
+ */
+function latestBillOf(domainId: string, instanceIds: string[]): { to: string; billingDemandKW?: number } | undefined {
+  let best: { to: string; billingDemandKW?: number } | undefined
+  for (const instanceId of instanceIds) {
+    const bill = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.lastBill
+    if (!bill?.to) continue
+    if (!best || Date.parse(bill.to) > Date.parse(best.to)) {
+      best = { to: String(bill.to), ...(Number.isFinite(Number(bill.billingDemandKW)) ? { billingDemandKW: Number(bill.billingDemandKW) } : {}) }
+    }
+  }
+  return best
+}
+
+/** 이 트윈들이 이어받고 있는 **발전 단가** — 창 안에 단가 사실이 없을 때 쓴다. */
+function latestGenerationPriceOf(
+  domainId: string,
+  instanceIds: string[]
+): { from: string; to: string; unitPrice: number; currency: string } | undefined {
+  let best: { from: string; to: string; unitPrice: number; currency: string } | undefined
+  for (const instanceId of instanceIds) {
+    const p = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.generationPrice
+    if (!p?.from || !Number.isFinite(Number(p.unitPrice)) || !p.currency) continue
+    if (!best || Date.parse(p.from) > Date.parse(best.from)) {
+      best = { from: String(p.from), to: String(p.to), unitPrice: Number(p.unitPrice), currency: String(p.currency) }
+    }
+  }
+  return best
+}
+
+/**
+ * 이 트윈들의 **발전 정격** — 이용률의 분모.
+ *
+ * 커널이 고른다(설비 합 → 자리 합계, 교류 → 직류). 여러 트윈이면 합한다 — 한 현장의 발전은
+ * 트윈마다 나뉘어 있어도 같은 현장의 발전이다. 근거가 갈리면 약한 쪽(직류·자리)으로 적는다.
+ */
+function generationRatedOf(
+  domainId: string,
+  instanceIds: string[]
+): { kW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location' } | undefined {
+  let kW = 0
+  let basis: 'ac' | 'dc' = 'ac'
+  let from: 'equipment' | 'location' = 'equipment'
+  for (const instanceId of instanceIds) {
+    /* 스냅샷에서 읽는다 — 커널이 고른 값이다. 여기서 모델을 다시 뒤지면 고르는 규칙이 두 벌이 된다. */
+    const r = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.generationRated
+    if (!r || !(Number(r.kW) > 0)) continue
+    kW += Number(r.kW)
+    if (r.basis === 'dc') basis = 'dc'
+    if (r.from === 'location') from = 'location'
+  }
+  return kW > 0 ? { kW, basis, from } : undefined
+}
+
+/** 이 트윈들이 이어받고 있는 **요금 기준** — 이 주기에 적용되는 값(청구서보다 먼저다). */
+function latestTariffBasisOf(domainId: string, instanceIds: string[]): { from: string; billingDemandKW?: number } | undefined {
+  let best: { from: string; billingDemandKW?: number } | undefined
+  for (const instanceId of instanceIds) {
+    const b = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.tariffBasis
+    if (!b?.from) continue
+    if (!best || Date.parse(b.from) > Date.parse(best.from)) {
+      best = { from: String(b.from), ...(Number.isFinite(Number(b.billingDemandKW)) ? { billingDemandKW: Number(b.billingDemandKW) } : {}) }
+    }
+  }
+  return best
+}
+
 async function energyTopologyOf(
   domainId: string,
   instanceIds: string[],
@@ -465,15 +579,50 @@ async function energyTopologyOf(
   return merged.roots.length ? merged : undefined
 }
 
-/** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
+/**
+ * 이 대상들의 **마지막 업무 기록 시각**(ISO). 기록이 없으면 null.
+ *
+ * ── 두 가지를 함께 고쳤다 (2026-08-28 실측) ─────────────────────────────────
+ * 예전 판은 이랬다.
+ *
+ *   findOne({ where: { domain: { id }, instanceId: In(…), eventType: In(셋) }, order: { revision: 'DESC' } })
+ *
+ * **① 관계로 물어 두 단계 질의가 된다.** 안쪽에 상한이 없어 조건에 맞는 행을 **전부 만든 뒤** 하나를
+ * 고른다 — 그 트윈의 업무 사실이 97만 행이고 `payload` 까지 실려 온다. 이 파일의 다른 자리가 같은 것을
+ * 실측해 적어 두었다(§`twinEvents`: 0.024초 대 12초). 서버 로그에 「느린 질의」로 찍혀 있던 것이
+ * 이것이고, 현장 성과 화면의 7.2초가 여기서 나왔다.
+ *
+ * **② 「마지막 시각」을 원하면서 `revision` 으로 정렬했다.** 그 둘은 어긋난다 — 연결된 시스템을 되읽는
+ * 트윈은 원본의 시각을 싣고 도착 순서로 리비전을 받으므로, 리비전이 가장 큰 행이 4월 사실일 수 있다
+ * (같은 어긋남을 오늘 저널 목록에서도 고쳤다). 창의 끝을 그 값으로 잡으면 **창 자체가 틀린다.**
+ *
+ * 지금은 종류마다 `MAX(eventTime)` 을 묻는다. `(domain, instance, event_type, event_time)` 색인의
+ * 끝을 집으므로 종류당 한 번이고, 셋 중 가장 늦은 것이 답이다.
+ */
 async function latestEventTime(domainId: string, instanceIds: string[]): Promise<string | null> {
   if (instanceIds.length === 0) return null
-  const row = await getRepository(TwinEvent).findOne({
-    where: { domain: { id: domainId }, instanceId: In(instanceIds), eventType: In(BUSINESS_EVENTS) },
-    order: { revision: 'DESC' }
-  })
-  /* 소비처는 ISO 문자열을 기대한다(시각 축의 공용 표기) — 컬럼이 날짜가 됐으므로 여기서 옮긴다. */
-  return row?.eventTime ? row.eventTime.toISOString() : null
+  const rows = await Promise.all(
+    instanceIds.flatMap(instanceId =>
+      BUSINESS_EVENTS.map(eventType =>
+        getReadRepository(TwinEvent)
+          .createQueryBuilder('e')
+          .select('MAX(e.eventTime)', 'at')
+          .where('e.domain = :domainId', { domainId })
+          .andWhere('e.instanceId = :instanceId', { instanceId })
+          .andWhere('e.eventType = :eventType', { eventType })
+          .getRawOne<{ at: unknown }>()
+          .catch(() => null)
+      )
+    )
+  )
+  /* 드라이버가 준 값은 시간대가 없을 수 있다 — 컬럼 변환을 지나게 한다(§`hydratedDate`). */
+  const repo = getReadRepository(TwinEvent)
+  let latest: Date | null = null
+  for (const r of rows) {
+    const at = hydratedDate(repo, 'eventTime', r?.at)
+    if (at && (!latest || at.getTime() > latest.getTime())) latest = at
+  }
+  return latest ? latest.toISOString() : null
 }
 
 /**
@@ -539,24 +688,82 @@ async function fetchEvents(domainId: string, instanceIds: string[], fromMs: numb
    * 남는 비용을 감추지 않는다: `payload` 파싱은 여전히 메인 스레드 일이고 연결을 나눠도 나뉘지 않는다
    * (실측 평균 1.5초). 그것을 더 줄이려면 폴드가 payload 에서 무엇을 쓰는지 좁혀야 한다 — 별 건이다.
    */
-  const raw = await getReadRepository(TwinEvent)
-    .createQueryBuilder('e')
-    .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.payload AS "payload"'])
-    .where('e.domain = :domainId', { domainId })
-    .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
-    .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
-    .andWhere('e.eventTime BETWEEN :from AND :to', { from: new Date(fromMs - lookbackMs), to: new Date(toMs) })
-    .orderBy('e.eventTime', 'ASC')
-    .addOrderBy('e.revision', 'ASC')
-    .limit(MAX_EVENTS)
-    .getRawMany<{ eventType: string; eventTime: unknown; payload: unknown }>()
-
-  /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
+  const from = new Date(fromMs - lookbackMs)
+  const to = new Date(toMs)
+
+  /**
+   * 한 갈래를 묻는다 — **종류를 정확일치로** 준다. 그것이 이 고침의 요점이다.
+   */
+  const readOne = (instanceId: string, eventType: string) =>
+    getReadRepository(TwinEvent)
+      .createQueryBuilder('e')
+      .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.revision AS "revision"', 'e.payload AS "payload"'])
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .andWhere('e.eventType = :eventType', { eventType })
+      .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
+      .orderBy('e.eventTime', 'ASC')
+      .addOrderBy('e.revision', 'ASC')
+      .limit(MAX_EVENTS)
+      .getRawMany<{ eventType: string; eventTime: unknown; revision: unknown; payload: unknown }>()
+
+  /*
+   * ── **종류를 나눠 묻는다** (2026-08-28 실측) ────────────────────────────────
+   *
+   * 예전에는 `eventType IN (셋)` + 시각 범위 + 시각순이었다. 그 모양에서 sqlite 는 종류 색인을 버리고
+   * 시각 색인으로 **구간 전체를 걸으며 행마다 종류를 확인한다.** 승화푸드(저널 3,140만행) 실측:
+   *
+   *   창 1시간    구간 안 0행 · 쓰는 행 0          40밀리초
+   *   창 24시간   구간 안 254,185행 · 쓰는 행 0   3,776밀리초   ← 25만 행을 걸어 0건을 쓴다
+   *   창 7일      구간 안 2,070,625행 · 34,143    173밀리초    ← 상한에 일찍 닿아 오히려 빠르다
+   *
+   * 창을 넓히면 빨라지는 것 자체가 신호였다. 종류를 정확일치로 물으면
+   * `ix_twin_event_7 (domain, instance, event_type, event_time)` 이 범위까지 색인에서 준다.
+   *
+   * 나눌 수를 제한한다 — 갈래마다 상한까지 받아야 정확하므로(§`mergeStreams`) 갈래가 많으면 메모리가
+   * 그만큼 든다. 넘으면 예전 한 질의로 간다(느리지만 답은 같다).
+   */
+  const pairs = instanceIds.length * BUSINESS_EVENTS.length
+  let raw: { eventType: string; eventTime: unknown; revision: unknown; payload: unknown }[]
+  let mergedCapped = false
+  if (pairs && pairs <= KPI_MAX_SPLIT) {
+    const streams = await Promise.all(
+      instanceIds.flatMap(instanceId => BUSINESS_EVENTS.map(eventType => readOne(instanceId, eventType)))
+    )
+    const merged = mergeStreams(streams, MAX_EVENTS, (a, b) => {
+      const at = String(a.eventTime ?? '').localeCompare(String(b.eventTime ?? ''))
+      if (at !== 0) return at
+      return Number(a.revision ?? 0) - Number(b.revision ?? 0)
+    })
+    if (merged.underfilled) {
+      /* 있을 수 없는 일이다 — 갈래가 상한보다 많이 받아 왔다. 조용히 쓰지 않고 말한다. */
+      twinWarn('[twin-kpi] a per-type stream returned more than the cap — the merge cannot be trusted; falling back')
+      raw = []
+    } else {
+      raw = merged.items
+      mergedCapped = merged.capped
+    }
+  } else {
+    raw = await getReadRepository(TwinEvent)
+      .createQueryBuilder('e')
+      .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.revision AS "revision"', 'e.payload AS "payload"'])
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
+      .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
+      .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
+      .orderBy('e.eventTime', 'ASC')
+      .addOrderBy('e.revision', 'ASC')
+      .limit(MAX_EVENTS)
+      .getRawMany<{ eventType: string; eventTime: unknown; revision: unknown; payload: unknown }>()
+    mergedCapped = raw.length >= MAX_EVENTS
+  }
+
+  /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 알리지 않고 잘라내면 숫자가 알리지 않고
    * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
   return {
     /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
     events: raw.map(r => ({ eventType: r.eventType, eventTime: isoOf(r.eventTime), payload: jsonOf(r.payload) })),
-    capped: raw.length >= MAX_EVENTS
+    capped: mergedCapped
   }
 }
 
@@ -594,15 +801,37 @@ function jsonOf(v: unknown): any {
 /**
  * 집계 대상 트윈 목록.
  *
- * 공간이 주어지면 **가동 중이고 운영 목적인** 것만 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
+ * 공간이 주어지면 그 공간의 **운영 목적** 트윈을 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
  * 트윈이 지정되면 그것 하나. 둘 다 없으면 무엇을 재야 할지 알 수 없으므로 명시 실패한다.
+ *
+ * ── **「지금 도는가」로 걸러내지 않는다** (2026-08-28 실측) ──────────────────
+ * 여기에 `running` 조건이 있었다. 그래서 멈춘 트윈은 현장으로 물었을 때 대상에서 빠졌고, 화면은
+ * 「기록이 없습니다」라고 말했다 — **저널에는 있는데.**
+ *
+ *   twinEventList(instanceId: "ems-plant-1")      1,792건
+ *   twinEventList(spaceId:    "ems-plant-1-site")     0건   ← 같은 트윈, 같은 도메인
+ *
+ * 규모로 보면 이것은 예외가 아니라 기본값이었다: 등록된 트윈 30개 중 **도는 것이 2개, 멈춘 것이 28개**다.
+ * 즉 현장으로 묻는 저널 조회가 대부분의 현장에서 거짓 「없다」를 냈다.
+ *
+ * 지운 이유는 두 가지다.
+ *
+ *  ① **저널은 기록이고, 프로세스가 지금 도는지는 다른 축이다.** 창 안에 있는 사실은 사실이다.
+ *     아래 줄이 트윈을 지정한 경우에 대해 이미 그 원칙을 적어 두었다(「정지·비등록이어도 저널은 남아
+ *     있을 수 있다」). 같은 원칙이 현장 경로에만 적용되지 않고 있었다.
+ *  ② 옛 주석이 대는 이유(「벤치 사본은 사용자가 보는 현장이 아니다」)는 **벤치 제외만** 설명한다.
+ *     `running` 에는 근거가 적혀 있지 않았다.
+ *
+ * **바뀌는 것**: 현장 KPI 가 이제 멈춘 트윈의 지난 기록도 센다. 창 안의 사실을 세는 것이 그 지표의
+ * 정의이므로 그것이 맞다. 「지금 도는 것만」이 필요한 화면이 생기면 그때 **이름 있는 축**으로 받는다 —
+ * 여기에 숨겨 두면 두 물음이 한 칸을 쓴다.
  */
 async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: string[]; restartPolicies: string[] }> {
   if (!input.instanceId && !input.spaceId) throw new Error('either instanceId or spaceId is required')
   const list = await TwinEngine.list(input.domainId)
   const rows = input.instanceId
     ? list.filter((x: any) => x?.instanceId === input.instanceId)
-    : list.filter((x: any) => x?.running && x.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId)
+    : list.filter((x: any) => x?.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId)
   /* 목록에서 못 찾아도(정지·비등록) 지정된 트윈은 그대로 조회한다 — 저널은 남아 있을 수 있다. */
   const instanceIds = rows.length ? rows.map((x: any) => x.instanceId as string) : input.instanceId ? [input.instanceId] : []
   /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
@@ -655,7 +884,19 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
             : 'no operational events in the journal yet — there is nothing to measure (this is NOT "zero throughput").'
       }
     }
-    toMs = Date.parse(latest)
+    /*
+     * ── **미래를 성과 구간으로 삼지 않는다** (2026-08-30) ──────────────────────
+     *
+     * 마지막 기록이 미래일 수 있다. 한 원본이 **끝나지 않은 이번 달**의 요금 정보를 청구서로 보냈고,
+     * 청구서의 사건 시각은 기간의 끝이라 그 사실이 **내일** 일어난 것으로 적혔다. 그러자 구간이
+     * `내일 00:00 → 모레 00:00` 이 되어 그 현장의 화면에서 **어제 발전량이 사라졌다.** 오류는 나지
+     * 않았고 화면만 비어 있었다.
+     *
+     * 커널이 이제 그런 사실을 받지 않는다. 그래도 여기서 막는다 — **이미 적힌 것은 사라지지 않고**,
+     * 저널은 지우지 않기 때문이다. 그리고 성과는 지나간 일이다. 아직 오지 않은 구간의 성과라는 것은
+     * 없다.
+     */
+    toMs = Math.min(Date.parse(latest), Date.now())
     basis = 'latest-event'
   }
 
@@ -677,12 +918,30 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
   const feederMap = await resourceFeederMap(input.domainId, instanceIds)
   /* 요금 단가도 축과 무관하게 읽는다 — 금액은 같은 창의 전력량·최대수요에서 나오는 사실이다. */
   const tariffFound = await tariffOf(input.domainId, instanceIds)
+  /*
+   * ── 요금적용전력은 **청구서가 먼저다** (2026-08-29) ─────────────────────────
+   *
+   * 그 값은 최근 몇 달의 최고 수요로 **매달 다시 정해진다.** 선언에 박아 두면 매달 사람이 갱신해야
+   * 하고, 안 하면 낡은 값으로 기본요금이 조용히 틀린다.
+   *
+   * 원본이 청구서에 그 값을 실어 매일 보낸다. 창 밖의 청구서는 저널 조회에 걸리지 않으므로
+   * **커널 상태에 이어져 있는 마지막 청구서**를 함께 넘긴다(§`EnergyState.lastBill`).
+   */
+  const lastBill = latestBillOf(input.domainId, instanceIds)
+  const tariffBasis = latestTariffBasisOf(input.domainId, instanceIds)
+  /* 이용률의 분모 — 커널이 모델의 선언에서 고른다(설비 합 → 자리 합계, 교류 → 직류). */
+  const generationRated = generationRatedOf(input.domainId, instanceIds)
+  const generationPrice = latestGenerationPriceOf(input.domainId, instanceIds)
   const kpi = foldKpi(events, { fromMs, toMs }, {
     groupBy: input.groupBy,
     locationArea: areaMap.locationArea,
     resourceFeeder: feederMap.resourceFeeder,
     meterFeeder: feederMap.meterFeeder,
     ...(tariffFound.tariff ? { tariff: tariffFound.tariff } : {}),
+    ...(lastBill ? { lastBill } : {}),
+    ...(tariffBasis ? { tariffBasis } : {}),
+    ...(generationRated ? { generationRated } : {}),
+    ...(generationPrice ? { generationPrice } : {}),
     ...shiftCtx,
     groupLimit: input.groupLimit
   })
@@ -691,14 +950,14 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
    *
    * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
    * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
-   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 알리지 않고 0 으로 세어진다.**
    *
    * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
    * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
    * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
    *
    * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
-   * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+   * 않는 사람도 알아야 하므로 로그에 남긴다 — 들어온 것이 없는 0 이 이 시스템에서 가장 비싼 침묵이다.
    *
    * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
    * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
@@ -741,7 +1000,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     for (const w of windows) {
       const { events: pastEvents, capped: pastCapped } = await fetchEvents(input.domainId, instanceIds, w.fromMs, w.toMs, lookbackMs)
       baseCapped = baseCapped || pastCapped
-      /* 축 없이, **같은 교대 정의**로 접는다(정의가 다르면 같은 시간대가 아니게 된다). */
+      /* 축 없이, **같은 교대 정의**로 처리한다(정의가 다르면 같은 시간대가 아니게 된다). */
       const past = foldKpi(pastEvents, w, { locationArea: areaMap.locationArea, ...shiftCtx })
       const values: Partial<Record<TwinMetricId, number | undefined>> = {}
       for (const metric of Object.keys(TWIN_METRIC) as TwinMetricId[]) values[metric] = TWIN_METRIC[metric].of(past)
@@ -783,7 +1042,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
       }))
     : undefined
 
-  /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 접는다. 기록이 없으면 delta 를 만들지 않는다
+  /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 계산한다. 기록이 없으면 delta 를 만들지 않는다
    * (없는 것을 0 으로 그리면 "변화 없음" 이라는 거짓이 된다). */
   let comparison: TwinKpiOutput['comparison']
   /* 관점 × 비교 교차 — 축별 delta 와 **사라진 축**(전에 있었고 지금 없는 것). */
@@ -799,13 +1058,13 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
       w.toMs,
       lookbackMs
     )
-    /* 축이 요청됐으면 비교 구간도 **같은 축**으로 접는다 — 교차("구역별로 어제 대비")를 내기 위해.
+    /* 축이 요청됐으면 비교 구간도 **같은 축**으로 처리한다 — 교차("구역별로 어제 대비")를 내기 위해.
      * 상한은 축이 서로 어긋나지 않게 넉넉히 둔다(현재 축이 상한 안에 있는데 비교 축에서 밀려나면
      * 있는데 없다고 말하게 된다). */
     const prev = foldKpi(prevEvents, w, {
       groupBy: input.groupBy,
       locationArea: areaMap.locationArea,
-      ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 접는다(정의가 다르면 축이 어긋난다)
+      ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 처리한다(정의가 다르면 축이 어긋난다)
       groupLimit: input.groupBy ? 100 : undefined
     })
     prevCappedFlag = prevCapped

package/server/engine/live-feed-registry.ts

@@ -29,7 +29,7 @@ export function registerLiveFeedProbe(probe: LiveFeedProbe): void {
  * 피드가 붙어 있나 — 어느 장부든 그렇다고 하면 그렇다.
  *
  * 장부가 터지는 것을 이 판정 전체의 실패로 만들지 않는다: 한 계층이 답하지 못해도 다른 계층의 사실은
- * 그대로 참이다. 다만 **조용히 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.
+ * 그대로 참이다. 다만 **알리지 않고 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.
  */
 export function liveFeedAttached(instanceId: string): boolean {
   for (const probe of probes) {

package/server/engine/load-meter.ts

@@ -63,7 +63,7 @@ export interface LoadMeter {
   overBudget: number
   /**
    * 마지막 경고 시각(ms). **한 번도 안 했으면 `-Infinity`** — 0 으로 두면 "0 시점에 경고했다" 가 되어
-   * 첫 느린 틱이 조용히 지나간다(검사가 그것을 잡았다).
+   * 첫 느린 틱이 알리지 않고 지나간다(검사가 그것을 잡았다).
    */
   lastWarnMs: number
 }