@operato/twin-kernel 0.7.16 → 0.7.18

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,40 @@ export declare const EMS_PROPERTY: {
     readonly maxDischargeKW: "dispatch.maxDischargeKW";
     /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
     readonly reserveSoc: "dispatch.reserveSoc";
+    /**
+     * 시뮬레이션이 **출발할 때의 SOC(%)** — 씨앗값이다.
+     *
+     * 계측이 SOC 를 알려 주는 트윈에는 필요 없다(잰 값이 진실이다). 시뮬 트윈에는 알려 줄 것이 없어서
+     * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
+     * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
+     *
+     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
+     */
+    readonly initialSoc: "storage.initialSoc";
 };
+/**
+ * 이 선언들의 **단위와 범위** — 값을 읽는 쪽이 아니라 **주는 쪽**을 위한 표다.
+ *
+ * ── 왜 커널이 단위를 말해야 하나 (2026-08-17) ────────────────────────────────
+ * 사용자가 「현재 SOC 80%」라고 말했고, 저작 AI 는 `storage.initialSoc = 0.8` 을 썼다. 커널은 이 값을
+ * **퍼센트**로 읽으므로(`(soc - reserve) / 100`) 그 배터리는 0.8% 로 선언됐다 — 쓸 수 있는 에너지가
+ * 사실상 없는 상태이고, **경고 하나 없이** 그렇게 됐다. 실화면에서 그렇게 났다.
+ *
+ * 잘못은 값을 준 쪽이 아니라 **단위를 말하지 않은 쪽**에 있다. 타입을 지어내지 못하게 카탈로그를 주면서
+ * 속성은 id 만 줬으니, 값을 만드는 쪽은 단위를 짐작할 수밖에 없었다.
+ *
+ * 표를 커널에 두는 이유: 이 단위는 **커널의 셈법이 정하는 것**이다(퍼센트로 나누는 코드가 여기 있다).
+ * 소비처마다 적으면 두 벌이 되고, 두 벌은 갈라진다 — 갈라지는 순간 이 결함이 그대로 돌아온다.
+ */
+export interface EmsPropertySpec {
+    /** 단위 — 사람이 읽는 표기(kW·kWh·% 등). 무차원이면 없다. */
+    uom?: string;
+    /** 값의 종류 — GS1 dataType 표기(`xs:double`·`xs:string`). */
+    dataType: 'xs:double' | 'xs:string';
+    /** 허용 범위 [min, max] — 밖의 값은 받는 쪽이 거절할 수 있다(있는 것만 적는다). */
+    range?: [number, number];
+    /** 무엇을 뜻하나 — 영어 canonical(표현 계층이 사용자 언어로 옮긴다). */
+    note: string;
+}
+export declare const EMS_PROPERTY_SPEC: Record<string, EmsPropertySpec>;
 export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -61,7 +61,31 @@ 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_PROPERTY_SPEC = {
+    [EMS_PROPERTY.contractKW]: { uom: 'kW', dataType: 'xs:double', note: 'contracted power at the metering point, in kW.' },
+    [EMS_PROPERTY.ratedKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while running, in kW.' },
+    [EMS_PROPERTY.standbyKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while idle, in kW.' },
+    [EMS_PROPERTY.demandChargePerKW]: { dataType: 'xs:double', note: 'demand charge per kW of billing-period peak, in the declared currency.' },
+    [EMS_PROPERTY.energyChargePerKWh]: { dataType: 'xs:double', note: 'energy charge per kWh, in the declared currency.' },
+    [EMS_PROPERTY.currency]: { dataType: 'xs:string', note: 'ISO 4217 currency code, e.g. USD or KRW.' },
+    [EMS_PROPERTY.capacityKWh]: { uom: 'kWh', dataType: 'xs:double', note: 'usable energy of the storage, in kWh.' },
+    [EMS_PROPERTY.dischargeAboveKW]: { uom: 'kW', dataType: 'xs:double', note: 'net demand above which the storage discharges, in kW.' },
+    [EMS_PROPERTY.maxDischargeKW]: { uom: 'kW', dataType: 'xs:double', note: 'inverter limit on discharge rate, in kW.' },
+    /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
+    [EMS_PROPERTY.reserveSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below.' },
+    [EMS_PROPERTY.initialSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'starting state of charge as a percentage 0-100 (80 means 80%, not 0.8).' }
 };
 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

@@ -34,6 +34,7 @@ __export(index_exports, {
   EMS_EQUIPMENT_TYPES: () => EMS_EQUIPMENT_TYPES,
   EMS_LOCATION_TYPES: () => EMS_LOCATION_TYPES,
   EMS_PROPERTY: () => EMS_PROPERTY,
+  EMS_PROPERTY_SPEC: () => EMS_PROPERTY_SPEC,
   EMS_TYPES: () => EMS_TYPES,
   ENERGY_EVENT: () => ENERGY_EVENT,
   EPCIS_CONTEXT: () => EPCIS_CONTEXT,
@@ -1725,7 +1726,31 @@ var EMS_PROPERTY = {
   /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
   maxDischargeKW: "dispatch.maxDischargeKW",
   /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
-  reserveSoc: "dispatch.reserveSoc"
+  reserveSoc: "dispatch.reserveSoc",
+  /**
+   * 시뮬레이션이 **출발할 때의 SOC(%)** — 씨앗값이다.
+   *
+   * 계측이 SOC 를 알려 주는 트윈에는 필요 없다(잰 값이 진실이다). 시뮬 트윈에는 알려 줄 것이 없어서
+   * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
+   * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
+   *
+   * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
+   */
+  initialSoc: "storage.initialSoc"
+};
+var EMS_PROPERTY_SPEC = {
+  [EMS_PROPERTY.contractKW]: { uom: "kW", dataType: "xs:double", note: "contracted power at the metering point, in kW." },
+  [EMS_PROPERTY.ratedKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while running, in kW." },
+  [EMS_PROPERTY.standbyKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while idle, in kW." },
+  [EMS_PROPERTY.demandChargePerKW]: { dataType: "xs:double", note: "demand charge per kW of billing-period peak, in the declared currency." },
+  [EMS_PROPERTY.energyChargePerKWh]: { dataType: "xs:double", note: "energy charge per kWh, in the declared currency." },
+  [EMS_PROPERTY.currency]: { dataType: "xs:string", note: "ISO 4217 currency code, e.g. USD or KRW." },
+  [EMS_PROPERTY.capacityKWh]: { uom: "kWh", dataType: "xs:double", note: "usable energy of the storage, in kWh." },
+  [EMS_PROPERTY.dischargeAboveKW]: { uom: "kW", dataType: "xs:double", note: "net demand above which the storage discharges, in kW." },
+  [EMS_PROPERTY.maxDischargeKW]: { uom: "kW", dataType: "xs:double", note: "inverter limit on discharge rate, in kW." },
+  /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
+  [EMS_PROPERTY.reserveSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below." },
+  [EMS_PROPERTY.initialSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "starting state of charge as a percentage 0-100 (80 means 80%, not 0.8)." }
 };
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
@@ -2996,6 +3021,8 @@ var FlowEngine = class {
   interventions = [];
   /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
   interventionLog = [];
+  /** 덮어쓴 선언 — 「이 값은 가정이다」를 소비처가 말할 수 있게. */
+  overrideLog = [];
   generating = false;
   speed = 1;
   eventSeq = 0;
@@ -3523,6 +3550,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 +3572,7 @@ var FlowEngine = class {
       this.gens = [];
       this.interventions = [];
       this.interventionLog = [];
+      this.overrideLog = [];
     },
     setSpeed: (f) => {
       this.speed = f;
@@ -3744,6 +3776,15 @@ var FlowEngine = class {
   interventionOutcomes() {
     return this.interventionLog.map((o) => ({ ...o }));
   }
+  /**
+   * 이 커널이 **가정으로 덮어쓴 선언들** — 없으면 빈 배열.
+   *
+   * 비어 있지 않다는 것은 「이 트윈의 수는 선언된 현장이 아니라 가정한 현장의 것」이라는 뜻이다.
+   * 화면·AI 가 그 사실을 함께 말해야 한다.
+   */
+  declarationOverrides() {
+    return this.overrideLog.map((o) => ({ ...o }));
+  }
   // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
   /**
    * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
@@ -6292,6 +6333,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) {
@@ -6752,6 +6797,7 @@ function retiredVocabularyIn(line) {
   EMS_EQUIPMENT_TYPES,
   EMS_LOCATION_TYPES,
   EMS_PROPERTY,
+  EMS_PROPERTY_SPEC,
   EMS_TYPES,
   ENERGY_EVENT,
   EPCIS_CONTEXT,

package/package.json

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