@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/engine/kpi-query.ts

@@ -16,7 +16,7 @@
  */
 import { Between, In } from 'typeorm'
 
-import { hierarchyOf } from '@operato/twin-kernel'
+import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY, type TariffDeclaration } from '@operato/twin-kernel'
 
 import { getRepository } from '@things-factory/shell'
 
@@ -25,8 +25,9 @@ import { TwinInstance } from '../service/twin-instance/twin-instance.js'
 import { TwinArea } from '../service/twin-space/twin-area.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
 import { TwinTarget } from '../service/twin-target/twin-target.js'
-import { judgeTargets, judgeGroupTargets, scopedTargets, type ScopedTargets, type TargetVerdict } from './kpi-target.js'
+import { TWIN_METRIC, judgeTargets, judgeGroupTargets, scopedTargets, type ScopedTargets, type TargetVerdict, type TwinMetricId } from './kpi-target.js'
 import { TwinEngine } from './twin-engine.js'
+import { buildEnergyTopology, type EnergyTopology } from './energy-topology.js'
 import {
   crossGroups,
   deltaP50,
@@ -38,9 +39,16 @@ import {
   type KpiGroupBy,
   type KpiResult
 } from './kpi-fold.js'
+import { MAX_BASELINE_PERIODS, baselineWindows, summarizeBaseline, type BaselineStride, type MetricBaseline } from './kpi-baseline.js'
 
-/** 업무 전이만 읽는다 — 설비 상태(equipment.status)는 OEE 누적기의 몫이고 여기선 쓰지 않는다. */
-const BUSINESS_EVENTS = ['task.status', 'order.status']
+/**
+ * 업무 전이만 읽는다 — 설비 상태(equipment.status)는 OEE 누적기의 몫이고 여기선 쓰지 않는다.
+ *
+ * **에너지 구간 마감**은 함께 읽는다(2026-08-14): 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서
+ * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
+ * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
+ */
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window']
 
 /** 한 번에 접을 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000
@@ -87,6 +95,18 @@ export interface TwinKpiInput {
    * 없는 것을 0% 로 그리면 "변화 없음" 이라는 거짓이 된다.
    */
   compareTo?: 'previous' | 'yesterday'
+  /**
+   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 접어 **분포**와 그 안의 자리를 낸다.
+   *
+   * `compareTo` 는 한 구간만 봐서 판단이 "어제보다 나아졌다" 에서 멈춘다 — 어제도 나빴으면 쓸모가 없다.
+   * 최근 며칠의 같은 시간대를 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
+   *
+   * `stride: 'week'` 는 같은 요일을 본다(주말·평일이 섞이지 않게). `periods` 는 1~14
+   * (창마다 조회가 한 번 더 붙는다 — 값을 공짜로 말하지 않는다).
+   *
+   * `compareTo` 와 함께 쓸 수 있다: 다른 질문이기 때문이다(직전 한 구간 vs 최근 분포).
+   */
+  baseline?: { periods: number; stride?: BaselineStride }
 }
 
 export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
@@ -147,6 +167,21 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
     waitTime?: KpiResult['waitTime']
     delta?: { tasks: number; orders: number; workP50Ms?: number; leadP50Ms?: number; waitP50Ms?: number }
   }
+  /**
+   * **여러 구간 분포**(요청했을 때만) — 지표별로 최근 N 구간의 분포와 지금의 자리.
+   *
+   * `samples` 는 **요청한 창 전부**다(기록 없는 창도 `measured:false` 로 남는다) — 빼고 말하면
+   * "지난 7일" 이 실제로는 3일이었다는 것을 아무도 모른다. 자리를 말할 수 없으면 `noPosition` 이
+   * 이유를 밝힌다(표본 부족·현재 값 없음). 방향은 지표의 성질이라 `standing` 이 그것을 적용한 읽기다.
+   */
+  baseline?: {
+    stride: BaselineStride
+    /** 요청한 과거 구간 수(상한 적용 후). */
+    periods: number
+    metrics: MetricBaseline[]
+    /** 과거 창 조회 중 하나라도 상한에 걸렸나 — 그 창의 값은 하한이라 분포가 낮게 보일 수 있다. */
+    capped?: boolean
+  }
   /**
    * 관점별 값(요청했을 때만). `key` 는 식별자, `label` 은 사람이 읽는 이름(있을 때만 — 구역은 이름이
    * 따로 저장되어 있다). `truncated` 는 상한 때문에 빠진 축의 수다.
@@ -155,7 +190,7 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
     by: KpiGroupBy
     items: (KpiGroupOut & { label?: string })[]
     /**
-     * 비교 구간에는 일이 있었는데 **지금은 없는** 축. 표에서 그냥 빠지면 멈춘 구역·놀고 있는 자원이
+     * 비교 구간에는 일이 있었는데 **지금은 없는** 축. 표에서 그냥 빠지면 멈춘 구역·대기 중인 자원이
      * 눈에 보이지 않는다 — 운영에서는 이것이 가장 중요한 신호일 수 있다.
      */
     disappeared?: { key: string; label?: string; tasks: number }[]
@@ -171,8 +206,8 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
   Partial<Pick<CrossedGroup, 'prevTasks' | 'deltaTasks' | 'deltaWorkP50Ms' | 'isNew'>>
 
 /**
- * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `locations[].parentId` 가
- * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 모델 정의의 `locations[].parentId` 가
+ * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 모델은 남아 있어 이 경로가 가장 튼튼하다.
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
@@ -185,11 +220,11 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
  * 저널에는 시각만 있고 교대가 없다(일부러 그렇게 뒀다 — 교대는 파생이라 찍어 두면 나중에 교대 시간을
  * 고쳤을 때 과거가 옛 구분으로 굳는다). 그래서 폴드가 계산할 재료를 여기서 모은다.
  *
- * 선언의 출처는 **보드의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
+ * 선언의 출처는 **모델의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
  * **가장 많이 쓰이는 선언 한 벌**을 쓴다 — 3교대 공장은 전 설비가 같은 교대이므로 이것이 곧 정답이고,
  * 자원마다 교대가 다른 현장에서는 이 축이 거칠다는 뜻이다(그 사실을 여기 적어 둔다).
  *
- * 시각 기준은 보드에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
+ * 시각 기준은 모델에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
  * 없으면 UTC 로 읽고, 그 기본값은 커널 계약에 밝혀져 있다.
  */
 /**
@@ -219,9 +254,9 @@ async function shiftContext(
   const tally = new Map<string, { decl: any[]; n: number }>()
   let utcOffsetMinutes: number | undefined
   for (const row of rows) {
-    const board = row.board as any
-    if (utcOffsetMinutes === undefined && typeof board?.utcOffsetMinutes === 'number') utcOffsetMinutes = board.utcOffsetMinutes
-    for (const e of (board?.equipment ?? []) as any[]) {
+    const model = row.model as any
+    if (utcOffsetMinutes === undefined && typeof model?.utcOffsetMinutes === 'number') utcOffsetMinutes = model.utcOffsetMinutes
+    for (const e of (model?.equipment ?? []) as any[]) {
       const decl = e?.workCalendar
       if (!Array.isArray(decl) || !decl.length) continue
       const key = JSON.stringify(decl)
@@ -246,12 +281,17 @@ async function locationAreaMap(
       where: { domain: { id: domainId }, instanceId: In(instanceIds) }
     })
     for (const row of rows) {
-      const locations = (((row.board as any)?.locations ?? []) as any[]).filter(n => n?.id)
+      const locations = (((row.model as any)?.locations ?? []) as any[]).filter(n => n?.id)
       if (!locations.length) continue
       /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
       let h
       try {
-        h = hierarchyOf({ locations })
+        /*
+         * 단 해석기를 함께 넘긴다 — 자리가 `level` 을 적지 않으면 **타입이 답한다**(카탈로그 선언).
+         * 이 집계는 지금 구역 롤업(`rollupOf`)만 쓰므로 결과가 달라지지 않는다. 그래도 여기서
+         * 잇는다: 단으로 묻는 질의(`ancestorOfLevel`)가 생길 때 배선을 다시 찾지 않게 한다.
+         */
+        h = hierarchyOf({ locations }, t => levelOfLocationType(t, row.kind))
       } catch (e: any) {
         console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
         continue
@@ -277,6 +317,153 @@ async function locationAreaMap(
   return { locationArea, labels }
 }
 
+/**
+ * 자원 → **배전 계통의 자리**(분기·수전) 지도와 그 자리의 이름.
+ *
+ * ── 무엇을 읽나 ─────────────────────────────────────────────────────────────
+ * 에너지 트윈의 모델이 「이 설비가 어느 자리에 매달렸나」를 선언한다(`homeLocation`). 그 자리가 분기가
+ * 아니라 하위 자리라면 부모를 타고 올라가 **전기 계통의 자리**를 찾는다 — 전기의 계통은 물리 구역과
+ * 다른 나무이므로 구역 롤업(`locationAreaMap`)을 쓸 수 없다.
+ *
+ * ── 왜 에너지 트윈만 읽나 ───────────────────────────────────────────────────
+ * 같은 설비가 공장 트윈에서는 자원(작업을 한다)이고 에너지 트윈에서는 부하(전기를 먹는다)다 — 사실 둘,
+ * id 하나. 가동시간은 공장 트윈의 저널에서 오고, 전기 계통의 소속은 이 모델에서 온다. 그 둘을 id 로
+ * 잇는 것이 이 지도의 일이다.
+ *
+ * 자리를 말하지 않는 설비는 **넣지 않는다** — 없는 소속을 만들면 그 몫이 엉뚱한 분기의 것이 된다.
+ */
+/**
+ * 선언된 **전기요금 단가** — 에너지 트윈의 자리 속성에서 읽는다(계약전력과 같은 자리).
+ *
+ * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
+ * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
+ * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ */
+async function tariffOf(
+  domainId: string,
+  instanceIds: string[]
+): Promise<{ tariff?: TariffDeclaration; conflict?: boolean }> {
+  if (!instanceIds.length) return {}
+  const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
+  const found: TariffDeclaration[] = []
+  for (const row of rows) {
+    if (row.kind !== 'ems') continue
+    for (const loc of ((row.model as any)?.locations ?? []) as any[]) {
+      const props = new Map<string, any>(((loc?.properties ?? []) as any[]).map(p => [String(p?.id), p?.value]))
+      const num = (id: string): number | undefined => {
+        const v = Number(props.get(id))
+        return Number.isFinite(v) && v > 0 ? v : undefined
+      }
+      const d = num(EMS_PROPERTY.demandChargePerKW)
+      const e = num(EMS_PROPERTY.energyChargePerKWh)
+      const cur = props.get(EMS_PROPERTY.currency)
+      if (d === undefined && e === undefined) continue
+      found.push({
+        ...(d !== undefined ? { demandChargePerKW: d } : {}),
+        ...(e !== undefined ? { energyChargePerKWh: e } : {}),
+        ...(cur ? { currency: String(cur) } : {})
+      })
+    }
+  }
+  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
+  )
+  return { tariff: first, ...(same ? {} : { conflict: true }) }
+}
+
+async function resourceFeederMap(
+  domainId: string,
+  instanceIds: string[]
+): Promise<{ resourceFeeder: Record<string, string>; meterFeeder: Record<string, string>; labels: Record<string, string> }> {
+  const resourceFeeder: Record<string, string> = {}
+  /** 계량 지점 → 그것이 재는 분기. 있으면 그 분기 값은 **측정**이다(배분보다 강한 근거). */
+  const meterFeeder: Record<string, string> = {}
+  const labels: Record<string, string> = {}
+  if (!instanceIds.length) return { resourceFeeder, meterFeeder, labels }
+
+  const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
+  for (const row of rows) {
+    if (row.kind !== 'ems') continue // 전기 계통을 선언하는 것은 에너지 트윈이다
+    const model: any = row.model ?? {}
+    const locations: any[] = (model.locations ?? []).filter((n: any) => n?.id)
+    const byId = new Map(locations.map((n: any) => [String(n.id), n]))
+    const electrical = new Set(EMS_LOCATION_TYPES as readonly string[])
+
+    /**
+     * 이 자리에서 **전기 상류**로 올라가 처음 만나는 계통의 자리. 없으면 undefined.
+     *
+     * 상류의 뜻은 커널이 읽는다(`electricalUpstreamOf`) — 공간 부모(공장·구역)를 따라 올라가면 전기적으로
+     * 뜻이 없는 길을 걷게 되고, 옛 세대(분기의 `parentId` 에 수전)와 새 세대(`upstreamId`)가 섞여 있으므로
+     * 그 판정을 여기서 다시 쓰면 두 벌이 된다.
+     */
+    const feederOf = (startId: string): string | undefined => {
+      const seen = new Set<string>()
+      let cur = byId.get(startId)
+      while (cur && !seen.has(String(cur.id))) {
+        seen.add(String(cur.id)) // 잘못된 모델의 순환이 여기서 멈춘다
+        if (electrical.has(String(cur.type))) return String(cur.id)
+        const up = electricalUpstreamOf(locations as any, String(cur.id))
+        cur = up ? byId.get(up) : cur.parentId ? byId.get(String(cur.parentId)) : undefined
+      }
+      return undefined
+    }
+
+    for (const e of (model.equipment ?? []) as any[]) {
+      const home = e?.homeLocation ?? e?.homeLocationId
+      if (!e?.id || !home) continue
+      /*
+       * 계량기는 부하가 아니다 — 그것의 「몫」을 세면 총량이 이중으로 나뉜다. 대신 **어디를 재는지**를
+       * 따로 모은다: 계량기가 분기에 있으면 그 분기 값은 배분이 아니라 **측정**이다(가장 강한 근거).
+       */
+      if (e.kind === 'meter') {
+        const at = feederOf(String(home))
+        /* 뿌리(수전)를 재는 계량기는 분기의 것이 아니다 — 그 값은 총량이고, 나머지는 뺄셈으로 나온다. */
+        if (at && String(byId.get(at)?.type) !== 'incoming') meterFeeder[String(e.id)] = at
+        continue
+      }
+      /* 차단기·태양광·축전지도 부하가 아니다. */
+      if (e.kind === 'breaker' || e.kind === 'pv-array' || e.kind === 'battery') continue
+      const feeder = feederOf(String(home))
+      if (feeder) resourceFeeder[String(e.id)] = feeder
+    }
+    for (const n of locations) if (electrical.has(String(n.type)) && n.name) labels[String(n.id)] = String(n.name)
+  }
+  return { resourceFeeder, meterFeeder, labels }
+}
+
+/**
+ * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 접는다.
+ *
+ * 여러 트윈이 한 공간에 있으면 **각 트윈의 뿌리를 나란히** 둔다(하나로 합치면 없는 결선을 그리게 된다).
+ * 에너지 트윈이 없으면 만들지 않는다 — 빈 그림은 고장으로 읽힌다.
+ */
+async function energyTopologyOf(
+  domainId: string,
+  instanceIds: string[],
+  energy: { byFeeder?: { key: string; kWh: number; basis?: 'measured' | 'apportioned'; peakKW?: number }[] } | undefined
+): Promise<EnergyTopology | undefined> {
+  if (!instanceIds.length) return undefined
+  const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
+  const ems = rows.filter(r => r.kind === 'ems' && r.model)
+  if (!ems.length) return undefined
+  const merged: EnergyTopology = { roots: [], unplaced: [], unmetered: [], loadsOnIncoming: 0 }
+  for (const row of ems) {
+    /*
+     * 지금의 설비 상태를 함께 넘긴다 — 발전·저장의 **지금 값**은 구간 폴드가 아니라 스냅샷이 안다.
+     * 없으면(정지된 트윈) 구조만 그린다.
+     */
+    const snap = TwinEngine.snapshot(domainId, row.instanceId)
+    const t = buildEnergyTopology(row.model, energy, snap?.equipment)
+    merged.roots.push(...t.roots)
+    merged.unplaced.push(...t.unplaced)
+    merged.unmetered.push(...t.unmetered)
+    merged.loadsOnIncoming += t.loadsOnIncoming
+  }
+  return merged.roots.length ? merged : undefined
+}
+
 /** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
 async function latestEventTime(domainId: string, instanceIds: string[]): Promise<string | null> {
   if (instanceIds.length === 0) return null
@@ -284,14 +471,15 @@ async function latestEventTime(domainId: string, instanceIds: string[]): Promise
     where: { domain: { id: domainId }, instanceId: In(instanceIds), eventType: In(BUSINESS_EVENTS) },
     order: { revision: 'DESC' }
   })
-  return row?.eventTime ?? null
+  /* 소비처는 ISO 문자열을 기대한다(시각 축의 공용 표기) — 컬럼이 날짜가 됐으므로 여기서 옮긴다. */
+  return row?.eventTime ? row.eventTime.toISOString() : null
 }
 
 /**
  * 창 구간의 업무 이벤트 — 창보다 `lookbackMs` 만큼 앞까지 읽는다(완료된 작업의 시작이 창 밖일 수 있다).
  *
- * eventTime 은 ISO 문자열 컬럼이라 사전식 비교가 성립한다(같은 파일군의 시각 커서와 동일 전제).
- * 비교 구간도 같은 규칙으로 읽어야 하므로 함수로 둔다 — 두 곳에 적으면 규칙이 갈라진다.
+ * eventTime 은 날짜 컬럼이라 DB 가 시각으로 비교한다 — 예전 문자열 컬럼 시절의 "UTC ISO 만 들어오면
+ * 사전식 비교가 맞는다" 는 전제가 필요 없다.
  */
 async function fetchEvents(domainId: string, instanceIds: string[], fromMs: number, toMs: number, lookbackMs: number) {
   if (instanceIds.length === 0) return { events: [] as KpiEvent[], capped: false }
@@ -300,7 +488,7 @@ async function fetchEvents(domainId: string, instanceIds: string[], fromMs: numb
       domain: { id: domainId },
       instanceId: In(instanceIds),
       eventType: In(BUSINESS_EVENTS),
-      eventTime: Between(new Date(fromMs - lookbackMs).toISOString(), new Date(toMs).toISOString())
+      eventTime: Between(new Date(fromMs - lookbackMs), new Date(toMs))
     },
     order: { revision: 'ASC' },
     take: MAX_EVENTS
@@ -308,7 +496,8 @@ async function fetchEvents(domainId: string, instanceIds: string[], fromMs: numb
   /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
    * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
   return {
-    events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime, payload: r.payload })),
+    /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
+    events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime?.toISOString(), payload: r.payload })),
     capped: rows.length >= MAX_EVENTS
   }
 }
@@ -327,7 +516,8 @@ async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: strin
     : list.filter((x: any) => x?.running && 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] : []
-  const realityModes = [...new Set(rows.map((x: any) => String(x.realityMode ?? 'unknown')))]
+  /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
+  const realityModes = [...new Set(rows.map((x: any) => String(x.realityMode)))]
   return { instanceIds, realityModes }
 }
 
@@ -391,9 +581,19 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
   const areaMap =
     input.groupBy === 'area' ? await locationAreaMap(input.domainId, instanceIds, input.spaceId) : { locationArea: {}, labels: {} }
   const shiftCtx = input.groupBy === 'shift' ? await shiftContext(input.domainId, instanceIds) : {}
+  /*
+   * 전기 계통 소속은 **축과 무관하게** 읽는다 — 분기별 몫은 관점 축이 아니라 에너지 사실의 일부라
+   * (같은 창의 총량을 나눈 것) 어느 축을 보고 있든 함께 나가야 한다.
+   */
+  const feederMap = await resourceFeederMap(input.domainId, instanceIds)
+  /* 요금 단가도 축과 무관하게 읽는다 — 금액은 같은 창의 전력량·최대수요에서 나오는 사실이다. */
+  const tariffFound = await tariffOf(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 } : {}),
     ...shiftCtx,
     groupLimit: input.groupLimit
   })
@@ -411,12 +611,49 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     minutes: Math.round((toMs - fromMs) / 60_000),
     basis
   }
+  /**
+   * 여러 구간 분포를 만든다 — **현재 창에 기록이 없어도 낸다.**
+   *
+   * 그때가 오히려 가장 알고 싶은 순간이다("지금 아무 기록이 없는데 평소엔 60건이었다" = 멈춘 신호).
+   * 그래서 조기 반환보다 앞에 두고 두 경로가 함께 쓴다.
+   */
+  const computeBaseline = async (): Promise<TwinKpiOutput['baseline']> => {
+    if (!input.baseline || !(input.baseline.periods > 0)) return undefined
+    const stride = input.baseline.stride ?? 'day'
+    const windows = baselineWindows(fromMs, toMs, input.baseline.periods, stride)
+    let baseCapped = false
+    const samples: { fromMs: number; toMs: number; values: Partial<Record<TwinMetricId, number | undefined>> }[] = []
+
+    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)
+      samples.push({ fromMs: w.fromMs, toMs: w.toMs, values })
+    }
+
+    const current: Partial<Record<TwinMetricId, number | undefined>> = {}
+    for (const metric of Object.keys(TWIN_METRIC) as TwinMetricId[]) current[metric] = TWIN_METRIC[metric].of(kpi)
+
+    return {
+      stride,
+      periods: windows.length,
+      metrics: summarizeBaseline(TWIN_METRIC, current, samples),
+      ...(baseCapped ? { capped: true } : {})
+    }
+  }
+
+
   if (kpi.eventsInWindow === 0) {
+    const baseline = await computeBaseline()
     return {
       window,
       measured: false,
       scope,
-      note: 'no operational events in this window — nothing to measure (this is NOT "zero throughput").'
+      note: 'no operational events in this window — nothing to measure (this is NOT "zero throughput").',
+      ...(baseline ? { baseline } : {})
     }
   }
 
@@ -485,6 +722,15 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
           }
   }
 
+  /*
+   * 여러 구간 동시 비교 — **같은 시간대를 며칠 뒤로** 옮겨 분포를 만든다(성과 맵 ③).
+   *
+   * 창마다 조회가 한 번 더 붙지만 각 창은 현재 창과 같은 길이라(보통 1~24h) 값싸다. 축(groupBy)은
+   * 넘기지 않는다 — 분포는 **전체 지표**의 질문이고, 축별 분포까지 내면 응답이 축 수만큼 부푼다
+   * (필요해지면 그때 축을 지정해 다시 묻는 것이 정직하다).
+   *
+   * 지표 어휘는 `TWIN_METRIC` 이 계속 소유하고, 여기서는 **값만 꺼내** 분포 모듈에 넘긴다.
+   */
   /* 관점 값은 시각 변환이 없어 그대로 통과한다. 붙이는 것은 ① 사람이 읽는 이름과 ② 축이 통째로
    * 비었을 때의 이유다 — "구역별 0건" 과 "노드에 구역이 안 붙어 있다" 는 완전히 다른 상황이다. */
   const groups = kpi.groups
@@ -529,8 +775,34 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
    * **목표가 없으면 판정하지 않는다** — 필드 자체를 만들지 않는다. 전부 "목표 없음" 으로 채우면
    * 화면이 회색 노이즈가 되고, 목표가 있는 지표가 묻힌다.
    */
+  /* 분포는 **한 번만** 계산한다 — 창마다 조회가 붙으므로 두 번 부르면 조회가 두 배가 된다. */
+  const baseline = await computeBaseline()
+
   /* 폴드가 돌려준 raw 창(ms)은 버린다 — 위의 ISO 창이 사람이 읽을 정본이다. */
   const { window: _rawWindow, groups: _rawGroups, ...rest } = kpi
+  /*
+   * 자리에 **부르는 이름**을 붙인다 — `feeder-2` 는 id 이고 사람은 「가공 라인」으로 부른다.
+   * 이름을 모르는 자리는 id 그대로 둔다(지어내지 않는다).
+   */
+  /* 단가가 갈려 있으면 밝힌다 — 우리가 고른 하나로 낸 금액이라는 사실을 화면이 말할 수 있게. */
+  if (rest.energy?.cost && tariffFound.conflict) rest.energy = { ...rest.energy, tariffConflict: true } as any
+  if (rest.energy?.byFeeder?.length) {
+    rest.energy = {
+      ...rest.energy,
+      byFeeder: rest.energy.byFeeder.map(row => ({ ...row, ...(feederMap.labels[row.key] ? { label: feederMap.labels[row.key] } : {}) }))
+    }
+  }
+  /*
+   * 계통도 — **선언된 관계와 계량이 덮는 범위**를 함께 낸다.
+   *
+   * 값은 여기서 다시 계산하지 않는다(폴드가 낸 분기별 몫을 그대로 노드에 얹는다). 계통은 모델이 아는
+   * 사실이므로 저널만 보는 폴드가 아니라 여기서 조립한다 — 화면이 모델을 따로 또 조회하지 않아도 되고,
+   * AI 도 같은 값을 읽는다(규칙 한 벌).
+   */
+  if (rest.energy) {
+    const topo = await energyTopologyOf(input.domainId, instanceIds, rest.energy)
+    if (topo) rest.energy = { ...rest.energy, topology: topo } as any
+  }
   return {
     window,
     measured: true,
@@ -540,6 +812,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...(buckets ? { buckets } : {}),
     ...(groups ? { groups } : {}),
     ...(verdicts.length ? { targets: verdicts } : {}),
-    ...(comparison ? { comparison } : {})
+    ...(comparison ? { comparison } : {}),
+    ...(baseline ? { baseline } : {})
   }
 }

package/server/engine/kpi-target.ts

@@ -50,7 +50,7 @@ const statOf = (s: DurationStats, pick: (d: DurationStats) => number): number |
  * 좋다 — 이것을 입력으로 받으면 반대로 적은 목표가 만들어지고, 그 뒤 판정이 전부 뒤집힌다.
  */
 export const TWIN_METRIC = {
-  /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 가른다.
+  /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 구분한다.
      0 으로 판정하면 "측정 못 한 구간" 이 "일을 안 한 구간" 으로 보고된다. */
   'throughput.tasks': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.tasks) },
   'throughput.orders': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.orders) },
@@ -61,6 +61,28 @@ export const TWIN_METRIC = {
   'leadTime.p90Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p90Ms) },
   'workTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.workTime, d => d.p50Ms) },
   'waitTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.waitTime, d => d.p50Ms) },
+  /*
+   * ── 에너지 (2026-08-17) ────────────────────────────────────────────────────
+   *
+   * 값은 폴드가 이미 내고 있었는데 **목표를 걸 수 있는 지표 목록에 없었다.** 그래서 화면은 「이번 창에
+   * 1,240kWh」를 보여 주면서도 그것이 좋은지 나쁜지는 말하지 못했다 — 에너지야말로 계약이라는 딱딱한
+   * 기준선이 있는 영역인데도 그랬다.
+   *
+   * 셋 다 방향은 **낮을수록 좋다**로 못 박는다. 「많이 쓸수록 좋다」는 에너지 목표는 없다. 산출이 늘어
+   * 전력량이 느는 경우는 원단위(`energy.intensity`)가 답할 자리이지, 방향을 뒤집을 이유가 아니다.
+   *
+   * 값이 없는 창(에너지 트윈이 아니거나 계측이 끊긴 창)은 `undefined` 로 남긴다 — 0 으로 읽으면
+   * 시간 지표에서 이미 겪은 그 결함이 그대로 재현된다(안 쓴 것이 아니라 못 잰 것인데 만점이 된다).
+   */
+  'energy.kWh': { direction: 'lower', unit: 'kWh', of: (k: KpiResult) => k.energy?.kWh },
+  /** 최대수요 — 계약 상한을 목표로 적는 자리다(요금의 기본요금 부분이 여기서 정해진다). */
+  'energy.peakKW': { direction: 'lower', unit: 'kW', of: (k: KpiResult) => k.energy?.peakKW },
+  /** 원단위 — 완료 오더당 kWh. 답할 수 없으면(`null`) 판정하지 않는다. */
+  'energy.intensity': {
+    direction: 'lower',
+    unit: 'kWh/order',
+    of: (k: KpiResult) => (typeof k.energy?.intensity?.value === 'number' ? k.energy.intensity.value : undefined)
+  },
   /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */
   'utilization.ratio': {
     direction: 'higher',
@@ -218,7 +240,7 @@ export function judgeTargets(kpi: KpiResult, targets: readonly TwinTargetSpec[]
   return out
 }
 
-/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 갈라진다). */
+/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 어긋난다). */
 function verdictOf(metric: TwinMetricId, actual: number, target: number, direction: 'higher' | 'lower'): TargetVerdict {
   const met = direction === 'higher' ? actual >= target : actual <= target
   const ratio = direction === 'higher' ? (target > 0 ? actual / target : Number.NaN) : actual > 0 ? target / actual : Number.NaN

package/server/engine/live-attentions.ts

@@ -6,7 +6,7 @@
  */
 import { deriveAttentions } from '@operato/twin-kernel'
 
-export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; nowTime?: string }>(
+export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; acked?: string[]; nowTime?: string }>(
   state: S
 ): S {
   if (!state) return state
@@ -18,7 +18,12 @@ export function withLiveAttentions<S extends { equipment?: any[]; locations?: an
      */
     attentions: deriveAttentions(
       { equipment: state.equipment ?? [], locations: state.locations ?? [], orders: state.orders ?? [], tasks: state.tasks ?? [] },
-      undefined,
+      /*
+       * **확인(ack)해 둔 것을 함께 넘긴다.** 예전에는 여기에 undefined 를 넘겨서, 라이브에서는
+       * 확인 처리가 화면에 전혀 반영되지 않았다 — 사람이 확인해도 신호가 계속 활성으로 나갔다.
+       * 확인 사실은 이제 저널에 남고(`attention.acked`) 프로젝터가 상태에 실어 오므로 여기서 받는다.
+       */
+      state.acked?.length ? new Set(state.acked) : undefined,
       state.nowTime
     )
   }

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

@@ -0,0 +1,58 @@
+/*
+ * 「이 트윈에 계측이 들어오고 있나」 — **그 사실을 한 자리에서 묻는다.**
+ *
+ * ── 무엇이 보이지 않았나 (2026-08-14) ───────────────────────────────────────
+ * 미러 트윈은 커널이 돌기만 하면 「도는 중」이라 보고했다. 그런데 계측을 나르는 피드가 떨어져 있으면
+ * 그 트윈은 **아무것도 받지 않으면서 도는 중**이다 — 화면에서 두 상태가 똑같이 보였고, 사람은
+ * 「값이 안 변하네」로 뒤늦게 알게 됐다(재기동 뒤 실제로 그랬다).
+ *
+ * ── 왜 장부가 하나여야 하나 ────────────────────────────────────────────────
+ * 피드를 여는 곳이 둘이다: 커넥터 기반(`reference-live`)과 프리셋 기반(앱의 `provision-from-preset`).
+ * 한쪽만 보고 「끊김」이라 말하면 **멀쩡히 흐르는 트윈을 끊겼다고 부르게 된다** — 거짓 경보는 참 경보를
+ * 죽인다. 그래서 각 계층이 자기 장부를 여기 **등록**하고, 묻는 쪽은 이 한 자리에만 묻는다.
+ *
+ * 호스트는 어떤 어댑터·프리셋이 있는지 몰라도 된다(계층을 거꾸로 잇지 않는다).
+ */
+
+/** 지금 피드가 붙어 있는 인스턴스 id 들 — 그 계층의 장부가 답한다. */
+export type LiveFeedProbe = () => string[]
+
+const probes: LiveFeedProbe[] = []
+
+/** 피드 장부를 등록한다(모듈 로드 시 한 번). */
+export function registerLiveFeedProbe(probe: LiveFeedProbe): void {
+  probes.push(probe)
+}
+
+/**
+ * 피드가 붙어 있나 — 어느 장부든 그렇다고 하면 그렇다.
+ *
+ * 장부가 터지는 것을 이 판정 전체의 실패로 만들지 않는다: 한 계층이 답하지 못해도 다른 계층의 사실은
+ * 그대로 참이다. 다만 **조용히 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.
+ */
+export function liveFeedAttached(instanceId: string): boolean {
+  for (const probe of probes) {
+    try {
+      if (probe().includes(instanceId)) return true
+    } catch (e: any) {
+      console.warn('[twin-live] a feed registry could not answer —', e?.message ?? e)
+    }
+  }
+  return false
+}
+
+/**
+ * 이 트윈의 **피드 사실** — 화면이 그대로 말할 수 있는 세 값.
+ *
+ * `not-applicable` 을 `detached` 와 섞지 않는다(이 시스템이 내내 지켜 온 「없음 ≠ 해당 없음」):
+ *  · 시뮬 트윈에는 나를 피드가 **없어야 한다** — 그건 결함이 아니라 그 트윈의 성질이다.
+ *  · 멈춘 트윈에게 피드를 묻는 것은 뜻이 없다 — 사람이 멈춰 둔 것이다.
+ *  · 남는 것 하나가 우리가 보이려던 사실이다: **도는 미러인데 아무것도 오지 않는다.**
+ */
+export type LiveFeedState = 'attached' | 'detached' | 'not-applicable'
+
+export function liveFeedStateOf(args: { realityMode?: string; running?: boolean; instanceId: string }): LiveFeedState {
+  if (args.realityMode !== 'mirror') return 'not-applicable'
+  if (!args.running) return 'not-applicable'
+  return liveFeedAttached(args.instanceId) ? 'attached' : 'detached'
+}