@operato/twin-kernel 0.7.66 → 0.7.67

package/dist/ems-kernel.d.ts

@@ -93,6 +93,23 @@ export declare class EmsKernel extends FlowEngine {
      * 계측 자체는 원천 시각을 달고 있어서 화면의 순간값은 정상으로 보였다 — 그래서 조용한 결함이었다.
      * 저널을 기간으로 계산하는 쪽(성과·요금·피더 배분)은 그 트윈에서 영원히 아무것도 찾지 못했다.
      */
+    /**
+     * 이 커널이 따로 드는 상태를 재개점에 담는다 — 계량 지점 · 수요 구간 · 월 최고 (2026-08-27).
+     *
+     * ── 왜 담아야 하나 ──────────────────────────────────────────────────────────
+     * 이 값들은 계측을 모아 **트윈이 만든 것**이다. 발전소는 「우리 트윈이 정한 15분 구간의 최대 수요」를
+     * 갖고 있지 않으므로 되풀어 주지 못한다. 담지 않으면 중간 저장본에서 이어 처리할 때 그만큼이
+     * 조용히 사라지고, 과거의 요금 근거를 말할 수 없게 된다.
+     *
+     * ── 무엇을 담지 않나 ────────────────────────────────────────────────────────
+     * 같은 구간에 제안을 이미 냈는지(`suggestedFor`)와 다른 트윈의 설비 상태(`peerStatus`)는 담지 않는다.
+     * 앞의 것은 브로드캐스팅을 줄이려는 표시일 뿐이고, 뒤의 것은 호스트가 매번 다시 넣어 준다.
+     * 구간 길이(`windowMs`)도 담지 않는다 — 그것은 선언에서 오는 값이고, 담으면 선언을 고쳐도 옛 값이
+     * 살아남는다.
+     */
+    serializeDomain(): unknown;
+    /** 재개점에서 되돌린다 — 담기지 않은 칸은 건드리지 않는다(빈 값으로 덮지 않는다). */
+    restoreDomain(raw: unknown): void;
     apply(envelope: CanonicalEnvelope): void;
     /**
      * 설비가 낸 자기 에너지 상태를 그 설비에 적는다 — 발전·저장·감축 여지·개폐 위치.

package/dist/ems-kernel.js

@@ -212,6 +212,50 @@ export class EmsKernel extends FlowEngine {
      * 계측 자체는 원천 시각을 달고 있어서 화면의 순간값은 정상으로 보였다 — 그래서 조용한 결함이었다.
      * 저널을 기간으로 계산하는 쪽(성과·요금·피더 배분)은 그 트윈에서 영원히 아무것도 찾지 못했다.
      */
+    /**
+     * 이 커널이 따로 드는 상태를 재개점에 담는다 — 계량 지점 · 수요 구간 · 월 최고 (2026-08-27).
+     *
+     * ── 왜 담아야 하나 ──────────────────────────────────────────────────────────
+     * 이 값들은 계측을 모아 **트윈이 만든 것**이다. 발전소는 「우리 트윈이 정한 15분 구간의 최대 수요」를
+     * 갖고 있지 않으므로 되풀어 주지 못한다. 담지 않으면 중간 저장본에서 이어 처리할 때 그만큼이
+     * 조용히 사라지고, 과거의 요금 근거를 말할 수 없게 된다.
+     *
+     * ── 무엇을 담지 않나 ────────────────────────────────────────────────────────
+     * 같은 구간에 제안을 이미 냈는지(`suggestedFor`)와 다른 트윈의 설비 상태(`peerStatus`)는 담지 않는다.
+     * 앞의 것은 브로드캐스팅을 줄이려는 표시일 뿐이고, 뒤의 것은 호스트가 매번 다시 넣어 준다.
+     * 구간 길이(`windowMs`)도 담지 않는다 — 그것은 선언에서 오는 값이고, 담으면 선언을 고쳐도 옛 값이
+     * 살아남는다.
+     */
+    serializeDomain() {
+        return {
+            points: [...this.points.values()],
+            open: this.open,
+            closed: this.closed,
+            closedTotal: this.closedTotal,
+            peak: this.peak,
+            generationHeardAtMs: [...this.generationHeardAtMs.entries()].map(([id, atMs]) => ({ id, atMs }))
+        };
+    }
+    /** 재개점에서 되돌린다 — 담기지 않은 칸은 건드리지 않는다(빈 값으로 덮지 않는다). */
+    restoreDomain(raw) {
+        const d = raw;
+        if (!d || typeof d !== 'object')
+            return;
+        if (Array.isArray(d.points)) {
+            this.points = new Map(d.points.filter((p) => p?.id).map((p) => [String(p.id), p]));
+        }
+        if (d.open !== undefined)
+            this.open = d.open;
+        if (Array.isArray(d.closed))
+            this.closed = d.closed;
+        if (typeof d.closedTotal === 'number')
+            this.closedTotal = d.closedTotal;
+        if (d.peak !== undefined)
+            this.peak = d.peak;
+        if (Array.isArray(d.generationHeardAtMs)) {
+            this.generationHeardAtMs = new Map(d.generationHeardAtMs.filter((x) => x?.id).map((x) => [String(x.id), Number(x.atMs)]));
+        }
+    }
     apply(envelope) {
         if (envelope.eventType === ENERGY_EVENT.measured) {
             this.ingestMeasured(envelope);

package/dist/event-journal.d.ts

@@ -1,5 +1,24 @@
 import type { TwinModelDef, CanonicalEnvelope, StructureShift } from './contract.ts';
 import { type ProjectedState, type ReducerCheckpoint } from './state-projector.ts';
+/** 저장된 기록을 처리할 것 — 도메인 커널 또는 `StateProjector`. 계약은 넷뿐이다. */
+export interface JournalProjector {
+    apply(e: CanonicalEnvelope): void;
+    snapshot(): ProjectedState;
+    serialize(): ReducerCheckpoint;
+    restore(cp: ReducerCheckpoint): void;
+    /** 공장이 바뀐 경계에서 구조를 갈아탄다 — 여러 마디를 이어 처리할 때만 쓴다(§`replaySegments`). */
+    adoptStructure(model: TwinModelDef): StructureShift;
+}
+/** 어떤 종류로 처리할지 부르는 쪽이 말한다 — 모델에는 종류가 없다(호스트가 든다). */
+export interface ReplayOptions {
+    /** `wms` · `yms` · `mes` · `ems`. 없으면 도메인 규칙 없이 처리한다. */
+    kind?: string;
+    /** 생산 명세(`productionSpec`) — 도메인 커널이 받는다. */
+    productionSpec?: unknown;
+    /** 테넌트 — 커널 생성자가 받는다. 저장된 기록을 처리하는 데는 쓰이지 않지만 계약이 요구한다. */
+    tenantId?: string;
+}
+export declare function journalProjector(model: TwinModelDef, opts?: ReplayOptions): JournalProjector;
 export declare class EventJournal {
     private events;
     /** 이벤트 1건 기록(추가 전용). runtime/kernel 의 onEvent 에 연결. */
@@ -14,7 +33,7 @@ export declare class EventJournal {
     untilSimTime(iso: string): CanonicalEnvelope[];
 }
 /** 이벤트열 → 상태 재구성(시간여행). `model` = 그 시점의 트윈 모델(토폴로지·자원). */
-export declare function replay(model: TwinModelDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+export declare function replay(model: TwinModelDef, events: readonly CanonicalEnvelope[], opts?: ReplayOptions): ProjectedState;
 /**
  * **재개점에서 이어서 계산한다** — 0부터 다시 계산하지 않는다.
  *
@@ -29,12 +48,12 @@ export declare function replay(model: TwinModelDef, events: readonly CanonicalEn
  * 구조가 바뀐 구간은 여기서 다루지 않는다(`replaySegments` 의 몫이다) — 재개점은 **한 구조 안에서**
  * 이어 붙이는 것이다. 구조가 바뀌었으면 부르는 쪽이 그 경계에서 갈라야 한다.
  */
-export declare function replayFrom(model: TwinModelDef, checkpoint: ReducerCheckpoint, events: readonly CanonicalEnvelope[]): {
+export declare function replayFrom(model: TwinModelDef, checkpoint: ReducerCheckpoint, events: readonly CanonicalEnvelope[], opts?: ReplayOptions): {
     state: ProjectedState;
     checkpoint: ReducerCheckpoint;
 };
 /** 이벤트열을 계산하고 **재개점도 함께** 낸다 — 다음 번에 이어 붙일 수 있게. */
-export declare function replayWithCheckpoint(model: TwinModelDef, events: readonly CanonicalEnvelope[]): {
+export declare function replayWithCheckpoint(model: TwinModelDef, events: readonly CanonicalEnvelope[], opts?: ReplayOptions): {
     state: ProjectedState;
     checkpoint: ReducerCheckpoint;
 };
@@ -73,7 +92,7 @@ export interface SegmentShift extends StructureShift {
  *
  * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
  */
-export declare function replaySegments(segments: readonly StructureSegment[]): {
+export declare function replaySegments(segments: readonly StructureSegment[], opts?: ReplayOptions): {
     state: ProjectedState;
     shifts: SegmentShift[];
 };

package/dist/event-journal.js

@@ -7,6 +7,46 @@
  * (이벤트-소싱: 상태는 항상 이벤트열의 함수. state-projector 가 폴딩 함수.)
  */
 import { StateProjector } from "./state-projector.js";
+import { WmsKernel } from "./kernel.js";
+import { YmsKernel } from "./yms-kernel.js";
+import { MesKernel } from "./mes-kernel.js";
+import { EmsKernel } from "./ems-kernel.js";
+/**
+ * 저장된 기록으로 상태를 만드는 것 — **도메인 커널이 있으면 그것을 쓴다** (2026-08-27).
+ *
+ * ── 무엇이 틀렸나 ───────────────────────────────────────────────────────────
+ * 이 파일의 함수들이 `StateProjector` 하나만 세웠다. 그런데 트윈이 도는 동안 사건을 처리하는 것은
+ * 도메인 커널이다(호스트가 `new EmsKernel(...)` 을 세워 `apply` 를 부른다). 두 코드가 아는 사건이
+ * 다르다 — `StateProjector` 는 `energy.*` 를 「담을 줄 모르는 사건」으로 세기만 한다.
+ *
+ * 그래서 같은 저장 기록에서 두 답이 나왔다. 과거 시점을 물으면(`recover`) 발전량과 계량이 늘 비어
+ * 있었다. 받아서 저장까지 해 둔 값인데 읽는 쪽이 건너뛴 것이다.
+ *
+ * 종류를 모르면 `StateProjector` 를 쓴다 — 부르는 쪽이 종류를 말해 주지 않는 경우가 있고, 그때
+ * 아무 커널이나 골라 세우면 없는 규칙이 상태에 섞인다.
+ */
+const DOMAIN_KERNELS = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel };
+export function journalProjector(model, opts) {
+    const Kernel = opts?.kind ? DOMAIN_KERNELS[opts.kind] : undefined;
+    if (!Kernel)
+        return new StateProjector(model);
+    /*
+     * 라이브가 세우는 순서와 **같은 순서**로 세운다(호스트 `startLive`). 순서가 다르면 같은 코드라도
+     * 다른 답이 나온다 — 모델을 싣기 전에 사건이 들어오면 없는 자리에 담긴다.
+     */
+    const kernel = new Kernel(String(opts?.tenantId ?? 'replay'), undefined, opts?.productionSpec);
+    kernel.loadTwinModel(model);
+    /* 관측 구동임을 세울 때 말한다 — 말하지 않으면 커널이 시뮬레이션으로 여기고 원천의 틈에서 멈춘다. */
+    if (typeof kernel.observe === 'function')
+        kernel.observe();
+    return {
+        apply: (e) => kernel.apply(e),
+        snapshot: () => kernel.getSnapshot(),
+        serialize: () => kernel.observedCheckpoint(),
+        restore: (cp) => kernel.restoreObserved(cp),
+        adoptStructure: (m) => kernel.adoptStructure(m)
+    };
+}
 export class EventJournal {
     events = [];
     /** 이벤트 1건 기록(추가 전용). runtime/kernel 의 onEvent 에 연결. */
@@ -33,8 +73,8 @@ export class EventJournal {
     }
 }
 /** 이벤트열 → 상태 재구성(시간여행). `model` = 그 시점의 트윈 모델(토폴로지·자원). */
-export function replay(model, events) {
-    const proj = new StateProjector(model);
+export function replay(model, events, opts) {
+    const proj = journalProjector(model, opts);
     for (const e of events)
         proj.apply(e);
     return proj.snapshot();
@@ -53,16 +93,16 @@ export function replay(model, events) {
  * 구조가 바뀐 구간은 여기서 다루지 않는다(`replaySegments` 의 몫이다) — 재개점은 **한 구조 안에서**
  * 이어 붙이는 것이다. 구조가 바뀌었으면 부르는 쪽이 그 경계에서 갈라야 한다.
  */
-export function replayFrom(model, checkpoint, events) {
-    const proj = new StateProjector(model);
+export function replayFrom(model, checkpoint, events, opts) {
+    const proj = journalProjector(model, opts);
     proj.restore(checkpoint);
     for (const e of events)
         proj.apply(e);
     return { state: proj.snapshot(), checkpoint: proj.serialize() };
 }
 /** 이벤트열을 계산하고 **재개점도 함께** 낸다 — 다음 번에 이어 붙일 수 있게. */
-export function replayWithCheckpoint(model, events) {
-    const proj = new StateProjector(model);
+export function replayWithCheckpoint(model, events, opts) {
+    const proj = journalProjector(model, opts);
     for (const e of events)
         proj.apply(e);
     return { state: proj.snapshot(), checkpoint: proj.serialize() };
@@ -79,10 +119,10 @@ export function replayWithCheckpoint(model, events) {
  *
  * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
  */
-export function replaySegments(segments) {
+export function replaySegments(segments, opts) {
     if (!segments.length)
         throw new Error('재생할 마디가 없다 — 구조를 하나도 주지 않았다');
-    const proj = new StateProjector(segments[0].model);
+    const proj = journalProjector(segments[0].model, opts);
     const shifts = [];
     for (let i = 0; i < segments.length; i++) {
         /* 첫 마디는 생성자가 이미 그 구조로 섰다 — 두 번 세우면 관측 전 상태를 다시 덮는다. */

package/dist/flow-engine.js

@@ -693,7 +693,23 @@ export class FlowEngine {
      * 관측 구동이 아니면 `undefined` — 시뮬은 리듀서를 갖지 않는다(저장할 것이 없다).
      */
     observedCheckpoint() {
-        return this.observer?.serialize();
+        /*
+         * 관측 구동인데 리듀서가 아직 없으면 만든다 (2026-08-27).
+         *
+         * 리듀서는 첫 봉투가 이 클래스의 `apply` 에 닿을 때 만들어진다. 그런데 도메인 커널이 그 봉투를
+         * 가로채고 돌아가면(에너지 사건이 그렇다) 리듀서가 만들어지지 않는다. 그러면 이 함수가
+         * `undefined` 를 내고, 호스트는 재개점이 없다고 보아 다음 조회마다 저장 기록을 처음부터 다시
+         * 처리한다 — 에너지만 들어오는 트윈에서 실제로 그랬다.
+         */
+        if (!this.observer && this.observeMode) {
+            this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });
+        }
+        const cp = this.observer?.serialize();
+        if (!cp)
+            return undefined;
+        /* 도메인 커널이 따로 드는 상태를 함께 담는다 — 없으면 그 칸을 만들지 않는다. */
+        const domain = typeof this.serializeDomain === 'function' ? this.serializeDomain() : undefined;
+        return domain === undefined ? cp : { ...cp, domain };
     }
     /**
      * **재개점에서 관측 리듀서를 되세운다** — 저널을 0부터 다시 집계하지 않게.
@@ -713,6 +729,11 @@ export class FlowEngine {
             this.observeMode = true;
         }
         this.observer.restore(cp);
+        /* 도메인 커널이 따로 드는 상태를 되돌린다 — 담기지 않았으면 되돌릴 것도 없다. */
+        if (cp?.domain !== undefined && typeof this.restoreDomain === 'function') {
+            ;
+            this.restoreDomain(cp.domain);
+        }
         this.observedDirty = true;
         this.settleObserved();
     }

package/dist/observed-reducer.d.ts

@@ -168,6 +168,18 @@ export interface ReducerCheckpoint {
         atMs: number;
         longestGapMs?: number;
     }[];
+    /**
+     * 도메인 커널이 따로 드는 상태 — 이 리듀서는 내용을 보지 않고 그대로 실어 보낸다 (2026-08-27).
+     *
+     * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+     * 에너지 커널은 이 리듀서 밖에 자기 상태를 든다(계량 지점 · 열린 수요 구간 · 닫힌 구간들 · 월 최고).
+     * 그 값들은 계측을 모아 **트윈이 만든 것**이라, 연결된 시스템이 되풀어 주지 않는다. 재개점에 담기지
+     * 않으면 중간 저장본에서 이어 처리할 때 그만큼이 조용히 사라진다.
+     *
+     * 내용을 여기서 정의하지 않는 이유: 도메인마다 다르고, 이 리듀서가 그것을 알면 도메인 규칙이
+     * 공통 코드로 새어 든다. 그대로 담아 두고 되돌려 줄 뿐이다.
+     */
+    domain?: unknown;
 }
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */