@operato/twin-kernel 0.0.6 → 0.2.0

package/dist/flow-engine.js

@@ -11,6 +11,7 @@
  */
 import { OP_EVENT, CMD } from "./contract.js";
 import { transformationEvent, aggregationEvent, objectEvent, DISP } from "./epcis.js";
+import { parseIsoDuration } from "./iso-duration.js";
 const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z');
 function mulberry32(seed) {
     let a = seed >>> 0;
@@ -116,14 +117,25 @@ export class FlowEngine {
     nodes = new Map();
     items = new Map();
     movers = new Map();
+    /** 사람 — 선언하지 않으면 빈 맵(인원 제약 없는 트윈, 기존 거동). */
+    persons = new Map();
+    /** 물리 자산 — 선언하지 않으면 빈 맵(자산 제약 없는 트윈, 기존 거동). */
+    assets = new Map();
     tasks = new Map();
     orders = new Map();
     revision = 0;
     clockMs = 0;
     rng = mulberry32(1);
     policy;
-    /** duration 시임(선택) — 미주입 시 도메인 상수. 씬/보드 바인딩이 거리·속도 기반 estimator 주입. */
+    /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
     durationEstimator;
+    /**
+     * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
+     * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
+     */
+    operationSpecs = new Map();
+    /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
+    specUse = new Map();
     epcSeq = 0;
     taskSeq = 0;
     orderSeq = 0;
@@ -140,9 +152,13 @@ export class FlowEngine {
     // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
     loadBoard(def) {
         for (const n of def.nodes)
-            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, occupancy: 0, status: 'idle', parentId: n.parentId });
+            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, occupancy: 0, status: 'idle', parentId: n.parentId });
+        for (const p of def.persons ?? [])
+            this.persons.set(p.id, { id: p.id, personnelClass: p.personnelClass, status: 'idle', taskId: null, window: p.window });
+        for (const a of def.assets ?? [])
+            this.assets.set(a.id, { id: a.id, assetClass: a.assetClass, location: a.homeNode, status: 'idle', taskId: null });
         for (const m of def.movers) {
-            const mover = { id: m.id, kind: m.kind, location: m.homeNode, status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 };
+            const mover = { id: m.id, kind: m.kind, location: m.homeNode, status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window };
             if (m.mtbfMs !== undefined) {
                 mover.mtbfMs = m.mtbfMs;
                 mover.mttrMs = m.mttrMs;
@@ -174,13 +190,89 @@ export class FlowEngine {
      * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
      */
     hydrateObserved(snap, orders = []) {
-        for (const n of snap.nodes)
-            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity ?? 0, occupancy: n.occupancy ?? 0, status: 'idle', parentId: n.parentId });
+        /* **관측된 것을 버리지 않는다.** 예전에는 노드·무버 상태를 'idle' 로, OEE 누적을 0 으로 덮고
+         * 물품의 로트·단위·소속·마스터데이터를 떨어뜨렸다. 씨앗이 잃은 것은 **예측도 모른다** —
+         * 고장 난 설비를 정상으로, 진행 중인 일을 없는 것으로 놓고 미래를 굴리면 답이 낙관 쪽으로 치우친다. */
+        for (const n of snap.nodes) {
+            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity ?? 0, parallelism: n.parallelism, occupancy: n.occupancy ?? 0, status: n.status ?? 'idle', parentId: n.parentId });
+        }
         this.items.clear();
-        for (const it of snap.items)
-            this.items.set(it.epc, { epc: it.epc, location: it.location, disposition: it.disposition ?? DISP.sellable, gtin: it.gtin, qty: it.qty ?? 1 });
-        for (const m of snap.movers)
-            this.movers.set(m.id, { id: m.id, kind: m.kind, location: m.location ?? '', status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 });
+        for (const it of snap.items) {
+            this.items.set(it.epc, {
+                epc: it.epc, location: it.location, disposition: it.disposition ?? DISP.sellable,
+                gtin: it.gtin, gtinKey: it.gtinKey, lot: it.lot, qty: it.qty ?? 1, uom: it.uom,
+                parent: it.parent, expiry: it.expiry, ilmd: it.ilmd
+            });
+        }
+        for (const m of snap.movers) {
+            /*
+             * 관측된 계측을 이어받는다 — **없어서 0 이었던 게 아니라 잘못 읽어서 0 이었다.**
+             * `OeeMetrics` 의 이름은 `runMs`·`setupMs`·`downMs`·`goodCount`·`scrapCount` 인데 예전 코드가
+             * `oee.good`·`oee.scrap`(존재하지 않는 키)을 읽어 항상 0 으로 떨어졌고, 시간 누적은 아예 0 으로
+             * 시작했다. 그래서 씨앗이 "가동 이력이 전혀 없는 설비" 로 출발해 예측의 OEE 가 리셋됐다.
+             *
+             * 라이브(미러)에서 이 값의 출처: 원 시스템이 시간 누적을 보내 주는 것이 아니라, 호스트가
+             * `equipment.status` 전이 구간을 적분하고 `quality.output` 카운터를 모아 파생한다. 그 파생에는
+             * 한계가 있다 — busy 를 가동으로 근사하고 **셋업을 분리하지 못해 0** 으로 둔다. 여기서는 받은
+             * 값을 그대로 이어받고, 없으면 0 에서 시작한다(꾸미지 않는다).
+             */
+            const oee = m.oee;
+            this.movers.set(m.id, {
+                id: m.id, kind: m.kind, location: m.location ?? '', status: m.status ?? 'idle', taskId: null,
+                runMs: oee?.runMs ?? 0, setupMs: oee?.setupMs ?? 0, downMs: oee?.downMs ?? 0,
+                goodCount: oee?.goodCount ?? 0, scrapCount: oee?.scrapCount ?? 0
+            });
+        }
+        /* 사람을 이어 붙인다 — **없으면 인원 요구가 영원히 채워지지 않는다.** 관측 상태에 사람이 있는데
+         * 씨앗이 버리면, 인원을 요구하는 공정의 작업이 하나도 시작되지 못하고 예측이 멈춘다(0 명 < 2 명).
+         * 배정 상태(busy/taskId)는 아래 작업 복원이 다시 세우므로 여기서는 등급·교대만 살린다. */
+        for (const p of snap.persons ?? []) {
+            this.persons.set(p.id, { id: p.id, personnelClass: p.personnelClass, status: 'idle', taskId: null });
+        }
+        /* 자산도 같다 — 잃으면 자산을 요구하는 작업이 영원히 못 나간다(빈 팔레트 0개 < 1개). */
+        for (const a of snap.assets ?? []) {
+            this.assets.set(a.id, { id: a.id, assetClass: a.assetClass, location: a.location, status: 'idle', taskId: null, carrying: a.carrying });
+        }
+        /* 진행 중이던 작업을 이어 붙인다 — 없으면 예측이 "일이 하나도 없는 현장" 에서 출발한다.
+         * 남은 시간을 모르면 **진척을 꾸미지 않고** 미착수(created)로 되돌린다: 그 일이 남아 있다는 사실은
+         * 지키면서, 얼마나 진행됐는지는 모른다고 말하는 쪽이 정직하다(커널이 다시 배정해 굴린다). */
+        for (const t of snap.tasks ?? []) {
+            if (t.status === 'completed')
+                continue;
+            const known = typeof t.remainingMs === 'number' && Number.isFinite(t.remainingMs);
+            this.tasks.set(t.id, {
+                id: t.id, kind: t.kind,
+                status: known && t.status === 'in-progress' ? 'in-progress' : 'created',
+                itemEpc: t.itemRefs?.[0] ?? '',
+                fromNode: t.fromNode ?? '', toNode: t.toNode ?? '',
+                resource: known && t.status === 'in-progress' ? (t.resourceRef ?? null) : null,
+                remainingMs: known ? t.remainingMs : (t.durationMs ?? 0),
+                durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
+                orderId: t.orderId,
+                intent: t.intent
+            });
+            /* 진행 중으로 살린 작업은 그 자원을 점유한 상태여야 한다(자원이 동시에 다른 일을 받지 않게). */
+            if (known && t.status === 'in-progress' && t.resourceRef) {
+                const mv = this.movers.get(t.resourceRef);
+                if (mv) {
+                    mv.status = 'busy';
+                    mv.taskId = t.id;
+                }
+            }
+            /* 사람도 같다 — 진행 중이던 작업에 투입돼 있던 사람은 여전히 묶여 있어야 한다. */
+            if (known && t.status === 'in-progress') {
+                const restored = this.tasks.get(t.id);
+                if (restored)
+                    restored.personnel = t.personnel ? [...t.personnel] : undefined;
+                for (const id of t.personnel ?? []) {
+                    const pp = this.persons.get(id);
+                    if (pp) {
+                        pp.status = 'busy';
+                        pp.taskId = t.id;
+                    }
+                }
+            }
+        }
         for (const o of orders) {
             const lines = (o.lines ?? []).map(l => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter(l => l.requested > 0);
             const remaining = lines.reduce((s, l) => s + l.requested, 0);
@@ -326,7 +418,7 @@ export class FlowEngine {
                 return;
             this.generating = true;
             for (const g of this.gens)
-                g.nextMs = this.clockMs + this.intervalMs(g.spec);
+                g.nextMs = this.nextFireMs(g.spec, this.clockMs);
         },
         pause: () => { this.generating = false; },
         reset: () => { this.generating = false; this.gens = []; },
@@ -348,13 +440,25 @@ export class FlowEngine {
             nodes: [...this.nodes.values()].map(n => ({ ...n })),
             items: [...this.items.values()].map(i => ({ epc: i.epc, gtin: i.gtin, qty: i.qty, location: i.location, disposition: i.disposition, expiry: i.expiry })),
             movers: [...this.movers.values()].map(m => {
-                const s = { id: m.id, kind: m.kind, location: m.location, status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held };
+                const s = { id: m.id, kind: m.kind, location: m.location, status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(this.offShift(m) ? { offShift: true } : {}) };
                 const t = m.taskId ? this.tasks.get(m.taskId) : undefined;
                 if (t && t.status === 'in-progress' && t.intent !== 'process')
                     s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
                 return s;
             }),
-            tasks: [...this.tasks.values()].map(t => ({ id: t.id, kind: t.kind, status: t.status, itemRefs: [t.itemEpc], fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, orderId: t.orderId, progress: t.status === 'in-progress' ? this.progressOf(t) : undefined })),
+            assets: [...this.assets.values()].map(a => {
+                const st = { id: a.id, assetClass: a.assetClass, location: a.location, status: a.status, taskId: a.taskId ?? undefined };
+                if (a.carrying)
+                    st.carrying = a.carrying;
+                return st;
+            }),
+            persons: [...this.persons.values()].map(p => {
+                const st = { id: p.id, personnelClass: p.personnelClass, status: p.status, taskId: p.taskId ?? undefined };
+                if (this.personOffShift(p))
+                    st.offShift = true;
+                return st;
+            }),
+            tasks: [...this.tasks.values()].map(t => ({ id: t.id, kind: t.kind, status: t.status, itemRefs: [t.itemEpc], fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, orderId: t.orderId, progress: t.status === 'in-progress' ? this.progressOf(t) : undefined, ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}) })),
             orders: [...this.orders.values()].map(o => ({ id: o.id, kind: o.kind, status: o.status, progress: o.requested ? o.fulfilled / o.requested : 0, held: o.held })),
             attentions: this.computeAttentions()
         };
@@ -398,14 +502,149 @@ export class FlowEngine {
         }
         clone.rng.state = this.rng.state; // RNG 연속성 → 생성 포함 결정적 분기
         clone.durationEstimator = this.durationEstimator; // 무상태 시임 — 참조 공유(policy 와 동형)
+        /* 명세는 불변(정의) → 참조 공유. 사용 기록은 fork 자기 것(무엇을 기본값으로 굴렸는지 fork 별로 다르다). */
+        clone.operationSpecs = this.operationSpecs;
+        clone.specUse = new Map([...this.specUse.entries()].map(([k, u]) => [k, { duration: u.duration, variability: u.variability, params: new Set(u.params) }]));
         return clone;
     }
     // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
     now() { return new Date(BASE_EPOCH + this.clockMs).toISOString(); }
     randInt(min, max) { return max <= min ? min : min + Math.floor(this.rng() * (max - min + 1)); }
-    /** task 소요 산출 — estimator 주입 시 그 값, 미주입/undefined 시 도메인 상수(fallback). "얼마"만 소비, "경로"는 씬. */
+    /**
+     * 오퍼레이션 명세를 싣는다 — 도메인 정의(ISA-95 OperationsSegment)의 시뮬 명세를 커널이 소비하는 입구.
+     * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
+     */
+    loadOperations(ops = []) {
+        for (const o of ops)
+            if (o?.key)
+                this.operationSpecs.set(o.key, o);
+    }
+    /**
+     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
+     *
+     * 이 순서인 이유: 실측에서 배운 값이 선언값을 이기고, 선언값이 우리가 코드에 박아 둔 상수를 이긴다.
+     * 셋 중 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
+     * "얼마"만 소비하고 "경로"는 씬이 소유한다(좌표-free 유지).
+     */
     durationOf(ctx, fallbackMs) {
-        return this.durationEstimator?.estimate(ctx) ?? fallbackMs;
+        const estimated = this.durationEstimator?.estimate(ctx);
+        /* 추정기가 답한 것은 **실측·계산에서 온 값**이므로 선언값과 구별해 기록한다 — "현장이 선언했다" 와
+         * "이력에서 배웠다" 는 예측의 자격이 다르다(후자가 더 강하다). 뭉개면 그 차이가 사라진다. */
+        if (typeof estimated === 'number') {
+            this.noteSpecUse(ctx.kind, 'measured');
+            return estimated;
+        }
+        if (estimated) {
+            /* 분포까지 아는 추정치 — **관측된 퍼짐**으로 흔든다. 평균만 쓰면 변동이 0 이라 줄이 생기지 않는다. */
+            this.noteSpecUse(ctx.kind, 'measured', estimated.spread?.distribution);
+            return this.sampleSpread(estimated.meanMs, estimated.spread);
+        }
+        const spec = this.operationSpecs.get(ctx.kind);
+        const declared = parseIsoDuration(spec?.duration);
+        if (declared === undefined) {
+            this.noteSpecUse(ctx.kind, 'default');
+            return fallbackMs;
+        }
+        this.noteSpecUse(ctx.kind, 'declared');
+        return this.applyVariability(declared, spec?.variability);
+    }
+    /**
+     * 소요시간 변동 표본 — **엔진 난수원으로만** 뽑는다(fork 결정성). 표준 밖 확장이므로 미지정이면 상수.
+     * 모수가 모자라면(uniform 에 min/max 없음 등) 변동을 발명하지 않고 평균을 그대로 쓴다.
+     */
+    applyVariability(meanMs, v) {
+        if (!v || v.distribution === 'constant')
+            return meanMs;
+        if (v.distribution === 'exponential')
+            return -Math.log(1 - this.rng()) * meanMs;
+        const minMs = parseIsoDuration(v.min);
+        const maxMs = parseIsoDuration(v.max);
+        if (minMs === undefined || maxMs === undefined)
+            return meanMs;
+        return this.sampleSpread(meanMs, { distribution: v.distribution, minMs, maxMs, modeMs: parseIsoDuration(v.mode) });
+    }
+    /**
+     * 퍼짐 표본 — **엔진 난수원으로만** 뽑는다(fork 결정성). 선언 명세(ISO 표기)와 실측 분포(ms)가
+     * 같은 수식을 쓴다: 한쪽만 고치면 두 경로가 다른 답을 낸다.
+     * 모수가 모자라거나 뒤집혀 있으면 **퍼짐을 발명하지 않고** 평균을 그대로 쓴다.
+     */
+    sampleSpread(meanMs, spread) {
+        if (!spread)
+            return meanMs;
+        const { minMs, maxMs } = spread;
+        if (!Number.isFinite(minMs) || !Number.isFinite(maxMs) || maxMs < minMs)
+            return meanMs;
+        if (spread.distribution === 'uniform')
+            return minMs + this.rng() * (maxMs - minMs);
+        // triangular — 최빈값 미지정이면 평균을 최빈값으로 본다(구간 밖이면 안으로 클램프).
+        const mode = Math.min(maxMs, Math.max(minMs, spread.modeMs ?? meanMs));
+        const u = this.rng();
+        const span = maxMs - minMs;
+        if (span <= 0)
+            return minMs;
+        const c = (mode - minMs) / span;
+        return u < c ? minMs + Math.sqrt(u * span * (mode - minMs)) : maxMs - Math.sqrt((1 - u) * span * (maxMs - mode));
+    }
+    /** 명세 모수(숫자) — 선언 없으면 undefined(0 으로 꾸미지 않는다). 소비처가 기본값을 정한다. */
+    paramNumber(opKey, id) {
+        const p = this.operationSpecs.get(opKey)?.parameters?.find(x => x.id === id);
+        if (!p)
+            return undefined;
+        const n = Number(p.value);
+        if (!Number.isFinite(n))
+            return undefined;
+        this.noteParamUse(opKey, id);
+        return n;
+    }
+    /** 명세 모수(기간) — ISO 8601 문자열을 밀리초로. 선언 없으면 undefined. */
+    paramDuration(opKey, id) {
+        const p = this.operationSpecs.get(opKey)?.parameters?.find(x => x.id === id);
+        const ms = parseIsoDuration(p?.value);
+        if (ms !== undefined)
+            this.noteParamUse(opKey, id);
+        return ms;
+    }
+    noteSpecUse(kind, duration, variability) {
+        const cur = this.specUse.get(kind);
+        if (cur) {
+            cur.duration = duration;
+            if (variability)
+                cur.variability = variability;
+            return;
+        }
+        this.specUse.set(kind, { duration, ...(variability ? { variability } : {}), params: new Set() });
+    }
+    noteParamUse(kind, id) {
+        const cur = this.specUse.get(kind);
+        if (cur)
+            cur.params.add(id);
+        else
+            this.specUse.set(kind, { duration: 'default', params: new Set([id]) });
+    }
+    /**
+     * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 박아 둔 상수인가.**
+     *
+     * 시뮬레이션 결과를 받는 쪽이 이걸 봐야 한다: 소요시간이 전부 기본값이면 그 예측으로 말할 수 있는 것은
+     * "같은 조건에서의 상대 비교" 뿐이고 "몇 시에 끝난다" 는 근거가 없다. 그 구분을 숫자로 드러낸다.
+     */
+    specCoverage() {
+        const operations = [...this.specUse.entries()].map(([kind, u]) => {
+            const spec = this.operationSpecs.get(kind);
+            /* 실측 분포를 쓴 경우가 우선 — 선언 명세의 변동보다 실제로 굴린 것이 사실이다. */
+            const variability = u.variability ?? spec?.variability?.distribution;
+            return {
+                kind,
+                duration: u.duration,
+                ...(variability ? { variability } : {}),
+                parameters: [...u.params].sort()
+            };
+        });
+        return {
+            operations,
+            measuredDurations: operations.filter(o => o.duration === 'measured').length,
+            declaredDurations: operations.filter(o => o.duration === 'declared').length,
+            defaultDurations: operations.filter(o => o.duration === 'default').length
+        };
     }
     /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
     pickGtin(mix) {
@@ -534,13 +773,244 @@ export class FlowEngine {
         for (const h of this.handlers)
             h(e);
     }
-    emitTask(t) { this.emitOp(OP_EVENT.task, { taskId: t.id, orderId: t.orderId, kind: t.kind, status: t.status, fromNode: t.fromNode, toNode: t.toNode, itemRefs: [t.itemEpc], resourceRef: t.resource ?? undefined }); }
+    /**
+     * 작업 전이 방출 — **커널이 아는 것을 미러도 알게** 한다.
+     *
+     * 예전에는 진척·남은 시간·의도를 싣지 않아, 미러 상태를 씨앗으로 한 예측이 "진행 중인 일이 없는
+     * 현장" 에서 출발했고, 소비처는 무자원 체류를 기록 누락으로 오해할 수밖에 없었다.
+     * 진척은 진행 중일 때만 뜻이 있으므로 그때만 싣는다(생성·완료 시점의 0/1 은 노이즈).
+     */
+    emitTask(t) {
+        const inProgress = t.status === 'in-progress';
+        const done = Math.max(0, (t.durationMs ?? 0) - (t.remainingMs ?? 0));
+        this.emitOp(OP_EVENT.task, {
+            taskId: t.id, orderId: t.orderId, kind: t.kind, status: t.status,
+            fromNode: t.fromNode, toNode: t.toNode, itemRefs: [t.itemEpc], resourceRef: t.resource ?? undefined,
+            intent: t.intent,
+            ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
+            ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
+            ...(t.durationMs ? { durationMs: t.durationMs } : {}),
+            ...(inProgress ? { remainingMs: t.remainingMs, progress: t.durationMs ? done / t.durationMs : undefined } : {})
+        });
+    }
+    /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
+    emitAsset(a) {
+        this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClass: a.assetClass, status: a.status, location: a.location, taskId: a.taskId ?? undefined, carrying: a.carrying });
+    }
+    emitPerson(p) {
+        this.emitOp(OP_EVENT.person, { personId: p.id, personnelClass: p.personnelClass, status: p.status, taskId: p.taskId ?? undefined, ...(this.personOffShift(p) ? { offShift: true } : {}) });
+    }
     emitMover(m, motion) { this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, motion }); }
     emitOrder(o) { this.emitOp(OP_EVENT.order, { orderId: o.id, kind: o.kind, status: o.status, requested: o.requested, fulfilled: o.fulfilled, held: o.held }); }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────
+    /**
+     * 자극 간격 — **계약이 선언한 네 분포를 실제로 판정한다.**
+     *
+     * 예전에는 `poisson` 만 구현하고 나머지는 전부 상수로 떨어졌다. 계약이 `uniform`·`profile` 을
+     * 선언하고 있었으므로, 그것을 지정한 사람은 자기가 요청한 분포로 도는 줄 알았다 — **조용한 거짓**이다.
+     *
+     *  constant  간격이 일정(평균 그대로)
+     *  poisson   무기억 도착(지수 간격) — 평균 유지
+     *  uniform   0..2×평균 균등 — 평균을 유지하면서 흔들린다(교과서적 U(0,2μ))
+     *  profile   시간대별 배율(`profile[시]`)로 도착률을 조절 — 하루 안의 수요 곡선
+     */
     intervalMs(spec) {
-        const base = 3_600_000 / spec.rate.meanPerHour;
-        return spec.rate.distribution === 'poisson' ? -Math.log(1 - this.rng()) * base : base;
+        const perHour = spec.rate.meanPerHour * this.profileFactor(spec.rate);
+        if (!(perHour > 0))
+            return Number.POSITIVE_INFINITY; // 그 시간대엔 도착이 없다(0 을 1/0=∞ 로 정직하게)
+        const base = 3_600_000 / perHour;
+        switch (spec.rate.distribution) {
+            case 'poisson':
+                return -Math.log(1 - this.rng()) * base;
+            case 'uniform':
+                return this.rng() * 2 * base;
+            case 'profile':
+            case 'constant':
+            default:
+                return base;
+        }
+    }
+    /**
+     * 시간대 배율 — `profile[시]`. `profile` 분포일 때만 적용하며, 배열이 짧으면 **순환**한다
+     * (24개면 하루, 8개면 8시간 주기). 미지정·다른 분포면 1(무영향).
+     * 시(hour)는 **시뮬 시각 자신의 프레임**(BASE_EPOCH 기준 UTC)이다 — 계약에 표준시가 없으므로
+     * 현지 시간대 해석은 아직 하지 않는다(꾸미지 않는다).
+     */
+    /**
+     * 다음 발화 시각 — **발화가 없는 시간대를 영원한 침묵으로 만들지 않는다.**
+     *
+     * 배율 0(그 시간대 도착 없음)이면 간격이 무한이 된다. 그것을 그대로 예약하면 이후 어떤 시간대가
+     * 와도 깨어나지 않는다 — 그래서 **다음 정시로 미뤄 다시 판정**한다(시간대가 바뀌면 배율도 바뀐다).
+     * 시나리오 시작과 구동 루프가 같은 규칙을 쓰도록 한 곳에 둔다(예전에는 시작 경로만 따로였다).
+     */
+    nextFireMs(spec, from) {
+        const interval = this.intervalMs(spec);
+        if (Number.isFinite(interval))
+            return from + interval;
+        const hourMs = 3_600_000;
+        return Math.floor(from / hourMs) * hourMs + hourMs; // 다음 정시에 재판정
+    }
+    profileFactor(rate) {
+        if (rate.distribution !== 'profile')
+            return 1;
+        const p = rate.profile;
+        if (!p?.length)
+            return 1;
+        const f = p[this.hourOfDay() % p.length];
+        return Number.isFinite(f) && f >= 0 ? f : 1;
+    }
+    /**
+     * 필요 물리 자산을 확보한다 — 인원과 **같은 규칙**(등급으로 요구, 부분 투입 없음, 확정은 나중).
+     * 자산은 사람과 달리 교대가 없고 **자리**가 있다(빈 팔레트가 어디 있는지가 다음 문제이지만,
+     * 지금은 자리를 따지지 않는다 — 따지려면 자산 이송 작업이 먼저 있어야 한다).
+     */
+    claimAssets(t) {
+        const need = this.operationSpecs.get(t.kind)?.physicalAssetSpecification;
+        if (!need?.length)
+            return [];
+        const picked = [];
+        for (const req of need) {
+            const want = Math.max(0, Math.floor(req.quantity ?? 0));
+            if (!want)
+                continue;
+            const avail = [...this.assets.values()].filter(a => a.status === 'idle' && !picked.includes(a.id) && (req.assetClass === undefined || a.assetClass === req.assetClass));
+            if (avail.length < want)
+                return null;
+            for (let i = 0; i < want; i++)
+                picked.push(avail[i].id);
+        }
+        return picked;
+    }
+    /** 확보한 자산을 작업에 묶는다 — 싣는 물류단위(SSCC)가 있으면 연결한다(GRAI ↔ SSCC). */
+    assignAssets(t, gear) {
+        if (!gear.length)
+            return;
+        t.assets = gear;
+        for (const id of gear) {
+            const a = this.assets.get(id);
+            if (!a)
+                continue;
+            a.status = 'in-use';
+            a.taskId = t.id;
+            if (t.itemEpc)
+                a.carrying = t.itemEpc;
+            this.emitAsset(a);
+        }
+    }
+    /**
+     * 작업이 끝나면 자산을 놓아 준다 — **사람과 다른 점: 자산은 도착 자리에 남는다**(물건이므로).
+     * 싣고 있던 것은 놓는다(빈 팔레트로 돌아간다 — 회수·재사용의 출발점).
+     */
+    releaseAssets(t) {
+        for (const id of t.assets ?? []) {
+            const a = this.assets.get(id);
+            if (!a)
+                continue;
+            a.status = 'idle';
+            a.taskId = null;
+            a.location = t.toNode || a.location;
+            a.carrying = undefined;
+            this.emitAsset(a);
+        }
+    }
+    /**
+     * 필요 인원을 확보한다 — **등급으로 요구하고 등급으로 고른다**(특정인 지목이 아니다).
+     * 요구가 없으면 빈 배열, 모자라면 `null`(작업은 기다린다 — **부분 투입으로 시작하지 않는다**).
+     * 여기서는 고르기만 하고 잡지 않는다: 설비까지 확보된 뒤 `assignCrew` 가 확정한다
+     * (반쯤 잡고 실패하면 사람이 아무 일도 못 하면서 묶인다).
+     */
+    claimPersonnel(t) {
+        const need = this.operationSpecs.get(t.kind)?.personnelSpecification;
+        if (!need?.length)
+            return [];
+        const picked = [];
+        for (const req of need) {
+            const want = Math.max(0, Math.floor(req.quantity ?? 0));
+            if (!want)
+                continue;
+            const avail = [...this.persons.values()].filter(p => p.status === 'idle' &&
+                !picked.includes(p.id) &&
+                !this.personOffShift(p) &&
+                (req.personnelClass === undefined || p.personnelClass === req.personnelClass));
+            if (avail.length < want)
+                return null; // 한 등급이라도 모자라면 시작하지 않는다
+            for (let i = 0; i < want; i++)
+                picked.push(avail[i].id);
+        }
+        return picked;
+    }
+    /** 확보한 사람을 작업에 묶는다(설비까지 확정된 뒤). */
+    assignCrew(t, crew) {
+        if (!crew.length)
+            return;
+        t.personnel = crew;
+        for (const id of crew) {
+            const p = this.persons.get(id);
+            if (!p)
+                continue;
+            p.status = 'busy';
+            p.taskId = t.id;
+            this.emitPerson(p);
+        }
+    }
+    /** 작업이 끝나면 사람을 놓아 준다 — 설비 해제와 별개 경로. */
+    releaseCrew(t) {
+        for (const id of t.personnel ?? []) {
+            const p = this.persons.get(id);
+            if (!p)
+                continue;
+            p.status = 'idle';
+            p.taskId = null;
+            this.emitPerson(p);
+        }
+    }
+    /** 사람의 교대 판정 — 자원(offShift)과 같은 규칙. */
+    personOffShift(p) {
+        const w = p.window;
+        if (!w)
+            return false;
+        const h = this.hourOfDay();
+        return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
+    }
+    /**
+     * 이 자리가 동시 처리 한도에 찼는가 — `parallelism` 을 선언한 자리만 판정한다(미선언=제약 없음).
+     * 세는 대상은 **그 자리에서 진행 중인 작업**(`toNode` 기준, in-progress). 대기 중인 작업은 세지 않는다.
+     */
+    stationFull(nodeId) {
+        if (!nodeId)
+            return false;
+        const limit = this.nodes.get(nodeId)?.parallelism;
+        if (!(typeof limit === 'number' && limit > 0))
+            return false;
+        let running = 0;
+        for (const t of this.tasks.values())
+            if (t.status === 'in-progress' && t.toNode === nodeId)
+                running++;
+        return running >= limit;
+    }
+    /** 교대 밖인가 — 자원이 지금 일하지 않는 이유 중 고장·계획정지와 구별되는 세 번째. */
+    offShift(m) {
+        const w = m.window;
+        if (!w)
+            return false;
+        const h = this.hourOfDay();
+        return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
+    }
+    /** 시뮬 시각의 시(0..23) — 운영시간·시간대 배율의 기준. */
+    hourOfDay() {
+        return new Date(BASE_EPOCH + this.clockMs).getUTCHours();
+    }
+    /**
+     * 운영시간 안인가 — `window {startHour, endHour}`. **선언만 되고 소비처가 없던 필드**를 판정한다.
+     * `startHour <= endHour` 면 같은 날 구간, 넘어가면 자정을 가로지르는 구간(야간 교대: 22→6).
+     * 미지정이면 언제나 참(24시간 가동).
+     */
+    inWindow(spec) {
+        const w = spec.window;
+        if (!w)
+            return true;
+        const h = this.hourOfDay();
+        return w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour;
     }
     /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
     sampleExp(meanMs) { return -Math.log(1 - this.rng()) * meanMs; }
@@ -582,6 +1052,18 @@ export class FlowEngine {
     generate() {
         for (const g of this.gens) {
             while (this.clockMs >= g.nextMs) {
+                const next = this.nextFireMs(g.spec, g.nextMs);
+                /* 배율 0(도착 없는 시간대) — 발화하지 않고 다음 정시에 다시 판정한다. */
+                if (this.intervalMs(g.spec) === Number.POSITIVE_INFINITY) {
+                    g.nextMs = next;
+                    continue;
+                }
+                /* 운영시간 밖이면 **자극을 만들지 않고 다음 슬롯으로 넘긴다** — 문을 닫은 시간에 트럭이 오지
+                 * 않는다. 예전에는 window 를 아무도 보지 않아 24시간 가동으로만 굴렀다. */
+                if (!this.inWindow(g.spec)) {
+                    g.nextMs = next;
+                    continue;
+                }
                 // 자극 클래스(공급/수요)로 hook 분기 — 도메인 kind 라벨이 아니라 stimulus 로 라우팅(무방언).
                 // stimulus 미지정 시 레거시 kind 로 추론(하위호환). 도메인은 kind 를 자유 명명하고 stimulus 로 분류.
                 const stimulus = g.spec.stimulus ?? (g.spec.kind === 'outbound-order' ? 'order' : 'arrival');
@@ -589,7 +1071,7 @@ export class FlowEngine {
                     this.onOrder(g.spec);
                 else
                     this.onArrival(g.spec);
-                g.nextMs += this.intervalMs(g.spec);
+                g.nextMs = next;
             }
         }
     }
@@ -603,14 +1085,29 @@ export class FlowEngine {
         for (const t of this.tasks.values()) {
             if (t.status !== 'created')
                 continue;
-            if (t.intent === 'dwell') { // 무자원 체류 — 자원 배정 없이 즉시 진행
+            /* 필요 인원 — 오퍼레이션 명세가 요구하면 등급별로 사람을 잡는다. 모자라면 **기다린다**
+             * (설비가 놀아도 사람이 없으면 일이 안 된다 — 그 줄이 현장의 실제 병목인 경우가 많다). */
+            const crew = this.claimPersonnel(t);
+            if (crew === null)
+                continue; // 인원 부족 → 다음 작업(다른 등급은 가능할 수 있다)
+            /* 필요 물리 자산 — 빈 팔레트가 없으면 출고가 못 나간다. 인원과 같은 규칙(부분 투입 없음). */
+            const gear = this.claimAssets(t);
+            if (gear === null)
+                continue;
+            if (t.intent === 'dwell') { // 무설비 체류 — 설비 배정 없이 진행(인원 요구가 있으면 위에서 확보됨)
                 t.status = 'in-progress';
                 t.remainingMs = t.durationMs;
+                this.assignCrew(t, crew);
+                this.assignAssets(t, gear);
                 this.emitTask(t);
                 continue;
             }
-            // resourceType 있으면 그 kind 무버만; 없으면 아무 유휴 무버.
-            const mover = [...this.movers.values()].find(m => m.status === 'idle' && !m.held && (t.resourceType === undefined || m.kind === t.resourceType));
+            /* 자리의 동시 처리 수를 넘지 않는다 — 자원이 남아도 스테이션이 한 대씩만 깎으면 줄을 선다.
+             * 이 제약이 없으면 대기가 생기지 않아 병목이 사라지고 예측이 낙관 쪽으로 치우친다. */
+            if (this.stationFull(t.toNode))
+                continue;
+            // resourceType 있으면 그 kind 무버만; 없으면 아무 유휴 무버. 교대 밖 자원은 배정하지 않는다.
+            const mover = [...this.movers.values()].find(m => m.status === 'idle' && !m.held && !this.offShift(m) && (t.resourceType === undefined || m.kind === t.resourceType));
             if (!mover)
                 continue; // 맞는 유휴 자원 없음 → 다음 task(break 아님: 다른 타입은 가용할 수 있음)
             // 체인지오버: task 의 changeoverKey 가 무버 직전 키와 다르면 셋업 부착(첫 작업은 셋업 없음).
@@ -625,6 +1122,8 @@ export class FlowEngine {
             t.status = 'in-progress';
             t.resource = mover.id;
             t.remainingMs = t.durationMs;
+            this.assignCrew(t, crew);
+            this.assignAssets(t, gear);
             this.emitTask(t);
             // process: 제자리 변환(모션 없음). transport: 이동 모션 방출.
             if (t.intent === 'process')
@@ -643,6 +1142,8 @@ export class FlowEngine {
                 continue;
             this.onTaskComplete(t);
             t.status = 'completed';
+            this.releaseCrew(t); // 사람은 설비와 별개로 해제한다(dwell 도 사람은 잡고 있었을 수 있다)
+            this.releaseAssets(t); // 자산도 같다 — 자산은 도착 자리에 남는다(사람과 달리 물건이므로)
             if (!t.resource) {
                 this.emitTask(t);
                 continue;