@operato/twin-kernel 0.7.21 → 0.7.22

package/dist/ems-kernel.d.ts

@@ -140,6 +140,16 @@ export declare class EmsKernel extends FlowEngine {
      * ④ 미러 트윈에서는 아무것도 만들지 않는다 — 관측 구동은 잰 것만 쓴다.
      */
     private deriveLoad;
+    /**
+     * 선언된 발전을 만든다 — **형상은 현장이 적는다.**
+     *
+     * 정격(`generation.ratedKW`)과 하루 형상(`generation.dailyProfile`)을 **둘 다** 선언한 설비만 발전한다:
+     * 하루 종일 정격으로 발전하는 태양광은 없으므로, 정격만 있는 선언으로 발전을 만들면 그 값은 거짓이다.
+     *
+     * 값은 **만든 것**이라고 사실에 밝힌다(`derived: true`) — 저널을 읽는 쪽이 계측과 구별할 수 있어야 한다.
+     * 시각은 현장 시간대로 읽는다(모델이 시간대를 말해 준다 — 교대 판정과 같은 기준).
+     */
+    private deriveGeneration;
     /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
     private hasDispatchPolicy;
     /**
@@ -163,6 +173,8 @@ export declare class EmsKernel extends FlowEngine {
     private emitEnergyEquipment;
     /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
     private numberProperty;
+    /** 글자로 선언된 값(발전 형상·통화 같은 것) — 비어 있으면 없는 것으로 본다. */
+    private stringProperty;
     tick(dtMs: number): void;
     getSnapshot(): StateSnapshot;
 }

package/dist/ems-kernel.js

@@ -27,8 +27,8 @@
  */
 import { FlowEngine } from "./flow-engine.js";
 import { firstFitPolicy } from "./allocation-policy.js";
-import { ENERGY_EVENT } from "./contract.js";
-import { EMS_PROPERTY, electricalUpstreamOf } from "./ems-profile.js";
+import { ENERGY_EVENT, minuteOfDayAt } from "./contract.js";
+import { EMS_PROPERTY, electricalUpstreamOf, generationFractionAt } from "./ems-profile.js";
 /** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
 export const DEMAND_WINDOW_MS = 15 * 60 * 1000;
 /** 그 시각이 속한 구간의 시작 — 벽시계 경계(00·15·30·45분)에 맞춘다. */
@@ -555,6 +555,14 @@ export class EmsKernel extends FlowEngine {
          * 음수는 **역송**이지 음의 수요가 아니다. 계통 수요는 0 에서 멈추고, 남는 발전은 그 설비의
          * `exportKW` 가 이미 사실로 말한다(여기서 다시 만들지 않는다).
          */
+        /*
+         * ── 선언된 발전을 먼저 만든다 (2026-08-18) ─────────────────────────────────
+         * 정격과 하루 형상을 선언한 설비는 이 시각의 비율만큼 발전한다. 형상을 우리가 지어내지 않으므로
+         * (위도·날씨로 곡선을 만들면 그 수의 출처를 설명할 수 없다) 선언이 없으면 발전하지 않는다.
+         *
+         * 미러에서는 여기까지 오지 않는다(위에서 관측이 진실이라 돌아간다) — 계측이 발전량을 말해 준다.
+         */
+        this.deriveGeneration(atMs);
         let generated = 0;
         let discharged = 0;
         let charged = 0;
@@ -604,6 +612,43 @@ export class EmsKernel extends FlowEngine {
         this.revision++;
         this.judgeOpenWindow(atMs);
     }
+    /**
+     * 선언된 발전을 만든다 — **형상은 현장이 적는다.**
+     *
+     * 정격(`generation.ratedKW`)과 하루 형상(`generation.dailyProfile`)을 **둘 다** 선언한 설비만 발전한다:
+     * 하루 종일 정격으로 발전하는 태양광은 없으므로, 정격만 있는 선언으로 발전을 만들면 그 값은 거짓이다.
+     *
+     * 값은 **만든 것**이라고 사실에 밝힌다(`derived: true`) — 저널을 읽는 쪽이 계측과 구별할 수 있어야 한다.
+     * 시각은 현장 시간대로 읽는다(모델이 시간대를 말해 준다 — 교대 판정과 같은 기준).
+     */
+    deriveGeneration(atMs) {
+        for (const e of this.boardDef?.equipment ?? []) {
+            const rated = this.numberProperty(e, EMS_PROPERTY.genRatedKW);
+            if (rated === undefined || !(rated > 0))
+                continue;
+            const profile = this.stringProperty(e, EMS_PROPERTY.genDailyProfile);
+            const hour = Math.floor(minuteOfDayAt(atMs, this.boardDef?.utcOffsetMinutes) / 60);
+            const fraction = generationFractionAt(profile, hour);
+            const state = this.equipment.get(e.id);
+            if (!state)
+                continue;
+            if (fraction === undefined) {
+                /* 형상이 없거나 형태가 아니면 발전하지 않는다 — 낡은 값을 남기지 않는다(지난 시각을 말하게 된다). */
+                if (Number(state.generatedKW) > 0) {
+                    ;
+                    state.generatedKW = 0;
+                    this.emitEnergyEquipment(e.id, atMs, { generatedKW: 0 });
+                }
+                continue;
+            }
+            const kW = rated * fraction;
+            const before = Number(state.generatedKW);
+            state.generatedKW = kW;
+            /* 값이 실제로 바뀔 때만 사실을 낸다 — 매 틱 같은 값을 되풀면 저널이 소음으로 찬다. */
+            if (!(Number.isFinite(before) && Math.abs(before - kW) < 1e-9))
+                this.emitEnergyEquipment(e.id, atMs, { generatedKW: kW });
+        }
+    }
     /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
     hasDispatchPolicy(equipmentId) {
         for (const e of this.boardDef?.equipment ?? []) {
@@ -709,6 +754,17 @@ export class EmsKernel extends FlowEngine {
         }
         return undefined;
     }
+    /** 글자로 선언된 값(발전 형상·통화 같은 것) — 비어 있으면 없는 것으로 본다. */
+    stringProperty(resource, id) {
+        for (const p of resource?.properties ?? []) {
+            if (p?.id !== id)
+                continue;
+            const v = String(p.value ?? '').trim();
+            if (v)
+                return v;
+        }
+        return undefined;
+    }
     tick(dtMs) {
         super.tick(dtMs);
         /*

package/dist/ems-profile.d.ts

@@ -40,6 +40,14 @@ export declare const EMS_PROPERTY: {
      * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
      */
     readonly initialSoc: "storage.initialSoc";
+    /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+    readonly genRatedKW: "generation.ratedKW";
+    /**
+     * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
+     *
+     * 예: `0,0,0,0,0,0,0.05,0.2,0.45,0.7,0.9,1,1,0.95,0.8,0.6,0.35,0.12,0.02,0,0,0,0,0`
+     */
+    readonly genDailyProfile: "generation.dailyProfile";
 };
 /**
  * 이 선언들의 **단위와 범위** — 값을 읽는 쪽이 아니라 **주는 쪽**을 위한 표다.
@@ -66,6 +74,13 @@ export interface EmsPropertySpec {
     note: string;
 }
 export declare const EMS_PROPERTY_SPEC: Record<string, EmsPropertySpec>;
+/**
+ * 하루 형상에서 **이 시각의 비율**을 읽는다 — 없거나 형태가 아니면 `undefined`(발전하지 않는다).
+ *
+ * 24개가 아니면 받지 않는다: 값이 몇 개인지 짐작해 늘리거나 자르면, 사람이 적은 곡선과 우리가 쓰는 곡선이
+ * 달라진다. 0~1 밖의 값도 받지 않는다(정격의 배수로 발전하는 태양광은 없다).
+ */
+export declare function generationFractionAt(profile: string | undefined | null, hourOfDay: number): number | undefined;
 export declare const EMS_TYPES: TwinTypeInfo[];
 /**
  * 이 자리의 **전기 상류** — 어디서 전기를 받는가.

package/dist/ems-profile.js

@@ -71,7 +71,28 @@ export const EMS_PROPERTY = {
      *
      * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
      */
-    initialSoc: 'storage.initialSoc'
+    initialSoc: 'storage.initialSoc',
+    /*
+     * ── 발전 — 태양광이 서 있기만 하던 자리 (2026-08-18) ────────────────────────
+     *
+     * 계통도에 태양광을 그려 놓고 시뮬에서는 한 톨도 만들지 못했다. 미러는 원천이 발전량을 보내 주지만,
+     * 시뮬 트윈에는 그것을 만들 근거가 없었다 — 그래서 「태양광을 늘리면 피크가 얼마나 내려가나」를 물을 수
+     * 없었다(what-if 의 값이 절반만 성립했다).
+     *
+     * **형상을 우리가 지어내지 않는다.** 위도·계절·날씨로 곡선을 만들면 그 수가 어디서 왔는지 아무도
+     * 설명할 수 없고, 흐린 날 현장의 실적과 어긋난다. 그래서 현장이 **하루 형상을 적는다**: 24개 비율
+     * (0~1)이면 그것이 그 현장의 곡선이다(측정한 형상을 그대로 붙일 수 있다).
+     *
+     * 정격만 있고 형상이 없으면 발전하지 않는다 — 하루 종일 정격으로 발전하는 태양광은 없다.
+     */
+    /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+    genRatedKW: 'generation.ratedKW',
+    /**
+     * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
+     *
+     * 예: `0,0,0,0,0,0,0.05,0.2,0.45,0.7,0.9,1,1,0.95,0.8,0.6,0.35,0.12,0.02,0,0,0,0,0`
+     */
+    genDailyProfile: 'generation.dailyProfile'
 };
 export const EMS_PROPERTY_SPEC = {
     [EMS_PROPERTY.contractKW]: { uom: 'kW', dataType: 'xs:double', note: 'contracted power at the metering point, in kW.' },
@@ -85,8 +106,34 @@ export const EMS_PROPERTY_SPEC = {
     [EMS_PROPERTY.maxDischargeKW]: { uom: 'kW', dataType: 'xs:double', note: 'inverter limit on discharge rate, in kW.' },
     /* 퍼센트다 — 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.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.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.'
+    }
 };
+/**
+ * 하루 형상에서 **이 시각의 비율**을 읽는다 — 없거나 형태가 아니면 `undefined`(발전하지 않는다).
+ *
+ * 24개가 아니면 받지 않는다: 값이 몇 개인지 짐작해 늘리거나 자르면, 사람이 적은 곡선과 우리가 쓰는 곡선이
+ * 달라진다. 0~1 밖의 값도 받지 않는다(정격의 배수로 발전하는 태양광은 없다).
+ */
+export function generationFractionAt(profile, hourOfDay) {
+    const parts = String(profile ?? '')
+        .split(',')
+        .map(v => v.trim())
+        .filter(v => v !== '');
+    if (parts.length !== 24)
+        return undefined;
+    const h = Math.floor(hourOfDay);
+    if (!Number.isFinite(h) || h < 0 || h > 23)
+        return undefined;
+    const v = Number(parts[h]);
+    if (!Number.isFinite(v) || v < 0 || v > 1)
+        return undefined;
+    return v;
+}
 export const EMS_TYPES = [
     /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
     {

package/dist-cjs/index.cjs

@@ -106,6 +106,7 @@ __export(index_exports, {
   foldJobResponses: () => foldJobResponses,
   foldTaskRecords: () => foldTaskRecords,
   gdtiUri: () => gdtiUri,
+  generationFractionAt: () => generationFractionAt,
   graiUri: () => graiUri,
   hierarchyOf: () => hierarchyOf,
   inWorkCalendar: () => inWorkCalendar,
@@ -1757,7 +1758,28 @@ var EMS_PROPERTY = {
    *
    * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
    */
-  initialSoc: "storage.initialSoc"
+  initialSoc: "storage.initialSoc",
+  /*
+   * ── 발전 — 태양광이 서 있기만 하던 자리 (2026-08-18) ────────────────────────
+   *
+   * 계통도에 태양광을 그려 놓고 시뮬에서는 한 톨도 만들지 못했다. 미러는 원천이 발전량을 보내 주지만,
+   * 시뮬 트윈에는 그것을 만들 근거가 없었다 — 그래서 「태양광을 늘리면 피크가 얼마나 내려가나」를 물을 수
+   * 없었다(what-if 의 값이 절반만 성립했다).
+   *
+   * **형상을 우리가 지어내지 않는다.** 위도·계절·날씨로 곡선을 만들면 그 수가 어디서 왔는지 아무도
+   * 설명할 수 없고, 흐린 날 현장의 실적과 어긋난다. 그래서 현장이 **하루 형상을 적는다**: 24개 비율
+   * (0~1)이면 그것이 그 현장의 곡선이다(측정한 형상을 그대로 붙일 수 있다).
+   *
+   * 정격만 있고 형상이 없으면 발전하지 않는다 — 하루 종일 정격으로 발전하는 태양광은 없다.
+   */
+  /** 발전 정격(kW) — 맑은 정오의 최대 출력. */
+  genRatedKW: "generation.ratedKW",
+  /**
+   * 하루 형상 — 쉼표로 나눈 **24개 비율**(0~1). 시각(현장 시간대)의 정격 대비 출력이다.
+   *
+   * 예: `0,0,0,0,0,0,0.05,0.2,0.45,0.7,0.9,1,1,0.95,0.8,0.6,0.35,0.12,0.02,0,0,0,0,0`
+   */
+  genDailyProfile: "generation.dailyProfile"
 };
 var EMS_PROPERTY_SPEC = {
   [EMS_PROPERTY.contractKW]: { uom: "kW", dataType: "xs:double", note: "contracted power at the metering point, in kW." },
@@ -1771,8 +1793,22 @@ var EMS_PROPERTY_SPEC = {
   [EMS_PROPERTY.maxDischargeKW]: { uom: "kW", dataType: "xs:double", note: "inverter limit on discharge rate, in kW." },
   /* 퍼센트다 — 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.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.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."
+  }
 };
+function generationFractionAt(profile, hourOfDay) {
+  const parts = String(profile ?? "").split(",").map((v2) => v2.trim()).filter((v2) => v2 !== "");
+  if (parts.length !== 24) return void 0;
+  const h = Math.floor(hourOfDay);
+  if (!Number.isFinite(h) || h < 0 || h > 23) return void 0;
+  const v = Number(parts[h]);
+  if (!Number.isFinite(v) || v < 0 || v > 1) return void 0;
+  return v;
+}
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
   {
@@ -6383,6 +6419,7 @@ var EmsKernel = class extends FlowEngine {
       }
     }
     if (!counted) return;
+    this.deriveGeneration(atMs);
     let generated = 0;
     let discharged = 0;
     let charged = 0;
@@ -6409,6 +6446,38 @@ var EmsKernel = class extends FlowEngine {
     this.revision++;
     this.judgeOpenWindow(atMs);
   }
+  /**
+   * 선언된 발전을 만든다 — **형상은 현장이 적는다.**
+   *
+   * 정격(`generation.ratedKW`)과 하루 형상(`generation.dailyProfile`)을 **둘 다** 선언한 설비만 발전한다:
+   * 하루 종일 정격으로 발전하는 태양광은 없으므로, 정격만 있는 선언으로 발전을 만들면 그 값은 거짓이다.
+   *
+   * 값은 **만든 것**이라고 사실에 밝힌다(`derived: true`) — 저널을 읽는 쪽이 계측과 구별할 수 있어야 한다.
+   * 시각은 현장 시간대로 읽는다(모델이 시간대를 말해 준다 — 교대 판정과 같은 기준).
+   */
+  deriveGeneration(atMs) {
+    for (const e of this.boardDef?.equipment ?? []) {
+      const rated = this.numberProperty(e, EMS_PROPERTY.genRatedKW);
+      if (rated === void 0 || !(rated > 0)) continue;
+      const profile = this.stringProperty(e, EMS_PROPERTY.genDailyProfile);
+      const hour = Math.floor(minuteOfDayAt(atMs, this.boardDef?.utcOffsetMinutes) / 60);
+      const fraction = generationFractionAt(profile, hour);
+      const state = this.equipment.get(e.id);
+      if (!state) continue;
+      if (fraction === void 0) {
+        if (Number(state.generatedKW) > 0) {
+          ;
+          state.generatedKW = 0;
+          this.emitEnergyEquipment(e.id, atMs, { generatedKW: 0 });
+        }
+        continue;
+      }
+      const kW = rated * fraction;
+      const before = Number(state.generatedKW);
+      state.generatedKW = kW;
+      if (!(Number.isFinite(before) && Math.abs(before - kW) < 1e-9)) this.emitEnergyEquipment(e.id, atMs, { generatedKW: kW });
+    }
+  }
   /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
   hasDispatchPolicy(equipmentId) {
     for (const e of this.boardDef?.equipment ?? []) {
@@ -6492,6 +6561,15 @@ var EmsKernel = class extends FlowEngine {
     }
     return void 0;
   }
+  /** 글자로 선언된 값(발전 형상·통화 같은 것) — 비어 있으면 없는 것으로 본다. */
+  stringProperty(resource, id) {
+    for (const p of resource?.properties ?? []) {
+      if (p?.id !== id) continue;
+      const v = String(p.value ?? "").trim();
+      if (v) return v;
+    }
+    return void 0;
+  }
   tick(dtMs) {
     super.tick(dtMs);
     const at = this.nowMs();
@@ -6974,6 +7052,7 @@ function retiredVocabularyIn(line) {
   foldJobResponses,
   foldTaskRecords,
   gdtiUri,
+  generationFractionAt,
   graiUri,
   hierarchyOf,
   inWorkCalendar,

package/package.json

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