@operato/twin-kernel 0.7.39 → 0.7.41

package/dist/flow-engine.js

@@ -9,7 +9,7 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf } from "./contract.js";
+import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP } from "./epcis.js";
 import { OP_PARAM } from "./domain-definition.js";
@@ -282,10 +282,151 @@ function energyFieldsOf(m) {
     }
     return out;
 }
+/**
+ * 물품 저장소 — **맵과 「자리별 색인」을 함께 든다.**
+ *
+ * ── 왜 클래스인가 (2026-08-21) ──────────────────────────────────────────────
+ * 자재를 확보할 때(`claimMaterials`) 「그 자리에 있는 물품」만 필요한데, 요구 한 줄마다 **물품 전체를
+ * 순회**하고 있었다. 규모 기준선이 그 값을 보인다: 물품이 15배 늘 때 주문당 비용이 3~4배가 된다
+ * (`test/order-scale-baseline.test.ts`). 목표 규모는 물품 10만이다.
+ *
+ * 색인을 따로 들면 갱신하는 자리가 흩어지고, 한 자리라도 빠뜨리면 **재고가 조용히 사라진다**(그 자리에
+ * 있는데 색인에 없으면 작업이 영원히 자재를 기다린다). 그래서 맵과 색인을 **한 객체**에 담아, 물품을
+ * 바꾸는 길이 이 클래스뿐이게 한다. 자리를 옮기는 것도 여기 통로가 있다(`relocate`) — 물품 객체의
+ * `location` 을 직접 고치면 색인이 어긋나므로, 그 규율은 시험이 지킨다.
+ *
+ * Map 과 같은 이름들을 그대로 낸다(`get`·`set`·`delete`·`has`·`values`·`clear`·순회) — 소비처를 고치지
+ * 않고 색인을 얻기 위해서다.
+ */
+export class ItemStore {
+    map = new Map();
+    byLocation = new Map();
+    get size() {
+        return this.map.size;
+    }
+    get(key) {
+        return this.map.get(key);
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    values() {
+        return this.map.values();
+    }
+    keys() {
+        return this.map.keys();
+    }
+    entries() {
+        return this.map.entries();
+    }
+    [Symbol.iterator]() {
+        return this.map[Symbol.iterator]();
+    }
+    forEach(fn) {
+        this.map.forEach((v, k) => fn(v, k));
+    }
+    set(key, item) {
+        const prev = this.map.get(key);
+        if (prev)
+            this.unindex(key, prev.location);
+        this.map.set(key, item);
+        this.index(key, item.location);
+        return this;
+    }
+    delete(key) {
+        const prev = this.map.get(key);
+        if (prev)
+            this.unindex(key, prev.location);
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+        this.byLocation.clear();
+    }
+    /**
+     * 물품을 다른 자리로 옮긴다 — **색인이 함께 움직이는 유일한 통로.**
+     *
+     * 없는 물품을 옮기라는 요청은 조용히 넘기지 않는다: 그 요청을 낸 쪽의 계산이 이미 어긋난 것이고,
+     * 지나가면 그 뒤의 이동·처분이 엉뚱한 자리에 적힌다.
+     */
+    relocate(key, to) {
+        const it = this.map.get(key);
+        if (!it)
+            throw new Error(`relocate: 물품 '${key}' 이 상태에 없습니다 — 없는 것을 옮길 수 없습니다`);
+        if (it.location !== to) {
+            this.unindex(key, it.location);
+            it.location = to;
+            this.index(key, to);
+        }
+        return it;
+    }
+    /**
+     * 사본 — **자기 복제 방법을 스스로 안다.**
+     *
+     * `fork()` 는 `Map` 만 알고 나머지는 `structuredClone` 으로 복제한다. 그 함수는 클래스의 메서드를
+     * 복제하지 못하므로(평범한 객체가 된다), 저장소가 복제를 맡지 않으면 사본의 물품 조회가 통째로
+     * 깨진다 — 실제로 그렇게 42건이 붉어졌다. 복제 방법을 아는 객체가 스스로 복제한다.
+     */
+    clone() {
+        const out = new ItemStore();
+        for (const [k, it] of this.map)
+            out.set(k, structuredClone(it));
+        return out;
+    }
+    /** 그 자리에 있는 물품들 — 색인이 답한다(전체 순회가 아니다). */
+    at(location) {
+        const keys = this.byLocation.get(location);
+        if (!keys)
+            return [];
+        const out = [];
+        for (const k of keys) {
+            const it = this.map.get(k);
+            if (it)
+                out.push(it);
+        }
+        return out;
+    }
+    /**
+     * 색인이 맵과 어긋난 자리 — **시험이 쓰는 확인 통로**(전체를 다시 세므로 비싸다).
+     *
+     * 어긋남은 조용한 결함이다(자재가 있는데 없다고 판정된다). 그래서 「어긋나지 않을 것이다」를 믿지 않고
+     * 시나리오를 돌린 뒤 이 값으로 확인한다.
+     */
+    indexDrift() {
+        const drift = [];
+        for (const [key, it] of this.map) {
+            if (!this.byLocation.get(it.location)?.has(key))
+                drift.push(`${key} 이 '${it.location}' 색인에 없다`);
+        }
+        for (const [loc, keys] of this.byLocation) {
+            for (const k of keys) {
+                const it = this.map.get(k);
+                if (!it)
+                    drift.push(`${k} 이 지워졌는데 '${loc}' 색인에 남아 있다`);
+                else if (it.location !== loc)
+                    drift.push(`${k} 은 '${it.location}' 에 있는데 '${loc}' 색인에 있다`);
+            }
+        }
+        return drift;
+    }
+    index(key, location) {
+        const set = this.byLocation.get(location) ?? new Set();
+        set.add(key);
+        this.byLocation.set(location, set);
+    }
+    unindex(key, location) {
+        const set = this.byLocation.get(location);
+        if (!set)
+            return;
+        set.delete(key);
+        if (!set.size)
+            this.byLocation.delete(location);
+    }
+}
 export class FlowEngine {
     tenantId;
     locations = new Map();
-    items = new Map();
+    items = new ItemStore();
     equipment = new Map();
     /** 등급 정의(표준 `<X>Class`) — 상속·유효기간 판정의 재료. 선언 안 하면 비어 있고, 소속 그대로 판정한다. */
     classDefs = {};
@@ -349,6 +490,21 @@ export class FlowEngine {
     /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
     observer;
     /** 관측분이 아직 커널 상태로 옮겨지지 않았다 — 스냅샷·fork 직전에 한 번만 옮긴다. */
+    /**
+     * **관측 모드에서 원본과 어긋난 횟수** — 받아들였지만 사실이 맞지 않았다.
+     *
+     * 미러는 원본을 비추는 쪽이라 어긋남을 만나도 멈추지 않는다(멈추면 원본의 한 건이 트윈 전체를
+     * 세운다). 그래서 **세어 둔다** — 세지 않으면 그 결함이 아무 데도 드러나지 않고, 화면은 어긋난 적이
+     * 없는 트윈과 구별되지 않는다.
+     */
+    /**
+     * **씨앗이 심지 못한 참조의 수** — 원본이 말했지만 그 물품이 스냅샷에 없었다.
+     *
+     * 0 이 아니면 이 트윈의 상태는 원본의 일부를 담지 못했다는 뜻이다. 예측·집계가 그 사실을 모르면
+     * 부족한 씨앗 위에서 낸 답을 완전한 답으로 읽는다.
+     */
+    seedDanglingRefs = 0;
+    transformInputsAbsent = 0;
     observedDirty = false;
     observeMode = false;
     /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
@@ -567,6 +723,25 @@ export class FlowEngine {
             if (e?.id && e.since)
                 this._attentionSince.set(e.id, e.since);
     }
+    /**
+     * 씨앗의 확보분 중 **이 트윈에 실제로 있는 것만** 남긴다 — 없는 것은 세고 버린다.
+     *
+     * 원본이 확보분을 말했는데 그 물품이 스냅샷에 없으면, 그 참조는 심는 순간 이미 사실이 아니다.
+     * 심어 두면 나중에 틱에서 드러나고(시뮬은 없는 것을 소비하지 않으므로 멈춘다) 그 판정이 예측
+     * 경로에서 터지면 원본의 빈틈 하나가 답 전체를 서버 오류로 죽인다.
+     *
+     * 그래서 심을 때 맞춘다. **없는 물품을 만들어 채우지 않는다** — 채우면 계보와 재고가 거짓 위에 선다.
+     * 대신 몇 건이 맞지 않았는지 남겨 씨앗이 불완전했다는 사실을 답에 실을 수 있게 한다.
+     */
+    resolvedAllocated(allocated) {
+        const all = allocated ?? [];
+        if (!all.length)
+            return { kept: [], dropped: 0 };
+        const kept = all.filter(epc => this.items.has(epc));
+        const dropped = all.length - kept.length;
+        this.seedDanglingRefs += dropped;
+        return { kept, dropped };
+    }
     hydrateObserved(snap, orders = []) {
         /* 확인 처리를 먼저 이어받는다 — 아래에서 상태를 주입하면 곧바로 주목 신호가 계산되므로, 늦게
          * 이어받으면 그 한 번은 확인 안 된 것으로 계산된다(화면이 잠깐 빨개진다). */
@@ -702,10 +877,24 @@ export class FlowEngine {
                    사라진다(같은 사실이 델타·스냅샷·이 변환 **세 길**을 지난다). */
                 ...(o.allocated?.length ? { allocated: o.allocated } : {}),
                 ...(o.gtin ? { gtin: o.gtin } : {}),
+                ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
                 ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
                 ...(o.dockDoor ? { dockDoor: o.dockDoor } : {}),
                 ...(o.windowStartMs !== undefined ? { windowStartMs: o.windowStartMs } : {})
             }));
+        /*
+         * ── 심을 때 참조를 맞춘다 (2026-08-21) ───────────────────────────────────
+         * 원본이 확보분을 말했는데 그 물품이 스냅샷에 없는 일이 실 연동에서 흔하다. 그 참조를 그대로
+         * 심으면 나중에 **틱에서** 드러난다 — 시뮬 규칙(없는 것을 소비하지 않는다)은 옳은데, 그 판정이
+         * 예측 경로에서 터지면 원본의 빈틈 하나가 정확도 추세 전체를 서버 오류로 죽인다(§`itemByRef` 에
+         * 같은 부류의 회귀가 적혀 있다).
+         *
+         * 그래서 판정을 **심는 시점**으로 옮긴다: 맞지 않는 참조는 심지 않고 **센다.** 그러면 시뮬의
+         * 멈추는 규칙은 그대로 남아 자기 결함을 여전히 드러내고, 원본의 빈틈은 예측을 죽이지 않으며
+         * 씨앗이 불완전했다는 사실이 답에 함께 실린다(§`StateSnapshot.conformance`).
+         *
+         * 지어내지 않는다 — 없는 물품을 만들어 채우면 그 뒤 계보와 재고가 전부 거짓 위에 선다.
+         */
         for (const o of observedOrders) {
             const lines = (o.lines ?? []).map(l => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter(l => l.requested > 0);
             /* **라인이 없는 오더를 조용히 빼지 않는다.** 예전에는 남은 양을 라인에서만 셌으므로, 품목 라인
@@ -716,6 +905,7 @@ export class FlowEngine {
                 : Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 0));
             if (remaining <= 0)
                 continue; // 이미 이행 완료 → 예측 대상 아님
+            const resolved = this.resolvedAllocated(o.allocated);
             this.orders.set(o.orderId, {
                 id: o.orderId, kind: o.kind, status: 'created', requested: remaining, fulfilled: 0,
                 /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
@@ -723,7 +913,11 @@ export class FlowEngine {
                    않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
                 /* 품목도 함께 — 씨앗이 흘리면 되살아난 오더가 무엇을 만드는지 모른다. */
                 ...(o.gtin ? { gtin: o.gtin } : {}),
-                bizTransaction: o.bizTransaction ?? '', allocated: (o.allocated ?? []).slice(), picked: [], shipmentEpc: null, lines,
+                /* 레시피도 함께 — 품목만 이어받으면 되살아난 오더가 「무엇으로」를 모르고, 그 오더의
+                   남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
+                ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+                bizTransaction: o.bizTransaction ?? '', allocated: resolved.kept, picked: [], shipmentEpc: null, lines,
+                ...(resolved.dropped ? { seedIncomplete: true } : {}),
                 /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
                    씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
                 ...(o.held ? { held: true } : {}),
@@ -1030,6 +1224,14 @@ export class FlowEngine {
             revision: this.revision,
             simClockMs: this.clockMs,
             nowTime: this.now(), // 트윈의 "지금" — 관측 모드면 마지막으로 들은 시각(§nowMs)
+            identityGrounding: this.identityGroundingView(),
+            /* 원본과 어긋난 사실 — 0 이면 싣지 않는다(어긋난 적 없는 트윈에 빈 칸을 만들지 않는다). */
+            ...(this.transformInputsAbsent || this.seedDanglingRefs
+                ? { conformance: {
+                        ...(this.transformInputsAbsent ? { transformInputsAbsent: this.transformInputsAbsent } : {}),
+                        ...(this.seedDanglingRefs ? { seedDanglingRefs: this.seedDanglingRefs } : {})
+                    } }
+                : {}),
             /* 출처 표시 — 보드(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
              * 시뮬이 아무 표시도 안 하면 소비처가 두 스냅샷을 같은 규칙으로 읽지 못한다. */
             locations: [...this.locations.values()].map(n => {
@@ -1119,6 +1321,10 @@ export class FlowEngine {
                  * 라인이 있는 오더는 `lines[].gtin` 이 품목을 말하고, 단일 품목 작업지시는 이 자리가 말한다.
                  */
                 ...(o.gtin ? { gtin: o.gtin } : {}),
+                /* **어느 레시피로 만드나** — 품목만으로는 「무엇으로」가 안 남는다(같은 품목의 대체 레시피가 있다). */
+                ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+                /* 씨앗이 다 심지 못했다는 사실 — 조용히 자르지 않는다(그 오더의 답은 부족한 씨앗 위에 있다). */
+                ...(o.seedIncomplete ? { seedIncomplete: true } : {}),
                 ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {}),
                 ...(o.priority !== undefined ? { priority: o.priority } : {}),
                 ...(o.startTime ? { startTime: o.startTime } : {}),
@@ -1241,10 +1447,16 @@ export class FlowEngine {
                 continue;
             const v = this[key];
             if (typeof v === 'function')
-                continue // rng — 아래서 state 만 복제
-                ;
+                continue; // rng — 아래서 state 만 복제
+            /* 복제 방법을 아는 객체는 스스로 복제한다(`ItemStore` 처럼 색인을 든 것) — `structuredClone` 은
+               클래스의 메서드를 복제하지 못하므로, 여기서 그것에 맡기면 사본이 조용히 반쪽이 된다. */
+            const cloneable = v;
             clone[key] =
-                v instanceof Map ? new Map([...v.entries()].map(([k, o]) => [k, structuredClone(o)])) : structuredClone(v);
+                v instanceof Map
+                    ? new Map([...v.entries()].map(([k, o]) => [k, structuredClone(o)]))
+                    : typeof cloneable?.clone === 'function'
+                        ? cloneable.clone()
+                        : structuredClone(v);
         }
         clone.rng.state = this.rng.state; // RNG 연속성 → 생성 포함 결정적 분기
         clone.durationEstimator = this.durationEstimator; // 무상태 시임 — 참조 공유(policy 와 동형)
@@ -1485,7 +1697,7 @@ export class FlowEngine {
      * 이긴다(원천 사본의 값이 낡았을 때 고칠 자리가 여기다). 무엇을 썼는지는 `specCoverage()` 가 밝힌다.
      *
      * ── 조용히 버리지 않는다 ────────────────────────────────────────────────────
-     * 읽을 수 없는 값은 던진다. 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 도는데,
+     * 읽을 수 없는 값은 오류를 낸다. 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 도는데,
      * 그 어긋남을 아무도 볼 수 없다(이 시스템에서 가장 비싼 종류의 침묵이다).
      */
     declareDurations(durations) {
@@ -1515,7 +1727,7 @@ export class FlowEngine {
      *  · **현장 선언이 원천 명세를 이긴다**(ADR-0034) — 원천 사본이 낡았을 때 고칠 자리가 그것뿐이다.
      *  · 명세 행이 없는 종류에도 얹힌다 — 행을 지어 만들면 지어낸 `intent` 가 능력 계산을 오염시킨다.
      *  · 무엇을 썼는지는 `specCoverage()` 의 `parameters` 가 그대로 밝힌다.
-     *  · 빈 이름·빈 값은 **던진다**: 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 돈다.
+     *  · 빈 이름·빈 값은 **오류를 낸다**: 받아 두고 무시하면 화면은 「넣었습니다」라고 말하고 시뮬은 상수로 돈다.
      */
     declareParameters(params) {
         for (const [kind, entries] of Object.entries(params ?? {})) {
@@ -1542,6 +1754,17 @@ export class FlowEngine {
     routeKeys() {
         return undefined;
     }
+    /**
+     * **이 트윈이 굴리는 서로 다른 라우트들** — 용량이 답할 수 있는지를 가른다.
+     *
+     * 하나면 `routeKeys()` 가 그 순서를 답한다. 둘 이상이면 「하루 몇 대」의 답이 **제품 구성에 따라
+     * 달라지므로**, 하나를 골라 답하지 않고 서로 다르다는 사실을 `capacity()` 가 함께 낸다. 조용히 고르면
+     * 능력 숫자가 거짓이 되고, 그 위에 선 모든 계획이 거짓 위에 선다.
+     */
+    distinctRouteKeys() {
+        const one = this.routeKeys();
+        return one ? ['(single)'] : [];
+    }
     /**
      * **이 공장이 하루 몇 대를 낼 수 있는가** — 실행해 보지 않고 답한다.
      *
@@ -1570,7 +1793,8 @@ export class FlowEngine {
             sampleWeekStartMs: opts.sampleWeekStartMs,
             unitsPerDay: opts.unitsPerDay
         });
-        return { ...analysis, mixedCalendars: calendars.size > 1 };
+        /* 라우트가 서로 다르면 그 사실을 알린다 — 「하루 몇 대」가 제품 구성에 따라 다르다는 뜻이다. */
+        return { ...analysis, mixedCalendars: calendars.size > 1, mixedRoutes: this.distinctRouteKeys().length > 1 };
     }
     /**
      * **생산 능력 보고서** — ISA-95 Part 4 `OperationsCapability`(§operations-capability).
@@ -1818,7 +2042,7 @@ export class FlowEngine {
      * `skuMix` 에서 weight 로 gtin 선택(rng) — 도착·오더 자극의 품목 결정.
      *
      * **빈 목록이면 고르지 않는다**(`undefined`). 예전에는 `mix[mix.length - 1].gtin` 으로 떨어져
-     * `mix[-1]` 이 undefined 가 되고 거기서 던졌다 — 그 예외가 서버까지 올라가 **정확도 추세 전체를
+     * `mix[-1]` 이 undefined 가 되고 거기서 오류가 났다 — 그 예외가 서버까지 올라가 **정확도 추세 전체를
      * 죽였다**(품목 구성을 선언하지 않은 자극 하나가 예측 전체를 껐다).
      *
      * 없는 품목을 지어내지 않는다: 무엇을 만들지 모르면 **만들지 않는 것**이 맞고, 부르는 쪽이
@@ -1850,10 +2074,34 @@ export class FlowEngine {
      * 도메인은 이 원시만 호출 — onTaskComplete 의 소비/생산/EPCIS 손코딩을 대체.
      */
     transform(inputs, outputs, opts) {
-        for (const epc of inputs) {
+        /*
+         * ── 없는 입력을 **조용히 지나가지 않는다** (2026-08-20) ────────────────────
+         *
+         * 예전에는 `if (!it) continue` 였다. 그런데 아래 이벤트는 `inputEPCList: inputs` 를 **그대로** 싣는다 —
+         * 즉 상태에서는 소비되지 않은 것이 기록에서는 소비된 것으로 남았다. 상태와 기록이 다른 말을 하면,
+         * 저널로 되돌린 트윈과 지금 도는 트윈이 서로 다른 사실을 말하게 된다.
+         *
+         * 시뮬레이션에서 이것은 **우리 계산의 결함**이다(우리가 없는 물건을 소비하라고 요구했다). 그래서
+         * 멈춘다. 미러는 처방이 다르다 — 원본이 진실이므로 받아들이고 어긋난 횟수를 남긴다.
+         *
+         * ── 미러를 멈추면 안 되는 이유 (2026-08-20, 시험으로 확인) ─────────────────
+         * 씨앗으로 세운 커널은 그대로 `tick` 한다(§`hydrateObserved`). 원본이 확보분 하나를 누락한
+         * 스냅샷을 주면 — 실 연동에서 흔한 빈틈이다 — 그 커널은 **첫 틱에 멈춘다.** 원본의 한 건이
+         * 라이브 트윈 전체를 세우는 것이고, 트윈은 원본을 비추는 쪽이므로 그 판정을 내릴 자리가 아니다.
+         * 그래서 관측 모드에서는 **받아들이고 센다.** 세지 않으면 원본 결함이 아무 데도 드러나지 않는다.
+         */
+        const absent = inputs.filter(epc => !this.items.get(epc));
+        if (absent.length && !this.observeMode) {
+            throw new Error(`transform: 입력 ${absent.length}건이 상태에 없습니다 (${absent.slice(0, 3).join(', ')}` +
+                `${absent.length > 3 ? ' …' : ''}) — 없는 것을 소비했다고 기록하지 않습니다. ` +
+                '이 트윈의 계산이 없는 물건을 요구했습니다.');
+        }
+        if (absent.length)
+            this.transformInputsAbsent += absent.length;
+        /* **실제로 소비한 것만** 이벤트에 싣는다 — 없던 것을 실으면 계보가 소비하지 않은 물건을 말한다. */
+        const consumed = absent.length ? inputs.filter(epc => this.items.has(epc)) : inputs;
+        for (const epc of consumed) {
             const it = this.items.get(epc);
-            if (!it)
-                continue;
             const n = this.locations.get(it.location);
             if (n)
                 n.occupancy--;
@@ -1867,7 +2115,7 @@ export class FlowEngine {
         }
         this.emit(transformationEvent({
             eventTime: this.now(), bizStep: opts.bizStep, disposition: opts.disposition,
-            inputEPCList: inputs.length ? inputs.slice() : undefined,
+            inputEPCList: consumed.length ? consumed.slice() : undefined,
             outputEPCList: outputs.length ? outputs.map(o => o.epc) : undefined,
             transformationID: opts.transformationId, readPoint: opts.readPoint, bizLocation: opts.bizLocation ?? opts.readPoint,
             bizTransactionList: opts.bizTransactionList
@@ -2077,6 +2325,9 @@ export class FlowEngine {
             /* 진행 중 할당과 거래번호를 함께 싣는다 — 이것이 없으면 웜스타트가 잃고, 되살아난 오더의
                계보가 입력 없이 나간다(무엇이 무엇으로 바뀌었나의 절반이 사라진다). */
             ...(o.gtin ? { gtin: o.gtin } : {}),
+            /* 어느 레시피로 만드는가 — 품목만 보내면 미러는 「무엇으로」를 알 수 없다(같은 품목에 대체
+               레시피가 있다). 시뮬만 아는 사실이 남으면 두 스냅샷을 같은 규칙으로 읽을 수 없다. */
+            ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
             ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
             ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
             /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
@@ -2241,11 +2492,10 @@ export class FlowEngine {
             let remaining = Math.max(0, req.quantity ?? 0);
             if (!remaining)
                 continue;
-            for (const it of this.items.values()) {
+            /* 그 자리에 있는 것만 본다 — **색인이 답한다**(예전에는 요구 한 줄마다 물품 전체를 순회했다). */
+            for (const it of this.items.at(at)) {
                 if (remaining <= 0)
                     break;
-                if (it.location !== at)
-                    continue; // 그 자리에 있는 것만 — 다른 창고의 부품은 지금 쓸 수 없다
                 if (!this.materialMatches(it, req))
                     continue;
                 const already = takenSoFar.get(it.epc) ?? 0;
@@ -2286,7 +2536,38 @@ export class FlowEngine {
      * 같은 품목이 그 자리에 이미 있으면 **수량을 더한다** — 새 줄을 만들면 같은 자리의 같은 로트가
      * 둘로 갈려 재고가 부푼다(§MaterialSubLot 에서 겪은 것과 반대 방향의 같은 오류).
      */
+    /**
+     * **이 공정의 산출을 도메인이 직접 만드는가** — 기본은 아니다(코어가 만든다).
+     *
+     * ── 왜 이 이음새가 있나 (2026-08-20) ──────────────────────────────────────
+     * 코어의 산출은 **비직렬 클래스+수량**이다(일련번호를 지어내지 않으므로). 그런데 어떤 도메인은
+     * 산출물에 **개체 정체성**이 필요하다: MES 의 레시피 생산은 개체마다 직렬번호를 갖고, 수율이
+     * 개체별로 양품/불량을 가르고, 계보(`TransformationEvent`)가 오더의 단계들을 잇는다.
+     *
+     * 그 도메인이 산출을 만들 때 코어도 같은 선언을 보고 만들면 **같은 산출이 두 벌** 된다 — 재고가
+     * 조용히 두 배가 되고, 그 위의 모든 계산이 거짓 위에 선다. 그래서 소유를 **한쪽으로 정한다.**
+     *
+     * 코어는 여기서 **도메인 명사를 하나도 알지 않는다**: 「누가 만드는가」만 묻는다. 무엇을 만드는지는
+     * 여전히 선언이 정하고, 코어는 그 선언을 읽을 뿐이다.
+     */
+    producesOwnOutputs(_opKey) {
+        return false;
+    }
+    /**
+     * **이 트윈의 정체성 근거** — 스냅샷에 실린다(§`StateSnapshot.identityGrounding`).
+     *
+     * 코어는 선언을 갖고 있지 않다(생산 선언은 도메인의 것이다). 그래서 기본은 **선언 없음**이고,
+     * 선언을 든 커널이 override 해서 자기 것을 답한다 — `routeKeys()` 와 같은 모양이다.
+     *
+     * 코어는 여기서 **정체성의 값을 정하지 않는다**: 「어디서 왔나」만 묻는다.
+     */
+    identityGroundingView() {
+        return identityGroundingOf(undefined);
+    }
     produceMaterials(t) {
+        /* 도메인이 소유를 주장하면 코어는 비켜선다 — 둘이 만들면 재고가 두 배가 된다. */
+        if (this.producesOwnOutputs(t.kind))
+            return;
         const made = (this.operationSpecs.get(t.kind)?.materialSpecification ?? []).filter(m => m.use === 'produced');
         if (!made.length)
             return;
@@ -2336,7 +2617,7 @@ export class FlowEngine {
      * 작업은 혼자 서지 못한다: 옮길 **물품**과, (있다면) 그것을 시킨 **오더** 위에 선다. 진행 중에
      * 둘 중 하나가 사라질 수 있다 — 물품은 포장·출하·소비로, 오더는 이미 이행돼 씨앗이 주입하지 않아서.
      *
-     * 그때 도메인 훅은 없는 것을 딛으려다 던진다(`order.gtin` · `item.location`). 그 예외 하나가
+     * 그때 도메인 훅은 없는 것을 딛으려다 오류를 낸다(`order.gtin` · `item.location`). 그 예외 하나가
      * **예측 전체를 죽였다** — 사용자에게는 기능이 통째로 사라진 것으로 보였다. 그래서 완료 **전에**
      * 여기서 묻고, 없으면 그 작업만 접는다.
      */
@@ -2353,7 +2634,7 @@ export class FlowEngine {
      * 이 도메인이 이 작업을 **끝맺을 수 있나** — 코어가 모르는 조건은 도메인이 답한다.
      *
      * 코어는 물품과 오더까지만 안다. 그런데 도메인은 더 필요할 수 있다 — MES 는 완료 시점에 **오더와
-     * 제품 정의**를 딛고 서고, 그 중 하나만 없어도 던진다. 코어가 그 조건을 추측하면 도메인마다 다른
+     * 제품 정의**를 딛고 서고, 그 중 하나만 없어도 오류를 낸다. 코어가 그 조건을 추측하면 도메인마다 다른
      * 가정을 코어에 박게 되므로(방언), **묻는다.**
      *
      * 기본은 `true` — 대부분의 작업은 코어가 확인한 것으로 충분하다.
@@ -2366,7 +2647,7 @@ export class FlowEngine {
      *
      * 물품 맵의 키는 `itemKeyOf`(직렬 물품은 `epc`, 로트의 부분은 `subLotId`)인데, 작업은 로트 식별자
      * (`itemEpc`)로 가리킨다. 비직렬 로트에서는 둘이 **다르다** — 그래서 그냥 `get` 하면 못 찾는다.
-     * 실제로 그 회귀를 냈다: 예측(씨앗) 경로에서 `item.location = …` 이 `undefined` 위에서 던져
+     * 실제로 그 회귀를 냈다: 예측(씨앗) 경로에서 `item.location = …` 이 `undefined` 위에서 오류를 내어
      * **정확도 추세 전체가 서버 오류로 죽었다.**
      *
      * **부분이 여럿이면 풀지 않는다** — 어느 부분을 가리키는지 알 수 없고, 아무거나 고르면 그 뒤
@@ -2376,6 +2657,18 @@ export class FlowEngine {
         const exact = this.items.get(ref);
         if (exact)
             return exact;
+        /*
+         * ── 여기부터는 **대체 경로**다 (2026-08-21에 규약으로 못 정한 뒤 남긴 자리) ──
+         *
+         * 규약은 하나다: 물품 맵의 키는 `itemKeyOf` 이고, **상태에 실리는 참조도 그 키**여야 한다.
+         * 그래야 이 함수가 `get` 한 번으로 끝난다. 이 아래가 실행되는 것은 참조가 키가 아닐 때이고,
+         * 정당한 경우는 하나다: **원본이 준 참조**(운영 사실 유입·씨앗)는 우리 키 규칙을 모른다.
+         *
+         * 전수 조회이므로 규모에서 비싸다(물품 10만이 목표 규모다). 그래서 **세어 둔다** — 이 수가 0 이
+         * 아니면 「참조가 키가 아닌 자리」가 아직 있다는 뜻이고, 인덱스를 얹을 근거는 그 수다.
+         * 재지 않으면 「대체 경로는 드물 것이다」라는 짐작 위에서 성능을 판단하게 된다.
+         */
+        this.refScans++;
         let hit;
         for (const it of this.items.values()) {
             if (it.epc !== ref)
@@ -2386,6 +2679,16 @@ export class FlowEngine {
         }
         return hit;
     }
+    /**
+     * 참조가 키가 아니어서 전수 조회로 찾은 횟수 — **성능 판단의 근거**다.
+     *
+     * 규약대로면 0 이다. 0 이 아닌 것은 결함이 아니라 사실이다(원본이 준 참조는 우리 키를 모른다).
+     * 다만 그 수가 규모와 함께 자라면 인덱스가 필요하다는 뜻이고, 그때 넣을 근거가 이 값이다.
+     */
+    refScans = 0;
+    refScanCount() {
+        return this.refScans;
+    }
     /**
      * 실제 자재 이동을 작업에 적어 둔다 — ISA-95 `JobResponse.MaterialActual`.
      * 같은 품목·같은 쓰임은 **한 줄로 합친다**(줄을 늘리면 실적을 세는 쪽이 중복을 걷어내야 한다).
@@ -2864,7 +3167,7 @@ export class FlowEngine {
              * **주체가 사라진 작업은 완료시키지 않고 접는다.**
              *
              * 진행 중에 그 물품이 없어질 수 있다(포장으로 합쳐지고, 출하로 나가고, 다른 공정이 소비한다).
-             * 그때 도메인 훅은 "없는 물품을 옮기려" 하다 던졌고, **그 예외 하나가 예측 전체를 죽였다** —
+             * 그때 도메인 훅은 "없는 물품을 옮기려" 하다 오류를 냈고, **그 예외 하나가 예측 전체를 죽였다** —
              * 사용자에게는 정확도 추세가 통째로 사라진 것으로 보였다.
              *
              * 조용히 넘기지도 않는다: 몇 건이 왜 접혔는지 센다. 그것이 잦다면 **상류에 진짜 문제가 있는 것**

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export * from './capacity.ts';
 export * from './operations-capability.ts';
 export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
-export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';
+export { MesKernel } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from './energy-ingest.ts';
 export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from './operational-ingest.ts';

package/dist/index.js

@@ -27,7 +27,7 @@ export * from "./capacity.js";
 export * from "./operations-capability.js";
 export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
-export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";
+export { MesKernel } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
 export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord } from "./energy-ingest.js";
 /* 운영 사실의 문 — 리듀서가 접는 여섯이 들어오는 자리(미러가 시뮬보다 가난하지 않게). */

package/dist/kernel.d.ts

@@ -5,6 +5,21 @@ import type { FlowOrder, FlowTask } from './flow-engine.ts';
 export declare class WmsKernel extends FlowEngine {
     private poSeq;
     constructor(tenantId: string, policy?: AllocationPolicy);
+    /**
+     * 내장 시나리오가 요구하는 자리 — **없으면 말한다.**
+     *
+     * ── 왜 (2026-08-20) ────────────────────────────────────────────────────────
+     * 이 커널은 입고·중간·보관 자리를 **자기 낱말로** 찾았고(`dock`·`staging`·`storage`), 없으면 조용히
+     * `return` 했다. 그래서 그 낱말을 쓰지 않는 현장의 트윈은 **아무 일도 일어나지 않는 공장**이 됐다 —
+     * 오류도 로그도 없이. 실제로 확인된 자리다: 첫 실 시스템(F&B)에는 `dock`·`gate`·`staging` 이 **한 건도
+     * 없다**(자리 타입이 자유 문자열이고, 입출고가 도크 단계 없이 자리에 직접 일어난다).
+     *
+     * 여기서 이름을 여는 것이 답이 아니다 — 이 경로는 부품·라우트가 내장 상수인 레거시 시나리오라,
+     * 이름만 열면 **지원하는 척**이 된다(MES 가 같은 이유로 같은 결론을 냈다). 답은 요구를 분명히 말하는
+     * 것이고, 오류를 내면 호스트가 그 트윈만 멈추고 이유를 등록부에 적는다(`tick-failed`) — 다른 트윈은 계속 돈다.
+     * 조용한 정지는 그 사실조차 남기지 않는다.
+     */
+    private builtInLocation;
     /** 입고 도착 — §4 라이프사이클: ASN(PO) → 팔레트 조립 → 수령 → putaway task. */
     protected onArrival(spec: GeneratorSpec): void;
     /**