@operato/twin-kernel 0.7.12 → 0.7.14

package/dist/ems-profile.d.ts

@@ -16,5 +16,11 @@ export declare const EMS_PROPERTY: {
     readonly ratedKW: "power.ratedKW";
     /** 멈춰 있을 때의 소비(kW). 없으면 멈춘 동안을 **비운다** — 0 이라고 주장하지 않는다. */
     readonly standbyKW: "power.standbyKW";
+    /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
+    readonly demandChargePerKW: "tariff.demandChargePerKW";
+    /** 사용량 단가 — 1kWh 당. */
+    readonly energyChargePerKWh: "tariff.energyChargePerKWh";
+    /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
+    readonly currency: "tariff.currency";
 };
 export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -20,7 +20,26 @@ export const EMS_PROPERTY = {
     /** 가동 중 소비(kW). */
     ratedKW: 'power.ratedKW',
     /** 멈춰 있을 때의 소비(kW). 없으면 멈춘 동안을 **비운다** — 0 이라고 주장하지 않는다. */
-    standbyKW: 'power.standbyKW'
+    standbyKW: 'power.standbyKW',
+    /*
+     * ── 요금 단가 — 수를 금액으로 바꾸는 선언 (2026-08-17) ─────────────────────
+     *
+     * 그동안 트윈은 「최대수요 328kW」·「전력량 1,547kWh」까지 말하고 멈췄다. 그런데 피크를 깎는 일이
+     * 돈이 되는 이유는 **요금이 둘로 나뉘기** 때문이다: 사용량(kWh)에 붙는 요금과 **최대수요(kW)에 붙는
+     * 기본요금**. 단가가 없으면 그 절반을 말할 수 없고, 그래서 「피크를 깎아 얼마를 아끼나」에 답하지 못했다.
+     *
+     * 단가는 **현장의 계약**이다(같은 나라 안에서도 사업자·요금제마다 다르다). 그래서 기본값을 두지
+     * 않는다 — 선언하지 않으면 금액을 계산하지 않는다. 짐작한 단가로 낸 금액은 숫자가 있다는 것만으로
+     * 사람을 결정으로 밀어붙인다.
+     *
+     * 계약전력(`contract.kW`)과 같은 자리(수전)에 선언한다.
+     */
+    /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
+    demandChargePerKW: 'tariff.demandChargePerKW',
+    /** 사용량 단가 — 1kWh 당. */
+    energyChargePerKWh: 'tariff.energyChargePerKWh',
+    /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
+    currency: 'tariff.currency'
 };
 export const EMS_TYPES = [
     /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */

package/dist/energy-attribution.d.ts

@@ -221,3 +221,47 @@ export declare function energyOfWindows(windows: readonly {
     startMs: number;
     endMs: number;
 }): WindowedEnergy;
+/** 선언된 단가 — 없는 항목은 계산하지 않는다(0 으로 두지 않는다). */
+export interface TariffDeclaration {
+    /** 최대수요 1kW 당 기본요금. */
+    demandChargePerKW?: number;
+    /** 1kWh 당 사용량 요금. */
+    energyChargePerKWh?: number;
+    /** ISO 4217 통화 코드. 없으면 금액에 단위를 붙일 수 없다. */
+    currency?: string;
+}
+/**
+ * 이 창의 전기요금 — **청구서가 아니다.**
+ *
+ * ── 무엇을 계산하나 ─────────────────────────────────────────────────────────
+ *  · 사용량 부분: `kWh × 단가`. 이것은 창에 비례하므로 창을 잘라도 뜻이 유지된다.
+ *  · 기본요금 부분: `최대수요 × 단가`. **이것은 창의 값이 아니다** — 기본요금은 청구 주기(보통 한 달)의
+ *    최고 수요로 매겨진다. 그래서 이 값의 뜻은 「이 창의 최대수요가 그 주기의 최고로 남는다면 기본요금이
+ *    이만큼」이고, 그 조건을 `demandBasis` 로 함께 낸다. 조건을 감추면 창을 좁힌 사람이 요금이 줄었다고
+ *    읽는다(실제로는 같은 달의 다른 시각에 더 높은 피크가 있을 수 있다).
+ *
+ * ── 세우지 않은 것 ──────────────────────────────────────────────────────────
+ * 시간대 요금(TOU)·계절 요금·래칫(직전 개월의 피크를 끌고 가는 구조)·최소 청구액·역률 요금은
+ * **모델에 없다.** 있는 척하지 않는다 — 그것들이 필요한 현장에서는 이 값이 실 청구서와 다르고,
+ * 그 사실을 아는 편이 그럴듯한 총액보다 낫다.
+ */
+export type ElectricityCost = {
+    /** 사용량 요금 — 선언과 전력량이 다 있을 때만. */
+    energyCharge?: number;
+    /** 기본요금 — 선언과 최대수요가 다 있을 때만. */
+    demandCharge?: number;
+    /** 위 둘의 합. 둘 중 하나만 있으면 그 하나다(없는 쪽을 0 으로 세지 않는다). */
+    total?: number;
+    currency?: string;
+    /** 기본요금이 성립하는 조건 — 창의 피크가 청구 주기의 최고일 때. */
+    demandBasis?: 'window-peak-as-period-peak';
+    /** 세우지 않은 요금 요소 — 소비처가 「이 값이 청구서가 아니다」를 말할 수 있게. */
+    notModeled: readonly string[];
+} | {
+    reason: 'no-tariff';
+};
+export declare function electricityCost(input: {
+    kWh?: number;
+    peakKW?: number;
+    tariff?: TariffDeclaration;
+}): ElectricityCost;

package/dist/energy-attribution.js

@@ -239,3 +239,27 @@ export function energyOfWindows(windows, range) {
         ...(first !== undefined && last !== undefined ? { window: { startMs: first, endMs: last } } : {})
     };
 }
+const NOT_MODELED = ['tou', 'seasonal', 'ratchet', 'minimum-bill', 'power-factor'];
+export function electricityCost(input) {
+    const t = input.tariff;
+    const eRate = Number(t?.energyChargePerKWh);
+    const dRate = Number(t?.demandChargePerKW);
+    const hasE = Number.isFinite(eRate) && eRate > 0;
+    const hasD = Number.isFinite(dRate) && dRate > 0;
+    /* 단가가 하나도 없으면 금액을 만들지 않는다 — 이유를 낸다(빈 값과 0 원을 구별할 수 있게). */
+    if (!hasE && !hasD)
+        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 total = energyCharge === undefined && demandCharge === undefined ? undefined : (energyCharge ?? 0) + (demandCharge ?? 0);
+    return {
+        ...(energyCharge !== undefined ? { energyCharge } : {}),
+        ...(demandCharge !== undefined ? { demandCharge, demandBasis: 'window-peak-as-period-peak' } : {}),
+        ...(total !== undefined ? { total } : {}),
+        ...(t?.currency ? { currency: String(t.currency) } : {}),
+        notModeled: NOT_MODELED
+    };
+}

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from './energy-ingest.ts';
-export { attributeEnergy, energyIntensity, energyOfWindows } from './energy-attribution.ts';
-export type { AttributionBasis, AttributionResult, EnergyConsumer, EnergyPool, EnergyShare, IntensityInput, IntensityResult, IntensityDenominator, WeightKind, WindowedEnergy } from './energy-attribution.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, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
 export * from './vocabulary.ts';

package/dist/index.js

@@ -30,6 +30,6 @@ export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from "./energy-ingest.js";
-export { attributeEnergy, energyIntensity, energyOfWindows } from "./energy-attribution.js";
+export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from "./energy-attribution.js";
 /* 에너지 상태 타입은 **계약**에 있다(상태의 모양은 계약이다) — contract 의 `export *` 가 이미 낸다. */
 export * from "./vocabulary.js";

package/dist-cjs/index.cjs

@@ -96,6 +96,7 @@ __export(index_exports, {
   documentPath: () => documentPath,
   dueStatusOf: () => dueStatusOf,
   effectivityAt: () => effectivityAt,
+  electricityCost: () => electricityCost,
   energyIntensity: () => energyIntensity,
   energyOfWindows: () => energyOfWindows,
   fefoPolicy: () => fefoPolicy,
@@ -1683,7 +1684,26 @@ var EMS_PROPERTY = {
   /** 가동 중 소비(kW). */
   ratedKW: "power.ratedKW",
   /** 멈춰 있을 때의 소비(kW). 없으면 멈춘 동안을 **비운다** — 0 이라고 주장하지 않는다. */
-  standbyKW: "power.standbyKW"
+  standbyKW: "power.standbyKW",
+  /*
+   * ── 요금 단가 — 수를 금액으로 바꾸는 선언 (2026-08-17) ─────────────────────
+   *
+   * 그동안 트윈은 「최대수요 328kW」·「전력량 1,547kWh」까지 말하고 멈췄다. 그런데 피크를 깎는 일이
+   * 돈이 되는 이유는 **요금이 둘로 나뉘기** 때문이다: 사용량(kWh)에 붙는 요금과 **최대수요(kW)에 붙는
+   * 기본요금**. 단가가 없으면 그 절반을 말할 수 없고, 그래서 「피크를 깎아 얼마를 아끼나」에 답하지 못했다.
+   *
+   * 단가는 **현장의 계약**이다(같은 나라 안에서도 사업자·요금제마다 다르다). 그래서 기본값을 두지
+   * 않는다 — 선언하지 않으면 금액을 계산하지 않는다. 짐작한 단가로 낸 금액은 숫자가 있다는 것만으로
+   * 사람을 결정으로 밀어붙인다.
+   *
+   * 계약전력(`contract.kW`)과 같은 자리(수전)에 선언한다.
+   */
+  /** 기본요금 단가 — 최대수요 1kW 당(청구 주기 기준). */
+  demandChargePerKW: "tariff.demandChargePerKW",
+  /** 사용량 단가 — 1kWh 당. */
+  energyChargePerKWh: "tariff.energyChargePerKWh",
+  /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
+  currency: "tariff.currency"
 };
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
@@ -6468,6 +6488,27 @@ function energyOfWindows(windows, range) {
     ...first !== void 0 && last !== void 0 ? { window: { startMs: first, endMs: last } } : {}
   };
 }
+var NOT_MODELED = ["tou", "seasonal", "ratchet", "minimum-bill", "power-factor"];
+function electricityCost(input) {
+  const t = input.tariff;
+  const eRate = Number(t?.energyChargePerKWh);
+  const dRate = Number(t?.demandChargePerKW);
+  const hasE = Number.isFinite(eRate) && eRate > 0;
+  const hasD = Number.isFinite(dRate) && dRate > 0;
+  if (!hasE && !hasD) 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 total = energyCharge === void 0 && demandCharge === void 0 ? void 0 : (energyCharge ?? 0) + (demandCharge ?? 0);
+  return {
+    ...energyCharge !== void 0 ? { energyCharge } : {},
+    ...demandCharge !== void 0 ? { demandCharge, demandBasis: "window-peak-as-period-peak" } : {},
+    ...total !== void 0 ? { total } : {},
+    ...t?.currency ? { currency: String(t.currency) } : {},
+    notModeled: NOT_MODELED
+  };
+}
 
 // src/vocabulary.ts
 var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE"];
@@ -6590,6 +6631,7 @@ function retiredVocabularyIn(line) {
   documentPath,
   dueStatusOf,
   effectivityAt,
+  electricityCost,
   energyIntensity,
   energyOfWindows,
   fefoPolicy,

package/package.json

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