@operato/twin-kernel 0.4.1 → 0.4.3

package/dist/capability.js

@@ -11,25 +11,30 @@
  * 이 의도를 *실현*한다 — 공유 계약은 관측(계층 B)뿐, 기제 methods(계층 A)는 공유 안 함.
  * ⚠ Mobile ≠ Transferable: Mobile=자원 자신이 이동, Transferable=자리가 아이템 이동(씬 기제).
  */
+/*
+ * `label` 은 **언어 중립 i18n 키**(`twin.capability.<key>`) — 사람 언어는 표현계층이 렌더한다(L2).
+ * 타입/시스템 라벨(domain-catalog)이 먼저 이 규약으로 옮겨졌고, 능력 라벨만 사람 말로 남아
+ * 영어 화면에 한글이 새고 있었다. `semantics` 는 설계 문서용 산문이므로 대상이 아니다.
+ */
 export const CAPABILITIES = {
     operable: {
-        key: 'operable', label: '운영', semantics: '능동 자원의 운영 상태(유휴/가동/고장). status 교차 관심사를 여기 하나로.',
+        key: 'operable', label: 'twin.capability.operable', semantics: '능동 자원의 운영 상태(유휴/가동/고장). status 교차 관심사를 여기 하나로.',
         stateFields: ['status'], results: ['statusChanged']
     },
     storable: {
-        key: 'storable', label: '저장', semantics: '아이템을 보유하는 위치 — 점유/용량. (씬 기제: Capacity)',
+        key: 'storable', label: 'twin.capability.storable', semantics: '아이템을 보유하는 위치 — 점유/용량. (씬 기제: Capacity)',
         stateFields: ['occupancy', 'capacity'], invariants: ['0 <= occupancy <= capacity (capacity>0)'], results: ['occupancyChanged']
     },
     mobile: {
-        key: 'mobile', label: '이동', semantics: '자원 자신이 자리 간 이동. Transferable(아이템 이동)과 다름. (씬 기제: CarrierLine)',
+        key: 'mobile', label: 'twin.capability.mobile', semantics: '자원 자신이 자리 간 이동. Transferable(아이템 이동)과 다름. (씬 기제: CarrierLine)',
         stateFields: ['location', 'motion'], models: ['Motion'], results: ['moved', 'motionTick']
     },
     processable: {
-        key: 'processable', label: '가공', semantics: '변환/가공 수행 — 산출(양품/불량). 운영 status 는 Operable 조합. progress 방출은 후속.',
+        key: 'processable', label: 'twin.capability.processable', semantics: '변환/가공 수행 — 산출(양품/불량). 운영 status 는 Operable 조합. progress 방출은 후속.',
         stateFields: ['output'], results: ['completed']
     },
     trackable: {
-        key: 'trackable', label: '추적', semantics: '오더/아이템 생애 추적 — 생애단계(도메인 라벨, 무방언)·진행·보류.',
+        key: 'trackable', label: 'twin.capability.trackable', semantics: '오더/아이템 생애 추적 — 생애단계(도메인 라벨, 무방언)·진행·보류.',
         stateFields: ['lifecycle', 'progress', 'held'], results: ['lifecycleChanged']
     }
 };

package/dist/contract.d.ts

@@ -971,6 +971,13 @@ export interface StateSnapshot {
     tasks: TaskState[];
     orders: OrderState[];
     attentions?: Attention[];
+    /**
+     * 확인(ack)해 둔 주목 신호 id — **상태에서 파생되지 않는 유일한 축.**
+     *
+     * 신호 자체는 상태에서 다시 계산되지만 "사람이 봤다" 는 계산으로 되살릴 수 없다. 스냅샷으로
+     * 왕복시켜야 재기동·되짚기에서 확인 상태가 유지된다.
+     */
+    acked?: string[];
 }
 export interface Command<T = unknown> {
     commandId: string;
@@ -1084,7 +1091,25 @@ export declare const OP_EVENT: {
     readonly asset: "asset.status";
     readonly order: "order.status";
     readonly quality: "quality.output";
+    /**
+     * 주목 신호 확인(ack) — **사람이 한 행위**라 파생될 수 없다.
+     *
+     * 다른 파생 상태는 상태에서 다시 계산된다(주목 신호 자체가 그렇다). 그런데 "누가 이것을 봤다" 는
+     * 계산으로 되살릴 수 없다. 저널에 남기지 않으면 재기동하면 확인해 둔 신호가 다시 빨개지고,
+     * 과거를 되짚어도 그때 무엇을 확인했는지 알 수 없다 — 저널이 현실을 불완전하게 담는 자리였다.
+     */
+    readonly attentionAck: "attention.acked";
 };
+/**
+ * 주목 신호 확인 델타 — 확인한 신호의 id 와 시각.
+ *
+ * 신호의 내용은 싣지 않는다(상태에서 다시 계산된다). 여기 남기는 것은 **사람이 확인했다는 사실** 하나다.
+ */
+export interface AttentionAckDelta {
+    id: string;
+    /** 확인한 시각 — 없으면 이벤트 시각을 쓴다. */
+    at?: ISOTime;
+}
 /** 사람 상태 델타 — 배정·해제·교대 전이 시 방출. 미러가 인원 가용을 비추는 근거. */
 export interface PersonStatusDelta extends EffectivePeriod {
     personId: string;
@@ -1328,6 +1353,59 @@ export interface BoardDef {
     personnelClasses?: ResourceClassDef[];
     equipmentClasses?: ResourceClassDef[];
     assetClasses?: ResourceClassDef[];
+    /**
+     * **생산 선언** — 이 트윈이 무엇을 어떻게 만드는가(ISA-95 `OperationsSegment` + BOM).
+     *
+     * ── 이름을 `productionSpec` 으로 정한 이유 (2026-08-05, 되돌리지 말 것) ─────────────────────────
+     * 이 자리는 예전에 **`mesSpec`** 이라는 이름으로, 그것도 **계약에 선언되지 않은 채**
+     * (`(board as any).mesSpec`) 타고 있었다.
+     *
+     * 그 이름의 유래는 자재가 아니라 **소비자**다: `MesKernel` 의 생성자 인자 이름이
+     * `mesSpec: MesDefinitionSpec` 이고(정의-구동 모드를 MES 에만 도입한 커밋 `ce4fbeb`), 호스트가
+     * 보드에 얹을 때 그 인자 이름을 그대로 가져왔다. 소비자가 하나일 때는 어색하지 않았다.
+     *
+     * `materialSpec` 도 답이 아니다. ① 담긴 것이 자재가 아니다 — 타입·오퍼레이션(소요·변동·모수·
+     * 인원/설비/자산/자재 명세)·라우트·레시피이고 자재는 그중 한 항목의 한 필드다. ② 그 이름은 이미
+     * 표준 자리로 쓰인다 — `OperationDef.materialSpecification` 이 ISA-95 `OpMaterialSpecificationType`
+     * 1:1 이다. 보드 수준에서 같은 이름을 쓰면 "어느 쪽 자재 명세냐" 가 매번 헷갈린다.
+     *
+     * `productionSpec` = ISA-95 의 생산 영역 어휘이고, 담긴 것("이 트윈이 무엇을 어떻게 만드는가")
+     * 그대로다. 특정 시스템(MES/WMS)에도, 특정 자원(자재)에도 기울지 않는다.
+     *
+     * 이름이 MES 였던 결과로 두 가지가 굳었다.
+     *
+     *  ① **일반 기제에 한 시스템 이름이 붙었다.** 담고 있는 것은 ISA-95 `OperationsSegment`(소요·모수·
+     *     자재 명세)와 BOM 이고, 그것은 MES 만의 것이 아니다 — 창고의 유통가공(키팅·세트조립)도 같은
+     *     "자재를 소비해 자재를 산출하는 공정" 이다. 이름이 MES 였기 때문에 **WMS 트윈은 이 선언을 실을
+     *     생각조차 하지 못했고**, 유통가공 창고 템플릿은 BOM 을 설명 문서(`detail`)에만 적어 둔 채
+     *     키트를 만들지 못하는 트윈을 만들어 냈다(랙이 꽉 차고 출고가 0건이었다).
+     *  ② 계약에 없으니 **아무도 이 자리를 발견할 수 없었다.** 타입이 말해 주지 않는 필드는 없는 필드다.
+     *
+     * 그래서 표준 어휘를 따르는 일반 이름으로 정식 선언한다. `mesSpec` 은 기존 트윈이 그대로 돌도록
+     * **읽기 호환으로만** 남긴다(새로 쓰지 않는다).
+     *
+     * ── 시스템별 생산의 경계 (여기서도 되돌리지 말 것) ────────────────────────────────────────────
+     * MES 의 생산은 **직렬번호·수율·생산오더 연결**을 갖는 레시피 경로다. 코어의 일반 자재 명세
+     * (`use: 'produced'`)는 **비직렬 클래스+수량**이라 그 셋을 표현하지 못한다 — 그래서 둘을 합치지
+     * 않는다. 겹치면 같은 산출이 두 번 생기므로 MES 커널이 기동 시점에 거부한다(`assertNoDoubleProduction`).
+     * 유통가공(VAS)은 비직렬 클래스+수량이 맞는 모양이므로 코어의 일반 경로를 쓴다.
+     */
+    productionSpec?: ProductionSpec;
+}
+/**
+ * 생산 선언 — 도메인 정의(ISA-95 operations + BOM)와, 그 추상 자재 키를 실제 GS1 식별자로 잇는 바인딩.
+ *
+ * 정의는 **gtin 을 모른다**(어느 회사의 물건인지는 현장의 사실이다). 그래서 키→item reference 바인딩과
+ * 회사 프리픽스를 여기서 받아 `urn:epc:idpat:sgtin:<prefix>.<ref>.*` 를 만든다.
+ */
+export interface ProductionSpec {
+    /** 무엇이 있고 어떻게 흐르나 — `DomainDefinition`(자기 타입, zero-dep). */
+    definition: import('./domain-definition.ts').DomainDefinition;
+    /** 자재 키 → GS1 item reference. */
+    binding?: Record<string, string>;
+    companyPrefix?: string;
+    /** 쓸 레시피 키(미지정 시 첫 레시피) — 직렬 생산 경로(MES)만 쓴다. */
+    recipeKey?: string;
 }
 export interface TwinKernel {
     loadBoard(def: BoardDef): void;

package/dist/contract.js

@@ -497,7 +497,20 @@ export const OP_EVENT = {
     /** 물리 자산 상태 전이 — 어디 있나·무엇을 싣고 있나(빈 팔레트인가). */
     asset: 'asset.status',
     order: 'order.status',
-    quality: 'quality.output' // 품질 산출(양품/불량) — OEE quality 입력. live 누적기가 이걸로 good/scrap 정확 추적.
+    quality: 'quality.output', // 품질 산출(양품/불량) — OEE quality 입력. live 누적기가 이걸로 good/scrap 정확 추적.
+    /**
+     * 주목 신호 확인(ack) — **사람이 한 행위**라 파생될 수 없다.
+     *
+     * 다른 파생 상태는 상태에서 다시 계산된다(주목 신호 자체가 그렇다). 그런데 "누가 이것을 봤다" 는
+     * 계산으로 되살릴 수 없다. 저널에 남기지 않으면 재기동하면 확인해 둔 신호가 다시 빨개지고,
+     * 과거를 되짚어도 그때 무엇을 확인했는지 알 수 없다 — 저널이 현실을 불완전하게 담는 자리였다.
+     */
+    /*
+     * 값이 커맨드(`CMD.attentionAck='attention.ack'`)와 겹치지 않게 **과거형**으로 둔다 — 커맨드는
+     * "확인해라"(요청)이고 이벤트는 "확인했다"(사실)다. 같은 문자열을 쓰면 저널에서 요청과 사실이
+     * 구별되지 않는다.
+     */
+    attentionAck: 'attention.acked'
 };
 // ── Command 채널 어휘 — 트윈의 "행위(act)" 면 (prescriptive/트랜잭션 프론트엔드) ──
 // 코어 공통: order.hold/resume(할당 보류). 도메인: order.release(즉시 투입) 등은 handleCommand 로.

package/dist/flow-engine.d.ts

@@ -348,6 +348,8 @@ export declare abstract class FlowEngine implements TwinKernel {
         assets?: AssetState[];
         tasks?: TaskState[];
         orders?: OrderState[];
+        /** 확인해 둔 주목 신호 id — 계산으로 되살릴 수 없는 유일한 축이라 스냅샷에서 이어받는다. */
+        acked?: string[];
     }, orders?: OrderStatusDelta[]): void;
     /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
     setLocationCapacity(locationId: string, capacity: number): boolean;
@@ -374,6 +376,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     private _attentionSince;
     dispatch(cmd: Command): CommandAck;
+    private dispatchInner;
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     protected handleCommand(cmd: Command): CommandAck;
     readonly scenario: ScenarioControl;
@@ -448,6 +451,13 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 오퍼레이션 명세를 싣는다 — 도메인 정의(ISA-95 OperationsSegment)의 시뮬 명세를 커널이 소비하는 입구.
      * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
      */
+    /**
+     * 선언된 오퍼레이션들 — 도메인 커널이 "무엇을 만들 수 있나" 를 물을 수 있게.
+     *
+     * `operationSpecs` 를 도메인이 직접 뒤지지 않게 읽기 창구를 둔다: 저장 형태(맵)가 바뀌어도
+     * 도메인은 몰라야 하고, 도메인이 그 맵에 쓰는 일이 생기면 정의가 권위라는 규약이 깨진다.
+     */
+    protected declaredOperations(): readonly OperationDef[];
     loadOperations(ops?: OperationDef[]): void;
     /**
      * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
@@ -608,6 +618,17 @@ export declare abstract class FlowEngine implements TwinKernel {
     private oeeOf;
     /** 정책에 넘길 특정 타입 자리의 관측 뷰 — 예약(그 자리로 향하는 in-flight task) 포함. */
     protected slotViews(locationType: string): SlotView[];
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    private _correlationId?;
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
     /**

package/dist/flow-engine.js

@@ -255,6 +255,15 @@ export class FlowEngine {
     // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
     loadBoard(def) {
         this.boardDef = def;
+        /*
+         * **생산 선언은 어느 커널이든 싣는다.** 예전에는 MES 커널만 생성자에서 이것을 실었고(그 시절
+         * 이름은 `mesSpec` 이었다), 그래서 창고 트윈은 "자재를 소비해 자재를 산출하는 공정" 을 선언할
+         * 방법이 없었다 — 유통가공 창고 템플릿이 BOM 을 설명 문서에만 적어 둔 채 키트를 못 만드는
+         * 트윈을 만들어 낸 원인이다. 담긴 것은 ISA-95 `OperationsSegment` 이고 시스템에 종속되지 않으므로
+         * 여기(공통)에서 싣는다. MES 는 그 위에 직렬·수율·오더연결 레시피 경로를 더 갖는다.
+         */
+        if (def.productionSpec?.definition?.operations?.length)
+            this.loadOperations(def.productionSpec.definition.operations);
         for (const n of readBoardLocations(def))
             this.locations.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, occupancy: 0, status: 'idle', parentId: n.parentId });
         this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
@@ -313,6 +322,10 @@ export class FlowEngine {
         this.revision = from;
     }
     hydrateObserved(snap, orders = []) {
+        /* 확인 처리를 먼저 이어받는다 — 아래에서 상태를 심으면 곧바로 주목 신호가 계산되므로, 늦게
+         * 이어받으면 그 한 번은 확인 안 된 것으로 계산된다(화면이 잠깐 빨개진다). */
+        for (const id of snap.acked ?? [])
+            this._acked.add(id);
         /* **관측된 것을 버리지 않는다.** 예전에는 자리·설비 상태를 'idle' 로, OEE 누적을 0 으로 덮고
          * 물품의 로트·단위·소속·마스터데이터를 떨어뜨렸다. 씨앗이 잃은 것은 **예측도 모른다** —
          * 고장 난 설비를 정상으로, 진행 중인 일을 없는 것으로 놓고 미래를 굴리면 답이 낙관 쪽으로 치우친다. */
@@ -533,6 +546,20 @@ export class FlowEngine {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     _attentionSince = new Map(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
     dispatch(cmd) {
+        /*
+         * 이 커맨드가 낳는 이벤트에 상관값을 단다. 명시값이 없으면 **commandId 를 쓴다** — 호출자가
+         * 따로 챙기지 않아도 모든 지시가 자기 결과와 이어진다(감사 기록이 commandId 를 이미 갖고 있다).
+         * finally 로 반드시 걷는다: 남겨 두면 그 뒤 틱에서 일어난 무관한 일까지 이 커맨드 탓이 된다.
+         */
+        this._correlationId = cmd.correlationId ?? cmd.commandId;
+        try {
+            return this.dispatchInner(cmd);
+        }
+        finally {
+            this._correlationId = undefined;
+        }
+    }
+    dispatchInner(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
         // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
         const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
@@ -549,8 +576,15 @@ export class FlowEngine {
             }
             case CMD.attentionAck: {
                 const id = cmd.args?.id;
-                if (id)
+                if (id) {
                     this._acked.add(id);
+                    /*
+                     * **사실로 남긴다.** 확인 처리는 사람이 한 행위라 상태에서 다시 계산될 수 없다. 저널에
+                     * 남기지 않으면 재기동하면 확인해 둔 신호가 다시 빨개지고, 과거를 되짚어도 그때 무엇을
+                     * 확인했는지 알 수 없다. 다른 커맨드(보류·재개)가 델타를 내는 것과 같은 길이다.
+                     */
+                    this.emitOp(OP_EVENT.attentionAck, { id, at: this.now() });
+                }
                 return ok();
             }
             // Operable 코어 — 자원(설비·설비) 제어. capability-keyed(resourceId), 모든 operable 자원 공통.
@@ -735,7 +769,9 @@ export class FlowEngine {
                 ...(o.endTime ? { endTime: o.endTime } : {}),
                 held: o.held
             })),
-            attentions: this.computeAttentions()
+            attentions: this.computeAttentions(),
+            /* 확인해 둔 신호 — 스냅샷으로 왕복해야 재기동 후에도 확인 상태가 유지된다. */
+            acked: [...this._acked]
         };
     }
     /*
@@ -896,6 +932,15 @@ export class FlowEngine {
      * 오퍼레이션 명세를 싣는다 — 도메인 정의(ISA-95 OperationsSegment)의 시뮬 명세를 커널이 소비하는 입구.
      * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
      */
+    /**
+     * 선언된 오퍼레이션들 — 도메인 커널이 "무엇을 만들 수 있나" 를 물을 수 있게.
+     *
+     * `operationSpecs` 를 도메인이 직접 뒤지지 않게 읽기 창구를 둔다: 저장 형태(맵)가 바뀌어도
+     * 도메인은 몰라야 하고, 도메인이 그 맵에 쓰는 일이 생기면 정의가 권위라는 규약이 깨진다.
+     */
+    declaredOperations() {
+        return [...this.operationSpecs.values()];
+    }
     loadOperations(ops = []) {
         for (const o of ops)
             if (o?.key)
@@ -1251,15 +1296,26 @@ export class FlowEngine {
                 views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
         return views;
     }
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    _correlationId;
     emit(event) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data: event };
         for (const h of this.handlers)
             h(e);
     }
     emitOp(eventType, data) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data };
         for (const h of this.handlers)
             h(e);
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './contract.ts';
+export * from './scenario-validate.ts';
 export * from './domain-definition.ts';
 export * from './counterfactual.ts';
 export * from './forecast.ts';
@@ -25,5 +26,4 @@ export * from './capacity.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 type { MesDefinitionSpec } from './mes-kernel.ts';
 export * from './vocabulary.ts';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./contract.js";
+export * from "./scenario-validate.js";
 export * from "./domain-definition.js";
 export * from "./counterfactual.js";
 export * from "./forecast.js";

package/dist/kernel.d.ts

@@ -28,6 +28,41 @@ export declare class WmsKernel extends FlowEngine {
     protected allocate(o: FlowOrder): void;
     /** 태스크 완료 — 이동 반영 후 putaway=storing, pick=picking(+전량 시 pack→stage→ship). */
     protected onTaskComplete(t: FlowTask): void;
+    /**
+     * 부족한 라인을 **만들어서** 채운다 — 부품 이송 → 가공 → 되돌리기 3단 사슬.
+     *
+     * 사슬인 이유는 커널의 두 규칙 때문이다(둘 다 의도된 규칙이라 우회하지 않는다):
+     * 자재는 **작업이 일어나는 자리에** 있어야 소비되고, 산출물은 `in_progress` 로 태어나 **팔 수 있는
+     * 재고가 아니다.** 그래서 부품을 작업대로 옮기고, 가공하고, 나온 것을 보관 자리로 되돌린다.
+     *
+     * **한 오더에 사슬 하나만** 굴린다. 매 tick 마다 다시 발행하면 같은 부품을 두 번 끌어오는 작업이
+     * 쌓이고, 그중 하나만 성공한 뒤 나머지는 영원히 재료를 기다린다.
+     */
+    private makeShortLines;
+    /** 이 오더가 굴리고 있는 생산 사슬이 있나 — 이송·가공·되돌리기 중 하나라도 열려 있으면 그렇다. */
+    private hasOpenMakeChain;
+    /** 지금 재고 — 판단 함수가 보는 형태로. */
+    private stockLines;
+    /** 부품을 작업대로 — 팔레트 이동이므로 피킹과 같은 기제다(부분 소비는 코어가 한다). */
+    private issueFeed;
+    /** 가공 — 작업 종류를 **오퍼레이션 키**로 둔다(코어가 그 키로 명세를 찾는다). */
+    private issueProcess;
+    private pushTask;
+    /**
+     * 가공 완료 — 코어가 이미 소비(시작)와 산출(완료 직전)을 실행했다. 남은 일은 만든 것을 **재고로
+     * 들여놓는 것**이다: 산출물은 `in_progress` 로 태어나 팔 수 있는 재고가 아니다.
+     *
+     * ── 왜 팔레트로 묶나 ───────────────────────────────────────────────────────
+     * 코어의 산출은 **클래스+수량 줄**이고 그 키에는 자리가 박혀 있다(`품목@자리`). 창고의 출고 경로는
+     * 직렬 물류단위(팔레트 SSCC)를 다루므로, 그 줄을 그대로 출고에 태우면 키를 EPC 로 착각해 조회가
+     * 깨진다(실제로 그렇게 터졌다). 억지로 태우면 EPCIS 에도 **EPC 가 아닌 문자열**이 `epcList` 로
+     * 나가는데, 그것은 코어가 산출에서 경계한 바로 그 일이다.
+     *
+     * 그래서 만든 물건을 **입고가 하는 것과 같은 방식**으로 들여놓는다: 팔레트(SSCC)를 만들고 그 안에
+     * 세트 N개를 담는다(AggregationEvent). 현장에서도 가공물은 팔레트에 실려 보관으로 간다.
+     * 그 뒤는 기존 경로 그대로다 — `putaway` 로 보관 자리에 넣으면 판매 가능이 된다.
+     */
+    private onProcessComplete;
     /** 전량 피킹 → packing(조립)·staging·shipping 마감. 화물 사이트 이탈, 백오더 잔량 재할당. */
     private finalizeOrder;
 }

package/dist/kernel.js

@@ -8,8 +8,10 @@
 import { CMD } from "./contract.js";
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine } from "./flow-engine.js";
+import { planMakeToOrder } from "./make-to-order.js";
 import { BIZSTEP, BTT } from "./wms-profile.js";
 import { DISP, ILMD_ATTR, aggregationEvent, gdtiUri, objectEvent, ssccUri, transactionEvent } from "./epcis.js";
+import { subLotIdOf } from "./contract.js";
 const TRAVEL_MS = 30_000;
 const COMPANY_PREFIX = '0614141';
 const SHELF_MS = 30 * 24 * 3_600_000; // 기본 유통기한(30일)
@@ -138,8 +140,13 @@ export class WmsKernel extends FlowEngine {
                 chosenAll.push(epc);
             }
         }
+        /*
+         * **재고에 없으면 만들 수 있는지 본다** — 유통가공(키팅·세트조립) 창고가 여기서 막혀 있었다.
+         * 인바운드는 부품을 넣고 오더는 세트를 요구하는데 그 세트를 만드는 공정을 아무도 부르지 않아,
+         * 랙이 꽉 차고 출고가 한 건도 나오지 않았다. 판단은 `planMakeToOrder`(순수)가 한다.
+         */
         if (chosenAll.length === 0)
-            return;
+            return this.makeShortLines(o);
         /* 할당은 아직 집은 것이 아니다 — 물건은 보관 자리에 있고 처분만 '예약' 으로 바뀐다.
          * 그래서 단계는 storing 이다(피킹 관측은 실제로 집을 때 따로 난다). */
         this.reserve(chosenAll, BIZSTEP.storing);
@@ -156,6 +163,13 @@ export class WmsKernel extends FlowEngine {
     }
     /** 태스크 완료 — 이동 반영 후 putaway=storing, pick=picking(+전량 시 pack→stage→ship). */
     onTaskComplete(t) {
+        /*
+         * **생산 사슬의 걸음들을 먼저 가른다.** 아래 이동 처리는 "주체가 팔레트 하나" 를 전제하는데,
+         * 가공은 클래스+수량 소비/산출이라 주체가 없다 — 그대로 두면 물품을 찾지 못해 터진다(실제로
+         * 그랬다). 걸음마다 무엇이 끝난 것인지 다르므로 각각 답한다.
+         */
+        if (t.intent === 'process')
+            return this.onProcessComplete(t);
         const item = this.itemByRef(t.itemEpc);
         /* 여기 도달했다면 코어가 이미 물품을 확인했다(주체가 사라진 작업은 완료 전에 접힌다).
            그래도 단정(`!`)은 쓰지 않는다 — 계약이 바뀌면 조용히 틀리는 대신 분명히 멈춘다. */
@@ -166,6 +180,14 @@ export class WmsKernel extends FlowEngine {
         from.occupancy--;
         to.occupancy++;
         item.location = to.id;
+        /*
+         * 부품 이송 — 자리만 옮긴다. 처분은 예약으로 남겨 둔다(다른 오더가 집어 가면 이 가공이 굶는다).
+         * 관측은 `staging_outbound` 가 아니라 이동 그대로다 — 아직 아무것도 만들지 않았다.
+         */
+        if (t.kind === 'feed') {
+            this.emit(objectEvent({ eventTime: this.now(), action: 'OBSERVE', bizStep: BIZSTEP.storing, disposition: item.disposition, epcList: [item.epc], quantityList: [{ epcClass: item.gtin, quantity: item.qty }], readPoint: to.id, bizLocation: to.id }));
+            return;
+        }
         if (t.kind === 'putaway') {
             item.disposition = DISP.sellable;
             this.emit(objectEvent({ eventTime: this.now(), action: 'OBSERVE', bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [item.epc], quantityList: [{ epcClass: item.gtin, quantity: item.qty }], readPoint: to.id, bizLocation: to.id }));
@@ -181,6 +203,131 @@ export class WmsKernel extends FlowEngine {
         if (order.picked.length === order.allocated.length)
             this.finalizeOrder(order, to);
     }
+    // ── 수요가 부르는 생산(유통가공) ────────────────────────────────────────────
+    /**
+     * 부족한 라인을 **만들어서** 채운다 — 부품 이송 → 가공 → 되돌리기 3단 사슬.
+     *
+     * 사슬인 이유는 커널의 두 규칙 때문이다(둘 다 의도된 규칙이라 우회하지 않는다):
+     * 자재는 **작업이 일어나는 자리에** 있어야 소비되고, 산출물은 `in_progress` 로 태어나 **팔 수 있는
+     * 재고가 아니다.** 그래서 부품을 작업대로 옮기고, 가공하고, 나온 것을 보관 자리로 되돌린다.
+     *
+     * **한 오더에 사슬 하나만** 굴린다. 매 tick 마다 다시 발행하면 같은 부품을 두 번 끌어오는 작업이
+     * 쌓이고, 그중 하나만 성공한 뒤 나머지는 영원히 재료를 기다린다.
+     */
+    makeShortLines(o) {
+        if (!o.lines?.length)
+            return;
+        if (this.hasOpenMakeChain(o.id))
+            return; // 이미 굴러가는 중
+        const stock = this.stockLines();
+        const locations = [...this.locations.values()].map(l => ({ id: l.id, type: l.type }));
+        const ops = this.declaredOperations();
+        for (const line of o.lines) {
+            const have = stock.filter(s => s.gtin === line.gtin && s.sellable && this.locations.get(s.location)?.type === 'storage')
+                .reduce((n, s) => n + s.qty, 0);
+            const short = line.requested - have;
+            if (short <= 0)
+                continue;
+            const plan = planMakeToOrder(line.gtin, short, ops, stock, locations);
+            for (const step of plan.steps) {
+                if (step.step === 'feed')
+                    this.issueFeed(o, step.gtin, step.from, step.to, step.qty);
+                else
+                    this.issueProcess(o, step.operation, step.at);
+            }
+            if (plan.steps.length)
+                return; // 한 번에 한 라인씩 — 부품을 여러 라인이 동시에 다투지 않게
+        }
+    }
+    /** 이 오더가 굴리고 있는 생산 사슬이 있나 — 이송·가공·되돌리기 중 하나라도 열려 있으면 그렇다. */
+    hasOpenMakeChain(orderId) {
+        for (const t of this.tasks.values()) {
+            if (t.orderId !== orderId || t.status === 'completed')
+                continue;
+            if (t.kind === 'feed' || t.intent === 'process')
+                return true;
+            /* 만든 것을 들여놓는 적재도 사슬의 일부다 — 끝나기 전에 다시 발행하면 같은 부품을 또 끌어온다. */
+            if (t.kind === 'putaway' && t.orderId === orderId)
+                return true;
+        }
+        return false;
+    }
+    /** 지금 재고 — 판단 함수가 보는 형태로. */
+    stockLines() {
+        return [...this.items.values()]
+            .filter(i => i.gtin)
+            .map(i => ({ gtin: i.gtin, location: i.location, qty: i.qty ?? 1, sellable: i.disposition === DISP.sellable }));
+    }
+    /** 부품을 작업대로 — 팔레트 이동이므로 피킹과 같은 기제다(부분 소비는 코어가 한다). */
+    issueFeed(o, gtin, from, to, qty) {
+        const src = [...this.items.values()].find(i => i.gtin === gtin && i.location === from && i.disposition === DISP.sellable);
+        if (!src)
+            return;
+        /* 이송 중에 다른 오더가 같은 팔레트를 집지 않게 예약으로 바꾼다 — 코어의 자재 게이트는
+           처분을 보지 않지만, 이 커널의 `allocate` 는 `sellable` 만 집으므로 이것으로 충돌을 막는다. */
+        src.disposition = DISP.reserved;
+        void qty; // 팔레트 단위로 옮긴다 — 필요량은 코어가 소비 시점에 부분 취득한다
+        this.pushTask(o, 'feed', src.epc, from, to);
+    }
+    /** 가공 — 작업 종류를 **오퍼레이션 키**로 둔다(코어가 그 키로 명세를 찾는다). */
+    issueProcess(o, operation, at) {
+        /* 물품을 지목하지 않는다 — 클래스+수량 소비/산출이므로 주체가 팔레트 하나가 아니다.
+           코어의 작업 게이트는 빈 `itemEpc` 를 견딘다(`t.itemEpc && …` 조건부 확인). */
+        /* **의도를 process 로 밝힌다** — 코어가 이 표시로 이동(모션)과 변환을 가르고, 이 커널의 완료 훅도
+           그것으로 판단한다. "선언된 오퍼레이션인가" 로 가르면 산출을 선언한 이동 작업까지 삼킨다. */
+        this.pushTask(o, operation, '', at, at, 'process');
+    }
+    pushTask(o, kind, itemEpc, from, to, intent) {
+        const id = `task-${++this.taskSeq}`;
+        const task = {
+            id, kind, status: 'created', itemEpc, fromNode: from, toNode: to, resource: null, remainingMs: 0,
+            durationMs: this.durationOf({ kind, fromNode: from, toNode: to }, TRAVEL_MS),
+            ...(intent ? { intent } : {}),
+            ...(o ? { orderId: o.id } : {})
+        };
+        this.tasks.set(id, task);
+        this.emitTask(task);
+    }
+    /**
+     * 가공 완료 — 코어가 이미 소비(시작)와 산출(완료 직전)을 실행했다. 남은 일은 만든 것을 **재고로
+     * 들여놓는 것**이다: 산출물은 `in_progress` 로 태어나 팔 수 있는 재고가 아니다.
+     *
+     * ── 왜 팔레트로 묶나 ───────────────────────────────────────────────────────
+     * 코어의 산출은 **클래스+수량 줄**이고 그 키에는 자리가 박혀 있다(`품목@자리`). 창고의 출고 경로는
+     * 직렬 물류단위(팔레트 SSCC)를 다루므로, 그 줄을 그대로 출고에 태우면 키를 EPC 로 착각해 조회가
+     * 깨진다(실제로 그렇게 터졌다). 억지로 태우면 EPCIS 에도 **EPC 가 아닌 문자열**이 `epcList` 로
+     * 나가는데, 그것은 코어가 산출에서 경계한 바로 그 일이다.
+     *
+     * 그래서 만든 물건을 **입고가 하는 것과 같은 방식**으로 들여놓는다: 팔레트(SSCC)를 만들고 그 안에
+     * 세트 N개를 담는다(AggregationEvent). 현장에서도 가공물은 팔레트에 실려 보관으로 간다.
+     * 그 뒤는 기존 경로 그대로다 — `putaway` 로 보관 자리에 넣으면 판매 가능이 된다.
+     */
+    onProcessComplete(t) {
+        const made = (t.materialActual ?? []).filter(m => m.use === 'produced');
+        const order = t.orderId ? this.orders.get(t.orderId) : undefined;
+        const at = t.toNode;
+        for (const m of made) {
+            const key = subLotIdOf(m.definitionId, at);
+            const row = this.items.get(key);
+            if (!row)
+                continue; // 누가 이미 소비했다 — 없는 것을 만들어 내지 않는다
+            const qty = row.qty ?? 0;
+            if (qty <= 0)
+                continue;
+            /* 클래스 줄을 팔레트로 바꾼다 — 자리 점유는 줄 하나에서 줄 하나로(늘지 않는다). */
+            this.items.delete(key);
+            const pallet = ssccUri(COMPANY_PREFIX, ++this.epcSeq);
+            const qtyList = [{ epcClass: m.definitionId, quantity: qty }];
+            this.items.set(pallet, { epc: pallet, gtin: m.definitionId, qty, location: at, disposition: DISP.in_progress });
+            const eventTime = this.now();
+            this.emit(aggregationEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.packing, parentID: pallet, childQuantityList: qtyList, readPoint: at }));
+            this.emit(objectEvent({ eventTime, action: 'ADD', bizStep: BIZSTEP.packing, disposition: DISP.in_progress, epcList: [pallet], quantityList: qtyList, readPoint: at, bizLocation: at }));
+            /* 보관으로 — `putaway` 완료가 판매 가능으로 표시하고 storing 관측을 낸다(입고와 같은 걸음). */
+            const storage = this.locationByType('storage');
+            if (storage)
+                this.pushTask(order, 'putaway', pallet, at, storage.id);
+        }
+    }
     /** 전량 피킹 → packing(조립)·staging·shipping 마감. 화물 사이트 이탈, 백오더 잔량 재할당. */
     finalizeOrder(order, staging) {
         const shipDock = this.locationByType('dock-ship') ?? staging;

package/dist/make-to-order.d.ts

@@ -0,0 +1,58 @@
+import type { OperationDef } from './domain-definition.ts';
+/** 이 판단이 보는 재고 한 줄 — 무엇이 어디에 얼마나, 팔 수 있나. */
+export interface StockLine {
+    /** 품목 식별자(GTIN). */
+    gtin: string;
+    /** 지금 있는 자리. */
+    location: string;
+    /** 수량(개수). */
+    qty: number;
+    /** 팔 수 있는 상태인가 — 아니면 예약·가공 중이다. */
+    sellable: boolean;
+}
+/** 자리 하나 — 타입으로 역할을 안다(작업대인가 보관인가). */
+export interface LocationLine {
+    id: string;
+    type: string;
+}
+/** 발행할 걸음. */
+export type MakeStep = 
+/** 부품을 작업대로 옮긴다 — 자재가 작업 자리에 있어야 소비되기 때문이다. */
+{
+    step: 'feed';
+    gtin: string;
+    from: string;
+    to: string;
+    qty: number;
+}
+/** 가공한다 — 코어가 소비(시작)·산출(완료)을 실행한다. */
+ | {
+    step: 'process';
+    operation: string;
+    at: string;
+};
+export interface MakePlan {
+    /** 지금 발행할 걸음들. 비어 있으면 발행할 것이 없다(기다리는 중이거나 만들 수 없다). */
+    steps: MakeStep[];
+    /**
+     * 왜 아무것도 발행하지 않았나 — **조용히 아무 일도 없는 상태를 남기지 않는다.**
+     * `not-producible` 만들 방법이 선언되지 않았다 · `waiting-feed` 부품이 오는 중 ·
+     * `short-materials` 부품 자체가 부족하다(만들 수 없다) · `no-station` 공정 자리가 없다.
+     */
+    reason?: 'not-producible' | 'waiting-feed' | 'short-materials' | 'no-station';
+}
+/** 품목 → 그것을 산출하는 공정. 선언에서 파생한다(코드에 표를 두지 않는다). */
+export declare function producedByIndex(ops: readonly OperationDef[]): Map<string, OperationDef>;
+/**
+ * 부족한 품목을 만들기 위해 **지금** 발행할 걸음을 정한다.
+ *
+ * @param gtin      부족한 품목(오더가 요구하는 것).
+ * @param shortQty  부족 수량.
+ * @param ops       이 트윈에 선언된 오퍼레이션들.
+ * @param stock     현재 재고.
+ * @param locations 자리 목록(공정 자리 해소용).
+ *
+ * 한 번에 **한 걸음 종류만** 낸다: 부품이 아직 작업대에 다 오지 않았으면 이송만 내고 가공은 다음에
+ * 낸다. 두 걸음을 한꺼번에 내면 가공이 부품 없이 시작을 시도하고, 코어가 거절하는 작업이 큐에 쌓인다.
+ */
+export declare function planMakeToOrder(gtin: string, shortQty: number, ops: readonly OperationDef[], stock: readonly StockLine[], locations: readonly LocationLine[]): MakePlan;