@operato/twin-kernel 0.11.23 → 0.11.24

package/dist/flow-engine.d.ts

@@ -500,6 +500,9 @@ export declare class ItemStore {
      * 사라진다**(있는데 없다고 판정된다). 자리 색인과 같은 규율이다.
      */
     private byGtin;
+    /** 같은 글자를 매번 뜯지 않는다 — 클래스 글자의 종류는 적고 물품은 많다. */
+    private itemClassCache;
+    private itemClass;
     get size(): number;
     get(key: string): FlowItem | undefined;
     has(key: string): boolean;

package/dist/flow-engine.js

@@ -10,7 +10,7 @@
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
 import { isWorkShiftExecutionBasis } from '@operato/ops-contract';
-import { OP_EVENT, CMD, USE_UOM, locationStatusOf, readBoardEquipment, equipmentClassMembership, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf, outsideLimit, computeOee } from '@operato/ops-contract';
+import { OP_EVENT, CMD, USE_UOM, locationStatusOf, readBoardEquipment, equipmentClassMembership, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, itemClassOf, identityGroundingOf, outsideLimit, computeOee } from '@operato/ops-contract';
 import { ObservedReducer } from "./observed-reducer.js";
 /* 주체를 정하는 규칙은 유입 문과 한 벌이다 — 두 곳에 적으면 한쪽만 고쳐진다. */
 import { resolveSubject } from '@operato/ops-contract';
@@ -407,7 +407,21 @@ export class ItemStore {
      * 색인을 밖에 따로 두지 않는다 — 갱신하는 자리가 흩어지면 한 자리라도 빠뜨렸을 때 **재고가 조용히
      * 사라진다**(있는데 없다고 판정된다). 자리 색인과 같은 규율이다.
      */
+    /*
+     * 품목 색인 — 키는 **품목 클래스**다(`itemClassOf`). 재고는 로트 클래스를 들고 오더는 품목 클래스를 묻는다
+     * (ADR-0076 ⑥ · ADR-0082 결정 2). 로트 글자를 키로 쓰면 품목을 물어도 로트 재고가 안 나온다.
+     */
     byGtin = new Map();
+    /** 같은 글자를 매번 뜯지 않는다 — 클래스 글자의 종류는 적고 물품은 많다. */
+    itemClassCache = new Map();
+    itemClass(gtin) {
+        let c = this.itemClassCache.get(gtin);
+        if (c === undefined) {
+            c = itemClassOf(gtin) ?? gtin;
+            this.itemClassCache.set(gtin, c);
+        }
+        return c;
+    }
     get size() {
         return this.map.size;
     }
@@ -515,7 +529,7 @@ export class ItemStore {
     }
     /** 그 품목인 물품들 — 색인이 답한다(자리를 모를 때 쓴다). */
     ofGtin(gtin) {
-        const keys = this.byGtin.get(gtin);
+        const keys = this.byGtin.get(this.itemClass(gtin));
         if (!keys)
             return [];
         const out = [];
@@ -549,7 +563,7 @@ export class ItemStore {
         }
         /* 품목 색인도 같은 규율로 본다 — 어긋나면 자재가 있는데 없다고 판정된다. */
         for (const [key, it] of this.map) {
-            if (it.gtin && !this.byGtin.get(it.gtin)?.has(key))
+            if (it.gtin && !this.byGtin.get(this.itemClass(it.gtin))?.has(key))
                 drift.push(`${key} 이 품목 '${it.gtin}' 색인에 없다`);
         }
         for (const [g, keys] of this.byGtin) {
@@ -557,7 +571,7 @@ export class ItemStore {
                 const it = this.map.get(k);
                 if (!it)
                     drift.push(`${k} 이 지워졌는데 품목 '${g}' 색인에 남아 있다`);
-                else if (it.gtin !== g)
+                else if (this.itemClass(it.gtin ?? '') !== g)
                     drift.push(`${k} 은 품목 '${it.gtin}' 인데 '${g}' 색인에 있다`);
             }
         }
@@ -566,9 +580,10 @@ export class ItemStore {
     index(key, location, gtin) {
         this.indexLocation(key, location);
         if (gtin) {
-            const set = this.byGtin.get(gtin) ?? new Set();
+            const g = this.itemClass(gtin);
+            const set = this.byGtin.get(g) ?? new Set();
             set.add(key);
-            this.byGtin.set(gtin, set);
+            this.byGtin.set(g, set);
         }
     }
     indexLocation(key, location) {
@@ -579,12 +594,13 @@ export class ItemStore {
     unindex(key, location, gtin) {
         this.unindexLocation(key, location);
         if (gtin) {
-            const set = this.byGtin.get(gtin);
+            const g = this.itemClass(gtin);
+            const set = this.byGtin.get(g);
             if (!set)
                 return;
             set.delete(key);
             if (!set.size)
-                this.byGtin.delete(gtin);
+                this.byGtin.delete(g);
         }
     }
     unindexLocation(key, location) {

package/dist/kernel.js

@@ -11,7 +11,7 @@ import { FlowEngine, allocatedQty } from "./flow-engine.js";
 import { planMakeToOrder } from "./make-to-order.js";
 import { BIZSTEP, BTT, WMS_ORDER_KIND } from '@operato/ops-contract';
 import { DISP, ILMD_ATTR, aggregationEvent, objectEvent, transactionEvent } from '@operato/ops-contract';
-import { subLotIdOf, itemKeyOf } from '@operato/ops-contract';
+import { subLotIdOf, itemKeyOf, sameItemClass, lotClassOfItem } from '@operato/ops-contract';
 const TRAVEL_MS = 30_000;
 const SHELF_MS = 30 * 24 * 3_600_000; // 기본 유통기한(30일)
 const SHELF_JITTER_MS = 5 * 24 * 3_600_000; // 로트별 만료 편차(FEFO 가 FIFO 와 갈리게)
@@ -57,8 +57,30 @@ export class WmsKernel extends FlowEngine {
         /* 발주 문서 식별자 — 선언된 이름공간 아래(CBV §8.5.5) 또는 선언된 GDTI 문서 타입. */
         const po = this.requireBizTransactionId(`PO-${poSeq}`, 'purchaseorder');
         const eventTime = this.now();
-        const qtyList = [{ epcClass: gtin, quantity: qty }];
+        /*
+         * ── 도착은 로트를 든다 (2026-09-24, ADR-0076 ⑥ · ADR-0082 결정 2) ──────────
+         * 로트는 발주 하나에 하나다(`L-<발주 번호>`) — rng 를 더 쓰지 않으므로 같은 씨앗이면 같은 사건이다.
+         * 케이스의 클래스는 계약이 만든 로트 클래스이고(`lotClassOfItem` → `lotClassUri`), plant · warehouse 가 보내는
+         * 로트와 같은 글자다. 오더 줄은 품목을 묻고 재고는 로트를 들므로 맞춤은 `sameItemClass` 가 한다.
+         *
+         * 선언된 품목이 로트를 붙일 수 없는 모양이면(식별자가 아닌 낱말) 품목 클래스 그대로 싣는다 — 로트를
+         * 말하지 않을 뿐 거짓은 없다. 자리 수가 틀린 GTIN 은 시나리오 검사가 선언에서 거절한다.
+         */
+        const lot = `L-${poSeq}`;
+        const lotClass = lotClassOfItem(gtin, lot) ?? gtin;
+        const qtyList = [{ epcClass: lotClass, quantity: qty }];
         const poTxn = [{ type: BTT.po, bizTransaction: po }];
+        /*
+         * **입고 오더가 도착보다 먼저 선다**(ADR-0076 ⑥, 판정 2026-09-24 — 물음 2 의 A). 「무엇이 오기로 되어
+         * 있었나」가 저널에 먼저 있어야 미러도 같은 순서로 안다. 리드 타임은 쓰는 소비자가 생길 때 연다.
+         * 배차 · 흐름 지표는 받는 오더를 이미 뺀다(`isFlowOrder`).
+         */
+        const inbound = {
+            id: `inbound-${poSeq}`, kind: WMS_ORDER_KIND.inbound, status: 'created', requested: qty, fulfilled: 0, bizTransaction: po,
+            allocated: [], picked: [], shipmentEpc: null, lines: [{ gtin, requested: qty }]
+        };
+        this.orders.set(inbound.id, inbound);
+        this.emitOrder(inbound);
         // 로트 만료(FEFO 용, 결정적 — rng 무소비로 byte-identical 유지). 편차로 도착순≠만료순 → FEFO 가 유의미.
         const expiry = this.clockMs + SHELF_MS - (this.epcSeq % 5) * SHELF_JITTER_MS;
         /* 방출한 마스터데이터를 **상태에도 들고 있는다** — 자기가 선언한 것을 자기가 모르면, 미러는 알고
@@ -68,7 +90,7 @@ export class WmsKernel extends FlowEngine {
          * 들어온 시각을 재고가 들고 있는다 — 「먼저 들어온 것 먼저」를 할 수 있는 유일한 근거다.
          * 값은 **receiving 이 일어난 시각**이고(수집 시각이 아니다), 여기서는 그 둘이 같다.
          */
-        this.items.set(epc, { epc, gtin, qty, location: dock.id, disposition: DISP.in_progress, expiry, ilmd, receivedAtMs: this.nowMs() });
+        this.items.set(epc, { epc, gtin: lotClass, qty, location: dock.id, disposition: DISP.in_progress, expiry, ilmd, receivedAtMs: this.nowMs() });
         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 }));
@@ -79,6 +101,11 @@ export class WmsKernel extends FlowEngine {
             epcList: [epc], quantityList: qtyList, readPoint: dock.id, bizLocation: dock.id, bizTransactionList: poTxn,
             ilmd
         }));
+        /* 수령했으므로 입고 오더를 이행하고 닫는다 — 시뮬에서 입고 오더를 닫는 것은 커널이다(ADR-0076 ⑥). */
+        inbound.fulfilled = qty;
+        inbound.status = 'completed';
+        this.emitOrder(inbound);
+        /* 적치는 품목으로 판단한다(같은 품목을 모으는 정책) — 로트가 아니라 품목 클래스를 넘긴다. */
         const binId = this.policy.selectPlacement({ item: { epc, gtin, qty }, slots: this.slotViews('storage') });
         if (!binId)
             return; // 수용 불가 → 도크 대기
@@ -156,7 +183,7 @@ export class WmsKernel extends FlowEngine {
         const staging = this.builtInLocation('staging', 'picked pallets wait here before shipping');
         const chosenAll = [];
         for (const line of o.lines) {
-            const already = allocatedQty(o.allocated.filter(a => this.items.get(a.epc)?.gtin === line.gtin));
+            const already = allocatedQty(o.allocated.filter(a => sameItemClass(this.items.get(a.epc)?.gtin, line.gtin)));
             const need = line.requested - already;
             if (need <= 0)
                 continue;
@@ -171,7 +198,7 @@ export class WmsKernel extends FlowEngine {
              * 모두 표현할 수 있고, **단위를 정하는 것은 부르는 쪽**이다.
              */
             const available = [...this.items.values()]
-                .filter(i => i.gtin === line.gtin && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === 'storage')
+                .filter(i => sameItemClass(i.gtin, line.gtin) && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === 'storage')
                 .filter(i => this.usableLot(i))
                 .map(i => ({ epc: i.epc, location: i.location, qty: 1, expiry: i.expiry, ...(i.receivedAtMs !== undefined ? { receivedAtMs: i.receivedAtMs } : {}) }));
             const chosen = this.policy.selectStock({ gtin: line.gtin, qty: need, available });
@@ -264,7 +291,7 @@ export class WmsKernel extends FlowEngine {
         const locations = [...this.locations.values()].map(l => ({ id: l.id, type: l.type }));
         const ops = this.declaredOperations();
         for (const line of o.lines) {
-            const have = stock.filter(s => s.gtin === line.gtin && s.sellable && this.locations.get(s.location)?.type === 'storage')
+            const have = stock.filter(s => sameItemClass(s.gtin, line.gtin) && s.sellable && this.locations.get(s.location)?.type === 'storage')
                 .reduce((n, s) => n + s.qty, 0);
             const short = line.requested - have;
             if (short <= 0)
@@ -301,7 +328,7 @@ export class WmsKernel extends FlowEngine {
     }
     /** 부품을 작업대로 — 팔레트 이동이므로 피킹과 같은 기제다(부분 소비는 코어가 한다). */
     issueFeed(o, gtin, from, to, qty) {
-        const src = [...this.items.values()].find(i => i.gtin === gtin && i.location === from && i.disposition === DISP.sellable);
+        const src = [...this.items.values()].find(i => sameItemClass(i.gtin, gtin) && i.location === from && i.disposition === DISP.sellable);
         if (!src)
             return;
         /* 이송 중에 다른 오더가 같은 팔레트를 집지 않게 예약으로 바꾼다 — 코어의 자재 게이트는
@@ -389,7 +416,7 @@ export class WmsKernel extends FlowEngine {
         if (order.lines)
             for (const epc of order.picked) {
                 const g = this.items.get(epc)?.gtin;
-                const line = order.lines.find(l => l.gtin === g && l.requested > 0);
+                const line = order.lines.find(l => sameItemClass(l.gtin, g) && l.requested > 0);
                 if (line)
                     line.requested--;
             }

package/dist/make-to-order.js

@@ -21,6 +21,7 @@
  * 그래서 한 오더가 부르는 것은 세 걸음이다: **부품 이송 → 가공 → 되돌리기.** 이 모듈은 그중
  * "지금 무엇을 발행해야 하나" 를 답한다 — 이송이 아직 안 끝났으면 가공을 발행하지 않는다.
  */
+import { sameItemClass } from '@operato/ops-contract';
 /** 품목 → 그것을 산출하는 공정. 선언에서 파생한다(코드에 표를 두지 않는다). */
 export function producedByIndex(ops) {
     const idx = new Map();
@@ -113,6 +114,6 @@ export function planMakeToOrder(gtin, shortQty, ops, stock, locations) {
 /** 이 재고가 명세를 만족하나 — 품목 지목만 본다(등급 상속은 엔진이 안다). */
 function matches(s, req) {
     if (req.materialDefinition)
-        return s.gtin === req.materialDefinition;
+        return sameItemClass(s.gtin, req.materialDefinition);
     return false;
 }

package/dist/mes-kernel.js

@@ -8,7 +8,7 @@
  *  ③ 셋업/체인지오버 = work-center 가 제품 전환 시 셋업(changeoverKey=제품 gtin) → OEE Availability.
  *  ④ OEE = base 가 설비(설비)별 계측(가동/셋업/기아/품질). cut=cutter·weld=welder 이종 자원.
  */
-import { identityGroundingOf, procedureViolations, isRecipeExecutionBasis } from '@operato/ops-contract';
+import { identityGroundingOf, procedureViolations, isRecipeExecutionBasis, sameItemClass } from '@operato/ops-contract';
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine, allocatedEpcs, allocatedQty } from "./flow-engine.js";
 import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass, bizTransactionUri } from '@operato/ops-contract';
@@ -820,7 +820,7 @@ export class MesKernel extends FlowEngine {
             if (fromType) {
                 for (const n of locsOfType.get(fromType) ?? []) {
                     for (const i of this.items.at(n.id)) {
-                        if (i.gtin === g && i.disposition === DISP.sellable)
+                        if (sameItemClass(i.gtin, g) && i.disposition === DISP.sellable)
                             available.push({ epc: i.epc, location: i.location, qty: 1 });
                     }
                 }

package/dist-cjs/index.cjs

@@ -1629,12 +1629,19 @@ var ILMD_ATTR = {
   /** 로트·배치 번호(직렬 개체에 로트를 붙일 때). */
   lot: "cbvmda:lotNumber"
 };
+function lgtinClass(companyPrefix, itemRefAndIndicator, lot) {
+  return `urn:epc:class:lgtin:${companyPrefix}.${itemRefAndIndicator}.${encodeURIComponent(lot)}`;
+}
 function parseEpc(uri) {
   const raw = String(uri ?? "");
   if (/(?:\/obj\/|:obj:)[^/:\s]+$/.test(raw))
     return { scheme: "unknown", instance: true, uri: raw };
-  if (/(?:\/class\/|:class:)[^/:\s]+$/.test(raw))
-    return { scheme: "unknown", instance: false, uri: raw };
+  const inHouseClass = raw.match(/(?:\/class\/|:class:)([^/:\s]+)$/);
+  if (inHouseClass) {
+    const at = inHouseClass[1].indexOf(LOT_SEPARATOR);
+    const split = at > 0 ? decodedPair(inHouseClass[1].slice(0, at), inHouseClass[1].slice(at + LOT_SEPARATOR.length)) : void 0;
+    return split ? { scheme: "unknown", instance: false, item: split[0], lot: split[1], uri: raw } : { scheme: "unknown", instance: false, uri: raw };
+  }
   const cls = raw.match(/^urn:epc:class:lgtin:(.+)$/);
   if (cls) {
     const seg = cls[1].split(".");
@@ -1666,12 +1673,83 @@ function parseEpc(uri) {
   }
   return { scheme: "unknown", instance: false, uri: raw };
 }
+function decodedPair(item, lot) {
+  if (!lot)
+    return void 0;
+  try {
+    return [decodeURIComponent(item), decodeURIComponent(lot)];
+  } catch {
+    return void 0;
+  }
+}
+function itemClassOf(uri) {
+  if (!uri)
+    return void 0;
+  const parsed = parseEpc(uri);
+  if (parsed.scheme === "lgtin" && parsed.gtinKey)
+    return `urn:epc:idpat:sgtin:${parsed.gtinKey}.*`;
+  if (parsed.item !== void 0) {
+    const marker = /^(.*(?:\/class\/|:class:))[^/:\s]+$/.exec(parsed.uri);
+    if (marker)
+      return `${marker[1]}${parsed.item.replace(STRUCTURE_BREAKING, (c) => PERCENT_ENCODED[c])}`;
+  }
+  return parsed.uri;
+}
+function lotClassOfItem(itemClass, lot) {
+  if (!itemClass)
+    return void 0;
+  const idpat = /^urn:epc:idpat:sgtin:(\d+)\.(\d+)\.\*$/.exec(itemClass);
+  if (idpat)
+    return lotClassUri({ namespace: "", item: "", lot, gtin: `${idpat[1]}.${idpat[2]}` });
+  const parsed = parseEpc(itemClass);
+  if (parsed.instance || parsed.lot !== void 0)
+    return void 0;
+  const url = /^(https?:\/\/.+)\/class\/([^/:\s]+)$/.exec(itemClass);
+  const urn = /^(urn:.+):class:([^/:\s]+)$/.exec(itemClass);
+  const at = url ?? urn;
+  if (!at)
+    return void 0;
+  let item;
+  try {
+    item = decodeURIComponent(at[2]);
+  } catch {
+    return void 0;
+  }
+  return lotClassUri({ namespace: at[1], item, lot });
+}
+function sameItemClass(a, b) {
+  const x = itemClassOf(a);
+  return x !== void 0 && x === itemClassOf(b);
+}
 function gdtiUri(companyPrefix, docType, serial) {
   return `urn:epc:id:gdti:${companyPrefix}.${docType}.${serial}`;
 }
 function objectUri(namespace, objId) {
   return underNamespace(namespace, "obj", objId);
 }
+function lotClassUri(input) {
+  const item = String(input.item ?? "");
+  const lot = String(input.lot ?? "");
+  if (!lot)
+    throw new Error(`lotClassUri: \uB85C\uD2B8\uAC00 \uBE44\uC5C8\uB2E4 \u2014 \uB85C\uD2B8 \uC5C6\uB294 \uD488\uBAA9\uC740 classUri \uB85C \uBD80\uB978\uB2E4 (item=${item})`);
+  if (input.gtin !== void 0) {
+    const [prefix, ref, ...rest] = String(input.gtin).split(".");
+    if (!prefix || !ref || rest.length) {
+      throw new Error(`lotClassUri: gtin \uC740 'CompanyPrefix.ItemRefAndIndicator' \uC5EC\uC57C \uD55C\uB2E4: ${input.gtin}`);
+    }
+    const uri = lgtinClass(prefix, ref, lot);
+    const wrong = gs1KeyDigitViolation(uri);
+    if (wrong)
+      throw new Error(`lotClassUri: ${wrong}`);
+    return uri;
+  }
+  if (!item)
+    throw new Error(`lotClassUri: \uD488\uBC88\uC774 \uBE44\uC5C8\uB2E4 (lot=${lot})`);
+  const enc = (v) => v.replace(LOT_COMPONENT_BREAKING, (c) => PERCENT_ENCODED[c]);
+  return joinUnderNamespace(input.namespace, "class", `${enc(item)}${LOT_SEPARATOR}${enc(lot)}`);
+}
+var LOT_SEPARATOR = ";lot=";
+var LOT_COMPONENT_BREAKING = /[%/:?# ;]/g;
 function bizTransactionUri(namespace, transId) {
   return underNamespace(namespace, "bt", transId);
 }
@@ -1682,16 +1760,20 @@ var PERCENT_ENCODED = {
   ":": "%3A",
   "?": "%3F",
   "#": "%23",
-  " ": "%20"
+  " ": "%20",
+  /* 로트 클래스의 가르는 글자 — `lotClassUri` 만 쓴다(§`LOT_COMPONENT_BREAKING`). 표는 한 벌이다. */
+  ";": "%3B"
 };
 function underNamespace(namespace, marker, id) {
-  const ns = namespace?.trim();
-  if (!ns)
-    return void 0;
   const raw = String(id);
   if (!raw)
     return void 0;
-  const v = raw.replace(STRUCTURE_BREAKING, (c) => PERCENT_ENCODED[c]);
+  return joinUnderNamespace(namespace, marker, raw.replace(STRUCTURE_BREAKING, (c) => PERCENT_ENCODED[c]));
+}
+function joinUnderNamespace(namespace, marker, v) {
+  const ns = namespace?.trim();
+  if (!ns)
+    return void 0;
   if (/^https?:\/\/[^/\s]+/.test(ns))
     return `${ns.replace(/\/+$/, "")}/${marker}/${v}`;
   if (/^urn:epc(global)?:/.test(ns))
@@ -1802,6 +1884,30 @@ function transformationEvent(p) {
     e.bizTransactionList = p.bizTransactionList;
   return e;
 }
+var GS1_KEY_DIGITS = { sgtin: 13, lgtin: 13, sscc: 17, grai: 12, gdti: 12, sgln: 12 };
+function gs1KeyDigitViolation(uri) {
+  if (!uri)
+    return void 0;
+  const m = /^urn:epc:(?:id|idpat|class):([a-z]+):([^:]+)$/.exec(uri);
+  if (!m)
+    return void 0;
+  const want = GS1_KEY_DIGITS[m[1]];
+  if (!want)
+    return void 0;
+  const parts = m[2].split(".");
+  if (parts.length < 2)
+    return `${m[1]} \uD615\uC2DD \uC624\uB958: ${uri} \u2014 \uD68C\uC0AC \uD504\uB9AC\uD53D\uC2A4\uC640 \uCC38\uC870\uAC00 '.' \uB85C \uAC08\uB824\uC57C \uD55C\uB2E4`;
+  const [prefix, ref] = parts;
+  if (ref === "*")
+    return void 0;
+  if (!/^\d+$/.test(prefix) || !/^\d+$/.test(ref)) {
+    return `${m[1]} \uD615\uC2DD \uC624\uB958: ${uri} \u2014 \uD68C\uC0AC \uD504\uB9AC\uD53D\uC2A4\uC640 \uCC38\uC870\uB294 \uC22B\uC790\uB2E4`;
+  }
+  const got = prefix.length + ref.length;
+  if (got === want)
+    return void 0;
+  return `${m[1]} \uC790\uB9AC \uC218 \uC624\uB958: ${uri} \u2014 \uD68C\uC0AC \uD504\uB9AC\uD53D\uC2A4(${prefix.length}) + \uCC38\uC870(${ref.length}) = ${got} \uC774\uC9C0\uB9CC ${want} \uC5EC\uC57C \uD55C\uB2E4(GS1 TDS). \uD504\uB9AC\uD53D\uC2A4\uB97C \uBC14\uAFB8\uBA74 \uCC38\uC870 \uC790\uB9AC \uC218\uB97C \uD568\uAED8 \uB9DE\uCDB0\uC57C \uD55C\uB2E4.`;
+}
 
 // ../ops-contract/dist/iso-duration.js
 var RE = /^(-)?P(?:(\d+(?:\.\d+)?)W)?(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
@@ -4033,7 +4139,21 @@ var ItemStore = class _ItemStore {
    * 색인을 밖에 따로 두지 않는다 — 갱신하는 자리가 흩어지면 한 자리라도 빠뜨렸을 때 **재고가 조용히
    * 사라진다**(있는데 없다고 판정된다). 자리 색인과 같은 규율이다.
    */
+  /*
+   * 품목 색인 — 키는 **품목 클래스**다(`itemClassOf`). 재고는 로트 클래스를 들고 오더는 품목 클래스를 묻는다
+   * (ADR-0076 ⑥ · ADR-0082 결정 2). 로트 글자를 키로 쓰면 품목을 물어도 로트 재고가 안 나온다.
+   */
   byGtin = /* @__PURE__ */ new Map();
+  /** 같은 글자를 매번 뜯지 않는다 — 클래스 글자의 종류는 적고 물품은 많다. */
+  itemClassCache = /* @__PURE__ */ new Map();
+  itemClass(gtin) {
+    let c = this.itemClassCache.get(gtin);
+    if (c === void 0) {
+      c = itemClassOf(gtin) ?? gtin;
+      this.itemClassCache.set(gtin, c);
+    }
+    return c;
+  }
   get size() {
     return this.map.size;
   }
@@ -4123,7 +4243,7 @@ var ItemStore = class _ItemStore {
   }
   /** 그 품목인 물품들 — 색인이 답한다(자리를 모를 때 쓴다). */
   ofGtin(gtin) {
-    const keys = this.byGtin.get(gtin);
+    const keys = this.byGtin.get(this.itemClass(gtin));
     if (!keys) return [];
     const out = [];
     for (const k of keys) {
@@ -4151,13 +4271,13 @@ var ItemStore = class _ItemStore {
       }
     }
     for (const [key, it] of this.map) {
-      if (it.gtin && !this.byGtin.get(it.gtin)?.has(key)) drift.push(`${key} \uC774 \uD488\uBAA9 '${it.gtin}' \uC0C9\uC778\uC5D0 \uC5C6\uB2E4`);
+      if (it.gtin && !this.byGtin.get(this.itemClass(it.gtin))?.has(key)) drift.push(`${key} \uC774 \uD488\uBAA9 '${it.gtin}' \uC0C9\uC778\uC5D0 \uC5C6\uB2E4`);
     }
     for (const [g, keys] of this.byGtin) {
       for (const k of keys) {
         const it = this.map.get(k);
         if (!it) drift.push(`${k} \uC774 \uC9C0\uC6CC\uC84C\uB294\uB370 \uD488\uBAA9 '${g}' \uC0C9\uC778\uC5D0 \uB0A8\uC544 \uC788\uB2E4`);
-        else if (it.gtin !== g) drift.push(`${k} \uC740 \uD488\uBAA9 '${it.gtin}' \uC778\uB370 '${g}' \uC0C9\uC778\uC5D0 \uC788\uB2E4`);
+        else if (this.itemClass(it.gtin ?? "") !== g) drift.push(`${k} \uC740 \uD488\uBAA9 '${it.gtin}' \uC778\uB370 '${g}' \uC0C9\uC778\uC5D0 \uC788\uB2E4`);
       }
     }
     return drift;
@@ -4165,9 +4285,10 @@ var ItemStore = class _ItemStore {
   index(key, location, gtin) {
     this.indexLocation(key, location);
     if (gtin) {
-      const set = this.byGtin.get(gtin) ?? /* @__PURE__ */ new Set();
+      const g = this.itemClass(gtin);
+      const set = this.byGtin.get(g) ?? /* @__PURE__ */ new Set();
       set.add(key);
-      this.byGtin.set(gtin, set);
+      this.byGtin.set(g, set);
     }
   }
   indexLocation(key, location) {
@@ -4178,10 +4299,11 @@ var ItemStore = class _ItemStore {
   unindex(key, location, gtin) {
     this.unindexLocation(key, location);
     if (gtin) {
-      const set = this.byGtin.get(gtin);
+      const g = this.itemClass(gtin);
+      const set = this.byGtin.get(g);
       if (!set) return;
       set.delete(key);
-      if (!set.size) this.byGtin.delete(gtin);
+      if (!set.size) this.byGtin.delete(g);
     }
   }
   unindexLocation(key, location) {
@@ -7276,7 +7398,7 @@ function planMakeToOrder(gtin, shortQty, ops, stock, locations) {
   return { steps: [{ step: "process", operation: op.key, at: station.id }] };
 }
 function matches(s, req) {
-  if (req.materialDefinition) return s.gtin === req.materialDefinition;
+  if (req.materialDefinition) return sameItemClass(s.gtin, req.materialDefinition);
   return false;
 }
 
@@ -7323,11 +7445,27 @@ var WmsKernel = class extends FlowEngine {
     const poSeq = ++this.poSeq;
     const po = this.requireBizTransactionId(`PO-${poSeq}`, "purchaseorder");
     const eventTime = this.now();
-    const qtyList = [{ epcClass: gtin, quantity: qty }];
+    const lot = `L-${poSeq}`;
+    const lotClass = lotClassOfItem(gtin, lot) ?? gtin;
+    const qtyList = [{ epcClass: lotClass, quantity: qty }];
     const poTxn = [{ type: BTT.po, bizTransaction: po }];
+    const inbound = {
+      id: `inbound-${poSeq}`,
+      kind: WMS_ORDER_KIND.inbound,
+      status: "created",
+      requested: qty,
+      fulfilled: 0,
+      bizTransaction: po,
+      allocated: [],
+      picked: [],
+      shipmentEpc: null,
+      lines: [{ gtin, requested: qty }]
+    };
+    this.orders.set(inbound.id, inbound);
+    this.emitOrder(inbound);
     const expiry = this.clockMs + SHELF_MS - this.epcSeq % 5 * SHELF_JITTER_MS;
     const ilmd = { [ILMD_ATTR.expiry]: expiry };
-    this.items.set(epc, { epc, gtin, qty, location: dock.id, disposition: DISP.in_progress, expiry, ilmd, receivedAtMs: this.nowMs() });
+    this.items.set(epc, { epc, gtin: lotClass, qty, location: dock.id, disposition: DISP.in_progress, expiry, ilmd, receivedAtMs: this.nowMs() });
     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 }));
@@ -7343,6 +7481,9 @@ var WmsKernel = class extends FlowEngine {
       bizTransactionList: poTxn,
       ilmd
     }));
+    inbound.fulfilled = qty;
+    inbound.status = "completed";
+    this.emitOrder(inbound);
     const binId = this.policy.selectPlacement({ item: { epc, gtin, qty }, slots: this.slotViews("storage") });
     if (!binId) return;
     const id = `task-${++this.taskSeq}`;
@@ -7421,10 +7562,10 @@ var WmsKernel = class extends FlowEngine {
     const staging = this.builtInLocation("staging", "picked pallets wait here before shipping");
     const chosenAll = [];
     for (const line of o.lines) {
-      const already = allocatedQty(o.allocated.filter((a) => this.items.get(a.epc)?.gtin === line.gtin));
+      const already = allocatedQty(o.allocated.filter((a) => sameItemClass(this.items.get(a.epc)?.gtin, line.gtin)));
       const need = line.requested - already;
       if (need <= 0) continue;
-      const available = [...this.items.values()].filter((i) => i.gtin === line.gtin && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === "storage").filter((i) => this.usableLot(i)).map((i) => ({ epc: i.epc, location: i.location, qty: 1, expiry: i.expiry, ...i.receivedAtMs !== void 0 ? { receivedAtMs: i.receivedAtMs } : {} }));
+      const available = [...this.items.values()].filter((i) => sameItemClass(i.gtin, line.gtin) && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === "storage").filter((i) => this.usableLot(i)).map((i) => ({ epc: i.epc, location: i.location, qty: 1, expiry: i.expiry, ...i.receivedAtMs !== void 0 ? { receivedAtMs: i.receivedAtMs } : {} }));
       const chosen = this.policy.selectStock({ gtin: line.gtin, qty: need, available });
       for (const row of chosen) {
         o.allocated.push(row);
@@ -7488,7 +7629,7 @@ var WmsKernel = class extends FlowEngine {
     const locations = [...this.locations.values()].map((l) => ({ id: l.id, type: l.type }));
     const ops = this.declaredOperations();
     for (const line of o.lines) {
-      const have = stock.filter((s) => s.gtin === line.gtin && s.sellable && this.locations.get(s.location)?.type === "storage").reduce((n, s) => n + s.qty, 0);
+      const have = stock.filter((s) => sameItemClass(s.gtin, line.gtin) && s.sellable && this.locations.get(s.location)?.type === "storage").reduce((n, s) => n + s.qty, 0);
       const short = line.requested - have;
       if (short <= 0) continue;
       const plan = planMakeToOrder(line.gtin, short, ops, stock, locations);
@@ -7514,7 +7655,7 @@ var WmsKernel = class extends FlowEngine {
   }
   /** 부품을 작업대로 — 팔레트 이동이므로 피킹과 같은 기제다(부분 소비는 코어가 한다). */
   issueFeed(o, gtin, from, to, qty) {
-    const src = [...this.items.values()].find((i) => i.gtin === gtin && i.location === from && i.disposition === DISP.sellable);
+    const src = [...this.items.values()].find((i) => sameItemClass(i.gtin, gtin) && i.location === from && i.disposition === DISP.sellable);
     if (!src) return;
     src.disposition = DISP.reserved;
     this.pushTask(o, "feed", src.epc, from, to);
@@ -7592,7 +7733,7 @@ var WmsKernel = class extends FlowEngine {
     order.fulfilled += allocatedQty(order.allocated);
     if (order.lines) for (const epc of order.picked) {
       const g = this.items.get(epc)?.gtin;
-      const line = order.lines.find((l) => l.gtin === g && l.requested > 0);
+      const line = order.lines.find((l) => sameItemClass(l.gtin, g) && l.requested > 0);
       if (line) line.requested--;
     }
     for (const epc of order.picked) {
@@ -8433,7 +8574,7 @@ The steps are the source of truth for execution order; the hierarchy only names
       if (fromType) {
         for (const n of locsOfType.get(fromType) ?? []) {
           for (const i of this.items.at(n.id)) {
-            if (i.gtin === g && i.disposition === DISP.sellable) available.push({ epc: i.epc, location: i.location, qty: 1 });
+            if (sameItemClass(i.gtin, g) && i.disposition === DISP.sellable) available.push({ epc: i.epc, location: i.location, qty: 1 });
           }
         }
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.11.23",
+  "version": "0.11.24",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {
@@ -28,6 +28,6 @@
     "test": "node --test test/*.test.ts"
   },
   "dependencies": {
-    "@operato/ops-contract": "^0.9.33"
+    "@operato/ops-contract": "^0.9.35"
   }
 }