@things-factory/headless-twin 10.0.14 → 10.0.17

package/server/engine/kpi-query.ts

@@ -15,6 +15,8 @@
  * 어떤 기준을 썼는지는 결과의 `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'
@@ -49,20 +51,29 @@ 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']
 
-/** 한 번에 접을 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
+/** 한 번에 계산할 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000
 
+/**
+ * 종류를 나눠 물을 때 만들 갈래 수의 상한 — 대상 × 종류.
+ *
+ * 갈래마다 상한(`MAX_EVENTS`)까지 받아야 합친 결과가 정확하다(§`mergeStreams`). 그래서 갈래가 늘면
+ * 메모리가 그만큼 든다. 셋(종류) × 둘(트윈)까지는 최악에 12만 행이고, 그 이상은 예전 한 질의로 간다 —
+ * 느리지만 답은 같다.
+ */
+const KPI_MAX_SPLIT = 6
+
 export interface TwinKpiInput {
   domainId: string
   /** 한 트윈. `spaceId` 와 둘 중 하나는 있어야 한다. */
   instanceId?: string
   /**
-   * 한 **공간** — 그 공간에서 가동 중인 트윈 전부를 **한 번에 접는다**.
+   * 한 **공간** — 그 공간에서 가동 중인 트윈 전부를 **한 번에 계산한다**.
    *
-   * 트윈별로 접어 평균을 다시 평균하면 분위수가 거짓이 된다(p90 의 평균은 p90 이 아니다).
-   * 그래서 이벤트를 모아 **한 번** 접는다. 사용자는 "부산 창고" 를 보고, 그 안에 트윈이 몇 개든
+   * 트윈별로 계산해 평균을 다시 평균하면 분위수가 거짓이 된다(p90 의 평균은 p90 이 아니다).
+   * 그래서 이벤트를 모아 **한 번** 계산한다. 사용자는 "부산 창고" 를 보고, 그 안에 트윈이 몇 개든
    * 합쳐서 본다(헤더 트윈 셀렉터를 없앤 결정과 같은 규율).
    */
   spaceId?: string
@@ -76,14 +87,14 @@ export interface TwinKpiInput {
   lookbackMinutes?: number
   /**
    * 창을 N 등분해 **구간별 값도** 함께 낸다(추세용). 1~48, 기본 0(쪼개지 않음).
-   * 조회는 한 번이고 접기만 N 번 반복한다 — 폴드가 순수하므로 값싸다.
+   * 조회는 한 번이고 계산만 N 번 반복한다 — 폴드가 순수하므로 값싸다.
    */
   buckets?: number
   /**
    * 같은 사실을 **다른 관점으로** 쪼갠다: 자원별·작업종류별·도착지점별·오더별·구역별.
    *
    * 고정된 한 렌즈만 낼 수 있으면 "구역별로는 어떤가" 라는 질문에 화면도 AI 도 답할 수 없다.
-   * 축은 조회 인자 하나이고, 접기는 순수 함수라 축을 하나 더 보는 값이 거의 없다.
+   * 축은 조회 인자 하나이고, 계산는 순수 함수라 축을 하나 더 보는 값이 거의 없다.
    */
   groupBy?: KpiGroupBy
   /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 함께 알린다. */
@@ -92,12 +103,12 @@ export interface TwinKpiInput {
    * **무엇과 비교할 것인가** — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday).
    *
    * 숫자 하나로는 좋아졌는지 나빠졌는지 알 수 없다("29초" 가 개선인지 악화인지). 창만 옮겨 한 번 더
-   * 접으면 되므로(폴드는 순수) 값싸다. 비교 구간에 기록이 없으면 **delta 를 만들지 않는다** —
+   * 계산하면 되므로(폴드는 순수) 값싸다. 비교 구간에 기록이 없으면 **delta 를 만들지 않는다** —
    * 없는 것을 0% 로 그리면 "변화 없음" 이라는 거짓이 된다.
    */
   compareTo?: 'previous' | 'yesterday'
   /**
-   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 접어 **분포**와 그 안의 자리를 낸다.
+   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 계산해 **분포**와 그 안의 자리를 낸다.
    *
    * `compareTo` 는 한 구간만 봐서 판단이 "어제보다 나아졌다" 에서 멈춘다 — 어제도 나빴으면 쓸모가 없다.
    * 최근 며칠의 같은 시간대를 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
@@ -122,7 +133,7 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
   /**
    * 조회가 **상한에 걸렸는가**(구간이 너무 커서 일부만 읽었을 수 있다).
    *
-   * true 면 이 구간의 숫자는 **하한**이다 — 실제로는 더 있었을 수 있다. 조용히 잘라내면 숫자가 조용히
+   * true 면 이 구간의 숫자는 **하한**이다 — 실제로는 더 있었을 수 있다. 알리지 않고 잘라내면 숫자가 알리지 않고
    * 작아지고 사용자는 그것을 성과 하락으로 읽는다. 구간을 좁혀 다시 물어야 한다.
    */
   eventsCapped?: boolean
@@ -132,9 +143,9 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
    */
   measured: boolean
   note?: string
-  /** 무엇을 집계했나 — 공간이면 합쳐 접은 트윈 목록을 밝힌다(숫자의 출처를 숨기지 않는다). */
+  /** 무엇을 집계했나 — 공간이면 합쳐 계산한 트윈 목록을 밝힌다(숫자의 출처를 숨기지 않는다). */
   /**
-   * 무엇을 집계했나 — 공간이면 합쳐 접은 트윈 목록.
+   * 무엇을 집계했나 — 공간이면 합쳐 계산한 트윈 목록.
    *
    * `restartPolicies` 는 **이 숫자가 무엇의 성과인지**를 말한다: mirror(실제 시스템을 반영) ·
    * `resume`(이어지는 가상 세계) · `reset`(재현 실험 사본). 같은 "345건" 이 현실의 실적일 수도, 시뮬레이션의
@@ -152,7 +163,7 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
    */
   targets?: TargetVerdict[]
   /**
-   * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 접은 앞 구간과의 차이.
+   * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 계산한 앞 구간과의 차이.
    *
    * `measured:false` 면 그 구간에 기록이 없다는 뜻이고 `delta` 는 없다(0 이 아니다).
    * delta 는 **현재 − 비교구간** 이다. 좋고 나쁨은 판단하지 않는다 — 처리량은 클수록 좋고 소요는
@@ -212,7 +223,7 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
- * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * **집계에서 오류 없이 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
  * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
  */
 /**
@@ -338,7 +349,7 @@ async function locationAreaMap(
  *
  * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
  * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
- * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ * 밝힌다(알리지 않고 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
  */
 async function tariffOf(
   domainId: string,
@@ -357,11 +368,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 +383,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 +453,33 @@ 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
+}
+
 async function energyTopologyOf(
   domainId: string,
   instanceIds: string[],
@@ -465,15 +505,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 +614,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 +727,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' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
@@ -677,12 +832,23 @@ 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 kpi = foldKpi(events, { fromMs, toMs }, {
     groupBy: input.groupBy,
     locationArea: areaMap.locationArea,
     resourceFeeder: feederMap.resourceFeeder,
     meterFeeder: feederMap.meterFeeder,
     ...(tariffFound.tariff ? { tariff: tariffFound.tariff } : {}),
+    ...(lastBill ? { lastBill } : {}),
     ...shiftCtx,
     groupLimit: input.groupLimit
   })
@@ -691,14 +857,14 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
    *
    * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
    * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
-   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 알리지 않고 0 으로 세어진다.**
    *
    * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
    * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
    * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
    *
    * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
-   * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+   * 않는 사람도 알아야 하므로 로그에 남긴다 — 들어온 것이 없는 0 이 이 시스템에서 가장 비싼 침묵이다.
    *
    * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
    * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
@@ -741,7 +907,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 +949,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
       }))
     : undefined
 
-  /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 접는다. 기록이 없으면 delta 를 만들지 않는다
+  /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 계산한다. 기록이 없으면 delta 를 만들지 않는다
    * (없는 것을 0 으로 그리면 "변화 없음" 이라는 거짓이 된다). */
   let comparison: TwinKpiOutput['comparison']
   /* 관점 × 비교 교차 — 축별 delta 와 **사라진 축**(전에 있었고 지금 없는 것). */
@@ -799,13 +965,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
 }

package/server/engine/local-declarations.ts

@@ -25,7 +25,7 @@
  *
  * ── 왜 모델에 바로 쓰지 않고 겹으로 두나 ────────────────────────────────────
  * 모델은 **원천의 사본**이다. 다시 읽기(resync)는 그 사본을 새로 그리므로, 모델에 직접 쓴 값은 다음
- * 다시 읽기에서 **조용히 사라진다** — 요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다.
+ * 다시 읽기에서 **오류 없이 사라진다** — 요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다.
  * 그래서 로컬 선언은 따로 보관하고, 모델을 그릴 때마다 그 위에 얹는다. 덤으로 「누가 말한 값인가」에
  * 답할 수 있다 — 이 시스템이 근거를 값과 함께 다니게 하는 규율과 같다(`basis`·`derived` 와 한 결).
  *
@@ -56,7 +56,7 @@ export interface LocalDeclaration {
     /**
      * 단위(UN/CEFACT 코드) — **어떤 값은 단위 없이는 뜻이 없다.**
      *
-     * 속도가 그렇다: 단위가 없으면 이동 시간 추정기가 그 설비를 **거절한다**(그러면 공정 시간이 조용히
+     * 속도가 그렇다: 단위가 없으면 이동 시간 추정기가 그 설비를 **거절한다**(그러면 공정 시간이 알리지 않고
      * 사라진다). 명세가 단위를 요구하면(`uomChoices`) 받고, 그 목록에 없는 코드는 거절한다 — 읽는 쪽이
      * 모르는 단위를 받아 두면 화면은 넣었다고 말하고 계산은 그 값을 버린다.
      */
@@ -120,7 +120,7 @@ export interface RejectedDeclaration {
      * 그 이름의 공정을 이 트윈에서 확인할 수 없다 — 커널이 돌린 적도 없고 명세 행에도 없다.
      *
      * 공정 선언은 자리·설비와 달리 **모델에 행이 없어도 성립한다**(창고·야드에는 행이 아예 없다).
-     * 그래서 오타를 잡아 줄 것이 이름 대조뿐이다 — 그마저 없으면 값은 조용히 아무 일도 하지 않는다.
+     * 그래서 오타를 잡아 줄 것이 이름 대조뿐이다 — 그마저 없으면 값은 알리지 않고 아무 일도 하지 않는다.
      */
     | 'unknown-operation'
   /** 무엇을 기대했나 — 사람이 고칠 수 있게(명세의 문장). */
@@ -199,7 +199,7 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
    *
    * 혼잡 90%·불량 15%는 우리가 정한 수였다. 통로를 95%로 채워 쓰는 창고는 그 기준에서 영구히 「병목」
    * 이고, 초기 라인은 계속 「불량 과다」로 운다 — 그때 진짜 경보도 함께 묻힌다. 선언이 없으면 기본값을
-   * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(조용히 기본값을 진실로 두지 않는다).
+   * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(알리지 않고 기본값을 진실로 두지 않는다).
    */
   {
     id: ATTENTION_PROPERTY.congestionRatio,
@@ -276,7 +276,7 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
  * 공정 모수 표에 한 칸 담는다 — **커널이 읽는 표기 그대로**(수율 0..1, 셋업 ISO 8601).
  *
  * 표를 통째로 새로 만들어 얹는다: 같은 모델 객체를 여러 겹이 지나므로(현장 → 트윈) 그때마다 새 객체여야
- * 앞 겹의 것을 조용히 덮어쓰지 않는다.
+ * 앞 겹의 것을 알리지 않고 덮어쓰지 않는다.
  */
 function putParam(next: any, kind: string, paramId: string, value: string): void {
   const table = { ...(next.localParams ?? {}) }
@@ -321,7 +321,7 @@ export function declarablePropertySpecs(kind: string | undefined): DeclarablePro
 /**
  * 로컬 선언을 검사한다 — **받은 것과 받지 않은 것을 함께** 돌려준다.
  *
- * 조용히 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
+ * 알리지 않고 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
  */
 export function validateLocalDeclarations(
   kind: string | undefined,
@@ -342,7 +342,7 @@ export function validateLocalDeclarations(
     const target: DeclarationTarget = d?.target === 'equipment' ? 'equipment' : d?.target === 'operation' ? 'operation' : 'location'
     const id = String(d?.id ?? '').trim()
     if (!id) {
-      /* 어느 대상인지 모르면 얹을 자리가 없다 — 그 사실을 말한다(조용히 버리지 않는다). */
+      /* 어느 대상인지 모르면 얹을 자리가 없다 — 그 사실을 말한다(알리지 않고 버리지 않는다). */
       rejected.push({ target, id: '', propertyId: '', reason: 'no-target-id' })
       continue
     }
@@ -449,7 +449,7 @@ export function mergeLocalDeclarations(
  * 고쳐 넣었다는 것은 「원천의 값이 낡았다」는 뜻이다. 다만 그 사실이 보여야 하므로 `source: 'local'` 를
  * 값에 붙인다 — 화면·감사가 「누가 말한 값인가」를 되짚을 수 있다.
  *
- * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
+ * 모델에 없는 대상에 얹으려 하면 **알리지 않고 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
  * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
  */
 export function applyLocalDeclarations<
@@ -461,7 +461,7 @@ export function applyLocalDeclarations<
   model: T
   missingTargets: { target: string; id: string }[]
   /**
-   * 읽을 수 있는 값으로 바꿀 수 없었던 선언 — **조용히 버리지 않기 위한 자리.**
+   * 읽을 수 있는 값으로 바꿀 수 없었던 선언 — **알리지 않고 버리지 않기 위한 자리.**
    *
    * 지금은 공정 시간에서만 난다(단위가 없거나 수가 아니면 ISO 8601 기간을 만들 수 없다). 문에서 이미
    * 검사하므로 정상 경로에서는 비어 있고, 옛 겹이나 손으로 넣은 데이터에서 드러난다.
@@ -504,7 +504,7 @@ export function applyLocalDeclarations<
        *
        * 겹에는 단위를 담고도 모델에 얹을 때 떨어뜨리고 있었다 — 그러면 속도를 넣어도 이동 시간 추정기가
        * 그 설비를 **버린다**(「speed has no unit of measure」). 화면은 「넣었습니다」라고 말하고 계산은
-       * 그 값을 못 쓰는, 가장 조용한 종류의 결함이다.
+       * 그 값을 못 쓰는, 가장 들어온 것이 없는 종류의 결함이다.
        */
       const next = { id: p.id, value: String(p.value), ...((p as any).uom ? { uom: String((p as any).uom) } : {}), source: 'local' as const }
       if (at >= 0) props[at] = { ...props[at], ...next }
@@ -531,7 +531,7 @@ export function applyLocalDeclarations<
       const uom = String((p as any).uom ?? '')
       /*
        * 값을 **커널이 읽는 표기로** 바꿔 담는다 — 시간은 ISO 8601, 수율은 비율(0..1).
-       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(조용히 0 이나 빈 값으로 만들지 않는다).
+       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(알리지 않고 0 이나 빈 값으로 만들지 않는다).
        */
       if (p.id === OPERATION_PROPERTY.duration) {
         const iso = isoDurationOf(p.value, uom)
@@ -596,7 +596,7 @@ export interface RevokedDeclaration extends DeclarationRevocation {
 /**
  * 겹에서 선언을 **뺀다** — 값을 넣는 것과 다른 결정이므로 다른 문이다.
  *
- * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(조용히 성공하면
+ * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(알리지 않고 성공하면
  * 사용자는 지웠다고 믿고 값은 그대로 남는다 — 가장 비싼 종류의 침묵이다).
  *
  * 속성이 하나도 남지 않은 대상은 겹에서 사라진다(빈 껍데기를 남기지 않는다).
@@ -750,7 +750,7 @@ export function applyDeclarationLayers<
   instanceLayerApplied: LocalDeclaration[]
   /** 갈 곳이 없던 대상 — 어느 범위에서 났는지 함께 낸다(현장 겹은 그 트윈에 없을 수 있다). */
   missingTargets: { scope: DeclarationScope; target: string; id: string }[]
-  /** 읽을 수 있는 값으로 바꿀 수 없던 선언 — 범위와 함께(조용히 버리지 않는다). */
+  /** 읽을 수 있는 값으로 바꿀 수 없던 선언 — 범위와 함께(알리지 않고 버리지 않는다). */
   unreadable: { scope: DeclarationScope; target: string; id: string; propertyId: string }[]
 } {
   const first = applyLocalDeclarations(model, spaceLayer)

package/server/engine/log.ts

@@ -46,7 +46,7 @@ export function stamp(at: Date = new Date()): string {
  * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**
  *
  * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는
- * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.
+ * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **오류 없이 사라진다.** 그래서 여기서 문자열로 편다.
  * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
  */
 export function line(args: unknown[]): string {

package/server/engine/measured-estimator.ts

@@ -18,7 +18,7 @@
  *  - 표본이 적으면 쓰지 않는다(`minSamples`). 한두 건의 p50 은 그 현장의 값이 아니다.
  *  - 'unknown' 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
  *  - 퍼짐이 성립하지 않으면(p10 ≥ p90, 또는 0) **퍼짐 없이 평균만** 넘긴다. 없는 흔들림을 만들지 않는다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
  */
 
 /** 커널 `DurationEstimate` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */

package/server/engine/measured-yield.ts

@@ -18,7 +18,7 @@
  *    여기서도 `good + scrap` 만 쓴다 — `tasks` 를 분모로 쓰면 이동·체류가 섞여 양품률이 낮게 나온다.
  *  - **0 도 사실이다.** 전부 불량이면 0 을 배운다(그 현장이 그랬다). 「값이 없다」와 구별해 다룬다 —
  *    커널이 `0` 을 받으면 전량 불량으로 굴러가고, 그것이 관측과 같은 결론이다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
  */
 
 /** 커널 `YieldEstimator` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */

package/server/engine/model-basis.ts

@@ -7,7 +7,7 @@
  * 주면 **이중 보정**이 되어 정확도가 나빠진다. 학습 시점의 accAfter 도 더는 유효하지 않다.
  *
  * 그래서 보정 기록에 **그때 모델의 근거**를 함께 남기고, 적용 전에 지금 근거와 비교한다. 달라졌으면
- * 적용하지 않고 **그 사실을 응답에 싣는다**(조용히 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
+ * 적용하지 않고 **그 사실을 응답에 싣는다**(오류 없이 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
  *
  * 비교는 **상대 허용오차**로 한다(양자화 지문이 아니라). 실측 p50 은 새 기록이 쌓일 때마다 1~2초씩
  * 흔들리는데, 값을 버킷으로 합쳐 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
@@ -40,7 +40,7 @@ export interface ModelBasis {
    * 선언된 공정 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델).
    *
    * **변동폭도 지문에 든다.** 변동폭이 허용오차를 정하므로(§toleranceOf), 그것이 바뀌었는데 "같은 모델"
-   * 이라고 하면 판정의 잣대가 조용히 바뀐 채로 학습이 이어진다.
+   * 이라고 하면 판정의 잣대가 알리지 않고 바뀐 채로 학습이 이어진다.
    */
   declared?: DeclaredOperation[]
 }