@operato/twin-kernel 0.0.1

package/dist/flow-engine.d.ts

@@ -0,0 +1,224 @@
+import type { BoardDef, Command, CommandAck, EventHandler, MoverMotion, GeneratorSpec, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe } 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';
+export interface FlowNode {
+    id: string;
+    type: string;
+    capacity: number;
+    occupancy: number;
+    status: string;
+}
+export interface FlowItem {
+    epc: string;
+    location: string;
+    disposition: string;
+    gtin?: string;
+    qty?: number;
+    expiry?: number;
+}
+export interface FlowMover {
+    id: string;
+    kind: string;
+    location: string;
+    status: string;
+    taskId: string | null;
+    runMs: number;
+    setupMs: number;
+    downMs: number;
+    goodCount: number;
+    scrapCount: number;
+    lastChangeoverKey?: string;
+    mtbfMs?: number;
+    mttrMs?: number;
+    nextFailureMs?: number;
+    repairUntilMs?: number;
+}
+export interface FlowTask {
+    id: string;
+    kind: string;
+    status: 'created' | 'in-progress' | 'completed';
+    itemEpc: string;
+    fromNode: string;
+    toNode: string;
+    resource: string | null;
+    remainingMs: number;
+    durationMs: number;
+    orderId?: string;
+    resourceType?: string;
+    setupMs?: number;
+    changeoverKey?: string;
+    appliedSetupMs?: number;
+    /**
+     * 작업 의도(씬 3 직교의도 정렬 · ISA-95 이동 vs 변환). 기본 'transport'.
+     *   transport: mover 가 item 을 fromNode→toNode 운반(완료 시 자원 위치 이동 + 이동 모션).
+     *   process:   노드에서 item 변환(자원=정지 설비 — 위치 불변, 모션 없음). 가공을 거리-0 운반으로 위장 안 함.
+     *   dwell:     노드에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
+     */
+    intent?: 'transport' | 'process' | 'dwell';
+}
+/** 오더 라인(멀티SKU) — 라인별 품목·잔량. 단일 SKU 오더 = 1 라인. */
+export interface OrderLine {
+    gtin: string;
+    requested: number;
+}
+export interface FlowOrder {
+    id: string;
+    kind: string;
+    status: string;
+    requested: number;
+    fulfilled: number;
+    bizTransaction: string;
+    allocated: string[];
+    picked: string[];
+    gtin?: string;
+    shipmentEpc?: string | null;
+    lines?: OrderLine[];
+    held?: boolean;
+    dockDoor?: string;
+    windowStartMs?: number;
+}
+interface Rng {
+    (): number;
+    state: number;
+}
+export declare abstract class FlowEngine implements TwinKernel {
+    tenantId: string;
+    nodes: Map<string, FlowNode>;
+    items: Map<string, FlowItem>;
+    movers: Map<string, FlowMover>;
+    tasks: Map<string, FlowTask>;
+    orders: Map<string, FlowOrder>;
+    revision: number;
+    clockMs: number;
+    protected rng: Rng;
+    protected policy: AllocationPolicy;
+    /** duration 시임(선택) — 미주입 시 도메인 상수. 씬/보드 바인딩이 거리·속도 기반 estimator 주입. */
+    durationEstimator?: DurationEstimator;
+    protected epcSeq: number;
+    protected taskSeq: number;
+    protected orderSeq: number;
+    protected soSeq: number;
+    private handlers;
+    private gens;
+    private generating;
+    private speed;
+    private eventSeq;
+    constructor(tenantId: string, policy: AllocationPolicy);
+    /** 입고/도착 자극 — 아이템 생성 + EPCIS 방출 + 반입 태스크 생성. */
+    protected abstract onArrival(spec: GeneratorSpec): void;
+    /** 출고/출차 오더 자극 — 오더 생성. */
+    protected abstract onOrder(spec: GeneratorSpec): void;
+    /** created 오더 할당 — 재고 선택 + 태스크 생성(정책 위임). */
+    protected abstract allocate(order: FlowOrder): void;
+    /**
+     * 태스크 완료 시 도메인 상태 효과 전부 — occupancy·location·아이템 변환·EPCIS 방출·오더 이행.
+     * base 는 task 생명주기(진행·완료·자원해제·델타)만 소유하고 "완료가 무엇을 의미하는지"는 도메인에.
+     * 이동(WMS/YMS: from→to 이동) 이든 변환(MES: 소비→생산) 이든 여기서 결정 → base 가 이동-중립.
+     */
+    protected abstract onTaskComplete(task: FlowTask): void;
+    loadBoard(def: BoardDef): void;
+    onEvent(handler: EventHandler): Unsubscribe;
+    /**
+     * Command 채널 — 트윈의 "행위(act)" 면. 코어 공통 커맨드(order.hold/resume)는 여기서,
+     * 도메인 커맨드(order.release 등)는 handleCommand 로 위임. 커맨드는 sim 상태를 변이하고
+     * State 델타를 유발한다(command → 행위 → 관측 폐루프).
+     */
+    dispatch(cmd: Command): CommandAck;
+    /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
+    protected handleCommand(cmd: Command): CommandAck;
+    readonly scenario: ScenarioControl;
+    tick(dtMs: number): void;
+    getSnapshot(): StateSnapshot;
+    /**
+     * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
+     * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 굴려 forecast·발산(predicted vs actual) 검사에 쓴다.
+     * fork 는 자기 구독자·시나리오를 갖고 원본과 격리(handlers·gens 비움, generating=false).
+     * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
+     */
+    fork(tenantId?: string): this;
+    protected now(): string;
+    protected randInt(min: number, max: number): number;
+    /** task 소요 산출 — estimator 주입 시 그 값, 미주입/undefined 시 도메인 상수(fallback). "얼마"만 소비, "경로"는 씬. */
+    protected durationOf(ctx: DurationContext, fallbackMs: number): number;
+    /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
+    protected pickGtin(mix: {
+        gtin: string;
+        weight: number;
+    }[]): string;
+    protected nodeByType(type: string): FlowNode | undefined;
+    /**
+     * process 변화 대수(EPCIS TransformationEvent · ISA-95 Material Consumed/Produced · 씬 Processable.transform).
+     * inputs 소비 → outputs 생산. 입출력 arity 가 곧 대수:
+     *   merge N→1(조립) · split 1→N(분해) · transform 1→1(타입변경) · loss N→0(소실) · gain 0→N(부산물·생성).
+     * 아이템 상태(소비/생산)와 노드 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
+     * 도메인은 이 원시만 호출 — onTaskComplete 의 소비/생산/EPCIS 손코딩을 대체.
+     */
+    protected transform(inputs: string[], outputs: {
+        epc: string;
+        gtin?: string;
+        qty?: number;
+        location: string;
+        disposition: string;
+    }[], opts: {
+        bizStep: string;
+        disposition?: string;
+        transformationId?: string;
+        readPoint: string;
+        bizLocation?: string;
+        bizTransactionList?: BizTransactionElement[];
+    }): void;
+    /**
+     * containment 조립(EPCIS AggregationEvent ADD) — 자식들을 부모(용기)로 집約.
+     * consume 지정 시 자식이 컨테이너로 흡수되며 독립 아이템에서 이탈(dematerialize: ObjectEvent DELETE + 제거).
+     * 미지정 시 이벤트만(자식은 독립 아이템 유지 — 예: WMS 패킹, 적재된 채 도착).
+     */
+    protected aggregate(parent: string, children: string[], opts: {
+        bizStep: string;
+        readPoint: string;
+        bizLocation?: string;
+        disposition?: string;
+        consume?: {
+            readPoint: string;
+            disposition: string;
+        };
+    }): void;
+    /**
+     * containment 분해(EPCIS AggregationEvent DELETE) — 부모(용기)에서 자식들을 풀어냄.
+     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 노드 배치 + occupancy + ObjectEvent ADD).
+     * 미지정 시 이벤트만.
+     */
+    protected disaggregate(parent: string, children: string[], opts: {
+        bizStep: string;
+        readPoint: string;
+        materialize?: {
+            location: string;
+            disposition: string;
+        };
+    }): void;
+    /** 품질 보고(OEE Quality) — 도메인이 완료 시 자원별 양품/불량 1건 계상(예: 용접 수율). */
+    protected recordOutput(moverId: string | null, good: boolean): void;
+    /** 무버 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
+    private oeeOf;
+    /** 정책에 넘길 특정 타입 노드의 관측 뷰 — 예약(그 노드로 향하는 in-flight task) 포함. */
+    protected slotViews(nodeType: string): SlotView[];
+    protected emit(event: EpcisEvent): void;
+    protected emitOp(eventType: string, data: unknown): void;
+    protected emitTask(t: FlowTask): void;
+    protected emitMover(m: FlowMover, motion?: MoverMotion): void;
+    protected emitOrder(o: FlowOrder): void;
+    private intervalMs;
+    /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
+    private sampleExp;
+    /**
+     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 무버만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
+     * up: nextFailure 도래 시 down(수리까지 repairUntil). down: downMs 누적, repair 도래 시 up(다음 고장 예약).
+     * down 중 무버는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
+     */
+    private processFailures;
+    protected progressOf(t: FlowTask): number;
+    private generate;
+    private processOrders;
+    private processTasks;
+}
+export {};

package/dist/flow-engine.js

@@ -0,0 +1,422 @@
+/*
+ * FlowEngine — 도메인-일반 flow 엔진 base (WMS·YMS 공유 mechanics 추출).
+ *
+ * WMS/YMS 커널의 mechanics(RNG·clock·scenario·tick 루프·무버 배정·태스크 진행·emit·snapshot·
+ * slotViews)는 동일했다 → 이 base 로 승격. 도메인 kernel 은 **flow 동사만** 구현:
+ *   onArrival(자극:입고 도착) · onOrder(자극:출고 오더) · allocate(오더→태스크) · onTaskComplete(태스크 완료)
+ *
+ * TwinKernel 구현 → StateProjector·TwinRuntime 가 도메인 무관하게 소비.
+ * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
+ * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowNode 단일 base 방향과 정합.)
+ */
+import { OP_EVENT, CMD } from "./contract.js";
+import { transformationEvent, aggregationEvent, objectEvent } from "./epcis.js";
+const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z');
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    const fn = (() => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    });
+    Object.defineProperty(fn, 'state', { get: () => a, set: (v) => { a = v >>> 0; } });
+    return fn;
+}
+export class FlowEngine {
+    tenantId;
+    nodes = new Map();
+    items = new Map();
+    movers = new Map();
+    tasks = new Map();
+    orders = new Map();
+    revision = 0;
+    clockMs = 0;
+    rng = mulberry32(1);
+    policy;
+    /** duration 시임(선택) — 미주입 시 도메인 상수. 씬/보드 바인딩이 거리·속도 기반 estimator 주입. */
+    durationEstimator;
+    epcSeq = 0;
+    taskSeq = 0;
+    orderSeq = 0;
+    soSeq = 0;
+    handlers = [];
+    gens = [];
+    generating = false;
+    speed = 1;
+    eventSeq = 0;
+    constructor(tenantId, policy) {
+        this.tenantId = tenantId;
+        this.policy = policy;
+    }
+    // ── 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' });
+        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 };
+            if (m.mtbfMs !== undefined) {
+                mover.mtbfMs = m.mtbfMs;
+                mover.mttrMs = m.mttrMs;
+                mover.nextFailureMs = this.sampleExp(m.mtbfMs);
+            }
+            this.movers.set(m.id, mover);
+        }
+    }
+    onEvent(handler) {
+        this.handlers.push(handler);
+        return () => { const i = this.handlers.indexOf(handler); if (i >= 0)
+            this.handlers.splice(i, 1); };
+    }
+    /**
+     * Command 채널 — 트윈의 "행위(act)" 면. 코어 공통 커맨드(order.hold/resume)는 여기서,
+     * 도메인 커맨드(order.release 등)는 handleCommand 로 위임. 커맨드는 sim 상태를 변이하고
+     * State 델타를 유발한다(command → 행위 → 관측 폐루프).
+     */
+    dispatch(cmd) {
+        const ok = () => ({ commandId: cmd.commandId, accepted: true });
+        const fail = (error) => ({ commandId: cmd.commandId, accepted: false, error });
+        switch (cmd.type) {
+            case CMD.orderHold:
+            case CMD.orderResume: {
+                const orderId = cmd.args?.orderId;
+                const order = orderId ? this.orders.get(orderId) : undefined;
+                if (!order)
+                    return fail(`order 없음: ${orderId}`);
+                order.held = cmd.type === CMD.orderHold;
+                this.emitOrder(order);
+                return ok();
+            }
+            default:
+                return this.handleCommand(cmd);
+        }
+    }
+    /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
+    handleCommand(cmd) {
+        return { commandId: cmd.commandId, accepted: false, error: `알 수 없는 커맨드: ${cmd.type}` };
+    }
+    scenario = {
+        load: (def) => {
+            this.rng = mulberry32((def.seed ?? 1) >>> 0);
+            this.speed = def.speed ?? 1;
+            this.gens = def.generators.map(spec => ({ spec, nextMs: 0 }));
+        },
+        start: () => {
+            if (this.generating)
+                return;
+            this.generating = true;
+            for (const g of this.gens)
+                g.nextMs = this.clockMs + this.intervalMs(g.spec);
+        },
+        pause: () => { this.generating = false; },
+        reset: () => { this.generating = false; this.gens = []; },
+        setSpeed: (f) => { this.speed = f; }
+    };
+    tick(dtMs) {
+        const dt = dtMs * this.speed;
+        this.clockMs += dt;
+        if (this.generating)
+            this.generate();
+        this.processFailures(dt);
+        this.processOrders();
+        this.processTasks(dt);
+    }
+    getSnapshot() {
+        return {
+            revision: this.revision,
+            simClockMs: this.clockMs,
+            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) };
+                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, progress: t.status === 'in-progress' ? this.progressOf(t) : undefined })),
+            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 }))
+        };
+    }
+    /**
+     * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
+     * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 굴려 forecast·발산(predicted vs actual) 검사에 쓴다.
+     * fork 는 자기 구독자·시나리오를 갖고 원본과 격리(handlers·gens 비움, generating=false).
+     * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
+     */
+    fork(tenantId = this.tenantId) {
+        const Ctor = this.constructor;
+        const clone = new Ctor(tenantId, this.policy);
+        // 상태·시나리오(gens/generating)·시퀀스 전부 복제 → 원본의 완전한 continuation.
+        // 구독자(handlers)만 격리(fork 는 자기 구독자), scenario 객체는 clone 에 바인딩된 것 유지.
+        const skip = new Set(['policy', 'scenario', 'tenantId', 'handlers', 'durationEstimator']);
+        for (const key of Object.keys(this)) {
+            if (skip.has(key))
+                continue;
+            const v = this[key];
+            if (typeof v === 'function')
+                continue // rng — 아래서 state 만 복제
+                ;
+            clone[key] =
+                v instanceof Map ? new Map([...v.entries()].map(([k, o]) => [k, structuredClone(o)])) : structuredClone(v);
+        }
+        clone.rng.state = this.rng.state; // RNG 연속성 → 생성 포함 결정적 분기
+        clone.durationEstimator = this.durationEstimator; // 무상태 시임 — 참조 공유(policy 와 동형)
+        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). "얼마"만 소비, "경로"는 씬. */
+    durationOf(ctx, fallbackMs) {
+        return this.durationEstimator?.estimate(ctx) ?? fallbackMs;
+    }
+    /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
+    pickGtin(mix) {
+        const total = mix.reduce((s, m) => s + m.weight, 0);
+        let r = this.rng() * total;
+        for (const m of mix) {
+            r -= m.weight;
+            if (r <= 0)
+                return m.gtin;
+        }
+        return mix[mix.length - 1].gtin;
+    }
+    nodeByType(type) {
+        for (const n of this.nodes.values())
+            if (n.type === type)
+                return n;
+        return undefined;
+    }
+    /**
+     * process 변화 대수(EPCIS TransformationEvent · ISA-95 Material Consumed/Produced · 씬 Processable.transform).
+     * inputs 소비 → outputs 생산. 입출력 arity 가 곧 대수:
+     *   merge N→1(조립) · split 1→N(분해) · transform 1→1(타입변경) · loss N→0(소실) · gain 0→N(부산물·생성).
+     * 아이템 상태(소비/생산)와 노드 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
+     * 도메인은 이 원시만 호출 — onTaskComplete 의 소비/생산/EPCIS 손코딩을 대체.
+     */
+    transform(inputs, outputs, opts) {
+        for (const epc of inputs) {
+            const it = this.items.get(epc);
+            if (!it)
+                continue;
+            const n = this.nodes.get(it.location);
+            if (n)
+                n.occupancy--;
+            this.items.delete(epc);
+        }
+        for (const o of outputs) {
+            this.items.set(o.epc, { epc: o.epc, gtin: o.gtin, qty: o.qty, location: o.location, disposition: o.disposition });
+            const n = this.nodes.get(o.location);
+            if (n)
+                n.occupancy++;
+        }
+        this.emit(transformationEvent({
+            eventTime: this.now(), bizStep: opts.bizStep, disposition: opts.disposition,
+            inputEPCList: inputs.length ? inputs.slice() : undefined,
+            outputEPCList: outputs.length ? outputs.map(o => o.epc) : undefined,
+            transformationID: opts.transformationId, readPoint: opts.readPoint, bizLocation: opts.bizLocation ?? opts.readPoint,
+            bizTransactionList: opts.bizTransactionList
+        }));
+    }
+    /**
+     * containment 조립(EPCIS AggregationEvent ADD) — 자식들을 부모(용기)로 집約.
+     * consume 지정 시 자식이 컨테이너로 흡수되며 독립 아이템에서 이탈(dematerialize: ObjectEvent DELETE + 제거).
+     * 미지정 시 이벤트만(자식은 독립 아이템 유지 — 예: WMS 패킹, 적재된 채 도착).
+     */
+    aggregate(parent, children, opts) {
+        this.emit(aggregationEvent({ eventTime: this.now(), action: 'ADD', bizStep: opts.bizStep, disposition: opts.disposition, parentID: parent, childEPCs: children.slice(), readPoint: opts.readPoint, bizLocation: opts.bizLocation }));
+        if (opts.consume) {
+            this.emit(objectEvent({ eventTime: this.now(), action: 'DELETE', bizStep: opts.bizStep, disposition: opts.consume.disposition, epcList: children.slice(), readPoint: opts.consume.readPoint }));
+            for (const c of children) {
+                const it = this.items.get(c);
+                if (it) {
+                    const n = this.nodes.get(it.location);
+                    if (n)
+                        n.occupancy--;
+                    this.items.delete(c);
+                }
+            }
+        }
+    }
+    /**
+     * containment 분해(EPCIS AggregationEvent DELETE) — 부모(용기)에서 자식들을 풀어냄.
+     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 노드 배치 + occupancy + ObjectEvent ADD).
+     * 미지정 시 이벤트만.
+     */
+    disaggregate(parent, children, opts) {
+        this.emit(aggregationEvent({ eventTime: this.now(), action: 'DELETE', bizStep: opts.bizStep, parentID: parent, childEPCs: children.slice(), readPoint: opts.readPoint }));
+        if (opts.materialize) {
+            const m = opts.materialize;
+            for (const c of children) {
+                this.items.set(c, { epc: c, location: m.location, disposition: m.disposition });
+                const n = this.nodes.get(m.location);
+                if (n)
+                    n.occupancy++;
+                this.emit(objectEvent({ eventTime: this.now(), action: 'ADD', bizStep: opts.bizStep, disposition: m.disposition, epcList: [c], readPoint: m.location, bizLocation: m.location }));
+            }
+        }
+    }
+    /** 품질 보고(OEE Quality) — 도메인이 완료 시 자원별 양품/불량 1건 계상(예: 용접 수율). */
+    recordOutput(moverId, good) {
+        const m = moverId ? this.movers.get(moverId) : undefined;
+        if (!m)
+            return;
+        if (good)
+            m.goodCount++;
+        else
+            m.scrapCount++;
+    }
+    /** 무버 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
+    oeeOf(m) {
+        const planned = this.clockMs;
+        const uptime = Math.max(0, planned - m.setupMs - m.downMs); // 가용시간(셋업·고장 제외)
+        const availability = planned > 0 ? uptime / planned : 1;
+        const performance = uptime > 0 ? Math.min(1, m.runMs / uptime) : (m.runMs > 0 ? 1 : 0);
+        const totalQ = m.goodCount + m.scrapCount;
+        const quality = totalQ > 0 ? m.goodCount / totalQ : 1;
+        return {
+            availability, performance, quality, overall: availability * performance * quality,
+            runMs: m.runMs, setupMs: m.setupMs, downMs: m.downMs, idleMs: Math.max(0, uptime - m.runMs), goodCount: m.goodCount, scrapCount: m.scrapCount
+        };
+    }
+    /** 정책에 넘길 특정 타입 노드의 관측 뷰 — 예약(그 노드로 향하는 in-flight task) 포함. */
+    slotViews(nodeType) {
+        const reserved = new Map();
+        for (const t of this.tasks.values())
+            if (t.status !== 'completed')
+                reserved.set(t.toNode, (reserved.get(t.toNode) ?? 0) + 1);
+        const views = [];
+        for (const n of this.nodes.values())
+            if (n.type === nodeType)
+                views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
+        return views;
+    }
+    emit(event) {
+        this.revision++;
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+        for (const h of this.handlers)
+            h(e);
+    }
+    emitOp(eventType, data) {
+        this.revision++;
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+        for (const h of this.handlers)
+            h(e);
+    }
+    emitTask(t) { this.emitOp(OP_EVENT.task, { taskId: t.id, kind: t.kind, status: t.status, fromNode: t.fromNode, toNode: t.toNode, itemRefs: [t.itemEpc], resourceRef: t.resource ?? undefined }); }
+    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 ─────────────────────────────────────────────────────────
+    intervalMs(spec) {
+        const base = 3_600_000 / spec.rate.meanPerHour;
+        return spec.rate.distribution === 'poisson' ? -Math.log(1 - this.rng()) * base : base;
+    }
+    /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
+    sampleExp(meanMs) { return -Math.log(1 - this.rng()) * meanMs; }
+    /**
+     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 무버만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
+     * up: nextFailure 도래 시 down(수리까지 repairUntil). down: downMs 누적, repair 도래 시 up(다음 고장 예약).
+     * down 중 무버는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
+     */
+    processFailures(dt) {
+        for (const m of this.movers.values()) {
+            if (m.mtbfMs === undefined)
+                continue;
+            if (m.status === 'down') {
+                m.downMs += dt;
+                if (this.clockMs >= (m.repairUntilMs ?? 0)) {
+                    m.status = m.taskId ? 'busy' : 'idle'; // 수리 완료 → 진행중 task 있으면 재개
+                    m.repairUntilMs = undefined;
+                    m.nextFailureMs = this.clockMs + this.sampleExp(m.mtbfMs);
+                    this.emitMover(m);
+                }
+            }
+            else if (this.clockMs >= (m.nextFailureMs ?? Infinity)) {
+                m.status = 'down'; // 고장 → 수리 대기
+                m.repairUntilMs = this.clockMs + this.sampleExp(m.mttrMs ?? m.mtbfMs);
+                m.nextFailureMs = undefined;
+                this.emitMover(m);
+            }
+        }
+    }
+    progressOf(t) { return t.durationMs <= 0 ? 1 : Math.min(1, Math.max(0, (t.durationMs - t.remainingMs) / t.durationMs)); }
+    generate() {
+        for (const g of this.gens) {
+            while (this.clockMs >= g.nextMs) {
+                if (g.spec.kind === 'inbound-arrival')
+                    this.onArrival(g.spec);
+                else if (g.spec.kind === 'outbound-order')
+                    this.onOrder(g.spec);
+                g.nextMs += this.intervalMs(g.spec);
+            }
+        }
+    }
+    processOrders() {
+        for (const o of this.orders.values())
+            if (o.status === 'created' && !o.held)
+                this.allocate(o);
+    }
+    processTasks(dt) {
+        // 1) created → in-progress. dwell(무자원)은 즉시 진행, transport/process 는 가용 자원 배정.
+        for (const t of this.tasks.values()) {
+            if (t.status !== 'created')
+                continue;
+            if (t.intent === 'dwell') { // 무자원 체류 — 자원 배정 없이 즉시 진행
+                t.status = 'in-progress';
+                t.remainingMs = t.durationMs;
+                this.emitTask(t);
+                continue;
+            }
+            // resourceType 있으면 그 kind 무버만; 없으면 아무 유휴 무버.
+            const mover = [...this.movers.values()].find(m => m.status === 'idle' && (t.resourceType === undefined || m.kind === t.resourceType));
+            if (!mover)
+                continue; // 맞는 유휴 자원 없음 → 다음 task(break 아님: 다른 타입은 가용할 수 있음)
+            // 체인지오버: task 의 changeoverKey 가 무버 직전 키와 다르면 셋업 부착(첫 작업은 셋업 없음).
+            if (t.setupMs && t.changeoverKey !== undefined && mover.lastChangeoverKey !== undefined && mover.lastChangeoverKey !== t.changeoverKey) {
+                t.appliedSetupMs = t.setupMs;
+                t.durationMs += t.setupMs; // 셋업을 가동 앞에 folded(무버 점유 = 셋업+사이클)
+            }
+            if (t.changeoverKey !== undefined)
+                mover.lastChangeoverKey = t.changeoverKey;
+            mover.status = 'busy';
+            mover.taskId = t.id;
+            t.status = 'in-progress';
+            t.resource = mover.id;
+            t.remainingMs = t.durationMs;
+            this.emitTask(t);
+            // process: 제자리 변환(모션 없음). transport: 이동 모션 방출.
+            if (t.intent === 'process')
+                this.emitMover(mover);
+            else
+                this.emitMover(mover, { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs, durationMs: t.durationMs, progress: 0, elapsedMs: 0 });
+        }
+        // 2) in-progress 진행/완료 — 상태 효과는 전부 도메인(onTaskComplete). base 는 자원 해제·델타만.
+        for (const t of this.tasks.values()) {
+            if (t.status !== 'in-progress')
+                continue;
+            if (t.resource && this.movers.get(t.resource)?.status === 'down')
+                continue; // 설비 고장 → 작업 동결
+            t.remainingMs -= dt;
+            if (t.remainingMs > 0)
+                continue;
+            this.onTaskComplete(t);
+            t.status = 'completed';
+            if (!t.resource) {
+                this.emitTask(t);
+                continue;
+            } // dwell(무자원) — 해제할 자원 없음
+            const mover = this.movers.get(t.resource);
+            // OEE 계측: 셋업/가동 누적(가동 = 총 duration − 셋업). onTaskComplete 가 recordOutput 로 품질 보고.
+            const setup = t.appliedSetupMs ?? 0;
+            mover.setupMs += setup;
+            mover.runMs += t.durationMs - setup;
+            mover.status = 'idle';
+            mover.taskId = null;
+            if (t.intent !== 'process')
+                mover.location = t.toNode; // 운반만 위치 이동; process 는 제자리
+            this.emitTask(t);
+            this.emitMover(mover);
+        }
+    }
+}

package/dist/forecast.d.ts

@@ -0,0 +1,29 @@
+import type { ScenarioControl, ScenarioDef, StateSnapshot } from './contract.ts';
+/** fork·시나리오 구동 가능한 트윈(FlowEngine 이 만족). */
+export interface ForecastTwin {
+    getSnapshot(): StateSnapshot;
+    tick(dtMs: number): void;
+    scenario: ScenarioControl;
+    fork(): ForecastTwin;
+}
+export interface MonteCarloResult {
+    runs: number;
+    samples: number[];
+    min: number;
+    max: number;
+    mean: number;
+    p50: number;
+    p90: number;
+}
+export interface MonteCarloOptions {
+    runs: number;
+    horizonMs: number;
+    scenario: ScenarioDef;
+    tickMs?: number;
+    metric: (s: StateSnapshot) => number;
+}
+/**
+ * 현재 상태에서 N개 확률적 미래를 표본화 → 지표 분포.
+ * run 마다 fork(현재 보존) + scenario.load(seed+i)(미래 변주) + horizon 까지 구동. 원본 무간섭.
+ */
+export declare function monteCarloForecast(twin: ForecastTwin, opts: MonteCarloOptions): MonteCarloResult;