@operato/twin-kernel 0.2.0 → 0.2.2

package/dist/flow-engine.js

@@ -9,8 +9,9 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowNode 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD } from "./contract.js";
-import { transformationEvent, aggregationEvent, objectEvent, DISP } from "./epcis.js";
+import { OP_EVENT, CMD, nodeStatusOf } from "./contract.js";
+import { ObservedReducer } from "./observed-reducer.js";
+import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR } from "./epcis.js";
 import { parseIsoDuration } from "./iso-duration.js";
 const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z');
 function mulberry32(seed) {
@@ -134,6 +135,13 @@ export class FlowEngine {
      * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
      */
     operationSpecs = new Map();
+    /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
+    observer;
+    /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
+    observedDirty = false;
+    observeMode = false;
+    /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
+    boardDef;
     /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
     specUse = new Map();
     epcSeq = 0;
@@ -141,6 +149,10 @@ export class FlowEngine {
     orderSeq = 0;
     soSeq = 0;
     handlers = [];
+    /** 구독자 접근(관측 재방출) — emit 과 같은 목록을 쓴다(두 경로가 갈리지 않게). */
+    handlersRef() {
+        return this.handlers;
+    }
     gens = [];
     generating = false;
     speed = 1;
@@ -151,6 +163,7 @@ export class FlowEngine {
     }
     // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
     loadBoard(def) {
+        this.boardDef = def;
         for (const n of def.nodes)
             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 ?? [])
@@ -199,9 +212,10 @@ export class FlowEngine {
         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, gtinKey: it.gtinKey, lot: it.lot, qty: it.qty ?? 1, uom: it.uom,
-                parent: it.parent, expiry: it.expiry, ilmd: it.ilmd
+                gtin: it.gtin, qty: it.qty ?? 1, uom: it.uom,
+                parent: it.parent, carriedBy: it.carriedBy, expiry: it.expiry, ilmd: it.ilmd
             });
         }
         for (const m of snap.movers) {
@@ -247,6 +261,7 @@ export class FlowEngine {
                 fromNode: t.fromNode ?? '', toNode: t.toNode ?? '',
                 resource: known && t.status === 'in-progress' ? (t.resourceRef ?? null) : null,
                 remainingMs: known ? t.remainingMs : (t.durationMs ?? 0),
+                startedAtSimMs: t.startedAtSimMs,
                 durationMs: t.durationMs ?? (known ? t.remainingMs : 0),
                 orderId: t.orderId,
                 intent: t.intent
@@ -273,7 +288,14 @@ export class FlowEngine {
                 }
             }
         }
-        for (const o of orders) {
+        /* 오더 원값은 이제 **스냅샷에 있다** — 따로 넘겨받은 것이 없으면 스냅샷에서 읽는다.
+         * (예전에는 상태가 progress 로 압축돼 호출부가 저널을 뒤져 원값을 넘겨야 했다.) */
+        const observedOrders = orders.length
+            ? orders
+            : (snap.orders ?? [])
+                .filter(o => o.requested !== undefined)
+                .map(o => ({ orderId: o.id, kind: o.kind, status: o.status, requested: o.requested, fulfilled: o.fulfilled ?? 0, held: o.held, lines: o.lines }));
+        for (const o of observedOrders) {
             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);
             if (remaining <= 0)
@@ -434,13 +456,21 @@ export class FlowEngine {
         this.processTasks(dt);
     }
     getSnapshot() {
+        this.settleObserved();
         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 })),
+            /* 출처 표시 — 보드(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
+             * 시뮬이 아무 표시도 안 하면 소비처가 두 스냅샷을 같은 규칙으로 읽지 못한다. */
+            nodes: [...this.nodes.values()].map(n => {
+                const { status, ...rest } = n;
+                /* 상태는 저장값이 아니라 포화도 파생 — 미러와 **같은 함수**를 쓴다(규칙이 둘이면 갈라진다). */
+                const derived = nodeStatusOf(n);
+                return { ...rest, ...(derived ? { status: derived } : {}), origin: 'master' };
+            }),
+            items: [...this.items.values()].map(i => this.itemState(i)),
             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, ...(this.offShift(m) ? { offShift: true } : {}) };
+                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, origin: 'master', ...(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 };
@@ -458,8 +488,26 @@ export class FlowEngine {
                     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 })),
+            /* 스냅샷이 **델타보다 가난하면 안 된다** — 예전에는 소요·남은 시간을 빼고 내보내서, 이 스냅샷으로
+             * 다른 커널을 심으면(hydrateObserved) 진행 중이던 작업을 이어 굴릴 수 없었다(미러 스냅샷은
+             * 델타에서 왔으므로 갖고 있었다 — 같은 계약을 두 구동이 다르게 채우던 자리). */
+            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,
+                ...(t.intent ? { intent: t.intent } : {}),
+                ...(t.durationMs ? { durationMs: t.durationMs } : {}),
+                ...(t.status === 'in-progress' ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: this.progressOf(t) } : {}),
+                ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
+                ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
+                ...(t.resources?.length ? { resources: t.resources.slice() } : {})
+            })),
+            orders: [...this.orders.values()].map(o => ({
+                id: o.id, kind: o.kind, status: o.status,
+                progress: o.requested ? o.fulfilled / o.requested : 0,
+                requested: o.requested, fulfilled: o.fulfilled,
+                ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {}),
+                held: o.held
+            })),
             attentions: this.computeAttentions()
         };
     }
@@ -485,6 +533,7 @@ export class FlowEngine {
      * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
      */
     fork(tenantId = this.tenantId) {
+        this.settleObserved(); // 관측으로 굴러온 커널을 fork 하려면 먼저 상태로 옮겨야 한다
         const Ctor = this.constructor;
         const clone = new Ctor(tenantId, this.policy);
         // 상태·시나리오(gens/generating)·시퀀스 전부 복제 → 원본의 완전한 continuation.
@@ -510,6 +559,54 @@ export class FlowEngine {
     // ── 보호 헬퍼 (도메인 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)); }
+    /**
+     * 관측 구동(P0 스파이크) — **이벤트로 커널을 굴린다.**
+     *
+     * 상태를 만드는 구동이 둘인데(시뮬 `tick` / 미러 `apply`) 지금은 **모델도 둘**이라 한쪽만 고치면
+     * 갈라진다(2026-08-01 하루에 아홉 곳). 근본 해법은 **한 상태 모델 두 구동**이고, 이것은 그 실현
+     * 가능성을 재는 스파이크다(design/plans/kernel-unification-live-observe.md P0).
+     *
+     * 여기서는 **이미 검증된 조각을 조립**한다: 투영기가 이벤트를 접고, 그 결과를 씨앗 경로
+     * (`hydrateObserved`)로 커널 상태에 심는다. 그래서 관측으로 굴린 커널을 그대로 `fork`·`tick` 할 수
+     * 있다 — "미러에서 예측한다" 가 별도 배관 없이 성립하는지가 이 스파이크의 질문이다.
+     *
+     * **비용은 정직하게**: 이벤트마다 전체를 다시 심으므로 O(상태 크기)다. P1 에서 반영 로직을 순수
+     * reduce 모듈로 추출해 투영기와 공유하면 사라진다. 지금은 계약이 성립하는지만 본다.
+     *
+     * `tick` 과 섞어 쓰지 않는다 — 섞으면 무엇이 진실인지 알 수 없다(관측이 시뮬을 덮어쓴다).
+     */
+    apply(envelope) {
+        if (!this.observer) {
+            this.observer = new ObservedReducer(this.boardDef ?? { nodes: [], movers: [] });
+            this.observeMode = true;
+        }
+        this.observer.apply(envelope);
+        /* **구독자에게 그대로 흘린다** — 호스트가 시뮬·관측 두 모드에서 같은 배선을 쓰게 하기 위해서다
+         * (`onEvent` 하나로 저널·방송이 붙는다). 관측 모드에서 이것은 **재방출**이지 새 사실이 아니다:
+         * 원천이 이미 그 이벤트를 갖고 있으므로, 호스트가 인입과 재방출을 **둘 다 저널에 적으면 중복**이
+         * 된다. 저널은 인입에서 한 번만 적는다. */
+        for (const h of this.observedHandlers())
+            h(envelope);
+        /* **이벤트마다 상태를 통째로 옮기지 않는다.** 옮기는 비용은 O(상태 크기)라, 이벤트 하나에 그것을
+         * 치르면 유입이 늘수록 감당이 안 된다. 필요해지는 순간(스냅샷·fork)에 **한 번만** 옮긴다. */
+        this.observedDirty = true;
+        this.revision++;
+    }
+    /** 관측분을 커널 상태로 옮긴다 — 필요할 때 한 번만(같은 규칙, 같은 씨앗 경로). */
+    settleObserved() {
+        if (!this.observedDirty || !this.observer)
+            return;
+        this.observedDirty = false;
+        this.hydrateObserved(this.observer.snapshot());
+    }
+    /** 구독자 목록 — 관측 재방출용(private handlers 에 접근). */
+    observedHandlers() {
+        return this.handlersRef();
+    }
+    /** 관측 구동으로 굴러가는 중인가 — 소비처가 "이 커널의 진실이 어디서 오나" 를 물을 수 있게. */
+    get observing() {
+        return this.observeMode;
+    }
     /**
      * 오퍼레이션 명세를 싣는다 — 도메인 정의(ISA-95 OperationsSegment)의 시뮬 명세를 커널이 소비하는 입구.
      * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
@@ -694,6 +791,52 @@ export class FlowEngine {
             bizTransactionList: opts.bizTransactionList
         }));
     }
+    /**
+     * 할당(예약) — **처분 변화를 이벤트로 낸다.**
+     *
+     * 예전에는 네 곳(WMS·YMS·MES 두 경로)이 각자 `disposition = reserved` 로 상태만 바꾸고 거래
+     * 이벤트(TransactionEvent)만 냈다. 거래 이벤트는 **처분을 싣지 않으므로** 미러는 그 물건이 잡혔다는
+     * 사실을 영영 알 수 없었다(적합성 하네스가 잡았다). 저널로 복원해도, 예측 씨앗에도 안 실린다.
+     *
+     * 관측 이벤트로 낸다 — 표준이 처분 변화를 표현하는 자리다(ObjectEvent OBSERVE + disposition).
+     * 물건이 여러 자리에 흩어져 있으면 **자리별로 나눠** 낸다(한 이벤트에 한 readPoint 가 맞다).
+     *
+     * `bizStep` 은 **호출부가 정한다.** 할당 자체를 가리키는 CBV 단계(reserving)를 1차 출처로 확인하지
+     * 못했으므로 어휘를 발명하지 않고, 그 할당이 속한 업무 단계를 그대로 쓴다.
+     */
+    reserve(epcs, bizStep) {
+        this.observeDisposition(epcs, DISP.reserved, bizStep);
+    }
+    /**
+     * 처분 변화 관측 — **상태와 이벤트를 한 번에.** 둘을 따로 쓰면 반드시 갈라진다.
+     *
+     * 실제로 양쪽으로 갈라져 있었다: 할당은 상태만 바꾸고 이벤트를 안 냈고(미러가 모름), 야드 도크
+     * 도착은 이벤트만 내고 상태를 안 바꿨다(이벤트와 상태가 다른 말). 적합성 하네스가 둘 다 잡았다.
+     *
+     * 물건이 여러 자리에 있으면 자리별로 나눠 낸다(한 이벤트에 한 readPoint 가 맞다).
+     * 이미 그 처분이면 아무 일도 하지 않는다(같은 사실을 두 번 말하지 않는다).
+     */
+    observeDisposition(epcs, disposition, bizStep, at) {
+        const byLocation = new Map();
+        for (const epc of epcs) {
+            const it = this.items.get(epc);
+            if (!it || it.disposition === disposition)
+                continue;
+            it.disposition = disposition;
+            const where = at ?? it.location ?? '';
+            const bin = byLocation.get(where);
+            if (bin)
+                bin.push(epc);
+            else
+                byLocation.set(where, [epc]);
+        }
+        for (const [where, list] of byLocation) {
+            this.emit(objectEvent({
+                eventTime: this.now(), action: 'OBSERVE', bizStep, disposition,
+                epcList: list, ...(where ? { readPoint: where, bizLocation: where } : {})
+            }));
+        }
+    }
     /**
      * containment 조립(EPCIS AggregationEvent ADD) — 자식들을 부모(용기)로 집約.
      * consume 지정 시 자식이 컨테이너로 흡수되며 독립 아이템에서 이탈(dematerialize: ObjectEvent DELETE + 제거).
@@ -712,6 +855,14 @@ export class FlowEngine {
                     this.items.delete(c);
                 }
             }
+            return;
+        }
+        /* 흡수하지 않는 조립 — 자식은 독립 물품으로 남되 **소속을 상태에도 남긴다.**
+         * 예전에는 이벤트만 내고 상태를 안 바꿔서, 미러는 소속을 알고 시뮬은 몰랐다(같은 사실, 다른 답). */
+        for (const c of children) {
+            const it = this.items.get(c);
+            if (it)
+                it.parent = parent;
         }
     }
     /**
@@ -721,6 +872,12 @@ export class FlowEngine {
      */
     disaggregate(parent, children, opts) {
         this.emit(aggregationEvent({ eventTime: this.now(), action: 'DELETE', bizStep: opts.bizStep, parentID: parent, childEPCs: children.slice(), readPoint: opts.readPoint }));
+        /* 분해 — 소속이 끊어진다(자식이 독립으로 남든 새로 등장하든). */
+        for (const c of children) {
+            const it = this.items.get(c);
+            if (it)
+                it.parent = undefined;
+        }
         if (opts.materialize) {
             const m = opts.materialize;
             for (const c of children) {
@@ -789,8 +946,9 @@ export class FlowEngine {
             intent: t.intent,
             ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
             ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
+            ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
             ...(t.durationMs ? { durationMs: t.durationMs } : {}),
-            ...(inProgress ? { remainingMs: t.remainingMs, progress: t.durationMs ? done / t.durationMs : undefined } : {})
+            ...(inProgress ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: t.durationMs ? done / t.durationMs : undefined } : {})
         });
     }
     /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
@@ -800,8 +958,18 @@ export class FlowEngine {
     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 }); }
+    /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
+     *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
+    emitMover(m, motion) {
+        this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, taskId: m.taskId ?? undefined, 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,
+            ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {})
+        });
+    }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────
     /**
      * 자극 간격 — **계약이 선언한 네 분포를 실제로 판정한다.**
@@ -892,8 +1060,14 @@ export class FlowEngine {
                 continue;
             a.status = 'in-use';
             a.taskId = t.id;
-            if (t.itemEpc)
+            if (t.itemEpc) {
                 a.carrying = t.itemEpc;
+                /* 반대 방향도 맺는다 — 계약이 두 축을 다 정의했으므로 한쪽만 채우면 소비처가 물품에서
+                 * 자산을 못 찾는다(자산 목록을 뒤져야 한다). */
+                const it = this.items.get(t.itemEpc);
+                if (it)
+                    it.carriedBy = a.id;
+            }
             this.emitAsset(a);
         }
     }
@@ -909,6 +1083,11 @@ export class FlowEngine {
             a.status = 'idle';
             a.taskId = null;
             a.location = t.toNode || a.location;
+            if (a.carrying) {
+                const it = this.items.get(a.carrying);
+                if (it)
+                    it.carriedBy = undefined;
+            }
             a.carrying = undefined;
             this.emitAsset(a);
         }
@@ -939,6 +1118,31 @@ export class FlowEngine {
         }
         return picked;
     }
+    /**
+     * 필요 설비를 고른다 — **인원·자산과 같은 규칙**(등급으로 요구, 부분 확보 없이 전량 아니면 대기).
+     * 명세(`equipmentSpecification`)가 없으면 기존 거동: `resourceType` 한 대(없으면 아무 유휴 설비).
+     * 여기서는 고르기만 한다 — 확정은 호출부가 다른 자원까지 확보한 뒤에 한다.
+     */
+    claimEquipment(t) {
+        const free = (kind, picked = []) => [...this.movers.values()].filter(m => m.status === 'idle' && !m.held && !this.offShift(m) && !picked.includes(m.id) && (kind === undefined || m.kind === kind));
+        const need = this.operationSpecs.get(t.kind)?.equipmentSpecification;
+        if (!need?.length) {
+            const one = free(t.resourceType)[0];
+            return one ? [one.id] : null;
+        }
+        const picked = [];
+        for (const req of need) {
+            const want = Math.max(0, Math.floor(req.quantity ?? 0));
+            if (!want)
+                continue;
+            const avail = free(req.equipmentClass, picked);
+            if (avail.length < want)
+                return null; // 한 등급이라도 모자라면 시작하지 않는다
+            for (let i = 0; i < want; i++)
+                picked.push(avail[i].id);
+        }
+        return picked.length ? picked : null;
+    }
     /** 확보한 사람을 작업에 묶는다(설비까지 확정된 뒤). */
     assignCrew(t, crew) {
         if (!crew.length)
@@ -1048,6 +1252,35 @@ export class FlowEngine {
             }
         }
     }
+    /**
+     * 물품 상태 산출 — **보유값 + 식별자에서 나오는 파생값.**
+     *
+     * 품번 키(`gtinKey`)·로트(`lot`)는 식별자의 순수 함수라 저장하지 않고 여기서 낸다. 투영기와 **같은
+     * 규칙**(`parseEpc`)을 쓴다 — 두 구동이 같은 식별자를 다르게 뜯으면 같은 사실이 다르게 보인다.
+     * 로트는 LGTIN 이면 식별자 안에 있고, 직렬 개체는 마스터데이터(`ilmd`)에 실려 온다.
+     */
+    itemState(i) {
+        const parsedClass = i.gtin ? parseEpc(i.gtin) : undefined;
+        const parsedSelf = parseEpc(i.epc);
+        const lot = parsedClass?.lot ??
+            parsedSelf.lot ??
+            (typeof i.ilmd?.[ILMD_ATTR.lot] === 'string' ? i.ilmd[ILMD_ATTR.lot] : undefined);
+        const gtinKey = parsedClass?.gtinKey ?? parsedSelf.gtinKey;
+        return {
+            epc: i.epc,
+            ...(i.gtin ? { gtin: i.gtin } : {}),
+            ...(gtinKey ? { gtinKey } : {}),
+            ...(lot ? { lot } : {}),
+            location: i.location,
+            ...(i.disposition ? { disposition: i.disposition } : {}),
+            ...(i.parent ? { parent: i.parent } : {}),
+            ...(i.carriedBy ? { carriedBy: i.carriedBy } : {}),
+            ...(i.qty !== undefined ? { qty: i.qty } : {}),
+            ...(i.uom ? { uom: i.uom } : {}),
+            ...(i.expiry !== undefined ? { expiry: i.expiry } : {}),
+            ...(i.ilmd ? { ilmd: i.ilmd } : {})
+        };
+    }
     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) {
@@ -1080,8 +1313,19 @@ export class FlowEngine {
             if (o.status === 'created' && !o.held)
                 this.allocate(o);
     }
+    /**
+     * 작업 진행 — **진행을 먼저, 배정을 나중에.**
+     *
+     * 예전에는 배정을 먼저 하고 같은 tick 에서 곧바로 dt 만큼 깎았다. 그래서 이제 막 시작한 작업이
+     * 시작하자마자 한 스텝 진행된 것으로 계산됐고, **방출한 모션 앵커(startedAtSimMs)와 스냅샷이 한
+     * tick 어긋났다**(적합성 하네스가 잡았다). 스텝이 커질수록 오차도 커진다.
+     */
     processTasks(dt) {
-        // 1) created → in-progress. dwell(무자원)은 즉시 진행, transport/process 는 가용 자원 배정.
+        this.advanceTasks(dt);
+        this.assignTasks();
+    }
+    assignTasks() {
+        // created → in-progress. dwell(무자원)은 즉시 진행, transport/process 는 가용 자원 배정.
         for (const t of this.tasks.values()) {
             if (t.status !== 'created')
                 continue;
@@ -1097,6 +1341,7 @@ export class FlowEngine {
             if (t.intent === 'dwell') { // 무설비 체류 — 설비 배정 없이 진행(인원 요구가 있으면 위에서 확보됨)
                 t.status = 'in-progress';
                 t.remainingMs = t.durationMs;
+                t.startedAtSimMs = this.clockMs;
                 this.assignCrew(t, crew);
                 this.assignAssets(t, gear);
                 this.emitTask(t);
@@ -1106,10 +1351,12 @@ export class FlowEngine {
              * 이 제약이 없으면 대기가 생기지 않아 병목이 사라지고 예측이 낙관 쪽으로 치우친다. */
             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 아님: 다른 타입은 가용할 수 있음)
+            /* 필요 설비 — 명세가 있으면 등급별 대수만큼(부분 확보 없이), 없으면 기존대로 한 대.
+             * 확보 실패는 `null` — 다음 작업으로 넘어간다(다른 타입은 가용할 수 있다). */
+            const rigs = this.claimEquipment(t);
+            if (!rigs)
+                continue;
+            const mover = this.movers.get(rigs[0]);
             // 체인지오버: task 의 changeoverKey 가 무버 직전 키와 다르면 셋업 부착(첫 작업은 셋업 없음).
             if (t.setupMs && t.changeoverKey !== undefined && mover.lastChangeoverKey !== undefined && mover.lastChangeoverKey !== t.changeoverKey) {
                 t.appliedSetupMs = t.setupMs;
@@ -1117,11 +1364,17 @@ export class FlowEngine {
             }
             if (t.changeoverKey !== undefined)
                 mover.lastChangeoverKey = t.changeoverKey;
-            mover.status = 'busy';
-            mover.taskId = t.id;
+            for (const id of rigs) {
+                const m = this.movers.get(id);
+                m.status = 'busy';
+                m.taskId = t.id;
+            }
             t.status = 'in-progress';
             t.resource = mover.id;
             t.remainingMs = t.durationMs;
+            t.startedAtSimMs = this.clockMs;
+            if (rigs.length > 1)
+                t.resources = rigs.slice(); // 대표만으로는 함께 잡힌 설비가 사라진다
             this.assignCrew(t, crew);
             this.assignAssets(t, gear);
             this.emitTask(t);
@@ -1131,7 +1384,9 @@ export class FlowEngine {
             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 는 자원 해제·델타만.
+    }
+    /** in-progress 진행/완료 — 상태 효과는 전부 도메인(onTaskComplete). base 는 자원 해제·델타만. */
+    advanceTasks(dt) {
         for (const t of this.tasks.values()) {
             if (t.status !== 'in-progress')
                 continue;
@@ -1157,6 +1412,21 @@ export class FlowEngine {
             mover.taskId = null;
             if (t.intent !== 'process')
                 mover.location = t.toNode; // 운반만 위치 이동; process 는 제자리
+            /* 함께 잡힌 설비도 같은 규칙으로 놓아 준다 — 대표만 풀면 나머지가 영원히 묶인다. */
+            for (const id of t.resources ?? []) {
+                if (id === mover.id)
+                    continue;
+                const m = this.movers.get(id);
+                if (!m)
+                    continue;
+                m.setupMs += setup;
+                m.runMs += t.durationMs - setup;
+                m.status = 'idle';
+                m.taskId = null;
+                if (t.intent !== 'process')
+                    m.location = t.toNode;
+                this.emitMover(m);
+            }
             this.emitTask(t);
             this.emitMover(mover);
         }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from './domain-catalog.ts';
 export * from './allocation-policy.ts';
 export * from './duration-estimator.ts';
 export * from './iso-duration.ts';
+export * from './observed-reducer.ts';
 export * from './state-projector.ts';
 export * from './task-fold.ts';
 export * from './face2-adapter.ts';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from "./domain-catalog.js";
 export * from "./allocation-policy.js";
 export * from "./duration-estimator.js";
 export * from "./iso-duration.js";
+export * from "./observed-reducer.js";
 export * from "./state-projector.js";
 export * from "./task-fold.js";
 export * from "./face2-adapter.js";

package/dist/kernel.js

@@ -33,7 +33,10 @@ export class WmsKernel extends FlowEngine {
         const poTxn = [{ type: BTT.po, bizTransaction: po }];
         // 로트 만료(FEFO 용, 결정적 — rng 무소비로 byte-identical 유지). 편차로 도착순≠만료순 → FEFO 가 유의미.
         const expiry = this.clockMs + SHELF_MS - (this.epcSeq % 5) * SHELF_JITTER_MS;
-        this.items.set(epc, { epc, gtin, qty, location: dock.id, disposition: DISP.in_progress, expiry });
+        /* 방출한 마스터데이터를 **상태에도 들고 있는다** — 자기가 선언한 것을 자기가 모르면, 미러는 알고
+         * 시뮬은 모르는 비대칭이 생긴다(파리티 테스트가 잡은 바로 그 종류). */
+        const ilmd = { [ILMD_ATTR.expiry]: expiry };
+        this.items.set(epc, { epc, gtin, qty, location: dock.id, disposition: DISP.in_progress, expiry, ilmd });
         dock.occupancy++;
         this.emit(transactionEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, bizTransactionList: poTxn, epcList: [epc], quantityList: qtyList, readPoint: dock.id }));
         this.emit(aggregationEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, parentID: epc, childQuantityList: qtyList, readPoint: dock.id }));
@@ -42,7 +45,7 @@ export class WmsKernel extends FlowEngine {
         this.emit(objectEvent({
             eventTime, action: 'ADD', bizStep: BIZSTEP.receiving, disposition: DISP.in_progress,
             epcList: [epc], quantityList: qtyList, readPoint: dock.id, bizLocation: dock.id, bizTransactionList: poTxn,
-            ilmd: { [ILMD_ATTR.expiry]: expiry }
+            ilmd
         }));
         const binId = this.policy.selectPlacement({ item: { epc, gtin, qty }, slots: this.slotViews('storage') });
         if (!binId)
@@ -115,13 +118,15 @@ export class WmsKernel extends FlowEngine {
                 .map(i => ({ epc: i.epc, location: i.location, qty: i.qty ?? 1, expiry: i.expiry }));
             const chosen = this.policy.selectStock({ gtin: line.gtin, qty: need, available });
             for (const epc of chosen) {
-                this.items.get(epc).disposition = DISP.reserved;
                 o.allocated.push(epc);
                 chosenAll.push(epc);
             }
         }
         if (chosenAll.length === 0)
             return;
+        /* 할당은 아직 집은 것이 아니다 — 물건은 보관 자리에 있고 처분만 '예약' 으로 바뀐다.
+         * 그래서 단계는 storing 이다(피킹 관측은 실제로 집을 때 따로 난다). */
+        this.reserve(chosenAll, BIZSTEP.storing);
         this.emit(transactionEvent({ eventTime: this.now(), action: 'ADD', bizStep: BIZSTEP.picking, bizTransactionList: [{ type: BTT.so, bizTransaction: o.bizTransaction }], epcList: chosenAll.slice() }));
         for (const epc of chosenAll) {
             const it = this.items.get(epc);

package/dist/mes-kernel.js

@@ -134,10 +134,9 @@ export class MesKernel extends FlowEngine {
                 return; // 부품 부족 → 대기
             picks.push(...chosen);
         }
-        for (const epc of picks) {
-            this.items.get(epc).disposition = DISP.reserved;
+        for (const epc of picks)
             o.allocated.push(epc);
-        }
+        this.reserve(picks, MES_BIZSTEP.producing);
         this.emit(transactionEvent({ eventTime: this.now(), action: 'ADD', bizStep: MES_BIZSTEP.producing, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: o.bizTransaction }], epcList: o.allocated.slice() }));
         this.emitStation(o, s0, o.allocated[0], product.gtin);
         o.status = 'op-' + s0.kind;
@@ -243,10 +242,9 @@ export class MesKernel extends FlowEngine {
                 return; // 자재 부족 → 대기
             picks.push(...chosen);
         }
-        for (const epc of picks) {
-            this.items.get(epc).disposition = DISP.reserved;
+        for (const epc of picks)
             o.allocated.push(epc);
-        }
+        this.reserve(picks, MES_BIZSTEP.producing);
         this.emit(transactionEvent({ eventTime: this.now(), action: 'ADD', bizStep: MES_BIZSTEP.producing, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: o.bizTransaction }], epcList: o.allocated.slice() }));
         this.emitStationDef(o, ops[0], o.allocated[0]);
         o.status = 'op-' + ops[0].key;