@operato/twin-kernel 0.7.9 → 0.7.10

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))];
@@ -6516,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.9",
+  "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": {