@things-factory/headless-twin 10.0.15 → 10.0.18

package/dist-server/engine/kpi-query.js

@@ -19,8 +19,10 @@ exports.computeTwinKpi = computeTwinKpi;
  * 어떤 기준을 썼는지는 결과의 `window.basis` 로 밝힌다 — 숨기면 사용자가 숫자를 오해한다.
  */
 const log_js_1 = require("./log.js");
+const event_type_split_shape_js_1 = require("../service/twin-journal/event-type-split-shape.js");
+const read_time_js_1 = require("./read-time.js");
 const typeorm_1 = require("typeorm");
-const twin_kernel_1 = require("@operato/twin-kernel");
+const ops_contract_1 = require("@operato/ops-contract");
 const shell_1 = require("@things-factory/shell");
 const twin_event_js_1 = require("../service/twin-event/twin-event.js");
 const twin_instance_js_1 = require("../service/twin-instance/twin-instance.js");
@@ -39,16 +41,44 @@ const kpi_baseline_js_1 = require("./kpi-baseline.js");
  * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`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;
 /**
  * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 모델 정의의 `locations[].parentId` 가
  * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 모델은 남아 있어 이 경로가 가장 튼튼하다.
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
- * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * **집계에서 오류 없이 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
  * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
  */
 /**
@@ -122,7 +152,7 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
                  * 이 집계는 지금 구역 롤업(`rollupOf`)만 쓰므로 결과가 달라지지 않는다. 그래도 여기서
                  * 잇는다: 단으로 묻는 질의(`ancestorOfLevel`)가 생길 때 배선을 다시 찾지 않게 한다.
                  */
-                h = (0, twin_kernel_1.hierarchyOf)({ locations }, t => (0, twin_kernel_1.levelOfLocationType)(t, row.kind));
+                h = (0, ops_contract_1.hierarchyOf)({ locations }, t => (0, ops_contract_1.levelOfLocationType)(t, row.kind));
             }
             catch (e) {
                 (0, log_js_1.twinWarn)(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`);
@@ -170,7 +200,7 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
  *
  * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
  * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
- * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ * 밝힌다(알리지 않고 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
  */
 async function tariffOf(domainId, instanceIds) {
     if (!instanceIds.length)
@@ -186,14 +216,17 @@ async function tariffOf(domainId, instanceIds) {
                 const v = Number(props.get(id));
                 return Number.isFinite(v) && v > 0 ? v : undefined;
             };
-            const d = num(twin_kernel_1.EMS_PROPERTY.demandChargePerKW);
-            const e = num(twin_kernel_1.EMS_PROPERTY.energyChargePerKWh);
-            const cur = props.get(twin_kernel_1.EMS_PROPERTY.currency);
+            const d = num(ops_contract_1.EMS_PROPERTY.demandChargePerKW);
+            const e = num(ops_contract_1.EMS_PROPERTY.energyChargePerKWh);
+            /* 요금적용전력 — 있으면 기본요금이 조건부 파생이 아니라 사실이 된다(§`electricityCost`). */
+            const b = num(ops_contract_1.EMS_PROPERTY.billingDemandKW);
+            const cur = props.get(ops_contract_1.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) } : {})
             });
         }
@@ -201,7 +234,10 @@ async function tariffOf(domainId, instanceIds) {
     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);
+    const same = found.every(t => t.demandChargePerKW === first.demandChargePerKW &&
+        t.energyChargePerKWh === first.energyChargePerKWh &&
+        t.billingDemandKW === first.billingDemandKW &&
+        t.currency === first.currency);
     return { tariff: first, ...(same ? {} : { conflict: true }) };
 }
 async function resourceFeederMap(domainId, instanceIds) {
@@ -218,7 +254,7 @@ async function resourceFeederMap(domainId, instanceIds) {
         const model = row.model ?? {};
         const locations = (model.locations ?? []).filter((n) => n?.id);
         const byId = new Map(locations.map((n) => [String(n.id), n]));
-        const electrical = new Set(twin_kernel_1.EMS_LOCATION_TYPES);
+        const electrical = new Set(ops_contract_1.EMS_LOCATION_TYPES);
         /**
          * 이 자리에서 **전기 상류**로 올라가 처음 만나는 계통의 자리. 없으면 undefined.
          *
@@ -233,7 +269,7 @@ async function resourceFeederMap(domainId, instanceIds) {
                 seen.add(String(cur.id)); // 잘못된 모델의 순환이 여기서 멈춘다
                 if (electrical.has(String(cur.type)))
                     return String(cur.id);
-                const up = (0, twin_kernel_1.electricalUpstreamOf)(locations, String(cur.id));
+                const up = (0, ops_contract_1.electricalUpstreamOf)(locations, String(cur.id));
                 cur = up ? byId.get(up) : cur.parentId ? byId.get(String(cur.parentId)) : undefined;
             }
             return undefined;
@@ -267,11 +303,82 @@ async function resourceFeederMap(domainId, instanceIds) {
     return { resourceFeeder, meterFeeder, labels };
 }
 /**
- * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 접는다.
+ * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 처리한다.
  *
  * 여러 트윈이 한 공간에 있으면 **각 트윈의 뿌리를 나란히** 둔다(하나로 합치면 없는 결선을 그리게 된다).
  * 에너지 트윈이 없으면 만들지 않는다 — 빈 그림은 고장으로 읽힌다.
  */
+/**
+ * 이 트윈들이 이어받고 있는 **마지막 청구서** — 요금적용전력의 우선 근거.
+ *
+ * 저널이 아니라 상태에서 읽는 이유: 청구는 한 달에 한 번이라 하루 창의 조회에는 걸리지 않는다.
+ * 그런데 그 값은 **그 창에도 적용된다**(요금 제도가 그렇게 군다). 커널이 재기동에서도 이어받으므로
+ * 상태가 그 자리다.
+ *
+ * 트윈이 여럿이면 가장 늦게 끝난 것을 쓴다 — 현장 하나에 청구가 여럿이면 그것은 다른 문제이고,
+ * 여기서 골라 감추지 않는다.
+ */
+function latestBillOf(domainId, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const bill = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.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, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const p = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.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, instanceIds) {
+    let kW = 0;
+    let basis = 'ac';
+    let from = 'equipment';
+    for (const instanceId of instanceIds) {
+        /* 스냅샷에서 읽는다 — 커널이 고른 값이다. 여기서 모델을 다시 뒤지면 고르는 규칙이 두 벌이 된다. */
+        const r = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.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, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const b = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.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, instanceIds, energy) {
     if (!instanceIds.length)
         return undefined;
@@ -294,16 +401,46 @@ async function energyTopologyOf(domainId, instanceIds, energy) {
     }
     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, instanceIds) {
     if (instanceIds.length === 0)
         return null;
-    const row = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).findOne({
-        where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds), eventType: (0, typeorm_1.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 => (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
+        .createQueryBuilder('e')
+        .select('MAX(e.eventTime)', 'at')
+        .where('e.domain = :domainId', { domainId })
+        .andWhere('e.instanceId = :instanceId', { instanceId })
+        .andWhere('e.eventType = :eventType', { eventType })
+        .getRawOne()
+        .catch(() => null))));
+    /* 드라이버가 준 값은 시간대가 없을 수 있다 — 컬럼 변환을 지나게 한다(§`hydratedDate`). */
+    const repo = (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent);
+    let latest = null;
+    for (const r of rows) {
+        const at = (0, read_time_js_1.hydratedDate)(repo, 'eventTime', r?.at);
+        if (at && (!latest || at.getTime() > latest.getTime()))
+            latest = at;
+    }
+    return latest ? latest.toISOString() : null;
 }
 /**
  * 창 구간의 업무 이벤트 — 창보다 `lookbackMs` 만큼 앞까지 읽는다(완료된 작업의 시작이 창 밖일 수 있다).
@@ -369,23 +506,79 @@ async function fetchEvents(domainId, instanceIds, fromMs, toMs, lookbackMs) {
      * 남는 비용을 감추지 않는다: `payload` 파싱은 여전히 메인 스레드 일이고 연결을 나눠도 나뉘지 않는다
      * (실측 평균 1.5초). 그것을 더 줄이려면 폴드가 payload 에서 무엇을 쓰는지 좁혀야 한다 — 별 건이다.
      */
-    const raw = await (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
+    const from = new Date(fromMs - lookbackMs);
+    const to = new Date(toMs);
+    /**
+     * 한 갈래를 묻는다 — **종류를 정확일치로** 준다. 그것이 이 고침의 요점이다.
+     */
+    const readOne = (instanceId, eventType) => (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
         .createQueryBuilder('e')
-        .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.payload AS "payload"'])
+        .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: new Date(fromMs - lookbackMs), to: new Date(toMs) })
+        .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();
-    /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
+    /*
+     * ── **종류를 나눠 묻는다** (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;
+    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 = (0, event_type_split_shape_js_1.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) {
+            /* 있을 수 없는 일이다 — 갈래가 상한보다 많이 받아 왔다. 조용히 쓰지 않고 말한다. */
+            (0, log_js_1.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 (0, shell_1.getReadRepository)(twin_event_js_1.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();
+        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
     };
 }
 /**
@@ -425,8 +618,30 @@ function jsonOf(v) {
 /**
  * 집계 대상 트윈 목록.
  *
- * 공간이 주어지면 **가동 중이고 운영 목적인** 것만 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
+ * 공간이 주어지면 그 공간의 **운영 목적** 트윈을 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
  * 트윈이 지정되면 그것 하나. 둘 다 없으면 무엇을 재야 할지 알 수 없으므로 명시 실패한다.
+ *
+ * ── **「지금 도는가」로 걸러내지 않는다** (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) {
     if (!input.instanceId && !input.spaceId)
@@ -434,7 +649,7 @@ async function resolveTargets(input) {
     const list = await twin_engine_js_1.TwinEngine.list(input.domainId);
     const rows = input.instanceId
         ? list.filter((x) => x?.instanceId === input.instanceId)
-        : list.filter((x) => x?.running && x.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId);
+        : list.filter((x) => x?.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId);
     /* 목록에서 못 찾아도(정지·비등록) 지정된 트윈은 그대로 조회한다 — 저널은 남아 있을 수 있다. */
     const instanceIds = rows.length ? rows.map((x) => x.instanceId) : input.instanceId ? [input.instanceId] : [];
     /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
@@ -482,7 +697,19 @@ async function computeTwinKpi(input) {
                     : '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';
     }
     const fromMs = input.fromTime ? Date.parse(input.fromTime) : toMs - minutes * 60_000;
@@ -500,12 +727,30 @@ async function computeTwinKpi(input) {
     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 = (0, kpi_fold_js_1.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
     });
@@ -514,14 +759,14 @@ async function computeTwinKpi(input) {
      *
      * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
      * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
-     * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+     * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 알리지 않고 0 으로 세어진다.**
      *
      * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
      * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
      * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
      *
      * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
-     * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+     * 않는 사람도 알아야 하므로 로그에 남긴다 — 들어온 것이 없는 0 이 이 시스템에서 가장 비싼 침묵이다.
      *
      * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
      * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
@@ -561,7 +806,7 @@ async function computeTwinKpi(input) {
         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 = (0, kpi_fold_js_1.foldKpi)(pastEvents, w, { locationArea: areaMap.locationArea, ...shiftCtx });
             const values = {};
             for (const metric of Object.keys(kpi_target_js_1.TWIN_METRIC))
@@ -599,7 +844,7 @@ async function computeTwinKpi(input) {
             workP50Ms: b.workP50Ms
         }))
         : undefined;
-    /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 접는다. 기록이 없으면 delta 를 만들지 않는다
+    /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 계산한다. 기록이 없으면 delta 를 만들지 않는다
      * (없는 것을 0 으로 그리면 "변화 없음" 이라는 거짓이 된다). */
     let comparison;
     /* 관점 × 비교 교차 — 축별 delta 와 **사라진 축**(전에 있었고 지금 없는 것). */
@@ -609,13 +854,13 @@ async function computeTwinKpi(input) {
     if (input.compareTo === 'previous' || input.compareTo === 'yesterday') {
         const w = (0, kpi_fold_js_1.shiftWindow)(fromMs, toMs, input.compareTo);
         const { events: prevEvents, capped: prevCapped } = await fetchEvents(input.domainId, instanceIds, w.fromMs, w.toMs, lookbackMs);
-        /* 축이 요청됐으면 비교 구간도 **같은 축**으로 접는다 — 교차("구역별로 어제 대비")를 내기 위해.
+        /* 축이 요청됐으면 비교 구간도 **같은 축**으로 처리한다 — 교차("구역별로 어제 대비")를 내기 위해.
          * 상한은 축이 서로 어긋나지 않게 넉넉히 둔다(현재 축이 상한 안에 있는데 비교 축에서 밀려나면
          * 있는데 없다고 말하게 된다). */
         const prev = (0, kpi_fold_js_1.foldKpi)(prevEvents, w, {
             groupBy: input.groupBy,
             locationArea: areaMap.locationArea,
-            ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 접는다(정의가 다르면 축이 어긋난다)
+            ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 처리한다(정의가 다르면 축이 어긋난다)
             groupLimit: input.groupBy ? 100 : undefined
         });
         prevCappedFlag = prevCapped;