@operato/twin-kernel 0.7.71 → 0.7.73

package/dist/contract.d.ts

@@ -1885,6 +1885,17 @@ export interface MeterPointState {
      * 다르며, 다를 때 맞는 쪽은 계량기다).
      */
     kWhAtWindowStart?: number;
+    /**
+     * 밖에서 마감되어 온 **마지막 사용 구간** — 계량 표본이 없는 현장의 화면이 「지난 구간에 얼마 썼나」를
+     * 말할 수 있게(§`ENERGY_EVENT.usagePeriod`).
+     *
+     * 우리가 마감한 구간(`kWhAtWindowStart` 로 뺀 값)과 **다른 값이다.** 더하지 않는다.
+     */
+    lastPeriodKWh?: number;
+    lastPeriodFrom?: ISOTime;
+    lastPeriodTo?: ISOTime;
+    /** 그 값의 근거 — 계량인지, 공급자가 준 것인지, 청구서인지. */
+    lastPeriodBasis?: ObservationBasis;
 }
 export interface DemandWindowState {
     startMs: number;
@@ -2009,6 +2020,13 @@ export interface EnergyState {
         hook: string;
         count: number;
     }[];
+    /**
+     * 마지막으로 받은 **청구서** — 공급자가 확정한 금액(§`ENERGY_EVENT.bill`).
+     *
+     * 우리가 계산한 금액을 덮지 않는다. 읽는 쪽이 둘을 견주어 어긋나면 그 사실을 낸다 — 우리 계산이
+     * 틀렸다는 뜻이고, 사람이 찾아내지 않아도 드러나야 한다.
+     */
+    lastBill?: EnergyBillData;
     /**
      * 설비마다 **지금 기간의 발전 관측** — 기간 발전량을 확정할 때 쓰는 기준점.
      *
@@ -2424,6 +2442,29 @@ export declare const ENERGY_EVENT: {
     readonly equipment: "energy.equipment";
     /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
     readonly demandWindow: "energy.demand.window";
+    /**
+     * **마감된 사용 구간이 도착했다** — 우리가 마감한 것이 아니라 밖에서 확정되어 온 것이다.
+     *
+     * 계량 표본이 오지 않는 현장이 있다. 공급자의 조회나 계량 데이터 시스템이 「이 구간에 X 썼다」를
+     * 이미 마감해 준다. 그 값을 적산(`energy.measured` 의 `kWh`)으로 보내면 커널이 그것을 누적으로
+     * 읽고 차분을 또 구한다 — 차분의 차분이 되어 틀린다. 그래서 다른 사건이다.
+     *
+     * `demandWindow` 와 **합치지 않는다.** 하나는 우리가 표본에서 마감한 것이고 이것은 밖에서 온
+     * 것이다. 두 회계를 더하면 같은 전기를 두 번 센다. 둘 다 있으면 읽는 쪽이 하나를 고르고 어느
+     * 쪽인지 말한다.
+     */
+    readonly usagePeriod: "energy.usage.period";
+    /**
+     * **청구서가 도착했다** — 공급자가 확정한 금액.
+     *
+     * 우리가 계산한 금액(§`electricityCost`)을 덮지 않는다. 두 값은 다른 것이다: 청구는 사실이고 우리
+     * 계산은 파생이다(구간 요금·예측·가정 비교에 쓴다). 계기 적산과 같은 규율이다 — 다를 때 맞는 쪽은
+     * 그 회계를 가진 쪽이다.
+     *
+     * 어긋나면 **그 사실을 낸다.** 우리 계산이 틀렸다는 뜻이고, 그것을 사람이 찾아내지 않아도 드러나야
+     * 한다(실제로 사람이 찾아낸 적이 있다 — 기본요금을 이 주기의 최대로 매기고 있었다).
+     */
+    readonly bill: "energy.bill";
     /**
      * 피크 경신 — 월 최대 수요가 갱신됐다.
      *
@@ -2608,6 +2649,53 @@ export interface EnergyGenerationPeriodData {
     /** 기간의 경계가 어디서 왔나 — 원본의 기준점(`declared`)이거나 현장의 시각 기준(`offset`). */
     boundary: 'declared' | 'offset';
 }
+/**
+ * 값이 어디서 왔나 — **관측의 근거**.
+ *
+ * 같은 kWh 라도 계량기가 잰 것과 공급자 화면에서 긁어온 것은 무게가 다르다. 실제로 긁어온 값이
+ * 망가져 있는 것을 본 적이 있다(다른 현장의 값이 섞이고, 세 자리 수가 한 자리로 왔다). 근거를 값과
+ * 함께 두면 화면이 「이 수는 계량이 아니다」를 말할 수 있다.
+ *
+ * 커널은 이 값으로 판정하지 않는다 — 무엇을 믿을지는 현장이 정한다.
+ */
+export declare const OBSERVATION_BASIS: readonly ["metered", "provider", "billed", "estimated"];
+export type ObservationBasis = (typeof OBSERVATION_BASIS)[number];
+/**
+ * 마감된 사용 구간 — `ENERGY_EVENT.usagePeriod` 의 데이터.
+ *
+ * 적산이 아니라 **그 구간에 쓴 양**이다. 구간의 단가를 함께 실을 수 있다: 시간대·계절마다 단가가
+ * 다른 현장에서 하나로 접으면 「피크를 깎아 얼마를 아끼나」가 사라진다.
+ */
+export interface EnergyUsagePeriodData {
+    meterId: string;
+    from: ISOTime;
+    to: ISOTime;
+    /** 이 구간에 쓴 양(kWh). */
+    kWh: number;
+    /** 이 구간의 최대 수요(kW) — 원본이 함께 줄 때만. */
+    maxKW?: number;
+    /** 이 구간에 적용된 단가(1kWh 당). 통화는 `currency`. */
+    unitPrice?: number;
+    currency?: string;
+    basis?: ObservationBasis;
+}
+/**
+ * 청구서 — `ENERGY_EVENT.bill` 의 데이터.
+ *
+ * **커널의 요금 어휘로 받는다**(사용량 요금·기본요금·합계). 공급자마다 청구서의 칸 이름이 다르므로
+ * 그 이름을 그대로 들이면 커널이 한 공급자의 모양에 묶인다. 옮기는 것은 커넥터의 일이다.
+ */
+export interface EnergyBillData {
+    from: ISOTime;
+    to: ISOTime;
+    /** 사용량 요금 · 기본요금 · 합계 — 청구서가 말한 값. 없는 것은 비운다(0 으로 채우지 않는다). */
+    energyCharge?: number;
+    demandCharge?: number;
+    total?: number;
+    currency?: string;
+    /** 그 청구가 기본요금을 매긴 기준(kW) — 우리 선언과 다르면 선언이 낡은 것이다. */
+    billingDemandKW?: number;
+}
 export interface EnergyDemandWindowData {
     /** 배전 구간(로케이션 id) 또는 현장 전체. */
     feederId?: string;

package/dist/contract.js

@@ -1034,6 +1034,29 @@ export const ENERGY_EVENT = {
     equipment: 'energy.equipment',
     /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
     demandWindow: 'energy.demand.window',
+    /**
+     * **마감된 사용 구간이 도착했다** — 우리가 마감한 것이 아니라 밖에서 확정되어 온 것이다.
+     *
+     * 계량 표본이 오지 않는 현장이 있다. 공급자의 조회나 계량 데이터 시스템이 「이 구간에 X 썼다」를
+     * 이미 마감해 준다. 그 값을 적산(`energy.measured` 의 `kWh`)으로 보내면 커널이 그것을 누적으로
+     * 읽고 차분을 또 구한다 — 차분의 차분이 되어 틀린다. 그래서 다른 사건이다.
+     *
+     * `demandWindow` 와 **합치지 않는다.** 하나는 우리가 표본에서 마감한 것이고 이것은 밖에서 온
+     * 것이다. 두 회계를 더하면 같은 전기를 두 번 센다. 둘 다 있으면 읽는 쪽이 하나를 고르고 어느
+     * 쪽인지 말한다.
+     */
+    usagePeriod: 'energy.usage.period',
+    /**
+     * **청구서가 도착했다** — 공급자가 확정한 금액.
+     *
+     * 우리가 계산한 금액(§`electricityCost`)을 덮지 않는다. 두 값은 다른 것이다: 청구는 사실이고 우리
+     * 계산은 파생이다(구간 요금·예측·가정 비교에 쓴다). 계기 적산과 같은 규율이다 — 다를 때 맞는 쪽은
+     * 그 회계를 가진 쪽이다.
+     *
+     * 어긋나면 **그 사실을 낸다.** 우리 계산이 틀렸다는 뜻이고, 그것을 사람이 찾아내지 않아도 드러나야
+     * 한다(실제로 사람이 찾아낸 적이 있다 — 기본요금을 이 주기의 최대로 매기고 있었다).
+     */
+    bill: 'energy.bill',
     /**
      * 피크 경신 — 월 최대 수요가 갱신됐다.
      *
@@ -1068,6 +1091,16 @@ export const ENERGY_EVENT = {
      */
     drSuggested: 'energy.dr.suggested'
 };
+/**
+ * 값이 어디서 왔나 — **관측의 근거**.
+ *
+ * 같은 kWh 라도 계량기가 잰 것과 공급자 화면에서 긁어온 것은 무게가 다르다. 실제로 긁어온 값이
+ * 망가져 있는 것을 본 적이 있다(다른 현장의 값이 섞이고, 세 자리 수가 한 자리로 왔다). 근거를 값과
+ * 함께 두면 화면이 「이 수는 계량이 아니다」를 말할 수 있다.
+ *
+ * 커널은 이 값으로 판정하지 않는다 — 무엇을 믿을지는 현장이 정한다.
+ */
+export const OBSERVATION_BASIS = ['metered', 'provider', 'billed', 'estimated'];
 // ── Command 채널 어휘 — 트윈의 "행위(act)" 면 (prescriptive/트랜잭션 프론트엔드) ──
 // 코어 공통: order.hold/resume(할당 보류). 도메인: order.release(즉시 투입) 등은 handleCommand 로.
 export const CMD = {

package/dist/ems-kernel.d.ts

@@ -111,6 +111,23 @@ export declare class EmsKernel extends FlowEngine {
     /** 재개점에서 되돌린다 — 담기지 않은 칸은 건드리지 않는다(빈 값으로 덮지 않는다). */
     restoreDomain(raw: unknown): void;
     apply(envelope: CanonicalEnvelope): void;
+    /**
+     * 밖에서 마감되어 온 사용 구간을 그 지점에 적는다.
+     *
+     * ── 수요 구간에 누적하지 않는다 ────────────────────────────────────────────
+     * 우리가 표본에서 마감하는 구간과 **다른 회계**다. 더하면 같은 전기를 두 번 센다. 여기서 하는 일은
+     * 「그 지점의 마지막 마감 구간」을 상태에 두는 것뿐이고, 구간들을 합하는 것은 저널을 읽는 쪽의 일이다
+     * (창을 맞춰 합해야 하므로).
+     *
+     * 모르는 지점이면 세어 둔다 — 조용히 버리면 「값이 왜 안 보이지」로만 남는다(계량과 같은 규율).
+     */
+    private applyUsagePeriod;
+    /**
+     * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
+     *
+     * 두 값은 다른 것이다: 청구는 사실이고 우리 계산은 파생이다. 어긋나면 읽는 쪽이 그것을 낸다.
+     */
+    private applyBill;
     /**
      * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
      *
@@ -180,6 +197,8 @@ export declare class EmsKernel extends FlowEngine {
     private generationPeriodObs;
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     private unclosedGenerationPeriods;
+    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    private lastBill?;
     private applyEquipmentEnergy;
     /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
     private unknownEquipmentReports;

package/dist/ems-kernel.js

@@ -269,8 +269,73 @@ export class EmsKernel extends FlowEngine {
             this.applyGenerated(envelope);
             return;
         }
+        if (envelope.eventType === ENERGY_EVENT.usagePeriod) {
+            this.applyUsagePeriod(envelope);
+            return;
+        }
+        if (envelope.eventType === ENERGY_EVENT.bill) {
+            this.applyBill(envelope);
+            return;
+        }
         super.apply(envelope);
     }
+    /**
+     * 밖에서 마감되어 온 사용 구간을 그 지점에 적는다.
+     *
+     * ── 수요 구간에 누적하지 않는다 ────────────────────────────────────────────
+     * 우리가 표본에서 마감하는 구간과 **다른 회계**다. 더하면 같은 전기를 두 번 센다. 여기서 하는 일은
+     * 「그 지점의 마지막 마감 구간」을 상태에 두는 것뿐이고, 구간들을 합하는 것은 저널을 읽는 쪽의 일이다
+     * (창을 맞춰 합해야 하므로).
+     *
+     * 모르는 지점이면 세어 둔다 — 조용히 버리면 「값이 왜 안 보이지」로만 남는다(계량과 같은 규율).
+     */
+    applyUsagePeriod(envelope) {
+        const d = envelope.data;
+        const id = String(d?.meterId ?? '').trim();
+        if (!id)
+            return;
+        const kWh = Number(d?.kWh);
+        if (!Number.isFinite(kWh))
+            return;
+        const point = this.points.get(id);
+        if (!point) {
+            /* 지점을 만들지 않는다 — 이 문은 「이 구간에 얼마」만 말하고 그 지점이 무엇인지 말하지 않는다. */
+            this.unknownEquipmentReports++;
+            return;
+        }
+        /* 늦게 온 옛 구간이 최신을 덮지 않게 — 끝 시각으로 가린다(계량 표본과 같은 규율). */
+        const toMs = Date.parse(String(d?.to ?? ''));
+        const priorToMs = Date.parse(String(point.lastPeriodTo ?? ''));
+        if (Number.isFinite(priorToMs) && Number.isFinite(toMs) && toMs < priorToMs)
+            return;
+        point.lastPeriodKWh = kWh;
+        if (d?.from)
+            point.lastPeriodFrom = d.from;
+        if (d?.to)
+            point.lastPeriodTo = d.to;
+        if (d?.basis)
+            point.lastPeriodBasis = d.basis;
+        this.revision++;
+    }
+    /**
+     * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
+     *
+     * 두 값은 다른 것이다: 청구는 사실이고 우리 계산은 파생이다. 어긋나면 읽는 쪽이 그것을 낸다.
+     */
+    applyBill(envelope) {
+        const d = envelope.data;
+        if (!d?.from || !d?.to)
+            return;
+        const toMs = Date.parse(String(d.to));
+        if (!Number.isFinite(toMs))
+            return;
+        const priorToMs = Date.parse(String(this.lastBill?.to ?? ''));
+        /* 지난 주기의 청구서가 늦게 와도 최신을 덮지 않는다. */
+        if (Number.isFinite(priorToMs) && toMs < priorToMs)
+            return;
+        this.lastBill = { ...d };
+        this.revision++;
+    }
     /**
      * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
      *
@@ -515,6 +580,8 @@ export class EmsKernel extends FlowEngine {
     generationPeriodObs = new Map();
     /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
     unclosedGenerationPeriods = 0;
+    /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+    lastBill;
     applyEquipmentEnergy(envelope) {
         const d = envelope.data;
         const id = String(d?.equipmentId ?? '').trim();
@@ -1306,6 +1373,9 @@ export class EmsKernel extends FlowEngine {
         /* 못 마감한 수도 이어받는다 — 이어받지 않으면 재기동마다 0 으로 돌아가 문제가 사라진 것처럼 보인다. */
         if (Number.isFinite(e.unclosedGenerationPeriods))
             this.unclosedGenerationPeriods = Number(e.unclosedGenerationPeriods);
+        /* 청구서도 이어받는다 — 재기동마다 사라지면 우리 계산과 견줄 기준이 없어진다. */
+        if (e.lastBill?.from && e.lastBill?.to)
+            this.lastBill = { ...e.lastBill };
     }
     getSnapshot() {
         const snap = super.getSnapshot();
@@ -1330,6 +1400,7 @@ export class EmsKernel extends FlowEngine {
                 }
                 : {}),
             ...(this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {}),
+            ...(this.lastBill ? { lastBill: { ...this.lastBill } } : {}),
             ...(contractKW !== undefined ? { contractKW } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
             ...(this.flowRequests.size

package/dist/ems-profile.d.ts

@@ -37,6 +37,17 @@ export declare const EMS_PROPERTY: {
     readonly standbyKW: "power.standbyKW";
     /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
     readonly demandChargePerKW: "tariff.demandChargePerKW";
+    /**
+     * **요금적용전력**(kW) — 기본요금이 실제로 매겨지는 기준. 계약전력과 다른 값이다.
+     *
+     * 기본요금이 걸리는 수는 이 주기에 잰 최대가 아닌 경우가 많다 — 지난 몇 달의 최고를 끌고 가거나,
+     * 약정 용량으로 매기거나, 사업자가 따로 정한다. 그 규칙은 나라와 계약마다 다르므로 커널이 계산하지
+     * 않고 **계산된 결과를 받는다.** 이 값이 있으면 기본요금이 조건부 파생이 아니라 사실이 된다.
+     *
+     * 계약전력(`contract.kW`)을 이 자리에 넣지 말 것. 넘었을 때의 뜻이 다르다 — 계약 초과는 약정
+     * 위반이고, 이쪽은 다음 주기의 기본요금이 오른다는 뜻이다.
+     */
+    readonly billingDemandKW: "tariff.billingDemandKW";
     /** 사용량 단가 — 1kWh 당. */
     readonly energyChargePerKWh: "tariff.energyChargePerKWh";
     /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */

package/dist/ems-profile.js

@@ -71,6 +71,17 @@ export const EMS_PROPERTY = {
      */
     /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
     demandChargePerKW: 'tariff.demandChargePerKW',
+    /**
+     * **요금적용전력**(kW) — 기본요금이 실제로 매겨지는 기준. 계약전력과 다른 값이다.
+     *
+     * 기본요금이 걸리는 수는 이 주기에 잰 최대가 아닌 경우가 많다 — 지난 몇 달의 최고를 끌고 가거나,
+     * 약정 용량으로 매기거나, 사업자가 따로 정한다. 그 규칙은 나라와 계약마다 다르므로 커널이 계산하지
+     * 않고 **계산된 결과를 받는다.** 이 값이 있으면 기본요금이 조건부 파생이 아니라 사실이 된다.
+     *
+     * 계약전력(`contract.kW`)을 이 자리에 넣지 말 것. 넘었을 때의 뜻이 다르다 — 계약 초과는 약정
+     * 위반이고, 이쪽은 다음 주기의 기본요금이 오른다는 뜻이다.
+     */
+    billingDemandKW: 'tariff.billingDemandKW',
     /** 사용량 단가 — 1kWh 당. */
     energyChargePerKWh: 'tariff.energyChargePerKWh',
     /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
@@ -141,6 +152,11 @@ export const EMS_PROPERTY_SPEC = {
     [EMS_PROPERTY.ratedKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while running, in kW.' },
     [EMS_PROPERTY.standbyKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while idle, in kW.' },
     [EMS_PROPERTY.demandChargePerKW]: { dataType: 'xs:double', note: 'demand charge per kW of billing-period peak, in the declared currency.' },
+    [EMS_PROPERTY.billingDemandKW]: {
+        uom: 'kW',
+        dataType: 'xs:double',
+        note: 'billing demand in kW — the basis the demand charge is actually billed on (often a rolling 12-month peak). Not the contracted power.'
+    },
     [EMS_PROPERTY.energyChargePerKWh]: { dataType: 'xs:double', note: 'energy charge per kWh, in the declared currency.' },
     [EMS_PROPERTY.currency]: { dataType: 'xs:string', note: 'ISO 4217 currency code, e.g. USD or KRW.' },
     [EMS_PROPERTY.capacityKWh]: { uom: 'kWh', dataType: 'xs:double', note: 'usable energy of the storage, in kWh.' },

package/dist/energy-attribution.d.ts

@@ -248,6 +248,24 @@ export declare function energyOfWindows(windows: readonly {
 export interface TariffDeclaration {
     /** 최대수요 1kW 당 기본요금. */
     demandChargePerKW?: number;
+    /**
+     * **요금적용전력**(kW) — 기본요금이 실제로 매겨지는 기준.
+     *
+     * ── 왜 최대수요와 다른 자리인가 (2026-08-29) ─────────────────────────────
+     * **기본요금이 걸리는 수는 이 주기에 잰 최대가 아닌 경우가 많다.** 지난 몇 달의 최고를 끌고 가거나,
+     * 약정한 용량으로 매기거나, 사업자가 따로 정한 기준을 쓴다. 그 규칙은 나라와 계약마다 다르므로
+     * **커널이 그것을 계산하지 않는다** — 계산된 결과를 선언으로 받는다.
+     *
+     * 그것을 확인한 실측 하나(2026-08-29, 어느 고압 현장): 청구 기준 1,650kW · 이 주기의 최대 600kW ·
+     * 기본요금 13,728,000. 이 주기의 최대로 계산하면 2.75배 어긋난다.
+     *
+     * 이 값이 있으면 기본요금은 **조건부 파생이 아니라 사실**이 된다(§`demandBasis`). 없으면 예전처럼
+     * 「이 창의 피크가 그 주기의 최고로 남는다면」이라는 조건을 달고 낸다.
+     *
+     * **계약전력(`contract.kW`)과 다른 값이다.** 계약전력은 약정이고 이것은 청구 기준이다. 넘었을 때
+     * 뜻도 다르다 — 계약 초과는 약정 위반이고, 이쪽은 다음 주기의 기본요금이 오른다는 뜻이다.
+     */
+    billingDemandKW?: number;
     /** 1kWh 당 사용량 요금. */
     energyChargePerKWh?: number;
     /** ISO 4217 통화 코드. 없으면 금액에 단위를 붙일 수 없다. */
@@ -276,9 +294,19 @@ export type ElectricityCost = {
     /** 위 둘의 합. 둘 중 하나만 있으면 그 하나다(없는 쪽을 0 으로 세지 않는다). */
     total?: number;
     currency?: string;
-    /** 기본요금이 성립하는 조건 — 창의 피크가 청구 주기의 최고일 때. */
-    demandBasis?: 'window-peak-as-period-peak';
-    /** 세우지 않은 요금 요소 — 소비처가 「이 값이 청구서가 아니다」를 말할 수 있게. */
+    /**
+     * 기본요금이 무엇 위에 섰나.
+     *
+     *   'billing-demand'                요금적용전력 선언 위 — 조건이 없다(청구 기준 그대로)
+     *   'window-peak-as-period-peak'    창의 피크가 청구 주기의 최고일 때만 성립하는 조건부 값
+     */
+    demandBasis?: 'billing-demand' | 'window-peak-as-period-peak';
+    /**
+     * 세우지 않은 요금 요소 — 소비처가 「이 값이 청구서가 아니다」를 말할 수 있게.
+     *
+     * **이 계산에서 실제로 빠진 것만** 담는다(2026-08-29). 예전에는 고정 목록이었는데, 그러면 선언이
+     * 채워져도 「세우지 않았다」가 그대로 남아 화면이 값을 실제보다 약하게 말한다.
+     */
     notModeled: readonly string[];
 } | {
     reason: 'no-tariff';
@@ -287,4 +315,11 @@ export declare function electricityCost(input: {
     kWh?: number;
     peakKW?: number;
     tariff?: TariffDeclaration;
+    /**
+     * 구간마다 제 단가로 계산한 사용량 요금 — 시간대·계절 요금이 오는 현장에서 소비처가 미리 더해 넘긴다.
+     *
+     * 넘어오면 단일 단가(`energyChargePerKWh`)를 쓰지 않는다. 새벽 87.3원과 낮 222.3원을 하나로 접으면
+     * 「피크를 깎아 얼마를 아끼나」가 사라진다 — 그 차이 위에 서는 답이기 때문이다.
+     */
+    energyChargeFromPeriods?: number;
 }): ElectricityCost;

package/dist/energy-attribution.js

@@ -250,22 +250,45 @@ export function electricityCost(input) {
     const t = input.tariff;
     const eRate = Number(t?.energyChargePerKWh);
     const dRate = Number(t?.demandChargePerKW);
+    const billingKW = Number(t?.billingDemandKW);
     const hasE = Number.isFinite(eRate) && eRate > 0;
     const hasD = Number.isFinite(dRate) && dRate > 0;
+    const hasBilling = Number.isFinite(billingKW) && billingKW > 0;
+    const priced = Number(input.energyChargeFromPeriods);
+    const hasPriced = Number.isFinite(priced) && priced >= 0;
     /* 단가가 하나도 없으면 금액을 만들지 않는다 — 이유를 낸다(빈 값과 0 원을 구별할 수 있게). */
-    if (!hasE && !hasD)
+    if (!hasE && !hasD && !hasPriced)
         return { reason: 'no-tariff' };
     const kWh = Number(input.kWh);
     const peakKW = Number(input.peakKW);
-    const energyCharge = hasE && Number.isFinite(kWh) ? kWh * eRate : undefined;
-    const demandCharge = hasD && Number.isFinite(peakKW) ? peakKW * dRate : undefined;
+    /* 구간별로 매겨진 값이 있으면 그것이 이긴다 — 그 쪽이 실제 단가를 알고 있다. */
+    const energyCharge = hasPriced ? priced : hasE && Number.isFinite(kWh) ? kWh * eRate : undefined;
+    /* 기본요금은 **요금적용전력이 있으면 그것으로** 매긴다. 없을 때만 창의 피크로 조건부 값을 낸다. */
+    const demandBase = hasBilling ? billingKW : peakKW;
+    const demandCharge = hasD && Number.isFinite(demandBase) ? demandBase * dRate : undefined;
     /* 반올림하지 않는다 — 표현은 화면의 일이고, 여기서 깎으면 합과 부분이 어긋난다. */
     const total = energyCharge === undefined && demandCharge === undefined ? undefined : (energyCharge ?? 0) + (demandCharge ?? 0);
+    /*
+     * 「세우지 않은 것」을 **이번 계산 기준으로** 센다. 선언이 채워진 요소는 빼야 화면이 값을 실제보다
+     * 약하게 말하지 않는다.
+     */
+    const notModeled = NOT_MODELED.filter(k => {
+        if ((k === 'tou' || k === 'seasonal') && hasPriced)
+            return false; // 구간마다 제 단가로 매겨졌다
+        if (k === 'ratchet' && hasBilling)
+            return false; // 요금적용전력이 곧 래칫의 결과다
+        return true;
+    });
     return {
         ...(energyCharge !== undefined ? { energyCharge } : {}),
-        ...(demandCharge !== undefined ? { demandCharge, demandBasis: 'window-peak-as-period-peak' } : {}),
+        ...(demandCharge !== undefined
+            ? {
+                demandCharge,
+                demandBasis: (hasBilling ? 'billing-demand' : 'window-peak-as-period-peak')
+            }
+            : {}),
         ...(total !== undefined ? { total } : {}),
         ...(t?.currency ? { currency: String(t.currency) } : {}),
-        notModeled: NOT_MODELED
+        notModeled
     };
 }

package/dist/energy-ingest.d.ts

@@ -98,3 +98,28 @@ export declare function isEnergyGenerationRecord(record: unknown): boolean;
  * (`EnergyEquipmentRecord.generatedKW`).
  */
 export declare function ingestEnergyGenerationRecords(records: EnergyGenerationRecord | EnergyGenerationRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
+/** 마감된 사용 구간 — 커넥터가 맞추는 모양. */
+export interface EnergyUsagePeriodRecord {
+    meterId: string;
+    from: string;
+    to: string;
+    kWh: number;
+    maxKW?: number;
+    unitPrice?: number;
+    currency?: string;
+    basis?: string;
+}
+export declare function isEnergyUsagePeriodRecord(record: unknown): boolean;
+/** 청구서 — 커넥터가 커널의 요금 어휘로 옮겨 보낸다. */
+export interface EnergyBillRecord {
+    from: string;
+    to: string;
+    energyCharge?: number;
+    demandCharge?: number;
+    total?: number;
+    currency?: string;
+    billingDemandKW?: number;
+}
+export declare function isEnergyBillRecord(record: unknown): boolean;
+export declare function ingestEnergyUsagePeriodRecords(records: EnergyUsagePeriodRecord | EnergyUsagePeriodRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
+export declare function ingestEnergyBillRecords(records: EnergyBillRecord | EnergyBillRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;

package/dist/energy-ingest.js

@@ -21,7 +21,7 @@
  * 값(`kW`)이 없는 표본은 **거부하지 않는다**: 계량기가 살아 있다는 사실 자체가 관측이고, 커널이
  * 「받았지만 부하를 못 읽었다」를 구별해 낸다(`observedAbsence: 'no-load-samples'`).
  */
-import { ENERGY_EVENT } from "./contract.js";
+import { ENERGY_EVENT, OBSERVATION_BASIS } from "./contract.js";
 /** 이 레코드가 에너지 표본인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게). */
 export function isEnergyRecord(record) {
     if (!record || typeof record !== 'object')
@@ -29,7 +29,19 @@ export function isEnergyRecord(record) {
     const r = record;
     /* 계량 지점이 있고 EPCIS 어휘가 없으면 에너지다. `epc` 가 함께 있으면 둘 중 무엇인지 알 수 없으므로
        에너지로 받지 않는다 — 그 판단은 커넥터가 명확히 해야 한다. */
-    return typeof r.meterId === 'string' && r.meterId.trim().length > 0 && r.epc === undefined;
+    if (!(typeof r.meterId === 'string' && r.meterId.trim().length > 0 && r.epc === undefined))
+        return false;
+    /*
+     * ── **마감된 구간은 계량 표본이 아니다** (2026-08-29) ──────────────────────
+     *
+     * 둘 다 `meterId` 를 가지므로 이 판별이 겹쳤다. 겹친 채로 두면 갈림의 **순서**가 값을 정한다 —
+     * 순서를 잘못 두면 시간별 사용량이 계량 문으로 가고, 그 문은 `kWh` 를 적산 레지스터로 읽는다.
+     * 우리가 넣는 값은 이미 그 구간의 양이므로 **차분의 차분**이 된다.
+     *
+     * 가장 나쁜 모양이다: **거부되지 않고 값만 틀린다.** 그래서 순서에 기대지 않고 배타로 만든다
+     * (설비 상태와 발전 적산을 가를 때와 같은 규율).
+     */
+    return r.from === undefined && r.to === undefined;
 }
 /**
  * 표본 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 이유와 함께 남는다.
@@ -315,3 +327,152 @@ export function ingestEnergyGenerationRecords(records, opts) {
     }
     return { accepted, rejected };
 }
+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 isEnergyBillRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.from === undefined || r.to === undefined)
+        return false;
+    return r.energyCharge !== undefined || r.demandCharge !== undefined || r.total !== undefined;
+}
+/** 두 시각을 읽고 순서를 본다 — 뒤집힌 구간은 받지 않는다(합이 음수가 된다). */
+function readSpan(r, errors) {
+    const from = String(r?.from ?? '').trim();
+    const to = String(r?.to ?? '').trim();
+    const fromMs = Date.parse(from);
+    const toMs = Date.parse(to);
+    if (!from || !Number.isFinite(fromMs))
+        errors.push(`from 을 시각으로 읽을 수 없다: ${JSON.stringify(r?.from)}`);
+    if (!to || !Number.isFinite(toMs))
+        errors.push(`to 를 시각으로 읽을 수 없다: ${JSON.stringify(r?.to)}`);
+    if (Number.isFinite(fromMs) && Number.isFinite(toMs) && !(toMs > fromMs)) {
+        errors.push(`구간이 뒤집혔거나 길이가 없다(${from} → ${to}) — 어느 쪽이 틀렸는지 우리가 정할 수 없다`);
+    }
+    return errors.length ? undefined : { from, to };
+}
+/** 0 이상의 수 하나 — 없으면 `undefined`, 값인데 읽을 수 없으면 오류. */
+function readAmount(raw, name, errors) {
+    if (raw === undefined || raw === null || String(raw).trim() === '')
+        return undefined;
+    const v = Number(raw);
+    if (!Number.isFinite(v)) {
+        errors.push(`${name} 를 수로 읽을 수 없다: ${JSON.stringify(raw)}`);
+        return undefined;
+    }
+    if (v < 0) {
+        errors.push(`${name} 가 음수다(${v})`);
+        return undefined;
+    }
+    return v;
+}
+export function ingestEnergyUsagePeriodRecords(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 meterId = String(r?.meterId ?? '').trim();
+        if (!meterId)
+            errors.push('meterId 가 없다 — 어느 지점이 쓴 것인지 지어낼 수 없다');
+        const span = readSpan(r, errors);
+        const rawKWh = r?.kWh;
+        let kWh;
+        if (rawKWh === undefined || rawKWh === null || String(rawKWh).trim() === '') {
+            errors.push('kWh 가 없다 — 이 문이 받는 값은 그 구간에 쓴 양이다');
+        }
+        else {
+            kWh = readAmount(rawKWh, 'kWh', errors);
+        }
+        const maxKW = readAmount(r?.maxKW, 'maxKW', errors);
+        const unitPrice = readAmount(r?.unitPrice, 'unitPrice', errors);
+        /* 단가를 실었으면 통화도 있어야 한다 — 단위 없는 금액은 다른 값과 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (unitPrice !== undefined && !currency)
+            errors.push('unitPrice 를 실었는데 currency 가 없다 — 단위 없는 금액은 더할 수 없다');
+        /* 근거는 아는 목록 안에서만 — 모르는 값을 받으면 화면이 그것을 근거로 말한다. */
+        let basis;
+        const rawBasis = r?.basis;
+        if (rawBasis !== undefined && rawBasis !== null && String(rawBasis).trim()) {
+            const text = String(rawBasis).trim();
+            if (!OBSERVATION_BASIS.includes(text)) {
+                errors.push(`basis 가 아는 값이 아니다(${OBSERVATION_BASIS.join('·')}): ${JSON.stringify(rawBasis)}`);
+            }
+            else
+                basis = text;
+        }
+        if (errors.length || !span || kWh === undefined) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            meterId,
+            from: span.from,
+            to: span.to,
+            kWh,
+            ...(maxKW !== undefined ? { maxKW } : {}),
+            ...(unitPrice !== undefined ? { unitPrice } : {}),
+            ...(currency ? { currency } : {}),
+            ...(basis ? { basis } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-usage-period-${++seq}`,
+            eventType: ENERGY_EVENT.usagePeriod,
+            /* 구간의 **끝**이 이 사실이 성립한 시각이다 — 시작으로 달면 저널이 그 구간을 미리 안 것이 된다. */
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function ingestEnergyBillRecords(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 energyCharge = readAmount(r?.energyCharge, 'energyCharge', errors);
+        const demandCharge = readAmount(r?.demandCharge, 'demandCharge', errors);
+        const total = readAmount(r?.total, 'total', errors);
+        const billingDemandKW = readAmount(r?.billingDemandKW, 'billingDemandKW', errors);
+        if (energyCharge === undefined && demandCharge === undefined && total === undefined) {
+            errors.push('금액이 하나도 없다 — 적을 사실이 없는 청구서는 받지 않는다');
+        }
+        /* 금액을 실었으면 통화가 있어야 한다. 없으면 그 수는 다른 수와 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (!currency)
+            errors.push('currency 가 없다 — 단위 없는 금액은 다른 금액과 더할 수 없다');
+        /*
+         * 합계가 부분들과 다른 것은 **거부하지 않는다.** 세금·역률 요금·최소 청구액처럼 우리가 세지 않는
+         * 항목이 청구서에 있을 수 있다. 그 차이는 사실이고, 읽는 쪽이 그것을 보고 판단한다.
+         */
+        if (errors.length || !span) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            from: span.from,
+            to: span.to,
+            ...(energyCharge !== undefined ? { energyCharge } : {}),
+            ...(demandCharge !== undefined ? { demandCharge } : {}),
+            ...(total !== undefined ? { total } : {}),
+            ...(currency ? { currency } : {}),
+            ...(billingDemandKW !== undefined ? { billingDemandKW } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-bill-${++seq}`,
+            eventType: ENERGY_EVENT.bill,
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}

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 } from './energy-ingest.ts';
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord } 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, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
+export type { EnergyRecord, EnergyEquipmentRecord, EnergyGenerationRecord, EnergyUsagePeriodRecord, EnergyBillRecord, 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 } from "./energy-ingest.js";
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord } 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

@@ -56,6 +56,7 @@ __export(index_exports, {
   MES_TYPES: () => MES_TYPES,
   METER_DIRECTION: () => METER_DIRECTION,
   MesKernel: () => MesKernel,
+  OBSERVATION_BASIS: () => OBSERVATION_BASIS,
   OPERATION_PROPERTY: () => OPERATION_PROPERTY,
   OP_EVENT: () => OP_EVENT,
   OP_PARAM: () => OP_PARAM,
@@ -124,16 +125,20 @@ __export(index_exports, {
   inWorkCalendar: () => inWorkCalendar,
   inWorkCalendarAt: () => inWorkCalendarAt,
   ingest: () => ingest,
+  ingestEnergyBillRecords: () => ingestEnergyBillRecords,
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords: () => ingestEnergyGenerationRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  ingestEnergyUsagePeriodRecords: () => ingestEnergyUsagePeriodRecords,
   ingestMasterData: () => ingestMasterData,
   ingestOperationalRecords: () => ingestOperationalRecords,
   isAggregationRecord: () => isAggregationRecord,
   isElectricalLocationType: () => isElectricalLocationType,
+  isEnergyBillRecord: () => isEnergyBillRecord,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyGenerationRecord: () => isEnergyGenerationRecord,
   isEnergyRecord: () => isEnergyRecord,
+  isEnergyUsagePeriodRecord: () => isEnergyUsagePeriodRecord,
   isEpcisEventType: () => isEpcisEventType,
   isEquipmentLevel: () => isEquipmentLevel,
   isMasterDataRecord: () => isMasterDataRecord,
@@ -692,6 +697,29 @@ var ENERGY_EVENT = {
   equipment: "energy.equipment",
   /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
   demandWindow: "energy.demand.window",
+  /**
+   * **마감된 사용 구간이 도착했다** — 우리가 마감한 것이 아니라 밖에서 확정되어 온 것이다.
+   *
+   * 계량 표본이 오지 않는 현장이 있다. 공급자의 조회나 계량 데이터 시스템이 「이 구간에 X 썼다」를
+   * 이미 마감해 준다. 그 값을 적산(`energy.measured` 의 `kWh`)으로 보내면 커널이 그것을 누적으로
+   * 읽고 차분을 또 구한다 — 차분의 차분이 되어 틀린다. 그래서 다른 사건이다.
+   *
+   * `demandWindow` 와 **합치지 않는다.** 하나는 우리가 표본에서 마감한 것이고 이것은 밖에서 온
+   * 것이다. 두 회계를 더하면 같은 전기를 두 번 센다. 둘 다 있으면 읽는 쪽이 하나를 고르고 어느
+   * 쪽인지 말한다.
+   */
+  usagePeriod: "energy.usage.period",
+  /**
+   * **청구서가 도착했다** — 공급자가 확정한 금액.
+   *
+   * 우리가 계산한 금액(§`electricityCost`)을 덮지 않는다. 두 값은 다른 것이다: 청구는 사실이고 우리
+   * 계산은 파생이다(구간 요금·예측·가정 비교에 쓴다). 계기 적산과 같은 규율이다 — 다를 때 맞는 쪽은
+   * 그 회계를 가진 쪽이다.
+   *
+   * 어긋나면 **그 사실을 낸다.** 우리 계산이 틀렸다는 뜻이고, 그것을 사람이 찾아내지 않아도 드러나야
+   * 한다(실제로 사람이 찾아낸 적이 있다 — 기본요금을 이 주기의 최대로 매기고 있었다).
+   */
+  bill: "energy.bill",
   /**
    * 피크 경신 — 월 최대 수요가 갱신됐다.
    *
@@ -726,6 +754,7 @@ var ENERGY_EVENT = {
    */
   drSuggested: "energy.dr.suggested"
 };
+var OBSERVATION_BASIS = ["metered", "provider", "billed", "estimated"];
 var CMD = {
   orderHold: "order.hold",
   orderResume: "order.resume",
@@ -7464,6 +7493,17 @@ var EMS_PROPERTY = {
    */
   /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
   demandChargePerKW: "tariff.demandChargePerKW",
+  /**
+   * **요금적용전력**(kW) — 기본요금이 실제로 매겨지는 기준. 계약전력과 다른 값이다.
+   *
+   * 기본요금이 걸리는 수는 이 주기에 잰 최대가 아닌 경우가 많다 — 지난 몇 달의 최고를 끌고 가거나,
+   * 약정 용량으로 매기거나, 사업자가 따로 정한다. 그 규칙은 나라와 계약마다 다르므로 커널이 계산하지
+   * 않고 **계산된 결과를 받는다.** 이 값이 있으면 기본요금이 조건부 파생이 아니라 사실이 된다.
+   *
+   * 계약전력(`contract.kW`)을 이 자리에 넣지 말 것. 넘었을 때의 뜻이 다르다 — 계약 초과는 약정
+   * 위반이고, 이쪽은 다음 주기의 기본요금이 오른다는 뜻이다.
+   */
+  billingDemandKW: "tariff.billingDemandKW",
   /** 사용량 단가 — 1kWh 당. */
   energyChargePerKWh: "tariff.energyChargePerKWh",
   /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
@@ -7532,6 +7572,11 @@ var EMS_PROPERTY_SPEC = {
   [EMS_PROPERTY.ratedKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while running, in kW." },
   [EMS_PROPERTY.standbyKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while idle, in kW." },
   [EMS_PROPERTY.demandChargePerKW]: { dataType: "xs:double", note: "demand charge per kW of billing-period peak, in the declared currency." },
+  [EMS_PROPERTY.billingDemandKW]: {
+    uom: "kW",
+    dataType: "xs:double",
+    note: "billing demand in kW \u2014 the basis the demand charge is actually billed on (often a rolling 12-month peak). Not the contracted power."
+  },
   [EMS_PROPERTY.energyChargePerKWh]: { dataType: "xs:double", note: "energy charge per kWh, in the declared currency." },
   [EMS_PROPERTY.currency]: { dataType: "xs:string", note: "ISO 4217 currency code, e.g. USD or KRW." },
   [EMS_PROPERTY.capacityKWh]: { uom: "kWh", dataType: "xs:double", note: "usable energy of the storage, in kWh." },
@@ -7897,8 +7942,61 @@ var EmsKernel = class extends FlowEngine {
       this.applyGenerated(envelope);
       return;
     }
+    if (envelope.eventType === ENERGY_EVENT.usagePeriod) {
+      this.applyUsagePeriod(envelope);
+      return;
+    }
+    if (envelope.eventType === ENERGY_EVENT.bill) {
+      this.applyBill(envelope);
+      return;
+    }
     super.apply(envelope);
   }
+  /**
+   * 밖에서 마감되어 온 사용 구간을 그 지점에 적는다.
+   *
+   * ── 수요 구간에 누적하지 않는다 ────────────────────────────────────────────
+   * 우리가 표본에서 마감하는 구간과 **다른 회계**다. 더하면 같은 전기를 두 번 센다. 여기서 하는 일은
+   * 「그 지점의 마지막 마감 구간」을 상태에 두는 것뿐이고, 구간들을 합하는 것은 저널을 읽는 쪽의 일이다
+   * (창을 맞춰 합해야 하므로).
+   *
+   * 모르는 지점이면 세어 둔다 — 조용히 버리면 「값이 왜 안 보이지」로만 남는다(계량과 같은 규율).
+   */
+  applyUsagePeriod(envelope) {
+    const d = envelope.data;
+    const id = String(d?.meterId ?? "").trim();
+    if (!id) return;
+    const kWh = Number(d?.kWh);
+    if (!Number.isFinite(kWh)) return;
+    const point = this.points.get(id);
+    if (!point) {
+      this.unknownEquipmentReports++;
+      return;
+    }
+    const toMs = Date.parse(String(d?.to ?? ""));
+    const priorToMs = Date.parse(String(point.lastPeriodTo ?? ""));
+    if (Number.isFinite(priorToMs) && Number.isFinite(toMs) && toMs < priorToMs) return;
+    point.lastPeriodKWh = kWh;
+    if (d?.from) point.lastPeriodFrom = d.from;
+    if (d?.to) point.lastPeriodTo = d.to;
+    if (d?.basis) point.lastPeriodBasis = d.basis;
+    this.revision++;
+  }
+  /**
+   * 청구서를 상태에 둔다 — **우리 계산을 덮지 않는다.**
+   *
+   * 두 값은 다른 것이다: 청구는 사실이고 우리 계산은 파생이다. 어긋나면 읽는 쪽이 그것을 낸다.
+   */
+  applyBill(envelope) {
+    const d = envelope.data;
+    if (!d?.from || !d?.to) return;
+    const toMs = Date.parse(String(d.to));
+    if (!Number.isFinite(toMs)) return;
+    const priorToMs = Date.parse(String(this.lastBill?.to ?? ""));
+    if (Number.isFinite(priorToMs) && toMs < priorToMs) return;
+    this.lastBill = { ...d };
+    this.revision++;
+  }
   /**
    * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
    *
@@ -8058,6 +8156,8 @@ var EmsKernel = class extends FlowEngine {
   generationPeriodObs = /* @__PURE__ */ new Map();
   /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
   unclosedGenerationPeriods = 0;
+  /** 마지막으로 받은 청구서 — 공급자가 확정한 금액. 우리 계산과 견주는 기준이다. */
+  lastBill;
   applyEquipmentEnergy(envelope) {
     const d = envelope.data;
     const id = String(d?.equipmentId ?? "").trim();
@@ -8610,6 +8710,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 };
   }
   getSnapshot() {
     const snap = super.getSnapshot();
@@ -8630,6 +8731,7 @@ var EmsKernel = class extends FlowEngine {
         generationPeriods: [...this.generationPeriodObs.entries()].map(([equipmentId, o]) => ({ equipmentId, ...o }))
       } : {},
       ...this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {},
+      ...this.lastBill ? { lastBill: { ...this.lastBill } } : {},
       ...contractKW !== void 0 ? { contractKW } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
       ...this.flowRequests.size ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) } : {}
@@ -9429,7 +9531,8 @@ var TwinRuntime = class {
 function isEnergyRecord(record) {
   if (!record || typeof record !== "object") return false;
   const r = record;
-  return typeof r.meterId === "string" && r.meterId.trim().length > 0 && r.epc === void 0;
+  if (!(typeof r.meterId === "string" && r.meterId.trim().length > 0 && r.epc === void 0)) return false;
+  return r.from === void 0 && r.to === void 0;
 }
 function ingestEnergyRecords(records, opts) {
   const arr = Array.isArray(records) ? records : records ? [records] : [];
@@ -9634,6 +9737,135 @@ function ingestEnergyGenerationRecords(records, opts) {
   }
   return { accepted, rejected };
 }
+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 isEnergyBillRecord(record) {
+  const r = record;
+  if (!r || typeof r !== "object") return false;
+  if (r.from === void 0 || r.to === void 0) return false;
+  return r.energyCharge !== void 0 || r.demandCharge !== void 0 || r.total !== void 0;
+}
+function readSpan(r, errors) {
+  const from = String(r?.from ?? "").trim();
+  const to = String(r?.to ?? "").trim();
+  const fromMs = Date.parse(from);
+  const toMs = Date.parse(to);
+  if (!from || !Number.isFinite(fromMs)) errors.push(`from \uC744 \uC2DC\uAC01\uC73C\uB85C \uC77D\uC744 \uC218 \uC5C6\uB2E4: ${JSON.stringify(r?.from)}`);
+  if (!to || !Number.isFinite(toMs)) errors.push(`to \uB97C \uC2DC\uAC01\uC73C\uB85C \uC77D\uC744 \uC218 \uC5C6\uB2E4: ${JSON.stringify(r?.to)}`);
+  if (Number.isFinite(fromMs) && Number.isFinite(toMs) && !(toMs > fromMs)) {
+    errors.push(`\uAD6C\uAC04\uC774 \uB4A4\uC9D1\uD614\uAC70\uB098 \uAE38\uC774\uAC00 \uC5C6\uB2E4(${from} \u2192 ${to}) \u2014 \uC5B4\uB290 \uCABD\uC774 \uD2C0\uB838\uB294\uC9C0 \uC6B0\uB9AC\uAC00 \uC815\uD560 \uC218 \uC5C6\uB2E4`);
+  }
+  return errors.length ? void 0 : { from, to };
+}
+function readAmount(raw, name, errors) {
+  if (raw === void 0 || raw === null || String(raw).trim() === "") return void 0;
+  const v = Number(raw);
+  if (!Number.isFinite(v)) {
+    errors.push(`${name} \uB97C \uC218\uB85C \uC77D\uC744 \uC218 \uC5C6\uB2E4: ${JSON.stringify(raw)}`);
+    return void 0;
+  }
+  if (v < 0) {
+    errors.push(`${name} \uAC00 \uC74C\uC218\uB2E4(${v})`);
+    return void 0;
+  }
+  return v;
+}
+function ingestEnergyUsagePeriodRecords(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 meterId = String(r?.meterId ?? "").trim();
+    if (!meterId) errors.push("meterId \uAC00 \uC5C6\uB2E4 \u2014 \uC5B4\uB290 \uC9C0\uC810\uC774 \uC4F4 \uAC83\uC778\uC9C0 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4");
+    const span = readSpan(r, errors);
+    const rawKWh = r?.kWh;
+    let kWh;
+    if (rawKWh === void 0 || rawKWh === null || String(rawKWh).trim() === "") {
+      errors.push("kWh \uAC00 \uC5C6\uB2E4 \u2014 \uC774 \uBB38\uC774 \uBC1B\uB294 \uAC12\uC740 \uADF8 \uAD6C\uAC04\uC5D0 \uC4F4 \uC591\uC774\uB2E4");
+    } else {
+      kWh = readAmount(rawKWh, "kWh", errors);
+    }
+    const maxKW = readAmount(r?.maxKW, "maxKW", errors);
+    const unitPrice = readAmount(r?.unitPrice, "unitPrice", errors);
+    const currency = String(r?.currency ?? "").trim() || void 0;
+    if (unitPrice !== void 0 && !currency) errors.push("unitPrice \uB97C \uC2E4\uC5C8\uB294\uB370 currency \uAC00 \uC5C6\uB2E4 \u2014 \uB2E8\uC704 \uC5C6\uB294 \uAE08\uC561\uC740 \uB354\uD560 \uC218 \uC5C6\uB2E4");
+    let basis;
+    const rawBasis = r?.basis;
+    if (rawBasis !== void 0 && rawBasis !== null && String(rawBasis).trim()) {
+      const text = String(rawBasis).trim();
+      if (!OBSERVATION_BASIS.includes(text)) {
+        errors.push(`basis \uAC00 \uC544\uB294 \uAC12\uC774 \uC544\uB2C8\uB2E4(${OBSERVATION_BASIS.join("\xB7")}): ${JSON.stringify(rawBasis)}`);
+      } else basis = text;
+    }
+    if (errors.length || !span || kWh === void 0) {
+      rejected.push({ record: r, errors });
+      continue;
+    }
+    const data = {
+      meterId,
+      from: span.from,
+      to: span.to,
+      kWh,
+      ...maxKW !== void 0 ? { maxKW } : {},
+      ...unitPrice !== void 0 ? { unitPrice } : {},
+      ...currency ? { currency } : {},
+      ...basis ? { basis } : {}
+    };
+    accepted.push({
+      eventId: `${opts.tenantId}-usage-period-${++seq}`,
+      eventType: ENERGY_EVENT.usagePeriod,
+      /* 구간의 **끝**이 이 사실이 성립한 시각이다 — 시작으로 달면 저널이 그 구간을 미리 안 것이 된다. */
+      eventTime: span.to,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
+function ingestEnergyBillRecords(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 energyCharge = readAmount(r?.energyCharge, "energyCharge", errors);
+    const demandCharge = readAmount(r?.demandCharge, "demandCharge", errors);
+    const total = readAmount(r?.total, "total", errors);
+    const billingDemandKW = readAmount(r?.billingDemandKW, "billingDemandKW", errors);
+    if (energyCharge === void 0 && demandCharge === void 0 && total === void 0) {
+      errors.push("\uAE08\uC561\uC774 \uD558\uB098\uB3C4 \uC5C6\uB2E4 \u2014 \uC801\uC744 \uC0AC\uC2E4\uC774 \uC5C6\uB294 \uCCAD\uAD6C\uC11C\uB294 \uBC1B\uC9C0 \uC54A\uB294\uB2E4");
+    }
+    const currency = String(r?.currency ?? "").trim() || void 0;
+    if (!currency) errors.push("currency \uAC00 \uC5C6\uB2E4 \u2014 \uB2E8\uC704 \uC5C6\uB294 \uAE08\uC561\uC740 \uB2E4\uB978 \uAE08\uC561\uACFC \uB354\uD560 \uC218 \uC5C6\uB2E4");
+    if (errors.length || !span) {
+      rejected.push({ record: r, errors });
+      continue;
+    }
+    const data = {
+      from: span.from,
+      to: span.to,
+      ...energyCharge !== void 0 ? { energyCharge } : {},
+      ...demandCharge !== void 0 ? { demandCharge } : {},
+      ...total !== void 0 ? { total } : {},
+      ...currency ? { currency } : {},
+      ...billingDemandKW !== void 0 ? { billingDemandKW } : {}
+    };
+    accepted.push({
+      eventId: `${opts.tenantId}-bill-${++seq}`,
+      eventType: ENERGY_EVENT.bill,
+      eventTime: span.to,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
 
 // src/operational-ingest.ts
 var TASK_STATUS = ["created", "assigned", "in-progress", "completed"];
@@ -10142,20 +10374,33 @@ function electricityCost(input) {
   const t = input.tariff;
   const eRate = Number(t?.energyChargePerKWh);
   const dRate = Number(t?.demandChargePerKW);
+  const billingKW = Number(t?.billingDemandKW);
   const hasE = Number.isFinite(eRate) && eRate > 0;
   const hasD = Number.isFinite(dRate) && dRate > 0;
-  if (!hasE && !hasD) return { reason: "no-tariff" };
+  const hasBilling = Number.isFinite(billingKW) && billingKW > 0;
+  const priced = Number(input.energyChargeFromPeriods);
+  const hasPriced = Number.isFinite(priced) && priced >= 0;
+  if (!hasE && !hasD && !hasPriced) return { reason: "no-tariff" };
   const kWh = Number(input.kWh);
   const peakKW = Number(input.peakKW);
-  const energyCharge = hasE && Number.isFinite(kWh) ? kWh * eRate : void 0;
-  const demandCharge = hasD && Number.isFinite(peakKW) ? peakKW * dRate : void 0;
+  const energyCharge = hasPriced ? priced : hasE && Number.isFinite(kWh) ? kWh * eRate : void 0;
+  const demandBase = hasBilling ? billingKW : peakKW;
+  const demandCharge = hasD && Number.isFinite(demandBase) ? demandBase * dRate : void 0;
   const total = energyCharge === void 0 && demandCharge === void 0 ? void 0 : (energyCharge ?? 0) + (demandCharge ?? 0);
+  const notModeled = NOT_MODELED.filter((k) => {
+    if ((k === "tou" || k === "seasonal") && hasPriced) return false;
+    if (k === "ratchet" && hasBilling) return false;
+    return true;
+  });
   return {
     ...energyCharge !== void 0 ? { energyCharge } : {},
-    ...demandCharge !== void 0 ? { demandCharge, demandBasis: "window-peak-as-period-peak" } : {},
+    ...demandCharge !== void 0 ? {
+      demandCharge,
+      demandBasis: hasBilling ? "billing-demand" : "window-peak-as-period-peak"
+    } : {},
     ...total !== void 0 ? { total } : {},
     ...t?.currency ? { currency: String(t.currency) } : {},
-    notModeled: NOT_MODELED
+    notModeled
   };
 }
 
@@ -10240,6 +10485,7 @@ function retiredVocabularyIn(line) {
   MES_TYPES,
   METER_DIRECTION,
   MesKernel,
+  OBSERVATION_BASIS,
   OPERATION_PROPERTY,
   OP_EVENT,
   OP_PARAM,
@@ -10308,16 +10554,20 @@ function retiredVocabularyIn(line) {
   inWorkCalendar,
   inWorkCalendarAt,
   ingest,
+  ingestEnergyBillRecords,
   ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords,
   ingestEnergyRecords,
+  ingestEnergyUsagePeriodRecords,
   ingestMasterData,
   ingestOperationalRecords,
   isAggregationRecord,
   isElectricalLocationType,
+  isEnergyBillRecord,
   isEnergyEquipmentRecord,
   isEnergyGenerationRecord,
   isEnergyRecord,
+  isEnergyUsagePeriodRecord,
   isEpcisEventType,
   isEquipmentLevel,
   isMasterDataRecord,

package/package.json

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