@operato/twin-kernel 0.7.82 → 0.7.84

package/dist/ems-kernel.js

@@ -554,6 +554,20 @@ export class EmsKernel extends FlowEngine {
              * 「어느 기간의 값인지 모른다」로 마감하지 못한다.
              */
             const kind = obs.accumulation ?? eq.generatedKWhAccumulation;
+            /*
+             * ── 마감하지 못하면 **손대지 않는다** (2026-08-30, 고침) ─────────────────
+             *
+             * 종류를 모르면 마감할 수 없다. 그런데 그대로 아래로 내려보내면 관측이 **오늘 것으로 덮인다** —
+             * 표본이 왔을 때는 그 재설정이 맞지만(새 관측이니까), 시계로 부를 때는 새 표본이 없다.
+             * 덮으면 어제는 영영 마감되지 않는다.
+             *
+             * 실제로 그렇게 됐다: 밤에 재기동해 종류가 비었고, 시계가 자정을 지날 때마다 어제 관측이
+             * 오늘로 밀렸다. 아침 표본이 와도 마감할 어제가 남아 있지 않다.
+             */
+            if (kind === undefined || kind === 'unknown') {
+                this.unclosedGenerationPeriods++;
+                continue;
+            }
             /*
              * 마감은 `applyGenerated` 와 **같은 함수**로 한다 — 규칙을 두 벌 만들면 표본으로 닫은 날과
              * 시계로 닫은 날이 다른 값을 낸다.

package/dist/energy-ingest.d.ts

@@ -115,6 +115,34 @@ export interface EnergyUsagePeriodRecord {
     basis?: string;
 }
 export declare function isEnergyUsagePeriodRecord(record: unknown): boolean;
+/**
+ * 마감된 **발전 기간** — 「이 기간에 이 설비가 이만큼 냈다」.
+ *
+ * 라이브에서는 커널이 스스로 마감해 낸다(§`closeGenerationPeriod`). 이 문은 **지난 기록을 채울 때**
+ * 쓴다 — 원본이 날짜별 발전량을 주는 현장에서, 트윈이 없던 동안의 날들을 뒤늦게 넣는다.
+ *
+ * 상태를 바꾸지 않는다. 저널에만 적히고, 저널을 읽는 쪽(성과 계산)이 그 사실을 본다.
+ */
+export interface EnergyGenerationPeriodRecord {
+    equipmentId: string;
+    from: string;
+    to: string;
+    kWh: number;
+    /** 원본이 준 적산의 종류 — 총량을 어떻게 얻었는지가 이것으로 갈린다. */
+    accumulation?: string;
+    /** 그 기간에서 처음·마지막으로 관측한 시각. 기간 경계와 다르면 그만큼 재지 않았다. */
+    observedFrom?: string;
+    observedTo?: string;
+}
+export declare function isEnergyGenerationPeriodRecord(record: unknown): boolean;
+/**
+ * 마감된 발전 기간을 봉투로 — **사건 시각은 기간의 끝**이다(그때 성립한다).
+ *
+ * 적산의 문(`ingestEnergyGenerationRecords`)과 겹치지 않는다: 그쪽은 구간이 없는 시점의 값이고
+ * 이쪽은 구간이 있는 마감된 사실이다. 겹치면 지난 기록이 「지금 적산」으로 읽혀 트윈의 시계가
+ * 과거로 끌린다.
+ */
+export declare function ingestEnergyGenerationPeriodRecords(records: EnergyGenerationPeriodRecord | EnergyGenerationPeriodRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
 /** 발전 단가 — 이 기간에 낸 전기 1kWh 의 값. 날마다 바뀐다. */
 export interface EnergyGenerationPriceRecord {
     from: string;

package/dist/energy-ingest.js

@@ -268,6 +268,9 @@ export function ingestEnergyEquipmentRecords(records, opts) {
 }
 /** 이 레코드가 발전 적산인가 — 어느 갈래로 보낼지를 한 곳에서 정한다. */
 export function isEnergyGenerationRecord(record) {
+    /* 구간이 있으면 마감된 발전 기간이지 시점의 적산이 아니다 — 겹치면 지난 기록이 「지금」으로 읽힌다. */
+    if (record?.from !== undefined || record?.to !== undefined)
+        return false;
     if (!record || typeof record !== 'object')
         return false;
     const r = record;
@@ -378,6 +381,84 @@ 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 isEnergyGenerationPeriodRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.equipmentId === undefined || r.from === undefined || r.to === undefined)
+        return false;
+    return r.kWh !== undefined;
+}
+/**
+ * 마감된 발전 기간을 봉투로 — **사건 시각은 기간의 끝**이다(그때 성립한다).
+ *
+ * 적산의 문(`ingestEnergyGenerationRecords`)과 겹치지 않는다: 그쪽은 구간이 없는 시점의 값이고
+ * 이쪽은 구간이 있는 마감된 사실이다. 겹치면 지난 기록이 「지금 적산」으로 읽혀 트윈의 시계가
+ * 과거로 끌린다.
+ */
+export function ingestEnergyGenerationPeriodRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const equipmentId = String(r?.equipmentId ?? '').trim();
+        if (!equipmentId)
+            errors.push('equipmentId 가 없다 — 어느 설비가 낸 것인지 지어낼 수 없다');
+        const span = readSpan(r, errors);
+        const kWh = readAmount(r?.kWh, 'kWh', errors);
+        if (kWh === undefined && !errors.length)
+            errors.push('kWh 가 없다 — 이 문이 받는 값은 그 기간의 발전량이다');
+        const ACCUMULATIONS = ['lifetime', 'daily', 'monthly', 'billing', 'unknown'];
+        let accumulation;
+        const rawAcc = r?.accumulation;
+        if (rawAcc !== undefined && rawAcc !== null && String(rawAcc).trim()) {
+            const text = String(rawAcc).trim();
+            if (!ACCUMULATIONS.includes(text)) {
+                errors.push(`accumulation 이 아는 값이 아니다(${ACCUMULATIONS.join('·')}): ${JSON.stringify(rawAcc)}`);
+            }
+            else
+                accumulation = text;
+        }
+        /* 관측 구간은 기간 안에 있어야 한다 — 밖이면 그 값이 이 기간의 것이 아니다. */
+        const readAt = (raw, name) => {
+            if (raw === undefined || raw === null || !String(raw).trim())
+                return undefined;
+            const text = String(raw).trim();
+            if (!Number.isFinite(Date.parse(text))) {
+                errors.push(`${name} 를 시각으로 읽을 수 없다: ${JSON.stringify(raw)}`);
+                return undefined;
+            }
+            return text;
+        };
+        const observedFrom = readAt(r?.observedFrom, 'observedFrom');
+        const observedTo = readAt(r?.observedTo, 'observedTo');
+        if (errors.length || !span || kWh === undefined) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            equipmentId,
+            kWh,
+            periodStart: span.from,
+            periodEnd: span.to,
+            /* 관측 구간을 말하지 않으면 기간 전체를 잰 것으로 둔다 — 지난 기록은 그 원본이 하루를 마감해 준 값이다. */
+            observedFrom: observedFrom ?? span.from,
+            observedTo: observedTo ?? span.to,
+            accumulation: (accumulation ?? 'daily'),
+            /* 밖에서 마감되어 온 것이다 — 우리가 시각 기준으로 닫은 것이 아니다. */
+            boundary: 'declared'
+        };
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPeriod, equipmentId, span.from, span.to),
+            eventType: ENERGY_EVENT.generationPeriod,
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
 export function isEnergyGenerationPriceRecord(record) {
     const r = record;
     if (!r || typeof r !== 'object')

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

@@ -127,6 +127,7 @@ __export(index_exports, {
   ingest: () => ingest,
   ingestEnergyBillRecords: () => ingestEnergyBillRecords,
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
+  ingestEnergyGenerationPeriodRecords: () => ingestEnergyGenerationPeriodRecords,
   ingestEnergyGenerationPriceRecords: () => ingestEnergyGenerationPriceRecords,
   ingestEnergyGenerationRecords: () => ingestEnergyGenerationRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
@@ -138,6 +139,7 @@ __export(index_exports, {
   isElectricalLocationType: () => isElectricalLocationType,
   isEnergyBillRecord: () => isEnergyBillRecord,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
+  isEnergyGenerationPeriodRecord: () => isEnergyGenerationPeriodRecord,
   isEnergyGenerationPriceRecord: () => isEnergyGenerationPriceRecord,
   isEnergyGenerationRecord: () => isEnergyGenerationRecord,
   isEnergyRecord: () => isEnergyRecord,
@@ -8183,6 +8185,10 @@ var EmsKernel = class extends FlowEngine {
       const eq = this.equipment.get(id);
       if (!eq) continue;
       const kind = obs.accumulation ?? eq.generatedKWhAccumulation;
+      if (kind === void 0 || kind === "unknown") {
+        this.unclosedGenerationPeriods++;
+        continue;
+      }
       this.closeGenerationPeriod(id, eq, {
         atMs: nowMs,
         kWh: obs.lastKWh,
@@ -9966,6 +9972,7 @@ function ingestEnergyEquipmentRecords(records, opts) {
   return { accepted, rejected };
 }
 function isEnergyGenerationRecord(record) {
+  if (record?.from !== void 0 || record?.to !== void 0) return false;
   if (!record || typeof record !== "object") return false;
   const r = record;
   return typeof r.equipmentId === "string" && r.equipmentId.trim().length > 0 && r.kWh !== void 0 && r.meterId === void 0 && r.epc === void 0;
@@ -10039,6 +10046,69 @@ 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 isEnergyGenerationPeriodRecord(record) {
+  const r = record;
+  if (!r || typeof r !== "object") return false;
+  if (r.equipmentId === void 0 || r.from === void 0 || r.to === void 0) return false;
+  return r.kWh !== void 0;
+}
+function ingestEnergyGenerationPeriodRecords(records, opts) {
+  const list = records === void 0 || records === null ? [] : Array.isArray(records) ? records : [records];
+  const accepted = [];
+  const rejected = [];
+  for (const r of list) {
+    const errors = [];
+    const equipmentId = String(r?.equipmentId ?? "").trim();
+    if (!equipmentId) errors.push("equipmentId \uAC00 \uC5C6\uB2E4 \u2014 \uC5B4\uB290 \uC124\uBE44\uAC00 \uB0B8 \uAC83\uC778\uC9C0 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4");
+    const span = readSpan(r, errors);
+    const kWh = readAmount(r?.kWh, "kWh", errors);
+    if (kWh === void 0 && !errors.length) errors.push("kWh \uAC00 \uC5C6\uB2E4 \u2014 \uC774 \uBB38\uC774 \uBC1B\uB294 \uAC12\uC740 \uADF8 \uAE30\uAC04\uC758 \uBC1C\uC804\uB7C9\uC774\uB2E4");
+    const ACCUMULATIONS = ["lifetime", "daily", "monthly", "billing", "unknown"];
+    let accumulation;
+    const rawAcc = r?.accumulation;
+    if (rawAcc !== void 0 && rawAcc !== null && String(rawAcc).trim()) {
+      const text = String(rawAcc).trim();
+      if (!ACCUMULATIONS.includes(text)) {
+        errors.push(`accumulation \uC774 \uC544\uB294 \uAC12\uC774 \uC544\uB2C8\uB2E4(${ACCUMULATIONS.join("\xB7")}): ${JSON.stringify(rawAcc)}`);
+      } else accumulation = text;
+    }
+    const readAt = (raw, name) => {
+      if (raw === void 0 || raw === null || !String(raw).trim()) return void 0;
+      const text = String(raw).trim();
+      if (!Number.isFinite(Date.parse(text))) {
+        errors.push(`${name} \uB97C \uC2DC\uAC01\uC73C\uB85C \uC77D\uC744 \uC218 \uC5C6\uB2E4: ${JSON.stringify(raw)}`);
+        return void 0;
+      }
+      return text;
+    };
+    const observedFrom = readAt(r?.observedFrom, "observedFrom");
+    const observedTo = readAt(r?.observedTo, "observedTo");
+    if (errors.length || !span || kWh === void 0) {
+      rejected.push({ record: r, errors });
+      continue;
+    }
+    const data = {
+      equipmentId,
+      kWh,
+      periodStart: span.from,
+      periodEnd: span.to,
+      /* 관측 구간을 말하지 않으면 기간 전체를 잰 것으로 둔다 — 지난 기록은 그 원본이 하루를 마감해 준 값이다. */
+      observedFrom: observedFrom ?? span.from,
+      observedTo: observedTo ?? span.to,
+      accumulation: accumulation ?? "daily",
+      /* 밖에서 마감되어 온 것이다 — 우리가 시각 기준으로 닫은 것이 아니다. */
+      boundary: "declared"
+    };
+    accepted.push({
+      eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPeriod, equipmentId, span.from, span.to),
+      eventType: ENERGY_EVENT.generationPeriod,
+      eventTime: span.to,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
 function isEnergyGenerationPriceRecord(record) {
   const r = record;
   if (!r || typeof r !== "object") return false;
@@ -10934,6 +11004,7 @@ function retiredVocabularyIn(line) {
   ingest,
   ingestEnergyBillRecords,
   ingestEnergyEquipmentRecords,
+  ingestEnergyGenerationPeriodRecords,
   ingestEnergyGenerationPriceRecords,
   ingestEnergyGenerationRecords,
   ingestEnergyRecords,
@@ -10945,6 +11016,7 @@ function retiredVocabularyIn(line) {
   isElectricalLocationType,
   isEnergyBillRecord,
   isEnergyEquipmentRecord,
+  isEnergyGenerationPeriodRecord,
   isEnergyGenerationPriceRecord,
   isEnergyGenerationRecord,
   isEnergyRecord,

package/package.json

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