@operato/twin-kernel 0.7.47 → 0.7.48

package/dist/mes-kernel.js

@@ -75,6 +75,7 @@ export class MesKernel extends FlowEngine {
         if (productionSpec?.definition?.operations) {
             this.assertNoDoubleProduction(productionSpec.definition.operations);
         }
+        this.assertRecipeOperationTags();
     }
     /**
      * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
@@ -115,6 +116,55 @@ export class MesKernel extends FlowEngine {
             "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 bad = [];
+        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) : undefined;
+                if (!steps) {
+                    bad.push(`recipe '${rc.key}' tags inputs with an operation but declares no route — the tag has nothing to match`);
+                }
+                else {
+                    for (const line of tagged) {
+                        if (!steps.has(line.operation)) {
+                            bad.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)'}) — 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)) {
+                    bad.push(`recipe '${rc.key}' declares material '${line.material}' both with and without an operation tag — ` +
+                        'the untagged line is claimed at order start and the tagged one at its step, so it would be consumed twice');
+                }
+            }
+        }
+        if (bad.length)
+            throw new Error(bad.join('; '));
+    }
     /**
      * **레시피 모드에서는 MES 가 산출을 소유한다** — 코어는 비켜선다(§`producesOwnOutputs`).
      *
@@ -293,11 +343,85 @@ export class MesKernel 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) : undefined;
+        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`).
      *
@@ -418,6 +542,12 @@ export class MesKernel extends FlowEngine {
      * 레거시(선언 없는 내장 프로파일) 경로는 이 함수를 쓰지 않는다 — 그쪽에는 대조할 선언이 없으므로
      * 커널 어휘 자체가 계약이다.
      */
+    /** 자리를 선언하지 않아 입고를 만들지 못한 자재 — 같은 말을 틱마다 반복하지 않는다. */
+    arrivalsWithoutPlace = 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)
@@ -474,11 +604,27 @@ export class MesKernel extends FlowEngine {
          * **선언된 레시피 **전부**의 소요를 본다** — 하나만 보면 다른 레시피의 자재가 영원히 안 들어오고,
          * 그 레시피의 오더는 이유 없이 대기한다(자재 부족은 조용하다).
          */
-        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;
+        /*
+         * ── 자리를 선언하지 않은 자재는 **입고를 만들 수 없다** (2026-08-22) ───────
+         * 보관처 선언은 확보에서는 정책이지만(없으면 품목 색인으로 찾는다), 입고는 자재를 **내려놓을 곳**이
+         * 필요하다. 커널은 그 자리를 지어내지 않는다.
+         *
+         * 그래서 만들지 않는다 — 다만 **조용히 빠지지 않는다.** 한 번 알린다: 그러지 않으면 「자극은 도는데
+         * 그 자재만 영원히 안 들어온다」가 되고 화면에 이유가 없다. 미러에서는 문제가 아니다(재고를 원본이
+         * 말한다) — 이 경로는 시뮬레이션의 입고 생성이다.
+         */
+        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 — 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 });
@@ -570,18 +716,43 @@ export class MesKernel extends FlowEngine {
                 locsOfType.set(n.type, [n]);
         }
         for (const line of rc.inputs) {
+            /*
+             * **태그가 붙은 줄은 여기서 확보하지 않는다** (2026-08-22) — 그 공정에 이르렀을 때 확보한다
+             * (§`RecipePart.operation` · `recipeInputsAt`). 앞에서 전량 확보하면 뒤 공정의 자재 부족이 오더
+             * 착수 시점에 나타나거나(실제로는 나중 일) 그 사이 공정의 재공이 서지 않는다.
+             */
+            if (line.operation)
+                continue;
             const g = this.classOf(line.material);
-            /* 자리 필터는 남는다 — 완제품도 `sellable` 이라, 반제품→완제품 체인에서 이것이 없으면 산출물을 자재로 소비한다. */
-            const fromType = this.locationTypeOfMaterial(line.material);
             /*
+             * ── 보관처 선언은 **정책이고, 없어도 돈다** (2026-08-22) ───────────────────
+             * 예전에는 `MaterialDef.locationType` 을 반드시 선언해야 했다. 그런데 **재고로 위치를 말하는
+             * 시스템**에는 그 선언이 없다 — 자재에 고정된 보관처를 두지 않는 것이 WMS 계열의 정상이고,
+             * 표준도 위치를 정의(`MaterialDefinition`)가 아니라 로트(`MaterialLot`)에 둔다. 실측: 첫 실
+             * 연동에서 원자재 986건 중 보관처가 선언된 것이 36건이었고, 레시피 937/1,408 이 실리지 못했다.
+             *
+             * 선언이 있으면 그것을 **현장의 정책**으로 읽어 그 타입의 자리만 본다(지금 거동 그대로).
+             * 없으면 **재고가 있는 곳에서 찾는다** — 품목 색인이 답하므로 전 로케이션을 훑지 않는다.
+             *
+             * 산출물을 자재로 먹지 않는 것은 **자리가 아니라 처분**이 막는다: 방금 만든 것과 변환을 기다리는
+             * 것은 `in_progress` 이고, 여기서 보는 것은 `sellable` 뿐이다.
+             *
              * 후보를 배열로 모은다. 지연 순회(생성기)로 바꿔 보았으나 **더 느렸다** — 물품 16,000 규모에서
              * 1562ms → 2723ms 였다. 항목마다 생성기 규약을 지나는 비용이 배열을 만드는 비용보다 크다.
-             * 측정이 그렇게 답했으므로 배열을 유지한다(§StockRequest.available 은 지연도 받는다).
              */
+            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)
+            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 });
                 }
             }
@@ -666,7 +837,17 @@ export class MesKernel extends FlowEngine {
             this.emitOrder(order);
             return;
         }
-        const fgStore = this.locationOfMaterial(rc.outputs[0].material);
+        /*
+         * ── 산출물이 놓이는 자리 (2026-08-22) ─────────────────────────────────────
+         * 선언이 있으면 그것이 현장의 정책이다(완제품창고로 보낸다). **없으면 만들어진 자리에 그대로 둔다** —
+         * 그것이 지어낸 값이 아니라 사실이다: 그 물건은 방금 이 공정에서 생겼고, 변환의 `readPoint` 가 바로
+         * 이 자리다. 창고로 옮기는 것은 **다른 일**(이동)이고, 모델이 그것을 선언해야 일어난다.
+         *
+         * 예전에는 선언이 없으면 오류를 냈다. 그래서 보관처를 선언하지 않는 원본(재고로 위치를 말하는
+         * 시스템)은 레시피를 실을 수 없었다.
+         */
+        const declaredFg = this.declaredLocationTypeOfMaterial(rc.outputs[0].material);
+        const fgStore = declaredFg ? this.locationOfMaterial(rc.outputs[0].material) : loc;
         /*
          * **완제품은 확보분 전량을 소비한다** — 하나만 소비하면 계보가 거짓이 되고 나머지가 영구 잠긴다.
          *