@operato/twin-kernel 0.2.0 → 0.2.1

package/dist-cjs/index.cjs

@@ -40,9 +40,11 @@ __export(index_exports, {
   MES_PRODUCT_GTINS: () => MES_PRODUCT_GTINS,
   MES_TYPES: () => MES_TYPES,
   MesKernel: () => MesKernel,
+  NODE_SATURATION_NEAR: () => NODE_SATURATION_NEAR,
   OP_EVENT: () => OP_EVENT,
   OP_PARAM: () => OP_PARAM,
-  StateProjector: () => StateProjector,
+  ObservedReducer: () => ObservedReducer,
+  StateProjector: () => ObservedReducer,
   TwinHistory: () => TwinHistory,
   TwinObserver: () => TwinObserver,
   TwinRuntime: () => TwinRuntime,
@@ -70,6 +72,7 @@ __export(index_exports, {
   lgtinClass: () => lgtinClass,
   mapRecord: () => mapRecord,
   monteCarloForecast: () => monteCarloForecast,
+  nodeStatusOf: () => nodeStatusOf,
   objectEvent: () => objectEvent,
   parseEpc: () => parseEpc,
   parseIsoDuration: () => parseIsoDuration,
@@ -87,6 +90,13 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/contract.ts
+var NODE_SATURATION_NEAR = 0.9;
+function nodeStatusOf(n) {
+  const cap = n.capacity;
+  if (!(typeof cap === "number" && cap > 0)) return void 0;
+  const r = (n.occupancy ?? 0) / cap;
+  return r >= 1 ? "full" : r >= NODE_SATURATION_NEAR ? "near-full" : "available";
+}
 var OP_EVENT = {
   task: "task.status",
   equipment: "equipment.status",
@@ -517,14 +527,16 @@ function validateEpcisEvent(e) {
   return v;
 }
 
-// src/state-projector.ts
+// src/observed-reducer.ts
 var UNKNOWN_TYPE = "unknown";
-var StateProjector = class {
+var ObservedReducer = class {
   /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
   master = /* @__PURE__ */ new Map();
   items = /* @__PURE__ */ new Map();
   aggregation = /* @__PURE__ */ new Map();
-  // parent SSCC → child EPCs
+  /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
+  pendingParent = /* @__PURE__ */ new Map();
+  // 자식 EPC → 부모(물류단위)
   tasks = /* @__PURE__ */ new Map();
   movers = /* @__PURE__ */ new Map();
   persons = /* @__PURE__ */ new Map();
@@ -534,7 +546,7 @@ var StateProjector = class {
   /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
   corrections = [];
   constructor(board) {
-    for (const n of board.nodes) this.master.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parentId: n.parentId, origin: "master" });
+    for (const n of board.nodes) this.master.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, parentId: n.parentId, origin: "master" });
     for (const m of board.movers) this.movers.set(m.id, { id: m.id, kind: m.kind, status: "idle", location: m.homeNode, origin: "master" });
     for (const p of board.persons ?? []) this.persons.set(p.id, { id: p.id, personnelClass: p.personnelClass, status: "idle" });
     for (const a of board.assets ?? []) this.assets.set(a.id, { id: a.id, assetClass: a.assetClass, location: a.homeNode, status: "idle" });
@@ -547,10 +559,12 @@ var StateProjector = class {
     }
     const cur = this.master.get(u.node.id);
     const capacity = u.node.capacity ?? cur?.capacity;
+    const parallelism = u.node.parallelism ?? cur?.parallelism;
     this.master.set(u.node.id, {
       id: u.node.id,
       type: u.node.type ?? cur?.type ?? UNKNOWN_TYPE,
       ...capacity === void 0 ? {} : { capacity },
+      ...parallelism === void 0 ? {} : { parallelism },
       ...u.node.parentId ?? cur?.parentId ? { parentId: u.node.parentId ?? cur?.parentId } : {},
       /* 마스터가 말한 것은 마스터 출처다 — 관측으로 알게 된 것(origin='observed')을 덮어 승격한다. */
       origin: "master"
@@ -623,6 +637,7 @@ var StateProjector = class {
           progress: d.progress,
           remainingMs: d.remainingMs,
           durationMs: d.durationMs,
+          startedAtSimMs: d.startedAtSimMs,
           ...d.personnel?.length ? { personnel: d.personnel.slice() } : {},
           ...d.assets?.length ? { assets: d.assets.slice() } : {}
         });
@@ -633,7 +648,7 @@ var StateProjector = class {
         if (this.stale(`mover:${d.moverId}`, e)) return;
         this.touchLocation(d.location);
         const known = this.movers.get(d.moverId);
-        this.movers.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, motion: d.motion, origin: known?.origin ?? "observed" });
+        this.movers.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, taskId: d.taskId, motion: d.motion, origin: known?.origin ?? "observed" });
         break;
       }
       case OP_EVENT.person: {
@@ -686,13 +701,17 @@ var StateProjector = class {
         this.aggregation.set(ev.parentID, [...ev.childEPCs]);
         for (const child of ev.childEPCs) {
           const cur = this.items.get(child);
-          if (cur) this.items.set(child, { ...cur, parent: ev.parentID });
-          else this.items.set(child, { epc: child, location: "", parent: ev.parentID });
+          if (cur) {
+            this.items.set(child, { ...cur, parent: ev.parentID });
+            continue;
+          }
+          this.pendingParent.set(child, ev.parentID);
         }
       } else if (ev.action === "DELETE") {
         for (const child of this.aggregation.get(ev.parentID) ?? []) {
           const cur = this.items.get(child);
           if (cur) this.items.set(child, { ...cur, parent: void 0 });
+          this.pendingParent.delete(child);
         }
         this.aggregation.delete(ev.parentID);
       }
@@ -755,7 +774,7 @@ var StateProjector = class {
       gtinKey: parsedClass?.gtinKey ?? parsedSelf.gtinKey ?? cur?.gtinKey,
       location: patch.location ?? cur?.location ?? "",
       disposition: patch.disposition ?? cur?.disposition,
-      parent: cur?.parent,
+      parent: cur?.parent ?? this.pendingParent.get(epc),
       qty: q?.quantity ?? cur?.qty,
       uom: q?.uom ?? cur?.uom,
       /* 마스터데이터는 생겨날 때 한 번 정해진다 — 뒤 이벤트가 지우지 않게 기존 값을 남긴다. */
@@ -781,15 +800,21 @@ var StateProjector = class {
     return {
       revision: this.revision,
       ...this.corrections.length ? { corrections: this.corrections.map((c) => ({ ...c })) } : {},
-      nodes: [...this.master.values()].map((n) => ({
-        id: n.id,
-        type: n.type,
-        occupancy: occ.get(n.id) ?? 0,
-        /* 용량 미상은 **키를 만들지 않는다** — 0 으로 실으면 "자리 없음" 이라는 없는 사실이 생긴다. */
-        ...n.capacity === void 0 ? {} : { capacity: n.capacity },
-        ...n.parentId ? { parentId: n.parentId } : {},
-        origin: n.origin
-      })),
+      nodes: [...this.master.values()].map((n) => {
+        const occupancy = occ.get(n.id) ?? 0;
+        const status = nodeStatusOf({ occupancy, capacity: n.capacity });
+        return {
+          id: n.id,
+          type: n.type,
+          occupancy,
+          ...status ? { status } : {},
+          /* 용량 미상은 **키를 만들지 않는다** — 0 으로 실으면 "자리 없음" 이라는 없는 사실이 생긴다. */
+          ...n.capacity === void 0 ? {} : { capacity: n.capacity },
+          ...n.parallelism === void 0 ? {} : { parallelism: n.parallelism },
+          ...n.parentId ? { parentId: n.parentId } : {},
+          origin: n.origin
+        };
+      }),
       /* 들고 있는 것을 전부 내보낸다 — 축소하면 그 자리에서 정보가 사라진다. */
       items: [...this.items.values()].map((i) => ({ ...i })),
       persons: [...this.persons.values()].map((p) => ({ ...p })),
@@ -828,7 +853,7 @@ var EventJournal = class {
   }
 };
 function replay(board, events) {
-  const proj = new StateProjector(board);
+  const proj = new ObservedReducer(board);
   for (const e of events) proj.apply(e);
   return proj.snapshot();
 }
@@ -1283,6 +1308,13 @@ var FlowEngine = class {
    * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
    */
   operationSpecs = /* @__PURE__ */ new Map();
+  /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
+  observer;
+  /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
+  observedDirty = false;
+  observeMode = false;
+  /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
+  boardDef;
   /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
   specUse = /* @__PURE__ */ new Map();
   epcSeq = 0;
@@ -1290,6 +1322,10 @@ var FlowEngine = class {
   orderSeq = 0;
   soSeq = 0;
   handlers = [];
+  /** 구독자 접근(관측 재방출) — emit 과 같은 목록을 쓴다(두 경로가 갈리지 않게). */
+  handlersRef() {
+    return this.handlers;
+  }
   gens = [];
   generating = false;
   speed = 1;
@@ -1300,6 +1336,7 @@ var FlowEngine = class {
   }
   // ── 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 ?? []) 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 });
@@ -1341,15 +1378,15 @@ var FlowEngine = class {
     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,
+        carriedBy: it.carriedBy,
         expiry: it.expiry,
         ilmd: it.ilmd
       });
@@ -1387,6 +1424,7 @@ var FlowEngine = class {
         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
@@ -1562,13 +1600,20 @@ var FlowEngine = class {
     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 ?? void 0, 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 ?? void 0, oee: this.oeeOf(m), held: m.held, origin: "master", ...this.offShift(m) ? { offShift: true } : {} };
         const t = m.taskId ? this.tasks.get(m.taskId) : void 0;
         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;
@@ -1583,7 +1628,24 @@ var FlowEngine = class {
         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 ?? void 0, orderId: t.orderId, progress: t.status === "in-progress" ? this.progressOf(t) : void 0, ...t.personnel?.length ? { personnel: t.personnel.slice() } : {} })),
+      /* 스냅샷이 **델타보다 가난하면 안 된다** — 예전에는 소요·남은 시간을 빼고 내보내서, 이 스냅샷으로
+       * 다른 커널을 심으면(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 ?? void 0,
+        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() } : {}
+      })),
       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()
     };
@@ -1609,6 +1671,7 @@ var FlowEngine = class {
    * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
    */
   fork(tenantId = this.tenantId) {
+    this.settleObserved();
     const Ctor = this.constructor;
     const clone = new Ctor(tenantId, this.policy);
     const skip = /* @__PURE__ */ new Set(["policy", "scenario", "tenantId", "handlers", "durationEstimator"]);
@@ -1631,6 +1694,46 @@ var FlowEngine = class {
   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);
+    for (const h of this.observedHandlers()) h(envelope);
+    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 를 다시 실으면 덮어쓴다(정의가 권위).
@@ -1793,6 +1896,53 @@ var FlowEngine = class {
       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 = /* @__PURE__ */ 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 + 제거).
@@ -1810,6 +1960,11 @@ var FlowEngine = class {
           this.items.delete(c);
         }
       }
+      return;
+    }
+    for (const c of children) {
+      const it = this.items.get(c);
+      if (it) it.parent = parent;
     }
   }
   /**
@@ -1819,6 +1974,10 @@ var FlowEngine = class {
    */
   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 = void 0;
+    }
     if (opts.materialize) {
       const m = opts.materialize;
       for (const c of children) {
@@ -1882,7 +2041,7 @@ var FlowEngine = class {
       ...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 : void 0 } : {}
+      ...inProgress ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: t.durationMs ? done / t.durationMs : void 0 } : {}
     });
   }
   /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
@@ -1892,8 +2051,10 @@ var FlowEngine = class {
   emitPerson(p) {
     this.emitOp(OP_EVENT.person, { personId: p.id, personnelClass: p.personnelClass, status: p.status, taskId: p.taskId ?? void 0, ...this.personOffShift(p) ? { offShift: true } : {} });
   }
+  /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
+   *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
   emitMover(m, motion) {
-    this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, motion });
+    this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, taskId: m.taskId ?? void 0, 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 });
@@ -1980,7 +2141,11 @@ var FlowEngine = class {
       if (!a) continue;
       a.status = "in-use";
       a.taskId = t.id;
-      if (t.itemEpc) a.carrying = 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);
     }
   }
@@ -1995,6 +2160,10 @@ var FlowEngine = class {
       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 = void 0;
+      }
       a.carrying = void 0;
       this.emitAsset(a);
     }
@@ -2116,6 +2285,33 @@ var FlowEngine = class {
       }
     }
   }
+  /**
+   * 물품 상태 산출 — **보유값 + 식별자에서 나오는 파생값.**
+   *
+   * 품번 키(`gtinKey`)·로트(`lot`)는 식별자의 순수 함수라 저장하지 않고 여기서 낸다. 투영기와 **같은
+   * 규칙**(`parseEpc`)을 쓴다 — 두 구동이 같은 식별자를 다르게 뜯으면 같은 사실이 다르게 보인다.
+   * 로트는 LGTIN 이면 식별자 안에 있고, 직렬 개체는 마스터데이터(`ilmd`)에 실려 온다.
+   */
+  itemState(i) {
+    const parsedClass = i.gtin ? parseEpc(i.gtin) : void 0;
+    const parsedSelf = parseEpc(i.epc);
+    const lot = parsedClass?.lot ?? parsedSelf.lot ?? (typeof i.ilmd?.[ILMD_ATTR.lot] === "string" ? i.ilmd[ILMD_ATTR.lot] : void 0);
+    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 !== void 0 ? { qty: i.qty } : {},
+      ...i.uom ? { uom: i.uom } : {},
+      ...i.expiry !== void 0 ? { 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));
   }
@@ -2141,7 +2337,18 @@ var FlowEngine = class {
   processOrders() {
     for (const o of this.orders.values()) if (o.status === "created" && !o.held) this.allocate(o);
   }
+  /**
+   * 작업 진행 — **진행을 먼저, 배정을 나중에.**
+   *
+   * 예전에는 배정을 먼저 하고 같은 tick 에서 곧바로 dt 만큼 깎았다. 그래서 이제 막 시작한 작업이
+   * 시작하자마자 한 스텝 진행된 것으로 계산됐고, **방출한 모션 앵커(startedAtSimMs)와 스냅샷이 한
+   * tick 어긋났다**(적합성 하네스가 잡았다). 스텝이 커질수록 오차도 커진다.
+   */
   processTasks(dt) {
+    this.advanceTasks(dt);
+    this.assignTasks();
+  }
+  assignTasks() {
     for (const t of this.tasks.values()) {
       if (t.status !== "created") continue;
       const crew = this.claimPersonnel(t);
@@ -2151,6 +2358,7 @@ var FlowEngine = class {
       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);
@@ -2171,12 +2379,16 @@ var FlowEngine = class {
       t.status = "in-progress";
       t.resource = mover.id;
       t.remainingMs = t.durationMs;
+      t.startedAtSimMs = this.clockMs;
       this.assignCrew(t, crew);
       this.assignAssets(t, gear);
       this.emitTask(t);
       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 });
     }
+  }
+  /** in-progress 진행/완료 — 상태 효과는 전부 도메인(onTaskComplete). base 는 자원 해제·델타만. */
+  advanceTasks(dt) {
     for (const t of this.tasks.values()) {
       if (t.status !== "in-progress") continue;
       if (t.resource && this.movers.get(t.resource)?.status === "down") continue;
@@ -2225,7 +2437,8 @@ var WmsKernel = class extends FlowEngine {
     const qtyList = [{ epcClass: gtin, quantity: qty }];
     const poTxn = [{ type: BTT.po, bizTransaction: po }];
     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 }));
@@ -2239,7 +2452,7 @@ var WmsKernel = class extends FlowEngine {
       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) return;
@@ -2314,12 +2527,12 @@ var WmsKernel = class extends FlowEngine {
       const available = [...this.items.values()].filter((i) => i.gtin === line.gtin && i.disposition === DISP.sellable && this.nodes.get(i.location)?.type === "storage").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;
+    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);
@@ -2463,7 +2676,7 @@ var YmsKernel = class extends FlowEngine {
       if (!staging || avail.length < CARGO_PER_TRAILER) return;
       this.trailerCargo.set(trailer.epc, avail.slice(0, CARGO_PER_TRAILER).map((i) => i.epc));
     }
-    trailer.disposition = DISP.reserved;
+    this.reserve([trailer.epc], bizStep);
     this.emit(transactionEvent({ eventTime: this.now(), action: "ADD", bizStep, bizTransactionList: [{ type: BTT_DELIVERY, bizTransaction: o.bizTransaction }], epcList: [trailer.epc], readPoint: door.id }));
     const dockKind = mode === "drop" ? "pull" : "spot-live";
     const task = { id: `task-${++this.taskSeq}`, kind: dockKind, status: "created", itemEpc: trailer.epc, fromNode: trailer.location, toNode: door.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: dockKind, fromNode: trailer.location, toNode: door.id }, TRAVEL_MS2), orderId: o.id };
@@ -2497,7 +2710,7 @@ var YmsKernel = class extends FlowEngine {
       const outbound = order2?.kind === "appointment-out";
       const staging = this.nodeByType("staging");
       const cargo = this.trailerCargo.get(trailer.epc) ?? [];
-      this.emit(objectEvent({ eventTime: this.now(), action: "OBSERVE", bizStep: outbound ? YARD_BIZSTEP.loading : YARD_BIZSTEP.unloading, disposition: DISP.in_progress, epcList: [trailer.epc], readPoint: to.id, bizLocation: to.id }));
+      this.observeDisposition([trailer.epc], DISP.in_progress, outbound ? YARD_BIZSTEP.loading : YARD_BIZSTEP.unloading, to.id);
       if (outbound) {
         if (cargo.length && staging) {
           this.aggregate(trailer.epc, cargo, { bizStep: YARD_BIZSTEP.loading, readPoint: to.id, consume: { readPoint: staging.id, disposition: DISP.in_transit } });
@@ -2623,10 +2836,8 @@ var MesKernel = class extends FlowEngine {
       if (chosen.length < line.qty) return;
       picks.push(...chosen);
     }
-    for (const epc of picks) {
-      this.items.get(epc).disposition = DISP.reserved;
-      o.allocated.push(epc);
-    }
+    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;
@@ -2723,10 +2934,8 @@ var MesKernel = class extends FlowEngine {
       if (chosen.length < line.qty) return;
       picks.push(...chosen);
     }
-    for (const epc of picks) {
-      this.items.get(epc).disposition = DISP.reserved;
-      o.allocated.push(epc);
-    }
+    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;
@@ -2797,8 +3006,10 @@ var MesKernel = class extends FlowEngine {
   MES_PRODUCT_GTINS,
   MES_TYPES,
   MesKernel,
+  NODE_SATURATION_NEAR,
   OP_EVENT,
   OP_PARAM,
+  ObservedReducer,
   StateProjector,
   TwinHistory,
   TwinObserver,
@@ -2827,6 +3038,7 @@ var MesKernel = class extends FlowEngine {
   lgtinClass,
   mapRecord,
   monteCarloForecast,
+  nodeStatusOf,
   objectEvent,
   parseEpc,
   parseIsoDuration,

package/package.json

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