@operato/twin-kernel 0.7.47 → 0.7.49

package/dist-cjs/index.cjs

@@ -111,6 +111,7 @@ __export(index_exports, {
   gdtiUri: () => gdtiUri,
   generationFractionAt: () => generationFractionAt,
   graiUri: () => graiUri,
+  gs1KeyDigitViolation: () => gs1KeyDigitViolation,
   hierarchyOf: () => hierarchyOf,
   identityGroundingOf: () => identityGroundingOf,
   inWorkCalendar: () => inWorkCalendar,
@@ -721,7 +722,6 @@ function validateDomainDefinition(def) {
       if (!matKeys.has(p.material)) v.push(`recipe '${rc.key}' material '${p.material}' \uBBF8\uC815\uC758`);
       if (typeof p.qty !== "number" || p.qty <= 0) v.push(`recipe '${rc.key}' material '${p.material}' qty \uBD80\uC815`);
       const mat = matByKey.get(p.material);
-      if (mat && !mat.locationType) v.push(`recipe '${rc.key}' material '${p.material}' locationType \uBBF8\uC120\uC5B8`);
       if (mat?.locationType && !locationKeys2.has(mat.locationType)) v.push(`recipe '${rc.key}' material '${p.material}' locationType '${mat.locationType}' \uBBF8\uC815\uC758`);
     }
   }
@@ -1039,8 +1039,28 @@ var EPC_CLASS_PREFIXES = ["urn:epc:idpat:", "urn:epc:class:"];
 var DL_CANONICAL = "https://id.gs1.org/";
 var CBV_URL_CLASS = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)*class\/[^/\s]+$/;
 var CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
+var GS1_KEY_DIGITS = { sgtin: 13, sscc: 17, grai: 12, gdti: 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.`;
+}
 function classIdentifierViolation(epcClass) {
   if (!epcClass) return `quantity epcClass \uBD80\uC815: ${epcClass}`;
+  const digits = gs1KeyDigitViolation(epcClass);
+  if (digits) return `quantity epcClass \uBD80\uC815: ${digits}`;
   if (EPC_CLASS_PREFIXES.some((p) => epcClass.startsWith(p))) return void 0;
   if (epcClass.startsWith(DL_CANONICAL)) return void 0;
   if (CBV_URL_CLASS.test(epcClass) || CBV_URN_CLASS.test(epcClass)) return void 0;
@@ -1048,6 +1068,18 @@ function classIdentifierViolation(epcClass) {
 }
 function validateEpcisEvent(e) {
   const v = [];
+  for (const [field, list] of [
+    ["epcList", e.epcList],
+    ["childEPCs", e.childEPCs],
+    ["inputEPCList", e.inputEPCList],
+    ["outputEPCList", e.outputEPCList],
+    ["parentID", e.parentID ? [e.parentID] : void 0]
+  ]) {
+    for (const epc of list ?? []) {
+      const bad2 = gs1KeyDigitViolation(epc);
+      if (bad2) v.push(`${field}: ${bad2}`);
+    }
+  }
   if (e["@context"] !== EPCIS_CONTEXT) v.push("@context \uB204\uB77D/\uBD88\uC77C\uCE58");
   if (!["ObjectEvent", "AggregationEvent", "TransactionEvent", "TransformationEvent"].includes(e.type)) v.push(`\uC54C \uC218 \uC5C6\uB294 type: ${e.type}`);
   if (typeof e.eventTime !== "string" || !ISO_RE.test(e.eventTime)) v.push("eventTime ISO8601 \uC544\uB2D8");
@@ -2517,6 +2549,34 @@ var TWIN_AXES = [
     standardClass: { isa95: "SegmentResponse", epcis: "TransformationEvent" },
     systems: LOGISTICS
   },
+  /*
+   * ── 물품이 축이 아니었다 (2026-08-22) ──────────────────────────────────────
+   * 트윈에서 **수가 가장 많은 것**이 물품인데(실측: 엔티티 3,611 중 2,400 · hatio-us 는 2,805) 그것을
+   * 가리켜 걸어 들어갈 자리가 없었다. 지도와 집약 태그에는 이미 보이는데 「모델 살펴보기」에는 문이
+   * 없었다 — 사용자가 트윈에 가장 자주 묻는 것이 「내 물건이 어디 있나」이므로 그것은 접근 장벽이다.
+   *
+   * 성격은 `orders`·`tasks` 와 같다: 상태에 살고, 저널에 이력이 있고, 원본이 낸 것을 트윈이 관측한다.
+   * 그래서 같은 조합(`instance` · `state` · `historical`)이다.
+   *
+   * ── 표준 대응 ─────────────────────────────────────────────────────────────
+   * ISA-95 는 `MaterialLot` 이다 — 물품은 「무슨 품목인가」(정의)가 아니라 「그 품목의 이 덩어리」이고,
+   * 위치·수량·부분(`MaterialSubLot`)을 그 자리가 든다. EPCIS 는 `ObjectEvent` 다: 개체가 생기고
+   * 관측되고 사라지는 것을 그 사건이 말한다.
+   *
+   * ── 무엇이 이 항목을 가리키나 ─────────────────────────────────────────────
+   * `subLotId ?? epc` 다. 짐작에 맡기면 `gtin` 으로 떨어지고, 그러면 **같은 품목의 물품 전부가 한
+   * 식별자로 뭉친다** — 화면이 2,400개를 몇 개로 보인다.
+   */
+  {
+    axis: "items",
+    label: "twin.axis.items",
+    kind: "instance",
+    source: "state",
+    historical: true,
+    idField: ["subLotId", "epc"],
+    standardClass: { isa95: "MaterialLot", epcis: "ObjectEvent" },
+    systems: LOGISTICS
+  },
   /*
    * ── 에너지가 더하는 개념은 **하나**다 (2026-08-14, §10 6.5단계) ──────────────
    *
@@ -2591,6 +2651,24 @@ var TWIN_RELATIONS = [
   { from: "tasks", field: "toNode", target: { kind: "axis", axis: "locations" }, via: "twin.rel.at", optional: true },
   { from: "tasks", field: "resourceRef", target: { kind: "axis", axis: "equipment" }, via: "twin.rel.by", optional: true },
   { from: "tasks", field: "personnel[]", target: { kind: "axis", axis: "persons" }, via: "twin.rel.crew", optional: true },
+  /*
+   * 물품의 관계 (2026-08-22) — 없으면 축이 **걸어 들어갈 수 없는 목록**이 된다.
+   *
+   * `location` 은 필수다 — 물품은 언제나 어딘가에 있다(그것이 물품의 뜻이다). 나머지는 선택이다:
+   * 물류단위에 담기지 않은 물품, 자산에 실리지 않은 팔레트가 정상이다.
+   *
+   * `parent` 는 **물품 축을 자기 자신으로** 가리킨다(팔레트에 담긴 상자 — EPCIS `AggregationEvent`).
+   * `carriedBy` 는 다른 축이다 — 반복사용 자산(GRAI)이 물류단위를 실어 나른다(§`FlowItem.carriedBy`).
+   *
+   * 관계 이름은 **소문자 한 낱말**이다(`twin.rel.<name>`) — 기존 열여덟 개가 그 규율이고 시험이 지킨다.
+   *
+   * 품목(`gtin`)은 오더와 **같은 규율**이다: 자재 키가 아니라 GS1 품목 참조이므로 축을 직접 가리키지
+   * 않고 `external` 로 둔다. 축을 가리키게 적으면 없는 필드를 가리키는 선언이 된다.
+   */
+  { from: "items", field: "location", target: { kind: "axis", axis: "locations" }, via: "twin.rel.at" },
+  { from: "items", field: "parent", target: { kind: "axis", axis: "items" }, via: "twin.rel.parent", optional: true },
+  { from: "items", field: "carriedBy", target: { kind: "axis", axis: "assets" }, via: "twin.rel.asset", optional: true },
+  { from: "items", field: "gtin", target: { kind: "external", entity: "gs1.itemRef" }, via: "twin.rel.item", optional: true },
   /*
    * 자격을 검증한 시험 — **여덟 갈래.** 자원(개체)과 등급 양쪽이 가리킨다: 표준이 그 둘 모두에 이
    * 참조를 두었기 때문이다(개체는 "이 사람이 통과했다", 등급은 "이 자격은 이 시험을 요구한다").
@@ -3401,6 +3479,22 @@ function energyFieldsOf(m) {
 var ItemStore = class _ItemStore {
   map = /* @__PURE__ */ new Map();
   byLocation = /* @__PURE__ */ new Map();
+  /**
+   * 품목별 색인 — **보관처를 선언하지 않은 현장을 위해.**
+   *
+   * ── 왜 필요한가 (2026-08-22) ──────────────────────────────────────────────
+   * 자재를 확보할 때 예전에는 「그 자재의 보관처 타입」을 반드시 선언해야 했다(`MaterialDef.locationType`).
+   * 그런데 **재고로 위치를 말하는 시스템**에는 그 선언이 없다 — 자재에 고정된 보관처를 두지 않는 것이
+   * WMS 계열의 정상이다. 실측: 첫 실 연동에서 원자재 986건 중 보관처가 선언된 것이 **36건**이었고, 그
+   * 때문에 레시피 937/1,408 건이 아예 실리지 못했다.
+   *
+   * 선언이 없으면 **재고가 있는 곳에서 찾는다.** 그때 전 로케이션을 훑으면 규모 기준선(품목 100만)에서
+   * 감당되지 않으므로 품목 색인이 답한다.
+   *
+   * 색인을 밖에 따로 두지 않는다 — 갱신하는 자리가 흩어지면 한 자리라도 빠뜨렸을 때 **재고가 조용히
+   * 사라진다**(있는데 없다고 판정된다). 자리 색인과 같은 규율이다.
+   */
+  byGtin = /* @__PURE__ */ new Map();
   get size() {
     return this.map.size;
   }
@@ -3427,19 +3521,20 @@ var ItemStore = class _ItemStore {
   }
   set(key, item) {
     const prev = this.map.get(key);
-    if (prev) this.unindex(key, prev.location);
+    if (prev) this.unindex(key, prev.location, prev.gtin);
     this.map.set(key, item);
-    this.index(key, item.location);
+    this.index(key, item.location, item.gtin);
     return this;
   }
   delete(key) {
     const prev = this.map.get(key);
-    if (prev) this.unindex(key, prev.location);
+    if (prev) this.unindex(key, prev.location, prev.gtin);
     return this.map.delete(key);
   }
   clear() {
     this.map.clear();
     this.byLocation.clear();
+    this.byGtin.clear();
   }
   /**
    * 물품을 다른 자리로 옮긴다 — **색인이 함께 움직이는 유일한 통로.**
@@ -3451,9 +3546,9 @@ var ItemStore = class _ItemStore {
     const it = this.map.get(key);
     if (!it) throw new Error(`relocate: \uBB3C\uD488 '${key}' \uC774 \uC0C1\uD0DC\uC5D0 \uC5C6\uC2B5\uB2C8\uB2E4 \u2014 \uC5C6\uB294 \uAC83\uC744 \uC62E\uAE38 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4`);
     if (it.location !== to) {
-      this.unindex(key, it.location);
+      this.unindexLocation(key, it.location);
       it.location = to;
-      this.index(key, to);
+      this.indexLocation(key, to);
     }
     return it;
   }
@@ -3466,7 +3561,9 @@ var ItemStore = class _ItemStore {
    */
   clone() {
     const out = new _ItemStore();
-    for (const [k, it] of this.map) out.set(k, structuredClone(it));
+    for (const [k, it] of this.map) out.map.set(k, structuredClone(it));
+    for (const [loc, keys] of this.byLocation) out.byLocation.set(loc, new Set(keys));
+    for (const [g, keys] of this.byGtin) out.byGtin.set(g, new Set(keys));
     return out;
   }
   /*
@@ -3485,6 +3582,17 @@ var ItemStore = class _ItemStore {
     }
     return out;
   }
+  /** 그 품목인 물품들 — 색인이 답한다(자리를 모를 때 쓴다). */
+  ofGtin(gtin) {
+    const keys = this.byGtin.get(gtin);
+    if (!keys) return [];
+    const out = [];
+    for (const k of keys) {
+      const it = this.map.get(k);
+      if (it) out.push(it);
+    }
+    return out;
+  }
   /**
    * 색인이 맵과 어긋난 자리 — **시험이 쓰는 확인 통로**(전체를 다시 세므로 비싸다).
    *
@@ -3503,14 +3611,41 @@ var ItemStore = class _ItemStore {
         else if (it.location !== loc) drift.push(`${k} \uC740 '${it.location}' \uC5D0 \uC788\uB294\uB370 '${loc}' \uC0C9\uC778\uC5D0 \uC788\uB2E4`);
       }
     }
+    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`);
+    }
+    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`);
+      }
+    }
     return drift;
   }
-  index(key, location) {
+  index(key, location, gtin) {
+    this.indexLocation(key, location);
+    if (gtin) {
+      const set = this.byGtin.get(gtin) ?? /* @__PURE__ */ new Set();
+      set.add(key);
+      this.byGtin.set(gtin, set);
+    }
+  }
+  indexLocation(key, location) {
     const set = this.byLocation.get(location) ?? /* @__PURE__ */ new Set();
     set.add(key);
     this.byLocation.set(location, set);
   }
-  unindex(key, location) {
+  unindex(key, location, gtin) {
+    this.unindexLocation(key, location);
+    if (gtin) {
+      const set = this.byGtin.get(gtin);
+      if (!set) return;
+      set.delete(key);
+      if (!set.size) this.byGtin.delete(gtin);
+    }
+  }
+  unindexLocation(key, location) {
     const set = this.byLocation.get(location);
     if (!set) return;
     set.delete(key);
@@ -3599,6 +3734,14 @@ var FlowEngine = class {
    */
   seedDanglingRefs = 0;
   transformInputsAbsent = 0;
+  /**
+   * 일반 요구(공정)와 구체 요구(레시피 × 공정)가 **등급 ↔ 품목으로 교차**한 횟수.
+   *
+   * 같은 키끼리는 구체가 상회한다(§`mergeMaterialNeeds`). 교차는 뜻으로는 상회일 수 있으나 판정에 등급
+   * 소속이 필요하고, 잘못 겹치면 자재가 조용히 사라지거나 두 배가 된다. 그래서 **둘 다 요구하고 센다** —
+   * 이 값이 크면 그 숫자가 다음 작업을 정한다.
+   */
+  materialSpecCrossKeyOverlaps = 0;
   observedDirty = false;
   observeMode = false;
   /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
@@ -4238,9 +4381,10 @@ var FlowEngine = class {
       // 트윈의 "지금" — 관측 모드면 마지막으로 들은 시각(§nowMs)
       identityGrounding: this.identityGroundingView(),
       /* 원본과 어긋난 사실 — 0 이면 싣지 않는다(어긋난 적 없는 트윈에 빈 칸을 만들지 않는다). */
-      ...this.transformInputsAbsent || this.seedDanglingRefs ? { conformance: {
+      ...this.transformInputsAbsent || this.seedDanglingRefs || this.materialSpecCrossKeyOverlaps ? { conformance: {
         ...this.transformInputsAbsent ? { transformInputsAbsent: this.transformInputsAbsent } : {},
-        ...this.seedDanglingRefs ? { seedDanglingRefs: this.seedDanglingRefs } : {}
+        ...this.seedDanglingRefs ? { seedDanglingRefs: this.seedDanglingRefs } : {},
+        ...this.materialSpecCrossKeyOverlaps ? { materialSpecCrossKeyOverlaps: this.materialSpecCrossKeyOverlaps } : {}
       } } : {},
       /* 출처 표시 — 보드(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
        * 시뮬이 아무 표시도 안 하면 소비처가 두 스냅샷을 같은 규칙으로 읽지 못한다. */
@@ -5376,7 +5520,8 @@ var FlowEngine = class {
    * 작업이 같은 부품을 또 잡는다). 산출(`produced`)은 여기서 다루지 않는다(완료 시점의 일이다).
    */
   claimMaterials(t) {
-    const need = (this.operationSpecs.get(t.kind)?.materialSpecification ?? []).filter((m) => m.use === "consumed");
+    const general = (this.operationSpecs.get(t.kind)?.materialSpecification ?? []).filter((m) => m.use === "consumed");
+    const need = this.mergeMaterialNeeds(general, this.recipeInputsAt(t), t.kind);
     if (!need.length) return [];
     const at = t.toNode;
     const picked = [];
@@ -5387,6 +5532,7 @@ var FlowEngine = class {
       for (const it of this.items.at(at)) {
         if (remaining <= 0) break;
         if (!this.materialMatches(it, req)) continue;
+        if (it.disposition === DISP.in_progress) continue;
         const already = takenSoFar.get(it.epc) ?? 0;
         const avail = Math.max(0, (it.qty ?? 1) - already);
         if (avail <= 0) continue;
@@ -5486,7 +5632,7 @@ var FlowEngine = class {
   requireObjectId(id) {
     const uri = this.declaredObjectId(id);
     if (uri) return uri;
-    throw new Error(this.identityMissing("object"));
+    throw new Error(this.identityMissing("an object"));
   }
   /** 거래 문서 식별자 — 선언된 이름공간 또는 선언된 GDTI 문서 타입. 둘 다 없으면 오류를 낸다. */
   requireBizTransactionId(id, docKind) {
@@ -5496,11 +5642,17 @@ var FlowEngine = class {
     const docType = decl?.documentTypes?.[docKind];
     const prefix = decl?.companyPrefix;
     if (docType && prefix) return gdtiUri(prefix, docType, Number(id) || 0);
-    throw new Error(this.identityMissing(`business transaction '${docKind}'`));
+    throw new Error(this.identityMissing(`the business transaction '${docKind}'`));
   }
-  /** 같은 문장을 두 곳에 적지 않는다 — 고치는 자리가 하나여야 한다. */
+  /**
+   * 같은 문장을 두 곳에 적지 않는다 — 고치는 자리가 하나여야 한다.
+   *
+   * `what` 은 **관사까지 갖춘 구**를 받는다(`'an object'`). 예전에는 여기서 `a ${what}` 로 관사를
+   * 붙였고, 화면에 「cannot name a object」·「cannot name a business transaction 'purchase'」가 그대로
+   * 나왔다. 사람이 읽는 문장이므로 부르는 자리가 관사를 정한다.
+   */
   identityMissing(what) {
-    return `this twin has no identity declaration, so the kernel cannot name a ${what}. Declare \`identity.namespaces\` on the model (CBV 2.0 \xA78.2.4 \`.../obj/<id>\` \xB7 \xA78.5.5 \`.../bt/<id>\` \u2014 assigned by the owner of that internet domain), or \`identity.documentTypes\` with \`identity.companyPrefix\` for GS1 keys. The kernel does not invent a company prefix: GS1 assigns it to a company, and a value the kernel picked would sit in the journal forever with nothing saying it was invented.`;
+    return `this twin has no identity declaration, so the kernel cannot name ${what}. Declare \`identity.namespaces\` on the model (CBV 2.0 \xA78.2.4 \`.../obj/<id>\` \xB7 \xA78.5.5 \`.../bt/<id>\` \u2014 assigned by the owner of that internet domain), or \`identity.documentTypes\` with \`identity.companyPrefix\` for GS1 keys. The kernel does not invent a company prefix: GS1 assigns it to a company, and a value the kernel picked would sit in the journal forever with nothing saying it was invented.`;
   }
   /** 선언된 이름공간 아래의 **거래 문서 식별자**(발주·주문·어포인트먼트) — 없으면 답하지 않는다. */
   declaredBizTransactionId(id) {
@@ -5640,14 +5792,97 @@ var FlowEngine = class {
       this.recordMaterialActual(t, it.definitionId ?? it.gtin, "consumed", take, it.uom);
       whole.push(epc);
     }
-    if (whole.length) {
-      this.transform(whole, [], {
+    if (!whole.length) return;
+    if (this.adoptConsumed(t, whole)) {
+      this.observeDisposition(whole, DISP.in_progress, CBV_BIZSTEP.consuming);
+      return;
+    }
+    const at = this.items.get(whole[0])?.location ?? t.toNode;
+    for (const epc of whole) {
+      const it = this.items.get(epc);
+      if (!it) continue;
+      const n = this.locations.get(it.location);
+      if (n) n.occupancy--;
+      this.items.delete(epc);
+    }
+    this.emit(
+      objectEvent({
+        eventTime: this.now(),
+        action: "DELETE",
         bizStep: CBV_BIZSTEP.consuming,
         disposition: DISP.in_progress,
-        transformationId: t.id,
-        readPoint: this.items.get(whole[0])?.location ?? t.toNode
-      });
+        epcList: whole.slice(),
+        readPoint: at,
+        bizLocation: at
+      })
+    );
+  }
+  /**
+   * **소비된 자재를 도메인이 계보로 가져가는가** — 가져가면 코어는 없애지 않고 예약만 한다.
+   *
+   * 공정이 먹은 자재는 **그 단계가 만드는 것의 입력**이다. 그것을 별도 사건으로 없애면 제품의 계보에서
+   * 그 자재가 빠지고, 회수 범위를 되짚을 때 조용히 좁아진다 — 식품이라면 그것이 사고다.
+   *
+   * 기본은 「가져가지 않는다」다: 만드는 것이 없는 소비(소모품·유통가공)는 개체가 사라진 것이 맞다.
+   */
+  adoptConsumed(_t, _epcs) {
+    return false;
+  }
+  /** 이 트윈이 사는 동안 한 번만 알린 상회 — 같은 말을 틱마다 반복하지 않는다. */
+  announcedOverrides = /* @__PURE__ */ new Set();
+  /**
+   * **구체가 일반을 이긴다 — 다만 상회하는 단위는 자재 한 줄이다.**
+   *
+   * ── 왜 합집합이 아닌가 (2026-08-22) ───────────────────────────────────────
+   * 두 원천이 같은 자재를 말할 수 있다. 일반은 「이 공정이 늘 쓰는 것」이고(품목과 무관 — 포장 필름·
+   * 세척수), 구체는 「이 품목을 이 공정에서 만들 때」다. 같은 자재를 둘이 말하면 **구체가 현장의 사실**
+   * 이므로 이긴다. 합집합이면 요구가 더해져 재고가 거짓이 된다.
+   *
+   * ── 왜 명세 전체를 덮지 않는가 ────────────────────────────────────────────
+   * 덮으면 반대로 틀린다. 레시피가 「무말랭이 90kg」만 말했다고 그 공정의 세척수 50L 이 사라지면, 품목과
+   * 무관하게 늘 들어가는 것이 빠진다 — 그것이 일반 자리의 존재 이유다. 요구의 단위가 자재 한 줄이므로
+   * 상회도 그 단위에서 일어난다.
+   *
+   * ── 등급 ↔ 품목이 교차하면 둘 다 요구한다 ─────────────────────────────────
+   * 명세는 품목(`materialDefinition`)으로도 등급(`materialClass`)으로도 요구한다. 일반이 등급을, 구체가
+   * 품목을 말하고 그 품목이 그 등급에 속하면 뜻으로는 상회지만, 그 판정에는 등급 소속이 필요하고 잘못
+   * 겹치면 자재가 **조용히 사라지거나 두 배**가 된다. 그래서 **같은 키끼리만** 상회시키고, 교차하는
+   * 경우는 세어 남기고 둘 다 요구한다 — 조용히 한쪽을 버리는 것이 가장 나쁘다.
+   */
+  mergeMaterialNeeds(general, specific, opKey) {
+    if (!specific.length) return general;
+    if (!general.length) return specific;
+    const keyOf = (m) => m.materialDefinition ? `def:${m.materialDefinition}` : m.materialClass ? `cls:${m.materialClass}` : "";
+    const beaten = new Set(specific.map(keyOf).filter(Boolean));
+    const out = [...specific];
+    for (const g of general) {
+      const k = keyOf(g);
+      if (k && beaten.has(k)) {
+        const note = `${opKey}|${k}`;
+        if (!this.announcedOverrides.has(note)) {
+          this.announcedOverrides.add(note);
+          console.warn(
+            `[twin] operation '${opKey}': the recipe's own requirement for ${k} overrides this operation's general requirement (the specific declaration wins). The operation's other lines still apply.`
+          );
+        }
+        continue;
+      }
+      const crosses = g.materialClass ? specific.some((sp) => !!sp.materialDefinition) : g.materialDefinition ? specific.some((sp) => !!sp.materialClass) : false;
+      if (crosses) this.materialSpecCrossKeyOverlaps++;
+      out.push(g);
     }
+    return out;
+  }
+  /**
+   * **그 작업이 만드는 품목의, 그 공정 몫** — 품목 범위를 아는 것은 도메인이다.
+   *
+   * 코어는 레시피를 모른다(창고·야드에는 레시피가 없다). 그래서 시임으로 둔다 — MES 가 오더의
+   * 레시피에서 그 공정에 태그된 투입을 돌려준다(§`RecipePart.operation`).
+   *
+   * 기본은 빈 목록이다: 품목 범위가 없는 트윈에서는 공정 명세만이 요구다.
+   */
+  recipeInputsAt(_t) {
+    return [];
   }
   /**
    * 이 사람이 **속한 등급들이 요구하는 시험**을 만족하나.
@@ -6655,6 +6890,7 @@ var MesKernel = class extends FlowEngine {
     if (productionSpec?.definition?.operations) {
       this.assertNoDoubleProduction(productionSpec.definition.operations);
     }
+    this.assertRecipeOperationTags();
   }
   /**
    * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
@@ -6681,6 +6917,53 @@ var MesKernel = class extends FlowEngine {
       `MES recipe already produces its output \u2014 operations [${bad2.join(", ")}] must not also declare that same material as materialSpecification use:'produced' (that would create the same output twice). Declare intermediate outputs freely; the final output belongs to the recipe.`
     );
   }
+  /**
+   * **레시피 투입의 공정 태그를 기동에서 검사한다** — 어긋나면 그 자재는 영원히 확보되지 않는다.
+   *
+   * ── 두 가지를 본다 (2026-08-22) ───────────────────────────────────────────
+   * ① **태그의 공정이 그 레시피의 라우트 단계에 있어야 한다.** 없으면 그 투입은 확보되는 시점이 오지
+   *    않고, 오더는 영원히 그 단계에서 멈춘다 — 화면에는 이유가 없다. 실 마스터에서 BOM 이 말하는
+   *    공정과 품목의 경로가 어긋나는 일이 실제로 있다(BOM 은 「조림」인데 경로에 조림이 없는 경우).
+   * ② **한 레시피 안에서** 같은 자재가 태그 있는 줄과 없는 줄에 동시에 있으면 거부한다. 태그 없는 줄은
+   *    오더 착수에 확보되고 태그 붙은 줄은 그 공정에서 확보되므로, 그 자재를 **두 번 먹는다.**
+   *
+   *    레시피와 **공정 명세**가 같은 자재를 말하는 것은 거부하지 않는다 — 그것은 상회이고 정상이다
+   *    (구체가 일반을 이긴다, §`mergeMaterialNeeds`).
+   *
+   * 런타임에 조용히 어긋나는 것보다 기동이 실패하는 편이 낫다.
+   */
+  assertRecipeOperationTags() {
+    const def = this.productionSpec?.definition;
+    if (!def?.recipes?.length) return;
+    const stepsOf = new Map((def.routes ?? []).map((r) => [r.key, new Set(r.steps ?? [])]));
+    const bad2 = [];
+    for (const rc of def.recipes) {
+      const tagged = rc.inputs.filter((i) => i.operation);
+      if (tagged.length) {
+        const steps = rc.route ? stepsOf.get(rc.route) : void 0;
+        if (!steps) {
+          bad2.push(`recipe '${rc.key}' tags inputs with an operation but declares no route \u2014 the tag has nothing to match`);
+        } else {
+          for (const line of tagged) {
+            if (!steps.has(line.operation)) {
+              bad2.push(
+                `recipe '${rc.key}' input '${line.material}' is tagged for operation '${line.operation}', which is not a step of its route '${rc.route}' (steps: ${[...steps].join(" > ") || "(none)"}) \u2014 that material would never be claimed and the order would wait forever with no reason on screen`
+              );
+            }
+          }
+        }
+      }
+      const withTag = new Set(tagged.map((i) => i.material));
+      for (const line of rc.inputs) {
+        if (!line.operation && withTag.has(line.material)) {
+          bad2.push(
+            `recipe '${rc.key}' declares material '${line.material}' both with and without an operation tag \u2014 the untagged line is claimed at order start and the tagged one at its step, so it would be consumed twice`
+          );
+        }
+      }
+    }
+    if (bad2.length) throw new Error(bad2.join("; "));
+  }
   /**
    * **레시피 모드에서는 MES 가 산출을 소유한다** — 코어는 비켜선다(§`producesOwnOutputs`).
    *
@@ -6838,11 +7121,75 @@ var MesKernel = class extends FlowEngine {
   onTaskComplete(t) {
     return this.onTaskCompleteDef(t);
   }
+  /**
+   * **공정이 먹은 자재는 오더의 계보에 합류한다** — 그 단계가 만드는 것의 입력이 된다.
+   *
+   * ── 무엇이 빠져 있었나 (2026-08-22) ───────────────────────────────────────
+   * 공정별 자재(`OperationDef.materialSpecification` `use:'consumed'`, ISA-95
+   * `OperationsSegment.MaterialSpecification`)는 커널이 이미 확보하고 소비했다. 그런데 그 자재가
+   * **오더가 들고 있는 것에 들어가지 않았다.** 단계의 변환 입력은 `order.allocated` 뿐이라, 뒤 공정에서
+   * 먹은 자재가 제품의 계보에서 빠졌다 — 회수 범위를 되짚으면 그 자재가 조용히 없다.
+   *
+   * 레시피가 없는 모드(유통가공)는 산출을 코어가 만들므로 가져가지 않는다(§`producesOwnOutputs`).
+   */
+  /**
+   * **그 오더의 레시피에서, 이 공정에 태그된 투입** — 품목 범위를 아는 것은 여기다.
+   *
+   * 오더가 없는 작업에는 답하지 않는다(창고 입고 등 — 그때는 공정 명세만이 요구다).
+   */
+  recipeInputsAt(t) {
+    if (!t.orderId) return [];
+    const order = this.orders.get(t.orderId);
+    if (!order) return [];
+    if (!this.productionSpec?.definition?.recipes?.length) return [];
+    const rc = this.recipeDef(order);
+    const out = [];
+    for (const line of rc.inputs) {
+      if (line.operation !== t.kind) continue;
+      out.push({ use: "consumed", materialDefinition: this.classOf(line.material), quantity: line.qty });
+    }
+    return out;
+  }
+  adoptConsumed(t, epcs) {
+    if (!epcs.length) return false;
+    if (!this.producesOwnOutputs(t.kind)) return false;
+    const order = t.orderId ? this.orders.get(t.orderId) : void 0;
+    if (!order) return false;
+    for (const epc of epcs) order.allocated.push(epc);
+    return true;
+  }
   // ── 정의-구동 모드 (도메인 정의 데이터로 실행 — 레거시와 분리, 하드코딩 대체) ──
   /** 선언된 레시피 전부 — 오더가 자기 것을 고르고, 수령이 전부의 소요를 본다. */
   recipesDef() {
     return this.productionSpec.definition.recipes ?? [];
   }
+  /**
+   * **소비되는 자재 전부** — 선언이 그것을 말하는 자리는 둘이고, 둘 다 본다.
+   *
+   * ── 왜 둘인가 (2026-08-22) ────────────────────────────────────────────────
+   * ① `RecipeDef.inputs` — 레시피가 쓰는 자재. 오더가 시작될 때 확보한다.
+   * ② `OperationDef.materialSpecification` `use:'consumed'` — **그 공정에서만** 들어가는 자재
+   *    (ISA-95 `OperationsSegment.MaterialSpecification`). 같은 부품이라도 공정마다 소요가 다르고,
+   *    표준은 「몇 개」를 공정의 사실로 둔다.
+   *
+   * 예전에는 수령이 ①만 봤다. 그래서 ②에만 선언된 자재는 **한 번도 입고되지 않았고**, 그 공정은 영원히
+   * 기다렸다 — 화면에는 이유가 없었다. 첫 실 연동의 BOM 이 (품목, 공정) 단위라 이 자리가 바로 막혔다.
+   *
+   * `binding` 을 지나지 않는 이름은 여기서 세지 않는다 — 커널이 그 자재의 정체성을 만들 수 없으므로
+   * **입고를 만들 수 없다**(밖에서 들어온 물품은 `claimMaterials` 가 클래스 문자열로 알아본다).
+   */
+  consumedMaterialKeys() {
+    const keys = new Set(this.recipesDef().flatMap((r) => r.inputs.map((i) => i.material)));
+    const binding = this.productionSpec?.binding ?? {};
+    for (const op of this.productionSpec?.definition?.operations ?? []) {
+      for (const m of op.materialSpecification ?? []) {
+        if (m.use !== "consumed" || !m.materialDefinition) continue;
+        const k = Object.keys(binding).find((key) => this.classOf(key) === m.materialDefinition);
+        if (k) keys.add(k);
+      }
+    }
+    return [...keys];
+  }
   /**
    * 이 오더의 레시피 — **오더가 들면 그것, 없으면 선언 수준의 기본**(§`FlowOrder.recipeKey`).
    *
@@ -6961,6 +7308,12 @@ var MesKernel = class extends FlowEngine {
    * 레거시(선언 없는 내장 프로파일) 경로는 이 함수를 쓰지 않는다 — 그쪽에는 대조할 선언이 없으므로
    * 커널 어휘 자체가 계약이다.
    */
+  /** 자리를 선언하지 않아 입고를 만들지 못한 자재 — 같은 말을 틱마다 반복하지 않는다. */
+  arrivalsWithoutPlace = /* @__PURE__ */ new Set();
+  /** 그 자재가 선언한 보관처 타입 — **없으면 undefined**(정책이 없다는 사실이다). */
+  declaredLocationTypeOfMaterial(materialKey) {
+    return this.productionSpec.definition.materials?.find((m) => m.key === materialKey)?.locationType;
+  }
   locationTypeOfMaterial(materialKey) {
     const type = this.productionSpec.definition.materials?.find((m) => m.key === materialKey)?.locationType;
     if (!type) throw new Error(`material '${materialKey}': MaterialDef.locationType \uBBF8\uC120\uC5B8 \u2014 \uC790\uC7AC\uAC00 \uB193\uC774\uB294 \uC790\uB9AC\uB97C \uCEE4\uB110\uC774 \uC9C0\uC5B4\uB0BC \uC218 \uC5C6\uB2E4`);
@@ -7006,8 +7359,17 @@ var MesKernel = class extends FlowEngine {
   onArrivalDef(spec) {
     const gtin = this.pickGtin(spec.content.skuMix);
     if (!gtin) return;
-    const inputKey = this.recipesDef().flatMap((r) => r.inputs.map((i) => i.material)).find((k) => this.classOf(k) === gtin);
+    const inputKey = this.consumedMaterialKeys().find((k) => this.classOf(k) === gtin);
     if (!inputKey) return;
+    if (!this.declaredLocationTypeOfMaterial(inputKey)) {
+      if (!this.arrivalsWithoutPlace.has(inputKey)) {
+        this.arrivalsWithoutPlace.add(inputKey);
+        console.warn(
+          `[twin] material '${inputKey}' declares no locationType, so simulated arrivals cannot be created for it (the kernel does not invent a place for material to sit). Stock for it must come from the source, or declare \`MaterialDef.locationType\`. Allocation still works \u2014 it looks wherever the stock is.`
+        );
+      }
+      return;
+    }
     const store = this.locationOfMaterial(inputKey);
     const epc = this.serialOf(inputKey, ++this.epcSeq);
     this.items.set(epc, { epc, gtin, qty: 1, location: store.id, disposition: DISP.sellable });
@@ -7079,12 +7441,19 @@ var MesKernel = class extends FlowEngine {
       else locsOfType.set(n.type, [n]);
     }
     for (const line of rc.inputs) {
+      if (line.operation) continue;
       const g = this.classOf(line.material);
-      const fromType = this.locationTypeOfMaterial(line.material);
+      const fromType = this.declaredLocationTypeOfMaterial(line.material);
       const available = [];
-      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 (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 });
+          }
+        }
+      } else {
+        for (const i of this.items.ofGtin(g)) {
+          if (i.disposition === DISP.sellable) available.push({ epc: i.epc, location: i.location, qty: 1 });
         }
       }
       const chosen = this.policy.selectStock({ gtin: g, qty: line.qty, available });
@@ -7143,7 +7512,8 @@ var MesKernel = class extends FlowEngine {
       this.emitOrder(order);
       return;
     }
-    const fgStore = this.locationOfMaterial(rc.outputs[0].material);
+    const declaredFg = this.declaredLocationTypeOfMaterial(rc.outputs[0].material);
+    const fgStore = declaredFg ? this.locationOfMaterial(rc.outputs[0].material) : loc;
     const consumed = order.allocated.slice();
     if (!consumed.length) {
       if (order.seedIncomplete) {
@@ -8608,6 +8978,7 @@ function retiredVocabularyIn(line) {
   gdtiUri,
   generationFractionAt,
   graiUri,
+  gs1KeyDigitViolation,
   hierarchyOf,
   identityGroundingOf,
   inWorkCalendar,

package/package.json

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