@operato/twin-kernel 0.7.16 → 0.7.17

package/dist/contract.d.ts

@@ -1450,6 +1450,26 @@ export interface ScenarioDef {
      * 아무도 답할 수 없다).
      */
     interventions?: ScenarioIntervention[];
+    /**
+     * **가정한 선언** — 「이렇게 선언돼 있었다면?」(예: 축전지에 피크 억제 임계를 넣으면).
+     *
+     * 개입(`interventions`)이 시각을 가진 **행동**이라면 이쪽은 시각이 없는 **모델의 변주**다. 둘을 한
+     * 자리에 두지 않는 이유: 행동은 저널에 남을 사실이 되고, 변주는 「그런 현장이었다면」이라는 가정이다.
+     *
+     * 시나리오와 함께 다니므로 fork 가 자기완결이다 — 같은 선언 하나로 예측·백테스트·AI 가 같은 미래를
+     * 재생한다. 다만 **실행 중 트윈에 이 시나리오를 걸면 그 트윈의 선언이 실제로 바뀐다**: 그것은
+     * 「우리 현장에 그 자동화가 있다」는 주장이므로, 무엇을 덮어썼는지 소비처가 읽을 수 있어야 한다
+     * (`declarationOverrides()`).
+     */
+    overrides?: ScenarioOverride[];
+}
+/** 가정한 선언 하나 — 어느 자원의 어느 속성을 무엇으로. */
+export interface ScenarioOverride {
+    resourceId: string;
+    propertyId: string;
+    value: string | number;
+    /** 그 자원이 없었으면 false — 조용히 성공한 척하지 않는다. */
+    applied?: boolean;
 }
 /** 가정한 개입 하나 — 시각 + 행동. */
 export interface ScenarioIntervention {

package/dist/ems-kernel.js

@@ -554,6 +554,15 @@ export class EmsKernel extends FlowEngine {
             const state = this.equipment.get(e.id);
             if (!state)
                 continue;
+            /*
+             * 시뮬의 출발 SOC — 선언에서 한 번 심는다(계측이 들어오면 그것이 이긴다).
+             * 이것이 없던 동안, 정책을 선언해도 「SOC 를 모른다」에 걸려 배터리가 아무 일도 하지 못했다.
+             */
+            if (!Number.isFinite(Number(state.soc))) {
+                const seed = this.numberProperty(e, EMS_PROPERTY.initialSoc);
+                if (seed !== undefined)
+                    state.soc = seed;
+            }
             const over = demandBeforeStorageKW - dispatched - above;
             if (over <= 0) {
                 /* 임계 아래 — 쓸 이유가 없다. 낡은 방전값을 남기지 않는다(상태가 지난 틱을 말하게 된다). */

package/dist/ems-profile.d.ts

@@ -30,5 +30,15 @@ export declare const EMS_PROPERTY: {
     readonly maxDischargeKW: "dispatch.maxDischargeKW";
     /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
     readonly reserveSoc: "dispatch.reserveSoc";
+    /**
+     * 시뮬레이션이 **출발할 때의 SOC(%)** — 씨앗값이다.
+     *
+     * 계측이 SOC 를 알려 주는 트윈에는 필요 없다(잰 값이 진실이다). 시뮬 트윈에는 알려 줄 것이 없어서
+     * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
+     * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
+     *
+     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+     */
+    readonly initialSoc: "storage.initialSoc";
 };
 export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -61,7 +61,17 @@ export const EMS_PROPERTY = {
     /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
     maxDischargeKW: 'dispatch.maxDischargeKW',
     /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
-    reserveSoc: 'dispatch.reserveSoc'
+    reserveSoc: 'dispatch.reserveSoc',
+    /**
+     * 시뮬레이션이 **출발할 때의 SOC(%)** — 씨앗값이다.
+     *
+     * 계측이 SOC 를 알려 주는 트윈에는 필요 없다(잰 값이 진실이다). 시뮬 트윈에는 알려 줄 것이 없어서
+     * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
+     * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
+     *
+     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+     */
+    initialSoc: 'storage.initialSoc'
 };
 export const EMS_TYPES = [
     /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, StructureShift } from './contract.ts';
+import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, StructureShift } from './contract.ts';
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
@@ -329,6 +329,8 @@ export declare abstract class FlowEngine implements TwinKernel {
     private interventions;
     /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
     private interventionLog;
+    /** 덮어쓴 선언 — 「이 값은 가정이다」를 소비처가 말할 수 있게. */
+    private overrideLog;
     private generating;
     private speed;
     private eventSeq;
@@ -480,6 +482,13 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 아직 시각이 오지 않은 것은 여기 없다(일어나지 않은 일을 결과로 적지 않는다).
      */
     interventionOutcomes(): InterventionOutcome[];
+    /**
+     * 이 커널이 **가정으로 덮어쓴 선언들** — 없으면 빈 배열.
+     *
+     * 비어 있지 않다는 것은 「이 트윈의 수는 선언된 현장이 아니라 가정한 현장의 것」이라는 뜻이다.
+     * 화면·AI 가 그 사실을 함께 말해야 한다.
+     */
+    declarationOverrides(): ScenarioOverride[];
     /**
      * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
      *

package/dist/flow-engine.js

@@ -290,6 +290,8 @@ export class FlowEngine {
     interventions = [];
     /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
     interventionLog = [];
+    /** 덮어쓴 선언 — 「이 값은 가정이다」를 소비처가 말할 수 있게. */
+    overrideLog = [];
     generating = false;
     speed = 1;
     eventSeq = 0;
@@ -875,6 +877,14 @@ export class FlowEngine {
             /* 개입은 **시작할 때** 시각이 정해진다(경과 기준) — 여기서는 받아만 둔다. */
             this.interventions = (def.interventions ?? []).map(spec => ({ spec, dueMs: 0, done: false }));
             this.interventionLog = [];
+            /*
+             * 가정한 선언은 **지금 곧 걸린다** — 시각이 없는 변주이므로 미룰 것이 없다.
+             * 무엇을 덮어썼는지 남긴다: 말하지 않으면 소비처가 what-if 결과를 트윈의 현재 상태로 읽는다.
+             */
+            this.overrideLog = (def.overrides ?? []).map(o => ({
+                ...o,
+                applied: this.setResourceProperty(o.resourceId, o.propertyId, o.value)
+            }));
         },
         start: () => {
             if (this.generating)
@@ -889,7 +899,7 @@ export class FlowEngine {
             }
         },
         pause: () => { this.generating = false; },
-        reset: () => { this.generating = false; this.gens = []; this.interventions = []; this.interventionLog = []; },
+        reset: () => { this.generating = false; this.gens = []; this.interventions = []; this.interventionLog = []; this.overrideLog = []; },
         setSpeed: (f) => { this.speed = f; }
     };
     tick(dtMs) {
@@ -1117,6 +1127,15 @@ export class FlowEngine {
     interventionOutcomes() {
         return this.interventionLog.map(o => ({ ...o }));
     }
+    /**
+     * 이 커널이 **가정으로 덮어쓴 선언들** — 없으면 빈 배열.
+     *
+     * 비어 있지 않다는 것은 「이 트윈의 수는 선언된 현장이 아니라 가정한 현장의 것」이라는 뜻이다.
+     * 화면·AI 가 그 사실을 함께 말해야 한다.
+     */
+    declarationOverrides() {
+        return this.overrideLog.map(o => ({ ...o }));
+    }
     // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
     /**
      * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.

package/dist-cjs/index.cjs

@@ -1725,7 +1725,17 @@ var EMS_PROPERTY = {
   /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
   maxDischargeKW: "dispatch.maxDischargeKW",
   /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
-  reserveSoc: "dispatch.reserveSoc"
+  reserveSoc: "dispatch.reserveSoc",
+  /**
+   * 시뮬레이션이 **출발할 때의 SOC(%)** — 씨앗값이다.
+   *
+   * 계측이 SOC 를 알려 주는 트윈에는 필요 없다(잰 값이 진실이다). 시뮬 트윈에는 알려 줄 것이 없어서
+   * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
+   * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
+   *
+   * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+   */
+  initialSoc: "storage.initialSoc"
 };
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
@@ -2996,6 +3006,8 @@ var FlowEngine = class {
   interventions = [];
   /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
   interventionLog = [];
+  /** 덮어쓴 선언 — 「이 값은 가정이다」를 소비처가 말할 수 있게. */
+  overrideLog = [];
   generating = false;
   speed = 1;
   eventSeq = 0;
@@ -3523,6 +3535,10 @@ var FlowEngine = class {
       this.gens = def.generators.map((spec) => ({ spec, nextMs: 0 }));
       this.interventions = (def.interventions ?? []).map((spec) => ({ spec, dueMs: 0, done: false }));
       this.interventionLog = [];
+      this.overrideLog = (def.overrides ?? []).map((o) => ({
+        ...o,
+        applied: this.setResourceProperty(o.resourceId, o.propertyId, o.value)
+      }));
     },
     start: () => {
       if (this.generating) return;
@@ -3541,6 +3557,7 @@ var FlowEngine = class {
       this.gens = [];
       this.interventions = [];
       this.interventionLog = [];
+      this.overrideLog = [];
     },
     setSpeed: (f) => {
       this.speed = f;
@@ -3744,6 +3761,15 @@ var FlowEngine = class {
   interventionOutcomes() {
     return this.interventionLog.map((o) => ({ ...o }));
   }
+  /**
+   * 이 커널이 **가정으로 덮어쓴 선언들** — 없으면 빈 배열.
+   *
+   * 비어 있지 않다는 것은 「이 트윈의 수는 선언된 현장이 아니라 가정한 현장의 것」이라는 뜻이다.
+   * 화면·AI 가 그 사실을 함께 말해야 한다.
+   */
+  declarationOverrides() {
+    return this.overrideLog.map((o) => ({ ...o }));
+  }
   // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
   /**
    * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
@@ -6292,6 +6318,10 @@ var EmsKernel = class extends FlowEngine {
       if (!(capacity > 0) || !(maxRate > 0)) continue;
       const state = this.equipment.get(e.id);
       if (!state) continue;
+      if (!Number.isFinite(Number(state.soc))) {
+        const seed = this.numberProperty(e, EMS_PROPERTY.initialSoc);
+        if (seed !== void 0) state.soc = seed;
+      }
       const over = demandBeforeStorageKW - dispatched - above;
       if (over <= 0) {
         if (Number(state.dischargeKW) > 0) {

package/package.json

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