@operato/twin-kernel 0.3.0 → 0.4.0

package/dist/flow-engine.js

@@ -9,11 +9,24 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure } from "./contract.js";
+import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, priorityRank, dueStatusOf, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
-import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR } from "./epcis.js";
+import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP } from "./epcis.js";
 import { parseIsoDuration } from "./iso-duration.js";
+import { analyzeCapacity } from "./capacity.js";
 const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z');
+/**
+ * 선언한 유효 기간만 뽑는다 — 마스터가 말하지 않으면 필드를 만들지 않는다.
+ *
+ * `{ effectiveStart: undefined }` 를 넣으면 스냅샷 왕복·미러 비교에서 "선언했지만 비었다" 와
+ * "선언하지 않았다" 가 구별되지 않는다(적합성 하네스가 갈라짐으로 잡는다).
+ */
+function effectiveOnly(r) {
+    return {
+        ...(r.effectiveStart ? { effectiveStart: r.effectiveStart } : {}),
+        ...(r.effectiveEnd ? { effectiveEnd: r.effectiveEnd } : {})
+    };
+}
 function mulberry32(seed) {
     let a = seed >>> 0;
     const fn = (() => {
@@ -30,7 +43,9 @@ function mulberry32(seed) {
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
-export function deriveAttentions(view, acked) {
+export function deriveAttentions(view, acked, 
+/** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
+nowIso) {
     // 언어 중립: kind + params(원시값) + 조치 code 만 방출. 사람이 읽는 title/detail/rationale/라벨은
     // 표현계층(클라 i18next)이 kind/code 로 렌더한다(무방언·다국어 — design/plans/i18n.md L3).
     const out = [];
@@ -63,6 +78,55 @@ export function deriveAttentions(view, acked) {
             }
         }
     }
+    /*
+     * **일이 들어오는 속도를 처리 속도가 못 따라간다** — 자리 포화(`bottleneck`)와 다른 종류의 막힘이다.
+     *
+     * 실제로 이것을 놓쳤다. Rosarito 도장은 부스가 텅 비어 있었고(점유율 낮음) 대수가 모자랐다.
+     * 자리로 재는 규칙은 그런 공장을 "정상" 이라 답한다 — 오더는 무한히 쌓이는데 화면 어디에도
+     * 깨지는 지점이 없었고, 사람이 용량을 손으로 계산하고서야 알았다. **용량 부족은 조용하다.**
+     *
+     * 재는 방법은 스냅샷만으로 답할 수 있어야 한다(추세를 쌓아 두지 않는다). 그래서 같은 공정에서
+     * **기다리는 일과 하고 있는 일의 비**를 본다 — 처리 능력이 충분하면 대기가 길게 늘지 않는다.
+     * 공정이 아예 안 돌면(하는 일 0, 기다리는 일 여럿) 그것이 가장 강한 신호다.
+     *
+     * 공정 이름은 작업이 스스로 말하는 것(`kind`)을 쓴다. 설비 종류로 환산하지 않는다 — 그 대응은
+     * 현장마다 다르고, 커널이 그 방언을 알면 보편 계약이 깨진다.
+     */
+    const QUEUE_FLOOR = 5; // 이보다 얕은 줄은 정상 변동이다
+    /*
+     * **공장이 쉬는 동안 쌓이는 것은 신호가 아니다.** 주말·휴일·휴게 시간에 줄이 길어지는 것은 달력이
+     * 시킨 일이고, 월요일이면 빠진다. 그때마다 사람을 부르면 매주 토요일에 같은 경고가 떠서 — 진짜
+     * 막혔을 때의 경고까지 같이 무시하게 된다.
+     *
+     * 쉬는 중인지는 **설비가 이미 말하고 있다**(`offShift`, 달력에서 파생). 여기서 달력을 다시 읽지
+     * 않는다 — 두 벌이 되면 갈라진다. 설비를 아예 모르면 판단하지 않는다(줄만 보고 단정하지 않는다).
+     */
+    const shutdown = (view.equipment?.length ?? 0) > 0 && view.equipment.every(m => m.offShift);
+    if (view.tasks?.length && !shutdown) {
+        const waiting = new Map();
+        const working = new Map();
+        for (const t of view.tasks) {
+            const bucket = t.status === 'created' || t.status === 'assigned' ? waiting : t.status === 'in-progress' ? working : undefined;
+            if (bucket)
+                bucket.set(t.kind, (bucket.get(t.kind) ?? 0) + 1);
+        }
+        for (const [operation, queued] of waiting) {
+            if (queued < QUEUE_FLOOR)
+                continue;
+            const active = working.get(operation) ?? 0;
+            const ratio = queued / Math.max(active, 1);
+            if (active > 0 && ratio < 3)
+                continue;
+            out.push({
+                id: `work-backlog:${operation}`,
+                kind: 'work-backlog',
+                severity: active === 0 || ratio >= 6 ? 'high' : 'medium',
+                anchor: { operation },
+                params: { operation, queued, active, ratio: Math.round(ratio * 10) / 10 },
+                recommendedActions: [{ code: 'advice.add-resource' }, { code: 'advice.downstream-priority' }]
+            });
+        }
+    }
     for (const m of view.equipment) {
         const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
         if (total >= 10) {
@@ -90,6 +154,26 @@ export function deriveAttentions(view, acked) {
                 suggestedAction: { code: 'act.resume-order', command: CMD.orderResume, args: { orderId: o.id } }
             });
     }
+    /* 납기 초과 — **표준 `EndTime` 이 있어야 판정할 수 있다.** 없으면 신호를 만들지 않는다(없는 납기를
+       지연으로도 정시로도 말하지 않는다). 이미 끝난 오더는 대상이 아니다.
+       심각도는 얼마나 늦었는지로 가른다 — 방금 넘긴 것과 하루 넘긴 것을 같게 부르면 신호가 무의미해진다. */
+    for (const o of view.orders) {
+        if (o.status === 'completed' || o.status === 'fulfilled')
+            continue;
+        if (dueStatusOf(o, nowIso) !== 'late')
+            continue;
+        const overdueMs = Date.parse(nowIso) - Date.parse(o.endTime);
+        out.push({
+            id: `late:${o.id}`,
+            kind: 'order-late',
+            severity: overdueMs >= 3600_000 ? 'critical' : 'high',
+            anchor: { orderId: o.id },
+            params: { orderId: o.id, endTime: o.endTime, overdueMs, ...(o.priority !== undefined ? { priority: o.priority } : {}) },
+            /* 조치는 권고만 둔다 — 지연을 커널이 스스로 해소할 수단이 없다(자원을 늘리거나 우선순위를
+               올리는 것은 사람의 결정이다). 없는 조치를 만들어 붙이지 않는다. */
+            recommendedActions: [{ code: 'advice.raise-priority' }, { code: 'advice.add-resource' }]
+        });
+    }
     if (acked)
         for (const a of out)
             if (acked.has(a.id))
@@ -120,6 +204,11 @@ export class FlowEngine {
     equipment = new Map();
     /** 등급 정의(표준 `<X>Class`) — 상속·유효기간 판정의 재료. 선언 안 하면 비어 있고, 소속 그대로 판정한다. */
     classDefs = {};
+    /**
+     * 품목 정의 색인(표준 `MaterialDefinition`) — 단위 환산의 **유일한 근거**.
+     * 비어 있으면 환산하지 않는다(계수를 모르는데 값을 만들지 않는다).
+     */
+    materialDefs = new Map();
     /** 사람 — 선언하지 않으면 빈 맵(인원 제약 없는 트윈, 기존 거동). */
     persons = new Map();
     /** 물리 자산 — 선언하지 않으면 빈 맵(자산 제약 없는 트윈, 기존 거동). */
@@ -168,13 +257,14 @@ export class FlowEngine {
         this.boardDef = def;
         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 };
+        this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
+        this.materialDefs = new Map((def.materialDefinitions ?? []).filter(d => d?.id).map(d => [d.id, d]));
         for (const p of def.persons ?? [])
-            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', taskId: null, window: p.window, ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}) });
+            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', taskId: null, window: p.window, ...(p.workCalendar ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}), ...effectiveOnly(p) });
         for (const a of readBoardAssets(def))
-            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', taskId: null, ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}) });
+            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', taskId: null, ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}), ...effectiveOnly(a) });
         for (const m of readBoardEquipment(def)) {
-            const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window };
+            const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window, ...(m.workCalendar ? { workCalendar: m.workCalendar } : {}), ...effectiveOnly(m) };
             if (m.mtbfMs !== undefined) {
                 eq.mtbfMs = m.mtbfMs;
                 eq.mttrMs = m.mttrMs;
@@ -205,6 +295,23 @@ export class FlowEngine {
      * 오더는 남은 데맨드(라인별 requested-fulfilled)를 'created' 로 복원(현재 재고에서 재계획).
      * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
      */
+    /**
+     * **이어서 센다** — 재기동 뒤 저널을 이어 쓸 때.
+     *
+     * 커널은 리비전을 0부터 센다. 새로 시작하는 우주라면 맞지만, **이어지는 현실**(sim-world)에서는
+     * 그 번호가 이미 저널에 있는 행과 겹친다 — 같은 트윈에 revision 7이 두 개 생기고, 재생 순서가
+     * 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다. 조용히 깨지는 종류다(오류가 안 난다).
+     *
+     * 그래서 이어 쓰기 전에 마지막 번호를 알려 준다. **뒤로는 못 간다** — 뒤로 가는 것은 곧 겹치는
+     * 것이고, 그것을 허용하면 이 함수가 막으려던 일이 이 함수를 통해 일어난다.
+     */
+    resumeRevision(from) {
+        if (!Number.isFinite(from) || from < 0)
+            throw new Error(`이어 셀 리비전이 올바르지 않다: ${from}`);
+        if (from < this.revision)
+            throw new Error(`리비전을 뒤로 되돌릴 수 없다: ${this.revision} → ${from} (겹치는 번호가 생긴다)`);
+        this.revision = from;
+    }
     hydrateObserved(snap, orders = []) {
         /* **관측된 것을 버리지 않는다.** 예전에는 자리·설비 상태를 'idle' 로, OEE 누적을 0 으로 덮고
          * 물품의 로트·단위·소속·마스터데이터를 떨어뜨렸다. 씨앗이 잃은 것은 **예측도 모른다** —
@@ -214,10 +321,14 @@ export class FlowEngine {
         }
         this.items.clear();
         for (const it of snap.items) {
-            this.items.set(it.epc, {
+            /* **부분마다 한 줄로 심는다** — `epc` 로 키를 잡으면 같은 로트의 두 부분이 하나로 접혀
+               씨앗에서 재고가 줄어든다(§MaterialSubLot 에서 겪은 것과 같은 오류의 세 번째 자리). */
+            this.items.set(itemKeyOf(it), {
                 /* 품번 키·로트는 식별자에서 파생되므로 심지 않는다(스냅샷이 다시 낸다 — 두 벌을 두면 어긋난다). */
                 epc: it.epc, location: it.location, disposition: it.disposition ?? DISP.sellable,
-                gtin: it.gtin, qty: it.qty ?? 1, uom: it.uom,
+                ...(it.subLotId ? { subLotId: it.subLotId } : {}),
+                ...(it.definitionId ? { definitionId: it.definitionId } : {}),
+                gtin: it.gtin, qty: it.qty ?? 1, uom: it.uom, ...(it.quantities?.length ? { quantities: it.quantities } : {}),
                 parent: it.parent, carriedBy: it.carriedBy, expiry: it.expiry, ilmd: it.ilmd
             });
         }
@@ -234,32 +345,121 @@ export class FlowEngine {
              * 값을 그대로 이어받고, 없으면 0 에서 시작한다(꾸미지 않는다).
              */
             const oee = m.oee;
+            /* **마스터가 말한 것을 관측이 지우지 않는다.** 예전에는 이 자리에서 통째로 새 객체를 만들어
+             * 교대 캘린더·속성·유효 기간·계획정지를 **전부 버렸다.** 그 결과 라이브(관측) 커널은
+             * 근무 시간을 모르고(항상 가용), 폐기를 모르고, 속도를 몰라 이동시간을 상수로 떨어뜨렸다.
+             * 관측이 말하는 것(위치·상태·계측)만 덮고 **선언은 지킨다**. */
+            const prev = this.equipment.get(m.id);
             this.equipment.set(m.id, {
+                ...(prev ?? {}),
                 id: m.id, kind: m.kind, location: m.location ?? '', ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status ?? 'idle', taskId: null,
                 runMs: oee?.runMs ?? 0, setupMs: oee?.setupMs ?? 0, downMs: oee?.downMs ?? 0,
-                goodCount: oee?.goodCount ?? 0, scrapCount: oee?.scrapCount ?? 0
+                goodCount: oee?.goodCount ?? 0, scrapCount: oee?.scrapCount ?? 0,
+                /* 계획 정지를 이어받는다 — 잃으면 씨앗이 **정비 중인 설비를 가용으로 놓고** 미래를 굴린다
+                   (예측이 낙관 쪽으로 치우친다). 씨앗 왕복 대조가 이것을 잡았다. */
+                ...(m.held ? { held: true } : {}),
+                /* 관측 스냅샷이 들고 있는 것은 관측을 따른다(미러가 보드에서 읽어 실어 온다). */
+                ...(m.properties ? { properties: m.properties } : {}),
+                ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}),
+                ...effectiveOnly(m)
             });
         }
         /* 사람을 이어 붙인다 — **없으면 인원 요구가 영원히 채워지지 않는다.** 관측 상태에 사람이 있는데
          * 씨앗이 버리면, 인원을 요구하는 공정의 작업이 하나도 시작되지 못하고 예측이 멈춘다(0 명 < 2 명).
          * 배정 상태(busy/taskId)는 아래 작업 복원이 다시 세우므로 여기서는 등급·교대만 살린다. */
         for (const p of snap.persons ?? []) {
-            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', taskId: null });
+            const prev = this.persons.get(p.id);
+            this.persons.set(p.id, {
+                ...(prev ?? {}),
+                id: p.id, personnelClassIds: p.personnelClassIds ?? prev?.personnelClassIds, status: 'idle', taskId: null,
+                ...(p.location ? { location: p.location } : {}),
+                ...(p.properties ? { properties: p.properties } : {}),
+                ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}),
+                ...effectiveOnly(p)
+            });
         }
         /* 자산도 같다 — 잃으면 자산을 요구하는 작업이 영원히 못 나간다(빈 팔레트 0개 < 1개). */
         for (const a of snap.assets ?? []) {
-            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.location, status: 'idle', taskId: null, carrying: a.carrying });
+            const prev = this.assets.get(a.id);
+            this.assets.set(a.id, {
+                ...(prev ?? {}),
+                id: a.id, assetClassIds: a.assetClassIds ?? prev?.assetClassIds, location: a.location, status: 'idle', taskId: null, carrying: a.carrying,
+                ...(a.properties ? { properties: a.properties } : {}),
+                ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}),
+                ...effectiveOnly(a)
+            });
         }
         /* 진행 중이던 작업을 이어 붙인다 — 없으면 예측이 "일이 하나도 없는 현장" 에서 출발한다.
          * 남은 시간을 모르면 **진척을 꾸미지 않고** 미착수(created)로 되돌린다: 그 일이 남아 있다는 사실은
          * 지키면서, 얼마나 진행됐는지는 모른다고 말하는 쪽이 정직하다(커널이 다시 배정해 굴린다). */
+        /*
+         * **주체가 없는 작업은 되살리지 않는다.**
+         *
+         * 씨앗은 진행 중이던 작업을 이어 붙이는데, 그 작업이 가리키는 물품이 상태에 없을 수 있다
+         * (이미 소비·출하됐거나, 관측이 그 물품을 담지 못했다). 그런 작업을 살려 두면 완료 시점에
+         * "없는 물품을 옮기려" 하다 **예측 전체가 죽는다** — 실제로 그렇게 죽었다(정확도 추세 서버 오류).
+         *
+         * 그렇다고 조용히 버리지도 않는다: **몇 건을 왜 뺐는지 말한다.** 조용한 누락은 "일이 없었다" 로
+         * 읽히고, 그것이 예측을 낙관 쪽으로 기울인다.
+         */
+        /* 오더 원값은 이제 **스냅샷에 있다** — 따로 넘겨받은 것이 없으면 스냅샷에서 읽는다.
+         * (예전에는 상태가 progress 로 압축돼 호출부가 저널을 뒤져 원값을 넘겨야 했다.) */
+        const observedOrders = orders.length
+            ? orders
+            : (snap.orders ?? [])
+                .filter(o => o.requested !== undefined)
+                .map(o => ({
+                orderId: o.id, kind: o.kind, status: o.status, requested: o.requested, fulfilled: o.fulfilled ?? 0, held: o.held, lines: o.lines,
+                /* 약속한 시각과 우선순위를 함께 옮긴다 — 없으면 관측 커널이 **"늦었나" 를 판단할 재료가
+                   없다.** 라이브 트윈이 납기 초과를 한 번도 보고하지 못한 원인 중 하나였다. */
+                ...(o.endTime ? { endTime: o.endTime } : {}),
+                ...(o.startTime ? { startTime: o.startTime } : {}),
+                ...(o.priority !== undefined ? { priority: o.priority } : {})
+            }));
+        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);
+            /* **라인이 없는 오더를 조용히 빼지 않는다.** 예전에는 남은 양을 라인에서만 셌으므로, 품목 라인
+             * 없이 총량만 오는 오더(실 시스템에 흔하다)가 전부 `remaining=0` 이 되어 **사라졌다** — 라이브
+             * 커널에 오더가 아예 없으니 지연도 이행 예측도 나올 수 없었다. 라인이 없으면 총량으로 센다. */
+            const remaining = lines.length
+                ? lines.reduce((s, l) => s + l.requested, 0)
+                : Math.max(0, (o.requested ?? 0) - (o.fulfilled ?? 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,
+                /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
+                   씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
+                ...(o.held ? { held: true } : {}),
+                ...(o.endTime ? { endTime: o.endTime } : {}),
+                ...(o.startTime ? { startTime: o.startTime } : {}),
+                ...(o.priority !== undefined ? { priority: o.priority } : {})
+            });
+        }
+        /* 작업이 딛고 설 오더를 먼저 세운다 — 순서가 뒤바뀌면 아래 확인이 언제나 "없다" 로 답한다. */
+        const seededOrderIds = new Set(this.orders.keys());
+        let orphaned = 0;
         for (const t of snap.tasks ?? []) {
             if (t.status === 'completed')
                 continue;
+            const ref = t.itemRefs?.[0];
+            if (ref && !this.itemByRef(ref)) {
+                orphaned++;
+                continue;
+            }
+            /* 오더도 같다 — 이미 이행된 오더는 심지 않으므로(위 `remaining <= 0`), 그 오더에 딸린 작업만
+               남으면 완료 시점에 없는 오더를 딛는다. 심는 단계에서 함께 뺀다. */
+            if (t.orderId && !seededOrderIds.has(t.orderId)) {
+                orphaned++;
+                continue;
+            }
             const known = typeof t.remainingMs === 'number' && Number.isFinite(t.remainingMs);
             this.tasks.set(t.id, {
                 id: t.id, kind: t.kind,
                 status: known && t.status === 'in-progress' ? 'in-progress' : 'created',
+                /* 이미 일어난 자재 이동은 **씨앗에도 남는다** — 잃으면 실적이 재기동마다 지워진다. */
+                ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
                 itemEpc: t.itemRefs?.[0] ?? '',
                 fromNode: t.fromNode ?? '', toNode: t.toNode ?? '',
                 resource: known && t.status === 'in-progress' ? (t.resourceRef ?? null) : null,
@@ -291,19 +491,9 @@ export class FlowEngine {
                 }
             }
         }
-        /* 오더 원값은 이제 **스냅샷에 있다** — 따로 넘겨받은 것이 없으면 스냅샷에서 읽는다.
-         * (예전에는 상태가 progress 로 압축돼 호출부가 저널을 뒤져 원값을 넘겨야 했다.) */
-        const observedOrders = orders.length
-            ? orders
-            : (snap.orders ?? [])
-                .filter(o => o.requested !== undefined)
-                .map(o => ({ orderId: o.id, kind: o.kind, status: o.status, requested: o.requested, fulfilled: o.fulfilled ?? 0, held: o.held, lines: o.lines }));
-        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);
-            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 });
+        if (orphaned) {
+            console.warn(`[twin-kernel] seed skipped ${orphaned} in-flight task(s) whose item is no longer in state — ` +
+                'they cannot be continued (the item was consumed/shipped, or the observation did not carry it).');
         }
     }
     /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
@@ -332,7 +522,16 @@ export class FlowEngine {
      * 도메인 커맨드(order.release 등)는 handleCommand 로 위임. 커맨드는 sim 상태를 변이하고
      * State 델타를 유발한다(command → 행위 → 관측 폐루프).
      */
-    _acked = new Set(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
+    _acked = new Set();
+    /**
+     * 완료 시점에 **주체가 사라져 접은 작업 수** — 조용한 누락이 되지 않게 센다.
+     *
+     * 물품이 포장·출하·소비로 없어지는 것은 정상이지만, 그 물품을 향한 작업이 남아 있었다는 것은
+     * 상류에 어긋남이 있다는 신호다. 0 이 아니면 그 사실을 소비처가 볼 수 있어야 한다.
+     */
+    abandonedTasks = 0;
+    /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
+    _attentionSince = new Map(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
     dispatch(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
         // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
@@ -463,6 +662,7 @@ export class FlowEngine {
         return {
             revision: this.revision,
             simClockMs: this.clockMs,
+            nowTime: this.now(), // 트윈의 "지금" — 관측 모드면 마지막으로 들은 시각(§nowMs)
             /* 출처 표시 — 보드(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
              * 시뮬이 아무 표시도 안 하면 소비처가 두 스냅샷을 같은 규칙으로 읽지 못한다. */
             locations: [...this.locations.values()].map(n => {
@@ -473,7 +673,7 @@ export class FlowEngine {
             }),
             items: [...this.items.values()].map(i => this.itemState(i)),
             equipment: [...this.equipment.values()].map(m => {
-                const s = { id: m.id, kind: m.kind, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), origin: 'master', ...(this.offShift(m) ? { offShift: true } : {}) };
+                const s = { id: m.id, kind: m.kind, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), status: m.status, taskId: m.taskId ?? undefined, oee: this.oeeOf(m), held: m.held, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), origin: 'master', ...(this.offShift(m) ? { offShift: true, ...this.offReason(m) } : {}), ...this.effectivePart(m), ...(this.shiftOf(m) ? { shift: this.shiftOf(m) } : {}) };
                 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 };
@@ -487,6 +687,7 @@ export class FlowEngine {
                     st.properties = a.properties;
                 if (a.testSpecificationIds)
                     st.testSpecificationIds = a.testSpecificationIds;
+                Object.assign(st, this.effectivePart(a));
                 return st;
             }),
             persons: [...this.persons.values()].map(p => {
@@ -497,8 +698,14 @@ export class FlowEngine {
                     st.properties = p.properties;
                 if (p.testSpecificationIds)
                     st.testSpecificationIds = p.testSpecificationIds;
-                if (this.personOffShift(p))
+                if (this.personOffShift(p)) {
                     st.offShift = true;
+                    Object.assign(st, this.offReason(p));
+                }
+                const sh = this.shiftOf(p);
+                if (sh)
+                    st.shift = sh;
+                Object.assign(st, this.effectivePart(p));
                 return st;
             }),
             /* 스냅샷이 **델타보다 가난하면 안 된다** — 예전에는 소요·남은 시간을 빼고 내보내서, 이 스냅샷으로
@@ -512,13 +719,20 @@ export class FlowEngine {
                 ...(t.status === 'in-progress' ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: this.progressOf(t) } : {}),
                 ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
                 ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
-                ...(t.resources?.length ? { resources: t.resources.slice() } : {})
+                ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
+                ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
+                ...(t.priority !== undefined ? { priority: t.priority } : {}),
+                ...(t.startTime ? { startTime: t.startTime } : {}),
+                ...(t.endTime ? { endTime: t.endTime } : {})
             })),
             orders: [...this.orders.values()].map(o => ({
                 id: o.id, kind: o.kind, status: o.status,
                 progress: o.requested ? o.fulfilled / o.requested : 0,
                 requested: o.requested, fulfilled: o.fulfilled,
                 ...(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 } : {}),
+                ...(o.endTime ? { endTime: o.endTime } : {}),
                 held: o.held
             })),
             attentions: this.computeAttentions()
@@ -531,12 +745,34 @@ export class FlowEngine {
      */
     computeAttentions() {
         // 계산 층은 순수 함수 deriveAttentions 로 위임 — sim(여기)과 live projector 미러가 공유(face2-inbound-live §1.1).
-        const out = deriveAttentions({ equipment: [...this.equipment.values()], locations: [...this.locations.values()], orders: [...this.orders.values()] }, this._acked);
-        // 확인(ack) 프루닝 — 사라진 조건은 ack 해제(재발 시 다시 active). 엔진 상태 변이라 여기 유지(marking 은 deriveAttentions).
+        const now = this.now();
+        const out = deriveAttentions({
+            equipment: [...this.equipment.values()],
+            locations: [...this.locations.values()],
+            orders: [...this.orders.values()],
+            tasks: [...this.tasks.values()]
+        }, this._acked, now // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
+        );
         const present = new Set(out.map(a => a.id));
+        /*
+         * **조건이 처음 성립한 시각**을 기억해 붙인다(표준 `WorkAlert.TimeStamp`).
+         *
+         * 주목 신호는 매 스냅샷 다시 계산되는 파생값이라, 여기서 "지금" 을 찍으면 모든 신호가 언제나
+         * 방금 생긴 것으로 보인다(스냅샷 시각과 같은 값 = 정보 0). 처음 본 시각만이 "얼마나 오래됐나" 에
+         * 답한다 — 방금 찬 자리와 세 시간째 막힌 자리는 할 일이 다르다.
+         */
+        for (const a of out) {
+            const first = this._attentionSince.get(a.id) ?? now;
+            this._attentionSince.set(a.id, first);
+            a.timeStamp = first;
+        }
+        // 확인(ack)·시작 시각 프루닝 — 사라진 조건은 함께 지운다(재발하면 그때가 새 시작이다).
         for (const id of [...this._acked])
             if (!present.has(id))
                 this._acked.delete(id);
+        for (const id of [...this._attentionSince.keys()])
+            if (!present.has(id))
+                this._attentionSince.delete(id);
         return out;
     }
     /**
@@ -570,7 +806,43 @@ export class FlowEngine {
         return clone;
     }
     // ── 보호 헬퍼 (도메인 hook 에서 사용) ──────────────────────────────────────
-    now() { return new Date(BASE_EPOCH + this.clockMs).toISOString(); }
+    /**
+     * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
+     *
+     * ── 관측 모드에서 시계가 멈춰 있었다 ────────────────────────────────────
+     * `apply()` 는 `clockMs` 를 밀지 않는다(관측은 시간을 굴리지 않는다). 그래서 라이브 트윈의 "지금" 이
+     * **BASE_EPOCH(2026-01-01)에 얼어 있었다.** 실 이벤트는 실제 시각을 달고 오므로 결과가 이렇게 된다:
+     *  · **납기 초과를 영원히 보고하지 않는다** — 실 납기가 항상 미래로 보인다
+     *  · 폐기·도입예정 판정이 틀린다(§EffectivePeriod)
+     *  · 교대 판정이 틀린다(§offCalendarAt)
+     * 셋 다 "시각으로만 바뀌는 사실" 이라 같은 결함이었다. 그래서 기준을 **한 곳**으로 모은다.
+     *
+     * 관측 중이면 **마지막으로 들은 발생 시각**을 쓴다(미러의 `lastObservedMs` 와 같은 기준 — 규칙 한 벌).
+     * 아직 아무것도 못 들었으면 시뮬 기준으로 떨어진다(그때는 판정할 사실도 없다).
+     */
+    nowMs() {
+        const observed = this.observeMode ? this.observer?.lastObservedMs : undefined;
+        return observed ?? BASE_EPOCH + this.clockMs;
+    }
+    now() { return new Date(this.nowMs()).toISOString(); }
+    /**
+     * 자극이 선언한 **약속**을 오더 필드로 — 표준 `OperationsRequest.Priority`·`StartTime`·`EndTime`.
+     *
+     * **base 에 한 곳만 둔다.** 오더를 만드는 곳이 도메인마다 있어(WMS 판매오더·MES 작업지시·YMS
+     * 어포인트먼트) 각자 계산하면 시간축이나 규약이 갈린다 — 실제로 한 번 갈렸다(납기를 `clockMs` 로
+     * 재고 `now()` 와 비교해 갓 만든 오더가 56년 늦은 것으로 판정됐다).
+     *
+     * 선언이 없으면 **빈 객체**를 준다 — 없는 약속을 만들지 않는다.
+     */
+    promiseOf(spec) {
+        const at = this.now();
+        return {
+            ...(spec.priority !== undefined ? { priority: spec.priority } : {}),
+            ...(spec.promisedLeadMinutes !== undefined
+                ? { startTime: at, endTime: new Date(Date.parse(at) + spec.promisedLeadMinutes * 60_000).toISOString() }
+                : {})
+        };
+    }
     randInt(min, max) { return max <= min ? min : min + Math.floor(this.rng() * (max - min + 1)); }
     /**
      * 관측 구동(P0 스파이크) — **이벤트로 커널을 굴린다.**
@@ -629,6 +901,43 @@ export class FlowEngine {
             if (o?.key)
                 this.operationSpecs.set(o.key, o);
     }
+    /**
+     * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
+     * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
+     */
+    routeKeys() {
+        return undefined;
+    }
+    /**
+     * **이 공장이 하루 몇 대를 낼 수 있는가** — 굴려 보지 않고 답한다.
+     *
+     * 커널이 직접 답하는 이유: 필요한 사실이 전부 여기 있다(공정 명세·설비와 신뢰도·인원·물리자산·
+     * 자리·근무 달력·시각 기준). 밖에서 모으면 그 값을 옮겨 적게 되고, 한쪽만 바뀌는 순간 "충분하다"
+     * 가 조용히 거짓이 된다. 계산 자체는 순수 함수(`analyzeCapacity`)에 맡긴다.
+     *
+     * 달력은 **자원이 선언한 것**을 쓴다. 자원마다 다른 달력을 쓰는 현장이면 대표를 고를 수 없으므로
+     * 그 사실을 결과에 실어 보낸다(`mixedCalendars`) — 조용히 하나를 골라 계산하면 천장이 틀린 채로
+     * 그럴듯해 보인다.
+     */
+    capacity(opts) {
+        const calendars = new Map();
+        for (const m of this.equipment.values())
+            if (m.workCalendar?.length)
+                calendars.set(JSON.stringify(m.workCalendar), m.workCalendar);
+        const analysis = analyzeCapacity({
+            operations: [...this.operationSpecs.values()],
+            ...(this.routeKeys() ? { route: this.routeKeys() } : {}),
+            equipment: [...this.equipment.values()].map(m => ({ kind: m.kind, mtbfMs: m.mtbfMs, mttrMs: m.mttrMs })),
+            persons: [...this.persons.values()],
+            assets: [...this.assets.values()],
+            locations: [...this.locations.values()],
+            ...(calendars.size === 1 ? { calendar: [...calendars.values()][0] } : {}),
+            ...(this.boardDef?.utcOffsetMinutes !== undefined ? { utcOffsetMinutes: this.boardDef.utcOffsetMinutes } : {}),
+            sampleWeekStartMs: opts.sampleWeekStartMs,
+            unitsPerDay: opts.unitsPerDay
+        });
+        return { ...analysis, mixedCalendars: calendars.size > 1 };
+    }
     /**
      * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
      *
@@ -756,8 +1065,19 @@ export class FlowEngine {
             defaultDurations: operations.filter(o => o.duration === 'default').length
         };
     }
-    /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
+    /**
+     * `skuMix` 에서 weight 로 gtin 선택(rng) — 도착·오더 자극의 품목 결정.
+     *
+     * **빈 목록이면 고르지 않는다**(`undefined`). 예전에는 `mix[mix.length - 1].gtin` 으로 떨어져
+     * `mix[-1]` 이 undefined 가 되고 거기서 던졌다 — 그 예외가 서버까지 올라가 **정확도 추세 전체를
+     * 죽였다**(품목 구성을 선언하지 않은 자극 하나가 예측 전체를 껐다).
+     *
+     * 없는 품목을 지어내지 않는다: 무엇을 만들지 모르면 **만들지 않는 것**이 맞고, 부르는 쪽이
+     * 그 사실을 알고 건너뛴다.
+     */
     pickGtin(mix) {
+        if (!mix?.length)
+            return undefined;
         const total = mix.reduce((s, m) => s + m.weight, 0);
         let r = this.rng() * total;
         for (const m of mix) {
@@ -960,26 +1280,37 @@ export class FlowEngine {
             ...(t.personnel?.length ? { personnel: t.personnel.slice() } : {}),
             ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
             ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
+            /* 실제 자재 이동 — 인원·설비와 같은 채널(실적을 한 곳에서 읽는다). */
+            ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
             ...(t.durationMs ? { durationMs: t.durationMs } : {}),
+            ...(t.priority !== undefined ? { priority: t.priority } : {}),
+            ...(t.startTime ? { startTime: t.startTime } : {}),
+            ...(t.endTime ? { endTime: t.endTime } : {}),
             ...(inProgress ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: t.durationMs ? done / t.durationMs : undefined } : {})
         });
     }
     /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
     emitAsset(a) {
-        this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, status: a.status, location: a.location, taskId: a.taskId ?? undefined, carrying: a.carrying });
+        this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, status: a.status, location: a.location, taskId: a.taskId ?? undefined, carrying: a.carrying, ...effectiveOnly(a) });
     }
     emitPerson(p) {
-        this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? undefined, ...(p.location ? { location: p.location } : {}), ...(this.personOffShift(p) ? { offShift: true } : {}) });
+        this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? undefined, ...(p.location ? { location: p.location } : {}), ...effectiveOnly(p) });
+        /* `offShift` 를 더 이상 실어 보내지 않는다 — 교대 경계는 **이벤트 없이 시각만으로** 넘어가므로
+           전이 순간의 판정을 보내면 유휴로 경계를 지난 사람이 옛 값에 머문다. 미러는 같은 함수
+           (`offCalendarAt`)를 자기 시각으로 부른다(유효 기간과 같은 규율). */
     }
     /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
      *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
     emitEquipment(m, motion) {
-        this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), taskId: m.taskId ?? undefined, motion });
+        this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, status: m.status, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), taskId: m.taskId ?? undefined, motion, ...(m.held ? { held: true } : {}), ...effectiveOnly(m) });
     }
     /** 오더 델타 — **라인까지 싣는다.** 라인이 빠지면 미러가 남은 데맨드를 라인별로 재계획할 수 없다. */
     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,
+            ...(o.priority !== undefined ? { priority: o.priority } : {}),
+            ...(o.startTime ? { startTime: o.startTime } : {}),
+            ...(o.endTime ? { endTime: o.endTime } : {}),
             ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {})
         });
     }
@@ -1058,6 +1389,7 @@ export class FlowEngine {
             /* 인원과 같은 규칙 — 상속을 타고 닫아 판정하고 유효기간 밖은 제외한다. 요구는 등급 하나+수량. */
             a => a.status === 'idle' &&
                 !picked.includes(a.id) &&
+                !this.outOfEffect(a) && // 폐기한 팔레트는 풀에서 빠진다
                 (req.assetClass === undefined ||
                     classClosure(a.assetClassIds, this.classDefs.asset, this.now()).has(req.assetClass)));
             if (avail.length < want)
@@ -1082,7 +1414,7 @@ export class FlowEngine {
                 a.carrying = t.itemEpc;
                 /* 반대 방향도 맺는다 — 계약이 두 축을 다 정의했으므로 한쪽만 채우면 소비처가 물품에서
                  * 자산을 못 찾는다(자산 목록을 뒤져야 한다). */
-                const it = this.items.get(t.itemEpc);
+                const it = this.itemByRef(t.itemEpc);
                 if (it)
                     it.carriedBy = a.id;
             }
@@ -1116,6 +1448,223 @@ export class FlowEngine {
      * 여기서는 고르기만 하고 잡지 않는다: 설비까지 확보된 뒤 `assignCrew` 가 확정한다
      * (반쯤 잡고 실패하면 사람이 아무 일도 못 하면서 묶인다).
      */
+    /**
+     * 필요 자재를 확보한다 — **ISA-95 `OperationsSegment.MaterialSpecification`**(`use: 'consumed'`).
+     *
+     * ── 4대 자원 중 자재만 게이트가 없었다 ────────────────────────────────────
+     * 인원·자산·설비는 모자라면 기다리는데 **자재는 없어도 작업이 시작됐다.** 그래서 부품이 떨어져
+     * 라인이 서는 상황이 예측에 아예 나타나지 않았다 — 트레일러 조립 공장에서 그것은 가장 흔한 정지다.
+     *
+     * 인원·자산과 **같은 규칙**이다: 등급(또는 품목)으로 요구하고, **부분 확보 없이 전량 아니면 대기.**
+     * 자재는 **작업이 일어나는 자리에 있어야** 한다(다른 창고의 부품은 지금 쓸 수 없다).
+     *
+     * 소비 시점은 **작업 시작**이다 — 자재는 들어가는 순간 없어진다(완료 시점에 빼면 그 사이 다른
+     * 작업이 같은 부품을 또 잡는다). 산출(`produced`)은 여기서 다루지 않는다(완료 시점의 일이다).
+     */
+    claimMaterials(t) {
+        const need = (this.operationSpecs.get(t.kind)?.materialSpecification ?? []).filter(m => m.use === 'consumed');
+        if (!need.length)
+            return [];
+        const at = t.toNode;
+        const picked = [];
+        const takenSoFar = new Map();
+        for (const req of need) {
+            let remaining = Math.max(0, req.quantity ?? 0);
+            if (!remaining)
+                continue;
+            for (const it of this.items.values()) {
+                if (remaining <= 0)
+                    break;
+                if (it.location !== at)
+                    continue; // 그 자리에 있는 것만 — 다른 창고의 부품은 지금 쓸 수 없다
+                if (!this.materialMatches(it, req))
+                    continue;
+                const already = takenSoFar.get(it.epc) ?? 0;
+                const avail = Math.max(0, (it.qty ?? 1) - already);
+                if (avail <= 0)
+                    continue;
+                const take = Math.min(avail, remaining);
+                picked.push({ epc: it.epc, take });
+                takenSoFar.set(it.epc, already + take);
+                remaining -= take;
+            }
+            if (remaining > 0)
+                return null; // 한 줄이라도 모자라면 시작하지 않는다(부분 투입 없음)
+        }
+        return picked;
+    }
+    /** 이 물품이 명세를 만족하나 — 품목 지목이 우선, 없으면 등급(상속을 타고 닫는다). */
+    materialMatches(it, req) {
+        const defId = it.definitionId ?? it.gtin;
+        if (req.materialDefinition)
+            return defId === req.materialDefinition;
+        if (req.materialClass) {
+            const def = defId ? this.materialDefs.get(defId) : undefined;
+            return classClosure(def?.materialClassIds, this.classDefs.material, this.now()).has(req.materialClass);
+        }
+        return true; // 지목도 등급도 없으면 아무 자재나(명세가 그렇게 느슨하면 그대로 따른다)
+    }
+    /**
+     * 산출 자재를 만든다 — ISA-95 `MaterialSpecification`(`use: 'produced'`).
+     *
+     * **소비의 짝이다**: 자재는 작업이 시작될 때 들어가고 끝날 때 나온다. 산출이 없으면 조립 공정이
+     * 부품만 먹고 아무것도 내놓지 않아, 다음 공정이 영원히 재료를 기다린다(라인 전체가 한 칸에서 멈춘다).
+     *
+     * 산출물의 자리는 **작업이 끝난 자리**(`toNode`)다. 식별자는 품목 식별자에 작업 id 를 붙여 만든다 —
+     * **EPC 처럼 보이게 꾸미지 않는다**(상류가 준 직렬번호와 구별돼야 한다). 상류가 진짜 식별자를
+     * 말해 주면 그것이 들어올 자리는 관측 경로다.
+     *
+     * 같은 품목이 그 자리에 이미 있으면 **수량을 더한다** — 새 줄을 만들면 같은 자리의 같은 로트가
+     * 둘로 갈려 재고가 부푼다(§MaterialSubLot 에서 겪은 것과 반대 방향의 같은 오류).
+     */
+    produceMaterials(t) {
+        const made = (this.operationSpecs.get(t.kind)?.materialSpecification ?? []).filter(m => m.use === 'produced');
+        if (!made.length)
+            return;
+        for (const spec of made) {
+            const qty = Math.max(0, spec.quantity ?? 0);
+            if (!qty)
+                continue;
+            /* 무엇을 만드는지 말하지 않으면 만들지 않는다 — 이름 없는 물품을 재고에 올리면
+               그 뒤 누구도 그것이 무엇인지 답할 수 없다(등급만으로는 품목이 정해지지 않는다). */
+            const gtin = spec.materialDefinition;
+            if (!gtin)
+                continue;
+            const at = t.toNode;
+            /*
+             * **클래스 + 수량으로 낸다 — 일련번호를 지어내지 않는다.**
+             *
+             * 처음에는 산출물마다 `<gtin>#made-<taskId>` 같은 EPC 를 만들었다. 적합성 하네스가 잡았다:
+             * 미러는 그 문자열을 파싱해 품목을 알아내려는데 EPC 가 아니라서 **품번이 갈렸다.** 애초에
+             * 우리는 만든 물건의 일련번호를 **모른다** — 상류가 말해 줄 때만 안다. 모르는 것을 지어내면
+             * 그 뒤 추적이 전부 가짜 식별자 위에 선다.
+             *
+             * 그래서 비직렬 생산으로 낸다(표준이 허용하는 모양): 그 자리의 **새 총량**을 관측으로 알린다.
+             * 미러도 같은 규칙으로 읽으므로(자리마다 한 줄 — §MaterialSubLot) 두 구동이 같은 답을 낸다.
+             */
+            const key = subLotIdOf(gtin, at);
+            const existing = this.items.get(key);
+            const total = (existing?.qty ?? 0) + qty;
+            if (existing)
+                existing.qty = total;
+            else {
+                this.items.set(key, { epc: gtin, subLotId: key, gtin, qty: total, location: at, disposition: DISP.in_progress, ...(spec.uom ? { uom: spec.uom } : {}) });
+                const n = this.locations.get(at);
+                if (n)
+                    n.occupancy++;
+            }
+            this.recordMaterialActual(t, gtin, 'produced', qty, spec.uom);
+            this.emit(objectEvent({
+                eventTime: this.now(), action: 'ADD', bizStep: CBV_BIZSTEP.commissioning, disposition: DISP.in_progress,
+                epcList: [], quantityList: [{ epcClass: gtin, quantity: total, ...(spec.uom ? { uom: spec.uom } : {}) }],
+                readPoint: at, bizLocation: at
+            }));
+        }
+    }
+    /**
+     * 이 작업이 **딛고 선 것**이 아직 있나 — 없으면 무엇이 없는지 답한다.
+     *
+     * 작업은 혼자 서지 못한다: 옮길 **물품**과, (있다면) 그것을 시킨 **오더** 위에 선다. 진행 중에
+     * 둘 중 하나가 사라질 수 있다 — 물품은 포장·출하·소비로, 오더는 이미 이행돼 씨앗이 심지 않아서.
+     *
+     * 그때 도메인 훅은 없는 것을 딛으려다 던진다(`order.gtin` · `item.location`). 그 예외 하나가
+     * **예측 전체를 죽였다** — 사용자에게는 기능이 통째로 사라진 것으로 보였다. 그래서 완료 **전에**
+     * 여기서 묻고, 없으면 그 작업만 접는다.
+     */
+    missingContextOf(t) {
+        if (t.itemEpc && !this.itemByRef(t.itemEpc))
+            return 'item';
+        if (t.orderId && !this.orders.has(t.orderId))
+            return 'order';
+        if (!this.canComplete(t))
+            return 'domain';
+        return undefined;
+    }
+    /**
+     * 이 도메인이 이 작업을 **끝맺을 수 있나** — 코어가 모르는 조건은 도메인이 답한다.
+     *
+     * 코어는 물품과 오더까지만 안다. 그런데 도메인은 더 필요할 수 있다 — MES 는 완료 시점에 **오더와
+     * 제품 정의**를 딛고 서고, 그 중 하나만 없어도 던진다. 코어가 그 조건을 추측하면 도메인마다 다른
+     * 가정을 코어에 박게 되므로(방언), **묻는다.**
+     *
+     * 기본은 `true` — 대부분의 작업은 코어가 확인한 것으로 충분하다.
+     */
+    canComplete(_t) {
+        return true;
+    }
+    /**
+     * 작업이 가리키는 물품을 찾는다 — **참조와 키가 다를 수 있다.**
+     *
+     * 물품 맵의 키는 `itemKeyOf`(직렬 물품은 `epc`, 로트의 부분은 `subLotId`)인데, 작업은 로트 식별자
+     * (`itemEpc`)로 가리킨다. 비직렬 로트에서는 둘이 **다르다** — 그래서 그냥 `get` 하면 못 찾는다.
+     * 실제로 그 회귀를 냈다: 예측(씨앗) 경로에서 `item.location = …` 이 `undefined` 위에서 던져
+     * **정확도 추세 전체가 서버 오류로 죽었다.**
+     *
+     * **부분이 여럿이면 풀지 않는다** — 어느 부분을 가리키는지 알 수 없고, 아무거나 고르면 그 뒤
+     * 이동·처분이 엉뚱한 자리에 적힌다. 그때는 참조가 부족한 것이고, 부르는 쪽이 그 사실을 말해야 한다.
+     */
+    itemByRef(ref) {
+        const exact = this.items.get(ref);
+        if (exact)
+            return exact;
+        let hit;
+        for (const it of this.items.values()) {
+            if (it.epc !== ref)
+                continue;
+            if (hit)
+                return undefined; // 부분이 여럿 — 어느 것인지 알 수 없다
+            hit = it;
+        }
+        return hit;
+    }
+    /**
+     * 실제 자재 이동을 작업에 적어 둔다 — ISA-95 `JobResponse.MaterialActual`.
+     * 같은 품목·같은 쓰임은 **한 줄로 합친다**(줄을 늘리면 실적을 세는 쪽이 중복을 걷어내야 한다).
+     */
+    recordMaterialActual(t, definitionId, use, quantity, uom) {
+        if (!definitionId || !(quantity > 0))
+            return;
+        const rows = (t.materialActual ??= []);
+        const hit = rows.find(r => r.definitionId === definitionId && r.use === use && r.uom === uom);
+        if (hit)
+            hit.quantity += quantity;
+        else
+            rows.push({ definitionId, use, quantity, ...(uom ? { uom } : {}) });
+    }
+    /** 확보한 자재를 **작업 시작 시점에 소비**한다 — 수량이 0 이 되면 물품 자체가 사라진다. */
+    consumeMaterials(t, taken) {
+        if (!taken.length)
+            return;
+        /* 통째로 없어지는 것은 **원시로** 내보낸다(계보가 남고 미러가 배운다). 부분 소비는 수량만 줄고
+           물품이 남으므로 `transform` 의 입력(전량 소비)으로 표현할 수 없다 — 그 경우 수량 변화를
+           관측 이벤트로 낸다. 어느 쪽이든 **상태만 바뀌는 일은 없다.** */
+        const whole = [];
+        for (const { epc, take } of taken) {
+            const it = this.items.get(epc);
+            if (!it)
+                continue;
+            const left = (it.qty ?? 1) - take;
+            if (left > 0) {
+                it.qty = left;
+                this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom);
+                /* 남은 수량을 그대로 알린다 — 관측 경로가 그 자리의 사실을 갱신한다(§quantityList). */
+                this.emit(objectEvent({
+                    eventTime: this.now(), action: 'OBSERVE', bizStep: CBV_BIZSTEP.consuming, disposition: DISP.in_progress,
+                    epcList: [], quantityList: [{ epcClass: it.gtin ?? it.epc, quantity: left, uom: it.uom }],
+                    readPoint: it.location, bizLocation: it.location
+                }));
+                continue;
+            }
+            this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom);
+            whole.push(epc);
+        }
+        if (whole.length) {
+            this.transform(whole, [], {
+                bizStep: CBV_BIZSTEP.consuming, disposition: DISP.in_progress, transformationId: t.id,
+                readPoint: this.items.get(whole[0])?.location ?? t.toNode
+            });
+        }
+    }
     claimPersonnel(t) {
         const need = this.operationSpecs.get(t.kind)?.personnelSpecification;
         if (!need?.length)
@@ -1128,6 +1677,7 @@ export class FlowEngine {
             const avail = [...this.persons.values()].filter(p => p.status === 'idle' &&
                 !picked.includes(p.id) &&
                 !this.personOffShift(p) &&
+                !this.outOfEffect(p) && // 입사 전·퇴사 후는 이 시각의 모델에 없다
                 /* 자격은 **상속을 타고 닫아** 판정한다 — 사람은 여러 등급에 속할 수 있고(표준), 등급은
                    다른 등급을 상속한다. "생산직 2명" 요구를 "용접 자격자" 가 만족해야 한다.
                    유효기간 밖의 등급은 닫힘에서 빠진다(만료된 자격으로 배정되지 않는다). */
@@ -1149,6 +1699,7 @@ export class FlowEngine {
         const free = (kind, picked = []) => [...this.equipment.values()].filter(m => m.status === 'idle' &&
             !m.held &&
             !this.offShift(m) &&
+            !this.outOfEffect(m) && // 도입 전·폐기 후는 이 시각의 모델에 없다
             !picked.includes(m.id) &&
             /* 설비의 소속은 아직 단수(`kind`)다 — 저널에 기록이 쌓여 복수화를 별도 작업으로 두었다.
                다만 등급 정의가 있으면 **상속은 지금도 탄다**: 'welder-6axis' 가 'welder' 를 상속하면
@@ -1199,11 +1750,7 @@ export class FlowEngine {
     }
     /** 사람의 교대 판정 — 자원(offShift)과 같은 규칙. */
     personOffShift(p) {
-        const w = p.window;
-        if (!w)
-            return false;
-        const h = this.hourOfDay();
-        return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
+        return this.offCalendar(p);
     }
     /**
      * 이 자리가 동시 처리 한도에 찼는가 — `parallelism` 을 선언한 자리만 판정한다(미선언=제약 없음).
@@ -1223,15 +1770,75 @@ export class FlowEngine {
     }
     /** 교대 밖인가 — 자원이 지금 일하지 않는 이유 중 고장·계획정지와 구별되는 세 번째. */
     offShift(m) {
-        const w = m.window;
-        if (!w)
-            return false;
-        const h = this.hourOfDay();
-        return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
+        return this.offCalendar(m);
+    }
+    /** 왜 쉬는가 — 휴일·휴게(non-working)인지 주말·교대 사이(off-hours)인지(§OffCalendarReason). */
+    offReason(r) {
+        const why = offCalendarReasonAt(r, this.nowMs(), this.boardDef?.utcOffsetMinutes);
+        return why ? { offShiftReason: why } : {};
+    }
+    /**
+     * 유효 기간 밖인가 — **네 번째 이유**(§Effectivity). 설비·사람·자산이 같은 규칙을 쓴다.
+     *
+     * 시뮬 시각을 ISO 로 풀어 계약의 `effectivityAt` 에 넘긴다. **판정은 커널에 두지 않는다** —
+     * 호스트(라이브 관측)도 같은 판정을 해야 하고, 규칙이 두 벌이면 갈라진다.
+     */
+    effectivityOf(r) {
+        if (!r.effectiveStart && !r.effectiveEnd)
+            return undefined; // 흔한 경우에 Date 를 만들지 않는다
+        return effectivityAt(r, this.now());
+    }
+    /**
+     * 지금 어느 교대인가 — 계약의 `activeShiftOf` 에 위임한다(미러도 같은 함수를 쓴다).
+     * 선언이 없으면 `undefined`: 교대를 나눠 놓지 않은 현장에 이름을 지어내지 않는다.
+     */
+    shiftOf(r) {
+        if (!r.workCalendar?.length)
+            return undefined;
+        /* 시각까지 넘긴다 — 휴일에는 어느 교대도 서지 않는다(되풀이만 보면 평소 교대로 잘못 답한다). */
+        return activeShiftAt(r.workCalendar, this.nowMs(), this.boardDef?.utcOffsetMinutes);
+    }
+    /** 유효 기간 밖이라 이 시각의 모델에 참여하지 않는가 — 배정 게이트가 쓰는 형태. */
+    outOfEffect(r) {
+        return this.effectivityOf(r) !== undefined;
+    }
+    /**
+     * 스냅샷·델타에 실을 조각 — **선언한 기간과 판정을 함께** 낸다.
+     *
+     * 판정만 내면 화면이 "왜" 를 말할 수 없고(언제 폐기됐나), 기간만 내면 소비처마다 다시 판정해 갈라진다.
+     * 선언이 없으면 아무것도 붙이지 않는다(대부분의 자원이 그렇다 — 필드를 늘리지 않는다).
+     */
+    effectivePart(r) {
+        if (!r.effectiveStart && !r.effectiveEnd)
+            return {};
+        const e = this.effectivityOf(r);
+        return {
+            ...(r.effectiveStart ? { effectiveStart: r.effectiveStart } : {}),
+            ...(r.effectiveEnd ? { effectiveEnd: r.effectiveEnd } : {}),
+            ...(e ? { effectivity: e } : {})
+        };
+    }
+    /**
+     * 지금 근무 시간 밖인가 — **캘린더가 있으면 그것으로, 없으면 옛 `window` 로** 판정한다.
+     *
+     * `window`(시 단위 하나)는 캘린더의 특수한 경우다. 둘을 한 함수로 모아 두면 인원·설비가 같은 규칙을
+     * 쓴다(예전에는 같은 식이 두 곳에 복사돼 있었다 — 한쪽만 고치면 조용히 갈라진다).
+     */
+    offCalendar(r) {
+        return offCalendarAt(r, this.nowMs(), this.boardDef?.utcOffsetMinutes);
+    }
+    /**
+     * 시뮬 시각의 분(0..1439) — 캘린더 판정의 기준.
+     *
+     * **보드가 선언한 기준으로 읽는다**(`utcOffsetMinutes`). 예전에는 UTC 로 읽어서 Rosarito(UTC−7)의
+     * 06시 교대가 7시간 틀렸다 — 시각대만 적고 기준을 안 적으면 반드시 이렇게 된다.
+     */
+    minuteOfDay() {
+        return minuteOfDayAt(this.nowMs(), this.boardDef?.utcOffsetMinutes);
     }
     /** 시뮬 시각의 시(0..23) — 운영시간·시간대 배율의 기준. */
     hourOfDay() {
-        return new Date(BASE_EPOCH + this.clockMs).getUTCHours();
+        return new Date(this.nowMs()).getUTCHours();
     }
     /**
      * 운영시간 안인가 — `window {startHour, endHour}`. **선언만 되고 소비처가 없던 필드**를 판정한다.
@@ -1297,6 +1904,8 @@ export class FlowEngine {
         const gtinKey = parsedClass?.gtinKey ?? parsedSelf.gtinKey;
         return {
             epc: i.epc,
+            ...(i.subLotId ? { subLotId: i.subLotId } : {}),
+            ...(i.definitionId ? { definitionId: i.definitionId } : {}),
             ...(i.gtin ? { gtin: i.gtin } : {}),
             ...(gtinKey ? { gtinKey } : {}),
             ...(lot ? { lot } : {}),
@@ -1306,6 +1915,7 @@ export class FlowEngine {
             ...(i.carriedBy ? { carriedBy: i.carriedBy } : {}),
             ...(i.qty !== undefined ? { qty: i.qty } : {}),
             ...(i.uom ? { uom: i.uom } : {}),
+            ...(i.quantities?.length ? { quantities: i.quantities } : {}),
             ...(i.expiry !== undefined ? { expiry: i.expiry } : {}),
             ...(i.ilmd ? { ilmd: i.ilmd } : {})
         };
@@ -1338,9 +1948,13 @@ export class FlowEngine {
         }
     }
     processOrders() {
-        for (const o of this.orders.values())
-            if (o.status === 'created' && !o.held)
-                this.allocate(o);
+        /* **우선순위 순으로 할당한다** — 표준 `OperationsRequest.Priority`. 같은 우선순위는 입력 순서를
+           지켜 결정성을 잃지 않는다(정렬이 안정적이어야 같은 seed 가 같은 결과를 낸다). */
+        const pending = [...this.orders.values()].filter(o => o.status === 'created' && !o.held);
+        if (pending.some(o => o.priority !== undefined))
+            pending.sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority));
+        for (const o of pending)
+            this.allocate(o);
     }
     /**
      * 작업 진행 — **진행을 먼저, 배정을 나중에.**
@@ -1355,7 +1969,12 @@ export class FlowEngine {
     }
     assignTasks() {
         // created → in-progress. dwell(무자원)은 즉시 진행, transport/process 는 가용 자원 배정.
-        for (const t of this.tasks.values()) {
+        /* 자원이 모자랄 때 **무엇을 먼저 잡는가** — 우선순위가 그것을 정한다(표준 `JobOrder.Priority`).
+           선언이 하나도 없으면 정렬하지 않는다(기존 거동 그대로, 불필요한 순서 변경 없음). */
+        const queue = [...this.tasks.values()];
+        if (queue.some(t => t.priority !== undefined))
+            queue.sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority));
+        for (const t of queue) {
             if (t.status !== 'created')
                 continue;
             /* 필요 인원 — 오퍼레이션 명세가 요구하면 등급별로 사람을 잡는다. 모자라면 **기다린다**
@@ -1367,12 +1986,17 @@ export class FlowEngine {
             const gear = this.claimAssets(t);
             if (gear === null)
                 continue;
+            /* 필요 자재 — 부품이 없으면 라인이 선다. 인원·자산과 같은 규칙(부분 투입 없이 전량 아니면 대기). */
+            const stock = this.claimMaterials(t);
+            if (stock === null)
+                continue;
             if (t.intent === 'dwell') { // 무설비 체류 — 설비 배정 없이 진행(인원 요구가 있으면 위에서 확보됨)
                 t.status = 'in-progress';
                 t.remainingMs = t.durationMs;
                 t.startedAtSimMs = this.clockMs;
                 this.assignCrew(t, crew);
                 this.assignAssets(t, gear);
+                this.consumeMaterials(t, stock);
                 this.emitTask(t);
                 continue;
             }
@@ -1406,6 +2030,7 @@ export class FlowEngine {
                 t.resources = rigs.slice(); // 대표만으로는 함께 잡힌 설비가 사라진다
             this.assignCrew(t, crew);
             this.assignAssets(t, gear);
+            this.consumeMaterials(t, stock);
             this.emitTask(t);
             // process: 제자리 변환(모션 없음). transport: 이동 모션 방출.
             if (t.intent === 'process')
@@ -1424,6 +2049,56 @@ export class FlowEngine {
             t.remainingMs -= dt;
             if (t.remainingMs > 0)
                 continue;
+            /*
+             * **산출 자재를 만든다** — ISA-95 `MaterialSpecification`(`use: 'produced'`).
+             *
+             * 도메인 훅(`onTaskComplete`)보다 **먼저** 한다: 훅이 산출물을 보고 다음 일을 만들 수 있어야
+             * 한다(만들어지기 전에 물으면 없다고 답한다). 소비가 시작 시점인 것과 짝이다 — 자재는
+             * 들어갈 때 없어지고 나올 때 생긴다.
+             */
+            /*
+             * **주체가 사라진 작업은 완료시키지 않고 접는다.**
+             *
+             * 진행 중에 그 물품이 없어질 수 있다(포장으로 합쳐지고, 출하로 나가고, 다른 공정이 소비한다).
+             * 그때 도메인 훅은 "없는 물품을 옮기려" 하다 던졌고, **그 예외 하나가 예측 전체를 죽였다** —
+             * 사용자에게는 정확도 추세가 통째로 사라진 것으로 보였다.
+             *
+             * 조용히 넘기지도 않는다: 몇 건이 왜 접혔는지 센다. 그것이 잦다면 **상류에 진짜 문제가 있는 것**
+             * 이고, 그 신호를 지우면 아무도 모른다.
+             */
+            const missing = this.missingContextOf(t);
+            if (missing) {
+                this.abandonedTasks++;
+                /* **한 번은 말한다.** 세어만 두고 아무도 안 보면 없는 것과 같고, 매번 말하면 로그가 묻힌다.
+                   잦아지면 상류에 진짜 어긋남이 있다는 뜻이다 — 그 신호를 지우지 않는다. */
+                if (this.abandonedTasks === 1) {
+                    const why = missing === 'item'
+                        ? 'the item it moves is no longer in state (consumed, shipped, or the observation did not carry it)'
+                        : missing === 'order'
+                            ? 'the order it belongs to is no longer in state (already fulfilled, so the seed did not restore it)'
+                            : 'the domain cannot complete it (its order or product definition is missing)';
+                    console.warn(`[twin-kernel] "${this.tenantId}": folding task ${t.id} — ${why}. Further such tasks are counted, not logged.`);
+                }
+                this.tasks.delete(t.id);
+                this.releaseCrew(t);
+                this.releaseAssets(t);
+                if (t.resource) {
+                    const rig = this.equipment.get(t.resource);
+                    if (rig) {
+                        rig.status = 'idle';
+                        rig.taskId = null;
+                    }
+                }
+                for (const id of t.resources ?? []) {
+                    const m = this.equipment.get(id);
+                    if (m) {
+                        m.status = 'idle';
+                        m.taskId = null;
+                    }
+                }
+                continue;
+            }
+            this.produceMaterials(t);
             this.onTaskComplete(t);
             t.status = 'completed';
             this.releaseCrew(t); // 사람은 설비와 별개로 해제한다(dwell 도 사람은 잡고 있었을 수 있다)