@operato/twin-kernel 0.7.47 → 0.7.49

package/dist/contract.d.ts

@@ -1464,6 +1464,14 @@ export interface StateSnapshot {
         transformInputsAbsent?: number;
         /** 씨앗이 심지 못한 참조의 수 — 원본이 말했지만 그 물품이 스냅샷에 없었다. */
         seedDanglingRefs?: number;
+        /**
+         * 일반 요구(공정)와 구체 요구(레시피 × 공정)가 **등급 ↔ 품목으로 교차**한 횟수.
+         *
+         * 같은 키끼리는 구체가 상회한다. 교차는 뜻으로는 상회일 수 있으나 판정에 등급 소속이 필요하고,
+         * 잘못 겹치면 자재가 조용히 사라지거나 두 배가 된다. 그래서 **둘 다 요구하고 센다** — 이 값이
+         * 크면 그 숫자가 다음 작업을 정한다.
+         */
+        materialSpecCrossKeyOverlaps?: number;
     };
     locations: LocationState[];
     items: ItemState[];

package/dist/domain-catalog.d.ts

@@ -70,8 +70,14 @@ export interface TwinAxisInfo {
      * 이 칸이 없던 동안 소비처는 `id`·`key`·`gtin` 을 **짐작**했고, 그래서 화면이 실재하는 항목을
      * 「식별자 없음 — 참조할 수 없는 항목」으로 보였다. 값은 있는데 가리킬 수 없다고 말한 것이다.
      * 짐작을 없애고 선언이 답한다 — 축이 사는 자리(`path`)를 선언하는 것과 같은 이유다.
+     *
+     * ── 여럿을 받는다 (2026-08-22) ────────────────────────────────────────────
+     * 정체성이 **한 칸으로 정해지지 않는 축**이 있다. 물품이 그렇다: 직렬 물품은 `epc` 가 유일하지만,
+     * 비직렬 로트가 자리마다 나뉘면 개체를 구별하는 것은 `subLotId` 다(같은 로트의 두 부분은 같은 `epc`
+     * 를 갖는다 — §`ItemState.subLotId`). 계약이 그 규칙을 말할 수 없으면 소비처가 다시 짐작한다.
+     * 그래서 **차례**를 받는다: 앞에서 값이 있는 첫 칸이 이긴다.
      */
-    idField?: string;
+    idField?: string | string[];
     /**
      * 이 축을 **어디서 읽나.**
      *

package/dist/domain-catalog.js

@@ -97,6 +97,27 @@ export const TWIN_AXES = [
         standardClass: { isa95: 'OperationsRequest', epcis: 'TransactionEvent' }, systems: LOGISTICS },
     { axis: 'tasks', label: 'twin.axis.tasks', kind: 'instance', source: 'state', historical: true,
         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단계) ──────────────
      *
@@ -163,6 +184,24 @@ export const 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 },
     /*
      * 자격을 검증한 시험 — **여덟 갈래.** 자원(개체)과 등급 양쪽이 가리킨다: 표준이 그 둘 모두에 이
      * 참조를 두었기 때문이다(개체는 "이 사람이 통과했다", 등급은 "이 자격은 이 시험을 요구한다").

package/dist/domain-definition.d.ts

@@ -42,8 +42,17 @@ export interface MaterialDef {
      * (커널은 어느 제품에도 기대지 않는다 — 실 시스템은 이 결함이 실재한다는 **증인**이고, 커널의 모양을
      * 정하는 것은 표준과 원칙이다.)
      *
-     * 선택 필드로 둔 것은 자재를 선언만 하고 쓰지 않는 정의를 막지 않으려는 것이다. **레시피가 쓰는
-     * 자재는 이것을 반드시 선언해야 한다** — `validateDomainDefinition` 이 그때 위반으로 잡는다.
+     * ── 요구가 아니라 **정책**이다 (2026-08-22) ────────────────────────────────
+     * 예전에는 레시피가 쓰는 자재에 이것을 요구했다. 그런데 재고로 위치를 말하는 시스템에는 이 선언이
+     * 없고(그것이 WMS 계열의 정상이다), 표준도 위치를 정의가 아니라 **로트**에 둔다. 실측: 첫 실 연동에서
+     * 원자재 986건 중 36건만 선언돼 있어 레시피 937/1,408 이 실리지 못했다.
+     *
+     * 그래서 요구를 거두었다. **있으면** 확보 범위를 그 타입의 자리로 좁히고(현장의 정책), **없으면**
+     * 재고가 있는 곳에서 찾는다(품목 색인 — §`ItemStore.ofGtin`).
+     *
+     * 다만 **입고를 만들려면 자리가 필요하다** — 시뮬레이션이 자재를 내려놓을 곳을 지어낼 수는 없다.
+     * 선언이 없는 자재는 입고가 만들어지지 않고, 커널이 그 사실을 한 번 알린다(조용히 빠지지 않는다).
+     * 미러에서는 문제가 아니다: 재고는 원본이 말한다.
      */
     locationType?: string;
 }
@@ -188,6 +197,15 @@ export interface OperationDef {
      * `use` 는 표준 `MaterialUse` 를 소문자로 쓴다(우리 어휘 규약). 지금 커널이 소비하는 것은
      * `consumed`(작업이 시작되려면 있어야 하고 시작 시 빠진다)뿐이고, 나머지는 **선언만 받아 둔다** —
      * 자리가 없으면 사실이 들어오지 못한다.
+     *
+     * ── 여기에 **품목별 BOM 을 넣지 않는다** (2026-08-22) ──────────────────────
+     * 이 자리는 ProcessSegment 쪽이다 — 트윈 전체에 한 벌이고 **어느 품목을 만드는 중인지 모른다**
+     * (`claimMaterials` 는 `operationSpecs.get(t.kind)` 로 찾는다). 그래서 여기 담기는 것은 **품목과
+     * 무관하게 그 자리가 늘 쓰는 것**이다: 포장 필름·세척수·윤활유 같은 `consumable`, 그 공정이 품목을
+     * 가리지 않고 먹는 부자재.
+     *
+     * 품목마다 다른 소요는 **레시피의 태그**가 든다(§`RecipePart.operation`). 실 데이터에서 이 둘을 섞으면
+     * 배합 로트 하나가 자재 631종 36톤을 먹는다 — 첫 실 연동이 그 크기를 재서 알려 주었다.
      */
     materialSpecification?: OpMaterialSpecification[];
 }
@@ -229,6 +247,29 @@ export interface RecipePart {
     /** MaterialDef.key. */
     material: string;
     qty: number;
+    /**
+     * **이 투입이 들어가는 공정** — `RouteDef.steps` 의 키. 없으면 오더 착수에 확보한다.
+     *
+     * ── 왜 여기인가 (2026-08-22) ──────────────────────────────────────────────
+     * ISA-95 에는 자재 명세가 붙는 자리가 **둘**이고 뜻이 다르다.
+     *
+     *  · `ProcessSegment` — 그 자리가 **할 수 있는 일**(능력·소요시간·필요 자원). 품목에 매이지 않는다.
+     *  · `OperationsSegment` — 그 **품목을 만드는 절차**의 한 단계(`OperationsDefinition` 소속). 품목에 매인다.
+     *
+     * `OperationDef` 는 ProcessSegment 쪽이다 — 트윈 전체에 한 벌이고 `locationType`·소요시간·설비 종류를
+     * 든다. 거기에 품목별 BOM 을 붙이면 **범주 오류**다. 실 데이터가 그 크기를 보였다: 「배합」에 붙이면
+     * 배합을 지나는 **모든** 로트가 자재 631종 36톤을 먹는다(실제로는 그 로트 한 품목분 수 kg).
+     *
+     * 품목별 공정 소요가 사는 자리는 OperationsSegment 이고, 이 커널에서 그 범위를 가진 것은 **레시피**다.
+     * 그래서 태그를 레시피 투입에 둔다.
+     *
+     * **`RecipeDef.steps[]` 로 두지 않는 이유**: 공정의 순서는 `RouteDef.steps` 가 이미 소유한다. 레시피에
+     * 단계 목록을 또 두면 두 목록이 어긋날 수 있고, 어긋났을 때 어느 쪽이 맞는지 말할 근거가 없다.
+     * 태그 하나면 **순서는 라우트가, 소요는 (레시피 × 공정)이** 말한다 — 한 사실에 한 자리다.
+     *
+     * 첫 실 연동(F&B MES)의 BOM 이 (만드는 품목, 공정) 단위이고, 경로가 둘 이상인 레시피가 306/471 이다.
+     */
+    operation?: string;
 }
 /** BOM/레시피 — ISA-95 Material Consumed/Produced · EPCIS TransformationEvent(input→output). */
 export interface RecipeDef {

package/dist/domain-definition.js

@@ -84,8 +84,16 @@ export function validateDomainDefinition(def) {
                 v.push(`recipe '${rc.key}' material '${p.material}' qty 부정`);
             /* 레시피가 쓰는 자재는 자기 자리를 말해야 한다 — 커널은 그것을 지어내지 않는다(MaterialDef.locationType). */
             const mat = matByKey.get(p.material);
-            if (mat && !mat.locationType)
-                v.push(`recipe '${rc.key}' material '${p.material}' locationType 미선언`);
+            /*
+             * ── 보관처는 **요구가 아니다** (2026-08-22) ────────────────────────────────
+             * 예전에는 레시피가 쓰는 자재에 `locationType` 을 요구했다. 그런데 **재고로 위치를 말하는
+             * 시스템**에는 그 선언이 없다 — 자재에 고정된 보관처를 두지 않는 것이 WMS 계열의 정상이고,
+             * 표준도 위치를 정의(`MaterialDefinition`)가 아니라 로트(`MaterialLot`)에 둔다.
+             *
+             * 실측이 그 비용을 보였다: 첫 실 연동에서 원자재 986건 중 보관처가 선언된 것이 36건이었고, 그
+             * 요구 때문에 레시피 **937/1,408 건이 아예 실리지 못했다.** 확보는 품목 색인으로 돌므로
+             * (§`ItemStore.ofGtin`) 선언은 있으면 좁히는 **정책**이고 없어도 정확하다.
+             */
             if (mat?.locationType && !locationKeys.has(mat.locationType))
                 v.push(`recipe '${rc.key}' material '${p.material}' locationType '${mat.locationType}' 미정의`);
         }

package/dist/epcis.d.ts

@@ -346,7 +346,13 @@ export declare function transformationEvent(p: {
     bizLocation?: string;
     bizTransactionList?: BizTransactionElement[];
 } & EpcisHeaderOptions): EpcisTransformationEvent;
-/** 위반 문구, 또는 통과면 `undefined`. */
+/**
+ * 그 GS1 키의 자리 수가 맞나 — 어긋나면 왜인지 말한다.
+ *
+ * `urn:epc:{id,idpat,class}:<키>:<프리픽스>.<참조>[.<직렬>]` 모양만 본다. 그 밖의 형식(도메인 기반
+ * 식별자 등)은 이 규약의 대상이 아니므로 아무 말도 하지 않는다.
+ */
+export declare function gs1KeyDigitViolation(uri: string | undefined): string | undefined;
 export declare function classIdentifierViolation(epcClass: string | undefined): string | undefined;
 export declare function validateEpcisEvent(e: EpcisEvent): string[];
 export {};

package/dist/epcis.js

@@ -334,9 +334,55 @@ const CBV_URL_CLASS = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)*class\/[^/\s]+$/;
 /** CBV §8.3.3 — URN 이름공간 소유자가 배정. `ObjClassid` 에 콜론 불가. */
 const CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
 /** 위반 문구, 또는 통과면 `undefined`. */
+/**
+ * **GS1 키의 자리 수 규약** — TDS 가 정한 합계다(회사 프리픽스 + 참조 = 고정 자리).
+ *
+ * ── 왜 여기서 보는가 (2026-08-22) ──────────────────────────────────────────
+ * 검증기가 모양(`urn:epc:idpat:sgtin:`)만 보고 **자리 수를 보지 않았다.** 실측: 12자리·14자리 SGTIN 이
+ * 전부 통과했다. 프리픽스를 바꾸는 작업에서 품목참조 자리 수를 맞추지 않으면 **조용히 어긋난
+ * 식별자가 저널에 영구히 남고**, 어느 화면도 그것을 말해 주지 않는다.
+ *
+ * 합계만 본다 — 프리픽스가 몇 자리인지는 GS1 이 회사마다 다르게 배정하므로 우리가 알 수 없다.
+ * 합계는 키 종류가 정한다: SGTIN 13(GTIN-14 의 표시자+13자리) · SSCC 17 · GRAI 12 · GDTI 12.
+ */
+const GS1_KEY_DIGITS = { sgtin: 13, sscc: 17, grai: 12, gdti: 12 };
+/**
+ * 그 GS1 키의 자리 수가 맞나 — 어긋나면 왜인지 말한다.
+ *
+ * `urn:epc:{id,idpat,class}:<키>:<프리픽스>.<참조>[.<직렬>]` 모양만 본다. 그 밖의 형식(도메인 기반
+ * 식별자 등)은 이 규약의 대상이 아니므로 아무 말도 하지 않는다.
+ */
+export function gs1KeyDigitViolation(uri) {
+    if (!uri)
+        return undefined;
+    const m = /^urn:epc:(?:id|idpat|class):([a-z]+):([^:]+)$/.exec(uri);
+    if (!m)
+        return undefined;
+    const want = GS1_KEY_DIGITS[m[1]];
+    if (!want)
+        return undefined;
+    const parts = m[2].split('.');
+    if (parts.length < 2)
+        return `${m[1]} 형식 오류: ${uri} — 회사 프리픽스와 참조가 '.' 로 갈려야 한다`;
+    const [prefix, ref] = parts;
+    /* 패턴의 `*` 는 자리 수를 말하지 않는다 — 참조 자리가 `*` 면 합계를 셀 수 없으므로 넘어간다. */
+    if (ref === '*')
+        return undefined;
+    if (!/^\d+$/.test(prefix) || !/^\d+$/.test(ref)) {
+        return `${m[1]} 형식 오류: ${uri} — 회사 프리픽스와 참조는 숫자다`;
+    }
+    const got = prefix.length + ref.length;
+    if (got === want)
+        return undefined;
+    return (`${m[1]} 자리 수 오류: ${uri} — 회사 프리픽스(${prefix.length}) + 참조(${ref.length}) = ${got} 이지만 ` +
+        `${want} 여야 한다(GS1 TDS). 프리픽스를 바꾸면 참조 자리 수를 함께 맞춰야 한다.`);
+}
 export function classIdentifierViolation(epcClass) {
     if (!epcClass)
         return `quantity epcClass 부정: ${epcClass}`;
+    const digits = gs1KeyDigitViolation(epcClass);
+    if (digits)
+        return `quantity epcClass 부정: ${digits}`;
     if (EPC_CLASS_PREFIXES.some(p => epcClass.startsWith(p)))
         return undefined;
     if (epcClass.startsWith(DL_CANONICAL))
@@ -349,6 +395,24 @@ export function classIdentifierViolation(epcClass) {
 }
 export function validateEpcisEvent(e) {
     const v = [];
+    /*
+     * ── 개체 식별자의 자리 수도 본다 (2026-08-22) ──────────────────────────────
+     * 클래스만 보고 개체를 보지 않으면, 같은 어긋남이 `epcList` 를 타고 그대로 저널에 들어간다. 판정은
+     * 한 규칙이므로 실리는 모든 자리에 같이 댄다(§`gs1KeyDigitViolation`).
+     */
+    for (const [field, list] of [
+        ['epcList', e.epcList],
+        ['childEPCs', e.childEPCs],
+        ['inputEPCList', e.inputEPCList],
+        ['outputEPCList', e.outputEPCList],
+        ['parentID', e.parentID ? [e.parentID] : undefined]
+    ]) {
+        for (const epc of list ?? []) {
+            const bad = gs1KeyDigitViolation(epc);
+            if (bad)
+                v.push(`${field}: ${bad}`);
+        }
+    }
     if (e['@context'] !== EPCIS_CONTEXT)
         v.push('@context 누락/불일치');
     if (!['ObjectEvent', 'AggregationEvent', 'TransactionEvent', 'TransformationEvent'].includes(e.type))

package/dist/flow-engine.d.ts

@@ -2,7 +2,7 @@ import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, Effectiv
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
-import type { OperationDef, IsoDuration } from './domain-definition.ts';
+import type { OperationDef, IsoDuration, OpMaterialSpecification } from './domain-definition.ts';
 import { type CapacityAnalysis } from './capacity.ts';
 import { type CommittedDemand, type OperationsCapabilityReport } from './operations-capability.ts';
 export interface FlowLocation {
@@ -402,6 +402,22 @@ export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;
 export declare class ItemStore {
     private map;
     private byLocation;
+    /**
+     * 품목별 색인 — **보관처를 선언하지 않은 현장을 위해.**
+     *
+     * ── 왜 필요한가 (2026-08-22) ──────────────────────────────────────────────
+     * 자재를 확보할 때 예전에는 「그 자재의 보관처 타입」을 반드시 선언해야 했다(`MaterialDef.locationType`).
+     * 그런데 **재고로 위치를 말하는 시스템**에는 그 선언이 없다 — 자재에 고정된 보관처를 두지 않는 것이
+     * WMS 계열의 정상이다. 실측: 첫 실 연동에서 원자재 986건 중 보관처가 선언된 것이 **36건**이었고, 그
+     * 때문에 레시피 937/1,408 건이 아예 실리지 못했다.
+     *
+     * 선언이 없으면 **재고가 있는 곳에서 찾는다.** 그때 전 로케이션을 훑으면 규모 기준선(품목 100만)에서
+     * 감당되지 않으므로 품목 색인이 답한다.
+     *
+     * 색인을 밖에 따로 두지 않는다 — 갱신하는 자리가 흩어지면 한 자리라도 빠뜨렸을 때 **재고가 조용히
+     * 사라진다**(있는데 없다고 판정된다). 자리 색인과 같은 규율이다.
+     */
+    private byGtin;
     get size(): number;
     get(key: string): FlowItem | undefined;
     has(key: string): boolean;
@@ -430,6 +446,8 @@ export declare class ItemStore {
     clone(): ItemStore;
     /** 그 자리에 있는 물품들 — 색인이 답한다(전체 순회가 아니다). */
     at(location: string): FlowItem[];
+    /** 그 품목인 물품들 — 색인이 답한다(자리를 모를 때 쓴다). */
+    ofGtin(gtin: string): FlowItem[];
     /**
      * 색인이 맵과 어긋난 자리 — **시험이 쓰는 확인 통로**(전체를 다시 세므로 비싸다).
      *
@@ -438,7 +456,9 @@ export declare class ItemStore {
      */
     indexDrift(): string[];
     private index;
+    private indexLocation;
     private unindex;
+    private unindexLocation;
 }
 export declare abstract class FlowEngine implements TwinKernel {
     tenantId: string;
@@ -527,6 +547,14 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     private seedDanglingRefs;
     private transformInputsAbsent;
+    /**
+     * 일반 요구(공정)와 구체 요구(레시피 × 공정)가 **등급 ↔ 품목으로 교차**한 횟수.
+     *
+     * 같은 키끼리는 구체가 상회한다(§`mergeMaterialNeeds`). 교차는 뜻으로는 상회일 수 있으나 판정에 등급
+     * 소속이 필요하고, 잘못 겹치면 자재가 조용히 사라지거나 두 배가 된다. 그래서 **둘 다 요구하고 센다** —
+     * 이 값이 크면 그 숫자가 다음 작업을 정한다.
+     */
+    private materialSpecCrossKeyOverlaps;
     private observedDirty;
     private observeMode;
     /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
@@ -1281,7 +1309,13 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected requireObjectId(id: string | number): string;
     /** 거래 문서 식별자 — 선언된 이름공간 또는 선언된 GDTI 문서 타입. 둘 다 없으면 오류를 낸다. */
     protected requireBizTransactionId(id: string | number, docKind: string): string;
-    /** 같은 문장을 두 곳에 적지 않는다 — 고치는 자리가 하나여야 한다. */
+    /**
+     * 같은 문장을 두 곳에 적지 않는다 — 고치는 자리가 하나여야 한다.
+     *
+     * `what` 은 **관사까지 갖춘 구**를 받는다(`'an object'`). 예전에는 여기서 `a ${what}` 로 관사를
+     * 붙였고, 화면에 「cannot name a object」·「cannot name a business transaction 'purchase'」가 그대로
+     * 나왔다. 사람이 읽는 문장이므로 부르는 자리가 관사를 정한다.
+     */
     private identityMissing;
     /** 선언된 이름공간 아래의 **거래 문서 식별자**(발주·주문·어포인트먼트) — 없으면 답하지 않는다. */
     protected declaredBizTransactionId(id: string | number): string | undefined;
@@ -1334,6 +1368,46 @@ export declare abstract class FlowEngine implements TwinKernel {
     private recordMaterialActual;
     /** 확보한 자재를 **작업 시작 시점에 소비**한다 — 수량이 0 이 되면 물품 자체가 사라진다. */
     private consumeMaterials;
+    /**
+     * **소비된 자재를 도메인이 계보로 가져가는가** — 가져가면 코어는 없애지 않고 예약만 한다.
+     *
+     * 공정이 먹은 자재는 **그 단계가 만드는 것의 입력**이다. 그것을 별도 사건으로 없애면 제품의 계보에서
+     * 그 자재가 빠지고, 회수 범위를 되짚을 때 조용히 좁아진다 — 식품이라면 그것이 사고다.
+     *
+     * 기본은 「가져가지 않는다」다: 만드는 것이 없는 소비(소모품·유통가공)는 개체가 사라진 것이 맞다.
+     */
+    protected adoptConsumed(_t: FlowTask, _epcs: string[]): boolean;
+    /** 이 트윈이 사는 동안 한 번만 알린 상회 — 같은 말을 틱마다 반복하지 않는다. */
+    private announcedOverrides;
+    /**
+     * **구체가 일반을 이긴다 — 다만 상회하는 단위는 자재 한 줄이다.**
+     *
+     * ── 왜 합집합이 아닌가 (2026-08-22) ───────────────────────────────────────
+     * 두 원천이 같은 자재를 말할 수 있다. 일반은 「이 공정이 늘 쓰는 것」이고(품목과 무관 — 포장 필름·
+     * 세척수), 구체는 「이 품목을 이 공정에서 만들 때」다. 같은 자재를 둘이 말하면 **구체가 현장의 사실**
+     * 이므로 이긴다. 합집합이면 요구가 더해져 재고가 거짓이 된다.
+     *
+     * ── 왜 명세 전체를 덮지 않는가 ────────────────────────────────────────────
+     * 덮으면 반대로 틀린다. 레시피가 「무말랭이 90kg」만 말했다고 그 공정의 세척수 50L 이 사라지면, 품목과
+     * 무관하게 늘 들어가는 것이 빠진다 — 그것이 일반 자리의 존재 이유다. 요구의 단위가 자재 한 줄이므로
+     * 상회도 그 단위에서 일어난다.
+     *
+     * ── 등급 ↔ 품목이 교차하면 둘 다 요구한다 ─────────────────────────────────
+     * 명세는 품목(`materialDefinition`)으로도 등급(`materialClass`)으로도 요구한다. 일반이 등급을, 구체가
+     * 품목을 말하고 그 품목이 그 등급에 속하면 뜻으로는 상회지만, 그 판정에는 등급 소속이 필요하고 잘못
+     * 겹치면 자재가 **조용히 사라지거나 두 배**가 된다. 그래서 **같은 키끼리만** 상회시키고, 교차하는
+     * 경우는 세어 남기고 둘 다 요구한다 — 조용히 한쪽을 버리는 것이 가장 나쁘다.
+     */
+    private mergeMaterialNeeds;
+    /**
+     * **그 작업이 만드는 품목의, 그 공정 몫** — 품목 범위를 아는 것은 도메인이다.
+     *
+     * 코어는 레시피를 모른다(창고·야드에는 레시피가 없다). 그래서 시임으로 둔다 — MES 가 오더의
+     * 레시피에서 그 공정에 태그된 투입을 돌려준다(§`RecipePart.operation`).
+     *
+     * 기본은 빈 목록이다: 품목 범위가 없는 트윈에서는 공정 명세만이 요구다.
+     */
+    protected recipeInputsAt(_t: FlowTask): OpMaterialSpecification[];
     /**
      * 이 사람이 **속한 등급들이 요구하는 시험**을 만족하나.
      *