@operato/twin-kernel 0.7.14 → 0.7.15

package/dist/contract.d.ts

@@ -1210,8 +1210,27 @@ export interface MeterPointState {
 export interface DemandWindowState {
     startMs: number;
     endMs: number;
-    /** 그 구간의 최대 순간부하 — 표본이 없으면 `undefined`(0 이 아니다). */
+    /**
+     * 그 구간의 최대 순간부하 — 표본이 없으면 `undefined`(0 이 아니다).
+     *
+     * **계통에서 끌어온 수요**다(요금이 이것에 매겨진다). 현장에 발전·축전이 있으면 설비가 끌어당긴
+     * 양과 다르다 — 그 차이는 `grossMaxKW` 와의 간격으로 읽는다.
+     */
     maxKW?: number;
+    /**
+     * 설비가 **끌어당긴** 최대(발전·방전 차감 전, 충전 포함).
+     *
+     * ── 왜 둘을 함께 두나 (2026-08-17) ────────────────────────────────────────
+     * 요금은 계통 수요(`maxKW`)로 매겨지지만, 「무엇이 그 수요를 만들었나」는 설비 부하가 답한다.
+     * 하나만 두면 둘 중 하나를 잃는다: 순수요만 두면 태양광이 잠깐 가려졌을 때 왜 피크가 올랐는지 설명할
+     * 수 없고, 총부하만 두면 요금이 실제보다 커 보인다.
+     *
+     * 그리고 **이 둘의 간격이 곧 깎인 양**이다(피크 셰이빙). 같은 표본에서 나온 두 최대값이므로 비교가
+     * 성립한다 — 서로 다른 창의 값을 견주는 것이 아니다.
+     *
+     * 발전·축전을 선언하지 않은 현장에서는 `maxKW` 와 같다(그때는 차감할 것이 없다).
+     */
+    grossMaxKW?: number;
     /** 표본 평균 부하 — 요금 산정의 평균 수요에 대응한다. */
     meanKW?: number;
     /** **kW 를 실은** 표본 수 — 부하 판정의 근거 수다(받은 표본 전체가 아니다). */

package/dist/ems-kernel.js

@@ -309,6 +309,9 @@ export class EmsKernel extends FlowEngine {
                 startMs: w.startMs,
                 endMs: w.endMs,
                 ...(w.maxKW !== undefined ? { maxKW: w.maxKW } : {}),
+                /* 총부하도 사실로 남긴다 — 이것이 없으면 저널을 읽는 쪽은 「무엇이 깎였나」를 되짚을 수 없다
+                   (요금은 순수요로 매겨지지만, 그 수요를 만든 것은 설비 부하다). */
+                ...(w.grossMaxKW !== undefined ? { grossMaxKW: w.grossMaxKW } : {}),
                 ...(w.meanKW !== undefined ? { meanKW: w.meanKW } : {}),
                 samples: w.samples,
                 ...(w.contractKW !== undefined ? { contractKW: w.contractKW } : {}),
@@ -450,14 +453,50 @@ export class EmsKernel extends FlowEngine {
         }
         if (!counted)
             return; // 셀 것이 하나도 없으면 구간에 값을 넣지 않는다(0 을 주장하지 않는다)
+        /*
+         * ── 계통에서 끌어오는 것은 **순수요**다 (2026-08-17) ──────────────────────
+         *
+         * 그동안 이 함수는 소비만 셌다. 그래서 태양광이 400kW 를 만들고 배터리가 300kW 를 내보내도 계통
+         * 수요가 한 톨도 줄지 않았다 — 「배터리로 피크를 깎는다」가 시뮬에서 성립하지 않는 상태였고,
+         * 그 위에 세운 요금·계약 판정도 그만큼 틀렸다.
+         *
+         * 요금이 매겨지는 것은 계량 지점을 지나는 전력이다:
+         *
+         *   순수요 = 설비 부하 + 충전 − 발전 − 방전
+         *
+         * 충전이 **더해지는** 이유: 배터리를 채우는 동안 그 전기도 계통에서 온다(피크를 만들 수 있다 —
+         * 잘못된 시각에 충전하면 깎으려던 피크를 오히려 키운다. 그 사실이 값에 보여야 한다).
+         *
+         * 음수는 **역송**이지 음의 수요가 아니다. 계통 수요는 0 에서 멈추고, 남는 발전은 그 설비의
+         * `exportKW` 가 이미 사실로 말한다(여기서 다시 만들지 않는다).
+         */
+        let generated = 0;
+        let discharged = 0;
+        let charged = 0;
+        for (const m of this.equipment.values()) {
+            const g = Number(m.generatedKW);
+            if (Number.isFinite(g) && g > 0)
+                generated += g;
+            const d = Number(m.dischargeKW);
+            if (Number.isFinite(d) && d > 0)
+                discharged += d;
+            const c = Number(m.chargeKW);
+            if (Number.isFinite(c) && c > 0)
+                charged += c;
+        }
+        const gross = total + charged;
+        const net = Math.max(0, gross - generated - discharged);
         this.closeDue(atMs);
         this.openWindow(atMs);
         const w = this.open;
         w.derived = true;
-        if (w.maxKW === undefined || total > w.maxKW)
-            w.maxKW = total;
+        /* 요금이 보는 수는 순수요다. 총부하는 「무엇이 그 수요를 만들었나」를 위해 함께 남긴다. */
+        if (w.maxKW === undefined || net > w.maxKW)
+            w.maxKW = net;
+        if (w.grossMaxKW === undefined || gross > w.grossMaxKW)
+            w.grossMaxKW = gross;
         w.samples++;
-        w.meanKW = w.meanKW === undefined ? total : (w.meanKW * (w.samples - 1) + total) / w.samples;
+        w.meanKW = w.meanKW === undefined ? net : (w.meanKW * (w.samples - 1) + net) / w.samples;
         this.revision++;
         this.judgeOpenWindow(atMs);
     }

package/dist/energy-attribution.d.ts

@@ -185,6 +185,15 @@ export interface WindowedEnergy {
     peakKW?: number;
     /** 그 최대수요가 난 구간의 시작 — 「언제였나」를 물으면 답할 수 있어야 한다. */
     peakStartMs?: number;
+    /**
+     * **그 피크 구간에서 설비가 끌어당긴 최대**(발전·방전 차감 전).
+     *
+     * `peakKW` 와의 간격이 그 순간에 깎인 양이다(태양광·배터리가 계통에서 덜어낸 몫). 다른 구간의 값과
+     * 견주지 않는다 — **같은 구간의 두 수**여야 그 차이가 뜻을 갖는다.
+     *
+     * 발전·축전을 선언하지 않은 현장에서는 `peakKW` 와 같다.
+     */
+    peakGrossKW?: number;
     /**
      * 어떻게 얻었나 — **파생임을 숨기지 않는다.**
      *  · `mean-kw` — 구간 평균부하 × 구간 길이. 표본의 평균이므로 **추정**이다.
@@ -217,6 +226,7 @@ export declare function energyOfWindows(windows: readonly {
     endMs: number;
     meanKW?: number;
     maxKW?: number;
+    grossMaxKW?: number;
 }[], range?: {
     startMs: number;
     endMs: number;

package/dist/energy-attribution.js

@@ -205,6 +205,7 @@ export function energyOfWindows(windows, range) {
     let last;
     let peakKW;
     let peakStartMs;
+    let peakGrossKW;
     for (const w of windows ?? []) {
         if (!inRange(w))
             continue;
@@ -216,6 +217,9 @@ export function energyOfWindows(windows, range) {
         if (Number.isFinite(max) && (peakKW === undefined || max > peakKW)) {
             peakKW = max;
             peakStartMs = Number(w.startMs);
+            /* **그 구간의** 총부하를 함께 집는다 — 다른 구간의 총부하와 견주면 차이가 뜻을 잃는다. */
+            const gross = Number(w.grossMaxKW);
+            peakGrossKW = Number.isFinite(gross) ? gross : undefined;
         }
         const mean = Number(w.meanKW);
         const hours = (Number(w.endMs) - Number(w.startMs)) / 3_600_000;
@@ -233,6 +237,7 @@ export function energyOfWindows(windows, range) {
     return {
         ...(counted > 0 ? { kWh } : {}),
         ...(peakKW !== undefined ? { peakKW, peakStartMs } : {}),
+        ...(peakGrossKW !== undefined ? { peakGrossKW } : {}),
         basis: 'mean-kw',
         counted,
         skipped,

package/dist-cjs/index.cjs

@@ -6019,6 +6019,9 @@ var EmsKernel = class extends FlowEngine {
         startMs: w.startMs,
         endMs: w.endMs,
         ...w.maxKW !== void 0 ? { maxKW: w.maxKW } : {},
+        /* 총부하도 사실로 남긴다 — 이것이 없으면 저널을 읽는 쪽은 「무엇이 깎였나」를 되짚을 수 없다
+           (요금은 순수요로 매겨지지만, 그 수요를 만든 것은 설비 부하다). */
+        ...w.grossMaxKW !== void 0 ? { grossMaxKW: w.grossMaxKW } : {},
         ...w.meanKW !== void 0 ? { meanKW: w.meanKW } : {},
         samples: w.samples,
         ...w.contractKW !== void 0 ? { contractKW: w.contractKW } : {},
@@ -6144,13 +6147,27 @@ var EmsKernel = class extends FlowEngine {
       }
     }
     if (!counted) return;
+    let generated = 0;
+    let discharged = 0;
+    let charged = 0;
+    for (const m of this.equipment.values()) {
+      const g = Number(m.generatedKW);
+      if (Number.isFinite(g) && g > 0) generated += g;
+      const d = Number(m.dischargeKW);
+      if (Number.isFinite(d) && d > 0) discharged += d;
+      const c = Number(m.chargeKW);
+      if (Number.isFinite(c) && c > 0) charged += c;
+    }
+    const gross = total + charged;
+    const net = Math.max(0, gross - generated - discharged);
     this.closeDue(atMs);
     this.openWindow(atMs);
     const w = this.open;
     w.derived = true;
-    if (w.maxKW === void 0 || total > w.maxKW) w.maxKW = total;
+    if (w.maxKW === void 0 || net > w.maxKW) w.maxKW = net;
+    if (w.grossMaxKW === void 0 || gross > w.grossMaxKW) w.grossMaxKW = gross;
     w.samples++;
-    w.meanKW = w.meanKW === void 0 ? total : (w.meanKW * (w.samples - 1) + total) / w.samples;
+    w.meanKW = w.meanKW === void 0 ? net : (w.meanKW * (w.samples - 1) + net) / w.samples;
     this.revision++;
     this.judgeOpenWindow(atMs);
   }
@@ -6461,12 +6478,15 @@ function energyOfWindows(windows, range) {
   let last;
   let peakKW;
   let peakStartMs;
+  let peakGrossKW;
   for (const w of windows ?? []) {
     if (!inRange(w)) continue;
     const max = Number(w.maxKW);
     if (Number.isFinite(max) && (peakKW === void 0 || max > peakKW)) {
       peakKW = max;
       peakStartMs = Number(w.startMs);
+      const gross = Number(w.grossMaxKW);
+      peakGrossKW = Number.isFinite(gross) ? gross : void 0;
     }
     const mean = Number(w.meanKW);
     const hours = (Number(w.endMs) - Number(w.startMs)) / 36e5;
@@ -6482,6 +6502,7 @@ function energyOfWindows(windows, range) {
   return {
     ...counted > 0 ? { kWh } : {},
     ...peakKW !== void 0 ? { peakKW, peakStartMs } : {},
+    ...peakGrossKW !== void 0 ? { peakGrossKW } : {},
     basis: "mean-kw",
     counted,
     skipped,

package/package.json

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