@operato/twin-kernel 0.7.15 → 0.7.16

package/dist/contract.d.ts

@@ -1433,6 +1433,40 @@ export interface ScenarioDef {
     speed?: number;
     horizon?: number;
     generators: GeneratorSpec[];
+    /**
+     * **가정한 개입** — 시각을 가진 행동들(what-if).
+     *
+     * ── 왜 시나리오에 있나 (2026-08-17) ───────────────────────────────────────
+     * 시나리오는 이미 「우리가 가정한 미래」다. 「30분 뒤 이 설비를 세운다」는 정확히 그 미래의 일부이므로
+     * 여기 있어야 한다. 호스트가 fork 를 굴리며 밖에서 커맨드를 쏘는 방법도 되지만, 그러면 가정이 fork
+     * 밖에 남아 **다른 소비처가 같은 미래를 재생할 수 없다**(예측·백테스트·AI·보드가 각자 타이밍을 다시
+     * 짜야 한다). fork 가 자기완결이면 같은 선언 하나로 어디서든 같은 미래가 나온다.
+     *
+     * `atMs` 는 **시나리오를 시작한 시점부터의 경과**다(절대 시각이 아니다) — fork 는 언제 갈라져도
+     * 같은 가정을 같은 순서로 겪어야 하고, 절대 시각으로 두면 갈라진 시점에 따라 다른 미래가 된다.
+     *
+     * `kind` 는 커맨드 어휘(`CMD`)를 그대로 쓴다 — 개입은 새 종류의 사건이 아니라 **행동**이고, 그 어휘는
+     * 이미 있다. 커널이 모르는 종류는 거절하고 그 사실을 남긴다(조용히 넘기면 「걸었는데 왜 안 바뀌나」를
+     * 아무도 답할 수 없다).
+     */
+    interventions?: ScenarioIntervention[];
+}
+/** 가정한 개입 하나 — 시각 + 행동. */
+export interface ScenarioIntervention {
+    /** 시나리오 시작부터의 경과(ms). 0 이면 시작하는 순간. */
+    atMs: number;
+    /** 커맨드 이름(`CMD` 의 값) — 예: `resource.hold`. */
+    kind: string;
+    args?: Record<string, unknown>;
+}
+/** 개입이 어떻게 됐나 — 걸린 것과 거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
+export interface InterventionOutcome {
+    atMs: number;
+    kind: string;
+    args?: Record<string, unknown>;
+    applied: boolean;
+    /** 거절 이유(커맨드가 낸 코드). 걸렸으면 없다. */
+    refusedCode?: string;
 }
 export interface ScenarioControl {
     load(def: ScenarioDef): void;

package/dist/ems-kernel.d.ts

@@ -129,6 +129,27 @@ export declare class EmsKernel extends FlowEngine {
      * ④ 미러 트윈에서는 아무것도 만들지 않는다 — 관측 구동은 잰 것만 쓴다.
      */
     private deriveLoad;
+    /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
+    private hasDispatchPolicy;
+    /**
+     * 선언된 정책으로 축전지를 방전시킨다 — **선언이 없으면 아무것도 하지 않는다.**
+     *
+     * 돌려주는 값은 이번 틱에 계통에서 덜어낸 kW 다. 부작용으로 그 설비의 `dischargeKW`·`soc` 를 고치고
+     * 사실(`energy.equipment`)을 낸다 — 저널을 읽는 쪽이 「배터리가 무엇을 했나」를 되짚을 수 있어야 한다.
+     *
+     * ── 무엇을 하지 않나 ──────────────────────────────────────────────────────
+     *  · 충전 계획을 만들지 않는다(언제 채울지는 요금 시간대의 일이고, 그 모델은 아직 없다).
+     *  · 용량·임계·최대율이 하나라도 없으면 방전하지 않는다 — 짐작한 수로 피크를 깎지 않는다.
+     *  · 미러 트윈에서는 불리지 않는다(호출자가 이미 관측 모드를 걸러낸다).
+     */
+    private dispatchStorage;
+    /**
+     * 파생된 설비 에너지 상태를 사실로 낸다 — **만든 값임을 밝힌다.**
+     *
+     * 계측으로 들어온 것과 같은 자리에 두면서 종류를 적지 않으면, 저널을 읽는 쪽이 우리가 계산한 방전을
+     * 계기가 잰 방전으로 읽는다(수요 구간의 `derived` 와 같은 규율).
+     */
+    private emitEnergyEquipment;
     /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
     private numberProperty;
     tick(dtMs: number): void;

package/dist/ems-kernel.js

@@ -423,7 +423,7 @@ export class EmsKernel extends FlowEngine {
      * ③ 멈춘 설비는 `power.standbyKW` 를 선언한 만큼만 센다. 선언이 없으면 0 이 아니라 **모름**이다.
      * ④ 미러 트윈에서는 아무것도 만들지 않는다 — 관측 구동은 잰 것만 쓴다.
      */
-    deriveLoad(atMs) {
+    deriveLoad(atMs, dtMs) {
         if (this.observing)
             return; // 미러 — 계측이 진실이다
         let total = 0;
@@ -477,15 +477,34 @@ export class EmsKernel extends FlowEngine {
             const g = Number(m.generatedKW);
             if (Number.isFinite(g) && g > 0)
                 generated += g;
-            const d = Number(m.dischargeKW);
-            if (Number.isFinite(d) && d > 0)
-                discharged += d;
             const c = Number(m.chargeKW);
             if (Number.isFinite(c) && c > 0)
                 charged += c;
+            /*
+             * **정책이 정하는 방전은 여기서 세지 않는다** (2026-08-17 시험이 잡았다).
+             *
+             * 세면 직전 틱에 우리가 만든 방전이 이번 틱의 입력으로 돌아와, 정책은 「임계 아래다, 쓸 이유가
+             * 없다」고 판단하고 방전을 멈춘다. 그러면 SOC 는 한 번만 줄고 피크는 깎인 채로 굳는다 —
+             * 배터리가 공짜로 무한히 일하는 그림이다.
+             *
+             * 계측으로 들어온 방전(정책이 없는 축전지)은 사실이므로 그대로 센다.
+             */
+            if (this.hasDispatchPolicy(m.id))
+                continue;
+            const d = Number(m.dischargeKW);
+            if (Number.isFinite(d) && d > 0)
+                discharged += d;
         }
         const gross = total + charged;
-        const net = Math.max(0, gross - generated - discharged);
+        /*
+         * ── 선언된 방전 정책이 있으면 여기서 방전한다 (2026-08-17) ────────────────
+         *
+         * 임계를 넘는 만큼만, 최대율 안에서, 예비 SOC 위에 남은 에너지로만. **SOC 가 실제로 줄고**, 다 쓰면
+         * 방전이 멈춰 피크가 다시 올라온다 — 그것이 사실이다. 줄지 않으면 트윈이 「무한히 깎을 수 있다」고
+         * 주장하게 되고, 그 위에 세운 요금 절감액은 짐작이 된다.
+         */
+        const dispatched = this.dispatchStorage(Math.max(0, gross - generated - discharged), atMs, dtMs);
+        const net = Math.max(0, gross - generated - discharged - dispatched);
         this.closeDue(atMs);
         this.openWindow(atMs);
         const w = this.open;
@@ -500,6 +519,91 @@ export class EmsKernel extends FlowEngine {
         this.revision++;
         this.judgeOpenWindow(atMs);
     }
+    /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
+    hasDispatchPolicy(equipmentId) {
+        for (const e of this.boardDef?.equipment ?? []) {
+            if (e.id !== equipmentId)
+                continue;
+            return (this.numberProperty(e, EMS_PROPERTY.capacityKWh) !== undefined &&
+                this.numberProperty(e, EMS_PROPERTY.dischargeAboveKW) !== undefined &&
+                this.numberProperty(e, EMS_PROPERTY.maxDischargeKW) !== undefined);
+        }
+        return false;
+    }
+    /**
+     * 선언된 정책으로 축전지를 방전시킨다 — **선언이 없으면 아무것도 하지 않는다.**
+     *
+     * 돌려주는 값은 이번 틱에 계통에서 덜어낸 kW 다. 부작용으로 그 설비의 `dischargeKW`·`soc` 를 고치고
+     * 사실(`energy.equipment`)을 낸다 — 저널을 읽는 쪽이 「배터리가 무엇을 했나」를 되짚을 수 있어야 한다.
+     *
+     * ── 무엇을 하지 않나 ──────────────────────────────────────────────────────
+     *  · 충전 계획을 만들지 않는다(언제 채울지는 요금 시간대의 일이고, 그 모델은 아직 없다).
+     *  · 용량·임계·최대율이 하나라도 없으면 방전하지 않는다 — 짐작한 수로 피크를 깎지 않는다.
+     *  · 미러 트윈에서는 불리지 않는다(호출자가 이미 관측 모드를 걸러낸다).
+     */
+    dispatchStorage(demandBeforeStorageKW, atMs, dtMs) {
+        let dispatched = 0;
+        for (const e of this.boardDef?.equipment ?? []) {
+            const capacity = this.numberProperty(e, EMS_PROPERTY.capacityKWh);
+            const above = this.numberProperty(e, EMS_PROPERTY.dischargeAboveKW);
+            const maxRate = this.numberProperty(e, EMS_PROPERTY.maxDischargeKW);
+            if (capacity === undefined || above === undefined || maxRate === undefined)
+                continue;
+            if (!(capacity > 0) || !(maxRate > 0))
+                continue;
+            const state = this.equipment.get(e.id);
+            if (!state)
+                continue;
+            const over = demandBeforeStorageKW - dispatched - above;
+            if (over <= 0) {
+                /* 임계 아래 — 쓸 이유가 없다. 낡은 방전값을 남기지 않는다(상태가 지난 틱을 말하게 된다). */
+                if (Number(state.dischargeKW) > 0) {
+                    state.dischargeKW = 0;
+                    this.emitEnergyEquipment(e.id, atMs, { dischargeKW: 0, ...(Number.isFinite(Number(state.soc)) ? { soc: Number(state.soc) } : {}) });
+                }
+                continue;
+            }
+            const reserve = this.numberProperty(e, EMS_PROPERTY.reserveSoc) ?? 0;
+            /* SOC 를 모르면 방전하지 않는다 — 남은 에너지를 모른 채 쓰면 얼마나 버티는지 지어내는 것이다. */
+            const soc = Number(state.soc);
+            if (!Number.isFinite(soc))
+                continue;
+            const usableKWh = ((soc - reserve) / 100) * capacity;
+            if (!(usableKWh > 0)) {
+                /* 다 썼다 — 방전을 멈추고 그 사실을 남긴다(피크가 다시 올라오는 것이 사실이다). */
+                if (Number(state.dischargeKW) > 0) {
+                    state.dischargeKW = 0;
+                    this.emitEnergyEquipment(e.id, atMs, { dischargeKW: 0, soc });
+                }
+                continue;
+            }
+            /*
+             * 이 틱에 낼 수 있는 kW — 남은 에너지를 이 틱 길이로 나눈 값이 상한이다. 틱이 짧으면 이 상한은
+             * 아주 크므로 실제로 묶는 것은 **누적**이다(SOC 가 줄면서 곧 위 검사에 걸린다).
+             */
+            const dtHours = dtMs / 3_600_000;
+            const rateCap = dtHours > 0 ? usableKWh / dtHours : maxRate;
+            const kW = Math.min(maxRate, over, rateCap);
+            if (!(kW > 0))
+                continue;
+            const drained = dtHours > 0 ? ((kW * dtHours) / capacity) * 100 : 0;
+            const nextSoc = Math.max(reserve, soc - drained);
+            state.dischargeKW = kW;
+            state.soc = nextSoc;
+            this.emitEnergyEquipment(e.id, atMs, { dischargeKW: kW, soc: nextSoc });
+            dispatched += kW;
+        }
+        return dispatched;
+    }
+    /**
+     * 파생된 설비 에너지 상태를 사실로 낸다 — **만든 값임을 밝힌다.**
+     *
+     * 계측으로 들어온 것과 같은 자리에 두면서 종류를 적지 않으면, 저널을 읽는 쪽이 우리가 계산한 방전을
+     * 계기가 잰 방전으로 읽는다(수요 구간의 `derived` 와 같은 규율).
+     */
+    emitEnergyEquipment(equipmentId, atMs, fields) {
+        this.emitOp(ENERGY_EVENT.equipment, { equipmentId, at: new Date(atMs).toISOString(), derived: true, ...fields });
+    }
     /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
     numberProperty(resource, id) {
         for (const p of resource?.properties ?? []) {
@@ -523,7 +627,8 @@ export class EmsKernel extends FlowEngine {
          * 부하를 먼저 만들고 마감한다 — 마감이 먼저면 마지막 값이 다음 구간으로 밀린다.
          */
         const at = this.nowMs();
-        this.deriveLoad(at);
+        /* 틱 길이를 함께 넘긴다 — 방전량을 에너지로 바꿀 때 필요하다(필드로 숨기면 어디서 온 값인지 흐려진다). */
+        this.deriveLoad(at, dtMs);
         this.closeDue(at);
     }
     getSnapshot() {

package/dist/ems-profile.d.ts

@@ -22,5 +22,13 @@ export declare const EMS_PROPERTY: {
     readonly energyChargePerKWh: "tariff.energyChargePerKWh";
     /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
     readonly currency: "tariff.currency";
+    /** 축전지 용량(kWh) — SOC 를 에너지로 바꾸는 값. 없으면 방전을 만들지 않는다. */
+    readonly capacityKWh: "storage.capacityKWh";
+    /** 이 순수요를 넘으면 방전한다(kW) — 피크 억제 임계. */
+    readonly dischargeAboveKW: "dispatch.dischargeAboveKW";
+    /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
+    readonly maxDischargeKW: "dispatch.maxDischargeKW";
+    /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
+    readonly reserveSoc: "dispatch.reserveSoc";
 };
 export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -39,7 +39,29 @@ export const EMS_PROPERTY = {
     /** 사용량 단가 — 1kWh 당. */
     energyChargePerKWh: 'tariff.energyChargePerKWh',
     /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
-    currency: 'tariff.currency'
+    currency: 'tariff.currency',
+    /*
+     * ── 축전지의 용량과 방전 정책 (2026-08-17) ─────────────────────────────────
+     *
+     * 「배터리로 피크를 깎는다」를 시뮬이 보이려면 방전을 만들어야 하고, 그것은 **선언에서** 나와야 한다.
+     * 임계·최대율·예비를 우리가 정하면 그 수가 어디서 왔는지 아무도 설명할 수 없다.
+     *
+     * ── 선언한다는 것은 「그 자동화가 있다」는 주장이다 ─────────────────────────
+     * 이 정책을 모델에 적으면 **라이브가 아닌 모든 구동이 그 규칙으로 돈다.** 현장에 BESS 제어기가 없는데
+     * 적으면 파생 부하가 실제보다 낙관적으로 나온다(피크가 깎인 것으로 보인다). 그러니 「도입하면?」을
+     * 묻는 것이라면 선언이 아니라 **what-if 가 덮어쓸 일**이다.
+     *
+     * 용량이 없으면 방전하지 않는다 — 용량을 모르면 「얼마나 버티나」를 답할 수 없고, 버티는 시간을
+     * 모른 채 깎으면 무한히 깎을 수 있다고 주장하는 셈이다.
+     */
+    /** 축전지 용량(kWh) — SOC 를 에너지로 바꾸는 값. 없으면 방전을 만들지 않는다. */
+    capacityKWh: 'storage.capacityKWh',
+    /** 이 순수요를 넘으면 방전한다(kW) — 피크 억제 임계. */
+    dischargeAboveKW: 'dispatch.dischargeAboveKW',
+    /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
+    maxDischargeKW: 'dispatch.maxDischargeKW',
+    /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
+    reserveSoc: 'dispatch.reserveSoc'
 };
 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, 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, 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';
@@ -325,6 +325,10 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 구독자 접근(관측 재방출) — emit 과 같은 목록을 쓴다(두 경로가 갈리지 않게). */
     private handlersRef;
     private gens;
+    /** 가정한 개입 — 시나리오가 실어 온 것들. `pendingMs` 는 시나리오 시작 기준 절대 클록으로 바뀐다. */
+    private interventions;
+    /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
+    private interventionLog;
     private generating;
     private speed;
     private eventSeq;
@@ -412,6 +416,18 @@ export declare abstract class FlowEngine implements TwinKernel {
         /** 확인해 둔 주목 신호 id — 계산으로 되살릴 수 없는 유일한 축이라 스냅샷에서 이어받는다. */
         acked?: string[];
     }, orders?: OrderStatusDelta[]): void;
+    /**
+     * what-if 구성 변주 — **선언을 덮어쓴다**(fork 대상). 바꿨으면 true.
+     *
+     * ── 왜 커맨드가 아닌가 (2026-08-17) ───────────────────────────────────────
+     * 「배터리에 피크 억제 정책을 넣으면?」은 **행동이 아니라 모델의 변주**다. 커맨드로 만들면 트윈이 실물
+     * 설비의 설정을 바꿀 수 있다는 뜻이 되는데, 제어는 범위 밖으로 두기로 했다(보호 계통·안전 사슬).
+     * 그래서 자리 용량 변경과 같은 자리에 둔다 — fork 에서 「만약 이렇게 선언돼 있었다면」을 묻는 손잡이다.
+     *
+     * **선언에 없던 속성도 넣을 수 있다** — 그것이 「도입하면?」의 뜻이다. 다만 원본이 아니라 fork 에
+     * 걸어야 한다: 실행 중 트윈에 걸면 그 트윈이 「우리 현장에 그 자동화가 있다」고 주장하게 된다.
+     */
+    setResourceProperty(resourceId: string, propertyId: string, value: string | number): boolean;
     /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
     setLocationCapacity(locationId: string, capacity: number): boolean;
     /**
@@ -451,6 +467,19 @@ export declare abstract class FlowEngine implements TwinKernel {
      * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
      */
     fork(tenantId?: string): this;
+    /**
+     * 시각이 된 개입을 적용한다 — **한 번만, 그리고 결과를 남긴다.**
+     *
+     * 거절도 사실이다: 커널이 모르는 종류이거나 대상이 없으면 커맨드가 코드로 답하고, 우리는 그것을
+     * 기록한다. 조용히 넘기면 「걸었는데 왜 안 바뀌나」를 아무도 답할 수 없다.
+     */
+    private applyInterventions;
+    /**
+     * 가정한 개입이 어떻게 됐나 — 소비처(예측 화면·AI)가 그대로 옮긴다.
+     *
+     * 아직 시각이 오지 않은 것은 여기 없다(일어나지 않은 일을 결과로 적지 않는다).
+     */
+    interventionOutcomes(): InterventionOutcome[];
     /**
      * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
      *

package/dist/flow-engine.js

@@ -286,6 +286,10 @@ export class FlowEngine {
         return this.handlers;
     }
     gens = [];
+    /** 가정한 개입 — 시나리오가 실어 온 것들. `pendingMs` 는 시나리오 시작 기준 절대 클록으로 바뀐다. */
+    interventions = [];
+    /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
+    interventionLog = [];
     generating = false;
     speed = 1;
     eventSeq = 0;
@@ -682,6 +686,31 @@ export class FlowEngine {
                 'they cannot be continued (the item was consumed/shipped, or the observation did not carry it).');
         }
     }
+    /**
+     * what-if 구성 변주 — **선언을 덮어쓴다**(fork 대상). 바꿨으면 true.
+     *
+     * ── 왜 커맨드가 아닌가 (2026-08-17) ───────────────────────────────────────
+     * 「배터리에 피크 억제 정책을 넣으면?」은 **행동이 아니라 모델의 변주**다. 커맨드로 만들면 트윈이 실물
+     * 설비의 설정을 바꿀 수 있다는 뜻이 되는데, 제어는 범위 밖으로 두기로 했다(보호 계통·안전 사슬).
+     * 그래서 자리 용량 변경과 같은 자리에 둔다 — fork 에서 「만약 이렇게 선언돼 있었다면」을 묻는 손잡이다.
+     *
+     * **선언에 없던 속성도 넣을 수 있다** — 그것이 「도입하면?」의 뜻이다. 다만 원본이 아니라 fork 에
+     * 걸어야 한다: 실행 중 트윈에 걸면 그 트윈이 「우리 현장에 그 자동화가 있다」고 주장하게 된다.
+     */
+    setResourceProperty(resourceId, propertyId, value) {
+        for (const e of this.boardDef?.equipment ?? []) {
+            if (e.id !== resourceId)
+                continue;
+            const props = (e.properties ??= []);
+            const found = props.find((p) => p?.id === propertyId);
+            if (found)
+                found.value = String(value);
+            else
+                props.push({ id: propertyId, value: String(value) });
+            return true;
+        }
+        return false;
+    }
     /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
     setLocationCapacity(locationId, capacity) {
         const n = this.locations.get(locationId);
@@ -843,6 +872,9 @@ export class FlowEngine {
             this.rng = mulberry32((def.seed ?? 1) >>> 0);
             this.speed = def.speed ?? 1;
             this.gens = def.generators.map(spec => ({ spec, nextMs: 0 }));
+            /* 개입은 **시작할 때** 시각이 정해진다(경과 기준) — 여기서는 받아만 둔다. */
+            this.interventions = (def.interventions ?? []).map(spec => ({ spec, dueMs: 0, done: false }));
+            this.interventionLog = [];
         },
         start: () => {
             if (this.generating)
@@ -850,14 +882,25 @@ export class FlowEngine {
             this.generating = true;
             for (const g of this.gens)
                 g.nextMs = this.nextFireMs(g.spec, this.clockMs);
+            /* 경과를 지금 기준으로 절대화한다 — fork 가 언제 갈라져도 같은 가정을 같은 순서로 겪는다. */
+            for (const iv of this.interventions) {
+                iv.dueMs = this.clockMs + Math.max(0, Number(iv.spec.atMs) || 0);
+                iv.done = false;
+            }
         },
         pause: () => { this.generating = false; },
-        reset: () => { this.generating = false; this.gens = []; },
+        reset: () => { this.generating = false; this.gens = []; this.interventions = []; this.interventionLog = []; },
         setSpeed: (f) => { this.speed = f; }
     };
     tick(dtMs) {
         const dt = dtMs * this.speed;
         this.clockMs += dt;
+        /*
+         * 개입을 **자극보다 먼저** 적용한다 — 그 틱에 생기는 일이 바뀐 조건을 보게 해야 한다.
+         * 나중에 적용하면 「세운 설비에 일감을 배정한 뒤 세우는」 한 틱이 생긴다.
+         */
+        if (this.generating)
+            this.applyInterventions();
         if (this.generating)
             this.generate();
         this.processFailures(dt);
@@ -1039,6 +1082,41 @@ export class FlowEngine {
         clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [k, { duration: u.duration, variability: u.variability, params: new Set(u.params) }]));
         return clone;
     }
+    /**
+     * 시각이 된 개입을 적용한다 — **한 번만, 그리고 결과를 남긴다.**
+     *
+     * 거절도 사실이다: 커널이 모르는 종류이거나 대상이 없으면 커맨드가 코드로 답하고, 우리는 그것을
+     * 기록한다. 조용히 넘기면 「걸었는데 왜 안 바뀌나」를 아무도 답할 수 없다.
+     */
+    applyInterventions() {
+        for (const iv of this.interventions) {
+            if (iv.done || this.clockMs < iv.dueMs)
+                continue;
+            iv.done = true;
+            /* 커맨드 계약 그대로 만든다 — 개입은 새 종류의 사건이 아니라 **행동**이다. */
+            const ack = this.dispatch({
+                commandId: `iv-${this.tenantId}-${iv.spec.kind}-${iv.dueMs}`,
+                type: iv.spec.kind,
+                tenantId: this.tenantId,
+                args: iv.spec.args ?? {}
+            });
+            this.interventionLog.push({
+                atMs: iv.spec.atMs,
+                kind: iv.spec.kind,
+                ...(iv.spec.args ? { args: iv.spec.args } : {}),
+                applied: ack.accepted === true,
+                ...(ack.accepted === true ? {} : { refusedCode: ack.errorCode ?? 'refused' })
+            });
+        }
+    }
+    /**
+     * 가정한 개입이 어떻게 됐나 — 소비처(예측 화면·AI)가 그대로 옮긴다.
+     *
+     * 아직 시각이 오지 않은 것은 여기 없다(일어나지 않은 일을 결과로 적지 않는다).
+     */
+    interventionOutcomes() {
+        return this.interventionLog.map(o => ({ ...o }));
+    }
     // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
     /**
      * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.

package/dist-cjs/index.cjs

@@ -1703,7 +1703,29 @@ var EMS_PROPERTY = {
   /** 사용량 단가 — 1kWh 당. */
   energyChargePerKWh: "tariff.energyChargePerKWh",
   /** 통화 — ISO 4217 코드(USD·KRW…). 없으면 금액에 단위를 붙이지 않는다. */
-  currency: "tariff.currency"
+  currency: "tariff.currency",
+  /*
+   * ── 축전지의 용량과 방전 정책 (2026-08-17) ─────────────────────────────────
+   *
+   * 「배터리로 피크를 깎는다」를 시뮬이 보이려면 방전을 만들어야 하고, 그것은 **선언에서** 나와야 한다.
+   * 임계·최대율·예비를 우리가 정하면 그 수가 어디서 왔는지 아무도 설명할 수 없다.
+   *
+   * ── 선언한다는 것은 「그 자동화가 있다」는 주장이다 ─────────────────────────
+   * 이 정책을 모델에 적으면 **라이브가 아닌 모든 구동이 그 규칙으로 돈다.** 현장에 BESS 제어기가 없는데
+   * 적으면 파생 부하가 실제보다 낙관적으로 나온다(피크가 깎인 것으로 보인다). 그러니 「도입하면?」을
+   * 묻는 것이라면 선언이 아니라 **what-if 가 덮어쓸 일**이다.
+   *
+   * 용량이 없으면 방전하지 않는다 — 용량을 모르면 「얼마나 버티나」를 답할 수 없고, 버티는 시간을
+   * 모른 채 깎으면 무한히 깎을 수 있다고 주장하는 셈이다.
+   */
+  /** 축전지 용량(kWh) — SOC 를 에너지로 바꾸는 값. 없으면 방전을 만들지 않는다. */
+  capacityKWh: "storage.capacityKWh",
+  /** 이 순수요를 넘으면 방전한다(kW) — 피크 억제 임계. */
+  dischargeAboveKW: "dispatch.dischargeAboveKW",
+  /** 최대 방전율(kW) — 인버터가 낼 수 있는 한계. */
+  maxDischargeKW: "dispatch.maxDischargeKW",
+  /** 예비 SOC(%) — 이 아래로는 쓰지 않는다(비상 대비). 없으면 0 으로 본다. */
+  reserveSoc: "dispatch.reserveSoc"
 };
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
@@ -2970,6 +2992,10 @@ var FlowEngine = class {
     return this.handlers;
   }
   gens = [];
+  /** 가정한 개입 — 시나리오가 실어 온 것들. `pendingMs` 는 시나리오 시작 기준 절대 클록으로 바뀐다. */
+  interventions = [];
+  /** 개입이 어떻게 됐나 — 걸린 것·거절된 것. 조용히 사라지지 않게 소비처가 읽는다. */
+  interventionLog = [];
   generating = false;
   speed = 1;
   eventSeq = 0;
@@ -3334,6 +3360,28 @@ var FlowEngine = class {
       );
     }
   }
+  /**
+   * what-if 구성 변주 — **선언을 덮어쓴다**(fork 대상). 바꿨으면 true.
+   *
+   * ── 왜 커맨드가 아닌가 (2026-08-17) ───────────────────────────────────────
+   * 「배터리에 피크 억제 정책을 넣으면?」은 **행동이 아니라 모델의 변주**다. 커맨드로 만들면 트윈이 실물
+   * 설비의 설정을 바꿀 수 있다는 뜻이 되는데, 제어는 범위 밖으로 두기로 했다(보호 계통·안전 사슬).
+   * 그래서 자리 용량 변경과 같은 자리에 둔다 — fork 에서 「만약 이렇게 선언돼 있었다면」을 묻는 손잡이다.
+   *
+   * **선언에 없던 속성도 넣을 수 있다** — 그것이 「도입하면?」의 뜻이다. 다만 원본이 아니라 fork 에
+   * 걸어야 한다: 실행 중 트윈에 걸면 그 트윈이 「우리 현장에 그 자동화가 있다」고 주장하게 된다.
+   */
+  setResourceProperty(resourceId, propertyId, value) {
+    for (const e of this.boardDef?.equipment ?? []) {
+      if (e.id !== resourceId) continue;
+      const props = e.properties ??= [];
+      const found = props.find((p) => p?.id === propertyId);
+      if (found) found.value = String(value);
+      else props.push({ id: propertyId, value: String(value) });
+      return true;
+    }
+    return false;
+  }
   /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
   setLocationCapacity(locationId, capacity) {
     const n = this.locations.get(locationId);
@@ -3473,11 +3521,17 @@ var FlowEngine = class {
       this.rng = mulberry32((def.seed ?? 1) >>> 0);
       this.speed = def.speed ?? 1;
       this.gens = def.generators.map((spec) => ({ spec, nextMs: 0 }));
+      this.interventions = (def.interventions ?? []).map((spec) => ({ spec, dueMs: 0, done: false }));
+      this.interventionLog = [];
     },
     start: () => {
       if (this.generating) return;
       this.generating = true;
       for (const g of this.gens) g.nextMs = this.nextFireMs(g.spec, this.clockMs);
+      for (const iv of this.interventions) {
+        iv.dueMs = this.clockMs + Math.max(0, Number(iv.spec.atMs) || 0);
+        iv.done = false;
+      }
     },
     pause: () => {
       this.generating = false;
@@ -3485,6 +3539,8 @@ var FlowEngine = class {
     reset: () => {
       this.generating = false;
       this.gens = [];
+      this.interventions = [];
+      this.interventionLog = [];
     },
     setSpeed: (f) => {
       this.speed = f;
@@ -3493,6 +3549,7 @@ var FlowEngine = class {
   tick(dtMs) {
     const dt = dtMs * this.speed;
     this.clockMs += dt;
+    if (this.generating) this.applyInterventions();
     if (this.generating) this.generate();
     this.processFailures(dt);
     this.processOrders();
@@ -3654,6 +3711,39 @@ var FlowEngine = class {
     clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [k, { duration: u.duration, variability: u.variability, params: new Set(u.params) }]));
     return clone;
   }
+  /**
+   * 시각이 된 개입을 적용한다 — **한 번만, 그리고 결과를 남긴다.**
+   *
+   * 거절도 사실이다: 커널이 모르는 종류이거나 대상이 없으면 커맨드가 코드로 답하고, 우리는 그것을
+   * 기록한다. 조용히 넘기면 「걸었는데 왜 안 바뀌나」를 아무도 답할 수 없다.
+   */
+  applyInterventions() {
+    for (const iv of this.interventions) {
+      if (iv.done || this.clockMs < iv.dueMs) continue;
+      iv.done = true;
+      const ack = this.dispatch({
+        commandId: `iv-${this.tenantId}-${iv.spec.kind}-${iv.dueMs}`,
+        type: iv.spec.kind,
+        tenantId: this.tenantId,
+        args: iv.spec.args ?? {}
+      });
+      this.interventionLog.push({
+        atMs: iv.spec.atMs,
+        kind: iv.spec.kind,
+        ...iv.spec.args ? { args: iv.spec.args } : {},
+        applied: ack.accepted === true,
+        ...ack.accepted === true ? {} : { refusedCode: ack.errorCode ?? "refused" }
+      });
+    }
+  }
+  /**
+   * 가정한 개입이 어떻게 됐나 — 소비처(예측 화면·AI)가 그대로 옮긴다.
+   *
+   * 아직 시각이 오지 않은 것은 여기 없다(일어나지 않은 일을 결과로 적지 않는다).
+   */
+  interventionOutcomes() {
+    return this.interventionLog.map((o) => ({ ...o }));
+  }
   // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
   /**
    * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
@@ -6126,7 +6216,7 @@ var EmsKernel = class extends FlowEngine {
    * ③ 멈춘 설비는 `power.standbyKW` 를 선언한 만큼만 센다. 선언이 없으면 0 이 아니라 **모름**이다.
    * ④ 미러 트윈에서는 아무것도 만들지 않는다 — 관측 구동은 잰 것만 쓴다.
    */
-  deriveLoad(atMs) {
+  deriveLoad(atMs, dtMs) {
     if (this.observing) return;
     let total = 0;
     let counted = 0;
@@ -6153,13 +6243,15 @@ var EmsKernel = class extends FlowEngine {
     for (const m of this.equipment.values()) {
       const g = Number(m.generatedKW);
       if (Number.isFinite(g) && g > 0) generated += g;
-      const d = Number(m.dischargeKW);
-      if (Number.isFinite(d) && d > 0) discharged += d;
       const c = Number(m.chargeKW);
       if (Number.isFinite(c) && c > 0) charged += c;
+      if (this.hasDispatchPolicy(m.id)) continue;
+      const d = Number(m.dischargeKW);
+      if (Number.isFinite(d) && d > 0) discharged += d;
     }
     const gross = total + charged;
-    const net = Math.max(0, gross - generated - discharged);
+    const dispatched = this.dispatchStorage(Math.max(0, gross - generated - discharged), atMs, dtMs);
+    const net = Math.max(0, gross - generated - discharged - dispatched);
     this.closeDue(atMs);
     this.openWindow(atMs);
     const w = this.open;
@@ -6171,6 +6263,76 @@ var EmsKernel = class extends FlowEngine {
     this.revision++;
     this.judgeOpenWindow(atMs);
   }
+  /** 이 설비가 방전 정책을 **선언했나** — 선언한 것의 방전은 정책이 매 틱 다시 정한다. */
+  hasDispatchPolicy(equipmentId) {
+    for (const e of this.boardDef?.equipment ?? []) {
+      if (e.id !== equipmentId) continue;
+      return this.numberProperty(e, EMS_PROPERTY.capacityKWh) !== void 0 && this.numberProperty(e, EMS_PROPERTY.dischargeAboveKW) !== void 0 && this.numberProperty(e, EMS_PROPERTY.maxDischargeKW) !== void 0;
+    }
+    return false;
+  }
+  /**
+   * 선언된 정책으로 축전지를 방전시킨다 — **선언이 없으면 아무것도 하지 않는다.**
+   *
+   * 돌려주는 값은 이번 틱에 계통에서 덜어낸 kW 다. 부작용으로 그 설비의 `dischargeKW`·`soc` 를 고치고
+   * 사실(`energy.equipment`)을 낸다 — 저널을 읽는 쪽이 「배터리가 무엇을 했나」를 되짚을 수 있어야 한다.
+   *
+   * ── 무엇을 하지 않나 ──────────────────────────────────────────────────────
+   *  · 충전 계획을 만들지 않는다(언제 채울지는 요금 시간대의 일이고, 그 모델은 아직 없다).
+   *  · 용량·임계·최대율이 하나라도 없으면 방전하지 않는다 — 짐작한 수로 피크를 깎지 않는다.
+   *  · 미러 트윈에서는 불리지 않는다(호출자가 이미 관측 모드를 걸러낸다).
+   */
+  dispatchStorage(demandBeforeStorageKW, atMs, dtMs) {
+    let dispatched = 0;
+    for (const e of this.boardDef?.equipment ?? []) {
+      const capacity = this.numberProperty(e, EMS_PROPERTY.capacityKWh);
+      const above = this.numberProperty(e, EMS_PROPERTY.dischargeAboveKW);
+      const maxRate = this.numberProperty(e, EMS_PROPERTY.maxDischargeKW);
+      if (capacity === void 0 || above === void 0 || maxRate === void 0) continue;
+      if (!(capacity > 0) || !(maxRate > 0)) continue;
+      const state = this.equipment.get(e.id);
+      if (!state) continue;
+      const over = demandBeforeStorageKW - dispatched - above;
+      if (over <= 0) {
+        if (Number(state.dischargeKW) > 0) {
+          state.dischargeKW = 0;
+          this.emitEnergyEquipment(e.id, atMs, { dischargeKW: 0, ...Number.isFinite(Number(state.soc)) ? { soc: Number(state.soc) } : {} });
+        }
+        continue;
+      }
+      const reserve = this.numberProperty(e, EMS_PROPERTY.reserveSoc) ?? 0;
+      const soc = Number(state.soc);
+      if (!Number.isFinite(soc)) continue;
+      const usableKWh = (soc - reserve) / 100 * capacity;
+      if (!(usableKWh > 0)) {
+        if (Number(state.dischargeKW) > 0) {
+          state.dischargeKW = 0;
+          this.emitEnergyEquipment(e.id, atMs, { dischargeKW: 0, soc });
+        }
+        continue;
+      }
+      const dtHours = dtMs / 36e5;
+      const rateCap = dtHours > 0 ? usableKWh / dtHours : maxRate;
+      const kW = Math.min(maxRate, over, rateCap);
+      if (!(kW > 0)) continue;
+      const drained = dtHours > 0 ? kW * dtHours / capacity * 100 : 0;
+      const nextSoc = Math.max(reserve, soc - drained);
+      state.dischargeKW = kW;
+      state.soc = nextSoc;
+      this.emitEnergyEquipment(e.id, atMs, { dischargeKW: kW, soc: nextSoc });
+      dispatched += kW;
+    }
+    return dispatched;
+  }
+  /**
+   * 파생된 설비 에너지 상태를 사실로 낸다 — **만든 값임을 밝힌다.**
+   *
+   * 계측으로 들어온 것과 같은 자리에 두면서 종류를 적지 않으면, 저널을 읽는 쪽이 우리가 계산한 방전을
+   * 계기가 잰 방전으로 읽는다(수요 구간의 `derived` 와 같은 규율).
+   */
+  emitEnergyEquipment(equipmentId, atMs, fields) {
+    this.emitOp(ENERGY_EVENT.equipment, { equipmentId, at: new Date(atMs).toISOString(), derived: true, ...fields });
+  }
   /** 자원 속성에서 수 하나 — 값이 수가 아니면 없는 것으로 본다(짐작하지 않는다). */
   numberProperty(resource, id) {
     for (const p of resource?.properties ?? []) {
@@ -6183,7 +6345,7 @@ var EmsKernel = class extends FlowEngine {
   tick(dtMs) {
     super.tick(dtMs);
     const at = this.nowMs();
-    this.deriveLoad(at);
+    this.deriveLoad(at, dtMs);
     this.closeDue(at);
   }
   getSnapshot() {

package/package.json

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