@operato/twin-kernel 0.7.74 → 0.7.75

package/dist/contract.d.ts

@@ -2035,6 +2035,18 @@ export interface EnergyState {
      * 틀렸다는 뜻이고, 사람이 찾아내지 않아도 드러나야 한다.
      */
     lastBill?: EnergyBillData;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `periodStart` 는 마지막 청구서의 끝이다(그 뒤가 아직 청구되지 않은 구간). 그것이 바뀌면 처음부터
+     * 다시 센다 — 지난 주기의 최고가 이번 주기를 정하지 않는다.
+     */
+    demandHigh?: {
+        kW: number;
+        atTo: ISOTime;
+        periodStart?: ISOTime;
+        since: ISOTime;
+    };
     /**
      * 설비마다 **지금 기간의 발전 관측** — 기간 발전량을 확정할 때 쓰는 기준점.
      *

package/dist/ems-kernel.d.ts

@@ -199,6 +199,13 @@ export declare class EmsKernel extends FlowEngine {
     private unclosedGenerationPeriods;
     /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
     private lastBill?;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+     * 그것이 바뀌면 처음부터 다시 센다.
+     */
+    private demandHigh?;
     private applyEquipmentEnergy;
     /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
     private unknownEquipmentReports;
@@ -242,6 +249,31 @@ export declare class EmsKernel extends FlowEngine {
      * 어려우므로 높게 부르지 않는다(경보가 소음이 되면 사람이 경보 자체를 읽지 않는다).
      */
     protected collectAttentions(): Attention[];
+    /**
+     * **이 주기의 최고가 요금적용전력을 넘었다** — 다음 주기의 기본요금이 오른다.
+     *
+     * ── 왜 계약 초과와 다른 신호인가 (2026-08-29) ────────────────────────────
+     * 계약 초과는 약정 위반이고 지금 조치할 일이다(줄이면 된다). 이쪽은 **이미 일어난 일**이다 —
+     * 넘은 순간 다음 주기의 기준이 정해지고, 지금 줄여도 되돌아가지 않는다. 사람이 할 일이 다르므로
+     * 신호도 다르다.
+     *
+     * ── 한 번만 울린다 ──────────────────────────────────────────────────────────
+     * 넘으면 그 주기 내내 참이다. 구간마다 다시 울리면 소음이 되고, 소음이 되면 아무도 안 본다.
+     * 그래서 신호의 id 를 주기로 묶고 「처음 넘은 시각」이 아니라 **그 주기의 최고**를 싣는다.
+     *
+     * ── 늦게 안다 ───────────────────────────────────────────────────────────────
+     * 최고 수요는 지난 구간이 마감되어야 온다(지금 원본은 시간마다). 그래서 넘은 것을 최대 한 시간
+     * 뒤에 안다. 그 사실을 `observedTo` 로 함께 내어 화면이 「언제까지의 값인가」를 말할 수 있게 한다.
+     */
+    protected billingDemandAttention(): Attention | undefined;
+    /**
+     * 선언된 **요금적용전력** — 기본요금이 걸리는 기준(§`EMS_PROPERTY.billingDemandKW`).
+     *
+     * 청구서가 그 값을 실어 오면 그쪽이 먼저다(§`billingDemandKW()`). 이것은 청구가 오지 않는 현장의 몫이다.
+     */
+    private declaredBillingDemandKW;
+    /** 지금 쓰는 요금적용전력 — **청구서가 먼저다.** 매달 바뀌는 값이라 선언은 곧 낡는다. */
+    private billingDemandKW;
     /** 계약을 선언한 수전 자리 — 주의가 가리킬 대상. 없으면 대상을 지어내지 않는다. */
     private incomingLocationId;
     /** 감축 가능으로 **선언된** 설비 — 커널이 능력을 짐작하지 않는다(타입이 선언한다). */

package/dist/ems-kernel.js

@@ -315,6 +315,26 @@ export class EmsKernel extends FlowEngine {
             point.lastPeriodTo = d.to;
         if (d?.basis)
             point.lastPeriodBasis = d.basis;
+        /*
+         * ── 이 청구 주기의 최고 수요 (2026-08-29) ─────────────────────────────────
+         *
+         * 기본요금은 이 값으로 다시 정해진다. 그래서 **넘은 순간과 얼마나 넘었는지**를 기억한다.
+         *
+         * 주기의 시작은 마지막 청구서의 끝이다(그 뒤가 아직 청구되지 않은 구간이다). 청구서가 없으면
+         * 관측을 시작한 때부터다 — 그 사실은 `since` 가 말한다.
+         *
+         * 구간마다 새로 세지 않는다: 한 번 넘으면 그 주기 내내 참이고, 매 구간 다시 알리면 소음이 된다.
+         */
+        const maxKW = Number(d?.maxKW);
+        if (Number.isFinite(maxKW) && maxKW >= 0 && d?.to) {
+            const periodStart = this.lastBill?.to;
+            /* 청구 주기가 바뀌었으면 처음부터 다시 센다 — 지난 주기의 최고가 이번 주기를 정하지 않는다. */
+            if (this.demandHigh && periodStart && this.demandHigh.periodStart !== periodStart)
+                this.demandHigh = undefined;
+            if (!this.demandHigh || maxKW > this.demandHigh.kW) {
+                this.demandHigh = { kW: maxKW, atTo: String(d.to), periodStart, since: this.demandHigh?.since ?? String(d.to) };
+            }
+        }
         this.revision++;
     }
     /**
@@ -582,6 +602,13 @@ export class EmsKernel extends FlowEngine {
     unclosedGenerationPeriods = 0;
     /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
     lastBill;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+     * 그것이 바뀌면 처음부터 다시 센다.
+     */
+    demandHigh;
     applyEquipmentEnergy(envelope) {
         const d = envelope.data;
         const id = String(d?.equipmentId ?? '').trim();
@@ -945,6 +972,9 @@ export class EmsKernel extends FlowEngine {
      */
     collectAttentions() {
         const out = super.collectAttentions();
+        const billingOver = this.billingDemandAttention();
+        if (billingOver)
+            out.push(billingOver);
         const w = this.open;
         if (!w || w.contractKW === undefined || w.meanKW === undefined)
             return out;
@@ -988,6 +1018,77 @@ export class EmsKernel extends FlowEngine {
         });
         return out;
     }
+    /**
+     * **이 주기의 최고가 요금적용전력을 넘었다** — 다음 주기의 기본요금이 오른다.
+     *
+     * ── 왜 계약 초과와 다른 신호인가 (2026-08-29) ────────────────────────────
+     * 계약 초과는 약정 위반이고 지금 조치할 일이다(줄이면 된다). 이쪽은 **이미 일어난 일**이다 —
+     * 넘은 순간 다음 주기의 기준이 정해지고, 지금 줄여도 되돌아가지 않는다. 사람이 할 일이 다르므로
+     * 신호도 다르다.
+     *
+     * ── 한 번만 울린다 ──────────────────────────────────────────────────────────
+     * 넘으면 그 주기 내내 참이다. 구간마다 다시 울리면 소음이 되고, 소음이 되면 아무도 안 본다.
+     * 그래서 신호의 id 를 주기로 묶고 「처음 넘은 시각」이 아니라 **그 주기의 최고**를 싣는다.
+     *
+     * ── 늦게 안다 ───────────────────────────────────────────────────────────────
+     * 최고 수요는 지난 구간이 마감되어야 온다(지금 원본은 시간마다). 그래서 넘은 것을 최대 한 시간
+     * 뒤에 안다. 그 사실을 `observedTo` 로 함께 내어 화면이 「언제까지의 값인가」를 말할 수 있게 한다.
+     */
+    billingDemandAttention() {
+        const high = this.demandHigh;
+        const basis = this.billingDemandKW();
+        if (!high || basis === undefined || high.kW <= basis)
+            return undefined;
+        const over = high.kW - basis;
+        const ratio = over / basis;
+        return {
+            id: `billing-demand-exceeded:${high.periodStart ?? high.since}`,
+            kind: 'billing-demand-exceeded',
+            severity: ratio > 0.15 ? 'high' : 'medium',
+            anchor: { locationId: this.incomingLocationId() },
+            params: {
+                peakKW: Math.round(high.kW),
+                billingDemandKW: Math.round(basis),
+                overKW: Math.round(over),
+                /* 값의 출처 — 청구서가 말한 기준인지 현장의 선언인지. 선언은 곧 낡는다. */
+                basisFrom: Number.isFinite(Number(this.lastBill?.billingDemandKW)) ? 'bill' : 'declaration',
+                observedTo: high.atTo,
+                periodSince: high.since
+            },
+            /*
+             * 조치를 걸지 않는다. **이미 일어난 일이라 되돌릴 수 없다** — 지금 줄여도 이 주기의 최고는
+             * 그대로다. 조치를 붙이면 화면이 「누르면 해결된다」고 거짓말한다.
+             */
+            recommendedActions: []
+        };
+    }
+    /**
+     * 선언된 **요금적용전력** — 기본요금이 걸리는 기준(§`EMS_PROPERTY.billingDemandKW`).
+     *
+     * 청구서가 그 값을 실어 오면 그쪽이 먼저다(§`billingDemandKW()`). 이것은 청구가 오지 않는 현장의 몫이다.
+     */
+    declaredBillingDemandKW() {
+        let max;
+        for (const loc of this.boardDef?.locations ?? []) {
+            for (const p of loc.properties ?? []) {
+                if (p.id !== EMS_PROPERTY.billingDemandKW)
+                    continue;
+                const v = Number(p.value);
+                if (!Number.isFinite(v) || v <= 0)
+                    continue;
+                if (max === undefined || v > max)
+                    max = v;
+            }
+        }
+        return max;
+    }
+    /** 지금 쓰는 요금적용전력 — **청구서가 먼저다.** 매달 바뀌는 값이라 선언은 곧 낡는다. */
+    billingDemandKW() {
+        const billed = Number(this.lastBill?.billingDemandKW);
+        if (Number.isFinite(billed) && billed > 0)
+            return billed;
+        return this.declaredBillingDemandKW();
+    }
     /** 계약을 선언한 수전 자리 — 주의가 가리킬 대상. 없으면 대상을 지어내지 않는다. */
     incomingLocationId() {
         for (const loc of this.boardDef?.locations ?? []) {
@@ -1381,6 +1482,9 @@ export class EmsKernel extends FlowEngine {
         /* 청구서도 이어받는다 — 재기동마다 사라지면 우리 계산과 견줄 기준이 없어진다. */
         if (e.lastBill?.from && e.lastBill?.to)
             this.lastBill = { ...e.lastBill };
+        /* 이 주기의 최고도 이어받는다 — 재기동마다 0 으로 돌아가면 이미 넘은 것을 못 넘었다고 말한다. */
+        if (Number.isFinite(Number(e.demandHigh?.kW)) && e.demandHigh?.since)
+            this.demandHigh = { ...e.demandHigh };
     }
     getSnapshot() {
         const snap = super.getSnapshot();
@@ -1406,6 +1510,7 @@ export class EmsKernel extends FlowEngine {
                 : {}),
             ...(this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {}),
             ...(this.lastBill ? { lastBill: { ...this.lastBill } } : {}),
+            ...(this.demandHigh ? { demandHigh: { ...this.demandHigh } } : {}),
             ...(contractKW !== undefined ? { contractKW } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
             ...(this.flowRequests.size

package/dist-cjs/index.cjs

@@ -7980,6 +7980,14 @@ var EmsKernel = class extends FlowEngine {
     if (d?.from) point.lastPeriodFrom = d.from;
     if (d?.to) point.lastPeriodTo = d.to;
     if (d?.basis) point.lastPeriodBasis = d.basis;
+    const maxKW = Number(d?.maxKW);
+    if (Number.isFinite(maxKW) && maxKW >= 0 && d?.to) {
+      const periodStart = this.lastBill?.to;
+      if (this.demandHigh && periodStart && this.demandHigh.periodStart !== periodStart) this.demandHigh = void 0;
+      if (!this.demandHigh || maxKW > this.demandHigh.kW) {
+        this.demandHigh = { kW: maxKW, atTo: String(d.to), periodStart, since: this.demandHigh?.since ?? String(d.to) };
+      }
+    }
     this.revision++;
   }
   /**
@@ -8158,6 +8166,13 @@ var EmsKernel = class extends FlowEngine {
   unclosedGenerationPeriods = 0;
   /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
   lastBill;
+  /**
+   * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+   *
+   * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+   * 그것이 바뀌면 처음부터 다시 센다.
+   */
+  demandHigh;
   applyEquipmentEnergy(envelope) {
     const d = envelope.data;
     const id = String(d?.equipmentId ?? "").trim();
@@ -8397,6 +8412,8 @@ var EmsKernel = class extends FlowEngine {
    */
   collectAttentions() {
     const out = super.collectAttentions();
+    const billingOver = this.billingDemandAttention();
+    if (billingOver) out.push(billingOver);
     const w = this.open;
     if (!w || w.contractKW === void 0 || w.meanKW === void 0) return out;
     const projected = w.meanKW;
@@ -8435,6 +8452,72 @@ var EmsKernel = class extends FlowEngine {
     });
     return out;
   }
+  /**
+   * **이 주기의 최고가 요금적용전력을 넘었다** — 다음 주기의 기본요금이 오른다.
+   *
+   * ── 왜 계약 초과와 다른 신호인가 (2026-08-29) ────────────────────────────
+   * 계약 초과는 약정 위반이고 지금 조치할 일이다(줄이면 된다). 이쪽은 **이미 일어난 일**이다 —
+   * 넘은 순간 다음 주기의 기준이 정해지고, 지금 줄여도 되돌아가지 않는다. 사람이 할 일이 다르므로
+   * 신호도 다르다.
+   *
+   * ── 한 번만 울린다 ──────────────────────────────────────────────────────────
+   * 넘으면 그 주기 내내 참이다. 구간마다 다시 울리면 소음이 되고, 소음이 되면 아무도 안 본다.
+   * 그래서 신호의 id 를 주기로 묶고 「처음 넘은 시각」이 아니라 **그 주기의 최고**를 싣는다.
+   *
+   * ── 늦게 안다 ───────────────────────────────────────────────────────────────
+   * 최고 수요는 지난 구간이 마감되어야 온다(지금 원본은 시간마다). 그래서 넘은 것을 최대 한 시간
+   * 뒤에 안다. 그 사실을 `observedTo` 로 함께 내어 화면이 「언제까지의 값인가」를 말할 수 있게 한다.
+   */
+  billingDemandAttention() {
+    const high = this.demandHigh;
+    const basis = this.billingDemandKW();
+    if (!high || basis === void 0 || high.kW <= basis) return void 0;
+    const over = high.kW - basis;
+    const ratio = over / basis;
+    return {
+      id: `billing-demand-exceeded:${high.periodStart ?? high.since}`,
+      kind: "billing-demand-exceeded",
+      severity: ratio > 0.15 ? "high" : "medium",
+      anchor: { locationId: this.incomingLocationId() },
+      params: {
+        peakKW: Math.round(high.kW),
+        billingDemandKW: Math.round(basis),
+        overKW: Math.round(over),
+        /* 값의 출처 — 청구서가 말한 기준인지 현장의 선언인지. 선언은 곧 낡는다. */
+        basisFrom: Number.isFinite(Number(this.lastBill?.billingDemandKW)) ? "bill" : "declaration",
+        observedTo: high.atTo,
+        periodSince: high.since
+      },
+      /*
+       * 조치를 걸지 않는다. **이미 일어난 일이라 되돌릴 수 없다** — 지금 줄여도 이 주기의 최고는
+       * 그대로다. 조치를 붙이면 화면이 「누르면 해결된다」고 거짓말한다.
+       */
+      recommendedActions: []
+    };
+  }
+  /**
+   * 선언된 **요금적용전력** — 기본요금이 걸리는 기준(§`EMS_PROPERTY.billingDemandKW`).
+   *
+   * 청구서가 그 값을 실어 오면 그쪽이 먼저다(§`billingDemandKW()`). 이것은 청구가 오지 않는 현장의 몫이다.
+   */
+  declaredBillingDemandKW() {
+    let max;
+    for (const loc of this.boardDef?.locations ?? []) {
+      for (const p of loc.properties ?? []) {
+        if (p.id !== EMS_PROPERTY.billingDemandKW) continue;
+        const v = Number(p.value);
+        if (!Number.isFinite(v) || v <= 0) continue;
+        if (max === void 0 || v > max) max = v;
+      }
+    }
+    return max;
+  }
+  /** 지금 쓰는 요금적용전력 — **청구서가 먼저다.** 매달 바뀌는 값이라 선언은 곧 낡는다. */
+  billingDemandKW() {
+    const billed = Number(this.lastBill?.billingDemandKW);
+    if (Number.isFinite(billed) && billed > 0) return billed;
+    return this.declaredBillingDemandKW();
+  }
   /** 계약을 선언한 수전 자리 — 주의가 가리킬 대상. 없으면 대상을 지어내지 않는다. */
   incomingLocationId() {
     for (const loc of this.boardDef?.locations ?? []) {
@@ -8715,6 +8798,7 @@ var EmsKernel = class extends FlowEngine {
     }
     if (Number.isFinite(e.unclosedGenerationPeriods)) this.unclosedGenerationPeriods = Number(e.unclosedGenerationPeriods);
     if (e.lastBill?.from && e.lastBill?.to) this.lastBill = { ...e.lastBill };
+    if (Number.isFinite(Number(e.demandHigh?.kW)) && e.demandHigh?.since) this.demandHigh = { ...e.demandHigh };
   }
   getSnapshot() {
     const snap = super.getSnapshot();
@@ -8736,6 +8820,7 @@ var EmsKernel = class extends FlowEngine {
       } : {},
       ...this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {},
       ...this.lastBill ? { lastBill: { ...this.lastBill } } : {},
+      ...this.demandHigh ? { demandHigh: { ...this.demandHigh } } : {},
       ...contractKW !== void 0 ? { contractKW } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
       ...this.flowRequests.size ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) } : {}

package/package.json

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