@operato/twin-kernel 0.7.38 → 0.7.40

package/dist/mes-kernel.js

@@ -1,6 +1,6 @@
 /*
  * MES Kernel — 제조: BOM 조립 + 다단계 라우팅(cut→weld) + 수율 + 셋업/체인지오버 + OEE. mechanics 는 FlowEngine base.
- * 부품 수령(다품종) → 작업지시(제품 2종 교대) → BOM 예약 → op1 cut(BOM 소비→WIP) → op2 weld(→완제품, 수율) → 저장.
+ * 부품 수령 → 작업지시(오더가 레시피를 든다) → 레시피 입력 확보 → 라우트 단계 진행 → 완제품(수율) → 저장.
  *
  * 도메인 깊이:
  *  ① BOM = 제품별 다품목 레시피(P1=2A+1B / P2=1A+2B — 상이 → 체인지오버 유발).
@@ -8,9 +8,10 @@
  *  ③ 셋업/체인지오버 = work-center 가 제품 전환 시 셋업(changeoverKey=제품 gtin) → OEE Availability.
  *  ④ OEE = base 가 설비(설비)별 계측(가동/셋업/기아/품질). cut=cutter·weld=welder 이종 자원.
  */
+import { identityGroundingOf } from "./contract.js";
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine } from "./flow-engine.js";
-import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass } from "./epcis.js";
+import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass, bizTransactionUri } from "./epcis.js";
 import { MES_BIZSTEP, BTT_PRODORDER, sgtinUri } from "./mes-profile.js";
 import { OP_PARAM } from "./domain-definition.js";
 /* 아래 셋은 **기본값**이다 — 명세(OperationDef.duration·parameters)가 있으면 그 값이 이긴다.
@@ -20,35 +21,7 @@ const DEFAULT_CYCLE_MS = 40_000;
 const DEFAULT_SETUP_MS = 15_000; // 체인지오버(제품 전환) 셋업 — OEE 가용성 손실
 // MES 도메인 커맨드(Tier 2, 무방언 — MES 어휘는 MES 커널 소유). handleCommand 로 처리.
 const MES_CMD = { changeover: 'mes.changeover' };
-const CP = '0614141';
-const WIP_ITEMREF = '066666';
-const WIP_GTIN = sgtinClass(CP, WIP_ITEMREF);
 const DEFAULT_YIELD = 0.8; // 양품률 기본값 — 현장 값은 OperationDef.parameters(OP_PARAM.yield) 로 온다
-// 부품(공용) — BOM 라인의 품목 클래스.
-const PART_A = { itemRef: '055551', gtin: sgtinClass(CP, '055551') };
-const PART_B = { itemRef: '055552', gtin: sgtinClass(CP, '055552') };
-// 제품 2종 — BOM 상이(제품 전환 시 cut/weld 체인지오버 셋업 발생).
-const PRODUCTS = [
-    { key: 'P1', ref: '077777', gtin: sgtinClass(CP, '077777'), bom: [{ part: PART_A, qty: 2 }, { part: PART_B, qty: 1 }] },
-    { key: 'P2', ref: '077778', gtin: sgtinClass(CP, '077778'), bom: [{ part: PART_A, qty: 1 }, { part: PART_B, qty: 2 }] }
-];
-/** 편의 — 시나리오 skuMix 로 쓸 부품 클래스. */
-export const MES_PART_GTINS = { partA: PART_A.gtin, partB: PART_B.gtin };
-/** 편의 — 완제품 클래스(제품 2종). */
-export const MES_PRODUCT_GTINS = { p1: PRODUCTS[0].gtin, p2: PRODUCTS[1].gtin };
-/** 레거시 MES 제품 목록(gtin+라벨) — mes.changeover 대상 제품 소싱용. 정의-구동 전환 시 recipe 출력으로 교체. */
-export const MES_PRODUCTS = PRODUCTS.map(p => ({ gtin: p.gtin, label: p.key }));
-/*
- * 트레일러 제조 라우트 — 순차 스테이션. 각 스테이션 완료가 다음 WIP 로 변환 + 다음 스테이션 태스크 발행.
- * 첫 스테이션(cut)은 BOM 부품 N→WIP, 중간은 WIP→WIP, 마지막(assembly)은 WIP→완성차(+수율/OEE).
- * 각 스테이션 = 이종 자원(resource) + 제품 전환 시 체인지오버 셋업.
- */
-const ROUTE = [
-    { kind: 'cut', locationType: 'cut-station', resource: 'cutter' },
-    { kind: 'weld', locationType: 'weld-station', resource: 'welder' },
-    { kind: 'paint', locationType: 'paint-booth', resource: 'painter' },
-    { kind: 'assembly', locationType: 'assembly-line', resource: 'assembler' }
-];
 /*
  * 정의-구동 모드 스펙은 **계약의 `ProductionSpec`** 이다(`contract.ts`).
  *
@@ -69,7 +42,6 @@ export class MesKernel extends FlowEngine {
         /* 정의가 있으면 그 안의 오퍼레이션 명세(소요·변동·모수)를 커널이 소비한다 — 없으면 기본값 경로. */
         if (productionSpec?.definition?.operations) {
             this.loadOperations(productionSpec.definition.operations);
-            this.assertNoDoubleProduction(productionSpec.definition.operations);
         }
         /*
          * **직렬 생산에는 바인딩이 있어야 한다.** 레시피 경로는 자재 키를 실제 GS1 식별자로 옮겨야
@@ -81,6 +53,10 @@ export class MesKernel extends FlowEngine {
             throw new Error('recipe-driven production needs `binding` and `companyPrefix` — the definition does not know GTINs, ' +
                 'so material keys cannot be resolved to GS1 identifiers');
         }
+        /* 겹침 검사는 **바인딩 검증 뒤**다 — 검사 자체가 자재 키를 식별자로 옮겨 견주기 때문이다. */
+        if (productionSpec?.definition?.operations) {
+            this.assertNoDoubleProduction(productionSpec.definition.operations);
+        }
     }
     /**
      * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
@@ -95,13 +71,78 @@ export class MesKernel extends FlowEngine {
      * 모든 계산이 거짓이 된다).
      */
     assertNoDoubleProduction(ops) {
-        const bad = ops.filter(o => (o.materialSpecification ?? []).some(m => m.use === 'produced')).map(o => o.key);
+        const finals = new Set((this.productionSpec?.definition?.recipes ?? []).flatMap(r => (r.outputs ?? []).map(o => this.classOf(o.material))));
+        const bad = ops
+            .filter(o => (o.materialSpecification ?? []).some(m => m.use === 'produced' && m.materialDefinition && finals.has(m.materialDefinition)))
+            .map(o => o.key);
         if (!bad.length)
             return;
-        throw new Error(`MES recipe already produces outputs — operations [${bad.join(', ')}] must not also declare materialSpecification use:'produced' ` +
-            '(that would create the same output twice). Consumption specs are fine; declare production in the recipe.');
+        throw new Error(`MES recipe already produces its output — operations [${bad.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.');
+    }
+    /**
+     * **레시피 모드에서는 MES 가 산출을 소유한다** — 코어는 비켜선다(§`producesOwnOutputs`).
+     *
+     * MES 의 산출은 개체 정체성(직렬번호) + 수율 + 오더 계보를 갖는다. 코어의 일반 산출은 비직렬
+     * 클래스+수량이라 그 셋을 표현하지 못한다. 둘이 같은 선언을 보고 각자 만들면 재고가 두 배가 된다.
+     *
+     * 레시피가 없으면(유통가공 등) 소유를 주장하지 않는다 — 그때는 코어의 산출이 맞다.
+     */
+    producesOwnOutputs(_opKey) {
+        return !!this.productionSpec?.definition?.recipes?.length;
+    }
+    /**
+     * 이 트윈의 정체성 근거 — 선언에서 파생한다(§`identityGroundingOf`).
+     *
+     * 선언이 근거를 정한다: 이름공간을 선언했으면 `declared`, 발급을 주장했으면 `issued`(주장이지 사실이
+     * 아니다). 선언이 없는 MES 트윈은 이제 만들 수 없으므로(`loadTwinModel` 이 거절한다) `fabricated` 로
+     * 판정될 일이 없다.
+     */
+    identityGroundingView() {
+        return identityGroundingOf(this.productionSpec);
+    }
+    /**
+     * 선언이 말하는 자리 타입이 **이 트윈에 있나** — 로드 시점에 한 번, 모아서 말한다 (2026-08-20).
+     *
+     * ── 왜 로드 시점인가 ───────────────────────────────────────────────────────
+     * 이것은 **선언의 흠**이다: 그 트윈의 생산 선언과 그 트윈의 모델이 서로 어긋났다. 틱에서 발견하면
+     * 그 트윈은 「도는데 아무 일도 안 일어나는」 모습이 된다 — 실제로 `allocateDef` 가 첫 공정의 자리를
+     * 못 찾으면 조용히 `return` 했고, 오더는 영원히 배정되지 않은 채 화면에는 「running」이라 적혔다.
+     *
+     * ── 좁히지 않는다 ─────────────────────────────────────────────────────────
+     * 「이 트윈이 실제로 지나는 라우트만 본다」는 예외를 한 번 검토했다가 버렸다. 근거로 삼은 「여러
+     * 트윈이 한 선언을 공유한다」가 **이 코드에 없는 이야기**였다: 호스트는 트윈마다 자기 모델에서
+     * 선언을 만든다(`productionSpecOf(model)`). 없는 사정을 상상해 검사에 구멍을 내지 않는다.
+     *
+     * 모아서 한 번에 말한다 — 하나씩 실패하면 사람이 같은 기동을 열 번 반복한다.
+     */
+    loadTwinModel(def) {
+        super.loadTwinModel(def);
+        /*
+         * 선언이 없으면 이 커널은 무엇을 만들지 알 수 없다. 예전에는 내장 상수(부품·제품·라우트)로 동작했고
+         * 그 상수가 모델에 없는 품목을 만들어 냈다. 그 경로를 제거했으므로 선언은 이제 필수다.
+         */
+        if (!this.productionSpec) {
+            throw new Error('MES twin requires a production declaration (ProductionSpec): materials, routes and recipes. ' +
+                'The kernel no longer carries a built-in demo product — what is made is decided by the model.');
+        }
+        const have = new Set([...this.locations.values()].map(l => l.type));
+        const missing = [];
+        for (const m of this.productionSpec.definition.materials ?? []) {
+            if (m.locationType && !have.has(m.locationType))
+                missing.push(`material '${m.key}' → '${m.locationType}'`);
+        }
+        for (const op of this.productionSpec.definition.operations ?? []) {
+            if (op.locationType && !have.has(op.locationType))
+                missing.push(`operation '${op.key}' → '${op.locationType}'`);
+        }
+        if (missing.length) {
+            throw new Error(`production declaration names location types this twin does not have: ${missing.join(' · ')}. ` +
+                `This twin has [${[...have].sort().join(', ')}]. Declare those locations in the model, or fix the declared ` +
+                'locationType — the kernel does not invent a place for material to sit.');
+        }
     }
-    productOf(gtin) { return PRODUCTS.find(p => p.gtin === gtin); }
     /**
      * MES 도메인 커맨드(Tier 2) — mes.changeover: 설비를 제품 gtin 으로 강제 전환.
      * 자동 체인지오버(task.changeoverKey 상이 시 셋업)의 수동 버전 — 운영자가 사전 전환(툴링 교체) 지시.
@@ -127,125 +168,54 @@ export class MesKernel extends FlowEngine {
         }
         return super.handleCommand(cmd);
     }
-    /** 부품 수령(다품종) — skuMix 의 gtin 으로 부품 종류 결정. */
+    /** 부품 수령 — 도착한 품목이 선언된 입력 자재면 그 자재가 선언한 자리에 생성. */
     onArrival(spec) {
-        if (this.productionSpec)
-            return this.onArrivalDef(spec);
-        const rawStore = this.locationByType('raw-store');
-        if (!rawStore)
-            return;
-        const gtin = this.pickGtin(spec.content.skuMix);
-        const part = [PART_A, PART_B].find(p => p.gtin === gtin);
-        if (!part)
-            return; // BOM 부품 아님
-        const epc = sgtinUri(CP, part.itemRef, ++this.epcSeq);
-        this.items.set(epc, { epc, gtin: part.gtin, qty: 1, location: rawStore.id, disposition: DISP.sellable });
-        rawStore.occupancy++;
-        this.emit(objectEvent({ eventTime: this.now(), action: 'ADD', bizStep: MES_BIZSTEP.receiving, disposition: DISP.sellable, epcList: [epc], quantityList: [{ epcClass: part.gtin, quantity: 1 }], readPoint: rawStore.id, bizLocation: rawStore.id }));
+        return this.onArrivalDef(spec);
     }
-    /** 작업지시 — 제품 2종 교대(체인지오버 유발). 제품 gtin 을 오더에 기록. */
+    /** 작업지시 — 오더가 자기 레시피를 든다(선언된 레시피 중에서). */
     onOrder(_spec) {
-        if (this.productionSpec)
-            return this.onOrderDef(_spec);
-        const product = PRODUCTS[this.orderSeq % PRODUCTS.length];
-        const id = `order-${++this.orderSeq}`;
-        const wo = gdtiUri(CP, '403', ++this.soSeq);
-        const order = { id, kind: 'workorder', status: 'created', gtin: product.gtin, requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [], ...this.promiseOf(_spec) };
-        this.orders.set(id, order);
-        this.emitOrder(order);
+        return this.onOrderDef(_spec);
     }
-    /** 할당 — 제품 BOM 각 라인의 부품 예약(하나라도 부족하면 대기) + 라우트 첫 스테이션(절단) 태스크. */
+    /** 할당 — 레시피 입력 전량 확보 후 첫 라우트 단계 태스크(부족하면 대기). */
     allocate(o) {
-        if (this.productionSpec)
-            return this.allocateDef(o);
-        const s0 = ROUTE[0];
-        const first = this.locationByType(s0.locationType);
-        const product = this.productOf(o.gtin);
-        if (!first || !product)
-            return;
-        // BOM 전 라인 확보 확인(부족하면 아무것도 예약 안 하고 대기)
-        const picks = [];
-        for (const line of product.bom) {
-            const available = [...this.items.values()]
-                .filter(i => i.gtin === line.part.gtin && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === 'raw-store')
-                .map(i => ({ epc: i.epc, location: i.location, qty: 1 }));
-            const chosen = this.policy.selectStock({ gtin: line.part.gtin, qty: line.qty, available });
-            if (chosen.length < line.qty)
-                return; // 부품 부족 → 대기
-            picks.push(...chosen);
-        }
-        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;
-        this.emitOrder(o);
-    }
-    /** 라우트 스테이션 태스크 발행(공통) — 제자리 가공(process), 이종 자원, 제품 전환 셋업. */
-    emitStation(o, stage, itemEpc, changeoverKey) {
-        const loc = this.locationByType(stage.locationType);
-        const task = { id: `task-${++this.taskSeq}`, kind: stage.kind, status: 'created', itemEpc, fromNode: loc.id, toNode: loc.id, resource: null, remainingMs: 0, durationMs: this.durationOf({ kind: stage.kind, fromNode: loc.id, toNode: loc.id, resourceKind: stage.resource }, DEFAULT_CYCLE_MS), orderId: o.id, resourceType: stage.resource, changeoverKey, setupMs: this.paramDuration(stage.kind, OP_PARAM.setupDuration) ?? DEFAULT_SETUP_MS, intent: 'process' };
-        this.tasks.set(task.id, task);
-        this.emitTask(task);
+        return this.allocateDef(o);
     }
-    /** op 완료 = 변환. 라우트 인덱스로 분기: 첫=BOM 소비→WIP, 중간=WIP→WIP, 마지막(조립)=WIP→완성차(수율→OEE 품질). */
     /**
      * MES 는 완료 시점에 **오더와 제품 정의**를 딛고 선다 — 둘 중 하나만 없어도 끝맺을 수 없다.
      *
      * 씨앗이 이미 이행된 오더를 주입하지 않으므로(남은 수량 0) 그 오더에 딸린 작업만 남을 수 있고,
-     * 관측이 오더 연결을 담지 못한 작업도 있다. 그때 예전에는 `order.gtin` 에서 던졌고 **그 예외
+     * 관측이 오더 연결을 담지 못한 작업도 있다. 그때 예전에는 `order.gtin` 에서 오류가 났고 **그 예외
      * 하나가 정확도 추세 전체를 죽였다.** 이제 코어가 이 답을 보고 그 작업만 접는다.
      */
     canComplete(t) {
-        if (this.productionSpec)
-            return !!(t.orderId && this.orders.get(t.orderId));
-        const order = t.orderId ? this.orders.get(t.orderId) : undefined;
-        return !!order && !!this.productOf(order.gtin);
+        return !!(t.orderId && this.orders.get(t.orderId));
     }
     onTaskComplete(t) {
-        if (this.productionSpec)
-            return this.onTaskCompleteDef(t);
-        /* 여기 도달했다면 `canComplete` 가 이미 확인했다 — 그래도 단정(`!`)은 쓰지 않는다. */
-        const order = this.orders.get(t.orderId);
-        const product = order && this.productOf(order.gtin);
-        if (!order || !product)
-            throw new Error(`task ${t.id}: order/product vanished between the core check and the domain hook`);
-        const i = ROUTE.findIndex(s => s.kind === t.kind);
-        const loc = this.locations.get(t.toNode);
-        const isLast = i === ROUTE.length - 1;
-        if (!isLast) {
-            // 중간 스테이션 — 입력(첫=BOM 전부 / 이후=이전 WIP) → 다음 WIP, 다음 스테이션 태스크.
-            const inputs = order.allocated.slice();
-            const wip = sgtinUri(CP, WIP_ITEMREF, ++this.wipSeq);
-            this.transform(inputs, [{ epc: wip, gtin: WIP_GTIN, qty: 1, location: loc.id, disposition: DISP.in_progress }], { bizStep: MES_BIZSTEP.producing, disposition: DISP.in_progress, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
-            order.allocated = [wip];
-            const next = ROUTE[i + 1];
-            this.emitStation(order, next, wip, product.gtin);
-            order.status = 'op-' + next.kind;
-            this.emitOrder(order);
-            return;
-        }
-        // 마지막 스테이션(조립) → 완성차 (transform 1→1, disposition 으로 수율 loss → OEE 품질)
-        const fgStore = this.locationByType('fg-store');
-        const wip = order.allocated[0];
-        const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
-        /* 판정을 **작업에 적는다** — 그 자리에서 적어야 저널에 종류와 함께 남고, 이력에서 수율을 배울 수 있다. */
-        t.outcome = good ? 'good' : 'scrap';
-        this.recordOutput(t.resource, good); // OEE 품질(마지막 자원별 양품/불량)
-        const disp = good ? DISP.sellable : DISP.non_sellable;
-        const outputEpc = sgtinUri(CP, product.ref, ++this.prodSeq);
-        this.transform([wip], [{ epc: outputEpc, gtin: product.gtin, qty: 1, location: fgStore.id, disposition: disp }], { bizStep: MES_BIZSTEP.producing, disposition: disp, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
-        this.emit(objectEvent({ eventTime: this.now(), action: 'OBSERVE', bizStep: MES_BIZSTEP.storing, disposition: disp, epcList: [outputEpc], quantityList: [{ epcClass: product.gtin, quantity: 1 }], readPoint: fgStore.id, bizLocation: fgStore.id }));
-        order.allocated = [];
-        order.fulfilled = 1;
-        order.status = good ? 'produced' : 'scrapped';
-        this.emitOrder(order);
+        return this.onTaskCompleteDef(t);
     }
     // ── 정의-구동 모드 (도메인 정의 데이터로 실행 — 레거시와 분리, 하드코딩 대체) ──
-    recipeDef() {
+    /** 선언된 레시피 전부 — 오더가 자기 것을 고르고, 수령이 전부의 소요를 본다. */
+    recipesDef() {
+        return this.productionSpec.definition.recipes ?? [];
+    }
+    /**
+     * 이 오더의 레시피 — **오더가 들면 그것, 없으면 선언 수준의 기본**(§`FlowOrder.recipeKey`).
+     *
+     * 오더가 든 키가 선언에 없으면 **말한다**: 조용히 첫 레시피로 떨어지면 그 오더는 다른 물건을 만들고,
+     * 그 뒤 계보·재고·수율이 전부 엉뚱한 품목에 붙는다.
+     */
+    recipeDef(order) {
         const d = this.productionSpec.definition;
-        return (this.productionSpec.recipeKey ? d.recipes?.find(r => r.key === this.productionSpec.recipeKey) : d.recipes?.[0]);
+        const key = order?.recipeKey ?? this.productionSpec.recipeKey;
+        if (key) {
+            const found = d.recipes?.find(r => r.key === key);
+            if (!found) {
+                throw new Error(`recipe '${key}' is not declared. Declared: [${(d.recipes ?? []).map(r => r.key).join(', ') || '(none)'}]. ` +
+                    `The kernel does not substitute another recipe — that would make this order produce a different item.`);
+            }
+            return found;
+        }
+        return d.recipes[0];
     }
     /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
     classOf(materialKey) {
@@ -254,61 +224,205 @@ export class MesKernel extends FlowEngine {
     serialOf(materialKey, serial) {
         return sgtinUri(this.productionSpec.companyPrefix, this.productionSpec.binding[materialKey], serial);
     }
+    /**
+     * 이 공정이 **만든다고 선언한 품목** — 표준 `OpMaterialSpecification` `MaterialUse='produced'`.
+     *
+     * ── 왜 이 함수가 생겼나 (2026-08-20) ──────────────────────────────────────
+     * 예전에는 라우트의 중간 단계마다 커널이 `sgtinUri(prefix, 'WIP', ++seq)` 로 **품목을 지어냈다.**
+     * 그러면 배합물·가열완료물·소분물이 전부 같은 상품코드가 된다 — 저널에 남는 것은 「무엇인지 아무도
+     * 답할 수 없는 물건」이고, 그것이 영구 기록이 된다. 게다가 그 조립은 `binding` 을 **건너뛴다**:
+     * 다른 모든 품목은 `classOf`/`serialOf` 로 인스턴스가 주입한 품번을 지나는데, `'WIP'` 만 커널이
+     * itemRef 자리에 리터럴을 넣었다.
+     *
+     * ── 규율 ──────────────────────────────────────────────────────────────────
+     * 만드는 것은 **선언이 정한다**. 선언이 없으면 만들지 않는다(§`produceMaterials` 와 같은 규율 —
+     * 「무엇을 만드는지 말하지 않으면 만들지 않는다」). 있으면 그 품목으로 만든다. 어느 쪽도 지어내지 않는다.
+     *
+     * 둘 이상을 선언하면 **거부한다**: 어느 것이 이 단계의 산출인지는 모델이 말할 일이고, 커널이 첫 줄을
+     * 고르면 나머지는 조용히 사라진다.
+     */
+    producedMaterialKeyOf(opKey) {
+        const made = (this.operationSpecs.get(opKey)?.materialSpecification ?? []).filter(m => m.use === 'produced');
+        if (!made.length)
+            return undefined;
+        if (made.length > 1) {
+            throw new Error(`operation '${opKey}' declares ${made.length} produced materials — the kernel does not choose one. ` +
+                `Declare exactly one 'produced' material for this step, or split the step.`);
+        }
+        const declared = made[0].materialDefinition;
+        if (!declared) {
+            /* 등급만으로는 품목이 정해지지 않는다 — 만들지 않는 것이 지어내는 것보다 낫다. */
+            return undefined;
+        }
+        return this.materialKeyOfClass(declared, opKey);
+    }
+    /**
+     * 표준 GTIN 클래스 → **모델의 자재 키.**
+     *
+     * 공정 명세는 표준 식별자(`MaterialDefinitionID` = GTIN idpat)로 품목을 가리키고, MES 프로파일의
+     * 나머지는 자재 키(`MaterialDef.key` + `binding`)로 가리킨다. **둘은 다른 층이고 `binding` 이 통로다.**
+     * 그래서 선언된 식별자가 이 트윈의 `binding` 을 지나 나오는 것인지 되짚어 확인한다.
+     *
+     * 없으면 **모델 위반이므로 멈춘다** — 커널이 바인딩 없는 품목의 정체성을 만들어 낼 자리가 없다.
+     */
+    materialKeyOfClass(gtinClass, opKey) {
+        const binding = this.productionSpec.binding;
+        const key = Object.keys(binding).find(k => this.classOf(k) === gtinClass);
+        if (!key) {
+            throw new Error(`operation '${opKey}' declares produced material '${gtinClass}', which no declared material binds to. ` +
+                `Known: ${Object.keys(binding).map(k => `${k}=${this.classOf(k)}`).join(', ') || '(none)'}. ` +
+                `Declare that material in the model with a binding — the kernel does not invent an identity for it.`);
+        }
+        return key;
+    }
+    /**
+     * 이 자재가 놓이는 **자리 타입** — 선언이 권위다(`MaterialDef.locationType`).
+     *
+     * 예전에는 이 자리에 `'raw-store'`·`'fg-store'` 가 박혀 있었다. 그래서 현장은 자기 창고를 그 이름으로
+     * **개명해야** 트윈이 굴러갔다 — 커널이 현장의 낱말을 정하는 셈이었다. 선언이 없으면 **지어내지 않고
+     * 말한다**: 예전 거동(조용한 return)에서는 아무도 왜 자재가 들어오지 않는지 알 수 없었다.
+     *
+     * 레거시(선언 없는 내장 프로파일) 경로는 이 함수를 쓰지 않는다 — 그쪽에는 대조할 선언이 없으므로
+     * 커널 어휘 자체가 계약이다.
+     */
+    locationTypeOfMaterial(materialKey) {
+        const type = this.productionSpec.definition.materials?.find(m => m.key === materialKey)?.locationType;
+        if (!type)
+            throw new Error(`material '${materialKey}': MaterialDef.locationType 미선언 — 자재가 놓이는 자리를 커널이 지어낼 수 없다`);
+        return type;
+    }
+    /** 그 자리 타입의 자리 — 이 트윈에 없으면 말한다(선언과 모델이 어긋난 사실이다). */
+    locationOfMaterial(materialKey) {
+        const type = this.locationTypeOfMaterial(materialKey);
+        const loc = this.locationByType(type);
+        if (!loc)
+            throw new Error(`material '${materialKey}': locationType '${type}' 인 자리가 이 트윈에 없다`);
+        return loc;
+    }
     /**
      * 라우트를 용량 계산에 알려 준다 — 수율을 거슬러 올릴 때 순서가 곧 계산이다.
      *
      * 순서를 모르면 선언 순서대로 세는데, 그러면 하류에서 잃는 몫이 엉뚱한 공정에 얹힌다(조용히
      * 틀린다). 생산 정의를 가진 커널만 이 답을 안다.
      */
+    /*
+     * ── 레시피가 여럿이면 「그 라우트」가 하나가 아니다 (2026-08-20) ────────────
+     * 용량은 트윈 수준의 질문이다(「이 공장이 하루 몇 대」). 레시피마다 라우트가 다르면 그 답이 제품
+     * 구성에 따라 달라지는데, **하나를 골라 답하면 능력 숫자가 조용히 거짓이 된다.** 그래서 갈릴 때는
+     * 답하지 않고(`undefined`) 서로 다르다는 사실을 `capacity()` 가 함께 낸다 — `mixedCalendars` 와 같은 규율.
+     */
     routeKeys() {
         if (!this.productionSpec)
             return undefined;
-        const d = this.productionSpec.definition;
-        return d.routes?.find(r => r.key === this.recipeDef().route)?.steps;
+        const routes = this.distinctRouteKeys();
+        if (routes.length !== 1)
+            return undefined;
+        return this.productionSpec.definition.routes?.find(r => r.key === routes[0])?.steps;
     }
-    /** recipe.route → 오퍼레이션 시퀀스 해소. */
-    routeOps() {
+    /** 선언된 레시피들이 쓰는 **서로 다른** 라우트 키들. 하나면 용량을 답할 수 있다. */
+    distinctRouteKeys() {
+        if (!this.productionSpec)
+            return [];
+        return [...new Set(this.recipesDef().map(r => r.route).filter((k) => !!k))];
+    }
+    /** recipe.route → 오퍼레이션 시퀀스 해소. 오더가 자기 레시피를 들면 그 라우트다. */
+    routeOps(order) {
         const d = this.productionSpec.definition;
-        const route = d.routes?.find(r => r.key === this.recipeDef().route);
+        const route = d.routes?.find(r => r.key === this.recipeDef(order).route);
         return (route?.steps ?? []).map(sk => d.operations?.find(o => o.key === sk)).filter((o) => !!o);
     }
-    /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 raw-store 에 생성. */
+    /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 **그 자재가 선언한 자리**에 생성. */
     onArrivalDef(spec) {
-        const rawStore = this.locationByType('raw-store');
-        if (!rawStore)
-            return;
         const gtin = this.pickGtin(spec.content.skuMix);
         /* 품목 구성이 비어 있으면 도착을 만들지 않는다 — 무엇이 왔는지 말할 수 없는 입고는 사실이 아니다. */
         if (!gtin)
             return;
-        const inputKey = this.recipeDef().inputs.map(i => i.material).find(k => this.classOf(k) === gtin);
+        /*
+         * **선언된 레시피 **전부**의 소요를 본다** — 하나만 보면 다른 레시피의 자재가 영원히 안 들어오고,
+         * 그 레시피의 오더는 이유 없이 대기한다(자재 부족은 조용하다).
+         */
+        const inputKey = this.recipesDef()
+            .flatMap(r => r.inputs.map(i => i.material))
+            .find(k => this.classOf(k) === gtin);
         if (!inputKey)
             return;
+        const store = this.locationOfMaterial(inputKey);
         const epc = this.serialOf(inputKey, ++this.epcSeq);
-        this.items.set(epc, { epc, gtin, qty: 1, location: rawStore.id, disposition: DISP.sellable });
-        rawStore.occupancy++;
-        this.emit(objectEvent({ eventTime: this.now(), action: 'ADD', bizStep: MES_BIZSTEP.receiving, disposition: DISP.sellable, epcList: [epc], quantityList: [{ epcClass: gtin, quantity: 1 }], readPoint: rawStore.id, bizLocation: rawStore.id }));
+        this.items.set(epc, { epc, gtin, qty: 1, location: store.id, disposition: DISP.sellable });
+        store.occupancy++;
+        this.emit(objectEvent({ eventTime: this.now(), action: 'ADD', bizStep: MES_BIZSTEP.receiving, disposition: DISP.sellable, epcList: [epc], quantityList: [{ epcClass: gtin, quantity: 1 }], readPoint: store.id, bizLocation: store.id }));
+    }
+    /**
+     * 정의 모드 작업지시 — 레시피 산출물 1개. **오더가 자기 레시피를 든다**(§`FlowOrder.recipeKey`).
+     *
+     * 선언 수준의 `recipeKey` 가 있으면 그 하나만 만든다(현장이 한 품목만 돌린다고 말한 것이다). 없으면
+     * 선언된 레시피를 **차례로** 돈다 — 그것이 제품 전환이고, 체인지오버 셋업은 `changeoverKey`(산출물
+     * 클래스)가 달라지는 것으로 자동으로 따라온다. 커널 상수 제품 목록이 필요했던 이유가 이것이었다.
+     *
+     * 차례는 `orderSeq` 로 정한다 — 난수를 쓰면 fork 예측이 결정적이지 않게 된다.
+     */
+    /**
+     * **작업지시의 거래 문서 식별자** — 선언이 정하고, 커널은 문서 타입을 정하지 않는다.
+     *
+     * ── 무엇이 틀렸나 (2026-08-21) ────────────────────────────────────────────
+     * 여기는 `gdtiUri(prefix, '403', seq)` 였다. GDTI 는 `회사 프리픽스 + 문서 타입 + 일련번호`이고
+     * **문서 타입은 GS1 이 공표하는 목록이 아니다** — 프리픽스를 배정받은 회사가 자기 번호 용량에서
+     * 정한다. 그런데 커널이 `'403'` 을 스스로 정해 저널에 영구히 기록했다. 회사의 배정 권한을 커널이
+     * 대신 행사한 것이고, 프리픽스 날조와 같은 종류다.
+     *
+     * ── 순서 ──────────────────────────────────────────────────────────────────
+     * ① 선언된 이름공간이 있으면 그 아래 `bt` 형태로 만든다(CBV §8.5.4·§8.5.5). **문서 타입이 필요
+     *    없는 길**이고, 회사가 도메인만 있으면 되므로 진입장벽이 가장 낮다.
+     * ② 없고 문서 타입을 선언했으면 GDTI 로 만든다(그 현장이 GDTI 를 쓰는 것이다).
+     * ③ 둘 다 없으면 **말한다.** 지어내면 그 값이 영구 기록이 되고, 어느 화면도 그것이 발명된
+     *    번호라고 말해 주지 않는다.
+     */
+    workOrderId(serial) {
+        const identity = this.productionSpec.identity;
+        for (const ns of identity?.namespaces ?? []) {
+            const uri = bizTransactionUri(ns, serial);
+            if (uri)
+                return uri;
+        }
+        const docType = identity?.documentTypes?.workorder;
+        if (docType)
+            return gdtiUri(this.productionSpec.companyPrefix, docType, serial);
+        throw new Error('work order needs an identifier the model declares: either `identity.namespaces` (CBV §8.5.4/§8.5.5 ' +
+            '`.../bt/<id>`) or `identity.documentTypes.workorder` (the GDTI document type this site assigns). ' +
+            'The kernel does not choose a document type — GS1 assigns the company prefix, the company assigns the type.');
     }
-    /** 정의 모드 작업지시 — 레시피 산출물 1개. */
     onOrderDef(_spec) {
-        const rc = this.recipeDef();
         const id = `order-${++this.orderSeq}`;
-        const wo = gdtiUri(this.productionSpec.companyPrefix, '403', ++this.soSeq);
-        const order = { id, kind: 'workorder', status: 'created', gtin: this.classOf(rc.outputs[0].material), requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [], ...this.promiseOf(_spec) };
+        const recipes = this.recipesDef();
+        const chosen = this.productionSpec.recipeKey ? undefined : recipes[(this.orderSeq - 1) % recipes.length];
+        const rc = this.recipeDef(chosen ? { recipeKey: chosen.key } : undefined);
+        const wo = this.workOrderId(++this.soSeq);
+        const order = { id, kind: 'workorder', status: 'created', ...(chosen ? { recipeKey: chosen.key } : {}), gtin: this.classOf(rc.outputs[0].material), requested: 1, fulfilled: 0, bizTransaction: wo, allocated: [], picked: [], ...this.promiseOf(_spec) };
         this.orders.set(id, order);
         this.emitOrder(order);
     }
     /** 정의 모드 할당 — 레시피 입력 BOM 전량 확보 후 첫 라우트 스텝 태스크. */
     allocateDef(o) {
-        const ops = this.routeOps();
-        if (!ops.length || !ops[0].locationType || !this.locationByType(ops[0].locationType))
+        const ops = this.routeOps(o);
+        /* 라우트가 비어 있으면 만들 것이 없다 — 선언이 그렇게 말한 것이다(사실대로 건너뛴다). */
+        if (!ops.length)
             return;
-        const rc = this.recipeDef();
+        /*
+         * 첫 공정이 자리를 말하지 않으면 **흠이다.** 예전에는 여기서 조용히 `return` 해서 오더가 영원히
+         * 배정되지 않았다. 자리의 존재 여부는 로드 시점이 이미 봤으므로, 여기 남는 것은 선언 자체가 빈 경우다.
+         */
+        const firstType = ops[0].locationType;
+        if (!firstType) {
+            throw new Error(`route step '${ops[0].key}' declares no locationType — the kernel cannot choose where work happens`);
+        }
+        const rc = this.recipeDef(o);
         const picks = [];
         for (const line of rc.inputs) {
             const g = this.classOf(line.material);
+            /* 자리 필터는 남는다 — 완제품도 `sellable` 이라, 반제품→완제품 체인에서 이것이 없으면 산출물을 자재로 집어먹는다. */
+            const fromType = this.locationTypeOfMaterial(line.material);
             const available = [...this.items.values()]
-                .filter(i => i.gtin === g && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === 'raw-store')
+                .filter(i => i.gtin === g && i.disposition === DISP.sellable && this.locations.get(i.location)?.type === fromType)
                 .map(i => ({ epc: i.epc, location: i.location, qty: 1 }));
             const chosen = this.policy.selectStock({ gtin: g, qty: line.qty, available });
             if (chosen.length < line.qty)
@@ -334,33 +448,82 @@ export class MesKernel extends FlowEngine {
         const order = this.orders.get(t.orderId);
         if (!order)
             throw new Error(`task ${t.id}: order vanished between the core check and the domain hook`);
-        const rc = this.recipeDef();
-        const ops = this.routeOps();
+        const rc = this.recipeDef(order);
+        const ops = this.routeOps(order);
         const i = ops.findIndex(s => s.key === t.kind);
         const loc = this.locations.get(t.toNode);
         const bizStep = ops[i]?.bizStep ?? MES_BIZSTEP.producing;
         const isLast = i === ops.length - 1;
         if (!isLast) {
-            const inputs = order.allocated.slice();
-            const wip = sgtinUri(this.productionSpec.companyPrefix, 'WIP', ++this.wipSeq);
-            const wipGtin = sgtinClass(this.productionSpec.companyPrefix, 'WIP');
-            this.transform(inputs, [{ epc: wip, gtin: wipGtin, qty: 1, location: loc.id, disposition: DISP.in_progress }], { bizStep, disposition: DISP.in_progress, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
-            order.allocated = [wip];
+            /*
+             * 이 단계가 **품목을 만든다고 선언했는지** 본다.
+             *
+             * 선언했으면 그 품목으로 변환한다(배합물·가열완료물처럼 이름과 코드를 가진 반제품). 선언하지
+             * 않았으면 **변환하지 않는다** — 확보분을 그대로 들고 다음 자리로 간다. 그 단계에서 무슨 일이
+             * 있었는지는 다음 자리의 이벤트가 말하고, `transformationId` 가 오더의 모든 단계를 잇는다.
+             *
+             * 예전에는 여기서 `'WIP'` 를 지어냈다 — 선언하지 않은 것을 만들었고, 그래서 모든 중간물이 같은
+             * 상품코드가 됐다. **만드는 것은 선언이 정한다.**
+             */
+            const producedKey = this.producedMaterialKeyOf(t.kind);
             const next = ops[i + 1];
-            this.emitStationDef(order, next, wip);
+            if (producedKey) {
+                const inputs = order.allocated.slice();
+                const made = this.serialOf(producedKey, ++this.wipSeq);
+                this.transform(inputs, [{ epc: made, gtin: this.classOf(producedKey), qty: 1, location: loc.id, disposition: DISP.in_progress }], { bizStep, disposition: DISP.in_progress, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
+                order.allocated = [made];
+            }
+            /* 다음 자리에 무엇을 들고 가는가 — 만든 것이 있으면 그것, 없으면 들고 있던 것. */
+            const carried = order.allocated[0];
+            if (!carried) {
+                throw new Error(`order ${order.id} at step '${t.kind}': nothing to carry to '${next.key}' — the order holds no allocated material ` +
+                    `and this step declares no produced material. Declare the step's input or its output in the model.`);
+            }
+            this.emitStationDef(order, next, carried);
             order.status = 'op-' + next.key;
             this.emitOrder(order);
             return;
         }
-        const fgStore = this.locationByType('fg-store');
-        const wip = order.allocated[0];
+        const fgStore = this.locationOfMaterial(rc.outputs[0].material);
+        /*
+         * **완제품은 확보분 전량을 소비한다** — 하나만 소비하면 계보가 거짓이 되고 나머지가 영구 잠긴다.
+         *
+         * ── 무엇이 틀렸나 (2026-08-20) ────────────────────────────────────────────
+         * 여기는 `order.allocated[0]` 하나만 변환 입력으로 썼다. 예전에는 그것이 정당했다: 첫 스테이션이
+         * **항상** 전량을 WIP 하나로 합쳤으므로(`inputs = allocated.slice()` → `allocated = [made]`)
+         * `[0]` 이 그 부품들의 계보를 대표했다.
+         *
+         * 중간 산출물을 선언하지 않으면 변환하지 않게 되면서 **합치는 자리가 사라졌다.** 그런데 마지막이
+         * 여전히 `[0]` 만 참조했다. 대가가 둘이었다:
+         *  ① **계보가 거짓** — 완제품의 입력이 1개로 기록되니 리콜 역추적이 나머지 자재를 못 찾는다.
+         *     식품이라면 회수 범위가 조용히 좁아진다.
+         *  ② **재고가 영구 잠김** — 남은 확보분이 `reserved` 로 남아 다시 확보되지 않는다. 자재가 계속
+         *     누락되다가 생산이 멈추고, 원인은 「자재 부족」으로 보인다.
+         *
+         * 중간 산출물을 선언한 경로에서는 `allocated` 가 이미 `[made]` 하나이므로 거동이 같다.
+         */
+        const consumed = order.allocated.slice();
+        if (!consumed.length) {
+            /*
+             * 씨앗이 이 오더의 확보분을 다 심지 못했으면(원본이 말한 물품이 스냅샷에 없었다) 이 오더는
+             * **완료할 수 없다.** 제품을 지어내면 계보가 거짓이 되고, 멈추면 원본의 빈틈 하나가 답 전체를
+             * 죽인다. 그래서 **막혔다고 말하고 넘어간다** — 그 사실은 `seedIncomplete` 로 이미 실려 있다.
+             */
+            if (order.seedIncomplete) {
+                order.status = 'blocked-seed-incomplete';
+                this.emitOrder(order);
+                return;
+            }
+            throw new Error(`order ${order.id} at final step '${t.kind}': nothing allocated to consume — the kernel does not make a ` +
+                `product out of nothing. Declare the recipe inputs, or the step's produced material.`);
+        }
         const good = this.rng() < (this.yieldOf(t.kind) ?? DEFAULT_YIELD);
         t.outcome = good ? 'good' : 'scrap'; // 같은 규율 — 판정은 일어난 자리에서 적는다
         this.recordOutput(t.resource, good);
         const disp = good ? DISP.sellable : DISP.non_sellable;
         const outEpc = this.serialOf(rc.outputs[0].material, ++this.prodSeq);
         const outGtin = this.classOf(rc.outputs[0].material);
-        this.transform([wip], [{ epc: outEpc, gtin: outGtin, qty: 1, location: fgStore.id, disposition: disp }], { bizStep, disposition: disp, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
+        this.transform(consumed, [{ epc: outEpc, gtin: outGtin, qty: 1, location: fgStore.id, disposition: disp }], { bizStep, disposition: disp, transformationId: order.bizTransaction, readPoint: loc.id, bizTransactionList: [{ type: BTT_PRODORDER, bizTransaction: order.bizTransaction }] });
         this.emit(objectEvent({ eventTime: this.now(), action: 'OBSERVE', bizStep: MES_BIZSTEP.storing, disposition: disp, epcList: [outEpc], quantityList: [{ epcClass: outGtin, quantity: 1 }], readPoint: fgStore.id, bizLocation: fgStore.id }));
         order.allocated = [];
         order.fulfilled = 1;