@operato/twin-kernel 0.7.23 → 0.7.25

package/dist/contract.d.ts

@@ -131,6 +131,26 @@ levelOfType?: (type: string) => EquipmentLevel | undefined): Hierarchy;
  * 왜 이제 계약에 넣는가: 지금까지 설비 속성(`speed`)이 **계약 밖으로 흘러** 마스터에서 호스트
  * 추정기까지 `any` 로 전달됐다. 자원에 붙는 사실이 계약에 자리가 없으면 소비처마다 다르게 읽는다.
  */
+/**
+ * 이 속성 값을 **누가 말했나** — 근거를 값과 함께 나르는 규율의 속성 판(`basis`·`derived` 와 같은 결).
+ *
+ * ── 두 낱말이 한 축이다 (2026-08-18 확정) ───────────────────────────────────
+ *  · `reference` — **외부 원천 시스템**이 준 값이다(SCADA·WMS·MES 의 마스터). 우리가 고르지 않았다.
+ *  · `local`     — **이 트윈 쪽에서 정한 값**이다. 원천이 모르는 수(계약전력·요금 단가·축전지 충전율)를
+ *                  운영 주체가 넣은 것이고, 사람이 넣었든 대리로 AI 가 채웠든 같다 — 축은 「누가 입력
+ *                  했나」가 아니라 **「권위가 어디 있나」**다.
+ *
+ * ── 장소 낱말과 섞지 않는다 ────────────────────────────────────────────────
+ * 예전 표식은 `'site'` 였다. 그런데 이 코드에서 `site` 는 **외부 시스템이 부르는 사업장**을 뜻한다
+ * (SAP 는 `P3`, Oracle 은 `W01` 로 같은 현장을 부른다). 그래서 「원천이 모르는 값」에 `site` 를 달면
+ * 이름이 내용과 정반대가 됐다 — 내가 쓴 편지를 「받은 편지함」에 넣어 둔 셈이다. `space`(트윈이 서는
+ * 그릇)도 답이 아니다: 그것은 **어디**에 답하는 낱말이고, 이 축은 **누가 말했나**에 답한다.
+ *
+ * ── 표식이 없으면 ──────────────────────────────────────────────────────────
+ * **모델을 그린 쪽이 말한 값**이다 — 참조에서 그린 모델이면 원천이고, 템플릿으로 만든 트윈이면 그
+ * 템플릿이다. 즉 「모른다」가 아니라 「원천 쪽」이다. 표식은 그 기본값과 다를 때 달린다.
+ */
+export type PropertySource = 'reference' | 'local';
 export interface ResourceProperty {
     /** 속성 식별자 — 표준 `ID`. 어휘는 표준이 정하지 않으므로 우리가 한 곳에서 정한다 — 그 자리는 읽는 쪽에 있다
      * (headless-twin `EQUIPMENT_PROPERTY`·`PROPERTY_EFFECTS`). 커널은 속성을 **나르기만** 한다. */
@@ -146,6 +166,14 @@ export interface ResourceProperty {
     children?: ResourceProperty[];
     /** 이 개체 속성이 구체화하는 **등급 속성** — 표준 `<X>ClassPropertyID`. */
     classPropertyId?: string;
+    /**
+     * 이 값을 누가 말했나(`PropertySource`) — 없으면 모델을 그린 쪽이다(대개 원천).
+     *
+     * 커널은 이 표식을 **읽지 않는다**(속성의 뜻은 `id`·`dataType`·`uom` 이 정한다). 나르기만 한다 —
+     * 계약에 선언해 두는 이유는, 예전에 이 표식이 **계약에 없는 필드로 얹혀 다녔기** 때문이다. 그러면
+     * 소비처가 `any` 로 읽고, 상태에 정말 실리는지 아무도 검사할 수 없다.
+     */
+    source?: PropertySource;
 }
 /**
  * 자격·적격을 **검증한 시험 명세**들 — 표준 `TestSpecificationID`(`maxOccurs="unbounded"`).
@@ -1376,6 +1404,19 @@ export interface StateSnapshot {
      * 왕복시켜야 재기동·재계산에서 확인 상태가 유지된다.
      */
     acked?: string[];
+    /**
+     * 주목 신호가 **처음 성립한 시각**(id → ISO) — 확인과 마찬가지로 **계산으로 되살릴 수 없다.**
+     *
+     * 신호는 매 스냅샷 다시 계산되지만 「언제부터인가」는 그 계산 안에 없다. 왕복시키지 않으면 재기동·
+     * 웜스타트 뒤 **세 시간째 지속된 조건이 「0초째」로 되살아난다** — 방금 찬 자리와 세 시간째 막힌
+     * 자리는 할 일이 다르므로, 그 값이 거짓이면 화면은 사람을 잘못된 순서로 움직인다.
+     *
+     * 사라진 조건은 함께 지운다(재발은 새 시작이다) — 그 규율은 `computeAttentions` 가 지킨다.
+     */
+    attentionSince?: {
+        id: string;
+        since: ISOTime;
+    }[];
     /**
      * 에너지 — **에너지 트윈만 채운다**(계량 지점·수요 구간·피크). 다른 종류에서는 없다.
      *

package/dist/ems-kernel.d.ts

@@ -1,6 +1,6 @@
 import { FlowEngine } from './flow-engine.ts';
 import { type AllocationPolicy } from './allocation-policy.ts';
-import { type CanonicalEnvelope, type DemandWindowState, type StateSnapshot, type Attention, type StructureShift, type TwinModelDef } from './contract.ts';
+import { type CanonicalEnvelope, type DemandWindowState, type EnergyState, type StateSnapshot, type Attention, type StructureShift, type TwinModelDef } from './contract.ts';
 /** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
 export declare const DEMAND_WINDOW_MS: number;
 /** 그 시각이 속한 구간의 시작 — 벽시계 경계(00·15·30·45분)에 맞춘다. */
@@ -208,5 +208,27 @@ export declare class EmsKernel extends FlowEngine {
     /** 글자로 선언된 값(발전 형상·통화 같은 것) — 비어 있으면 없는 것으로 본다. */
     private stringProperty;
     tick(dtMs: number): void;
+    /**
+     * 에너지의 연속성 — **SCADA 는 「이번 15분에 지금까지 얼마」를 모른다.**
+     *
+     * 계량기는 순간값과 적산값을 준다. 「이 구간의 최대」·「구간이 열릴 때의 적산」·「관측 이후 최대」는
+     * 우리가 접어 만든 값이라, 재기동하면 원천이 되풀어 주지 않는다. 잃으면 오류 없이 값이 작아진다 —
+     * 구간 전력량이 기준점을 새로 잡아 짧아지고, 그 구간의 피크가 부팅 이후로만 잡힌다(요금이 걸린 수다).
+     *
+     * 지난 마감 구간도 이어받는다: 이미 저널에 있는 사실이지만, 화면이 그것을 보려고 매번 저널을 접지
+     * 않게 한다(자른 사실은 `closedTotal` 이 그대로 나른다).
+     *
+     * 지금 열린 구간이 **이미 지나간 것**이어도 그대로 받는다 — 다음 표본이 오면 커널이 그 구간을 정상
+     * 경로로 마감한다(그 사실은 자기 시각을 달고 있어 늦게 나가도 참이다). 여기서 버리면 그 15분은
+     * 통째로 사라진다.
+     */
+    hydrateContinuity(snap: {
+        acked?: string[];
+        attentionSince?: {
+            id: string;
+            since: string;
+        }[];
+        energy?: EnergyState;
+    }): void;
     getSnapshot(): StateSnapshot;
 }

package/dist/ems-kernel.js

@@ -875,6 +875,38 @@ export class EmsKernel extends FlowEngine {
         this.deriveLoad(at, dtMs);
         this.closeDue(at);
     }
+    /**
+     * 에너지의 연속성 — **SCADA 는 「이번 15분에 지금까지 얼마」를 모른다.**
+     *
+     * 계량기는 순간값과 적산값을 준다. 「이 구간의 최대」·「구간이 열릴 때의 적산」·「관측 이후 최대」는
+     * 우리가 접어 만든 값이라, 재기동하면 원천이 되풀어 주지 않는다. 잃으면 오류 없이 값이 작아진다 —
+     * 구간 전력량이 기준점을 새로 잡아 짧아지고, 그 구간의 피크가 부팅 이후로만 잡힌다(요금이 걸린 수다).
+     *
+     * 지난 마감 구간도 이어받는다: 이미 저널에 있는 사실이지만, 화면이 그것을 보려고 매번 저널을 접지
+     * 않게 한다(자른 사실은 `closedTotal` 이 그대로 나른다).
+     *
+     * 지금 열린 구간이 **이미 지나간 것**이어도 그대로 받는다 — 다음 표본이 오면 커널이 그 구간을 정상
+     * 경로로 마감한다(그 사실은 자기 시각을 달고 있어 늦게 나가도 참이다). 여기서 버리면 그 15분은
+     * 통째로 사라진다.
+     */
+    hydrateContinuity(snap) {
+        super.hydrateContinuity(snap);
+        const e = snap?.energy;
+        if (!e)
+            return;
+        for (const p of e.points ?? [])
+            if (p?.id)
+                this.points.set(p.id, { ...p });
+        if (e.open)
+            this.open = { ...e.open };
+        if (e.closed?.length)
+            this.closed = e.closed.map(w => ({ ...w })).slice(-KEEP_CLOSED);
+        /* 자른 수는 이어받은 목록으로 다시 세지 않는다 — 그러면 잘려 나간 과거가 조용히 0 이 된다. */
+        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 };
+    }
     getSnapshot() {
         const snap = super.getSnapshot();
         const contractKW = this.declaredContractKW();

package/dist/flow-engine.d.ts

@@ -407,6 +407,29 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 것이고, 그것을 허용하면 이 함수가 막으려던 일이 이 함수를 통해 일어난다.
      */
     resumeRevision(from: number): void;
+    /**
+     * **원천이 되풀어 주지 않는 것만 잇는다** — 미러(관측 구동) 재기동의 연속성.
+     *
+     * ── 왜 따로 두나 (2026-08-18) ──────────────────────────────────────────────
+     * 미러의 진실은 원천이다. 그래서 재고·위치·설비 상태는 스냅샷에서 심지 않는다 — 다음 계측·다음
+     * 마스터 재읽기가 곧 정정하므로, 심으면 **떠난 물건이 되살아나는** 위험만 남는다.
+     *
+     * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 접어 만든 것들이다:
+     *  · 확인(ack)·조건이 처음 성립한 시각 — 사람이 한 일과 우리가 기억한 시각
+     *  · 열린 구간의 누적·적산 기준점·관측 이후 최대 — SCADA 는 「이번 15분에 지금까지 얼마」를 모른다
+     *
+     * 이것을 잃으면 오류 없이 값이 작아진다(실측: 재기동 뒤 그 구간의 전력량·피크가 작게 나오고, 세
+     * 시간째 지속된 경보가 「0초째」가 된다). 그래서 축을 갈라, 되풀어 주지 않는 것만 이어받는다.
+     *
+     * 도메인 축(에너지 등)은 서브클래스가 override 로 덧붙인다(`super.hydrateContinuity(snap)` 합성).
+     */
+    hydrateContinuity(snap: {
+        acked?: string[];
+        attentionSince?: {
+            id: string;
+            since: string;
+        }[];
+    }): void;
     hydrateObserved(snap: {
         locations: LocationState[];
         items: ItemState[];
@@ -415,8 +438,13 @@ export declare abstract class FlowEngine implements TwinKernel {
         assets?: AssetState[];
         tasks?: TaskState[];
         orders?: OrderState[];
-        /** 확인해 둔 주목 신호 id — 계산으로 되살릴 수 없는 유일한 축이라 스냅샷에서 이어받는다. */
+        /** 확인해 둔 주목 신호 id — 계산으로 되살릴 수 없어 스냅샷에서 이어받는다. */
         acked?: string[];
+        /** 주목 신호가 처음 성립한 시각 — 이어받지 않으면 지속된 조건이 「방금」으로 되살아난다. */
+        attentionSince?: {
+            id: string;
+            since: string;
+        }[];
     }, orders?: OrderStatusDelta[]): void;
     /**
      * what-if 구성 변주 — **선언을 덮어쓴다**(fork 대상). 바꿨으면 true.

package/dist/flow-engine.js

@@ -465,11 +465,39 @@ export class FlowEngine {
             throw new Error(`리비전을 뒤로 되돌릴 수 없다: ${this.revision} → ${from} (겹치는 번호가 생긴다)`);
         this.revision = from;
     }
+    /**
+     * **원천이 되풀어 주지 않는 것만 잇는다** — 미러(관측 구동) 재기동의 연속성.
+     *
+     * ── 왜 따로 두나 (2026-08-18) ──────────────────────────────────────────────
+     * 미러의 진실은 원천이다. 그래서 재고·위치·설비 상태는 스냅샷에서 심지 않는다 — 다음 계측·다음
+     * 마스터 재읽기가 곧 정정하므로, 심으면 **떠난 물건이 되살아나는** 위험만 남는다.
+     *
+     * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 접어 만든 것들이다:
+     *  · 확인(ack)·조건이 처음 성립한 시각 — 사람이 한 일과 우리가 기억한 시각
+     *  · 열린 구간의 누적·적산 기준점·관측 이후 최대 — SCADA 는 「이번 15분에 지금까지 얼마」를 모른다
+     *
+     * 이것을 잃으면 오류 없이 값이 작아진다(실측: 재기동 뒤 그 구간의 전력량·피크가 작게 나오고, 세
+     * 시간째 지속된 경보가 「0초째」가 된다). 그래서 축을 갈라, 되풀어 주지 않는 것만 이어받는다.
+     *
+     * 도메인 축(에너지 등)은 서브클래스가 override 로 덧붙인다(`super.hydrateContinuity(snap)` 합성).
+     */
+    hydrateContinuity(snap) {
+        for (const id of snap?.acked ?? [])
+            this._acked.add(id);
+        for (const e of snap?.attentionSince ?? [])
+            if (e?.id && e.since)
+                this._attentionSince.set(e.id, e.since);
+    }
     hydrateObserved(snap, orders = []) {
         /* 확인 처리를 먼저 이어받는다 — 아래에서 상태를 주입하면 곧바로 주목 신호가 계산되므로, 늦게
          * 이어받으면 그 한 번은 확인 안 된 것으로 계산된다(화면이 잠깐 빨개진다). */
         for (const id of snap.acked ?? [])
             this._acked.add(id);
+        /* 「언제부터인가」도 함께 이어받는다 — 상태를 심으면 곧바로 신호가 계산되므로, 늦게 받으면 그 한 번은
+           모두 방금 생긴 것으로 찍히고 그 값이 그대로 굳는다(다음 계산은 이미 기억된 시각을 쓴다). */
+        for (const e of snap.attentionSince ?? [])
+            if (e?.id && e.since)
+                this._attentionSince.set(e.id, e.since);
         /* **관측된 것을 버리지 않는다.** 예전에는 자리·설비 상태를 'idle' 로, OEE 누적을 0 으로 덮고
          * 물품의 로트·단위·소속·마스터데이터를 떨어뜨렸다. 씨앗이 잃은 것은 **예측도 모른다** —
          * 고장 난 설비를 정상으로, 진행 중인 일을 없는 것으로 놓고 미래를 실행하면 답이 낙관 쪽으로 치우친다. */
@@ -748,7 +776,7 @@ export class FlowEngine {
      */
     abandonedTasks = 0;
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
-    _attentionSince = new Map(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
+    _attentionSince = new Map();
     dispatch(cmd) {
         /*
          * 이 커맨드가 낳는 이벤트에 상관값을 단다. 명시값이 없으면 **commandId 를 쓴다** — 호출자가
@@ -1022,7 +1050,9 @@ export class FlowEngine {
             })),
             attentions: this.computeAttentions(),
             /* 확인해 둔 신호 — 스냅샷으로 왕복해야 재기동 후에도 확인 상태가 유지된다. */
-            acked: [...this._acked]
+            acked: [...this._acked],
+            /* 언제부터인가 — 이것도 계산으로 되살릴 수 없다. 위 계산이 사라진 조건을 이미 지웠으므로 지금 남은 것이 곧 진실이다. */
+            attentionSince: [...this._attentionSince].map(([id, since]) => ({ id, since }))
         };
     }
     /*

package/dist-cjs/index.cjs

@@ -3254,8 +3254,29 @@ var FlowEngine = class {
     if (from < this.revision) throw new Error(`\uB9AC\uBE44\uC804\uC744 \uB4A4\uB85C \uB418\uB3CC\uB9B4 \uC218 \uC5C6\uB2E4: ${this.revision} \u2192 ${from} (\uACB9\uCE58\uB294 \uBC88\uD638\uAC00 \uC0DD\uAE34\uB2E4)`);
     this.revision = from;
   }
+  /**
+   * **원천이 되풀어 주지 않는 것만 잇는다** — 미러(관측 구동) 재기동의 연속성.
+   *
+   * ── 왜 따로 두나 (2026-08-18) ──────────────────────────────────────────────
+   * 미러의 진실은 원천이다. 그래서 재고·위치·설비 상태는 스냅샷에서 심지 않는다 — 다음 계측·다음
+   * 마스터 재읽기가 곧 정정하므로, 심으면 **떠난 물건이 되살아나는** 위험만 남는다.
+   *
+   * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 접어 만든 것들이다:
+   *  · 확인(ack)·조건이 처음 성립한 시각 — 사람이 한 일과 우리가 기억한 시각
+   *  · 열린 구간의 누적·적산 기준점·관측 이후 최대 — SCADA 는 「이번 15분에 지금까지 얼마」를 모른다
+   *
+   * 이것을 잃으면 오류 없이 값이 작아진다(실측: 재기동 뒤 그 구간의 전력량·피크가 작게 나오고, 세
+   * 시간째 지속된 경보가 「0초째」가 된다). 그래서 축을 갈라, 되풀어 주지 않는 것만 이어받는다.
+   *
+   * 도메인 축(에너지 등)은 서브클래스가 override 로 덧붙인다(`super.hydrateContinuity(snap)` 합성).
+   */
+  hydrateContinuity(snap) {
+    for (const id of snap?.acked ?? []) this._acked.add(id);
+    for (const e of snap?.attentionSince ?? []) if (e?.id && e.since) this._attentionSince.set(e.id, e.since);
+  }
   hydrateObserved(snap, orders = []) {
     for (const id of snap.acked ?? []) this._acked.add(id);
+    for (const e of snap.attentionSince ?? []) if (e?.id && e.since) this._attentionSince.set(e.id, e.since);
     for (const n of snap.locations) {
       this.locations.set(n.id, { id: n.id, type: n.type, capacity: n.capacity ?? 0, parallelism: n.parallelism, occupancy: n.occupancy ?? 0, status: n.status ?? "idle", parentId: n.parentId });
     }
@@ -3515,7 +3536,6 @@ var FlowEngine = class {
   abandonedTasks = 0;
   /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
   _attentionSince = /* @__PURE__ */ new Map();
-  // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
   dispatch(cmd) {
     this._correlationId = cmd.correlationId ?? cmd.commandId;
     try {
@@ -3758,7 +3778,9 @@ var FlowEngine = class {
       })),
       attentions: this.computeAttentions(),
       /* 확인해 둔 신호 — 스냅샷으로 왕복해야 재기동 후에도 확인 상태가 유지된다. */
-      acked: [...this._acked]
+      acked: [...this._acked],
+      /* 언제부터인가 — 이것도 계산으로 되살릴 수 없다. 위 계산이 사라진 조건을 이미 지웠으므로 지금 남은 것이 곧 진실이다. */
+      attentionSince: [...this._attentionSince].map(([id, since]) => ({ id, since }))
     };
   }
   /*
@@ -6676,6 +6698,30 @@ var EmsKernel = class extends FlowEngine {
     this.deriveLoad(at, dtMs);
     this.closeDue(at);
   }
+  /**
+   * 에너지의 연속성 — **SCADA 는 「이번 15분에 지금까지 얼마」를 모른다.**
+   *
+   * 계량기는 순간값과 적산값을 준다. 「이 구간의 최대」·「구간이 열릴 때의 적산」·「관측 이후 최대」는
+   * 우리가 접어 만든 값이라, 재기동하면 원천이 되풀어 주지 않는다. 잃으면 오류 없이 값이 작아진다 —
+   * 구간 전력량이 기준점을 새로 잡아 짧아지고, 그 구간의 피크가 부팅 이후로만 잡힌다(요금이 걸린 수다).
+   *
+   * 지난 마감 구간도 이어받는다: 이미 저널에 있는 사실이지만, 화면이 그것을 보려고 매번 저널을 접지
+   * 않게 한다(자른 사실은 `closedTotal` 이 그대로 나른다).
+   *
+   * 지금 열린 구간이 **이미 지나간 것**이어도 그대로 받는다 — 다음 표본이 오면 커널이 그 구간을 정상
+   * 경로로 마감한다(그 사실은 자기 시각을 달고 있어 늦게 나가도 참이다). 여기서 버리면 그 15분은
+   * 통째로 사라진다.
+   */
+  hydrateContinuity(snap) {
+    super.hydrateContinuity(snap);
+    const e = snap?.energy;
+    if (!e) return;
+    for (const p of e.points ?? []) if (p?.id) this.points.set(p.id, { ...p });
+    if (e.open) this.open = { ...e.open };
+    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 };
+  }
   getSnapshot() {
     const snap = super.getSnapshot();
     const contractKW = this.declaredContractKW();

package/package.json

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