@operato/twin-kernel 0.7.74 → 0.7.76

package/dist/contract.d.ts

@@ -2035,6 +2035,24 @@ export interface EnergyState {
      * 틀렸다는 뜻이고, 사람이 찾아내지 않아도 드러나야 한다.
      */
     lastBill?: EnergyBillData;
+    /**
+     * 마지막으로 받은 **요금 기준** — 이 주기에 적용되는 요금적용전력과 단가.
+     *
+     * 청구서보다 이쪽이 먼저다: 청구서는 끝난 기간의 정산이고 이것은 지금 적용되는 값이다.
+     */
+    tariffBasis?: EnergyTariffBasisData;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `periodStart` 는 마지막 청구서의 끝이다(그 뒤가 아직 청구되지 않은 구간). 그것이 바뀌면 처음부터
+     * 다시 센다 — 지난 주기의 최고가 이번 주기를 정하지 않는다.
+     */
+    demandHigh?: {
+        kW: number;
+        atTo: ISOTime;
+        periodStart?: ISOTime;
+        since: ISOTime;
+    };
     /**
      * 설비마다 **지금 기간의 발전 관측** — 기간 발전량을 확정할 때 쓰는 기준점.
      *
@@ -2462,6 +2480,18 @@ export declare const ENERGY_EVENT: {
      * 쪽인지 말한다.
      */
     readonly usagePeriod: "energy.usage.period";
+    /**
+     * **이 주기에 적용되는 요금 기준이 정해졌다** — 요금적용전력과 기본요금 단가.
+     *
+     * 청구서와 다른 사건이다. 청구서는 끝난 기간의 정산이고 이것은 **지금 적용되는 기준**이다.
+     * 그래서 사건 시각도 다르다 — 청구서는 기간의 끝, 이것은 기간의 시작이다(그때부터 유효하다).
+     *
+     * 이 값은 매 주기 다시 정해진다. 모델의 선언에 적어 두면 사람이 매달 갱신해야 하고, 안 하면 낡은
+     * 값으로 기본요금이 조용히 틀린다. 공급자가 알려 주는 값을 그대로 받는 것이 맞다.
+     *
+     * **금액을 싣지 않는다.** 요금적용전력 × 단가는 커널이 계산한다. 곱을 받으면 그것이 정산인 척한다.
+     */
+    readonly tariffBasis: "energy.tariff.basis";
     /**
      * **청구서가 도착했다** — 공급자가 확정한 금액.
      *
@@ -2717,6 +2747,31 @@ export interface EnergyUsagePeriodData {
  * **커널의 요금 어휘로 받는다**(사용량 요금·기본요금·합계). 공급자마다 청구서의 칸 이름이 다르므로
  * 그 이름을 그대로 들이면 커널이 한 공급자의 모양에 묶인다. 옮기는 것은 커넥터의 일이다.
  */
+/**
+ * 이 주기에 적용되는 요금 기준 — `ENERGY_EVENT.tariffBasis` 의 데이터.
+ *
+ * 사건 시각은 `from` 이다. 「이 시각부터 이 기준이 적용된다」이므로 주기가 끝나기 전에 성립하고,
+ * `to` 로 시각을 잡으면 아직 오지 않은 시각이 저널에 적힌다.
+ */
+export interface EnergyTariffBasisData {
+    from: ISOTime;
+    to: ISOTime;
+    /** 기본요금이 걸리는 기준(kW) — 공급자가 정한다(§`TariffDeclaration.billingDemandKW`). */
+    billingDemandKW?: number;
+    /** 그 기준 1kW 당 기본요금. */
+    demandChargePerKW?: number;
+    currency?: string;
+}
+/**
+ * 청구서 — 공급자가 **정산한** 금액.
+ *
+ * ── 지금 이 문으로 오는 것이 없다 (2026-08-29 확인) ────────────────────────
+ * 붙어 있는 원본에 정산 금액을 주는 조회가 없다. 그 원본이 주는 것은 이 주기의 **요금 기준**이고
+ * 그것은 다른 문으로 받는다(§`EnergyTariffBasisData`).
+ *
+ * 그 둘을 한 문으로 받으면 **우리가 곱한 값을 우리가 다시 빼는** 비교가 된다 — 실제로 한 번 그렇게
+ * 했고, 차이가 0 인 것을 계산이 맞았다는 확인으로 읽었다. 같은 두 값을 두 번 곱한 것이었다.
+ */
 export interface EnergyBillData {
     from: ISOTime;
     to: ISOTime;

package/dist/contract.js

@@ -1046,6 +1046,18 @@ export const ENERGY_EVENT = {
      * 쪽인지 말한다.
      */
     usagePeriod: 'energy.usage.period',
+    /**
+     * **이 주기에 적용되는 요금 기준이 정해졌다** — 요금적용전력과 기본요금 단가.
+     *
+     * 청구서와 다른 사건이다. 청구서는 끝난 기간의 정산이고 이것은 **지금 적용되는 기준**이다.
+     * 그래서 사건 시각도 다르다 — 청구서는 기간의 끝, 이것은 기간의 시작이다(그때부터 유효하다).
+     *
+     * 이 값은 매 주기 다시 정해진다. 모델의 선언에 적어 두면 사람이 매달 갱신해야 하고, 안 하면 낡은
+     * 값으로 기본요금이 조용히 틀린다. 공급자가 알려 주는 값을 그대로 받는 것이 맞다.
+     *
+     * **금액을 싣지 않는다.** 요금적용전력 × 단가는 커널이 계산한다. 곱을 받으면 그것이 정산인 척한다.
+     */
+    tariffBasis: 'energy.tariff.basis',
     /**
      * **청구서가 도착했다** — 공급자가 확정한 금액.
      *

package/dist/ems-kernel.d.ts

@@ -122,6 +122,13 @@ export declare class EmsKernel extends FlowEngine {
      * 모르는 지점이면 세어 둔다 — 조용히 버리면 「값이 왜 안 보이지」로만 남는다(계량과 같은 규율).
      */
     private applyUsagePeriod;
+    /**
+     * 이 주기에 적용되는 요금 기준을 상태에 둔다.
+     *
+     * 늦게 온 지난 주기의 기준이 최신을 덮지 않게 시작 시각으로 가린다. 같은 주기의 값이 다시 오면
+     * 새것을 쓴다 — 사업자가 그 주기의 기준을 고칠 수 있다.
+     */
+    private applyTariffBasis;
     /**
      * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
      *
@@ -197,8 +204,17 @@ export declare class EmsKernel extends FlowEngine {
     private generationPeriodObs;
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     private unclosedGenerationPeriods;
-    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
     private lastBill?;
+    /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+    private tariffBasis?;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+     * 그것이 바뀌면 처음부터 다시 센다.
+     */
+    private demandHigh?;
     private applyEquipmentEnergy;
     /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
     private unknownEquipmentReports;
@@ -242,6 +258,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

@@ -277,6 +277,10 @@ export class EmsKernel extends FlowEngine {
             this.applyBill(envelope);
             return;
         }
+        if (envelope.eventType === ENERGY_EVENT.tariffBasis) {
+            this.applyTariffBasis(envelope);
+            return;
+        }
         super.apply(envelope);
     }
     /**
@@ -315,6 +319,45 @@ 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++;
+    }
+    /**
+     * 이 주기에 적용되는 요금 기준을 상태에 둔다.
+     *
+     * 늦게 온 지난 주기의 기준이 최신을 덮지 않게 시작 시각으로 가린다. 같은 주기의 값이 다시 오면
+     * 새것을 쓴다 — 사업자가 그 주기의 기준을 고칠 수 있다.
+     */
+    applyTariffBasis(envelope) {
+        const d = envelope.data;
+        if (!d?.from || !d?.to)
+            return;
+        const fromMs = Date.parse(String(d.from));
+        if (!Number.isFinite(fromMs))
+            return;
+        const priorFromMs = Date.parse(String(this.tariffBasis?.from ?? ''));
+        if (Number.isFinite(priorFromMs) && fromMs < priorFromMs)
+            return;
+        this.tariffBasis = { ...d };
         this.revision++;
     }
     /**
@@ -580,8 +623,17 @@ export class EmsKernel extends FlowEngine {
     generationPeriodObs = new Map();
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     unclosedGenerationPeriods = 0;
-    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
     lastBill;
+    /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+    tariffBasis;
+    /**
+     * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+     *
+     * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+     * 그것이 바뀌면 처음부터 다시 센다.
+     */
+    demandHigh;
     applyEquipmentEnergy(envelope) {
         const d = envelope.data;
         const id = String(d?.equipmentId ?? '').trim();
@@ -945,6 +997,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 +1043,85 @@ 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.tariffBasis?.billingDemandKW))
+                    ? 'tariff-basis'
+                    : 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 basis = Number(this.tariffBasis?.billingDemandKW);
+        if (Number.isFinite(basis) && basis > 0)
+            return basis;
+        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 +1515,11 @@ export class EmsKernel extends FlowEngine {
         /* 청구서도 이어받는다 — 재기동마다 사라지면 우리 계산과 견줄 기준이 없어진다. */
         if (e.lastBill?.from && e.lastBill?.to)
             this.lastBill = { ...e.lastBill };
+        if (e.tariffBasis?.from && e.tariffBasis?.to)
+            this.tariffBasis = { ...e.tariffBasis };
+        /* 이 주기의 최고도 이어받는다 — 재기동마다 0 으로 돌아가면 이미 넘은 것을 못 넘었다고 말한다. */
+        if (Number.isFinite(Number(e.demandHigh?.kW)) && e.demandHigh?.since)
+            this.demandHigh = { ...e.demandHigh };
     }
     getSnapshot() {
         const snap = super.getSnapshot();
@@ -1406,6 +1545,8 @@ export class EmsKernel extends FlowEngine {
                 : {}),
             ...(this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {}),
             ...(this.lastBill ? { lastBill: { ...this.lastBill } } : {}),
+            ...(this.tariffBasis ? { tariffBasis: { ...this.tariffBasis } } : {}),
+            ...(this.demandHigh ? { demandHigh: { ...this.demandHigh } } : {}),
             ...(contractKW !== undefined ? { contractKW } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
             ...(this.flowRequests.size

package/dist/energy-ingest.d.ts

@@ -115,6 +115,22 @@ export interface EnergyUsagePeriodRecord {
     basis?: string;
 }
 export declare function isEnergyUsagePeriodRecord(record: unknown): boolean;
+/** 이 주기에 적용되는 요금 기준 — 공급자가 정하고 매 주기 다시 정해진다. */
+export interface EnergyTariffBasisRecord {
+    from: string;
+    to: string;
+    billingDemandKW?: number;
+    demandChargePerKW?: number;
+    currency?: string;
+}
+export declare function isEnergyTariffBasisRecord(record: unknown): boolean;
+/**
+ * 요금 기준을 봉투로 — **사건 시각은 `from`** 이다.
+ *
+ * 「이 시각부터 이 기준이 적용된다」이므로 주기가 끝나기 전에 성립한다. `to` 로 잡으면 아직 오지 않은
+ * 시각이 저널에 적힌다(실제로 그렇게 해서 9월 1일 사건이 8월 29일에 적힌 적이 있다).
+ */
+export declare function ingestEnergyTariffBasisRecords(records: EnergyTariffBasisRecord | EnergyTariffBasisRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
 /** 청구서 — 커넥터가 커널의 요금 어휘로 옮겨 보낸다. */
 export interface EnergyBillRecord {
     from: string;

package/dist/energy-ingest.js

@@ -378,6 +378,63 @@ export function isEnergyUsagePeriodRecord(record) {
     const r = record;
     return !!r && typeof r === 'object' && r.meterId !== undefined && r.from !== undefined && r.to !== undefined && r.kWh !== undefined;
 }
+export function isEnergyTariffBasisRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.from === undefined || r.to === undefined)
+        return false;
+    return r.billingDemandKW !== undefined || r.demandChargePerKW !== undefined;
+}
+/**
+ * 요금 기준을 봉투로 — **사건 시각은 `from`** 이다.
+ *
+ * 「이 시각부터 이 기준이 적용된다」이므로 주기가 끝나기 전에 성립한다. `to` 로 잡으면 아직 오지 않은
+ * 시각이 저널에 적힌다(실제로 그렇게 해서 9월 1일 사건이 8월 29일에 적힌 적이 있다).
+ */
+export function ingestEnergyTariffBasisRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const r of list) {
+        const errors = [];
+        const span = readSpan(r, errors);
+        const billingDemandKW = readAmount(r?.billingDemandKW, 'billingDemandKW', errors);
+        const demandChargePerKW = readAmount(r?.demandChargePerKW, 'demandChargePerKW', errors);
+        if (billingDemandKW === undefined && demandChargePerKW === undefined) {
+            errors.push('요금 기준이 하나도 없다 — 적을 사실이 없는 기준은 받지 않는다');
+        }
+        /* 단가를 실었으면 통화가 있어야 한다 — 단위 없는 금액은 다른 금액과 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (demandChargePerKW !== undefined && !currency)
+            errors.push('demandChargePerKW 를 실었는데 currency 가 없다');
+        /* 금액은 받지 않는다 — 두 값의 곱은 커널이 한다. 곱을 받으면 그것이 정산인 척한다. */
+        if (r?.demandCharge !== undefined || r?.total !== undefined) {
+            errors.push('금액(demandCharge·total)은 이 문이 받지 않는다 — 정산 금액은 청구서 문으로 보낸다');
+        }
+        if (errors.length || !span) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            from: span.from,
+            to: span.to,
+            ...(billingDemandKW !== undefined ? { billingDemandKW } : {}),
+            ...(demandChargePerKW !== undefined ? { demandChargePerKW } : {}),
+            ...(currency ? { currency } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-tariff-basis-${++seq}`,
+            eventType: ENERGY_EVENT.tariffBasis,
+            /* **시작 시각**이다 — 그때부터 유효하다(§ 위 주석). */
+            eventTime: span.from,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
 export function isEnergyBillRecord(record) {
     const r = record;
     if (!r || typeof r !== 'object')

package/dist/index.d.ts

@@ -30,10 +30,10 @@ export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
-export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord } from './energy-ingest.ts';
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord } from './energy-ingest.ts';
 export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from './operational-ingest.ts';
 export type { OperationalKind, OperationalRecord, OperationalIngestOptions } from './operational-ingest.ts';
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from './energy-attribution.ts';
 export type { AttributionBasis, AttributionResult, ElectricityCost, EnergyConsumer, EnergyPool, EnergyShare, IntensityInput, IntensityResult, IntensityDenominator, TariffDeclaration, WeightKind, WindowedEnergy } from './energy-attribution.ts';
-export type { EnergyRecord, EnergyEquipmentRecord, EnergyGenerationRecord, EnergyUsagePeriodRecord, EnergyBillRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
+export type { EnergyRecord, EnergyEquipmentRecord, EnergyGenerationRecord, EnergyUsagePeriodRecord, EnergyBillRecord, EnergyTariffBasisRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
 export * from './vocabulary.ts';

package/dist/index.js

@@ -30,7 +30,7 @@ export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
-export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord } from "./energy-ingest.js";
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord } from "./energy-ingest.js";
 /* 운영 사실의 문 — 리듀서가 다루는 여섯이 들어오는 자리(미러가 시뮬보다 가난하지 않게). */
 export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from "./operational-ingest.js";
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from "./energy-attribution.js";

package/dist-cjs/index.cjs

@@ -129,6 +129,7 @@ __export(index_exports, {
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords: () => ingestEnergyGenerationRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  ingestEnergyTariffBasisRecords: () => ingestEnergyTariffBasisRecords,
   ingestEnergyUsagePeriodRecords: () => ingestEnergyUsagePeriodRecords,
   ingestMasterData: () => ingestMasterData,
   ingestOperationalRecords: () => ingestOperationalRecords,
@@ -138,6 +139,7 @@ __export(index_exports, {
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyGenerationRecord: () => isEnergyGenerationRecord,
   isEnergyRecord: () => isEnergyRecord,
+  isEnergyTariffBasisRecord: () => isEnergyTariffBasisRecord,
   isEnergyUsagePeriodRecord: () => isEnergyUsagePeriodRecord,
   isEpcisEventType: () => isEpcisEventType,
   isEquipmentLevel: () => isEquipmentLevel,
@@ -709,6 +711,18 @@ var ENERGY_EVENT = {
    * 쪽인지 말한다.
    */
   usagePeriod: "energy.usage.period",
+  /**
+   * **이 주기에 적용되는 요금 기준이 정해졌다** — 요금적용전력과 기본요금 단가.
+   *
+   * 청구서와 다른 사건이다. 청구서는 끝난 기간의 정산이고 이것은 **지금 적용되는 기준**이다.
+   * 그래서 사건 시각도 다르다 — 청구서는 기간의 끝, 이것은 기간의 시작이다(그때부터 유효하다).
+   *
+   * 이 값은 매 주기 다시 정해진다. 모델의 선언에 적어 두면 사람이 매달 갱신해야 하고, 안 하면 낡은
+   * 값으로 기본요금이 조용히 틀린다. 공급자가 알려 주는 값을 그대로 받는 것이 맞다.
+   *
+   * **금액을 싣지 않는다.** 요금적용전력 × 단가는 커널이 계산한다. 곱을 받으면 그것이 정산인 척한다.
+   */
+  tariffBasis: "energy.tariff.basis",
   /**
    * **청구서가 도착했다** — 공급자가 확정한 금액.
    *
@@ -7950,6 +7964,10 @@ var EmsKernel = class extends FlowEngine {
       this.applyBill(envelope);
       return;
     }
+    if (envelope.eventType === ENERGY_EVENT.tariffBasis) {
+      this.applyTariffBasis(envelope);
+      return;
+    }
     super.apply(envelope);
   }
   /**
@@ -7980,6 +7998,30 @@ 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++;
+  }
+  /**
+   * 이 주기에 적용되는 요금 기준을 상태에 둔다.
+   *
+   * 늦게 온 지난 주기의 기준이 최신을 덮지 않게 시작 시각으로 가린다. 같은 주기의 값이 다시 오면
+   * 새것을 쓴다 — 사업자가 그 주기의 기준을 고칠 수 있다.
+   */
+  applyTariffBasis(envelope) {
+    const d = envelope.data;
+    if (!d?.from || !d?.to) return;
+    const fromMs = Date.parse(String(d.from));
+    if (!Number.isFinite(fromMs)) return;
+    const priorFromMs = Date.parse(String(this.tariffBasis?.from ?? ""));
+    if (Number.isFinite(priorFromMs) && fromMs < priorFromMs) return;
+    this.tariffBasis = { ...d };
     this.revision++;
   }
   /**
@@ -8156,8 +8198,17 @@ var EmsKernel = class extends FlowEngine {
   generationPeriodObs = /* @__PURE__ */ new Map();
   /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
   unclosedGenerationPeriods = 0;
-  /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+  /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
   lastBill;
+  /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+  tariffBasis;
+  /**
+   * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
+   *
+   * `since` 는 이 주기에서 처음 잰 구간의 끝이다. `periodStart` 는 마지막 청구서의 끝이고,
+   * 그것이 바뀌면 처음부터 다시 센다.
+   */
+  demandHigh;
   applyEquipmentEnergy(envelope) {
     const d = envelope.data;
     const id = String(d?.equipmentId ?? "").trim();
@@ -8397,6 +8448,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 +8488,74 @@ 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.tariffBasis?.billingDemandKW)) ? "tariff-basis" : 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 basis = Number(this.tariffBasis?.billingDemandKW);
+    if (Number.isFinite(basis) && basis > 0) return basis;
+    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 +8836,8 @@ 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 (e.tariffBasis?.from && e.tariffBasis?.to) this.tariffBasis = { ...e.tariffBasis };
+    if (Number.isFinite(Number(e.demandHigh?.kW)) && e.demandHigh?.since) this.demandHigh = { ...e.demandHigh };
   }
   getSnapshot() {
     const snap = super.getSnapshot();
@@ -8736,6 +8859,8 @@ var EmsKernel = class extends FlowEngine {
       } : {},
       ...this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {},
       ...this.lastBill ? { lastBill: { ...this.lastBill } } : {},
+      ...this.tariffBasis ? { tariffBasis: { ...this.tariffBasis } } : {},
+      ...this.demandHigh ? { demandHigh: { ...this.demandHigh } } : {},
       ...contractKW !== void 0 ? { contractKW } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
       ...this.flowRequests.size ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) } : {}
@@ -9781,6 +9906,52 @@ function isEnergyUsagePeriodRecord(record) {
   const r = record;
   return !!r && typeof r === "object" && r.meterId !== void 0 && r.from !== void 0 && r.to !== void 0 && r.kWh !== void 0;
 }
+function isEnergyTariffBasisRecord(record) {
+  const r = record;
+  if (!r || typeof r !== "object") return false;
+  if (r.from === void 0 || r.to === void 0) return false;
+  return r.billingDemandKW !== void 0 || r.demandChargePerKW !== void 0;
+}
+function ingestEnergyTariffBasisRecords(records, opts) {
+  const list = records === void 0 || records === null ? [] : Array.isArray(records) ? records : [records];
+  const accepted = [];
+  const rejected = [];
+  let seq = 0;
+  for (const r of list) {
+    const errors = [];
+    const span = readSpan(r, errors);
+    const billingDemandKW = readAmount(r?.billingDemandKW, "billingDemandKW", errors);
+    const demandChargePerKW = readAmount(r?.demandChargePerKW, "demandChargePerKW", errors);
+    if (billingDemandKW === void 0 && demandChargePerKW === void 0) {
+      errors.push("\uC694\uAE08 \uAE30\uC900\uC774 \uD558\uB098\uB3C4 \uC5C6\uB2E4 \u2014 \uC801\uC744 \uC0AC\uC2E4\uC774 \uC5C6\uB294 \uAE30\uC900\uC740 \uBC1B\uC9C0 \uC54A\uB294\uB2E4");
+    }
+    const currency = String(r?.currency ?? "").trim() || void 0;
+    if (demandChargePerKW !== void 0 && !currency) errors.push("demandChargePerKW \uB97C \uC2E4\uC5C8\uB294\uB370 currency \uAC00 \uC5C6\uB2E4");
+    if (r?.demandCharge !== void 0 || r?.total !== void 0) {
+      errors.push("\uAE08\uC561(demandCharge\xB7total)\uC740 \uC774 \uBB38\uC774 \uBC1B\uC9C0 \uC54A\uB294\uB2E4 \u2014 \uC815\uC0B0 \uAE08\uC561\uC740 \uCCAD\uAD6C\uC11C \uBB38\uC73C\uB85C \uBCF4\uB0B8\uB2E4");
+    }
+    if (errors.length || !span) {
+      rejected.push({ record: r, errors });
+      continue;
+    }
+    const data = {
+      from: span.from,
+      to: span.to,
+      ...billingDemandKW !== void 0 ? { billingDemandKW } : {},
+      ...demandChargePerKW !== void 0 ? { demandChargePerKW } : {},
+      ...currency ? { currency } : {}
+    };
+    accepted.push({
+      eventId: `${opts.tenantId}-tariff-basis-${++seq}`,
+      eventType: ENERGY_EVENT.tariffBasis,
+      /* **시작 시각**이다 — 그때부터 유효하다(§ 위 주석). */
+      eventTime: span.from,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
 function isEnergyBillRecord(record) {
   const r = record;
   if (!r || typeof r !== "object") return false;
@@ -10598,6 +10769,7 @@ function retiredVocabularyIn(line) {
   ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords,
   ingestEnergyRecords,
+  ingestEnergyTariffBasisRecords,
   ingestEnergyUsagePeriodRecords,
   ingestMasterData,
   ingestOperationalRecords,
@@ -10607,6 +10779,7 @@ function retiredVocabularyIn(line) {
   isEnergyEquipmentRecord,
   isEnergyGenerationRecord,
   isEnergyRecord,
+  isEnergyTariffBasisRecord,
   isEnergyUsagePeriodRecord,
   isEpcisEventType,
   isEquipmentLevel,

package/package.json

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