@operato/twin-kernel 0.7.76 → 0.7.77

package/dist/ems-kernel.d.ts

@@ -337,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

@@ -1410,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 ?? []) {

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.js

@@ -384,6 +384,16 @@ export function isEnergyTariffBasisRecord(record) {
         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;
 }
 /**

package/dist-cjs/index.cjs

@@ -7567,8 +7567,22 @@ var EMS_PROPERTY = {
    *
    * 정격만 있고 형상이 없으면 발전하지 않는다 — 하루 종일 정격으로 발전하는 태양광은 없다.
    */
-  /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+  /**
+   * 발전 정격(kW) — **교류 쪽 최대 출력**. 계통으로 나가는 값이다.
+   *
+   * 이용률의 분모가 이 값이다(만든 양 ÷ 정격 × 시간). **직류 쪽 정격(§`genRatedKWdc`)과 다르고 더 작다** —
+   * 두 값을 한 이름에 담으면 이용률이 그 차이만큼 틀리고, 틀린 이유가 아무 데도 표시되지 않는다.
+   *
+   * 설비마다 선언하거나, 설비별 값을 모르는 현장은 **자리(수전)에 합계로** 선언한다.
+   */
   genRatedKW: "generation.ratedKW",
+  /**
+   * 발전 정격(kW) — **직류 쪽**. 변환기(인버터)의 입력 쪽 정격이고, 태양광이면 패널 정격의 합이다.
+   *
+   * 이용률의 분모로 쓰지 않는다. 이 값이 교류 정격보다 큰 것은 설계이고(변환기를 그렇게 고른다),
+   * 그 차이가 「맑은 정오에도 교류 출력이 더 오르지 않는 이유」를 설명한다.
+   */
+  genRatedKWdc: "generation.ratedKWdc",
   /**
    * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
    *
@@ -7599,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."
@@ -8760,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 ?? []) {
@@ -9910,6 +9972,7 @@ 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.7.76",
+  "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": {