@operato/twin-kernel 0.0.6 → 0.2.0

package/dist/flow-engine.d.ts

@@ -1,11 +1,13 @@
-import type { Attention, BoardDef, Command, CommandAck, EventHandler, MoverMotion, OeeMetrics, GeneratorSpec, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, NodeState, ItemState, MoverState, OrderStatusDelta } from './contract.ts';
+import type { Attention, BoardDef, Command, CommandAck, EventHandler, MoverMotion, OeeMetrics, AssetState, GeneratorSpec, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, NodeState, ItemState, MoverState, 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 {
     id: string;
     type: string;
     capacity: number;
+    parallelism?: number;
     occupancy: number;
     status: string;
     parentId?: string;
@@ -18,12 +20,37 @@ export interface FlowItem {
     qty?: number;
     expiry?: number;
 }
+/** 물리 자산 — 반복사용(팔레트·랙·용기). 설비도 물품도 아니다(GRAI vs SSCC 구분은 계약 주석 참조). */
+export interface FlowAsset {
+    id: string;
+    assetClass?: string;
+    location?: string;
+    status: string;
+    taskId: string | null;
+    carrying?: string;
+}
+/** 사람 — 설비와 별개 자원(고장·OEE 가 아니라 등급·교대로 산다). */
+export interface FlowPerson {
+    id: string;
+    personnelClass?: string;
+    status: string;
+    taskId: string | null;
+    window?: {
+        startHour: number;
+        endHour: number;
+    };
+}
 export interface FlowMover {
     id: string;
     kind: string;
     location: string;
     status: string;
     taskId: string | null;
+    /** 교대(가동시간) — 지정 시 이 시간대에만 배정된다. 미지정=24시간 가용. */
+    window?: {
+        startHour: number;
+        endHour: number;
+    };
     runMs: number;
     setupMs: number;
     downMs: number;
@@ -46,6 +73,10 @@ export interface FlowTask {
     fromNode: string;
     toNode: string;
     resource: string | null;
+    /** 이 작업에 투입된 사람들 — 설비와 별개 축(설비 1대 + 작업자 2명이 동시에 잡힌다). */
+    personnel?: string[];
+    /** 이 작업에 투입된 물리 자산(팔레트 등). */
+    assets?: string[];
     remainingMs: number;
     durationMs: number;
     orderId?: string;
@@ -130,14 +161,25 @@ export declare abstract class FlowEngine implements TwinKernel {
     nodes: Map<string, FlowNode>;
     items: Map<string, FlowItem>;
     movers: Map<string, FlowMover>;
+    /** 사람 — 선언하지 않으면 빈 맵(인원 제약 없는 트윈, 기존 거동). */
+    persons: Map<string, FlowPerson>;
+    /** 물리 자산 — 선언하지 않으면 빈 맵(자산 제약 없는 트윈, 기존 거동). */
+    assets: Map<string, FlowAsset>;
     tasks: Map<string, FlowTask>;
     orders: Map<string, FlowOrder>;
     revision: number;
     clockMs: number;
     protected rng: Rng;
     protected policy: AllocationPolicy;
-    /** duration 시임(선택) — 미주입 시 도메인 상수. 씬/보드 바인딩이 거리·속도 기반 estimator 주입. */
+    /** duration 시임(선택) — 미주입 시 명세, 명세도 없으면 도메인 상수. 이력 보정 추정기가 여기 들어온다. */
     durationEstimator?: DurationEstimator;
+    /**
+     * 오퍼레이션 명세(선택) — 작업 종류(`FlowTask.kind` = `OperationDef.key`) → 소요·변동·모수.
+     * 도메인 정의에서 실어 온다(`loadOperations`). 없으면 커널 기본값을 쓰고 그 사실을 `specCoverage()` 가 밝힌다.
+     */
+    protected operationSpecs: Map<string, OperationDef>;
+    /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
+    private specUse;
     protected epcSeq: number;
     protected taskSeq: number;
     protected orderSeq: number;
@@ -183,6 +225,9 @@ export declare abstract class FlowEngine implements TwinKernel {
         nodes: NodeState[];
         items: ItemState[];
         movers: MoverState[];
+        persons?: PersonState[];
+        assets?: AssetState[];
+        tasks?: TaskState[];
     }, orders?: OrderStatusDelta[]): void;
     /** what-if 구성 변주 — 노드 용량 변경(fork 대상). 존재하면 true. */
     setNodeCapacity(nodeId: string, capacity: number): boolean;
@@ -215,8 +260,54 @@ export declare abstract class FlowEngine implements TwinKernel {
     fork(tenantId?: string): this;
     protected now(): string;
     protected randInt(min: number, max: number): number;
-    /** task 소요 산출 — estimator 주입 시 그 값, 미주입/undefined 시 도메인 상수(fallback). "얼마"만 소비, "경로"는 씬. */
+    /**
+     * 오퍼레이션 명세를 싣는다 — 도메인 정의(ISA-95 OperationsSegment)의 시뮬 명세를 커널이 소비하는 입구.
+     * 같은 key 를 다시 실으면 덮어쓴다(정의가 권위).
+     */
+    loadOperations(ops?: OperationDef[]): void;
+    /**
+     * task 소요 산출 — 우선순위: **① 추정기(이력 보정) → ② 명세(ISA-95 Duration + 변동) → ③ 도메인 상수.**
+     *
+     * 이 순서인 이유: 실측에서 배운 값이 선언값을 이기고, 선언값이 우리가 코드에 박아 둔 상수를 이긴다.
+     * 셋 중 무엇을 썼는지는 `specCoverage()` 로 드러낸다 — 상수를 쓴 것이 조용히 넘어가지 않게.
+     * "얼마"만 소비하고 "경로"는 씬이 소유한다(좌표-free 유지).
+     */
     protected durationOf(ctx: DurationContext, fallbackMs: number): number;
+    /**
+     * 소요시간 변동 표본 — **엔진 난수원으로만** 뽑는다(fork 결정성). 표준 밖 확장이므로 미지정이면 상수.
+     * 모수가 모자라면(uniform 에 min/max 없음 등) 변동을 발명하지 않고 평균을 그대로 쓴다.
+     */
+    private applyVariability;
+    /**
+     * 퍼짐 표본 — **엔진 난수원으로만** 뽑는다(fork 결정성). 선언 명세(ISO 표기)와 실측 분포(ms)가
+     * 같은 수식을 쓴다: 한쪽만 고치면 두 경로가 다른 답을 낸다.
+     * 모수가 모자라거나 뒤집혀 있으면 **퍼짐을 발명하지 않고** 평균을 그대로 쓴다.
+     */
+    private sampleSpread;
+    /** 명세 모수(숫자) — 선언 없으면 undefined(0 으로 꾸미지 않는다). 소비처가 기본값을 정한다. */
+    protected paramNumber(opKey: string, id: string): number | undefined;
+    /** 명세 모수(기간) — ISO 8601 문자열을 밀리초로. 선언 없으면 undefined. */
+    protected paramDuration(opKey: string, id: string): number | undefined;
+    private noteSpecUse;
+    private noteParamUse;
+    /**
+     * 시뮬 명세 자기보고 — **어디까지 데이터로 말했고 어디부터 우리가 박아 둔 상수인가.**
+     *
+     * 시뮬레이션 결과를 받는 쪽이 이걸 봐야 한다: 소요시간이 전부 기본값이면 그 예측으로 말할 수 있는 것은
+     * "같은 조건에서의 상대 비교" 뿐이고 "몇 시에 끝난다" 는 근거가 없다. 그 구분을 숫자로 드러낸다.
+     */
+    specCoverage(): {
+        operations: {
+            kind: string;
+            duration: 'measured' | 'declared' | 'default';
+            variability?: string;
+            parameters: string[];
+        }[];
+        /** 이력·계산에서 온 소요(추정기) — 선언값보다 강한 근거. */
+        measuredDurations: number;
+        declaredDurations: number;
+        defaultDurations: number;
+    };
     /** skuMix 에서 weight 로 gtin 선택(rng) — 도착/오더 자극의 품목 결정. */
     protected pickGtin(mix: {
         gtin: string;
@@ -280,10 +371,87 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected slotViews(nodeType: string): SlotView[];
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
+    /**
+     * 작업 전이 방출 — **커널이 아는 것을 미러도 알게** 한다.
+     *
+     * 예전에는 진척·남은 시간·의도를 싣지 않아, 미러 상태를 씨앗으로 한 예측이 "진행 중인 일이 없는
+     * 현장" 에서 출발했고, 소비처는 무자원 체류를 기록 누락으로 오해할 수밖에 없었다.
+     * 진척은 진행 중일 때만 뜻이 있으므로 그때만 싣는다(생성·완료 시점의 0/1 은 노이즈).
+     */
     protected emitTask(t: FlowTask): void;
+    /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
+    protected emitAsset(a: FlowAsset): void;
+    protected emitPerson(p: FlowPerson): void;
     protected emitMover(m: FlowMover, motion?: MoverMotion): void;
     protected emitOrder(o: FlowOrder): void;
+    /**
+     * 자극 간격 — **계약이 선언한 네 분포를 실제로 판정한다.**
+     *
+     * 예전에는 `poisson` 만 구현하고 나머지는 전부 상수로 떨어졌다. 계약이 `uniform`·`profile` 을
+     * 선언하고 있었으므로, 그것을 지정한 사람은 자기가 요청한 분포로 도는 줄 알았다 — **조용한 거짓**이다.
+     *
+     *  constant  간격이 일정(평균 그대로)
+     *  poisson   무기억 도착(지수 간격) — 평균 유지
+     *  uniform   0..2×평균 균등 — 평균을 유지하면서 흔들린다(교과서적 U(0,2μ))
+     *  profile   시간대별 배율(`profile[시]`)로 도착률을 조절 — 하루 안의 수요 곡선
+     */
     private intervalMs;
+    /**
+     * 시간대 배율 — `profile[시]`. `profile` 분포일 때만 적용하며, 배열이 짧으면 **순환**한다
+     * (24개면 하루, 8개면 8시간 주기). 미지정·다른 분포면 1(무영향).
+     * 시(hour)는 **시뮬 시각 자신의 프레임**(BASE_EPOCH 기준 UTC)이다 — 계약에 표준시가 없으므로
+     * 현지 시간대 해석은 아직 하지 않는다(꾸미지 않는다).
+     */
+    /**
+     * 다음 발화 시각 — **발화가 없는 시간대를 영원한 침묵으로 만들지 않는다.**
+     *
+     * 배율 0(그 시간대 도착 없음)이면 간격이 무한이 된다. 그것을 그대로 예약하면 이후 어떤 시간대가
+     * 와도 깨어나지 않는다 — 그래서 **다음 정시로 미뤄 다시 판정**한다(시간대가 바뀌면 배율도 바뀐다).
+     * 시나리오 시작과 구동 루프가 같은 규칙을 쓰도록 한 곳에 둔다(예전에는 시작 경로만 따로였다).
+     */
+    private nextFireMs;
+    private profileFactor;
+    /**
+     * 필요 물리 자산을 확보한다 — 인원과 **같은 규칙**(등급으로 요구, 부분 투입 없음, 확정은 나중).
+     * 자산은 사람과 달리 교대가 없고 **자리**가 있다(빈 팔레트가 어디 있는지가 다음 문제이지만,
+     * 지금은 자리를 따지지 않는다 — 따지려면 자산 이송 작업이 먼저 있어야 한다).
+     */
+    private claimAssets;
+    /** 확보한 자산을 작업에 묶는다 — 싣는 물류단위(SSCC)가 있으면 연결한다(GRAI ↔ SSCC). */
+    private assignAssets;
+    /**
+     * 작업이 끝나면 자산을 놓아 준다 — **사람과 다른 점: 자산은 도착 자리에 남는다**(물건이므로).
+     * 싣고 있던 것은 놓는다(빈 팔레트로 돌아간다 — 회수·재사용의 출발점).
+     */
+    private releaseAssets;
+    /**
+     * 필요 인원을 확보한다 — **등급으로 요구하고 등급으로 고른다**(특정인 지목이 아니다).
+     * 요구가 없으면 빈 배열, 모자라면 `null`(작업은 기다린다 — **부분 투입으로 시작하지 않는다**).
+     * 여기서는 고르기만 하고 잡지 않는다: 설비까지 확보된 뒤 `assignCrew` 가 확정한다
+     * (반쯤 잡고 실패하면 사람이 아무 일도 못 하면서 묶인다).
+     */
+    private claimPersonnel;
+    /** 확보한 사람을 작업에 묶는다(설비까지 확정된 뒤). */
+    private assignCrew;
+    /** 작업이 끝나면 사람을 놓아 준다 — 설비 해제와 별개 경로. */
+    private releaseCrew;
+    /** 사람의 교대 판정 — 자원(offShift)과 같은 규칙. */
+    protected personOffShift(p: FlowPerson): boolean;
+    /**
+     * 이 자리가 동시 처리 한도에 찼는가 — `parallelism` 을 선언한 자리만 판정한다(미선언=제약 없음).
+     * 세는 대상은 **그 자리에서 진행 중인 작업**(`toNode` 기준, in-progress). 대기 중인 작업은 세지 않는다.
+     */
+    private stationFull;
+    /** 교대 밖인가 — 자원이 지금 일하지 않는 이유 중 고장·계획정지와 구별되는 세 번째. */
+    protected offShift(m: FlowMover): boolean;
+    /** 시뮬 시각의 시(0..23) — 운영시간·시간대 배율의 기준. */
+    protected hourOfDay(): number;
+    /**
+     * 운영시간 안인가 — `window {startHour, endHour}`. **선언만 되고 소비처가 없던 필드**를 판정한다.
+     * `startHour <= endHour` 면 같은 날 구간, 넘어가면 자정을 가로지르는 구간(야간 교대: 22→6).
+     * 미지정이면 언제나 참(24시간 가동).
+     */
+    private inWindow;
     /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
     private sampleExp;
     /**