@operato/twin-kernel 0.7.8 → 0.7.10

package/dist/energy-attribution.d.ts

@@ -171,6 +171,20 @@ export declare function energyIntensity(input: IntensityInput): IntensityResult;
 export interface WindowedEnergy {
     /** 그 범위의 전력량 — 셀 수 있는 구간이 하나도 없으면 `undefined`(0 이 아니다). */
     kWh?: number;
+    /**
+     * 그 범위의 **최대수요** — 구간 최대부하 중 가장 큰 값. 요금이 걸리는 수다.
+     *
+     * ── 왜 여기서 내나 (2026-08-17) ──────────────────────────────────────────
+     * 「이 범위」를 정하는 규칙(걸친 구간은 세지 않는다)이 이미 여기 있다. 최대수요를 소비처에서 따로
+     * 세면 그 경계 규칙이 두 벌이 되고, 전력량과 최대수요가 **서로 다른 구간 집합**을 말하게 된다 —
+     * 같은 창을 두고 두 수가 어긋나면 어느 쪽도 못 믿는다.
+     *
+     * 평균부하(`meanKW`)로 대신하지 않는다. 15분 평균 400kW 인 구간의 최대가 900kW 일 수 있고,
+     * 계약을 넘겼는지는 **최대**가 답한다. 구간이 최대를 싣고 오지 않으면 이 값은 없다(짐작하지 않는다).
+     */
+    peakKW?: number;
+    /** 그 최대수요가 난 구간의 시작 — 「언제였나」를 물으면 답할 수 있어야 한다. */
+    peakStartMs?: number;
     /**
      * 어떻게 얻었나 — **파생임을 숨기지 않는다.**
      *  · `mean-kw` — 구간 평균부하 × 구간 길이. 표본의 평균이므로 **추정**이다.
@@ -202,6 +216,7 @@ export declare function energyOfWindows(windows: readonly {
     startMs: number;
     endMs: number;
     meanKW?: number;
+    maxKW?: number;
 }[], range?: {
     startMs: number;
     endMs: number;

package/dist/energy-attribution.js

@@ -203,9 +203,20 @@ export function energyOfWindows(windows, range) {
     let skipped = 0;
     let first;
     let last;
+    let peakKW;
+    let peakStartMs;
     for (const w of windows ?? []) {
         if (!inRange(w))
             continue;
+        /*
+         * 최대수요는 전력량과 **따로 센다.** 평균을 못 읽어 전력량에서 빠진 구간도 최대는 실려 올 수
+         * 있고(그 반대도 있다), 하나가 없다고 다른 하나를 버리면 있는 사실을 잃는다.
+         */
+        const max = Number(w.maxKW);
+        if (Number.isFinite(max) && (peakKW === undefined || max > peakKW)) {
+            peakKW = max;
+            peakStartMs = Number(w.startMs);
+        }
         const mean = Number(w.meanKW);
         const hours = (Number(w.endMs) - Number(w.startMs)) / 3_600_000;
         if (!Number.isFinite(mean) || !Number.isFinite(hours) || hours <= 0) {
@@ -221,6 +232,7 @@ export function energyOfWindows(windows, range) {
     }
     return {
         ...(counted > 0 ? { kWh } : {}),
+        ...(peakKW !== undefined ? { peakKW, peakStartMs } : {}),
         basis: 'mean-kw',
         counted,
         skipped,

package/dist/forecast.d.ts

@@ -35,3 +35,22 @@ export interface MonteCarloOptions {
  * run 마다 fork(현재 보존) + scenario.load(seed+i)(미래 변주) + horizon 까지 구동. 원본 무간섭.
  */
 export declare function monteCarloForecast(twin: ForecastTwin, opts: MonteCarloOptions): MonteCarloResult;
+/**
+ * 같은 예측을, **회차 사이에 자리를 내주면서** 계산한다.
+ *
+ * ── 왜 필요한가 (2026-08-17 실측) ───────────────────────────────────────────
+ * 이 예측은 호출한 쪽의 이벤트 루프에서 **동기로** 돈다. 실측으로 트윈 하나의 예측 한 번이
+ * 30회차 × 300틱 = 9,000틱, 한 틱 3.2ms → **28.5초**였다. 그동안 그 프로세스의 라이브 트윈도,
+ * HTTP 도, 구독도 전부 멈춘다 — 예측 한 번에 시스템 전체가 정지한다.
+ *
+ * 총 시간은 이 함수로 줄지 않는다(그건 틱 수를 줄이는 다른 일이다). 줄어드는 것은 **한 번에
+ * 붙잡는 시간**이다. 회차 하나가 끝날 때마다 자리를 내주면 그 사이에 틱과 요청이 지나간다.
+ *
+ * 양보 방법은 **호출자가 준다.** 커널은 실행 환경을 모른다(`setImmediate` 는 서버 런타임의 것이다).
+ * 주지 않으면 마이크로태스크로 떨어지는데, 그것은 I/O 에 자리를 내주지 못하므로 **얼어붙는 증상은
+ * 그대로**다 — 그래서 기본값에 기대지 말고 호출자가 명시하는 것이 맞다.
+ */
+export declare function monteCarloForecastAsync(twin: ForecastTwin, opts: MonteCarloOptions & {
+    yieldFn?: () => Promise<void>;
+    yieldEveryTicks?: number;
+}): Promise<MonteCarloResult>;

package/dist/forecast.js

@@ -18,14 +18,9 @@ function clockOf(twin) {
  */
 export function monteCarloForecast(twin, opts) {
     const now = clockOf(twin);
-    const step = opts.tickMs ?? 1000;
-    const baseSeed = opts.scenario.seed ?? 1;
     const samples = [];
     for (let i = 0; i < opts.runs; i++) {
-        const fc = twin.fork();
-        fc.scenario.load({ ...opts.scenario, seed: baseSeed + i }); // 미래만 변주(현재 상태는 fork 로 보존)
-        fc.scenario.start();
-        const target = now + opts.horizonMs;
+        const { fc, step, target } = startRun(twin, opts, now, i);
         let guard = 0;
         while (clockOf(fc) < target && guard++ < 1_000_000)
             fc.tick(step);
@@ -33,6 +28,61 @@ export function monteCarloForecast(twin, opts) {
     }
     return summarize(opts.runs, samples);
 }
+/**
+ * 한 회차의 **출발점** — fork(현재 보존) + 그 회차의 미래(seed 변주).
+ *
+ * 동기·비동기 두 진입점이 이것을 함께 쓴다. 구동 루프는 각자 쓰지만(하나는 중간에 await 한다),
+ * **표본이 무엇이 되는지를 정하는 규칙**(어디서 갈라져 어떤 seed 로 도는가)은 여기 한 곳이다.
+ * 그것이 갈라지면 같은 seed 가 다른 수를 내고, 그때는 어느 쪽이 옳은지 가릴 방법이 없다.
+ */
+function startRun(twin, opts, nowMs, i) {
+    const fc = twin.fork();
+    fc.scenario.load({ ...opts.scenario, seed: (opts.scenario.seed ?? 1) + i }); // 미래만 변주(현재 상태는 fork 로 보존)
+    fc.scenario.start();
+    return { fc, step: opts.tickMs ?? 1000, target: nowMs + opts.horizonMs };
+}
+/**
+ * 같은 예측을, **회차 사이에 자리를 내주면서** 계산한다.
+ *
+ * ── 왜 필요한가 (2026-08-17 실측) ───────────────────────────────────────────
+ * 이 예측은 호출한 쪽의 이벤트 루프에서 **동기로** 돈다. 실측으로 트윈 하나의 예측 한 번이
+ * 30회차 × 300틱 = 9,000틱, 한 틱 3.2ms → **28.5초**였다. 그동안 그 프로세스의 라이브 트윈도,
+ * HTTP 도, 구독도 전부 멈춘다 — 예측 한 번에 시스템 전체가 정지한다.
+ *
+ * 총 시간은 이 함수로 줄지 않는다(그건 틱 수를 줄이는 다른 일이다). 줄어드는 것은 **한 번에
+ * 붙잡는 시간**이다. 회차 하나가 끝날 때마다 자리를 내주면 그 사이에 틱과 요청이 지나간다.
+ *
+ * 양보 방법은 **호출자가 준다.** 커널은 실행 환경을 모른다(`setImmediate` 는 서버 런타임의 것이다).
+ * 주지 않으면 마이크로태스크로 떨어지는데, 그것은 I/O 에 자리를 내주지 못하므로 **얼어붙는 증상은
+ * 그대로**다 — 그래서 기본값에 기대지 말고 호출자가 명시하는 것이 맞다.
+ */
+export async function monteCarloForecastAsync(twin, opts) {
+    const now = clockOf(twin);
+    const yieldFn = opts.yieldFn ?? (() => Promise.resolve());
+    /*
+     * **회차 사이만 내주면 부족하다.** 회차 하나가 300틱 × 3.2ms ≈ 1초라, 그동안 들어온 요청은 그만큼
+     * 기다린다(실측 응답 3초). 그래서 틱 몇 개마다도 끊는다 — 기본값은 라이브 틱 간격(1초)보다 훨씬
+     * 짧게 잡아, 트윈이 한 박자도 밀리지 않을 크기로 둔다.
+     */
+    const everyTicks = Math.max(1, opts.yieldEveryTicks ?? 50);
+    const samples = [];
+    for (let i = 0; i < opts.runs; i++) {
+        const { fc, step, target } = startRun(twin, opts, now, i);
+        let guard = 0;
+        let sinceYield = 0;
+        while (clockOf(fc) < target && guard++ < 1_000_000) {
+            fc.tick(step);
+            if (++sinceYield >= everyTicks) {
+                sinceYield = 0;
+                await yieldFn();
+            }
+        }
+        samples.push(opts.metric(fc.getSnapshot()));
+        if (i < opts.runs - 1)
+            await yieldFn();
+    }
+    return summarize(opts.runs, samples);
+}
 function summarize(runs, samples) {
     const sorted = [...samples].sort((a, b) => a - b);
     const pct = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];

package/dist-cjs/index.cjs

@@ -122,6 +122,7 @@ __export(index_exports, {
   meetsTests: () => meetsTests,
   minuteOfDayAt: () => minuteOfDayAt,
   monteCarloForecast: () => monteCarloForecast,
+  monteCarloForecastAsync: () => monteCarloForecastAsync,
   objectEvent: () => objectEvent,
   offCalendarAt: () => offCalendarAt,
   offCalendarReasonAt: () => offCalendarReasonAt,
@@ -730,20 +731,42 @@ function clockOf2(twin) {
 }
 function monteCarloForecast(twin, opts) {
   const now = clockOf2(twin);
-  const step = opts.tickMs ?? 1e3;
-  const baseSeed = opts.scenario.seed ?? 1;
   const samples = [];
   for (let i = 0; i < opts.runs; i++) {
-    const fc = twin.fork();
-    fc.scenario.load({ ...opts.scenario, seed: baseSeed + i });
-    fc.scenario.start();
-    const target = now + opts.horizonMs;
+    const { fc, step, target } = startRun(twin, opts, now, i);
     let guard = 0;
     while (clockOf2(fc) < target && guard++ < 1e6) fc.tick(step);
     samples.push(opts.metric(fc.getSnapshot()));
   }
   return summarize(opts.runs, samples);
 }
+function startRun(twin, opts, nowMs, i) {
+  const fc = twin.fork();
+  fc.scenario.load({ ...opts.scenario, seed: (opts.scenario.seed ?? 1) + i });
+  fc.scenario.start();
+  return { fc, step: opts.tickMs ?? 1e3, target: nowMs + opts.horizonMs };
+}
+async function monteCarloForecastAsync(twin, opts) {
+  const now = clockOf2(twin);
+  const yieldFn = opts.yieldFn ?? (() => Promise.resolve());
+  const everyTicks = Math.max(1, opts.yieldEveryTicks ?? 50);
+  const samples = [];
+  for (let i = 0; i < opts.runs; i++) {
+    const { fc, step, target } = startRun(twin, opts, now, i);
+    let guard = 0;
+    let sinceYield = 0;
+    while (clockOf2(fc) < target && guard++ < 1e6) {
+      fc.tick(step);
+      if (++sinceYield >= everyTicks) {
+        sinceYield = 0;
+        await yieldFn();
+      }
+    }
+    samples.push(opts.metric(fc.getSnapshot()));
+    if (i < opts.runs - 1) await yieldFn();
+  }
+  return summarize(opts.runs, samples);
+}
 function summarize(runs, samples) {
   const sorted = [...samples].sort((a, b) => a - b);
   const pct = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
@@ -6339,8 +6362,15 @@ function energyOfWindows(windows, range) {
   let skipped = 0;
   let first;
   let last;
+  let peakKW;
+  let peakStartMs;
   for (const w of windows ?? []) {
     if (!inRange(w)) continue;
+    const max = Number(w.maxKW);
+    if (Number.isFinite(max) && (peakKW === void 0 || max > peakKW)) {
+      peakKW = max;
+      peakStartMs = Number(w.startMs);
+    }
     const mean = Number(w.meanKW);
     const hours = (Number(w.endMs) - Number(w.startMs)) / 36e5;
     if (!Number.isFinite(mean) || !Number.isFinite(hours) || hours <= 0) {
@@ -6354,6 +6384,7 @@ function energyOfWindows(windows, range) {
   }
   return {
     ...counted > 0 ? { kWh } : {},
+    ...peakKW !== void 0 ? { peakKW, peakStartMs } : {},
     basis: "mean-kw",
     counted,
     skipped,
@@ -6508,6 +6539,7 @@ function retiredVocabularyIn(line) {
   meetsTests,
   minuteOfDayAt,
   monteCarloForecast,
+  monteCarloForecastAsync,
   objectEvent,
   offCalendarAt,
   offCalendarReasonAt,

package/package.json

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