@operato/twin-kernel 0.2.3 → 0.4.0

package/dist/flow-engine.d.ts

@@ -1,9 +1,10 @@
-import type { Attention, BoardDef, CanonicalEnvelope, Command, CommandAck, EventHandler, MoverMotion, OeeMetrics, AssetState, GeneratorSpec, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, NodeState, ItemState, MoverState, OrderStatusDelta, TaskState } from './contract.ts';
+import type { ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, BoardDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState } from './contract.ts';
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
 import type { OperationDef } from './domain-definition.ts';
-export interface FlowNode {
+import { type CapacityAnalysis } from './capacity.ts';
+export interface FlowLocation {
     id: string;
     type: string;
     capacity: number;
@@ -24,6 +25,10 @@ export interface FlowItem {
     epc: string;
     location: string;
     disposition: string;
+    /** 무슨 품목인가 — 표준 `MaterialLot.MaterialDefinitionID`. 보통은 `gtin` 이 곧 정의 id 라 비어 있다. */
+    definitionId?: string;
+    /** 로트의 부분(표준 `MaterialSubLot.ID`) — 비직렬 로트가 자리마다 갈릴 때. */
+    subLotId?: string;
     gtin?: string;
     qty?: number;
     /** 수량 단위(UN/CEFACT). 개수면 없다 — 없는 것을 'EA' 로 꾸미지 않는다. */
@@ -35,38 +40,62 @@ export interface FlowItem {
     expiry?: number;
     /** 개체·로트 마스터데이터 원문 — 생겨날 때 정해지고 뒤 이벤트가 지우지 않는다. */
     ilmd?: Record<string, unknown>;
+    /** 선언된 모든 수량 — 표준 `MaterialLot.Quantity`(복수). 관측에서 온 물품이 여러 단위를 들 수 있다. */
+    quantities?: MaterialQuantity[];
 }
 /** 물리 자산 — 반복사용(팔레트·랙·용기). 설비도 물품도 아니다(GRAI vs SSCC 구분은 계약 주석 참조). */
-export interface FlowAsset {
+export interface FlowAsset extends EffectivePeriod {
     id: string;
-    assetClass?: string;
+    /** 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). */
+    assetClassIds?: string[];
     location?: string;
     status: string;
     taskId: string | null;
     carrying?: string;
+    /** 자원 속성 — 표준 `PhysicalAssetProperty`. */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
 }
 /** 사람 — 설비와 별개 자원(고장·OEE 가 아니라 등급·교대로 산다). */
-export interface FlowPerson {
+export interface FlowPerson extends EffectivePeriod {
     id: string;
-    personnelClass?: string;
+    /** 속한 등급들 — 표준 `PersonnelClassID`(복수). 자격이 여럿인 사람을 표현한다. */
+    personnelClassIds?: string[];
     status: string;
     taskId: string | null;
     window?: {
         startHour: number;
         endHour: number;
     };
+    /** 근무 캘린더 — 표준 `WorkCalendarEntry`(복수). 있으면 `window` 보다 이것을 본다. */
+    workCalendar?: WorkCalendarEntry[];
+    /** 지금 어디에 있나 — 표준 `Person.OperationalLocation`. 커널은 사람을 움직이지 않는다(마스터·관측이 말한다). */
+    location?: string;
+    /** 자원 속성 — 표준 `PersonProperty`. */
+    properties?: ResourceProperty[];
+    /** 자격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
 }
-export interface FlowMover {
+export interface FlowEquipment extends EffectivePeriod {
     id: string;
     kind: string;
     location: string;
     status: string;
     taskId: string | null;
+    /** 붙박인 자리 — 소속. `location` 은 지금 위치. 고정 설비는 둘이 항상 같다(EquipmentState.homeLocation 참조). */
+    homeLocation?: string;
+    /** 자원 속성 — 표준 `EquipmentProperty`(§ResourceProperty). */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
     /** 교대(가동시간) — 지정 시 이 시간대에만 배정된다. 미지정=24시간 가용. */
     window?: {
         startHour: number;
         endHour: number;
     };
+    /** 근무 캘린더 — 표준 `WorkCalendarEntry`(복수). 있으면 `window` 보다 이것을 본다. */
+    workCalendar?: WorkCalendarEntry[];
     runMs: number;
     setupMs: number;
     downMs: number;
@@ -85,12 +114,29 @@ export interface FlowTask {
     id: string;
     kind: string;
     status: 'created' | 'in-progress' | 'completed';
+    /**
+     * **실제로 들어가고 나온 자재** — ISA-95 `JobResponse.MaterialActual`.
+     *
+     * 명세(계획)가 아니라 **일어난 일**이다. 투입 인원·설비가 이미 작업 델타에 타고 있으니 자재도 같은
+     * 채널에 실어야 실적을 **한 곳에서** 읽는다(EPCIS 이벤트에서 되짚으려면 작업과 잇는 끈이 없다).
+     */
+    materialActual?: {
+        definitionId: string;
+        use: 'consumed' | 'produced';
+        quantity: number;
+        uom?: string;
+    }[];
     itemEpc: string;
     fromNode: string;
     toNode: string;
     resource: string | null;
     /** 착수 시각(절대 sim-clock) — 보간 앵커(모션과 같은 규율). */
     startedAtSimMs?: number;
+    /** 우선순위 — 표준 `JobOrder.Priority`(작은 값이 급하다). 배정 순서를 정한다. */
+    priority?: number;
+    /** 예정 창 — 표준 `JobOrder.StartTime`/`EndTime`. 실제 착수와 다른 축. */
+    startTime?: string;
+    endTime?: string;
     /** 이 작업에 투입된 사람들 — 설비와 별개 축(설비 1대 + 작업자 2명이 동시에 잡힌다). */
     personnel?: string[];
     /** 이 작업에 투입된 물리 자산(팔레트 등). */
@@ -106,9 +152,9 @@ export interface FlowTask {
     appliedSetupMs?: number;
     /**
      * 작업 의도(씬 3 직교의도 정렬 · ISA-95 이동 vs 변환). 기본 'transport'.
-     *   transport: mover 가 item 을 fromNode→toNode 운반(완료 시 자원 위치 이동 + 이동 모션).
-     *   process:   노드에서 item 변환(자원=정지 설비 — 위치 불변, 모션 없음). 가공을 거리-0 운반으로 위장 안 함.
-     *   dwell:     노드에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
+     *   transport: eq 가 item 을 fromNode→toNode 운반(완료 시 자원 위치 이동 + 이동 모션).
+     *   process:   자리에서 item 변환(자원=정지 설비 — 위치 불변, 모션 없음). 가공을 거리-0 운반으로 위장 안 함.
+     *   dwell:     자리에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
      */
     intent?: 'transport' | 'process' | 'dwell';
 }
@@ -132,25 +178,31 @@ export interface FlowOrder {
     held?: boolean;
     dockDoor?: string;
     windowStartMs?: number;
+    /** 우선순위 — 표준 `OperationsRequest.Priority`(작은 값이 급하다). 할당 순서를 정한다. */
+    priority?: number;
+    /** 예정 창 — 표준 `StartTime`/`EndTime`. 납기가 있어야 "늦었나" 를 물을 수 있다. */
+    startTime?: string;
+    endTime?: string;
 }
 interface Rng {
     (): number;
     state: number;
 }
 /**
- * 주목신호 계산(순수) — State 스냅샷(movers/nodes/orders)에서 attentions 파생.
+ * 주목신호 계산(순수) — State 스냅샷(equipment/locations/orders)에서 attentions 파생.
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
 export declare function deriveAttentions(view: {
-    movers: {
+    equipment: {
         id: string;
         status?: string;
         location?: string;
         goodCount?: number;
         scrapCount?: number;
+        offShift?: boolean;
     }[];
-    nodes: {
+    locations: {
         id: string;
         capacity?: number;
         occupancy?: number;
@@ -158,8 +210,23 @@ export declare function deriveAttentions(view: {
     orders: {
         id: string;
         held?: boolean;
+        status?: string;
+        endTime?: ISOTime;
+        priority?: number;
+    }[];
+    /**
+     * 작업 — 대기 행렬을 재는 데 쓴다. **주지 않으면 재지 않는다**(모르면 판단하지 않는다).
+     * 두 구동(시뮬·미러)이 **똑같이 넣어야** 한다 — 한쪽만 넣으면 같은 공장이 한쪽에서만 막힌
+     * 것처럼 보인다.
+     */
+    tasks?: {
+        id: string;
+        kind: string;
+        status: string;
     }[];
-}, acked?: ReadonlySet<string>): Attention[];
+}, acked?: ReadonlySet<string>, 
+/** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
+nowIso?: ISOTime): Attention[];
 /** OEE 계측 카운터 — sim 은 tick 으로 누적, live 는 실 텔레메트리 또는 이벤트 누적기가 채운다(face2-inbound-live §1.1). */
 export interface OeeCounters {
     runMs: number;
@@ -178,9 +245,21 @@ export interface OeeCounters {
 export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;
 export declare abstract class FlowEngine implements TwinKernel {
     tenantId: string;
-    nodes: Map<string, FlowNode>;
+    locations: Map<string, FlowLocation>;
     items: Map<string, FlowItem>;
-    movers: Map<string, FlowMover>;
+    equipment: Map<string, FlowEquipment>;
+    /** 등급 정의(표준 `<X>Class`) — 상속·유효기간 판정의 재료. 선언 안 하면 비어 있고, 소속 그대로 판정한다. */
+    protected classDefs: {
+        personnel?: ResourceClassDef[];
+        equipment?: ResourceClassDef[];
+        asset?: ResourceClassDef[];
+        material?: ResourceClassDef[];
+    };
+    /**
+     * 품목 정의 색인(표준 `MaterialDefinition`) — 단위 환산의 **유일한 근거**.
+     * 비어 있으면 환산하지 않는다(계수를 모르는데 값을 만들지 않는다).
+     */
+    protected materialDefs: Map<string, MaterialDefinition>;
     /** 사람 — 선언하지 않으면 빈 맵(인원 제약 없는 트윈, 기존 거동). */
     persons: Map<string, FlowPerson>;
     /** 물리 자산 — 선언하지 않으면 빈 맵(자산 제약 없는 트윈, 기존 거동). */
@@ -233,34 +312,45 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected abstract onTaskComplete(task: FlowTask): void;
     loadBoard(def: BoardDef): void;
     /**
-     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 무버 추가. loadBoard 무버 삽입과 동일 규약.
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
      * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
      */
-    addMover(m: {
+    addEquipment(m: {
         id: string;
         kind: string;
-        homeNode: string;
+        homeLocation: string;
         mtbfMs?: number;
         mttrMs?: number;
     }): void;
     /**
-     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·무버·노드)과
+     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·설비·자리)과
      * 저널 오더(원값+라인)로 이 커널의 맵을 채운다. tick 으로 만든 게 아니라 "현재 관측된 현실"을 심어
      * 이후 fork/tick 으로 예측한다. 라이브 런타임은 여전히 projector 미러 — 이 커널은 예측용 임시본.
      * 오더는 남은 데맨드(라인별 requested-fulfilled)를 'created' 로 복원(현재 재고에서 재계획).
      * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
      */
+    /**
+     * **이어서 센다** — 재기동 뒤 저널을 이어 쓸 때.
+     *
+     * 커널은 리비전을 0부터 센다. 새로 시작하는 우주라면 맞지만, **이어지는 현실**(sim-world)에서는
+     * 그 번호가 이미 저널에 있는 행과 겹친다 — 같은 트윈에 revision 7이 두 개 생기고, 재생 순서가
+     * 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다. 조용히 깨지는 종류다(오류가 안 난다).
+     *
+     * 그래서 이어 쓰기 전에 마지막 번호를 알려 준다. **뒤로는 못 간다** — 뒤로 가는 것은 곧 겹치는
+     * 것이고, 그것을 허용하면 이 함수가 막으려던 일이 이 함수를 통해 일어난다.
+     */
+    resumeRevision(from: number): void;
     hydrateObserved(snap: {
-        nodes: NodeState[];
+        locations: LocationState[];
         items: ItemState[];
-        movers: MoverState[];
+        equipment: EquipmentState[];
         persons?: PersonState[];
         assets?: AssetState[];
         tasks?: TaskState[];
         orders?: OrderState[];
     }, orders?: OrderStatusDelta[]): void;
-    /** what-if 구성 변주 — 노드 용량 변경(fork 대상). 존재하면 true. */
-    setNodeCapacity(nodeId: string, capacity: number): boolean;
+    /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
+    setLocationCapacity(locationId: string, capacity: number): boolean;
     /**
      * forecast 몬테카를로 — fork 의 RNG 만 재시드(시나리오·상태·gens·in-flight 는 보존).
      * "현재 조건 지속"을 유지한 채 **미래 확률만** 변주(도착·고장 타이밍 등) → run 마다 다른 표본.
@@ -274,6 +364,15 @@ export declare abstract class FlowEngine implements TwinKernel {
      * State 델타를 유발한다(command → 행위 → 관측 폐루프).
      */
     private _acked;
+    /**
+     * 완료 시점에 **주체가 사라져 접은 작업 수** — 조용한 누락이 되지 않게 센다.
+     *
+     * 물품이 포장·출하·소비로 없어지는 것은 정상이지만, 그 물품을 향한 작업이 남아 있었다는 것은
+     * 상류에 어긋남이 있다는 신호다. 0 이 아니면 그 사실을 소비처가 볼 수 있어야 한다.
+     */
+    protected abandonedTasks: number;
+    /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
+    private _attentionSince;
     dispatch(cmd: Command): CommandAck;
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     protected handleCommand(cmd: Command): CommandAck;
@@ -288,7 +387,39 @@ export declare abstract class FlowEngine implements TwinKernel {
      * rng 는 fork 의 시나리오 load 시 재시드(드레인 예측은 생성 없어 rng 무관·결정적).
      */
     fork(tenantId?: string): this;
+    /**
+     * 이 커널의 **지금**(ms) — 시각으로 바뀌는 모든 판정의 단일 기준.
+     *
+     * ── 관측 모드에서 시계가 멈춰 있었다 ────────────────────────────────────
+     * `apply()` 는 `clockMs` 를 밀지 않는다(관측은 시간을 굴리지 않는다). 그래서 라이브 트윈의 "지금" 이
+     * **BASE_EPOCH(2026-01-01)에 얼어 있었다.** 실 이벤트는 실제 시각을 달고 오므로 결과가 이렇게 된다:
+     *  · **납기 초과를 영원히 보고하지 않는다** — 실 납기가 항상 미래로 보인다
+     *  · 폐기·도입예정 판정이 틀린다(§EffectivePeriod)
+     *  · 교대 판정이 틀린다(§offCalendarAt)
+     * 셋 다 "시각으로만 바뀌는 사실" 이라 같은 결함이었다. 그래서 기준을 **한 곳**으로 모은다.
+     *
+     * 관측 중이면 **마지막으로 들은 발생 시각**을 쓴다(미러의 `lastObservedMs` 와 같은 기준 — 규칙 한 벌).
+     * 아직 아무것도 못 들었으면 시뮬 기준으로 떨어진다(그때는 판정할 사실도 없다).
+     */
+    protected nowMs(): number;
     protected now(): string;
+    /**
+     * 자극이 선언한 **약속**을 오더 필드로 — 표준 `OperationsRequest.Priority`·`StartTime`·`EndTime`.
+     *
+     * **base 에 한 곳만 둔다.** 오더를 만드는 곳이 도메인마다 있어(WMS 판매오더·MES 작업지시·YMS
+     * 어포인트먼트) 각자 계산하면 시간축이나 규약이 갈린다 — 실제로 한 번 갈렸다(납기를 `clockMs` 로
+     * 재고 `now()` 와 비교해 갓 만든 오더가 56년 늦은 것으로 판정됐다).
+     *
+     * 선언이 없으면 **빈 객체**를 준다 — 없는 약속을 만들지 않는다.
+     */
+    protected promiseOf(spec: {
+        promisedLeadMinutes?: number;
+        priority?: number;
+    }): {
+        priority?: number;
+        startTime?: string;
+        endTime?: string;
+    };
     protected randInt(min: number, max: number): number;
     /**
      * 관측 구동(P0 스파이크) — **이벤트로 커널을 굴린다.**
@@ -318,6 +449,28 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
      */
     loadOperations(ops?: OperationDef[]): void;
+    /**
+     * 라우트(공정 순서) — 수율을 거슬러 올릴 때 필요하다. 기본은 모른다(선언 순서를 쓴다).
+     * 생산 정의를 가진 커널이 override 해서 자기 라우트를 답한다.
+     */
+    protected routeKeys(): string[] | undefined;
+    /**
+     * **이 공장이 하루 몇 대를 낼 수 있는가** — 굴려 보지 않고 답한다.
+     *
+     * 커널이 직접 답하는 이유: 필요한 사실이 전부 여기 있다(공정 명세·설비와 신뢰도·인원·물리자산·
+     * 자리·근무 달력·시각 기준). 밖에서 모으면 그 값을 옮겨 적게 되고, 한쪽만 바뀌는 순간 "충분하다"
+     * 가 조용히 거짓이 된다. 계산 자체는 순수 함수(`analyzeCapacity`)에 맡긴다.
+     *
+     * 달력은 **자원이 선언한 것**을 쓴다. 자원마다 다른 달력을 쓰는 현장이면 대표를 고를 수 없으므로
+     * 그 사실을 결과에 실어 보낸다(`mixedCalendars`) — 조용히 하나를 골라 계산하면 천장이 틀린 채로
+     * 그럴듯해 보인다.
+     */
+    capacity(opts: {
+        unitsPerDay: number;
+        sampleWeekStartMs: number;
+    }): CapacityAnalysis & {
+        mixedCalendars: boolean;
+    };
     /**
      * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
      *
@@ -361,17 +514,26 @@ export declare abstract class FlowEngine implements TwinKernel {
         declaredDurations: number;
         defaultDurations: number;
     };
-    /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
+    /**
+     * `skuMix` 에서 weight 로 gtin 선택(rng) — 도착·오더 자극의 품목 결정.
+     *
+     * **빈 목록이면 고르지 않는다**(`undefined`). 예전에는 `mix[mix.length - 1].gtin` 으로 떨어져
+     * `mix[-1]` 이 undefined 가 되고 거기서 던졌다 — 그 예외가 서버까지 올라가 **정확도 추세 전체를
+     * 죽였다**(품목 구성을 선언하지 않은 자극 하나가 예측 전체를 껐다).
+     *
+     * 없는 품목을 지어내지 않는다: 무엇을 만들지 모르면 **만들지 않는 것**이 맞고, 부르는 쪽이
+     * 그 사실을 알고 건너뛴다.
+     */
     protected pickGtin(mix: {
         gtin: string;
         weight: number;
-    }[]): string;
-    protected nodeByType(type: string): FlowNode | undefined;
+    }[]): string | undefined;
+    protected locationByType(type: string): FlowLocation | undefined;
     /**
      * process 변화 대수(EPCIS TransformationEvent · ISA-95 Material Consumed/Produced · 씬 Processable.transform).
      * inputs 소비 → outputs 생산. 입출력 arity 가 곧 대수:
      *   merge N→1(조립) · split 1→N(분해) · transform 1→1(타입변경) · loss N→0(소실) · gain 0→N(부산물·생성).
-     * 아이템 상태(소비/생산)와 노드 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
+     * 아이템 상태(소비/생산)와 자리 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
      * 도메인은 이 원시만 호출 — onTaskComplete 의 소비/생산/EPCIS 손코딩을 대체.
      */
     protected transform(inputs: string[], outputs: {
@@ -429,7 +591,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     }): void;
     /**
      * containment 분해(EPCIS AggregationEvent DELETE) — 부모(용기)에서 자식들을 풀어냄.
-     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 노드 배치 + occupancy + ObjectEvent ADD).
+     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 자리 배치 + occupancy + ObjectEvent ADD).
      * 미지정 시 이벤트만.
      */
     protected disaggregate(parent: string, children: string[], opts: {
@@ -442,10 +604,10 @@ export declare abstract class FlowEngine implements TwinKernel {
     }): void;
     /** 품질 보고(OEE Quality) — 도메인이 완료 시 자원별 양품/불량 1건 계상(예: 용접 수율). */
     protected recordOutput(moverId: string | null, good: boolean): void;
-    /** 무버 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
+    /** 설비 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
     private oeeOf;
-    /** 정책에 넘길 특정 타입 노드의 관측 뷰 — 예약(그 노드로 향하는 in-flight task) 포함. */
-    protected slotViews(nodeType: string): SlotView[];
+    /** 정책에 넘길 특정 타입 자리의 관측 뷰 — 예약(그 자리로 향하는 in-flight task) 포함. */
+    protected slotViews(locationType: string): SlotView[];
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
     /**
@@ -461,7 +623,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected emitPerson(p: FlowPerson): void;
     /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
      *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
-    protected emitMover(m: FlowMover, motion?: MoverMotion): void;
+    protected emitEquipment(m: FlowEquipment, motion?: EquipmentMotion): void;
     /** 오더 델타 — **라인까지 싣는다.** 라인이 빠지면 미러가 남은 데맨드를 라인별로 재계획할 수 없다. */
     protected emitOrder(o: FlowOrder): void;
     /**
@@ -510,6 +672,76 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 여기서는 고르기만 하고 잡지 않는다: 설비까지 확보된 뒤 `assignCrew` 가 확정한다
      * (반쯤 잡고 실패하면 사람이 아무 일도 못 하면서 묶인다).
      */
+    /**
+     * 필요 자재를 확보한다 — **ISA-95 `OperationsSegment.MaterialSpecification`**(`use: 'consumed'`).
+     *
+     * ── 4대 자원 중 자재만 게이트가 없었다 ────────────────────────────────────
+     * 인원·자산·설비는 모자라면 기다리는데 **자재는 없어도 작업이 시작됐다.** 그래서 부품이 떨어져
+     * 라인이 서는 상황이 예측에 아예 나타나지 않았다 — 트레일러 조립 공장에서 그것은 가장 흔한 정지다.
+     *
+     * 인원·자산과 **같은 규칙**이다: 등급(또는 품목)으로 요구하고, **부분 확보 없이 전량 아니면 대기.**
+     * 자재는 **작업이 일어나는 자리에 있어야** 한다(다른 창고의 부품은 지금 쓸 수 없다).
+     *
+     * 소비 시점은 **작업 시작**이다 — 자재는 들어가는 순간 없어진다(완료 시점에 빼면 그 사이 다른
+     * 작업이 같은 부품을 또 잡는다). 산출(`produced`)은 여기서 다루지 않는다(완료 시점의 일이다).
+     */
+    private claimMaterials;
+    /** 이 물품이 명세를 만족하나 — 품목 지목이 우선, 없으면 등급(상속을 타고 닫는다). */
+    private materialMatches;
+    /**
+     * 산출 자재를 만든다 — ISA-95 `MaterialSpecification`(`use: 'produced'`).
+     *
+     * **소비의 짝이다**: 자재는 작업이 시작될 때 들어가고 끝날 때 나온다. 산출이 없으면 조립 공정이
+     * 부품만 먹고 아무것도 내놓지 않아, 다음 공정이 영원히 재료를 기다린다(라인 전체가 한 칸에서 멈춘다).
+     *
+     * 산출물의 자리는 **작업이 끝난 자리**(`toNode`)다. 식별자는 품목 식별자에 작업 id 를 붙여 만든다 —
+     * **EPC 처럼 보이게 꾸미지 않는다**(상류가 준 직렬번호와 구별돼야 한다). 상류가 진짜 식별자를
+     * 말해 주면 그것이 들어올 자리는 관측 경로다.
+     *
+     * 같은 품목이 그 자리에 이미 있으면 **수량을 더한다** — 새 줄을 만들면 같은 자리의 같은 로트가
+     * 둘로 갈려 재고가 부푼다(§MaterialSubLot 에서 겪은 것과 반대 방향의 같은 오류).
+     */
+    private produceMaterials;
+    /**
+     * 이 작업이 **딛고 선 것**이 아직 있나 — 없으면 무엇이 없는지 답한다.
+     *
+     * 작업은 혼자 서지 못한다: 옮길 **물품**과, (있다면) 그것을 시킨 **오더** 위에 선다. 진행 중에
+     * 둘 중 하나가 사라질 수 있다 — 물품은 포장·출하·소비로, 오더는 이미 이행돼 씨앗이 심지 않아서.
+     *
+     * 그때 도메인 훅은 없는 것을 딛으려다 던진다(`order.gtin` · `item.location`). 그 예외 하나가
+     * **예측 전체를 죽였다** — 사용자에게는 기능이 통째로 사라진 것으로 보였다. 그래서 완료 **전에**
+     * 여기서 묻고, 없으면 그 작업만 접는다.
+     */
+    protected missingContextOf(t: FlowTask): 'item' | 'order' | 'domain' | undefined;
+    /**
+     * 이 도메인이 이 작업을 **끝맺을 수 있나** — 코어가 모르는 조건은 도메인이 답한다.
+     *
+     * 코어는 물품과 오더까지만 안다. 그런데 도메인은 더 필요할 수 있다 — MES 는 완료 시점에 **오더와
+     * 제품 정의**를 딛고 서고, 그 중 하나만 없어도 던진다. 코어가 그 조건을 추측하면 도메인마다 다른
+     * 가정을 코어에 박게 되므로(방언), **묻는다.**
+     *
+     * 기본은 `true` — 대부분의 작업은 코어가 확인한 것으로 충분하다.
+     */
+    protected canComplete(_t: FlowTask): boolean;
+    /**
+     * 작업이 가리키는 물품을 찾는다 — **참조와 키가 다를 수 있다.**
+     *
+     * 물품 맵의 키는 `itemKeyOf`(직렬 물품은 `epc`, 로트의 부분은 `subLotId`)인데, 작업은 로트 식별자
+     * (`itemEpc`)로 가리킨다. 비직렬 로트에서는 둘이 **다르다** — 그래서 그냥 `get` 하면 못 찾는다.
+     * 실제로 그 회귀를 냈다: 예측(씨앗) 경로에서 `item.location = …` 이 `undefined` 위에서 던져
+     * **정확도 추세 전체가 서버 오류로 죽었다.**
+     *
+     * **부분이 여럿이면 풀지 않는다** — 어느 부분을 가리키는지 알 수 없고, 아무거나 고르면 그 뒤
+     * 이동·처분이 엉뚱한 자리에 적힌다. 그때는 참조가 부족한 것이고, 부르는 쪽이 그 사실을 말해야 한다.
+     */
+    protected itemByRef(ref: string): FlowItem | undefined;
+    /**
+     * 실제 자재 이동을 작업에 적어 둔다 — ISA-95 `JobResponse.MaterialActual`.
+     * 같은 품목·같은 쓰임은 **한 줄로 합친다**(줄을 늘리면 실적을 세는 쪽이 중복을 걷어내야 한다).
+     */
+    private recordMaterialActual;
+    /** 확보한 자재를 **작업 시작 시점에 소비**한다 — 수량이 0 이 되면 물품 자체가 사라진다. */
+    private consumeMaterials;
     private claimPersonnel;
     /**
      * 필요 설비를 고른다 — **인원·자산과 같은 규칙**(등급으로 요구, 부분 확보 없이 전량 아니면 대기).
@@ -529,7 +761,62 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     private stationFull;
     /** 교대 밖인가 — 자원이 지금 일하지 않는 이유 중 고장·계획정지와 구별되는 세 번째. */
-    protected offShift(m: FlowMover): boolean;
+    protected offShift(m: FlowEquipment): boolean;
+    /** 왜 쉬는가 — 휴일·휴게(non-working)인지 주말·교대 사이(off-hours)인지(§OffCalendarReason). */
+    protected offReason(r: {
+        window?: {
+            startHour: number;
+            endHour: number;
+        };
+        workCalendar?: WorkCalendarEntry[];
+    }): {
+        offShiftReason?: OffCalendarReason;
+    };
+    /**
+     * 유효 기간 밖인가 — **네 번째 이유**(§Effectivity). 설비·사람·자산이 같은 규칙을 쓴다.
+     *
+     * 시뮬 시각을 ISO 로 풀어 계약의 `effectivityAt` 에 넘긴다. **판정은 커널에 두지 않는다** —
+     * 호스트(라이브 관측)도 같은 판정을 해야 하고, 규칙이 두 벌이면 갈라진다.
+     */
+    protected effectivityOf(r: EffectivePeriod): Effectivity | undefined;
+    /**
+     * 지금 어느 교대인가 — 계약의 `activeShiftOf` 에 위임한다(미러도 같은 함수를 쓴다).
+     * 선언이 없으면 `undefined`: 교대를 나눠 놓지 않은 현장에 이름을 지어내지 않는다.
+     */
+    protected shiftOf(r: {
+        workCalendar?: WorkCalendarEntry[];
+    }): string | undefined;
+    /** 유효 기간 밖이라 이 시각의 모델에 참여하지 않는가 — 배정 게이트가 쓰는 형태. */
+    protected outOfEffect(r: EffectivePeriod): boolean;
+    /**
+     * 스냅샷·델타에 실을 조각 — **선언한 기간과 판정을 함께** 낸다.
+     *
+     * 판정만 내면 화면이 "왜" 를 말할 수 없고(언제 폐기됐나), 기간만 내면 소비처마다 다시 판정해 갈라진다.
+     * 선언이 없으면 아무것도 붙이지 않는다(대부분의 자원이 그렇다 — 필드를 늘리지 않는다).
+     */
+    protected effectivePart(r: EffectivePeriod): Partial<EffectivePeriod> & {
+        effectivity?: Effectivity;
+    };
+    /**
+     * 지금 근무 시간 밖인가 — **캘린더가 있으면 그것으로, 없으면 옛 `window` 로** 판정한다.
+     *
+     * `window`(시 단위 하나)는 캘린더의 특수한 경우다. 둘을 한 함수로 모아 두면 인원·설비가 같은 규칙을
+     * 쓴다(예전에는 같은 식이 두 곳에 복사돼 있었다 — 한쪽만 고치면 조용히 갈라진다).
+     */
+    protected offCalendar(r: {
+        window?: {
+            startHour: number;
+            endHour: number;
+        };
+        workCalendar?: WorkCalendarEntry[];
+    }): boolean;
+    /**
+     * 시뮬 시각의 분(0..1439) — 캘린더 판정의 기준.
+     *
+     * **보드가 선언한 기준으로 읽는다**(`utcOffsetMinutes`). 예전에는 UTC 로 읽어서 Rosarito(UTC−7)의
+     * 06시 교대가 7시간 틀렸다 — 시각대만 적고 기준을 안 적으면 반드시 이렇게 된다.
+     */
+    protected minuteOfDay(): number;
     /** 시뮬 시각의 시(0..23) — 운영시간·시간대 배율의 기준. */
     protected hourOfDay(): number;
     /**
@@ -541,9 +828,9 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
     private sampleExp;
     /**
-     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 무버만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
+     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 설비만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
      * up: nextFailure 도래 시 down(수리까지 repairUntil). down: downMs 누적, repair 도래 시 up(다음 고장 예약).
-     * down 중 무버는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
+     * down 중 설비는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
      */
     private processFailures;
     /**