@operato/twin-kernel 0.7.4 → 0.7.6

package/dist/contract.d.ts

@@ -842,6 +842,18 @@ export interface EquipmentState extends EffectivePeriod {
      * 셋을 합치면 "왜 안 움직이나" 에 답할 수 없다(고쳐야 하나·풀어야 하나·기다려야 하나).
      */
     offShift?: boolean;
+    /** generating — 만든 전력·역송(kW). */
+    generatedKW?: number;
+    exportKW?: number;
+    /** storing — 충전율(%)·충전·방전(kW). 충전과 방전을 나눈다(손실·수명 판단이 그 둘을 구별한다). */
+    soc?: number;
+    chargeKW?: number;
+    dischargeKW?: number;
+    /** curtailable — 줄일 수 있나, 그리고 최소 유지(kW). 그 아래로 내리면 공정이 죽는다. */
+    curtailable?: boolean;
+    minKW?: number;
+    /** switching — 개폐 위치(IEC 61850 `Pos`). 과도·불량을 열림/닫힘으로 반올림하지 않는다. */
+    position?: 'open' | 'closed' | 'intermediate' | 'bad';
     /**
      * 유효 기간 밖이라 이 시각의 모델에 없다 — **네 번째 이유**(§Effectivity).
      * 도입 예정(`not-yet`)과 폐기(`expired`)를 구별한다. 유효하면 값이 없다.
@@ -1218,7 +1230,13 @@ export interface EnergyState {
     /** 관측 시작 이후 최대 수요 — 월 경계는 여기서 정하지 않는다(위 주석). */
     peakSince?: {
         kW: number;
-        windowStartMs: number;
+        windowStartMs: number; /**
+         * 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — **버린 것을 세어 둔다.**
+         *
+         * 원천에 우리가 모르는 설비가 있다는 것은 그 자체로 알아야 할 사실이다(모델이 낡았거나 매핑이
+         * 틀렸다). 조용히 버리면 「값이 왜 안 보이지」로만 남는다.
+         */
+        unknownEquipment?: number;
     };
     /** 현장이 선언한 계약전력(자리 속성) — 없으면 계약 대비 판정을 하지 않는다. */
     contractKW?: number;
@@ -1428,6 +1446,12 @@ export declare const OP_EVENT: {
 export declare const ENERGY_EVENT: {
     /** 계량 도착 — 그 시점의 유효전력·누적량. 15분 수요 구간에 누적된다. */
     readonly measured: "energy.measured";
+    /**
+     * 설비의 에너지 상태 — 발전·저장·감축 여지·개폐 위치.
+     *
+     * 계량과 다른 사건으로 둔다: 계량은 구간에 **누적**되고 이것은 그 설비의 **지금**을 바꾼다.
+     */
+    readonly equipment: "energy.equipment";
     /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
     readonly demandWindow: "energy.demand.window";
     /**
@@ -1455,6 +1479,27 @@ export declare const ENERGY_EVENT: {
     readonly drSuggested: "energy.dr.suggested";
 };
 export type EnergyEventType = (typeof ENERGY_EVENT)[keyof typeof ENERGY_EVENT];
+/**
+ * 설비가 낸 **자기 에너지 상태** — 계량이 아닌 능력들의 값.
+ *
+ * 계량(`energy.measured`)과 갈라 두는 이유: 계량은 **구간에 누적되는 표본**이고, 이것들은 **그 설비의
+ * 지금 상태**다. 같은 문으로 넣으면 발전량이 부하 구간에 더해지거나 충전율이 요금 판정에 섞인다.
+ *
+ * 한 봉투에 여러 능력의 값이 함께 올 수 있다(원 시스템이 한 번에 준다) — 각 값은 그것을 선언한 능력의
+ * 필드로만 들어간다. 없는 값은 **보내지 않는다**(0 을 보내면 「그렇게 측정됐다」가 된다).
+ */
+export interface EnergyEquipmentData {
+    equipmentId: string;
+    at: ISOTime;
+    generatedKW?: number;
+    exportKW?: number;
+    soc?: number;
+    chargeKW?: number;
+    dischargeKW?: number;
+    curtailable?: boolean;
+    minKW?: number;
+    position?: 'open' | 'closed' | 'intermediate' | 'bad';
+}
 /** 계량 도착의 실린 값 — 계량 지점 하나의 한 시점. */
 export interface EnergyMeasuredData {
     /** 계량 지점(설비 id). */
@@ -1850,6 +1895,14 @@ export interface TwinKernel {
     adoptStructure(def: TwinModelDef): StructureShift;
     /** 이 커널이 관측으로 구동됨을 선언한다 — 첫 이벤트가 오기 전에도 그렇다. */
     observe(): void;
+    /**
+     * 시각 기준점을 세운다 — 이 트윈의 「지금」은 `기준점 + 경과`다.
+     *
+     * 세우는 쪽이 기동 순간의 실제 시각을 준다. 주지 않으면 커널의 기본 기준점을 쓰는데, 그러면 시뮬
+     * 트윈의 저널 시각이 재기동마다 되감겨 「언제 있었던 일인가」를 되짚을 수 없다.
+     * **기동 직후에만** 부른다 — 시계가 흐른 뒤에 옮기면 그전에 낸 사실들과 시간축이 어긋난다.
+     */
+    setClockOrigin?(originMs: number): void;
     getSnapshot(): StateSnapshot;
     onEvent(handler: EventHandler): Unsubscribe;
     dispatch(cmd: Command): CommandAck;

package/dist/contract.js

@@ -631,6 +631,12 @@ export const OP_EVENT = {
 export const ENERGY_EVENT = {
     /** 계량 도착 — 그 시점의 유효전력·누적량. 15분 수요 구간에 누적된다. */
     measured: 'energy.measured',
+    /**
+     * 설비의 에너지 상태 — 발전·저장·감축 여지·개폐 위치.
+     *
+     * 계량과 다른 사건으로 둔다: 계량은 구간에 **누적**되고 이것은 그 설비의 **지금**을 바꾼다.
+     */
+    equipment: 'energy.equipment',
     /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
     demandWindow: 'energy.demand.window',
     /**

package/dist/ems-kernel.d.ts

@@ -70,6 +70,21 @@ export declare class EmsKernel extends FlowEngine {
      * 적는다(상위 `apply` 의 재방출 규약과 같은 이유).
      */
     apply(envelope: CanonicalEnvelope): void;
+    /**
+     * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
+     *
+     * ── 계량과 갈라 두는 이유 ──────────────────────────────────────────────────
+     * 계량은 **수요 구간에 누적**되는 표본이고, 이것들은 그 설비의 **지금**이다. 같은 문으로 넣으면
+     * 태양광 발전량이 부하 구간에 더해지거나 충전율이 요금 판정에 섞인다.
+     *
+     * 모르는 설비의 상태는 **버리지 않고 세어 둔다** — 원천에 우리 모델이 모르는 설비가 있다는 것은
+     * 그 자체로 알아야 할 사실이다(상위 커널의 `unhandled` 와 같은 규율).
+     *
+     * 온 값만 덮는다: 보내지 않은 필드는 그대로 둔다(없는 값을 0 으로 만들지 않는다).
+     */
+    private applyEquipmentEnergy;
+    /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
+    private unknownEquipmentReports;
     private ingestMeasured;
     private openWindow;
     /**

package/dist/ems-kernel.js

@@ -173,8 +173,49 @@ export class EmsKernel extends FlowEngine {
             this.ingestMeasured(envelope);
             return;
         }
+        if (envelope.eventType === ENERGY_EVENT.equipment) {
+            this.applyEquipmentEnergy(envelope);
+            return;
+        }
         super.apply(envelope);
     }
+    /**
+     * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
+     *
+     * ── 계량과 갈라 두는 이유 ──────────────────────────────────────────────────
+     * 계량은 **수요 구간에 누적**되는 표본이고, 이것들은 그 설비의 **지금**이다. 같은 문으로 넣으면
+     * 태양광 발전량이 부하 구간에 더해지거나 충전율이 요금 판정에 섞인다.
+     *
+     * 모르는 설비의 상태는 **버리지 않고 세어 둔다** — 원천에 우리 모델이 모르는 설비가 있다는 것은
+     * 그 자체로 알아야 할 사실이다(상위 커널의 `unhandled` 와 같은 규율).
+     *
+     * 온 값만 덮는다: 보내지 않은 필드는 그대로 둔다(없는 값을 0 으로 만들지 않는다).
+     */
+    applyEquipmentEnergy(envelope) {
+        const d = envelope.data;
+        const id = String(d?.equipmentId ?? '').trim();
+        const eq = id ? this.equipment.get(id) : undefined;
+        if (!eq) {
+            this.unknownEquipmentReports++;
+            return;
+        }
+        const put = (k) => {
+            const v = d[k];
+            if (v !== undefined)
+                eq[k] = v;
+        };
+        put('generatedKW');
+        put('exportKW');
+        put('soc');
+        put('chargeKW');
+        put('dischargeKW');
+        put('curtailable');
+        put('minKW');
+        put('position');
+        this.revision++;
+    }
+    /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
+    unknownEquipmentReports = 0;
     ingestMeasured(envelope) {
         const d = envelope.data;
         /* 시각은 **계측이 말한 것**이 먼저다(`data.at`) — 봉투 시각은 전달 시각일 수 있다.
@@ -276,12 +317,23 @@ export class EmsKernel extends FlowEngine {
                  * kW 를 못 읽은 경우(계기 오류·필드 누락)가 실제로 있고, 그것은 「아무것도 오지 않았다」와
                  * 다르다. 무엇이 왔는지는 지점별 `samplesInWindow` 가 답한다.
                  */
-                ...(w.samples === 0 ? { observedAbsence: 'no-load-samples' } : {})
+                ...(w.samples === 0 ? { observedAbsence: 'no-load-samples' } : {}),
+                /*
+                 * **만든 값이면 그렇게 말한다.** 상태에만 표시하고 사실에는 빠뜨리면, 저널을 읽는 쪽
+                 * (성과·이력·보고서)이 시뮬레이션의 수를 계측으로 읽는다 — 값이 그럴듯할수록 위험하다.
+                 */
+                ...(w.derived ? { derived: true } : {})
             });
             /* 피크는 **마감된 구간**으로만 갱신한다 — 열린 구간의 최대는 아직 확정이 아니다. */
             if (w.maxKW !== undefined && (this.peak === undefined || w.maxKW > this.peak.kW)) {
                 this.peak = { kW: w.maxKW, windowStartMs: w.startMs };
-                this.emitOp(ENERGY_EVENT.peak, { kW: w.maxKW, windowStartMs: w.startMs, ...(w.contractKW !== undefined ? { contractKW: w.contractKW } : {}) });
+                this.emitOp(ENERGY_EVENT.peak, {
+                    kW: w.maxKW,
+                    windowStartMs: w.startMs,
+                    ...(w.contractKW !== undefined ? { contractKW: w.contractKW } : {}),
+                    /* 피크도 그 구간에서 왔다 — 구간이 만든 값이면 피크도 만든 값이다. */
+                    ...(w.derived ? { derived: true } : {})
+                });
             }
             /* 다음 구간은 표본이 올 때 연다 — 미리 열면 오지 않은 구간을 존재하는 것처럼 만든다. */
             this.open = undefined;
@@ -419,9 +471,18 @@ export class EmsKernel extends FlowEngine {
     }
     tick(dtMs) {
         super.tick(dtMs);
-        /* 부하를 먼저 만들고 마감한다 — 마감이 먼저면 마지막 값이 다음 구간으로 밀린다. */
-        this.deriveLoad(this.clockMs);
-        this.closeDue(this.clockMs);
+        /*
+         * 구간은 **이 트윈의 「지금」**으로 잡는다(`nowMs`) — 경과 시간(`clockMs`)이 아니다.
+         *
+         * 예전에는 경과 시간을 그대로 넘겨서 시뮬 트윈의 수요 구간이 **1970년**에 섰다. 계측 경로는
+         * 계측이 말한 절대 시각을 쓰므로, 두 경로가 서로 다른 시간축에 값을 넣고 있었던 셈이다.
+         * 요금은 벽시계의 15분으로 매겨지니 그 경계에 서야 견줄 수 있다.
+         *
+         * 부하를 먼저 만들고 마감한다 — 마감이 먼저면 마지막 값이 다음 구간으로 밀린다.
+         */
+        const at = this.nowMs();
+        this.deriveLoad(at);
+        this.closeDue(at);
     }
     getSnapshot() {
         const snap = super.getSnapshot();
@@ -439,6 +500,7 @@ export class EmsKernel extends FlowEngine {
             closed: this.closed.map(w => ({ ...w })),
             closedTotal: this.closedTotal,
             ...(this.peak ? { peakSince: { ...this.peak } } : {}),
+            ...(this.unknownEquipmentReports ? { unknownEquipment: this.unknownEquipmentReports } : {}),
             ...(contractKW !== undefined ? { contractKW } : {}),
             /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
             ...(this.flowRequests.size

package/dist/energy-ingest.d.ts

@@ -37,3 +37,26 @@ export declare function isEnergyRecord(record: unknown): boolean;
  * 페이로드를 먼저 보고, 저널·시간여행은 봉투를 본다 — 둘이 다르면 같은 사실이 두 시각을 갖는다.
  */
 export declare function ingestEnergyRecords(records: EnergyRecord | EnergyRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
+/** 정규 설비 에너지 레코드 — 커넥터가 이 모양으로 맞춰 준다(필드 이름이 계약이다). */
+export interface EnergyEquipmentRecord {
+    equipmentId: string;
+    at?: string;
+    generatedKW?: number;
+    exportKW?: number;
+    soc?: number;
+    chargeKW?: number;
+    dischargeKW?: number;
+    curtailable?: boolean;
+    minKW?: number;
+    position?: string;
+}
+/** 이 레코드가 설비 에너지 상태인가 — 라우팅 판정을 한 곳에 둔다. */
+export declare function isEnergyEquipmentRecord(record: unknown): boolean;
+/**
+ * 설비 에너지 레코드 → 봉투. 계량과 같은 규율이다: 지어낼 수 없는 것이 빠지면 거부하고, 거부한 것은
+ * 이유와 함께 돌려준다.
+ *
+ * **값이 하나도 없는 레코드는 거부한다** — 계량과 다른 점이다. 계량은 「응답했다」는 사실 자체가
+ * 관측이지만(그래서 kW 없는 표본을 받는다), 여기서는 바꿀 상태가 없는 것을 사실로 적을 이유가 없다.
+ */
+export declare function ingestEnergyEquipmentRecords(records: EnergyEquipmentRecord | EnergyEquipmentRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;

package/dist/energy-ingest.js

@@ -89,3 +89,106 @@ export function ingestEnergyRecords(records, opts) {
     }
     return { accepted, rejected };
 }
+/** 개폐 위치의 값 — 표준이 정한 넷. 그 밖의 낱말은 받지 않는다(뭉개면 없는 확신이 생긴다). */
+const POSITIONS = new Set(['open', 'closed', 'intermediate', 'bad']);
+/** 이 레코드가 설비 에너지 상태인가 — 라우팅 판정을 한 곳에 둔다. */
+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;
+}
+/**
+ * 설비 에너지 레코드 → 봉투. 계량과 같은 규율이다: 지어낼 수 없는 것이 빠지면 거부하고, 거부한 것은
+ * 이유와 함께 돌려준다.
+ *
+ * **값이 하나도 없는 레코드는 거부한다** — 계량과 다른 점이다. 계량은 「응답했다」는 사실 자체가
+ * 관측이지만(그래서 kW 없는 표본을 받는다), 여기서는 바꿀 상태가 없는 것을 사실로 적을 이유가 없다.
+ */
+export function ingestEnergyEquipmentRecords(records, opts) {
+    const arr = Array.isArray(records) ? records : records ? [records] : [];
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const record of arr) {
+        const errors = [];
+        const r = record;
+        const equipmentId = String(r?.equipmentId ?? '').trim();
+        if (!equipmentId)
+            errors.push('equipmentId 없음 — 어느 설비의 상태인지 모르는 값은 실을 수 없다');
+        const at = String(r?.at ?? '').trim() || opts.defaultEventTime;
+        const atMs = at ? Date.parse(at) : Number.NaN;
+        if (!Number.isFinite(atMs))
+            errors.push('at 없음/형식 오류 — 지금 시각으로 메우면 언제의 상태인지 알 수 없다');
+        const num = (v, name, min, max) => {
+            if (v === undefined || v === null || v === '')
+                return undefined;
+            const n = Number(v);
+            if (!Number.isFinite(n)) {
+                errors.push(`${name} 가 수가 아니다: ${JSON.stringify(v)}`);
+                return undefined;
+            }
+            if (min !== undefined && n < min) {
+                errors.push(`${name} 가 ${min} 보다 작다: ${n}`);
+                return undefined;
+            }
+            if (max !== undefined && n > max) {
+                errors.push(`${name} 가 ${max} 보다 크다: ${n}`);
+                return undefined;
+            }
+            return n;
+        };
+        const generatedKW = num(r?.generatedKW, 'generatedKW', 0);
+        const exportKW = num(r?.exportKW, 'exportKW');
+        /* 충전율은 백분율이다 — 범위를 벗어난 값은 받지 않는다(단위를 잘못 매핑한 커넥터를 조용히 통과시키면
+           「배터리가 380% 찼다」가 화면에 뜬다). */
+        const soc = num(r?.soc, 'soc', 0, 100);
+        const chargeKW = num(r?.chargeKW, 'chargeKW', 0);
+        const dischargeKW = num(r?.dischargeKW, 'dischargeKW', 0);
+        const minKW = num(r?.minKW, 'minKW', 0);
+        let curtailable;
+        if (r?.curtailable !== undefined && r?.curtailable !== null) {
+            if (typeof r.curtailable !== 'boolean')
+                errors.push(`curtailable 가 참/거짓이 아니다: ${JSON.stringify(r.curtailable)}`);
+            else
+                curtailable = r.curtailable;
+        }
+        let position;
+        if (r?.position !== undefined && r?.position !== null && r?.position !== '') {
+            const p = String(r.position);
+            if (!POSITIONS.has(p))
+                errors.push(`position 이 표준 값이 아니다(open·closed·intermediate·bad): ${JSON.stringify(r.position)}`);
+            else
+                position = p;
+        }
+        const values = { generatedKW, exportKW, soc, chargeKW, dischargeKW, curtailable, minKW, position };
+        if (!errors.length && Object.values(values).every(v => v === undefined)) {
+            errors.push('바꿀 상태가 하나도 없다 — 값 없는 보고는 사실로 적을 것이 없다');
+        }
+        if (errors.length) {
+            rejected.push({ record, errors });
+            continue;
+        }
+        const eventTime = new Date(atMs).toISOString();
+        const data = {
+            equipmentId,
+            at: eventTime,
+            ...(generatedKW !== undefined ? { generatedKW } : {}),
+            ...(exportKW !== undefined ? { exportKW } : {}),
+            ...(soc !== undefined ? { soc } : {}),
+            ...(chargeKW !== undefined ? { chargeKW } : {}),
+            ...(dischargeKW !== undefined ? { dischargeKW } : {}),
+            ...(curtailable !== undefined ? { curtailable } : {}),
+            ...(minKW !== undefined ? { minKW } : {}),
+            ...(position !== undefined ? { position } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-energy-eq-${++seq}`,
+            eventType: ENERGY_EVENT.equipment,
+            eventTime,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}

package/dist/flow-engine.d.ts

@@ -285,6 +285,20 @@ export declare abstract class FlowEngine implements TwinKernel {
     orders: Map<string, FlowOrder>;
     revision: number;
     clockMs: number;
+    /**
+     * 시각의 **기준점** — 이 트윈의 「지금」은 `originMs + clockMs` 다.
+     *
+     * ── 왜 고정 상수가 아닌가 (2026-08-15) ─────────────────────────────────────
+     * 기준점이 `BASE_EPOCH` 하나로 고정돼 있어서, 시뮬 트윈의 저널 시각이 **재기동마다 되감겼다.**
+     * 며칠을 돈 트윈의 사건들이 전부 `2026-01-01T00:00:xx` 에 몰려 있었고, 그래서 「언제 있었던 일인가」를
+     * 되짚을 수 없었다. 실 시각으로 창을 자르는 성과·이력 질의에는 그 트윈이 아예 보이지 않는다.
+     *
+     * 에너지에서는 더 아프다: 수요 구간은 벽시계의 15분에 맞춰 끊어야 요금과 견줄 수 있는데, 기준점이
+     * 가짜면 그 구간도 가짜 시각에 선다.
+     *
+     * 기본값은 그대로 둔다(시험·결정성). 살아 있는 시뮬 트윈을 세우는 호스트가 실제 시각으로 옮긴다.
+     */
+    protected originMs: number;
     protected rng: Rng;
     protected policy: AllocationPolicy;
     /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
@@ -452,6 +466,15 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 아직 아무것도 못 들었으면 시뮬 기준으로 떨어진다(그때는 판정할 사실도 없다).
      */
     protected nowMs(): number;
+    /**
+     * 시각 기준점을 세운다 — **살아 있는 시뮬 트윈은 실제 시각 위에서 돈다.**
+     *
+     * 세우는 쪽(호스트)이 기동 순간의 실제 시각을 준다. 재기동하면 그만큼 앞으로 뛰는데, 그것이 사실이다
+     * (그 사이 이 트윈은 돌지 않았고, 저널의 빈 구간이 그 사실을 말한다).
+     *
+     * 이미 시계가 흐른 뒤에 옮기면 그전에 낸 사실들과 시간축이 어긋나므로 **기동 직후에만** 부른다.
+     */
+    setClockOrigin(originMs: number): void;
     protected now(): string;
     /**
      * 자극이 선언한 **약속**을 오더 필드로 — 표준 `OperationsRequest.Priority`·`StartTime`·`EndTime`.

package/dist/flow-engine.js

@@ -207,6 +207,23 @@ export function computeOee(c, nowMs) {
         runMs: c.runMs, setupMs: c.setupMs, downMs: c.downMs, idleMs: Math.max(0, uptime - c.runMs), goodCount: c.goodCount, scrapCount: c.scrapCount
     };
 }
+/**
+ * 에너지 능력이 선언한 상태 필드를 스냅샷에 싣는다 — **온 것만.**
+ *
+ * 능력 계약이 이 필드들을 관측으로 선언해 두었는데 투영이 싣지 않으면, 값이 커널 안에서만 살고
+ * 화면·성과·저널 어디에도 나타나지 않는다(실제로 그랬다: 값을 적었는데 스냅샷에 없었다).
+ *
+ * 값이 없으면 **키를 만들지 않는다** — 에너지에서 「모른다」와 「0 이다」는 요금이 갈리는 차이다.
+ */
+function energyFieldsOf(m) {
+    const out = {};
+    const src = m;
+    for (const k of ['generatedKW', 'exportKW', 'soc', 'chargeKW', 'dischargeKW', 'curtailable', 'minKW', 'position']) {
+        if (src[k] !== undefined)
+            out[k] = src[k];
+    }
+    return out;
+}
 export class FlowEngine {
     tenantId;
     locations = new Map();
@@ -227,6 +244,20 @@ export class FlowEngine {
     orders = new Map();
     revision = 0;
     clockMs = 0;
+    /**
+     * 시각의 **기준점** — 이 트윈의 「지금」은 `originMs + clockMs` 다.
+     *
+     * ── 왜 고정 상수가 아닌가 (2026-08-15) ─────────────────────────────────────
+     * 기준점이 `BASE_EPOCH` 하나로 고정돼 있어서, 시뮬 트윈의 저널 시각이 **재기동마다 되감겼다.**
+     * 며칠을 돈 트윈의 사건들이 전부 `2026-01-01T00:00:xx` 에 몰려 있었고, 그래서 「언제 있었던 일인가」를
+     * 되짚을 수 없었다. 실 시각으로 창을 자르는 성과·이력 질의에는 그 트윈이 아예 보이지 않는다.
+     *
+     * 에너지에서는 더 아프다: 수요 구간은 벽시계의 15분에 맞춰 끊어야 요금과 견줄 수 있는데, 기준점이
+     * 가짜면 그 구간도 가짜 시각에 선다.
+     *
+     * 기본값은 그대로 둔다(시험·결정성). 살아 있는 시뮬 트윈을 세우는 호스트가 실제 시각으로 옮긴다.
+     */
+    originMs = BASE_EPOCH;
     rng = mulberry32(1);
     policy;
     /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
@@ -843,7 +874,7 @@ export class FlowEngine {
             }),
             items: [...this.items.values()].map(i => this.itemState(i)),
             equipment: [...this.equipment.values()].map(m => {
-                const s = { id: m.id, kind: m.kind, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), ...(m.testResults ? { testResults: m.testResults } : {}), capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: 'master', ...(this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}), ...this.effectivePart(m), ...(this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}) };
+                const s = { id: m.id, kind: m.kind, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), ...(m.testResults ? { testResults: m.testResults } : {}), capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: 'master', ...(this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}), ...this.effectivePart(m), ...(this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}), ...energyFieldsOf(m) };
                 const t = m.taskId ? this.tasks.get(m.taskId) : undefined;
                 if (t && t.status === 'in-progress' && t.intent !== 'process')
                     s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
@@ -1016,7 +1047,20 @@ export class FlowEngine {
      */
     nowMs() {
         const observed = this.observeMode ? this.observer?.lastObservedMs : undefined;
-        return observed ?? BASE_EPOCH + this.clockMs;
+        return observed ?? this.originMs + this.clockMs;
+    }
+    /**
+     * 시각 기준점을 세운다 — **살아 있는 시뮬 트윈은 실제 시각 위에서 돈다.**
+     *
+     * 세우는 쪽(호스트)이 기동 순간의 실제 시각을 준다. 재기동하면 그만큼 앞으로 뛰는데, 그것이 사실이다
+     * (그 사이 이 트윈은 돌지 않았고, 저널의 빈 구간이 그 사실을 말한다).
+     *
+     * 이미 시계가 흐른 뒤에 옮기면 그전에 낸 사실들과 시간축이 어긋나므로 **기동 직후에만** 부른다.
+     */
+    setClockOrigin(originMs) {
+        if (!Number.isFinite(originMs))
+            throw new Error('clock origin must be a finite epoch millisecond value');
+        this.originMs = originMs;
     }
     now() { return new Date(this.nowMs()).toISOString(); }
     /**

package/dist/index.d.ts

@@ -29,8 +29,8 @@ export { WmsKernel } from './kernel.ts';
 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 } from './energy-ingest.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 type { EnergyRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
+export type { EnergyRecord, EnergyEquipmentRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
 export * from './vocabulary.ts';

package/dist/index.js

@@ -29,7 +29,7 @@ export { WmsKernel } from "./kernel.js";
 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 } from "./energy-ingest.js";
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from "./energy-ingest.js";
 export { attributeEnergy, energyIntensity, energyOfWindows } from "./energy-attribution.js";
 /* 에너지 상태 타입은 **계약**에 있다(상태의 모양은 계약이다) — contract 의 `export *` 가 이미 낸다. */
 export * from "./vocabulary.js";

package/dist-cjs/index.cjs

@@ -107,7 +107,9 @@ __export(index_exports, {
   inWorkCalendar: () => inWorkCalendar,
   inWorkCalendarAt: () => inWorkCalendarAt,
   ingest: () => ingest,
+  ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyRecord: () => isEnergyRecord,
   isEquipmentLevel: () => isEquipmentLevel,
   isoDurationHours: () => isoDurationHours,
@@ -483,6 +485,12 @@ var OP_EVENT = {
 var ENERGY_EVENT = {
   /** 계량 도착 — 그 시점의 유효전력·누적량. 15분 수요 구간에 누적된다. */
   measured: "energy.measured",
+  /**
+   * 설비의 에너지 상태 — 발전·저장·감축 여지·개폐 위치.
+   *
+   * 계량과 다른 사건으로 둔다: 계량은 구간에 **누적**되고 이것은 그 설비의 **지금**을 바꾼다.
+   */
+  equipment: "energy.equipment",
   /** 수요 구간 마감 — 그 구간의 최대 수요가 확정된다(요금의 단위). */
   demandWindow: "energy.demand.window",
   /**
@@ -2789,6 +2797,14 @@ function computeOee(c, nowMs) {
     scrapCount: c.scrapCount
   };
 }
+function energyFieldsOf(m) {
+  const out = {};
+  const src = m;
+  for (const k of ["generatedKW", "exportKW", "soc", "chargeKW", "dischargeKW", "curtailable", "minKW", "position"]) {
+    if (src[k] !== void 0) out[k] = src[k];
+  }
+  return out;
+}
 var FlowEngine = class {
   tenantId;
   locations = /* @__PURE__ */ new Map();
@@ -2809,6 +2825,20 @@ var FlowEngine = class {
   orders = /* @__PURE__ */ new Map();
   revision = 0;
   clockMs = 0;
+  /**
+   * 시각의 **기준점** — 이 트윈의 「지금」은 `originMs + clockMs` 다.
+   *
+   * ── 왜 고정 상수가 아닌가 (2026-08-15) ─────────────────────────────────────
+   * 기준점이 `BASE_EPOCH` 하나로 고정돼 있어서, 시뮬 트윈의 저널 시각이 **재기동마다 되감겼다.**
+   * 며칠을 돈 트윈의 사건들이 전부 `2026-01-01T00:00:xx` 에 몰려 있었고, 그래서 「언제 있었던 일인가」를
+   * 되짚을 수 없었다. 실 시각으로 창을 자르는 성과·이력 질의에는 그 트윈이 아예 보이지 않는다.
+   *
+   * 에너지에서는 더 아프다: 수요 구간은 벽시계의 15분에 맞춰 끊어야 요금과 견줄 수 있는데, 기준점이
+   * 가짜면 그 구간도 가짜 시각에 선다.
+   *
+   * 기본값은 그대로 둔다(시험·결정성). 살아 있는 시뮬 트윈을 세우는 호스트가 실제 시각으로 옮긴다.
+   */
+  originMs = BASE_EPOCH;
   rng = mulberry32(1);
   policy;
   /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
@@ -3375,7 +3405,7 @@ var FlowEngine = class {
       }),
       items: [...this.items.values()].map((i) => this.itemState(i)),
       equipment: [...this.equipment.values()].map((m) => {
-        const s = { id: m.id, kind: m.kind, location: m.location, ...m.homeLocation ? { homeLocation: m.homeLocation } : {}, status: m.status, taskId: m.taskId ?? void 0, oee: this.oeeOf(m), held: m.held, ...m.properties ? { properties: m.properties } : {}, ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}, ...m.testResults ? { testResults: m.testResults } : {}, capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: "master", ...this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}, ...this.effectivePart(m), ...this.shiftOf(m) ? { shift: this.shiftOf(m) } : {} };
+        const s = { id: m.id, kind: m.kind, location: m.location, ...m.homeLocation ? { homeLocation: m.homeLocation } : {}, status: m.status, taskId: m.taskId ?? void 0, oee: this.oeeOf(m), held: m.held, ...m.properties ? { properties: m.properties } : {}, ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}, ...m.testResults ? { testResults: m.testResults } : {}, capability: this.capabilityOfResource(m, m.kind ? [m.kind] : [], this.classDefs.equipment), origin: "master", ...this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}, ...this.effectivePart(m), ...this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}, ...energyFieldsOf(m) };
         const t = m.taskId ? this.tasks.get(m.taskId) : void 0;
         if (t && t.status === "in-progress" && t.intent !== "process") s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
         return s;
@@ -3529,7 +3559,19 @@ var FlowEngine = class {
    */
   nowMs() {
     const observed = this.observeMode ? this.observer?.lastObservedMs : void 0;
-    return observed ?? BASE_EPOCH + this.clockMs;
+    return observed ?? this.originMs + this.clockMs;
+  }
+  /**
+   * 시각 기준점을 세운다 — **살아 있는 시뮬 트윈은 실제 시각 위에서 돈다.**
+   *
+   * 세우는 쪽(호스트)이 기동 순간의 실제 시각을 준다. 재기동하면 그만큼 앞으로 뛰는데, 그것이 사실이다
+   * (그 사이 이 트윈은 돌지 않았고, 저널의 빈 구간이 그 사실을 말한다).
+   *
+   * 이미 시계가 흐른 뒤에 옮기면 그전에 낸 사실들과 시간축이 어긋나므로 **기동 직후에만** 부른다.
+   */
+  setClockOrigin(originMs) {
+    if (!Number.isFinite(originMs)) throw new Error("clock origin must be a finite epoch millisecond value");
+    this.originMs = originMs;
   }
   now() {
     return new Date(this.nowMs()).toISOString();
@@ -5730,8 +5772,48 @@ var EmsKernel = class extends FlowEngine {
       this.ingestMeasured(envelope);
       return;
     }
+    if (envelope.eventType === ENERGY_EVENT.equipment) {
+      this.applyEquipmentEnergy(envelope);
+      return;
+    }
     super.apply(envelope);
   }
+  /**
+   * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.
+   *
+   * ── 계량과 갈라 두는 이유 ──────────────────────────────────────────────────
+   * 계량은 **수요 구간에 누적**되는 표본이고, 이것들은 그 설비의 **지금**이다. 같은 문으로 넣으면
+   * 태양광 발전량이 부하 구간에 더해지거나 충전율이 요금 판정에 섞인다.
+   *
+   * 모르는 설비의 상태는 **버리지 않고 세어 둔다** — 원천에 우리 모델이 모르는 설비가 있다는 것은
+   * 그 자체로 알아야 할 사실이다(상위 커널의 `unhandled` 와 같은 규율).
+   *
+   * 온 값만 덮는다: 보내지 않은 필드는 그대로 둔다(없는 값을 0 으로 만들지 않는다).
+   */
+  applyEquipmentEnergy(envelope) {
+    const d = envelope.data;
+    const id = String(d?.equipmentId ?? "").trim();
+    const eq = id ? this.equipment.get(id) : void 0;
+    if (!eq) {
+      this.unknownEquipmentReports++;
+      return;
+    }
+    const put = (k) => {
+      const v = d[k];
+      if (v !== void 0) eq[k] = v;
+    };
+    put("generatedKW");
+    put("exportKW");
+    put("soc");
+    put("chargeKW");
+    put("dischargeKW");
+    put("curtailable");
+    put("minKW");
+    put("position");
+    this.revision++;
+  }
+  /** 우리 모델이 모르는 설비가 상태를 보내 온 횟수 — 조용히 버리지 않는다. */
+  unknownEquipmentReports = 0;
   ingestMeasured(envelope) {
     const d = envelope.data;
     const atMs = [String(d?.at ?? ""), String(envelope.eventTime ?? "")].map((v) => Date.parse(v)).find((v) => Number.isFinite(v));
@@ -5802,11 +5884,22 @@ var EmsKernel = class extends FlowEngine {
          * kW 를 못 읽은 경우(계기 오류·필드 누락)가 실제로 있고, 그것은 「아무것도 오지 않았다」와
          * 다르다. 무엇이 왔는지는 지점별 `samplesInWindow` 가 답한다.
          */
-        ...w.samples === 0 ? { observedAbsence: "no-load-samples" } : {}
+        ...w.samples === 0 ? { observedAbsence: "no-load-samples" } : {},
+        /*
+         * **만든 값이면 그렇게 말한다.** 상태에만 표시하고 사실에는 빠뜨리면, 저널을 읽는 쪽
+         * (성과·이력·보고서)이 시뮬레이션의 수를 계측으로 읽는다 — 값이 그럴듯할수록 위험하다.
+         */
+        ...w.derived ? { derived: true } : {}
       });
       if (w.maxKW !== void 0 && (this.peak === void 0 || w.maxKW > this.peak.kW)) {
         this.peak = { kW: w.maxKW, windowStartMs: w.startMs };
-        this.emitOp(ENERGY_EVENT.peak, { kW: w.maxKW, windowStartMs: w.startMs, ...w.contractKW !== void 0 ? { contractKW: w.contractKW } : {} });
+        this.emitOp(ENERGY_EVENT.peak, {
+          kW: w.maxKW,
+          windowStartMs: w.startMs,
+          ...w.contractKW !== void 0 ? { contractKW: w.contractKW } : {},
+          /* 피크도 그 구간에서 왔다 — 구간이 만든 값이면 피크도 만든 값이다. */
+          ...w.derived ? { derived: true } : {}
+        });
       }
       this.open = void 0;
     }
@@ -5926,8 +6019,9 @@ var EmsKernel = class extends FlowEngine {
   }
   tick(dtMs) {
     super.tick(dtMs);
-    this.deriveLoad(this.clockMs);
-    this.closeDue(this.clockMs);
+    const at = this.nowMs();
+    this.deriveLoad(at);
+    this.closeDue(at);
   }
   getSnapshot() {
     const snap = super.getSnapshot();
@@ -5943,6 +6037,7 @@ var EmsKernel = class extends FlowEngine {
       closed: this.closed.map((w) => ({ ...w })),
       closedTotal: this.closedTotal,
       ...this.peak ? { peakSince: { ...this.peak } } : {},
+      ...this.unknownEquipmentReports ? { unknownEquipment: this.unknownEquipmentReports } : {},
       ...contractKW !== void 0 ? { contractKW } : {},
       /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
       ...this.flowRequests.size ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) } : {}
@@ -6005,6 +6100,90 @@ function ingestEnergyRecords(records, opts) {
   }
   return { accepted, rejected };
 }
+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;
+}
+function ingestEnergyEquipmentRecords(records, opts) {
+  const arr = Array.isArray(records) ? records : records ? [records] : [];
+  const accepted = [];
+  const rejected = [];
+  let seq = 0;
+  for (const record of arr) {
+    const errors = [];
+    const r = record;
+    const equipmentId = String(r?.equipmentId ?? "").trim();
+    if (!equipmentId) errors.push("equipmentId \uC5C6\uC74C \u2014 \uC5B4\uB290 \uC124\uBE44\uC758 \uC0C1\uD0DC\uC778\uC9C0 \uBAA8\uB974\uB294 \uAC12\uC740 \uC2E4\uC744 \uC218 \uC5C6\uB2E4");
+    const at = String(r?.at ?? "").trim() || opts.defaultEventTime;
+    const atMs = at ? Date.parse(at) : Number.NaN;
+    if (!Number.isFinite(atMs)) errors.push("at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC9C0\uAE08 \uC2DC\uAC01\uC73C\uB85C \uBA54\uC6B0\uBA74 \uC5B8\uC81C\uC758 \uC0C1\uD0DC\uC778\uC9C0 \uC54C \uC218 \uC5C6\uB2E4");
+    const num = (v, name, min, max) => {
+      if (v === void 0 || v === null || v === "") return void 0;
+      const n = Number(v);
+      if (!Number.isFinite(n)) {
+        errors.push(`${name} \uAC00 \uC218\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+        return void 0;
+      }
+      if (min !== void 0 && n < min) {
+        errors.push(`${name} \uAC00 ${min} \uBCF4\uB2E4 \uC791\uB2E4: ${n}`);
+        return void 0;
+      }
+      if (max !== void 0 && n > max) {
+        errors.push(`${name} \uAC00 ${max} \uBCF4\uB2E4 \uD06C\uB2E4: ${n}`);
+        return void 0;
+      }
+      return n;
+    };
+    const generatedKW = num(r?.generatedKW, "generatedKW", 0);
+    const exportKW = num(r?.exportKW, "exportKW");
+    const soc = num(r?.soc, "soc", 0, 100);
+    const chargeKW = num(r?.chargeKW, "chargeKW", 0);
+    const dischargeKW = num(r?.dischargeKW, "dischargeKW", 0);
+    const minKW = num(r?.minKW, "minKW", 0);
+    let curtailable;
+    if (r?.curtailable !== void 0 && r?.curtailable !== null) {
+      if (typeof r.curtailable !== "boolean") errors.push(`curtailable \uAC00 \uCC38/\uAC70\uC9D3\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(r.curtailable)}`);
+      else curtailable = r.curtailable;
+    }
+    let position;
+    if (r?.position !== void 0 && r?.position !== null && r?.position !== "") {
+      const p = String(r.position);
+      if (!POSITIONS.has(p)) errors.push(`position \uC774 \uD45C\uC900 \uAC12\uC774 \uC544\uB2C8\uB2E4(open\xB7closed\xB7intermediate\xB7bad): ${JSON.stringify(r.position)}`);
+      else position = p;
+    }
+    const values = { generatedKW, exportKW, soc, chargeKW, dischargeKW, curtailable, minKW, position };
+    if (!errors.length && Object.values(values).every((v) => v === void 0)) {
+      errors.push("\uBC14\uAFC0 \uC0C1\uD0DC\uAC00 \uD558\uB098\uB3C4 \uC5C6\uB2E4 \u2014 \uAC12 \uC5C6\uB294 \uBCF4\uACE0\uB294 \uC0AC\uC2E4\uB85C \uC801\uC744 \uAC83\uC774 \uC5C6\uB2E4");
+    }
+    if (errors.length) {
+      rejected.push({ record, errors });
+      continue;
+    }
+    const eventTime = new Date(atMs).toISOString();
+    const data = {
+      equipmentId,
+      at: eventTime,
+      ...generatedKW !== void 0 ? { generatedKW } : {},
+      ...exportKW !== void 0 ? { exportKW } : {},
+      ...soc !== void 0 ? { soc } : {},
+      ...chargeKW !== void 0 ? { chargeKW } : {},
+      ...dischargeKW !== void 0 ? { dischargeKW } : {},
+      ...curtailable !== void 0 ? { curtailable } : {},
+      ...minKW !== void 0 ? { minKW } : {},
+      ...position !== void 0 ? { position } : {}
+    };
+    accepted.push({
+      eventId: `${opts.tenantId}-energy-eq-${++seq}`,
+      eventType: ENERGY_EVENT.equipment,
+      eventTime,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
 
 // src/energy-attribution.ts
 var near = (a, b, eps = 1e-9) => Math.abs(a - b) <= eps;
@@ -6288,7 +6467,9 @@ function retiredVocabularyIn(line) {
   inWorkCalendar,
   inWorkCalendarAt,
   ingest,
+  ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
+  isEnergyEquipmentRecord,
   isEnergyRecord,
   isEquipmentLevel,
   isoDurationHours,

package/package.json

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