@operato/twin-kernel 0.7.19 → 0.7.20

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`(이벤트에 등장해서 알게 된 자리). 소비처가 둘을 구별해야 한다: 관측으로 알게 된 자리는

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();

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);
@@ -6942,6 +6957,7 @@ function retiredVocabularyIn(line) {
   documentPath,
   dueStatusOf,
   effectivityAt,
+  electricalUpstreamOf,
   electricityCost,
   energyIntensity,
   energyOfWindows,
@@ -6957,6 +6973,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.20",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {