@operato/twin-kernel 0.0.4 → 0.0.6

package/dist/flow-engine.js

@@ -10,7 +10,7 @@
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowNode 단일 base 방향과 정합.)
  */
 import { OP_EVENT, CMD } from "./contract.js";
-import { transformationEvent, aggregationEvent, objectEvent } from "./epcis.js";
+import { transformationEvent, aggregationEvent, objectEvent, DISP } from "./epcis.js";
 const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z');
 function mulberry32(seed) {
     let a = seed >>> 0;
@@ -23,6 +23,94 @@ function mulberry32(seed) {
     Object.defineProperty(fn, 'state', { get: () => a, set: (v) => { a = v >>> 0; } });
     return fn;
 }
+/**
+ * 주목신호 계산(순수) — State 스냅샷(movers/nodes/orders)에서 attentions 파생.
+ * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
+ * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
+ */
+export function deriveAttentions(view, acked) {
+    // 언어 중립: kind + params(원시값) + 조치 code 만 방출. 사람이 읽는 title/detail/rationale/라벨은
+    // 표현계층(클라 i18next)이 kind/code 로 렌더한다(무방언·다국어 — design/plans/i18n.md L3).
+    const out = [];
+    for (const m of view.movers) {
+        if (m.status === 'down') {
+            out.push({
+                id: `breakdown:${m.id}`, kind: 'breakdown', severity: 'critical',
+                anchor: { moverId: m.id, nodeId: m.location },
+                params: { moverId: m.id, ...(m.location ? { nodeId: m.location } : {}) },
+                recommendedActions: [
+                    { code: 'act.repair', command: CMD.resourceRepair, args: { resourceId: m.id } },
+                    { code: 'act.hold-until-repair', command: CMD.resourceHold, args: { resourceId: m.id } }
+                ],
+                suggestedAction: { code: 'act.repair', command: CMD.resourceRepair, args: { resourceId: m.id } }
+            });
+        }
+    }
+    for (const n of view.nodes) {
+        if ((n.capacity ?? 0) > 0) {
+            const r = (n.occupancy ?? 0) / n.capacity;
+            if (r >= 0.9) {
+                const saturated = r >= 1;
+                out.push({
+                    id: `bottleneck:${n.id}`, kind: 'bottleneck', severity: saturated ? 'high' : 'medium',
+                    anchor: { nodeId: n.id },
+                    params: { nodeId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100), saturated: saturated ? 1 : 0 },
+                    recommendedActions: [{ code: 'advice.add-resource' }, { code: 'advice.downstream-priority' }]
+                    // 권고만(command 없음) — 표현계층이 advice.* 코드로 렌더
+                });
+            }
+        }
+    }
+    for (const m of view.movers) {
+        const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
+        if (total >= 10) {
+            const rate = (m.scrapCount ?? 0) / total;
+            if (rate >= 0.15)
+                out.push({
+                    id: `scrap:${m.id}`, kind: 'scrap-high', severity: rate >= 0.3 ? 'high' : 'medium',
+                    anchor: { moverId: m.id, nodeId: m.location },
+                    params: { moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100) },
+                    recommendedActions: [
+                        { code: 'act.hold-for-inspection', command: CMD.resourceHold, args: { resourceId: m.id } },
+                        { code: 'act.reset-metrics', command: CMD.resourceResetMetrics, args: { resourceId: m.id } }
+                    ],
+                    suggestedAction: { code: 'act.hold-for-inspection', command: CMD.resourceHold, args: { resourceId: m.id } }
+                });
+        }
+    }
+    for (const o of view.orders) {
+        if (o.held)
+            out.push({
+                id: `hold:${o.id}`, kind: 'hold', severity: 'medium',
+                anchor: { orderId: o.id },
+                params: { orderId: o.id },
+                recommendedActions: [{ code: 'act.resume-order', command: CMD.orderResume, args: { orderId: o.id } }],
+                suggestedAction: { code: 'act.resume-order', command: CMD.orderResume, args: { orderId: o.id } }
+            });
+    }
+    if (acked)
+        for (const a of out)
+            if (acked.has(a.id))
+                a.state = 'acknowledged';
+    return out;
+}
+/**
+ * OEE 공식(순수) — 누적 카운터 + 현재 시각 → OEE. sim(oeeOf)과 live 가 **공유하는 계산 층**(face2-inbound-live §1.1).
+ * ⚠ attentions 와 달리: 입력(카운터)이 관측 State·이벤트에 없다 → live 는 카운터를 텔레메트리(정확) 또는
+ *    이벤트 누적기(근사)로 별도 공급해야 한다. 공식만 공유되고 입력원은 live 데이터-생산 결정.
+ */
+export function computeOee(c, nowMs) {
+    const planned = Math.max(0, nowMs - (c.metricsSinceMs ?? 0) - (c.holdMs ?? 0));
+    const uptime = Math.max(0, planned - c.setupMs - c.downMs); // 가용시간(셋업·고장 제외)
+    const availability = planned > 0 ? uptime / planned : 1;
+    const performance = uptime > 0 ? Math.min(1, c.runMs / uptime) : (c.runMs > 0 ? 1 : 0);
+    const totalQ = c.goodCount + c.scrapCount;
+    const quality = totalQ > 0 ? c.goodCount / totalQ : 1;
+    return {
+        availability, performance, quality, overall: availability * performance * quality,
+        runMs: c.runMs, setupMs: c.setupMs, downMs: c.downMs, idleMs: Math.max(0, uptime - c.runMs), goodCount: c.goodCount, scrapCount: c.scrapCount
+    };
+}
 export class FlowEngine {
     tenantId;
     nodes = new Map();
@@ -52,7 +140,7 @@ export class FlowEngine {
     // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
     loadBoard(def) {
         for (const n of def.nodes)
-            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, occupancy: 0, status: 'idle' });
+            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, occupancy: 0, status: 'idle', parentId: n.parentId });
         for (const m of def.movers) {
             const mover = { id: m.id, kind: m.kind, location: m.homeNode, status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 };
             if (m.mtbfMs !== undefined) {
@@ -63,6 +151,60 @@ export class FlowEngine {
             this.movers.set(m.id, mover);
         }
     }
+    /**
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 무버 추가. loadBoard 무버 삽입과 동일 규약.
+     * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
+     */
+    addMover(m) {
+        if (this.movers.has(m.id))
+            return;
+        const mover = { id: m.id, kind: m.kind, location: m.homeNode, status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 };
+        if (m.mtbfMs !== undefined) {
+            mover.mtbfMs = m.mtbfMs;
+            mover.mttrMs = m.mttrMs;
+            mover.nextFailureMs = this.sampleExp(m.mtbfMs);
+        }
+        this.movers.set(m.id, mover);
+    }
+    /**
+     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·무버·노드)과
+     * 저널 오더(원값+라인)로 이 커널의 맵을 채운다. tick 으로 만든 게 아니라 "현재 관측된 현실"을 심어
+     * 이후 fork/tick 으로 예측한다. 라이브 런타임은 여전히 projector 미러 — 이 커널은 예측용 임시본.
+     * 오더는 남은 데맨드(라인별 requested-fulfilled)를 'created' 로 복원(현재 재고에서 재계획).
+     * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
+     */
+    hydrateObserved(snap, orders = []) {
+        for (const n of snap.nodes)
+            this.nodes.set(n.id, { id: n.id, type: n.type, capacity: n.capacity ?? 0, occupancy: n.occupancy ?? 0, status: 'idle', parentId: n.parentId });
+        this.items.clear();
+        for (const it of snap.items)
+            this.items.set(it.epc, { epc: it.epc, location: it.location, disposition: it.disposition ?? DISP.sellable, gtin: it.gtin, qty: it.qty ?? 1 });
+        for (const m of snap.movers)
+            this.movers.set(m.id, { id: m.id, kind: m.kind, location: m.location ?? '', status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 });
+        for (const o of orders) {
+            const lines = (o.lines ?? []).map(l => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter(l => l.requested > 0);
+            const remaining = lines.reduce((s, l) => s + l.requested, 0);
+            if (remaining <= 0)
+                continue; // 이미 이행 완료 → 예측 대상 아님
+            this.orders.set(o.orderId, { id: o.orderId, kind: o.kind, status: 'created', requested: remaining, fulfilled: 0, bizTransaction: '', allocated: [], picked: [], shipmentEpc: null, lines });
+        }
+    }
+    /** what-if 구성 변주 — 노드 용량 변경(fork 대상). 존재하면 true. */
+    setNodeCapacity(nodeId, capacity) {
+        const n = this.nodes.get(nodeId);
+        if (!n)
+            return false;
+        n.capacity = Math.max(0, capacity);
+        return true;
+    }
+    /**
+     * forecast 몬테카를로 — fork 의 RNG 만 재시드(시나리오·상태·gens·in-flight 는 보존).
+     * "현재 조건 지속"을 유지한 채 **미래 확률만** 변주(도착·고장 타이밍 등) → run 마다 다른 표본.
+     * (monteCarloForecast 은 scenario.load 로 gens 를 갈아끼우므로 "현재 조건"이 깨진다 — 그 대안.)
+     */
+    reseed(seed) {
+        this.rng = mulberry32(seed >>> 0);
+    }
     onEvent(handler) {
         this.handlers.push(handler);
         return () => { const i = this.handlers.indexOf(handler); if (i >= 0)
@@ -73,27 +215,105 @@ export class FlowEngine {
      * 도메인 커맨드(order.release 등)는 handleCommand 로 위임. 커맨드는 sim 상태를 변이하고
      * State 델타를 유발한다(command → 행위 → 관측 폐루프).
      */
+    _acked = new Set(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
     dispatch(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
-        const fail = (error) => ({ commandId: cmd.commandId, accepted: false, error });
+        // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
+        const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
         switch (cmd.type) {
             case CMD.orderHold:
             case CMD.orderResume: {
                 const orderId = cmd.args?.orderId;
                 const order = orderId ? this.orders.get(orderId) : undefined;
                 if (!order)
-                    return fail(`order 없음: ${orderId}`);
+                    return fail('order-not-found', { orderId: orderId ?? '' });
                 order.held = cmd.type === CMD.orderHold;
                 this.emitOrder(order);
                 return ok();
             }
+            case CMD.attentionAck: {
+                const id = cmd.args?.id;
+                if (id)
+                    this._acked.add(id);
+                return ok();
+            }
+            // Operable 코어 — 자원(설비·무버) 제어. capability-keyed(resourceId), 모든 operable 자원 공통.
+            case CMD.resourceHold:
+            case CMD.resourceResume: {
+                const m = this.movers.get(cmd.args?.resourceId ?? '');
+                if (!m)
+                    return fail('resource-not-found');
+                m.held = cmd.type === CMD.resourceHold; // 계획 정지 → 배정 스킵
+                this.emitMover(m);
+                return ok();
+            }
+            case CMD.resourceDown: {
+                const a = cmd.args;
+                const m = this.movers.get(a?.resourceId ?? '');
+                if (!m)
+                    return fail('resource-not-found');
+                if (m.status !== 'down') {
+                    m.status = 'down'; // 비계획 고장 주입 — 기존 고장 machinery(processFailures)가 downMs 누적·수리 처리
+                    m.repairUntilMs = this.clockMs + (Number(a?.durationMs) || m.mttrMs || 60_000);
+                    this.emitMover(m);
+                }
+                return ok();
+            }
+            case CMD.resourceRepair: {
+                const m = this.movers.get(cmd.args?.resourceId ?? '');
+                if (!m)
+                    return fail('resource-not-found');
+                if (m.status === 'down') {
+                    m.status = m.taskId ? 'busy' : 'idle'; // 진행중 task 있으면 재개(고장모델 수리 로직과 동형)
+                    m.repairUntilMs = undefined;
+                    if (m.mtbfMs !== undefined)
+                        m.nextFailureMs = this.clockMs + this.sampleExp(m.mtbfMs);
+                    this.emitMover(m);
+                }
+                return ok();
+            }
+            case CMD.resourceResetMetrics: {
+                const m = this.movers.get(cmd.args?.resourceId ?? '');
+                if (!m)
+                    return fail('resource-not-found');
+                m.runMs = 0;
+                m.setupMs = 0;
+                m.downMs = 0;
+                m.goodCount = 0;
+                m.scrapCount = 0;
+                m.holdMs = 0;
+                m.metricsSinceMs = this.clockMs; // 계측 창을 지금부터 재시작
+                this.emitMover(m);
+                return ok();
+            }
+            case CMD.resourceAdd: {
+                // 라이브 자원 추가(실제 act) — addMover(what-if 와 동일 경로)로 런타임에 무버 삽입 + equipment 델타 방출.
+                // 새 무버는 즉시 배정 대상(다음 tick). 유일 id 생성(충돌 회피). 좌표/persistence 는 호스트 몫(커널=위상만).
+                const a = cmd.args;
+                if (!a?.kind)
+                    return fail('kind-required');
+                if (!a?.homeNode || !this.nodes.has(a.homeNode))
+                    return fail('home-node-not-found', { homeNode: a?.homeNode ?? '' });
+                const count = Math.max(1, Math.min(50, Number(a.count) || 1));
+                let seq = this.movers.size;
+                for (let i = 0; i < count; i++) {
+                    let id = `${a.kind}-${++seq}`;
+                    while (this.movers.has(id))
+                        id = `${a.kind}-${++seq}`;
+                    this.addMover({ id, kind: a.kind, homeNode: a.homeNode });
+                    const m = this.movers.get(id);
+                    if (m)
+                        this.emitMover(m); // equipment.status 델타 → 상태/저널에 새 무버 반영
+                }
+                return ok();
+            }
             default:
                 return this.handleCommand(cmd);
         }
     }
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     handleCommand(cmd) {
-        return { commandId: cmd.commandId, accepted: false, error: `알 수 없는 커맨드: ${cmd.type}` };
+        return { commandId: cmd.commandId, accepted: false, errorCode: 'unknown-command', errorParams: { type: cmd.type }, error: `unknown-command: ${cmd.type}` };
     }
     scenario = {
         load: (def) => {
@@ -128,16 +348,32 @@ export class FlowEngine {
             nodes: [...this.nodes.values()].map(n => ({ ...n })),
             items: [...this.items.values()].map(i => ({ epc: i.epc, gtin: i.gtin, qty: i.qty, location: i.location, disposition: i.disposition, expiry: i.expiry })),
             movers: [...this.movers.values()].map(m => {
-                const s = { id: m.id, kind: m.kind, location: m.location, status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m) };
+                const s = { id: m.id, kind: m.kind, location: m.location, status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held };
                 const t = m.taskId ? this.tasks.get(m.taskId) : undefined;
                 if (t && t.status === 'in-progress' && t.intent !== 'process')
                     s.motion = { fromNode: t.fromNode, toNode: t.toNode, startedAtSimMs: this.clockMs - (t.durationMs - t.remainingMs), durationMs: t.durationMs, progress: this.progressOf(t), elapsedMs: t.durationMs - t.remainingMs };
                 return s;
             }),
-            tasks: [...this.tasks.values()].map(t => ({ id: t.id, kind: t.kind, status: t.status, itemRefs: [t.itemEpc], fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, progress: t.status === 'in-progress' ? this.progressOf(t) : undefined })),
-            orders: [...this.orders.values()].map(o => ({ id: o.id, kind: o.kind, status: o.status, progress: o.requested ? o.fulfilled / o.requested : 0, held: o.held }))
+            tasks: [...this.tasks.values()].map(t => ({ id: t.id, kind: t.kind, status: t.status, itemRefs: [t.itemEpc], fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, orderId: t.orderId, progress: t.status === 'in-progress' ? this.progressOf(t) : undefined })),
+            orders: [...this.orders.values()].map(o => ({ id: o.id, kind: o.kind, status: o.status, progress: o.requested ? o.fulfilled / o.requested : 0, held: o.held })),
+            attentions: this.computeAttentions()
         };
     }
+    /*
+     * 주목 신호 판단 — 상태(노드·무버·오더)에서 도메인 조건을 평가해 Attention 방출.
+     * severity=ISA-18.2 우선순위 계열, kind=도메인 라벨. UI 는 판단 안 함(임계값 여기 소유).
+     * 도메인별 추가 판단은 서브클래스가 override 로 확장(super.computeAttentions() 합성).
+     */
+    computeAttentions() {
+        // 계산 층은 순수 함수 deriveAttentions 로 위임 — sim(여기)과 live projector 미러가 공유(face2-inbound-live §1.1).
+        const out = deriveAttentions({ movers: [...this.movers.values()], nodes: [...this.nodes.values()], orders: [...this.orders.values()] }, this._acked);
+        // 확인(ack) 프루닝 — 사라진 조건은 ack 해제(재발 시 다시 active). 엔진 상태 변이라 여기 유지(marking 은 deriveAttentions).
+        const present = new Set(out.map(a => a.id));
+        for (const id of [...this._acked])
+            if (!present.has(id))
+                this._acked.delete(id);
+        return out;
+    }
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 굴려 forecast·발산(predicted vs actual) 검사에 쓴다.
@@ -266,19 +502,13 @@ export class FlowEngine {
             m.goodCount++;
         else
             m.scrapCount++;
+        // 품질 델타 방출 — live OEE 누적기가 good/scrap 을 정확 추적(equipment.status 는 quality 미포함). WMS/YMS 는 미호출→무영향.
+        this.emitOp(OP_EVENT.quality, { moverId: m.id, good, goodCount: m.goodCount, scrapCount: m.scrapCount });
     }
     /** 무버 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
     oeeOf(m) {
-        const planned = this.clockMs;
-        const uptime = Math.max(0, planned - m.setupMs - m.downMs); // 가용시간(셋업·고장 제외)
-        const availability = planned > 0 ? uptime / planned : 1;
-        const performance = uptime > 0 ? Math.min(1, m.runMs / uptime) : (m.runMs > 0 ? 1 : 0);
-        const totalQ = m.goodCount + m.scrapCount;
-        const quality = totalQ > 0 ? m.goodCount / totalQ : 1;
-        return {
-            availability, performance, quality, overall: availability * performance * quality,
-            runMs: m.runMs, setupMs: m.setupMs, downMs: m.downMs, idleMs: Math.max(0, uptime - m.runMs), goodCount: m.goodCount, scrapCount: m.scrapCount
-        };
+        // 순수 공식 computeOee 로 위임 — sim(여기)과 live 가 같은 계산 층 공유. planned 는 hold 제외(계획정지 OEE 무영향).
+        return computeOee(m, this.clockMs);
     }
     /** 정책에 넘길 특정 타입 노드의 관측 뷰 — 예약(그 노드로 향하는 in-flight task) 포함. */
     slotViews(nodeType) {
@@ -304,7 +534,7 @@ export class FlowEngine {
         for (const h of this.handlers)
             h(e);
     }
-    emitTask(t) { this.emitOp(OP_EVENT.task, { taskId: t.id, kind: t.kind, status: t.status, fromNode: t.fromNode, toNode: t.toNode, itemRefs: [t.itemEpc], resourceRef: t.resource ?? undefined }); }
+    emitTask(t) { this.emitOp(OP_EVENT.task, { taskId: t.id, orderId: t.orderId, kind: t.kind, status: t.status, fromNode: t.fromNode, toNode: t.toNode, itemRefs: [t.itemEpc], resourceRef: t.resource ?? undefined }); }
     emitMover(m, motion) { this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, motion }); }
     emitOrder(o) { this.emitOp(OP_EVENT.order, { orderId: o.id, kind: o.kind, status: o.status, requested: o.requested, fulfilled: o.fulfilled, held: o.held }); }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────
@@ -321,19 +551,27 @@ export class FlowEngine {
      */
     processFailures(dt) {
         for (const m of this.movers.values()) {
-            if (m.mtbfMs === undefined)
-                continue;
             if (m.status === 'down') {
+                // down 회계 + 수리 — 확률적 고장·강제 고장(resource.down) 공통. repairUntilMs 도래 시 복구.
                 m.downMs += dt;
-                if (this.clockMs >= (m.repairUntilMs ?? 0)) {
-                    m.status = m.taskId ? 'busy' : 'idle'; // 수리 완료 → 진행중 task 있으면 재개
+                if (m.repairUntilMs != null && this.clockMs >= m.repairUntilMs) {
+                    m.status = m.taskId ? 'busy' : 'idle'; // 진행중 task 있으면 재개
                     m.repairUntilMs = undefined;
-                    m.nextFailureMs = this.clockMs + this.sampleExp(m.mtbfMs);
+                    if (m.mtbfMs !== undefined)
+                        m.nextFailureMs = this.clockMs + this.sampleExp(m.mtbfMs);
                     this.emitMover(m);
                 }
+                continue;
             }
-            else if (this.clockMs >= (m.nextFailureMs ?? Infinity)) {
-                m.status = 'down'; // 고장 → 수리 대기
+            if (m.held) {
+                // 계획 정지(resource.hold) — 정지 시간 누적(OEE planned 에서 제외). 정지 중엔 고장 스케줄 진행 안 함.
+                if (m.status === 'idle')
+                    m.holdMs = (m.holdMs ?? 0) + dt;
+                continue;
+            }
+            // 확률적 고장 — mtbf 지정 무버만(미지정=고장 없음, rng 무소비 → byte-identical baseline).
+            if (m.mtbfMs !== undefined && this.clockMs >= (m.nextFailureMs ?? Infinity)) {
+                m.status = 'down';
                 m.repairUntilMs = this.clockMs + this.sampleExp(m.mttrMs ?? m.mtbfMs);
                 m.nextFailureMs = undefined;
                 this.emitMover(m);
@@ -344,10 +582,13 @@ export class FlowEngine {
     generate() {
         for (const g of this.gens) {
             while (this.clockMs >= g.nextMs) {
-                if (g.spec.kind === 'inbound-arrival')
-                    this.onArrival(g.spec);
-                else if (g.spec.kind === 'outbound-order')
+                // 자극 클래스(공급/수요)로 hook 분기 — 도메인 kind 라벨이 아니라 stimulus 로 라우팅(무방언).
+                // stimulus 미지정 시 레거시 kind 로 추론(하위호환). 도메인은 kind 를 자유 명명하고 stimulus 로 분류.
+                const stimulus = g.spec.stimulus ?? (g.spec.kind === 'outbound-order' ? 'order' : 'arrival');
+                if (stimulus === 'order')
                     this.onOrder(g.spec);
+                else
+                    this.onArrival(g.spec);
                 g.nextMs += this.intervalMs(g.spec);
             }
         }
@@ -369,7 +610,7 @@ export class FlowEngine {
                 continue;
             }
             // resourceType 있으면 그 kind 무버만; 없으면 아무 유휴 무버.
-            const mover = [...this.movers.values()].find(m => m.status === 'idle' && (t.resourceType === undefined || m.kind === t.resourceType));
+            const mover = [...this.movers.values()].find(m => m.status === 'idle' && !m.held && (t.resourceType === undefined || m.kind === t.resourceType));
             if (!mover)
                 continue; // 맞는 유휴 자원 없음 → 다음 task(break 아님: 다른 타입은 가용할 수 있음)
             // 체인지오버: task 의 changeoverKey 가 무버 직전 키와 다르면 셋업 부착(첫 작업은 셋업 없음).

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './contract.ts';
+export * from './domain-definition.ts';
 export * from './counterfactual.ts';
 export * from './forecast.ts';
 export * from './twin-observer.ts';
@@ -6,6 +7,7 @@ export * from './event-journal.ts';
 export * from './divergence.ts';
 export * from './epcis.ts';
 export * from './wms-profile.ts';
+export * from './capability.ts';
 export * from './domain-catalog.ts';
 export * from './allocation-policy.ts';
 export * from './duration-estimator.ts';
@@ -17,4 +19,5 @@ export * from './mes-profile.ts';
 export * from './flow-engine.ts';
 export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
-export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS } from './mes-kernel.ts';
+export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';
+export type { MesDefinitionSpec } from './mes-kernel.ts';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./contract.js";
+export * from "./domain-definition.js";
 export * from "./counterfactual.js";
 export * from "./forecast.js";
 export * from "./twin-observer.js";
@@ -6,6 +7,7 @@ export * from "./event-journal.js";
 export * from "./divergence.js";
 export * from "./epcis.js";
 export * from "./wms-profile.js";
+export * from "./capability.js";
 export * from "./domain-catalog.js";
 export * from "./allocation-policy.js";
 export * from "./duration-estimator.js";
@@ -17,4 +19,4 @@ export * from "./mes-profile.js";
 export * from "./flow-engine.js";
 export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
-export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS } from "./mes-kernel.js";
+export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";

package/dist/kernel.js

@@ -72,7 +72,7 @@ export class WmsKernel extends FlowEngine {
             const a = cmd.args;
             const lines = a?.lines ?? (a?.gtin ? [{ gtin: a.gtin, qty: a.qty ?? 1 }] : []);
             if (lines.length === 0)
-                return { commandId: cmd.commandId, accepted: false, error: 'order.release: gtin 또는 lines 필요' };
+                return { commandId: cmd.commandId, accepted: false, errorCode: 'order-release-needs-lines', error: 'order.release: gtin or lines required' };
             this.createSalesOrder(lines);
             return { commandId: cmd.commandId, accepted: true };
         }

package/dist/mes-kernel.d.ts

@@ -1,7 +1,8 @@
-import type { GeneratorSpec } from './contract.ts';
+import type { GeneratorSpec, Command, CommandAck } from './contract.ts';
 import type { AllocationPolicy } from './allocation-policy.ts';
 import { FlowEngine } from './flow-engine.ts';
 import type { FlowOrder, FlowTask } from './flow-engine.ts';
+import type { DomainDefinition } from './domain-definition.ts';
 /** 편의 — 시나리오 skuMix 로 쓸 부품 클래스. */
 export declare const MES_PART_GTINS: {
     partA: string;
@@ -12,17 +13,60 @@ export declare const MES_PRODUCT_GTINS: {
     p1: string;
     p2: string;
 };
+/** 레거시 MES 제품 목록(gtin+라벨) — mes.changeover 대상 제품 소싱용. 정의-구동 전환 시 recipe 출력으로 교체. */
+export declare const MES_PRODUCTS: {
+    gtin: string;
+    label: string;
+}[];
+/**
+ * 정의-구동 모드 스펙 — 커널이 도메인 정의(추상)를 소비. 구체 gtin 은 여기서:
+ * 자재 키 → GS1 item reference 바인딩 + company prefix (정의는 gtin 을 모른다, plan §게이트 (b)).
+ */
+export interface MesDefinitionSpec {
+    definition: DomainDefinition;
+    /** 자재 키 → GS1 item reference. 구체 gtin = sgtin(companyPrefix, itemRef). */
+    binding: Record<string, string>;
+    companyPrefix: string;
+    /** 사용할 recipe 키(미지정 시 첫 recipe). */
+    recipeKey?: string;
+}
 export declare class MesKernel extends FlowEngine {
     private wipSeq;
     private prodSeq;
-    constructor(tenantId: string, policy?: AllocationPolicy);
+    /** 정의-구동 모드(선택). 미지정 시 레거시 하드코딩 경로 — byte-identical. */
+    private mesSpec?;
+    constructor(tenantId: string, policy?: AllocationPolicy, mesSpec?: MesDefinitionSpec);
     private productOf;
+    /**
+     * MES 도메인 커맨드(Tier 2) — mes.changeover: 설비를 제품 gtin 으로 강제 전환.
+     * 자동 체인지오버(task.changeoverKey 상이 시 셋업)의 수동 버전 — 운영자가 사전 전환(툴링 교체) 지시.
+     * 이미 그 제품이면 no-op, 아니면 셋업(SETUP_MS, OEE 가용성 손실) + lastChangeoverKey 각인
+     * (이후 그 제품 task 는 자동 셋업 생략). command → 변이 → State 델타(폐루프).
+     */
+    protected handleCommand(cmd: Command): CommandAck;
     /** 부품 수령(다품종) — skuMix 의 gtin 으로 부품 종류 결정. */
     protected onArrival(spec: GeneratorSpec): void;
     /** 작업지시 — 제품 2종 교대(체인지오버 유발). 제품 gtin 을 오더에 기록. */
     protected onOrder(_spec: GeneratorSpec): void;
-    /** 할당 — 제품 BOM 각 라인의 부품 예약(하나라도 부족하면 대기) + op1(cut, 체인지오버 셋업). */
+    /** 할당 — 제품 BOM 각 라인의 부품 예약(하나라도 부족하면 대기) + 라우트 첫 스테이션(절단) 태스크. */
     protected allocate(o: FlowOrder): void;
-    /** op 완료 = 변환. cut: BOM 부품 소비 → WIP. weld: WIP → 완제품(수율: 양품/불량 → OEE 품질 보고). */
+    /** 라우트 스테이션 태스크 발행(공통) — 제자리 가공(process), 이종 자원, 제품 전환 셋업. */
+    private emitStation;
+    /** op 완료 = 변환. 라우트 인덱스로 분기: 첫=BOM 소비→WIP, 중간=WIP→WIP, 마지막(조립)=WIP→완성차(수율→OEE 품질). */
     protected onTaskComplete(t: FlowTask): void;
+    private recipeDef;
+    /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
+    private classOf;
+    private serialOf;
+    /** recipe.route → 오퍼레이션 시퀀스 해소. */
+    private routeOps;
+    /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 raw-store 에 생성. */
+    private onArrivalDef;
+    /** 정의 모드 작업지시 — 레시피 산출물 1개. */
+    private onOrderDef;
+    /** 정의 모드 할당 — 레시피 입력 BOM 전량 확보 후 첫 라우트 스텝 태스크. */
+    private allocateDef;
+    private emitStationDef;
+    /** 정의 모드 완료 — 라우트 인덱스: 중간=WIP 변환+다음 스텝, 마지막=완제품(수율). */
+    private onTaskCompleteDef;
 }