@operato/twin-kernel 0.7.4 → 0.7.5

package/dist/contract.d.ts

@@ -1850,6 +1850,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/ems-kernel.js

@@ -276,12 +276,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 +430,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();

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

@@ -227,6 +227,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 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
@@ -1016,7 +1030,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-cjs/index.cjs

@@ -2809,6 +2809,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 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
@@ -3529,7 +3543,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();
@@ -5802,11 +5828,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 +5963,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();

package/package.json

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