@operato/twin-kernel 0.7.68 → 0.7.70

package/dist/capability.d.ts

@@ -53,6 +53,19 @@ export interface GeneratingState {
     exportKW?: number;
     generatedKWh?: number;
     generatedKWhResetAt?: string;
+    /** 지금 든 적산이 무엇부터 쌓인 것인가 — 원본이 말했을 때만 있다. */
+    generatedKWhSince?: string;
+    /** 되돌아간 판정이 사실인가 짐작인가 — 'declared' 또는 'inferred'. */
+    generatedKWhBasis?: 'declared' | 'inferred';
+    /** 어떤 누적인가 — 원본이 말하지 않으면 'unknown' 이다(칸이 비지 않는다). */
+    generatedKWhAccumulation?: 'lifetime' | 'daily' | 'monthly' | 'billing' | 'unknown';
+    /** 끝난 기간의 발전량(kWh) — 성과지표가 기간당 에너지로 정의된다. */
+    generatedKWhLastPeriod?: number;
+    /** 그 기간이 끝난 시각. */
+    generatedKWhLastPeriodEnd?: string;
+    /** 그 기간에서 처음·마지막으로 관측한 시각 — 기간 경계와 다르면 그만큼 재지 않았다. */
+    generatedKWhLastPeriodObservedFrom?: string;
+    generatedKWhLastPeriodObservedTo?: string;
 }
 /** 저장 — 담고 낸다. 충전과 방전을 나눈다(손실·수명 판단이 둘을 구별해야 한다). */
 export interface StoringState {

package/dist/capability.js

@@ -86,7 +86,7 @@ export const CAPABILITIES = {
          * 계량 능력(`metered`)이 `kW` 와 `kWh` 를 함께 선언한 것과 같은 짝이다. 적산은 발전 설비의 보편적
          * 사실이고(태양광·열병합·디젤), 그것이 없으면 성능비·발전시간 같은 성과를 아무도 셀 수 없다.
          */
-        stateFields: ['generatedKW', 'exportKW', 'generatedKWh', 'generatedKWhResetAt'], models: ['GeneratingState'], results: ['generated']
+        stateFields: ['generatedKW', 'exportKW', 'generatedKWh', 'generatedKWhResetAt', 'generatedKWhSince', 'generatedKWhBasis', 'generatedKWhAccumulation', 'generatedKWhLastPeriod', 'generatedKWhLastPeriodEnd', 'generatedKWhLastPeriodObservedFrom', 'generatedKWhLastPeriodObservedTo'], models: ['GeneratingState'], results: ['generated']
     },
     /*
      * ── 왜 `storing` 이 아니라 `energyStoring` 인가 (2026-08-15) ────────────────

package/dist/contract.d.ts

@@ -930,6 +930,16 @@ export interface WorkCalendarEntry {
 }
 /** 선언된 기준의 요일(0 일요일 … 6 토요일). */
 export declare function weekdayAt(ms: number, utcOffsetMinutes?: number): number;
+/**
+ * 선언된 기준으로 **며칠째인가** — 하루 단위 셈의 경계를 정하는 데 쓴다(기간 발전량 등).
+ *
+ * 요일·분과 같은 규칙이다: 선언된 오프셋을 더한 뒤 UTC 로 읽는다. 선언이 없으면 UTC 의 하루다.
+ * 고정 오프셋이므로 일광절약시간을 쓰는 현장에서는 계절에 따라 한 시간 어긋난다 — 그 현장이 생기면
+ * 오프셋이 아니라 지역 이름(`TwinSpace.timezone`)을 커널까지 내려야 한다.
+ */
+export declare function localDayIndexAt(ms: number, utcOffsetMinutes?: number): number;
+/** 그 날의 시작(UTC ms) — `localDayIndexAt` 의 역함수. */
+export declare function localDayStartMs(dayIndex: number, utcOffsetMinutes?: number): number;
 export declare function inWorkCalendar(entries: readonly WorkCalendarEntry[] | undefined, minuteOfDay: number): boolean;
 /**
  * 이 **시각**이 근무 시간인가 — 되풀이(`HH:MM`)와 **한 번뿐인 구간**(휴일·정비창)을 함께 본다.
@@ -1378,6 +1388,62 @@ export interface EquipmentState extends EffectivePeriod {
      * 되돌아간 적이 없으면 이 칸이 없다.
      */
     generatedKWhResetAt?: ISOTime;
+    /**
+     * 지금 든 적산이 **무엇부터 쌓인 것인가** — 원본이 말했을 때만 있다 (2026-08-28).
+     *
+     * 이 값이 있으면 차분을 구하는 쪽이 구간을 안다. 그리고 값이 줄었을 때 그것이 계기의 이상인지
+     * (기준점 그대로) 구간이 새로 시작한 것인지(기준점이 나아갔다) 갈릴 수 있다.
+     */
+    generatedKWhSince?: ISOTime;
+    /**
+     * `generatedKWhResetAt` 이 **사실인가 짐작인가**.
+     *
+     *   'declared'  기준점을 받았고 그것이 그대로인데 값이 줄었다 — 계기의 이상이다
+     *   'inferred'  기준점을 받지 못했고 값이 줄었다 — 계기 교체인지 구간 경계인지 **모른다**
+     *
+     * 예전에는 둘을 구별하지 않고 언제나 「되돌아갔다」로 적었다. 그러면 하루 누적을 주는 원본에서 매일
+     * 자정이 계기 교체로 보인다. 짐작을 사실처럼 적지 않기 위한 칸이다.
+     */
+    generatedKWhBasis?: 'declared' | 'inferred';
+    /**
+     * 지금 든 적산이 **어떤 누적인가** — 원본이 말하지 않으면 `'unknown'` 이다(칸이 비지 않는다).
+     *
+     * 「모른다」를 값으로 두는 이유: 이 칸이 비어 있으면 소비처가 그 수를 평생치로 읽는다. 그러면 하루치를
+     * 주는 발전소의 「지금까지 낸 양」이 오늘치가 되고, 아무도 그것을 알아채지 못한다.
+     */
+    generatedKWhAccumulation?: 'lifetime' | 'daily' | 'monthly' | 'billing' | 'unknown';
+    /**
+     * **끝난 기간의 발전량**(kWh) — 가장 최근에 마감된 한 기간의 총량.
+     *
+     * ── 왜 이 칸이 필요한가 (2026-08-28) ──────────────────────────────────────
+     * ISO 50001 의 성과지표(EnPI)와 기준선은 「기간당 에너지」로 정의된다. 태양광 성능비도 분자가 기간
+     * 발전량이다. 적산값 하나만 두면 그 어느 것도 계산할 수 없다.
+     *
+     * 기간의 경계는 **둘 중 하나에서** 온다. 어느 쪽이었는지 사건에 적는다(§`EnergyGenerationPeriodData`).
+     *
+     *   원본의 선언   `generatedKWhSince` 가 나아갔다 — 그 시각이 곧 앞 기간의 끝이다
+     *   현장의 선언   `TwinModelDef.utcOffsetMinutes` 로 정한 그 지역의 자정
+     *
+     * 커널이 시간대를 짐작하는 일은 없다. 선언이 없으면 UTC 로 읽고, 그것이 선언되지 않았다는 사실은
+     * 트윈 정의에 남는다(§`utcOffsetMinutes`).
+     *
+     * 총량은 계산이 아니라 관측이다 — 하루치를 주는 원본은 마지막으로 본 값 그대로이고, 평생 적산을 주는
+     * 원본은 그날 처음 본 값과의 차이다. 관측이 미치지 못한 구간은 사건이 시각으로 밝힌다.
+     *
+     * 같은 값이 사건으로도 나간다(`ENERGY_EVENT.generationPeriod`). 상태에만 두면 지난 기간들을 합할 수
+     * 없다.
+     */
+    generatedKWhLastPeriod?: number;
+    /** 그 기간이 끝난 시각. 원본이 새 기준점을 말했으면 그 시각이고, 아니면 되돌아감을 본 시각이다. */
+    generatedKWhLastPeriodEnd?: ISOTime;
+    /**
+     * 그 기간에서 **처음·마지막으로 관측한 시각** — 기간의 경계와 다르면 그만큼 재지 않았다.
+     *
+     * 이 둘이 없으면 상태만 읽는 화면이 덜 잰 값을 온전한 값으로 읽는다. 얼마나 어긋나면 문제인지는
+     * 현장이 정할 일이므로 커널이 판정하지 않고 시각을 그대로 낸다(판정을 두 벌 만들지 않는다).
+     */
+    generatedKWhLastPeriodObservedFrom?: ISOTime;
+    generatedKWhLastPeriodObservedTo?: ISOTime;
     /** storing — 충전율(%)·충전·방전(kW). 충전과 방전을 나눈다(손실·수명 판단이 그 둘을 구별한다). */
     soc?: number;
     chargeKW?: number;
@@ -1943,6 +2009,33 @@ export interface EnergyState {
         hook: string;
         count: number;
     }[];
+    /**
+     * 설비마다 **지금 기간의 발전 관측** — 기간 발전량을 확정할 때 쓰는 기준점.
+     *
+     * 계량 지점이 `kWhAtWindowStart` 를 상태에 두는 것과 같은 이유다: 재기동에서 이것이 없으면 그날의
+     * 발전량이 부팅 이후로만 잡히고, **적게 잡힌 것이 드러나지 않는다.**
+     */
+    generationPeriods?: GenerationPeriodObservation[];
+    /**
+     * **마감하지 못한 기간 누적**의 수 — 월·요금기간 종류인데 원본이 기준점(`kWhSince`)을 말하지 않으면
+     * 커널은 그 기간이 언제 끝나는지 알 수 없다(자정으로는 끝나지 않는다).
+     *
+     * 세어 두는 이유: 세지 않으면 그 발전소의 발전량이 아무 표시 없이 영원히 나오지 않는다. 0 이면 이
+     * 칸을 만들지 않는다.
+     */
+    unclosedGenerationPeriods?: number;
+}
+/** 지금 기간의 발전 관측 — 기간 발전량은 이 기준점과 마지막 관측의 관계로 정해진다. */
+export interface GenerationPeriodObservation {
+    equipmentId: string;
+    /** 선언된 시각 기준의 며칠째인가(§`localDayIndexAt`). */
+    dayIndex: number;
+    /** 이 기간에서 처음 본 적산과 그 시각 — 평생 적산의 기준점이다. */
+    fromKWh: number;
+    fromMs: number;
+    /** 이 기간에서 마지막으로 본 적산과 그 시각 — 하루 누적은 이것이 곧 총량이다. */
+    lastKWh: number;
+    lastMs: number;
 }
 /**
  * 조치방향 — code=안정 조치 키(언어 중립). command 있으면 원클릭 실행, 없으면 권고.
@@ -2343,6 +2436,16 @@ export declare const ENERGY_EVENT: {
     readonly tariffShift: "energy.tariff.shift";
     /** 발전(PV 등) — 역송을 포함한다(음의 소비가 아니라 별개 사실이다). */
     readonly generated: "energy.generated";
+    /**
+     * **기간 발전량 확정** — 한 기간이 끝났고 그 기간에 얼마 냈는지가 정해졌다.
+     *
+     * ISO 50001 의 성과지표와 기준선, 태양광 성능비가 모두 「기간당 에너지」로 정의된다. 적산값만 상태에
+     * 두면 그 어느 것도 계산할 수 없고, 지난 기간들을 합할 수도 없다(상태는 지금 하나만 든다).
+     *
+     * 계량이 수요 구간을 마감해 사실로 내는 것과 같은 짝이다(§`demandWindow`). 두 값을 더하지 말 것 —
+     * 발전량은 설비가 만든 양이고 구간 전력량은 계량 지점을 지난 양이다.
+     */
+    readonly generationPeriod: "energy.generation.period";
     /** 저장(ESS 충전). */
     readonly stored: "energy.stored";
     /** 방전(ESS). 충전과 나눈다 — 손실·수명 판단이 둘을 구별해야 한다. */
@@ -2405,6 +2508,63 @@ export interface EnergyGeneratedData {
      * 다르며 다를 때 맞는 쪽은 계기다(계량 쪽과 같은 규율).
      */
     kWh: number;
+    /**
+     * **이 적산이 쌓이기 시작한 시각** — 원본이 말했을 때만 있다 (2026-08-28).
+     *
+     * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+     * 계기가 주는 적산이 어느 구간의 것인지는 **원본마다 다르다** — 설치 이후·하루·한 달·요금기간.
+     * 표준도 그것을 갈라 둔다(계측값에 구간을 붙인다). 그런데 이 문은 한 뜻만 가정하고 있었다:
+     * 단조 증가하는 총적산. 그래서 값이 줄면 **계기 교체로 추론했다.**
+     *
+     * 하루 누적을 주는 원본에서는 그 추론이 매일 자정마다 참이 된다 — 실측(PPMS 인버터):
+     *
+     *   2026-08-25 23:37 KST   acc 574.8
+     *   2026-08-28 18:25 KST   acc 165.2      ← 줄었다. 자정에 되돌아간다
+     *
+     * 그대로 받으면 「계기 교체가 하루에 한 번 일어난다」가 기록된다.
+     *
+     * ── 왜 시각인가(구간의 이름이 아니라) ───────────────────────────────────────
+     * 한 축으로 하루·한 달·요금기간·설치 이후를 다 담고, 커널이 구간을 이어 붙일 근거도 그 시각이다.
+     * 「요금기간」 같은 이름은 경계를 계약이 정하므로 이름만으로는 커널이 알 수 없다.
+     *
+     * **없으면 「모른다」다** — 설치 이후로 가정하지 않는다. 그때 커널은 지금처럼 추론하고, 그 추론이
+     * 짐작이라는 사실을 상태에 남긴다(§`generatedKWhBasis`).
+     */
+    since?: ISOTime;
+    /**
+     * **어떤 누적인가** — 표준이 값의 형에 두는 축이다 (2026-08-28).
+     *
+     * ── 왜 구간의 시작만으로 부족한가 ───────────────────────────────────────────
+     * 처음에는 `since`(구간의 시작) 하나만 두었다. 그러면 **원본이 그것을 모를 때 아무 표도 남지 않는다** —
+     * 소비처는 `574.8` 만 보고 그것이 하루치인지 평생치인지 알 방법이 없다. 되돌아가야 비로소 「모른다」가
+     * 남는데(§`generatedKWhBasis`), 그전까지는 그 값을 다른 값과 비교해도 아무도 막지 않는다.
+     *
+     * 이 트윈의 규율은 **모르는 것을 모른다고 말하는 것**이다. 그래서 모름도 값으로 둔다.
+     *
+     * ── 이 축의 근거 ────────────────────────────────────────────────────────────
+     * **표준이 강제해서 두는 축이 아니다.** 근거는 위 문단 하나로 끝난다 — 기준점을 모르는 값을 받으면
+     * 커널이 추론하고, 추론한 것이 사실로 적힌다. 종류와 구간은 겹치지 않는 물음에 답한다: 종류는
+     * 「견줄 수 있나」, 시각은 「어느 구간인가」.
+     *
+     * 곁근거로 IEC 61968-9 의 `ReadingType` 이 계측값의 성질을 여러 축으로 나눈다고 알고 있다(누적 방식·
+     * 거시 구간·방향). **다만 그 문서를 읽지 않았다** — 유료 표준이고 이 저장소에 사본이 없다. 축 이름은
+     * 기억이므로 이 주석을 근거로 인용하지 말 것. 커널이 **채택 선언한** 에너지 표준은 IEC 61850(설비·
+     * 계측 모델)과 ISO 50001(경영)이다(§`StandardClass`).
+     *
+     * 어느 표준도 「적산은 평생치다」라고 말하지 않는다. 그 전제는 커널의 판정에 있었다 —
+     * 값이 줄면 계기의 이상으로 읽는 것(§`generatedKWhResetAt`). 그것이 매일 자정을 계기 교체로
+     * 적게 만든 자리다.
+     *
+     *   'lifetime'  설치 이후 — 단조 증가한다. 줄면 계기의 이상이다
+     *   'daily'     그날부터
+     *   'monthly'   그달부터
+     *   'billing'   요금기간부터 — 경계는 계약이 정하므로 시각을 함께 받아야 구간이 정해진다
+     *   'unknown'   **원본이 말하지 않는다.** 이 값을 다른 값과 비교하지 말라는 뜻이다
+     *
+     * 없으면(칸이 아예 없으면) 커널은 `'unknown'` 으로 둔다 — 예전 판이 보내던 레코드가 조용히 평생치로
+     * 읽히지 않게.
+     */
+    accumulation?: 'lifetime' | 'daily' | 'monthly' | 'billing' | 'unknown';
     at: ISOTime;
 }
 /** 계량 도착의 실린 값 — 계량 지점 하나의 한 시점. */
@@ -2415,11 +2575,40 @@ export interface EnergyMeasuredData {
     kW: number;
     /** 누적 전력량(kWh) — 계기 누적값. 차분은 소비처가 한다(계기 교체·리셋을 우리가 지어내지 않는다). */
     kWh?: number;
+    /**
+     * 이 적산이 쌓이기 시작한 시각 — 원본이 말했을 때만 있다(§`EnergyGeneratedData.since`).
+     *
+     * 계량 쪽의 셈은 이 값 없이도 정직하다 — 적산이 줄면 그 구간의 전력량을 **내지 않는다**(음수를
+     * 만들지 않는다). 이 축은 셈을 바꾸지 않고 **왜 비는지**를 말할 수 있게 한다: 「계기가 교체돼서」와
+     * 「구간이 바뀌어서」는 다른 사실이고, 화면이 그 둘을 같은 빈칸으로 보이면 사람이 계기를 의심한다.
+     */
+    kWhSince?: ISOTime;
     /** 역률 — 없으면 모르는 것이다(1 로 채우지 않는다). */
     powerFactor?: number;
     at: ISOTime;
 }
 /** 수요 구간 마감 — 계약 대비 판정의 단위. */
+/**
+ * 기간 발전량 확정 — `ENERGY_EVENT.generationPeriod` 의 데이터.
+ *
+ * 관측 구간을 함께 싣는 이유: 기간의 끝이 자정인데 마지막 표본이 저녁 여덟 시였다면, 그 사이는 재지
+ * 않은 것이다. 태양광이면 대개 0 이지만 그것은 현장이 판단할 일이고, 재지 않은 것을 0 으로 적으면
+ * 우리가 그 판단을 대신한 것이 된다.
+ */
+export interface EnergyGenerationPeriodData {
+    equipmentId: string;
+    /** 이 기간에 만든 양(kWh). */
+    kWh: number;
+    periodStart: ISOTime;
+    periodEnd: ISOTime;
+    /** 이 기간에서 처음·마지막으로 관측한 시각. 기간 경계와 다르면 그만큼 재지 않았다. */
+    observedFrom: ISOTime;
+    observedTo: ISOTime;
+    /** 원본이 준 적산의 종류 — 총량을 어떻게 얻었는지가 이것으로 갈린다. */
+    accumulation: 'lifetime' | 'daily' | 'monthly' | 'billing';
+    /** 기간의 경계가 어디서 왔나 — 원본의 기준점(`declared`)이거나 현장의 시각 기준(`offset`). */
+    boundary: 'declared' | 'offset';
+}
 export interface EnergyDemandWindowData {
     /** 배전 구간(로케이션 id) 또는 현장 전체. */
     feederId?: string;

package/dist/contract.js

@@ -642,6 +642,20 @@ function onDeclaredDay(e, minuteOfDay, weekday) {
 export function weekdayAt(ms, utcOffsetMinutes) {
     return new Date(ms + (utcOffsetMinutes ?? 0) * 60_000).getUTCDay();
 }
+/**
+ * 선언된 기준으로 **며칠째인가** — 하루 단위 셈의 경계를 정하는 데 쓴다(기간 발전량 등).
+ *
+ * 요일·분과 같은 규칙이다: 선언된 오프셋을 더한 뒤 UTC 로 읽는다. 선언이 없으면 UTC 의 하루다.
+ * 고정 오프셋이므로 일광절약시간을 쓰는 현장에서는 계절에 따라 한 시간 어긋난다 — 그 현장이 생기면
+ * 오프셋이 아니라 지역 이름(`TwinSpace.timezone`)을 커널까지 내려야 한다.
+ */
+export function localDayIndexAt(ms, utcOffsetMinutes) {
+    return Math.floor((ms + (utcOffsetMinutes ?? 0) * 60_000) / 86_400_000);
+}
+/** 그 날의 시작(UTC ms) — `localDayIndexAt` 의 역함수. */
+export function localDayStartMs(dayIndex, utcOffsetMinutes) {
+    return dayIndex * 86_400_000 - (utcOffsetMinutes ?? 0) * 60_000;
+}
 /**
  * 절대 구간이 그 시각을 덮는가 — 한쪽만 있으면 그쪽만 본다(열린 구간).
  * 깨진 시각으로는 판정하지 않는다(짐작해 고치지 않는다).
@@ -1031,6 +1045,16 @@ export const ENERGY_EVENT = {
     tariffShift: 'energy.tariff.shift',
     /** 발전(PV 등) — 역송을 포함한다(음의 소비가 아니라 별개 사실이다). */
     generated: 'energy.generated',
+    /**
+     * **기간 발전량 확정** — 한 기간이 끝났고 그 기간에 얼마 냈는지가 정해졌다.
+     *
+     * ISO 50001 의 성과지표와 기준선, 태양광 성능비가 모두 「기간당 에너지」로 정의된다. 적산값만 상태에
+     * 두면 그 어느 것도 계산할 수 없고, 지난 기간들을 합할 수도 없다(상태는 지금 하나만 든다).
+     *
+     * 계량이 수요 구간을 마감해 사실로 내는 것과 같은 짝이다(§`demandWindow`). 두 값을 더하지 말 것 —
+     * 발전량은 설비가 만든 양이고 구간 전력량은 계량 지점을 지난 양이다.
+     */
+    generationPeriod: 'energy.generation.period',
     /** 저장(ESS 충전). */
     stored: 'energy.stored',
     /** 방전(ESS). 충전과 나눈다 — 손실·수명 판단이 둘을 구별해야 한다. */

package/dist/ems-kernel.d.ts

@@ -141,8 +141,45 @@ export declare class EmsKernel extends FlowEngine {
      * 않으면 늦게 온 옛 적산이 최신 값을 뒤로 돌린다 — 그리고 그것이 「계기가 되돌아갔다」로 잘못 적힌다.
      */
     private applyGenerated;
+    /**
+     * **기간이 끝났으면 그 기간의 발전량을 사실로 낸다.**
+     *
+     * ── 없던 것 (2026-08-28) ────────────────────────────────────────────────────
+     * 적산값을 상태에 세우고 끝이었다. 그래서 「어제 얼마 냈나」·「이번 달 성능비」에 답할 자리가 없었고,
+     * 매일 자정에 값이 되돌아가는 원본에서는 그 하루의 총량이 **버려졌다** — 우리가 마지막으로 본 값이
+     * 곧 그날의 총량인데도.
+     *
+     * ISO 50001 의 성과지표와 기준선은 기간당 에너지로 정의된다(§`domain-catalog` 에너지 표준). 적산
+     * 하나로는 계산할 수 없다.
+     *
+     * ── 경계는 둘 중 하나에서 온다 ──────────────────────────────────────────────
+     *   원본의 기준점이 나아갔다     그 시각이 앞 기간의 끝이다 → boundary 'declared'
+     *   현장의 자정을 지났다         `utcOffsetMinutes` 가 정한 자정 → boundary 'offset'
+     *
+     * ── 총량을 얻는 방법이 종류마다 다르다 ──────────────────────────────────────
+     *   'daily'              마지막으로 본 값이 그대로 그날의 총량이다
+     *   'lifetime'           그날 처음 본 값과의 차이
+     *   'monthly'·'billing'  원본이 기준점을 말했을 때만 마감한다 — 자정으로는 그 기간이 끝나지 않는다
+     *   'unknown'            마감하지 않는다. 어느 기간의 값인지 모르는 수를 기간 사실로 낼 수 없다
+     *
+     * 관측 구간(`observedFrom`·`observedTo`)을 함께 낸다. 기간의 끝은 자정인데 마지막 표본이 저녁이었다면
+     * 그 사이는 재지 않은 것이고, 재지 않은 것을 0 으로 적으면 우리가 현장의 판단을 대신하는 것이 된다.
+     */
+    private closeGenerationPeriod;
+    private localDayIndex;
+    private dayStartMs;
     /** 설비마다 발전 적산을 마지막으로 들은 시각 — 늦게 온 옛 표본을 가리는 데만 쓴다. */
     private generationHeardAtMs;
+    /**
+     * 설비마다 **지금 기간의 관측** — 기간 발전량을 확정할 때 쓰는 기준점(§`closeGenerationPeriod`).
+     *
+     * **스냅샷에 낸다**(`EnergyState.generationPeriods`). 처음에는 「셈을 위한 값이니 상태에 두지 않는다」고
+     * 두었는데 그것이 틀렸다 — 재기동하면 평생 적산의 기준점이 사라지고, 그날의 발전량이 부팅 이후로만
+     * 잡힌다. 계량 지점이 `kWhAtWindowStart` 를 상태에 두는 것과 같은 이유다.
+     */
+    private generationPeriodObs;
+    /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
+    private unclosedGenerationPeriods;
     private applyEquipmentEnergy;
     /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
     private unknownEquipmentReports;

package/dist/ems-kernel.js

@@ -27,7 +27,7 @@
  */
 import { FlowEngine } from "./flow-engine.js";
 import { firstFitPolicy } from "./allocation-policy.js";
-import { CMD, ENERGY_EVENT, minuteOfDayAt } from "./contract.js";
+import { CMD, ENERGY_EVENT, minuteOfDayAt, localDayIndexAt, localDayStartMs } from "./contract.js";
 import { EMS_PROPERTY, METER_DIRECTION, electricalUpstreamOf, generationFractionAt } from "./ems-profile.js";
 /** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
 export const DEMAND_WINDOW_MS = 15 * 60 * 1000;
@@ -322,19 +322,188 @@ export class EmsKernel extends FlowEngine {
         if (heardAt !== undefined && atMs < heardAt)
             return;
         this.generationHeardAtMs.set(id, atMs);
+        /*
+         * ── 되돌아간 적산 — **세 갈래로 가른다** (2026-08-28) ───────────────────────
+         *
+         * 예전에는 갈래가 하나였다: 값이 줄면 계기 교체다. 그런데 **하루 누적을 주는 원본**에서는 그
+         * 판정이 매일 자정마다 참이 된다 — 실측(PPMS 인버터): 574.8 → 165.2, 자정에 되돌아간다.
+         * 그러면 「계기 교체가 하루에 한 번 일어난다」가 지난 기록에 남는다.
+         *
+         * 원본이 **기준점**을 말해 주면 그 추론이 필요 없어진다(§`EnergyGeneratedData.since`).
+         *
+         *   기준점 그대로 · 값이 줄었다     계기의 이상이다        → resetAt · basis 'declared'
+         *   기준점이 나아갔다               구간이 새로 시작했다    → resetAt 을 찍지 않는다
+         *   기준점이 없다 · 값이 줄었다      모른다                → resetAt · basis 'inferred'
+         *
+         * 셋째가 예전의 전부였다. 짐작을 사실처럼 적지 않기 위해 그것에 표를 남긴다.
+         */
         const before = Number(eq.generatedKWh);
-        if (Number.isFinite(before) && kWh < before) {
+        const priorSince = eq.generatedKWhSince;
+        const since = typeof d?.since === 'string' && d.since.trim() ? d.since.trim() : undefined;
+        const periodAdvanced = !!since && !!priorSince && Date.parse(since) > Date.parse(priorSince);
+        /*
+         * ── 「사실」이라 말할 수 있는 조건은 **둘을 다 아는 것**이다 (2026-08-28, 고침) ─
+         *
+         * 앞 판은 `since ? 'declared' : 'inferred'` 였다. 그래서 **기준점을 뒤늦게 알게 되는 원본**에서
+         * 첫 되돌아감이 「짐작인데 사실로」 기록됐다 — 인티그레이션 레인이 짚었다.
+         *
+         *   표본 1..N   기준점 없음
+         *   표본 N+1    기준점이 처음 왔고, 값이 줄었다
+         *               → `priorSince` 가 없으니 구간이 나아갔는지 알 수 없다
+         *               → 그런데 `since` 가 있으므로 'declared' 가 붙었다
+         *
+         * 갈래를 정확히 적는다. **같은 기준점에서 줄었을 때만** 계기의 이상이라고 말할 수 있다.
+         *
+         *   기준점 둘 다 있고 나아갔다   구간이 새로 시작했다 → 되돌아감으로 적지 않는다
+         *   기준점 둘 다 있고 같다        계기의 이상이다      → 'declared'
+         *   기준점이 뒤로 갔다            모른다              → 'inferred' (원본이 옛 기준을 다시 말했다)
+         *   기준점이 이제 처음 왔다        모른다              → 'inferred'
+         *   기준점이 없다                모른다              → 'inferred'
+         */
+        const sameSince = !!since && !!priorSince && Date.parse(since) === Date.parse(priorSince);
+        /*
+         * ── 종류를 알면 기준점 없이도 경계를 안다 (2026-08-28) ─────────────────────
+         *
+         * 앞 판은 `since` 만 보았다. 그래서 하루 누적을 선언한 원본이 기준점을 주지 않으면 매일 자정이
+         * 계기 교체로 기록됐다 — 종류를 말해 주었는데도.
+         *
+         * 그리고 **같은 날 안에서** 줄어든 것은 종류가 무엇이든 이상이다: 하루 누적의 경계는 자정이고,
+         * 자정이 어디인지는 현장의 선언(`utcOffsetMinutes`)이 답한다.
+         */
+        const accumulation = typeof d?.accumulation === 'string' ? d.accumulation : undefined;
+        const kind = (accumulation ?? eq.generatedKWhAccumulation);
+        const periodic = kind === 'daily' || kind === 'monthly' || kind === 'billing';
+        const dropped = Number.isFinite(before) && kWh < before;
+        const obs = this.generationPeriodObs.get(id);
+        const dayIndex = this.localDayIndex(atMs);
+        const sameDayDrop = dropped && obs !== undefined && obs.dayIndex === dayIndex;
+        if (dropped && !periodAdvanced && (!periodic || sameDayDrop)) {
             /* 되돌아갔다 — 값은 새것으로 두고, 그 사실을 시각으로 남긴다(우리가 계단을 메우지 않는다). */
             ;
             eq.generatedKWhResetAt = new Date(atMs).toISOString();
+            eq.generatedKWhBasis = sameSince ? 'declared' : 'inferred';
         }
-        ;
+        /* 기준점은 온 것만 세운다 — 오지 않았다고 앞서 받은 것을 지우지 않는다(결측 ≠ 없음). */
+        if (since)
+            eq.generatedKWhSince = since;
+        /*
+         * ── 누적의 종류 — **모름도 값이다** (2026-08-28) ────────────────────────────
+         *
+         * 이 칸을 비워 두면 소비처가 그 수를 평생치로 읽는다. 그러면 하루치를 주는 발전소의 「지금까지 낸
+         * 양」이 오늘치가 되고, 되돌아가기 전까지 아무도 알아채지 못한다.
+         *
+         * 원본이 말했으면 그것을, 말하지 않았으면 `'unknown'` 을 세운다 — 앞서 받은 값을 지우지는 않는다
+         * (한 표본이 종류를 빠뜨렸다고 아는 사실을 잃을 이유가 없다).
+         */
+        if (accumulation)
+            eq.generatedKWhAccumulation = accumulation;
+        else if (eq.generatedKWhAccumulation === undefined)
+            eq.generatedKWhAccumulation = 'unknown';
         eq.generatedKWh = kWh;
         eq.measuredAt = new Date(atMs).toISOString();
+        this.closeGenerationPeriod(id, eq, { atMs, kWh, dayIndex, kind, since, priorSince, periodAdvanced, faulted: dropped && sameDayDrop });
         this.revision++;
     }
+    /**
+     * **기간이 끝났으면 그 기간의 발전량을 사실로 낸다.**
+     *
+     * ── 없던 것 (2026-08-28) ────────────────────────────────────────────────────
+     * 적산값을 상태에 세우고 끝이었다. 그래서 「어제 얼마 냈나」·「이번 달 성능비」에 답할 자리가 없었고,
+     * 매일 자정에 값이 되돌아가는 원본에서는 그 하루의 총량이 **버려졌다** — 우리가 마지막으로 본 값이
+     * 곧 그날의 총량인데도.
+     *
+     * ISO 50001 의 성과지표와 기준선은 기간당 에너지로 정의된다(§`domain-catalog` 에너지 표준). 적산
+     * 하나로는 계산할 수 없다.
+     *
+     * ── 경계는 둘 중 하나에서 온다 ──────────────────────────────────────────────
+     *   원본의 기준점이 나아갔다     그 시각이 앞 기간의 끝이다 → boundary 'declared'
+     *   현장의 자정을 지났다         `utcOffsetMinutes` 가 정한 자정 → boundary 'offset'
+     *
+     * ── 총량을 얻는 방법이 종류마다 다르다 ──────────────────────────────────────
+     *   'daily'              마지막으로 본 값이 그대로 그날의 총량이다
+     *   'lifetime'           그날 처음 본 값과의 차이
+     *   'monthly'·'billing'  원본이 기준점을 말했을 때만 마감한다 — 자정으로는 그 기간이 끝나지 않는다
+     *   'unknown'            마감하지 않는다. 어느 기간의 값인지 모르는 수를 기간 사실로 낼 수 없다
+     *
+     * 관측 구간(`observedFrom`·`observedTo`)을 함께 낸다. 기간의 끝은 자정인데 마지막 표본이 저녁이었다면
+     * 그 사이는 재지 않은 것이고, 재지 않은 것을 0 으로 적으면 우리가 현장의 판단을 대신하는 것이 된다.
+     */
+    closeGenerationPeriod(id, eq, at) {
+        const obs = this.generationPeriodObs.get(id);
+        const fresh = { dayIndex: at.dayIndex, fromKWh: at.kWh, fromMs: at.atMs, lastKWh: at.kWh, lastMs: at.atMs };
+        /* 계기가 되돌아간 뒤의 기준점은 쓸 수 없다 — 차이가 음수가 되거나, 더 나쁘게 작아진 총량이 참인 척한다. */
+        if (at.faulted || !obs || at.kind === undefined || at.kind === 'unknown') {
+            this.generationPeriodObs.set(id, fresh);
+            return;
+        }
+        const declaredClose = at.periodAdvanced && !!at.priorSince && !!at.since;
+        const dayClose = at.dayIndex > obs.dayIndex && (at.kind === 'daily' || at.kind === 'lifetime');
+        let startMs;
+        let endMs;
+        let boundary;
+        if (declaredClose && at.kind !== 'lifetime') {
+            /* 평생 적산에 기준점이 나아가는 것은 뜻이 서지 않는다(기간이 하루가 아니다) — 자정 마감만 쓴다. */
+            startMs = Date.parse(at.priorSince);
+            endMs = Date.parse(at.since);
+            boundary = 'declared';
+        }
+        else if (dayClose) {
+            startMs = this.dayStartMs(obs.dayIndex);
+            endMs = this.dayStartMs(obs.dayIndex + 1);
+            boundary = 'offset';
+        }
+        if (startMs === undefined || endMs === undefined || boundary === undefined || !Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+            /*
+             * 하루가 지났는데 마감할 근거가 없다 — 월·요금기간 종류인데 기준점이 오지 않는 경우다. 세어 둔다:
+             * 세지 않으면 그 발전소의 발전량이 아무 표시 없이 영원히 나오지 않는다.
+             */
+            if (at.dayIndex > obs.dayIndex && (at.kind === 'monthly' || at.kind === 'billing'))
+                this.unclosedGenerationPeriods++;
+            if (at.dayIndex !== obs.dayIndex)
+                this.generationPeriodObs.set(id, fresh);
+            else
+                this.generationPeriodObs.set(id, { ...obs, lastKWh: at.kWh, lastMs: at.atMs });
+            return;
+        }
+        const total = at.kind === 'lifetime' ? obs.lastKWh - obs.fromKWh : obs.lastKWh;
+        if (Number.isFinite(total) && total >= 0) {
+            this.emitOp(ENERGY_EVENT.generationPeriod, {
+                equipmentId: id,
+                kWh: total,
+                periodStart: new Date(startMs).toISOString(),
+                periodEnd: new Date(endMs).toISOString(),
+                observedFrom: new Date(obs.fromMs).toISOString(),
+                observedTo: new Date(obs.lastMs).toISOString(),
+                accumulation: at.kind,
+                boundary
+            });
+            eq.generatedKWhLastPeriod = total;
+            eq.generatedKWhLastPeriodEnd = new Date(endMs).toISOString();
+            /* 상태만 읽는 화면이 덜 잰 값을 온전한 값으로 읽지 않게, 관측 구간을 함께 남긴다. */
+            eq.generatedKWhLastPeriodObservedFrom = new Date(obs.fromMs).toISOString();
+            eq.generatedKWhLastPeriodObservedTo = new Date(obs.lastMs).toISOString();
+        }
+        this.generationPeriodObs.set(id, fresh);
+    }
+    /* 자정의 위치는 트윈 정의가 선언한다 — 커널이 짐작하지 않는다(§`localDayIndexAt`). */
+    localDayIndex(atMs) {
+        return localDayIndexAt(atMs, this.boardDef?.utcOffsetMinutes);
+    }
+    dayStartMs(dayIndex) {
+        return localDayStartMs(dayIndex, this.boardDef?.utcOffsetMinutes);
+    }
     /** 설비마다 발전 적산을 마지막으로 들은 시각 — 늦게 온 옛 표본을 가리는 데만 쓴다. */
     generationHeardAtMs = new Map();
+    /**
+     * 설비마다 **지금 기간의 관측** — 기간 발전량을 확정할 때 쓰는 기준점(§`closeGenerationPeriod`).
+     *
+     * **스냅샷에 낸다**(`EnergyState.generationPeriods`). 처음에는 「셈을 위한 값이니 상태에 두지 않는다」고
+     * 두었는데 그것이 틀렸다 — 재기동하면 평생 적산의 기준점이 사라지고, 그날의 발전량이 부팅 이후로만
+     * 잡힌다. 계량 지점이 `kWhAtWindowStart` 를 상태에 두는 것과 같은 이유다.
+     */
+    generationPeriodObs = new Map();
+    /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
+    unclosedGenerationPeriods = 0;
     applyEquipmentEnergy(envelope) {
         const d = envelope.data;
         const id = String(d?.equipmentId ?? '').trim();
@@ -1107,6 +1276,26 @@ export class EmsKernel extends FlowEngine {
             this.closedTotal = Number(e.closedTotal);
         if (e.peakSince && Number.isFinite(e.peakSince.kW))
             this.peak = { kW: e.peakSince.kW, windowStartMs: e.peakSince.windowStartMs };
+        /*
+         * 발전 기준점을 이어받는다 — 이것이 없으면 재기동한 날의 발전량이 부팅 이후로만 잡힌다(평생 적산은
+         * 그날 처음 본 값과의 차이이므로). 계량 지점의 `kWhAtWindowStart` 와 같은 이유다.
+         */
+        for (const o of e.generationPeriods ?? []) {
+            if (!o?.equipmentId)
+                continue;
+            if (![o.dayIndex, o.fromKWh, o.fromMs, o.lastKWh, o.lastMs].every(v => Number.isFinite(Number(v))))
+                continue;
+            this.generationPeriodObs.set(o.equipmentId, {
+                dayIndex: Number(o.dayIndex),
+                fromKWh: Number(o.fromKWh),
+                fromMs: Number(o.fromMs),
+                lastKWh: Number(o.lastKWh),
+                lastMs: Number(o.lastMs)
+            });
+        }
+        /* 못 마감한 수도 이어받는다 — 이어받지 않으면 재기동마다 0 으로 돌아가 문제가 사라진 것처럼 보인다. */
+        if (Number.isFinite(e.unclosedGenerationPeriods))
+            this.unclosedGenerationPeriods = Number(e.unclosedGenerationPeriods);
     }
     getSnapshot() {
         const snap = super.getSnapshot();
@@ -1125,6 +1314,12 @@ export class EmsKernel extends FlowEngine {
             closedTotal: this.closedTotal,
             ...(this.peak ? { peakSince: { ...this.peak } } : {}),
             ...(this.unknownEquipmentReports ? { unknownEquipment: this.unknownEquipmentReports } : {}),
+            ...(this.generationPeriodObs.size
+                ? {
+                    generationPeriods: [...this.generationPeriodObs.entries()].map(([equipmentId, o]) => ({ equipmentId, ...o }))
+                }
+                : {}),
+            ...(this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {}),
             ...(contractKW !== undefined ? { contractKW } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
             ...(this.flowRequests.size

package/dist/energy-ingest.d.ts

@@ -65,6 +65,27 @@ export interface EnergyGenerationRecord {
     equipmentId: string;
     /** 계기 적산값(kWh) — 연결된 시스템이 준 값 그대로. 차분은 소비처가 한다. */
     kWh?: number;
+    /**
+     * **이 적산이 쌓이기 시작한 시각**(ISO) — 원본이 그 뜻을 말할 때만 싣는다 (2026-08-28).
+     *
+     * 하루 누적을 주는 원본이 있다. 그 값을 총적산으로 받으면 **매일 자정이 계기 교체로 기록된다**
+     * (§`EnergyGeneratedData.since` 의 실측).
+     *
+     * **없으면 비운다** — 설치 이후라고 가정하지 않는다. 원본이 말하지 않은 것을 커넥터가 지어내지
+     * 않는 것이 이 문의 규율이다. 다만 원본의 **문서나 코드가 그 뜻을 말한다면** 그것을 커널 어휘로
+     * 옮기는 것은 지어내기가 아니다 — 그때 현장의 선언된 시간대로 그 구간의 시작을 적는다.
+     */
+    kWhSince?: string;
+    /**
+     * **어떤 누적인가** — 원본이 말하지 않으면 `'unknown'` 을 싣는다 (2026-08-28).
+     *
+     * 비우지 말고 `'unknown'` 을 실으라는 뜻이 아니다: 비워도 커널이 `'unknown'` 으로 둔다. 다만
+     * **모른다는 것을 아는 커넥터는 그것을 말하는 편이 낫다** — 그러면 「아직 안 붙였다」와 「원본이 말해
+     * 주지 않는다」가 갈린다.
+     *
+     * 값의 목록과 뜻은 `EnergyGeneratedData.accumulation` 에 있다.
+     */
+    kWhAccumulation?: 'lifetime' | 'daily' | 'monthly' | 'billing' | 'unknown';
     at?: string;
 }
 /** 이 레코드가 발전 적산인가 — 어느 갈래로 보낼지를 한 곳에서 정한다. */

package/dist/energy-ingest.js

@@ -96,7 +96,22 @@ export function isEnergyEquipmentRecord(record) {
     if (!record || typeof record !== 'object')
         return false;
     const r = record;
-    return typeof r.equipmentId === 'string' && r.equipmentId.trim().length > 0 && r.epc === undefined && r.meterId === undefined;
+    /*
+     * ── **발전 적산을 밀어낸다** (2026-08-28 · 인티그레이션 레인이 걸어 보고 찾았다) ─
+     *
+     * 이 판정이 `equipmentId` 만 보아서 **발전 적산 레코드에도 참이었다.** 그래서 호스트가 설비 상태
+     * 필터를 먼저 돌리면 적산이 이 문으로 들어오고, 이 문은 「바꿀 상태가 하나도 없다」고 거부한다 —
+     * **엉뚱한 이유로 거부되고 커넥터는 보냈다고 믿는다.**
+     *
+     * 호스트가 순서로 풀 수 있지만 순서는 다음 사람이 줄을 옮기면 깨진다. 다른 어휘를 밀어내는 규율은
+     * 발전 쪽이 이미 갖고 있었다(`meterId`·`epc` 를 본다) — 이쪽만 없었다. **판정끼리 배타로 만든다.**
+     */
+    return (typeof r.equipmentId === 'string' &&
+        r.equipmentId.trim().length > 0 &&
+        r.epc === undefined &&
+        r.meterId === undefined &&
+        /* 적산을 실었으면 발전이다 — 이 문의 값은 상태이고, 적산은 자기 문이 있다. */
+        r.kWh === undefined);
 }
 /**
  * 설비 에너지 레코드 → 봉투. 계량과 같은 규율이다: 지어낼 수 없는 것이 빠지면 받지 않고, 받지 않은 것은
@@ -221,6 +236,20 @@ export function ingestEnergyGenerationRecords(records, opts) {
         const equipmentId = String(r?.equipmentId ?? '').trim();
         if (!equipmentId)
             errors.push('equipmentId 가 없다 — 어느 설비가 만든 것인지 지어낼 수 없다');
+        /*
+         * ── **한 레코드가 두 사실을 실어 오면 거부한다** (2026-08-28) ────────────────
+         *
+         * 판정을 배타로 만들면서 생긴 자리다. 적산을 실었으면 이 문으로 오는데, 그 레코드에 상태 값
+         * (`generatedKW`·`soc`·`position` …)이 함께 있으면 **그 사실이 조용히 사라진다** — 이 문은 상태를
+         * 읽지 않기 때문이다.
+         *
+         * 잃는 것보다 거부하는 편이 낫다. 커넥터가 갈라 보내면 둘 다 산다.
+         */
+        const STATE_FIELDS = ['generatedKW', 'exportKW', 'soc', 'chargeKW', 'dischargeKW', 'curtailable', 'minKW', 'position'];
+        const alsoState = STATE_FIELDS.filter(f => r?.[f] !== undefined);
+        if (alsoState.length) {
+            errors.push(`적산과 설비 상태를 한 레코드에 실었다(${alsoState.join('·')}) — 이 문은 적산만 읽으므로 그 값이 사라진다. 갈라 보낼 것`);
+        }
         const raw = r?.kWh;
         const kWh = Number(raw);
         if (raw === undefined || raw === null || !Number.isFinite(kWh)) {
@@ -233,11 +262,49 @@ export function ingestEnergyGenerationRecords(records, opts) {
         const eventTime = String(r?.at ?? '').trim() || opts.defaultEventTime || '';
         if (!eventTime)
             errors.push('at 이 없고 기본 시각도 주지 않았다 — 언제 잰 것인지 지어낼 수 없다');
+        /*
+         * 기준점은 **말했을 때만** 받는다. 형식이 틀리면 거부한다 — 못 읽는 기준점을 통과시키면 커널이
+         * 그것을 「기준점이 없다」로 읽고 다시 추론으로 떨어지는데, 커넥터는 알렸다고 믿는다.
+         */
+        let since;
+        const rawSince = r?.kWhSince;
+        if (rawSince !== undefined && rawSince !== null && String(rawSince).trim()) {
+            const text = String(rawSince).trim();
+            const at = Date.parse(text);
+            if (!Number.isFinite(at))
+                errors.push(`kWhSince 를 시각으로 읽을 수 없다: ${JSON.stringify(rawSince)}`);
+            else if (Number.isFinite(Date.parse(eventTime)) && at > Date.parse(eventTime)) {
+                /* 미래에서 쌓이기 시작한 적산은 없다 — 두 값 중 하나가 틀렸고, 어느 쪽인지 우리가 고를 수 없다. */
+                errors.push(`kWhSince(${text}) 가 잰 시각(${eventTime})보다 뒤다 — 둘 중 하나가 틀렸다`);
+            }
+            else
+                since = text;
+        }
+        /*
+         * 누적의 종류 — 아는 목록 밖의 값은 거부한다. 뭉개서 받으면 「모른다」와 「틀리게 말했다」가 같아진다.
+         */
+        const ACCUMULATIONS = ['lifetime', 'daily', 'monthly', 'billing', 'unknown'];
+        let accumulation;
+        const rawAcc = r?.kWhAccumulation;
+        if (rawAcc !== undefined && rawAcc !== null && String(rawAcc).trim()) {
+            const text = String(rawAcc).trim();
+            if (!ACCUMULATIONS.includes(text)) {
+                errors.push(`kWhAccumulation 이 아는 값이 아니다(${ACCUMULATIONS.join('·')}): ${JSON.stringify(rawAcc)}`);
+            }
+            else
+                accumulation = text;
+        }
         if (errors.length) {
             rejected.push({ record: r, errors });
             continue;
         }
-        const data = { equipmentId, kWh, at: eventTime };
+        const data = {
+            equipmentId,
+            kWh,
+            at: eventTime,
+            ...(since ? { since } : {}),
+            ...(accumulation ? { accumulation } : {})
+        };
         accepted.push({
             eventId: `${opts.tenantId}-generated-${++seq}`,
             eventType: ENERGY_EVENT.generated,

package/dist-cjs/index.cjs

@@ -146,6 +146,8 @@ __export(index_exports, {
   judgeAgainstSpec: () => judgeAgainstSpec,
   levelOfLocationType: () => levelOfLocationType,
   lgtinClass: () => lgtinClass,
+  localDayIndexAt: () => localDayIndexAt,
+  localDayStartMs: () => localDayStartMs,
   locationStatusOf: () => locationStatusOf,
   lotFromAttributes: () => lotFromAttributes,
   mapRecord: () => mapRecord,
@@ -461,6 +463,12 @@ function onDeclaredDay(e, minuteOfDay, weekday) {
 function weekdayAt(ms2, utcOffsetMinutes) {
   return new Date(ms2 + (utcOffsetMinutes ?? 0) * 6e4).getUTCDay();
 }
+function localDayIndexAt(ms2, utcOffsetMinutes) {
+  return Math.floor((ms2 + (utcOffsetMinutes ?? 0) * 6e4) / 864e5);
+}
+function localDayStartMs(dayIndex, utcOffsetMinutes) {
+  return dayIndex * 864e5 - (utcOffsetMinutes ?? 0) * 6e4;
+}
 function coversInstant(e, atMs) {
   const from = e.startDateTime ? Date.parse(e.startDateTime) : NaN;
   const to = e.finishDateTime ? Date.parse(e.finishDateTime) : NaN;
@@ -695,6 +703,16 @@ var ENERGY_EVENT = {
   tariffShift: "energy.tariff.shift",
   /** 발전(PV 등) — 역송을 포함한다(음의 소비가 아니라 별개 사실이다). */
   generated: "energy.generated",
+  /**
+   * **기간 발전량 확정** — 한 기간이 끝났고 그 기간에 얼마 냈는지가 정해졌다.
+   *
+   * ISO 50001 의 성과지표와 기준선, 태양광 성능비가 모두 「기간당 에너지」로 정의된다. 적산값만 상태에
+   * 두면 그 어느 것도 계산할 수 없고, 지난 기간들을 합할 수도 없다(상태는 지금 하나만 든다).
+   *
+   * 계량이 수요 구간을 마감해 사실로 내는 것과 같은 짝이다(§`demandWindow`). 두 값을 더하지 말 것 —
+   * 발전량은 설비가 만든 양이고 구간 전력량은 계량 지점을 지난 양이다.
+   */
+  generationPeriod: "energy.generation.period",
   /** 저장(ESS 충전). */
   stored: "energy.stored",
   /** 방전(ESS). 충전과 나눈다 — 손실·수명 판단이 둘을 구별해야 한다. */
@@ -2710,7 +2728,7 @@ var CAPABILITIES = {
      * 계량 능력(`metered`)이 `kW` 와 `kWh` 를 함께 선언한 것과 같은 짝이다. 적산은 발전 설비의 보편적
      * 사실이고(태양광·열병합·디젤), 그것이 없으면 성능비·발전시간 같은 성과를 아무도 셀 수 없다.
      */
-    stateFields: ["generatedKW", "exportKW", "generatedKWh", "generatedKWhResetAt"],
+    stateFields: ["generatedKW", "exportKW", "generatedKWh", "generatedKWhResetAt", "generatedKWhSince", "generatedKWhBasis", "generatedKWhAccumulation", "generatedKWhLastPeriod", "generatedKWhLastPeriodEnd", "generatedKWhLastPeriodObservedFrom", "generatedKWhLastPeriodObservedTo"],
     models: ["GeneratingState"],
     results: ["generated"]
   },
@@ -7927,17 +7945,119 @@ var EmsKernel = class extends FlowEngine {
     if (heardAt !== void 0 && atMs < heardAt) return;
     this.generationHeardAtMs.set(id, atMs);
     const before = Number(eq.generatedKWh);
-    if (Number.isFinite(before) && kWh < before) {
+    const priorSince = eq.generatedKWhSince;
+    const since = typeof d?.since === "string" && d.since.trim() ? d.since.trim() : void 0;
+    const periodAdvanced = !!since && !!priorSince && Date.parse(since) > Date.parse(priorSince);
+    const sameSince = !!since && !!priorSince && Date.parse(since) === Date.parse(priorSince);
+    const accumulation = typeof d?.accumulation === "string" ? d.accumulation : void 0;
+    const kind = accumulation ?? eq.generatedKWhAccumulation;
+    const periodic = kind === "daily" || kind === "monthly" || kind === "billing";
+    const dropped = Number.isFinite(before) && kWh < before;
+    const obs = this.generationPeriodObs.get(id);
+    const dayIndex = this.localDayIndex(atMs);
+    const sameDayDrop = dropped && obs !== void 0 && obs.dayIndex === dayIndex;
+    if (dropped && !periodAdvanced && (!periodic || sameDayDrop)) {
       ;
       eq.generatedKWhResetAt = new Date(atMs).toISOString();
+      eq.generatedKWhBasis = sameSince ? "declared" : "inferred";
     }
-    ;
+    if (since) eq.generatedKWhSince = since;
+    if (accumulation) eq.generatedKWhAccumulation = accumulation;
+    else if (eq.generatedKWhAccumulation === void 0) eq.generatedKWhAccumulation = "unknown";
     eq.generatedKWh = kWh;
     eq.measuredAt = new Date(atMs).toISOString();
+    this.closeGenerationPeriod(id, eq, { atMs, kWh, dayIndex, kind, since, priorSince, periodAdvanced, faulted: dropped && sameDayDrop });
     this.revision++;
   }
+  /**
+   * **기간이 끝났으면 그 기간의 발전량을 사실로 낸다.**
+   *
+   * ── 없던 것 (2026-08-28) ────────────────────────────────────────────────────
+   * 적산값을 상태에 세우고 끝이었다. 그래서 「어제 얼마 냈나」·「이번 달 성능비」에 답할 자리가 없었고,
+   * 매일 자정에 값이 되돌아가는 원본에서는 그 하루의 총량이 **버려졌다** — 우리가 마지막으로 본 값이
+   * 곧 그날의 총량인데도.
+   *
+   * ISO 50001 의 성과지표와 기준선은 기간당 에너지로 정의된다(§`domain-catalog` 에너지 표준). 적산
+   * 하나로는 계산할 수 없다.
+   *
+   * ── 경계는 둘 중 하나에서 온다 ──────────────────────────────────────────────
+   *   원본의 기준점이 나아갔다     그 시각이 앞 기간의 끝이다 → boundary 'declared'
+   *   현장의 자정을 지났다         `utcOffsetMinutes` 가 정한 자정 → boundary 'offset'
+   *
+   * ── 총량을 얻는 방법이 종류마다 다르다 ──────────────────────────────────────
+   *   'daily'              마지막으로 본 값이 그대로 그날의 총량이다
+   *   'lifetime'           그날 처음 본 값과의 차이
+   *   'monthly'·'billing'  원본이 기준점을 말했을 때만 마감한다 — 자정으로는 그 기간이 끝나지 않는다
+   *   'unknown'            마감하지 않는다. 어느 기간의 값인지 모르는 수를 기간 사실로 낼 수 없다
+   *
+   * 관측 구간(`observedFrom`·`observedTo`)을 함께 낸다. 기간의 끝은 자정인데 마지막 표본이 저녁이었다면
+   * 그 사이는 재지 않은 것이고, 재지 않은 것을 0 으로 적으면 우리가 현장의 판단을 대신하는 것이 된다.
+   */
+  closeGenerationPeriod(id, eq, at) {
+    const obs = this.generationPeriodObs.get(id);
+    const fresh = { dayIndex: at.dayIndex, fromKWh: at.kWh, fromMs: at.atMs, lastKWh: at.kWh, lastMs: at.atMs };
+    if (at.faulted || !obs || at.kind === void 0 || at.kind === "unknown") {
+      this.generationPeriodObs.set(id, fresh);
+      return;
+    }
+    const declaredClose = at.periodAdvanced && !!at.priorSince && !!at.since;
+    const dayClose = at.dayIndex > obs.dayIndex && (at.kind === "daily" || at.kind === "lifetime");
+    let startMs;
+    let endMs;
+    let boundary;
+    if (declaredClose && at.kind !== "lifetime") {
+      startMs = Date.parse(at.priorSince);
+      endMs = Date.parse(at.since);
+      boundary = "declared";
+    } else if (dayClose) {
+      startMs = this.dayStartMs(obs.dayIndex);
+      endMs = this.dayStartMs(obs.dayIndex + 1);
+      boundary = "offset";
+    }
+    if (startMs === void 0 || endMs === void 0 || boundary === void 0 || !Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+      if (at.dayIndex > obs.dayIndex && (at.kind === "monthly" || at.kind === "billing")) this.unclosedGenerationPeriods++;
+      if (at.dayIndex !== obs.dayIndex) this.generationPeriodObs.set(id, fresh);
+      else this.generationPeriodObs.set(id, { ...obs, lastKWh: at.kWh, lastMs: at.atMs });
+      return;
+    }
+    const total = at.kind === "lifetime" ? obs.lastKWh - obs.fromKWh : obs.lastKWh;
+    if (Number.isFinite(total) && total >= 0) {
+      this.emitOp(ENERGY_EVENT.generationPeriod, {
+        equipmentId: id,
+        kWh: total,
+        periodStart: new Date(startMs).toISOString(),
+        periodEnd: new Date(endMs).toISOString(),
+        observedFrom: new Date(obs.fromMs).toISOString(),
+        observedTo: new Date(obs.lastMs).toISOString(),
+        accumulation: at.kind,
+        boundary
+      });
+      eq.generatedKWhLastPeriod = total;
+      eq.generatedKWhLastPeriodEnd = new Date(endMs).toISOString();
+      eq.generatedKWhLastPeriodObservedFrom = new Date(obs.fromMs).toISOString();
+      eq.generatedKWhLastPeriodObservedTo = new Date(obs.lastMs).toISOString();
+    }
+    this.generationPeriodObs.set(id, fresh);
+  }
+  /* 자정의 위치는 트윈 정의가 선언한다 — 커널이 짐작하지 않는다(§`localDayIndexAt`). */
+  localDayIndex(atMs) {
+    return localDayIndexAt(atMs, this.boardDef?.utcOffsetMinutes);
+  }
+  dayStartMs(dayIndex) {
+    return localDayStartMs(dayIndex, this.boardDef?.utcOffsetMinutes);
+  }
   /** 설비마다 발전 적산을 마지막으로 들은 시각 — 늦게 온 옛 표본을 가리는 데만 쓴다. */
   generationHeardAtMs = /* @__PURE__ */ new Map();
+  /**
+   * 설비마다 **지금 기간의 관측** — 기간 발전량을 확정할 때 쓰는 기준점(§`closeGenerationPeriod`).
+   *
+   * **스냅샷에 낸다**(`EnergyState.generationPeriods`). 처음에는 「셈을 위한 값이니 상태에 두지 않는다」고
+   * 두었는데 그것이 틀렸다 — 재기동하면 평생 적산의 기준점이 사라지고, 그날의 발전량이 부팅 이후로만
+   * 잡힌다. 계량 지점이 `kWhAtWindowStart` 를 상태에 두는 것과 같은 이유다.
+   */
+  generationPeriodObs = /* @__PURE__ */ new Map();
+  /** 기준점이 없어 마감하지 못한 기간 누적의 수 — 조용히 사라지지 않게 센다. */
+  unclosedGenerationPeriods = 0;
   applyEquipmentEnergy(envelope) {
     const d = envelope.data;
     const id = String(d?.equipmentId ?? "").trim();
@@ -8479,6 +8599,18 @@ var EmsKernel = class extends FlowEngine {
     if (e.closed?.length) this.closed = e.closed.map((w) => ({ ...w })).slice(-KEEP_CLOSED);
     if (Number.isFinite(e.closedTotal)) this.closedTotal = Number(e.closedTotal);
     if (e.peakSince && Number.isFinite(e.peakSince.kW)) this.peak = { kW: e.peakSince.kW, windowStartMs: e.peakSince.windowStartMs };
+    for (const o of e.generationPeriods ?? []) {
+      if (!o?.equipmentId) continue;
+      if (![o.dayIndex, o.fromKWh, o.fromMs, o.lastKWh, o.lastMs].every((v) => Number.isFinite(Number(v)))) continue;
+      this.generationPeriodObs.set(o.equipmentId, {
+        dayIndex: Number(o.dayIndex),
+        fromKWh: Number(o.fromKWh),
+        fromMs: Number(o.fromMs),
+        lastKWh: Number(o.lastKWh),
+        lastMs: Number(o.lastMs)
+      });
+    }
+    if (Number.isFinite(e.unclosedGenerationPeriods)) this.unclosedGenerationPeriods = Number(e.unclosedGenerationPeriods);
   }
   getSnapshot() {
     const snap = super.getSnapshot();
@@ -8495,6 +8627,10 @@ var EmsKernel = class extends FlowEngine {
       closedTotal: this.closedTotal,
       ...this.peak ? { peakSince: { ...this.peak } } : {},
       ...this.unknownEquipmentReports ? { unknownEquipment: this.unknownEquipmentReports } : {},
+      ...this.generationPeriodObs.size ? {
+        generationPeriods: [...this.generationPeriodObs.entries()].map(([equipmentId, o]) => ({ equipmentId, ...o }))
+      } : {},
+      ...this.unclosedGenerationPeriods ? { unclosedGenerationPeriods: this.unclosedGenerationPeriods } : {},
       ...contractKW !== void 0 ? { contractKW } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
       ...this.flowRequests.size ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) } : {}
@@ -9348,7 +9484,8 @@ var POSITIONS = /* @__PURE__ */ new Set(["open", "closed", "intermediate", "bad"
 function isEnergyEquipmentRecord(record) {
   if (!record || typeof record !== "object") return false;
   const r = record;
-  return typeof r.equipmentId === "string" && r.equipmentId.trim().length > 0 && r.epc === void 0 && r.meterId === void 0;
+  return typeof r.equipmentId === "string" && r.equipmentId.trim().length > 0 && r.epc === void 0 && r.meterId === void 0 && /* 적산을 실었으면 발전이다 — 이 문의 값은 상태이고, 적산은 자기 문이 있다. */
+  r.kWh === void 0;
 }
 function ingestEnergyEquipmentRecords(records, opts) {
   const arr = Array.isArray(records) ? records : records ? [records] : [];
@@ -9442,6 +9579,13 @@ function ingestEnergyGenerationRecords(records, opts) {
     const errors = [];
     const equipmentId = String(r?.equipmentId ?? "").trim();
     if (!equipmentId) errors.push("equipmentId \uAC00 \uC5C6\uB2E4 \u2014 \uC5B4\uB290 \uC124\uBE44\uAC00 \uB9CC\uB4E0 \uAC83\uC778\uC9C0 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4");
+    const STATE_FIELDS = ["generatedKW", "exportKW", "soc", "chargeKW", "dischargeKW", "curtailable", "minKW", "position"];
+    const alsoState = STATE_FIELDS.filter((f) => r?.[f] !== void 0);
+    if (alsoState.length) {
+      errors.push(
+        `\uC801\uC0B0\uACFC \uC124\uBE44 \uC0C1\uD0DC\uB97C \uD55C \uB808\uCF54\uB4DC\uC5D0 \uC2E4\uC5C8\uB2E4(${alsoState.join("\xB7")}) \u2014 \uC774 \uBB38\uC740 \uC801\uC0B0\uB9CC \uC77D\uC73C\uBBC0\uB85C \uADF8 \uAC12\uC774 \uC0AC\uB77C\uC9C4\uB2E4. \uAC08\uB77C \uBCF4\uB0BC \uAC83`
+      );
+    }
     const raw = r?.kWh;
     const kWh = Number(raw);
     if (raw === void 0 || raw === null || !Number.isFinite(kWh)) {
@@ -9451,11 +9595,36 @@ function ingestEnergyGenerationRecords(records, opts) {
     }
     const eventTime = String(r?.at ?? "").trim() || opts.defaultEventTime || "";
     if (!eventTime) errors.push("at \uC774 \uC5C6\uACE0 \uAE30\uBCF8 \uC2DC\uAC01\uB3C4 \uC8FC\uC9C0 \uC54A\uC558\uB2E4 \u2014 \uC5B8\uC81C \uC7B0 \uAC83\uC778\uC9C0 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4");
+    let since;
+    const rawSince = r?.kWhSince;
+    if (rawSince !== void 0 && rawSince !== null && String(rawSince).trim()) {
+      const text = String(rawSince).trim();
+      const at = Date.parse(text);
+      if (!Number.isFinite(at)) errors.push(`kWhSince \uB97C \uC2DC\uAC01\uC73C\uB85C \uC77D\uC744 \uC218 \uC5C6\uB2E4: ${JSON.stringify(rawSince)}`);
+      else if (Number.isFinite(Date.parse(eventTime)) && at > Date.parse(eventTime)) {
+        errors.push(`kWhSince(${text}) \uAC00 \uC7B0 \uC2DC\uAC01(${eventTime})\uBCF4\uB2E4 \uB4A4\uB2E4 \u2014 \uB458 \uC911 \uD558\uB098\uAC00 \uD2C0\uB838\uB2E4`);
+      } else since = text;
+    }
+    const ACCUMULATIONS = ["lifetime", "daily", "monthly", "billing", "unknown"];
+    let accumulation;
+    const rawAcc = r?.kWhAccumulation;
+    if (rawAcc !== void 0 && rawAcc !== null && String(rawAcc).trim()) {
+      const text = String(rawAcc).trim();
+      if (!ACCUMULATIONS.includes(text)) {
+        errors.push(`kWhAccumulation \uC774 \uC544\uB294 \uAC12\uC774 \uC544\uB2C8\uB2E4(${ACCUMULATIONS.join("\xB7")}): ${JSON.stringify(rawAcc)}`);
+      } else accumulation = text;
+    }
     if (errors.length) {
       rejected.push({ record: r, errors });
       continue;
     }
-    const data = { equipmentId, kWh, at: eventTime };
+    const data = {
+      equipmentId,
+      kWh,
+      at: eventTime,
+      ...since ? { since } : {},
+      ...accumulation ? { accumulation } : {}
+    };
     accepted.push({
       eventId: `${opts.tenantId}-generated-${++seq}`,
       eventType: ENERGY_EVENT.generated,
@@ -10162,6 +10331,8 @@ function retiredVocabularyIn(line) {
   judgeAgainstSpec,
   levelOfLocationType,
   lgtinClass,
+  localDayIndexAt,
+  localDayStartMs,
   locationStatusOf,
   lotFromAttributes,
   mapRecord,

package/package.json

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