@operato/twin-kernel 0.7.19 → 0.7.21

package/dist/contract.d.ts

@@ -699,6 +699,25 @@ export interface LocationState {
      * 중간 단이 생기는 순간 그 아래 자리를 **집계에서 조용히 빠뜨린다**(정합성이 아니라 침묵이 문제다).
      */
     parentId?: string;
+    /**
+     * **전기적으로 어디서 받는가** — 이 자리에 전기를 주는 상류 자리(수전·분기).
+     *
+     * ── 왜 `parentId` 와 따로 두나 (2026-08-18) ─────────────────────────────────
+     * 한동안 분기의 `parentId` 에 수전을 적었다. 그러면 한 필드가 두 뜻을 겸한다: **공간 포함**(이 분기는
+     * 공장 안에 있다)과 **전기 상류**(이 분기는 수전에서 받는다). 겸용의 값은 조용히 새어 나간다 — 공간
+     * 해석기가 수전을 「구역」으로 읽어 매 인제스트마다 거짓 경보를 냈고(「area 가 없는 것을 가리킨다」),
+     * 계통을 읽는 쪽은 공간 부모를 전기 상류로 오해할 위험을 안고 있었다.
+     *
+     * 두 관계는 실제로 다르다: 분기는 공장 **안에** 있고(공간), 수전에서 **받는다**(전기). 한 자리가 둘을
+     * 함께 가질 수 있으므로 필드도 둘이어야 한다.
+     *
+     * **옛 세대는 읽는 경계에서 흡수한다**(`electricalUpstreamOf`): 이 값이 없고 `parentId` 가 전기 자리를
+     * 가리키면 그것을 상류로 읽는다. 저장된 모델을 고치지 않고도 두 세대가 같은 답을 낸다.
+     *
+     * ⚠️ **물류 흐름의 상·하류가 아니다.** 흐름 쪽에는 같은 낱말이 다른 뜻으로 있다(씬의 `downstreamRef` 는
+     * 물건이 다음에 갈 곳이다). 이 값은 **전기를 어디서 받는가**이고, 물건의 이동과 무관하다.
+     */
+    upstreamId?: string;
     /**
      * 이 자리를 **어떻게 알게 됐는가** — `master`(원 시스템 마스터/저작이 말해 준 자리) ·
      * `observed`(이벤트에 등장해서 알게 된 자리). 소비처가 둘을 구별해야 한다: 관측으로 알게 된 자리는
@@ -1218,6 +1237,17 @@ export interface MeterPointState {
 export interface DemandWindowState {
     startMs: number;
     endMs: number;
+    /**
+     * 이 구간의 **최대가 찍힌 순간**의 지점별 kW — 요금이 걸린 수는 kW 다.
+     *
+     * 나중에 계산할 수 없다: 커널은 표본을 보관하지 않으므로 그 순간이 지나면 각 지점이 얼마였는지 알 길이
+     * 없다. 그래서 최대가 갱신되는 순간에 찍어 둔다. 「어느 분기를 깎아야 피크가 내려가나」의 유일한 근거다
+     * (전력량이 큰 분기와 피크를 만든 분기는 다를 수 있다).
+     */
+    pointsAtPeak?: {
+        id: string;
+        kW: number;
+    }[];
     /**
      * 그 구간의 최대 순간부하 — 표본이 없으면 `undefined`(0 이 아니다).
      *

package/dist/ems-kernel.js

@@ -28,7 +28,7 @@
 import { FlowEngine } from "./flow-engine.js";
 import { firstFitPolicy } from "./allocation-policy.js";
 import { ENERGY_EVENT } from "./contract.js";
-import { EMS_PROPERTY } from "./ems-profile.js";
+import { EMS_PROPERTY, electricalUpstreamOf } from "./ems-profile.js";
 /** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
 export const DEMAND_WINDOW_MS = 15 * 60 * 1000;
 /** 그 시각이 속한 구간의 시작 — 벽시계 경계(00·15·30·45분)에 맞춘다. */
@@ -128,9 +128,17 @@ export class EmsKernel extends FlowEngine {
         const locOf = new Map();
         for (const e of this.boardDef?.equipment ?? [])
             locOf.set(e.id, e.homeLocation);
+        /*
+         * 계층을 **전기 상류**로 걷는다 — 공간 부모가 아니다.
+         *
+         * 예전에는 `parentId` 를 그대로 걸었다. 그때는 분기의 `parentId` 에 수전이 적혀 있어서 답이 같았지만,
+         * 공간 부모(공장·구역)를 적은 모델에서는 그 사슬이 **전기적으로 뜻이 없는 길**을 따라간다. 상류의
+         * 뜻을 읽는 규칙은 한 곳에 있다(`electricalUpstreamOf` — 옛 세대도 그 안에서 흡수한다).
+         */
+        const locs = this.boardDef?.locations ?? [];
         const parentOf = new Map();
-        for (const l of this.boardDef?.locations ?? [])
-            parentOf.set(l.id, l.parentId);
+        for (const l of locs)
+            parentOf.set(l.id, electricalUpstreamOf(locs, l.id));
         /* 계량되고 있는 자리들 — 표본이 실제로 온 계량기의 자리만 센다(선언만 있고 값이 없는 계량기는
            부하에 기여하지 않으므로 계층 판정에서도 제외한다). */
         const meteredLocs = new Set();
@@ -292,8 +300,25 @@ export class EmsKernel extends FlowEngine {
              */
             const roots = this.rootMeterIds();
             const total = [...this.points.values()].reduce((sum, p) => sum + (roots.has(p.id) ? p.kW ?? 0 : 0), 0);
-            if (w.maxKW === undefined || total > w.maxKW)
+            if (w.maxKW === undefined || total > w.maxKW) {
                 w.maxKW = total;
+                /*
+                 * ── 피크가 갱신된 **그 순간**의 지점별 kW 를 붙잡는다 (2026-08-18) ─────────
+                 *
+                 * 요금이 매겨지는 수는 kW(최대수요)이고 전력량(kWh)이 아니다. 그런데 지점별로 남기던 것은
+                 * 구간 전력량뿐이라, 「어느 분기를 깎아야 피크가 내려가나」에 답할 수 없었다 — 전력량이 큰 분기가
+                 * 피크를 만든 분기와 다를 수 있다(하루 종일 조금씩 쓰는 부하 vs 잠깐 크게 쓰는 부하).
+                 *
+                 * 나중에 계산할 수 없는 값이다: 표본을 보관하지 않으므로 그 순간이 지나면 각 지점이 얼마였는지
+                 * 알 길이 없다. 그래서 **갱신되는 순간에** 찍는다.
+                 *
+                 * 뿌리만이 아니라 **모든 지점**을 찍는다: 뿌리 합이 피크를 만들지만, 그 피크를 누가 만들었는지는
+                 * 하위 계량이 답한다. kW 를 모르는 지점은 넣지 않는다(0 으로 만들지 않는다).
+                 */
+                w.pointsAtPeak = [...this.points.values()]
+                    .filter(p => Number.isFinite(Number(p.kW)))
+                    .map(p => ({ id: p.id, kW: Number(p.kW) }));
+            }
             w.samples++;
             w.meanKW = (w.meanKW === undefined ? total : (w.meanKW * (w.samples - 1) + total) / w.samples);
         }
@@ -379,6 +404,11 @@ export class EmsKernel extends FlowEngine {
                  * `root` 는 계층 판정을 우리가 말해 주는 것이다 — 소비처가 같은 규칙을 다시 쓰면 갈라진다.
                  */
                 ...(pointShares.length ? { points: pointShares } : {}),
+                /*
+                 * 피크 순간의 지점별 kW — 요금이 걸린 수는 kW 다. 이것이 없으면 저널을 읽는 쪽은 「어느 분기를
+                 * 깎아야 피크가 내려가나」에 답할 수 없다(전력량이 큰 분기와 피크를 만든 분기는 다를 수 있다).
+                 */
+                ...(w.pointsAtPeak?.length ? { pointsAtPeak: w.pointsAtPeak } : {}),
                 /*
                  * **만든 값이면 그렇게 말한다.** 상태에만 표시하고 사실에는 빠뜨리면, 저널을 읽는 쪽
                  * (성과·이력·보고서)이 시뮬레이션의 수를 계측으로 읽는다 — 값이 그럴듯할수록 위험하다.

package/dist/ems-profile.d.ts

@@ -67,3 +67,22 @@ export interface EmsPropertySpec {
 }
 export declare const EMS_PROPERTY_SPEC: Record<string, EmsPropertySpec>;
 export declare const EMS_TYPES: TwinTypeInfo[];
+/**
+ * 이 자리의 **전기 상류** — 어디서 전기를 받는가.
+ *
+ * ── 왜 함수로 두나 (2026-08-18) ─────────────────────────────────────────────
+ * 두 세대가 섞여 있다. 새 모델은 `upstream` 을 적고, 그 전 모델은 분기의 `parentId` 에 수전을 적었다.
+ * 판정을 소비처마다 쓰면(호스트·계통도·커널) 한쪽만 고쳐지고 그때부터 화면과 계산이 다른 계통을 말한다.
+ * 그래서 **읽는 규칙을 한 곳**에 둔다.
+ *
+ * 옛 세대를 흡수하는 조건이 좁다: `parentId` 가 **전기 자리**(수전·분기·구역 계량)를 가리킬 때만
+ * 상류로 읽는다. 공장·구역 같은 공간 부모를 상류로 읽으면 없는 결선을 만들어 낸다.
+ */
+export declare function electricalUpstreamOf(locations: readonly {
+    id: string;
+    type?: string;
+    parentId?: string;
+    upstreamId?: string;
+}[] | undefined | null, id: string): string | undefined;
+/** 전기 계통의 자리인가 — 수전·분기·구역 계량. */
+export declare function isElectricalLocationType(type: string): boolean;

package/dist/ems-profile.js

@@ -210,3 +210,30 @@ export const EMS_TYPES = [
         capabilities: ['curtailable', 'metered', 'operable']
     }
 ];
+/**
+ * 이 자리의 **전기 상류** — 어디서 전기를 받는가.
+ *
+ * ── 왜 함수로 두나 (2026-08-18) ─────────────────────────────────────────────
+ * 두 세대가 섞여 있다. 새 모델은 `upstream` 을 적고, 그 전 모델은 분기의 `parentId` 에 수전을 적었다.
+ * 판정을 소비처마다 쓰면(호스트·계통도·커널) 한쪽만 고쳐지고 그때부터 화면과 계산이 다른 계통을 말한다.
+ * 그래서 **읽는 규칙을 한 곳**에 둔다.
+ *
+ * 옛 세대를 흡수하는 조건이 좁다: `parentId` 가 **전기 자리**(수전·분기·구역 계량)를 가리킬 때만
+ * 상류로 읽는다. 공장·구역 같은 공간 부모를 상류로 읽으면 없는 결선을 만들어 낸다.
+ */
+export function electricalUpstreamOf(locations, id) {
+    const byId = new Map((locations ?? []).filter(l => l?.id).map(l => [String(l.id), l]));
+    const self = byId.get(String(id));
+    if (!self)
+        return undefined;
+    if (self.upstreamId)
+        return String(self.upstreamId);
+    const parent = self.parentId ? byId.get(String(self.parentId)) : undefined;
+    if (!parent)
+        return undefined;
+    return isElectricalLocationType(String(parent.type ?? '')) ? String(parent.id) : undefined;
+}
+/** 전기 계통의 자리인가 — 수전·분기·구역 계량. */
+export function isElectricalLocationType(type) {
+    return EMS_LOCATION_TYPES.includes(type);
+}

package/dist-cjs/index.cjs

@@ -97,6 +97,7 @@ __export(index_exports, {
   documentPath: () => documentPath,
   dueStatusOf: () => dueStatusOf,
   effectivityAt: () => effectivityAt,
+  electricalUpstreamOf: () => electricalUpstreamOf,
   electricityCost: () => electricityCost,
   energyIntensity: () => energyIntensity,
   energyOfWindows: () => energyOfWindows,
@@ -112,6 +113,7 @@ __export(index_exports, {
   ingest: () => ingest,
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  isElectricalLocationType: () => isElectricalLocationType,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyRecord: () => isEnergyRecord,
   isEquipmentLevel: () => isEquipmentLevel,
@@ -1894,6 +1896,18 @@ var EMS_TYPES = [
     capabilities: ["curtailable", "metered", "operable"]
   }
 ];
+function electricalUpstreamOf(locations, id) {
+  const byId = new Map((locations ?? []).filter((l) => l?.id).map((l) => [String(l.id), l]));
+  const self = byId.get(String(id));
+  if (!self) return void 0;
+  if (self.upstreamId) return String(self.upstreamId);
+  const parent = self.parentId ? byId.get(String(self.parentId)) : void 0;
+  if (!parent) return void 0;
+  return isElectricalLocationType(String(parent.type ?? "")) ? String(parent.id) : void 0;
+}
+function isElectricalLocationType(type) {
+  return EMS_LOCATION_TYPES.includes(type);
+}
 
 // src/capability.ts
 var CAPABILITIES = {
@@ -6049,8 +6063,9 @@ var EmsKernel = class extends FlowEngine {
   rootMeterIds() {
     const locOf = /* @__PURE__ */ new Map();
     for (const e of this.boardDef?.equipment ?? []) locOf.set(e.id, e.homeLocation);
+    const locs = this.boardDef?.locations ?? [];
     const parentOf = /* @__PURE__ */ new Map();
-    for (const l of this.boardDef?.locations ?? []) parentOf.set(l.id, l.parentId);
+    for (const l of locs) parentOf.set(l.id, electricalUpstreamOf(locs, l.id));
     const meteredLocs = /* @__PURE__ */ new Set();
     for (const id of this.points.keys()) {
       const loc = locOf.get(id);
@@ -6169,7 +6184,10 @@ var EmsKernel = class extends FlowEngine {
     if (kW !== void 0) {
       const roots = this.rootMeterIds();
       const total = [...this.points.values()].reduce((sum, p) => sum + (roots.has(p.id) ? p.kW ?? 0 : 0), 0);
-      if (w.maxKW === void 0 || total > w.maxKW) w.maxKW = total;
+      if (w.maxKW === void 0 || total > w.maxKW) {
+        w.maxKW = total;
+        w.pointsAtPeak = [...this.points.values()].filter((p) => Number.isFinite(Number(p.kW))).map((p) => ({ id: p.id, kW: Number(p.kW) }));
+      }
       w.samples++;
       w.meanKW = w.meanKW === void 0 ? total : (w.meanKW * (w.samples - 1) + total) / w.samples;
     }
@@ -6247,6 +6265,11 @@ var EmsKernel = class extends FlowEngine {
          * `root` 는 계층 판정을 우리가 말해 주는 것이다 — 소비처가 같은 규칙을 다시 쓰면 갈라진다.
          */
         ...pointShares.length ? { points: pointShares } : {},
+        /*
+         * 피크 순간의 지점별 kW — 요금이 걸린 수는 kW 다. 이것이 없으면 저널을 읽는 쪽은 「어느 분기를
+         * 깎아야 피크가 내려가나」에 답할 수 없다(전력량이 큰 분기와 피크를 만든 분기는 다를 수 있다).
+         */
+        ...w.pointsAtPeak?.length ? { pointsAtPeak: w.pointsAtPeak } : {},
         /*
          * **만든 값이면 그렇게 말한다.** 상태에만 표시하고 사실에는 빠뜨리면, 저널을 읽는 쪽
          * (성과·이력·보고서)이 시뮬레이션의 수를 계측으로 읽는다 — 값이 그럴듯할수록 위험하다.
@@ -6942,6 +6965,7 @@ function retiredVocabularyIn(line) {
   documentPath,
   dueStatusOf,
   effectivityAt,
+  electricalUpstreamOf,
   electricityCost,
   energyIntensity,
   energyOfWindows,
@@ -6957,6 +6981,7 @@ function retiredVocabularyIn(line) {
   ingest,
   ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
+  isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyRecord,
   isEquipmentLevel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {