@operato/twin-kernel 0.7.75 → 0.7.77

package/dist/contract.d.ts

@@ -2035,6 +2035,12 @@ export interface EnergyState {
      * 틀렸다는 뜻이고, 사람이 찾아내지 않아도 드러나야 한다.
      */
     lastBill?: EnergyBillData;
+    /**
+     * 마지막으로 받은 **요금 기준** — 이 주기에 적용되는 요금적용전력과 단가.
+     *
+     * 청구서보다 이쪽이 먼저다: 청구서는 끝난 기간의 정산이고 이것은 지금 적용되는 값이다.
+     */
+    tariffBasis?: EnergyTariffBasisData;
     /**
      * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
      *
@@ -2474,6 +2480,18 @@ export declare const ENERGY_EVENT: {
      * 쪽인지 말한다.
      */
     readonly usagePeriod: "energy.usage.period";
+    /**
+     * **이 주기에 적용되는 요금 기준이 정해졌다** — 요금적용전력과 기본요금 단가.
+     *
+     * 청구서와 다른 사건이다. 청구서는 끝난 기간의 정산이고 이것은 **지금 적용되는 기준**이다.
+     * 그래서 사건 시각도 다르다 — 청구서는 기간의 끝, 이것은 기간의 시작이다(그때부터 유효하다).
+     *
+     * 이 값은 매 주기 다시 정해진다. 모델의 선언에 적어 두면 사람이 매달 갱신해야 하고, 안 하면 낡은
+     * 값으로 기본요금이 조용히 틀린다. 공급자가 알려 주는 값을 그대로 받는 것이 맞다.
+     *
+     * **금액을 싣지 않는다.** 요금적용전력 × 단가는 커널이 계산한다. 곱을 받으면 그것이 정산인 척한다.
+     */
+    readonly tariffBasis: "energy.tariff.basis";
     /**
      * **청구서가 도착했다** — 공급자가 확정한 금액.
      *
@@ -2729,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,10 @@ export declare class EmsKernel extends FlowEngine {
     private generationPeriodObs;
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     private unclosedGenerationPeriods;
-    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
     private lastBill?;
+    /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+    private tariffBasis?;
     /**
      * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
      *
@@ -328,6 +337,25 @@ export declare class EmsKernel extends FlowEngine {
      * 계기가 잰 방전으로 읽는다(수요 구간의 `derived` 와 같은 규율).
      */
     private emitEnergyEquipment;
+    /**
+     * 이 트윈의 **발전 정격** — 이용률의 분모가 될 값과 그 근거.
+     *
+     * ── 어느 정격으로 나누나 ───────────────────────────────────────────────────
+     * 교류가 먼저다. 계통으로 나가는 양은 교류 정격을 넘을 수 없으므로 그 비가 1 을 넘지 않는다.
+     * 직류로 나누면 잘 만든 발전소도 100% 에 닿지 않아 늘 낮게 보인다.
+     *
+     * **다만 시스템마다 관행이 다르다.** 직류로 나눠 보여 주는 화면이 실제로 있다. 그래서 커널은
+     * 어느 쪽으로 나눴는지를 값과 함께 낸다 — 두 화면의 수가 다를 때 사람이 맞춰 볼 수 있어야 한다.
+     *
+     * ── 어디서 읽나 ────────────────────────────────────────────────────────────
+     * 설비마다 선언돼 있으면 그 합이다. 없으면 자리(수전)에 선언된 합계를 쓴다. 둘 다 없으면
+     * 계산하지 않는다 — 0 이나 짐작을 내지 않는다.
+     */
+    generationRated(): {
+        kW: number;
+        basis: 'ac' | 'dc';
+        from: 'equipment' | 'location';
+    } | undefined;
     /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
     private numberProperty;
     /** 글자로 선언된 값(발전 형상·통화 같은 것) — 비어 있으면 없는 것으로 본다. */

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);
     }
     /**
@@ -337,6 +341,25 @@ export class EmsKernel extends FlowEngine {
         }
         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++;
+    }
     /**
      * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
      *
@@ -600,8 +623,10 @@ export class EmsKernel extends FlowEngine {
     generationPeriodObs = new Map();
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     unclosedGenerationPeriods = 0;
-    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
     lastBill;
+    /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+    tariffBasis;
     /**
      * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
      *
@@ -1051,7 +1076,11 @@ export class EmsKernel extends FlowEngine {
                 billingDemandKW: Math.round(basis),
                 overKW: Math.round(over),
                 /* 값의 출처 — 청구서가 말한 기준인지 현장의 선언인지. 선언은 곧 낡는다. */
-                basisFrom: Number.isFinite(Number(this.lastBill?.billingDemandKW)) ? 'bill' : 'declaration',
+                basisFrom: Number.isFinite(Number(this.tariffBasis?.billingDemandKW))
+                    ? 'tariff-basis'
+                    : Number.isFinite(Number(this.lastBill?.billingDemandKW))
+                        ? 'bill'
+                        : 'declaration',
                 observedTo: high.atTo,
                 periodSince: high.since
             },
@@ -1084,6 +1113,10 @@ export class EmsKernel extends FlowEngine {
     }
     /** 지금 쓰는 요금적용전력 — **청구서가 먼저다.** 매달 바뀌는 값이라 선언은 곧 낡는다. */
     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;
@@ -1377,6 +1410,49 @@ export class EmsKernel extends FlowEngine {
     emitEnergyEquipment(equipmentId, atMs, fields) {
         this.emitOp(ENERGY_EVENT.equipment, { equipmentId, at: new Date(atMs).toISOString(), derived: true, ...fields });
     }
+    /**
+     * 이 트윈의 **발전 정격** — 이용률의 분모가 될 값과 그 근거.
+     *
+     * ── 어느 정격으로 나누나 ───────────────────────────────────────────────────
+     * 교류가 먼저다. 계통으로 나가는 양은 교류 정격을 넘을 수 없으므로 그 비가 1 을 넘지 않는다.
+     * 직류로 나누면 잘 만든 발전소도 100% 에 닿지 않아 늘 낮게 보인다.
+     *
+     * **다만 시스템마다 관행이 다르다.** 직류로 나눠 보여 주는 화면이 실제로 있다. 그래서 커널은
+     * 어느 쪽으로 나눴는지를 값과 함께 낸다 — 두 화면의 수가 다를 때 사람이 맞춰 볼 수 있어야 한다.
+     *
+     * ── 어디서 읽나 ────────────────────────────────────────────────────────────
+     * 설비마다 선언돼 있으면 그 합이다. 없으면 자리(수전)에 선언된 합계를 쓴다. 둘 다 없으면
+     * 계산하지 않는다 — 0 이나 짐작을 내지 않는다.
+     */
+    generationRated() {
+        for (const [prop, basis] of [
+            [EMS_PROPERTY.genRatedKW, 'ac'],
+            [EMS_PROPERTY.genRatedKWdc, 'dc']
+        ]) {
+            let sum = 0;
+            for (const e of this.boardDef?.equipment ?? []) {
+                const v = this.numberProperty(e, prop);
+                if (v !== undefined && v > 0)
+                    sum += v;
+            }
+            if (sum > 0)
+                return { kW: sum, basis, from: 'equipment' };
+        }
+        for (const [prop, basis] of [
+            [EMS_PROPERTY.genRatedKW, 'ac'],
+            [EMS_PROPERTY.genRatedKWdc, 'dc']
+        ]) {
+            let sum = 0;
+            for (const loc of this.boardDef?.locations ?? []) {
+                const v = this.numberProperty(loc, prop);
+                if (v !== undefined && v > 0)
+                    sum += v;
+            }
+            if (sum > 0)
+                return { kW: sum, basis, from: 'location' };
+        }
+        return undefined;
+    }
     /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
     numberProperty(resource, id) {
         for (const p of resource?.properties ?? []) {
@@ -1482,6 +1558,8 @@ 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 };
@@ -1510,6 +1588,7 @@ 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 } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */

package/dist/ems-profile.d.ts

@@ -70,8 +70,22 @@ export declare const EMS_PROPERTY: {
      * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
      */
     readonly initialSoc: "storage.initialSoc";
-    /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+    /**
+     * 발전 정격(kW) — **교류 쪽 최대 출력**. 계통으로 나가는 값이다.
+     *
+     * 이용률의 분모가 이 값이다(만든 양 ÷ 정격 × 시간). **직류 쪽 정격(§`genRatedKWdc`)과 다르고 더 작다** —
+     * 두 값을 한 이름에 담으면 이용률이 그 차이만큼 틀리고, 틀린 이유가 아무 데도 표시되지 않는다.
+     *
+     * 설비마다 선언하거나, 설비별 값을 모르는 현장은 **자리(수전)에 합계로** 선언한다.
+     */
     readonly genRatedKW: "generation.ratedKW";
+    /**
+     * 발전 정격(kW) — **직류 쪽**. 변환기(인버터)의 입력 쪽 정격이고, 태양광이면 패널 정격의 합이다.
+     *
+     * 이용률의 분모로 쓰지 않는다. 이 값이 교류 정격보다 큰 것은 설계이고(변환기를 그렇게 고른다),
+     * 그 차이가 「맑은 정오에도 교류 출력이 더 오르지 않는 이유」를 설명한다.
+     */
+    readonly genRatedKWdc: "generation.ratedKWdc";
     /**
      * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
      *

package/dist/ems-profile.js

@@ -131,8 +131,22 @@ export const EMS_PROPERTY = {
      *
      * 정격만 있고 형상이 없으면 발전하지 않는다 — 하루 종일 정격으로 발전하는 태양광은 없다.
      */
-    /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+    /**
+     * 발전 정격(kW) — **교류 쪽 최대 출력**. 계통으로 나가는 값이다.
+     *
+     * 이용률의 분모가 이 값이다(만든 양 ÷ 정격 × 시간). **직류 쪽 정격(§`genRatedKWdc`)과 다르고 더 작다** —
+     * 두 값을 한 이름에 담으면 이용률이 그 차이만큼 틀리고, 틀린 이유가 아무 데도 표시되지 않는다.
+     *
+     * 설비마다 선언하거나, 설비별 값을 모르는 현장은 **자리(수전)에 합계로** 선언한다.
+     */
     genRatedKW: 'generation.ratedKW',
+    /**
+     * 발전 정격(kW) — **직류 쪽**. 변환기(인버터)의 입력 쪽 정격이고, 태양광이면 패널 정격의 합이다.
+     *
+     * 이용률의 분모로 쓰지 않는다. 이 값이 교류 정격보다 큰 것은 설계이고(변환기를 그렇게 고른다),
+     * 그 차이가 「맑은 정오에도 교류 출력이 더 오르지 않는 이유」를 설명한다.
+     */
+    genRatedKWdc: 'generation.ratedKWdc',
     /**
      * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
      *
@@ -165,7 +179,16 @@ export const EMS_PROPERTY_SPEC = {
     /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
     [EMS_PROPERTY.reserveSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below.' },
     [EMS_PROPERTY.initialSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'starting state of charge as a percentage 0-100 (80 means 80%, not 0.8).' },
-    [EMS_PROPERTY.genRatedKW]: { uom: 'kW', dataType: 'xs:double', note: 'rated generation output at clear-sky noon, in kW.' },
+    [EMS_PROPERTY.genRatedKW]: {
+        uom: 'kW',
+        dataType: 'xs:double',
+        note: 'rated AC generation output, in kW — the denominator of capacity factor. Declare per equipment, or on the incoming location as a site total.'
+    },
+    [EMS_PROPERTY.genRatedKWdc]: {
+        uom: 'kW',
+        dataType: 'xs:double',
+        note: 'rated DC generation capacity, in kW (panel rating for PV). Larger than the AC rating by design; not the capacity-factor denominator.'
+    },
     [EMS_PROPERTY.genDailyProfile]: {
         dataType: 'xs:string',
         note: 'daily shape as 24 comma-separated fractions of rated output (0-1), one per hour of local time — the site declares its own curve; we do not invent one.'

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,73 @@ 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;
+    /*
+     * ── 청구서와 배타로 (2026-08-29) ───────────────────────────────────────────
+     *
+     * 청구서가 요금적용전력을 함께 실으면 이 판별도 참이 됐다. 그때 이 문으로 가면 「금액은 받지
+     * 않는다」로 거부되어 **정산이 통째로 사라진다** — 거부는 되지만 그 사실을 잃는 것은 같다.
+     *
+     * 금액이 하나라도 있으면 그것은 정산이다. 기준은 금액을 싣지 않는다.
+     */
+    if (r.energyCharge !== undefined || r.demandCharge !== undefined || r.total !== 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",
   /**
    * **청구서가 도착했다** — 공급자가 확정한 금액.
    *
@@ -7553,8 +7567,22 @@ var EMS_PROPERTY = {
    *
    * 정격만 있고 형상이 없으면 발전하지 않는다 — 하루 종일 정격으로 발전하는 태양광은 없다.
    */
-  /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+  /**
+   * 발전 정격(kW) — **교류 쪽 최대 출력**. 계통으로 나가는 값이다.
+   *
+   * 이용률의 분모가 이 값이다(만든 양 ÷ 정격 × 시간). **직류 쪽 정격(§`genRatedKWdc`)과 다르고 더 작다** —
+   * 두 값을 한 이름에 담으면 이용률이 그 차이만큼 틀리고, 틀린 이유가 아무 데도 표시되지 않는다.
+   *
+   * 설비마다 선언하거나, 설비별 값을 모르는 현장은 **자리(수전)에 합계로** 선언한다.
+   */
   genRatedKW: "generation.ratedKW",
+  /**
+   * 발전 정격(kW) — **직류 쪽**. 변환기(인버터)의 입력 쪽 정격이고, 태양광이면 패널 정격의 합이다.
+   *
+   * 이용률의 분모로 쓰지 않는다. 이 값이 교류 정격보다 큰 것은 설계이고(변환기를 그렇게 고른다),
+   * 그 차이가 「맑은 정오에도 교류 출력이 더 오르지 않는 이유」를 설명한다.
+   */
+  genRatedKWdc: "generation.ratedKWdc",
   /**
    * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
    *
@@ -7585,7 +7613,16 @@ var EMS_PROPERTY_SPEC = {
   /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
   [EMS_PROPERTY.reserveSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below." },
   [EMS_PROPERTY.initialSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "starting state of charge as a percentage 0-100 (80 means 80%, not 0.8)." },
-  [EMS_PROPERTY.genRatedKW]: { uom: "kW", dataType: "xs:double", note: "rated generation output at clear-sky noon, in kW." },
+  [EMS_PROPERTY.genRatedKW]: {
+    uom: "kW",
+    dataType: "xs:double",
+    note: "rated AC generation output, in kW \u2014 the denominator of capacity factor. Declare per equipment, or on the incoming location as a site total."
+  },
+  [EMS_PROPERTY.genRatedKWdc]: {
+    uom: "kW",
+    dataType: "xs:double",
+    note: "rated DC generation capacity, in kW (panel rating for PV). Larger than the AC rating by design; not the capacity-factor denominator."
+  },
   [EMS_PROPERTY.genDailyProfile]: {
     dataType: "xs:string",
     note: "daily shape as 24 comma-separated fractions of rated output (0-1), one per hour of local time \u2014 the site declares its own curve; we do not invent one."
@@ -7950,6 +7987,10 @@ var EmsKernel = class extends FlowEngine {
       this.applyBill(envelope);
       return;
     }
+    if (envelope.eventType === ENERGY_EVENT.tariffBasis) {
+      this.applyTariffBasis(envelope);
+      return;
+    }
     super.apply(envelope);
   }
   /**
@@ -7990,6 +8031,22 @@ var EmsKernel = class extends FlowEngine {
     }
     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++;
+  }
   /**
    * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
    *
@@ -8164,8 +8221,10 @@ var EmsKernel = class extends FlowEngine {
   generationPeriodObs = /* @__PURE__ */ new Map();
   /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
   unclosedGenerationPeriods = 0;
-  /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+  /** 마지막으로 받은 청구서 — 공급자가 **정산한** 금액. 지금 이 문으로 오는 것은 없다. */
   lastBill;
+  /** 마지막으로 받은 요금 기준 — 이 주기에 적용되는 요금적용전력과 단가. */
+  tariffBasis;
   /**
    * 이 청구 주기의 **최고 수요** — 기본요금이 이 값으로 다시 정해진다.
    *
@@ -8484,7 +8543,7 @@ var EmsKernel = class extends FlowEngine {
         billingDemandKW: Math.round(basis),
         overKW: Math.round(over),
         /* 값의 출처 — 청구서가 말한 기준인지 현장의 선언인지. 선언은 곧 낡는다. */
-        basisFrom: Number.isFinite(Number(this.lastBill?.billingDemandKW)) ? "bill" : "declaration",
+        basisFrom: Number.isFinite(Number(this.tariffBasis?.billingDemandKW)) ? "tariff-basis" : Number.isFinite(Number(this.lastBill?.billingDemandKW)) ? "bill" : "declaration",
         observedTo: high.atTo,
         periodSince: high.since
       },
@@ -8514,6 +8573,8 @@ var EmsKernel = class extends FlowEngine {
   }
   /** 지금 쓰는 요금적용전력 — **청구서가 먼저다.** 매달 바뀌는 값이라 선언은 곧 낡는다. */
   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();
@@ -8722,6 +8783,45 @@ var EmsKernel = class extends FlowEngine {
   emitEnergyEquipment(equipmentId, atMs, fields) {
     this.emitOp(ENERGY_EVENT.equipment, { equipmentId, at: new Date(atMs).toISOString(), derived: true, ...fields });
   }
+  /**
+   * 이 트윈의 **발전 정격** — 이용률의 분모가 될 값과 그 근거.
+   *
+   * ── 어느 정격으로 나누나 ───────────────────────────────────────────────────
+   * 교류가 먼저다. 계통으로 나가는 양은 교류 정격을 넘을 수 없으므로 그 비가 1 을 넘지 않는다.
+   * 직류로 나누면 잘 만든 발전소도 100% 에 닿지 않아 늘 낮게 보인다.
+   *
+   * **다만 시스템마다 관행이 다르다.** 직류로 나눠 보여 주는 화면이 실제로 있다. 그래서 커널은
+   * 어느 쪽으로 나눴는지를 값과 함께 낸다 — 두 화면의 수가 다를 때 사람이 맞춰 볼 수 있어야 한다.
+   *
+   * ── 어디서 읽나 ────────────────────────────────────────────────────────────
+   * 설비마다 선언돼 있으면 그 합이다. 없으면 자리(수전)에 선언된 합계를 쓴다. 둘 다 없으면
+   * 계산하지 않는다 — 0 이나 짐작을 내지 않는다.
+   */
+  generationRated() {
+    for (const [prop, basis] of [
+      [EMS_PROPERTY.genRatedKW, "ac"],
+      [EMS_PROPERTY.genRatedKWdc, "dc"]
+    ]) {
+      let sum = 0;
+      for (const e of this.boardDef?.equipment ?? []) {
+        const v = this.numberProperty(e, prop);
+        if (v !== void 0 && v > 0) sum += v;
+      }
+      if (sum > 0) return { kW: sum, basis, from: "equipment" };
+    }
+    for (const [prop, basis] of [
+      [EMS_PROPERTY.genRatedKW, "ac"],
+      [EMS_PROPERTY.genRatedKWdc, "dc"]
+    ]) {
+      let sum = 0;
+      for (const loc of this.boardDef?.locations ?? []) {
+        const v = this.numberProperty(loc, prop);
+        if (v !== void 0 && v > 0) sum += v;
+      }
+      if (sum > 0) return { kW: sum, basis, from: "location" };
+    }
+    return void 0;
+  }
   /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
   numberProperty(resource, id) {
     for (const p of resource?.properties ?? []) {
@@ -8798,6 +8898,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 (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() {
@@ -8820,6 +8921,7 @@ 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 } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
@@ -9866,6 +9968,53 @@ 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;
+  if (r.energyCharge !== void 0 || r.demandCharge !== void 0 || r.total !== 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;
@@ -10683,6 +10832,7 @@ function retiredVocabularyIn(line) {
   ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords,
   ingestEnergyRecords,
+  ingestEnergyTariffBasisRecords,
   ingestEnergyUsagePeriodRecords,
   ingestMasterData,
   ingestOperationalRecords,
@@ -10692,6 +10842,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.75",
+  "version": "0.7.77",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {