@operato/twin-kernel 0.0.6 → 0.2.0

package/dist/contract.d.ts

@@ -11,19 +11,71 @@ export type TaskStatus = 'created' | 'assigned' | 'in-progress' | 'completed';
 export interface NodeState {
     id: string;
     type: string;
+    /**
+     * **저장 용량** — 이 자리에 동시에 놓일 수 있는 물품 수. 뜻을 바꾸지 않는다(배정 정책·포화 판정이
+     * 이 뜻으로 굳어 있다). 처리 능력은 아래 `parallelism` 이 따로 말한다.
+     */
     capacity?: number;
+    /**
+     * **동시 처리 수** — 이 자리에서 한 번에 진행될 수 있는 작업 수(대기 이론의 서버 수).
+     *
+     * 저장 용량과 다른 축이다: 절단 스테이션은 자재를 20개 쌓아 둘 수 있어도(`capacity`) 한 번에
+     * 한 대만 깎는다(`parallelism: 1`). 예전에는 한 필드가 둘을 겸해서 그 현장을 표현할 방법이 없었고,
+     * 자원만 놀고 있으면 같은 자리에서 작업이 무제한 동시에 진행됐다 — 대기가 생기지 않아 병목이
+     * 사라지고 예측이 낙관 쪽으로 치우쳤다.
+     *
+     * 미지정 = 제약 없음(기존 거동). 0 은 "처리하지 않는 자리"가 아니라 **선언 오류**로 보고 무시한다
+     * — 0 으로 막을 일이라면 그 자리에 작업을 보내지 않는 것이 맞다.
+     */
+    parallelism?: number;
     occupancy: number;
     status?: string;
     parentId?: string;
+    /**
+     * 이 자리를 **어떻게 알게 됐는가** — `master`(원 시스템 마스터/저작이 말해 준 자리) ·
+     * `observed`(이벤트에 등장해서 알게 된 자리). 소비처가 둘을 구별해야 한다: 관측으로 알게 된 자리는
+     * 보드에 좌표가 없고 용량이 비어 있어 **계획에 참여하지 못한다**(그 사실을 감추지 않기 위한 표시).
+     */
+    origin?: 'master' | 'observed';
 }
+/**
+ * 물품 상태 — 표준이 담는 것을 담는다(EPCIS 2.0 / TDS).
+ *
+ * 세 층위가 한 모델에 들어온다: 개체(SGTIN, 일련번호까지) · **로트 클래스(LGTIN, 품번+로트)** ·
+ * 품목 클래스(GTIN). 낱개 일련번호가 없고 로트로만 관리하는 자재(원자재·화학·식품)가 현장의 다수이므로
+ * 로트와 수량·단위가 일급이어야 한다 — 없으면 회수·유통기한·품질 격리를 표현할 수 없다.
+ */
 export interface ItemState {
+    /** 식별자 — 개체(urn:epc:id:…) 또는 클래스(urn:epc:class:lgtin:… / urn:epc:idpat:…). */
     epc: string;
+    /**
+     * 품목 클래스 식별자 — **URI 원문 그대로**(`urn:epc:idpat:sgtin:…` 또는 `urn:epc:class:lgtin:…`).
+     * 오더의 skuMix·할당이 이 값으로 매칭하므로 뜻을 바꾸지 않는다.
+     */
     gtin?: string;
+    /** 품번 키(CompanyPrefix.ItemRef) — 식별자에서 파생. 로트가 달라도 같은 품번으로 묶는 축. */
+    gtinKey?: string;
+    /** 로트·배치 번호 — LGTIN 이면 식별자에서 파생, 직렬 개체면 ilmd 에서 온다(ilmd 는 미지원). */
+    lot?: string;
     location: string;
     disposition?: string;
+    /** 소속 물류단위(팔레트 SSCC 등) — AggregationEvent 로 맺어진다. 3D 적재 표현의 재료. */
     parent?: string;
+    /**
+     * 이 물류단위를 싣고 있는 **반복사용 자산**(GRAI 팔레트 등). `parent`(물류단위 소속)와 다른 축이다:
+     * `parent` 는 "무엇에 담겼나"(SSCC), 이것은 "무엇에 실렸나"(GRAI). 자산을 쓰지 않는 현장은 비어 있다.
+     */
+    carriedBy?: string;
+    /** 수량 — 비직렬(클래스) 물품의 개수·중량. 개체 물품은 1. */
     qty?: number;
+    /** 수량 단위(UN/ECE Rec 20 코드: EA·KGM 등). 없으면 개수로 읽는다. */
+    uom?: string;
     expiry?: number;
+    /**
+     * 개체·로트 마스터데이터 원문 — 표준이 속성 이름을 정의하지 않으므로(상위 문서 소관) **받은 것을
+     * 그대로 들고 있는다.** 도메인이 자기 어휘로 읽을 수 있고, 우리가 모르는 속성도 잃지 않는다.
+     */
+    ilmd?: Record<string, unknown>;
 }
 /**
  * 운영·키네마틱 모션 — State 이원 모델의 "연속" 절반.
@@ -66,6 +118,59 @@ export interface MoverState {
     motion?: MoverMotion;
     oee?: OeeMetrics;
     held?: boolean;
+    /**
+     * 교대 밖이라 지금 일하지 않는다 — 고장(down)·계획정지(held)와 **다른 이유**다.
+     * 셋을 뭉개면 "왜 안 움직이나" 에 답할 수 없다(고쳐야 하나·풀어야 하나·기다려야 하나).
+     */
+    offShift?: boolean;
+    /** 이 자원을 어떻게 알게 됐는가 — NodeState.origin 과 같은 뜻(성장 정책을 한 규칙으로 선언). */
+    origin?: 'master' | 'observed';
+}
+/**
+ * 사람 — **ISA-95 `Person`.** 설비와 다른 자원 종류다.
+ *
+ * 왜 무버(설비)로 뭉개지 않는가: 사람은 고장 나지 않고(MTBF), 설비종합효율로 평가하지 않으며,
+ * **등급(자격)과 교대로 산다.** 같은 그릇에 담으면 설비의 어휘(고장·수리·OEE)가 사람에게 붙고
+ * 사람의 어휘(등급·교대·투입 인원)가 설비에 붙는다 — 둘 다 거짓이 된다.
+ *
+ * 그리고 **인원은 현장에서 가장 자주 부족한 자원**이다. 모델에 없으면 "사람을 두 명 더 넣으면
+ * 어떻게 되나" 를 물을 수 없고, 사람이 만들어 내는 줄이 예측에서 통째로 사라진다.
+ */
+export interface PersonState {
+    id: string;
+    /** 소속 등급 — ISA-95 `PersonnelClassID`. 배정은 개인이 아니라 **등급으로 요구**된다. */
+    personnelClass?: string;
+    /** 'idle' | 'busy'. 고장(down)이 없다 — 사람은 그렇게 모델링하지 않는다. */
+    status: string;
+    taskId?: string;
+    /** 교대 밖 — 자원(MoverState.offShift)과 같은 뜻. */
+    offShift?: boolean;
+}
+/**
+ * 물리 자산 — **ISA-95 `PhysicalAsset`, GS1 `GRAI`(반복사용 자산).**
+ *
+ * 왜 물품(Material)과 따로 두는가: **SSCC 와 GRAI 는 다른 것**이다. SSCC 는 *물류단위*(그 팔레트에
+ * 실린 화물 한 덩어리)이고 GRAI 는 *돌아오는 팔레트 자체*다. 같은 GRAI 팔레트가 오늘은 SSCC 999 를,
+ * 내일은 다른 SSCC 를 싣는다. 둘을 뭉개면 **팔레트 회수·풀링을 표현할 수 없고**(팔레트가 화물과 함께
+ * 사라진다), EPCIS 조립 이벤트의 `parentID`(=물류단위)도 뜻이 흐려진다.
+ *
+ * 그리고 빈 팔레트 부족은 현장의 실제 제약이다 — 자산이 없어 작업이 못 나가는 일이 사람 부족만큼 잦다.
+ */
+export interface AssetState {
+    id: string;
+    /** 자산 등급 — pallet · rack · bin · trailer 등. 도메인 소유(코어는 강제하지 않는다). */
+    assetClass?: string;
+    /** 지금 있는 자리. */
+    location?: string;
+    /** 'idle' | 'in-use'. 고장·OEE 로 평가하지 않는다(설비가 아니다). */
+    status: string;
+    /** 지금 이 자산이 잡혀 있는 작업. */
+    taskId?: string;
+    /**
+     * 지금 싣고 있는 물류단위(SSCC 등) — **자산과 화물의 연결.**
+     * 비어 있으면 빈 팔레트다(회수 대상이자 다음 출고의 재료).
+     */
+    carrying?: string;
 }
 export interface TaskState {
     id: string;
@@ -77,6 +182,16 @@ export interface TaskState {
     resourceRef?: string;
     orderId?: string;
     progress?: number;
+    /** 남은 시간·총 소요(ms) — 진행 중인 작업을 이어서 굴리는 데 필요(씨앗의 충실도). */
+    remainingMs?: number;
+    durationMs?: number;
+    /** 작업 의도 — 무자원이 설계인지(체류) 기록 누락인지 구별하는 근거. */
+    intent?: 'transport' | 'process' | 'dwell';
+    /**
+     * 이 작업에 투입된 사람들 — 설비(`resourceRef`)와 **별개 축**이다.
+     * 한 작업이 설비 하나와 사람 여럿을 동시에 잡을 수 있다(용접 로봇 1대 + 작업자 2명).
+     */
+    personnel?: string[];
 }
 export interface OrderState {
     id: string;
@@ -127,6 +242,10 @@ export interface StateSnapshot {
     nodes: NodeState[];
     items: ItemState[];
     movers: MoverState[];
+    /** 사람 — 등급·교대·투입 상태. 인원을 선언하지 않은 트윈에서는 빈 배열. */
+    persons: PersonState[];
+    /** 물리 자산(반복사용) — 선언하지 않은 트윈에서는 빈 배열. */
+    assets: AssetState[];
     tasks: TaskState[];
     orders: OrderState[];
     attentions?: Attention[];
@@ -159,9 +278,23 @@ export interface CommandAck {
 export interface TwinCommandChannel {
     dispatch(command: Pick<Command, 'commandId' | 'type' | 'args'>): Promise<CommandAck>;
 }
+/**
+ * 자극 발생률 — **네 분포 모두 실제로 판정된다**(예전에는 poisson 만 구현되고 나머지는 조용히 상수였다).
+ *
+ *  `constant`  간격 일정
+ *  `poisson`   무기억 도착(지수 간격) — 실제 도착 과정에 가장 가깝다
+ *  `uniform`   0..2×평균 균등 — 평균을 유지하면서 흔들린다
+ *  `profile`   시간대별 배율(`profile[시]`)로 도착률을 조절 — 하루 안의 수요 곡선
+ */
 export interface RateSpec {
     distribution: 'poisson' | 'uniform' | 'constant' | 'profile';
+    /** 시간당 평균 발생 수. `profile` 이면 여기에 시간대 배율이 곱해진다. */
     meanPerHour: number;
+    /**
+     * 시간대 배율 — `profile[시]`(0=자정). `distribution: 'profile'` 일 때만 쓰인다.
+     * 배열이 짧으면 **순환**한다(24개=하루, 8개=8시간 주기). 0 이면 그 시간대에는 발생하지 않는다.
+     * 시(hour)는 시뮬 시각 자신의 프레임 — 계약에 표준시가 없으므로 현지 시간대 해석은 하지 않는다.
+     */
     profile?: number[];
 }
 export interface ContentSpec {
@@ -188,6 +321,11 @@ export interface GeneratorSpec {
     stimulus?: 'arrival' | 'order';
     rate: RateSpec;
     content: ContentSpec;
+    /**
+     * 운영시간 — 이 구간 밖에서는 자극이 발생하지 않는다(문 닫은 시간에 트럭이 오지 않는다).
+     * `startHour <= endHour` 면 같은 날 구간, 넘어가면 자정을 가로지르는 야간 구간(22→6).
+     * 미지정이면 24시간 가동. 시(hour) 해석은 `RateSpec.profile` 과 같다.
+     */
     window?: {
         startHour: number;
         endHour: number;
@@ -209,9 +347,30 @@ export interface ScenarioControl {
 export declare const OP_EVENT: {
     readonly task: "task.status";
     readonly equipment: "equipment.status";
+    /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
+    readonly person: "person.status";
+    /** 물리 자산 상태 전이 — 어디 있나·무엇을 싣고 있나(빈 팔레트인가). */
+    readonly asset: "asset.status";
     readonly order: "order.status";
     readonly quality: "quality.output";
 };
+/** 사람 상태 델타 — 배정·해제·교대 전이 시 방출. 미러가 인원 가용을 비추는 근거. */
+export interface PersonStatusDelta {
+    personId: string;
+    personnelClass?: string;
+    status: string;
+    taskId?: string;
+    offShift?: boolean;
+}
+/** 물리 자산 상태 델타 — 이동·투입·적재/하역 시 방출. 미러가 자산 가용을 비추는 근거. */
+export interface AssetStatusDelta {
+    assetId: string;
+    assetClass?: string;
+    status: string;
+    location?: string;
+    taskId?: string;
+    carrying?: string;
+}
 /** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 무버 누적값. */
 export interface QualityDelta {
     moverId: string;
@@ -221,6 +380,10 @@ export interface QualityDelta {
 }
 export interface TaskStatusDelta {
     taskId: string;
+    /** 투입된 사람들 — 미러가 인원 배정을 그대로 비추려면 델타에 실려야 한다. */
+    personnel?: string[];
+    /** 투입된 물리 자산(팔레트 등). */
+    assets?: string[];
     orderId?: string;
     kind: string;
     status: TaskStatus;
@@ -228,6 +391,23 @@ export interface TaskStatusDelta {
     toNode?: string;
     itemRefs?: string[];
     resourceRef?: string;
+    /**
+     * 작업 의도 — transport(운반) · process(가공) · dwell(체류).
+     *
+     * 없으면 소비처가 "자원이 없는 것" 과 "자원을 쓰지 않는 공정" 을 **구별할 수 없다**(체류는 무자원이
+     * 정상인데 데이터 유실로 읽힌다 — 2026-07-31 에 화면이 그렇게 말할 뻔했다).
+     */
+    intent?: 'transport' | 'process' | 'dwell';
+    /**
+     * 진척(0~1)과 남은 시간(ms) — **진행 중인 작업을 이어서 굴리려면 필요하다.**
+     *
+     * 없으면 미러 상태를 씨앗으로 한 예측이 "진행 중인 일이 하나도 없는 현장" 에서 출발한다.
+     * 완료·생성 시점에는 의미가 없어 in-progress 에만 실린다.
+     */
+    progress?: number;
+    remainingMs?: number;
+    /** 이 작업의 총 소요 예상(ms) — 진척의 분모. */
+    durationMs?: number;
 }
 export interface EquipmentStatusDelta {
     moverId: string;
@@ -267,22 +447,50 @@ export declare const CMD: {
     readonly resourceResetMetrics: "resource.reset-metrics";
     readonly resourceAdd: "resource.add";
 };
-export type OperationalDelta = TaskStatusDelta | EquipmentStatusDelta | OrderStatusDelta;
+export type OperationalDelta = TaskStatusDelta | EquipmentStatusDelta | PersonStatusDelta | AssetStatusDelta | OrderStatusDelta;
 export type EventHandler = (e: CanonicalEnvelope) => void;
 export type Unsubscribe = () => void;
 export interface BoardDef {
+    /** parallelism = 동시 처리 수(NodeState.parallelism 참조). capacity 는 저장 용량. */
     nodes: {
         id: string;
         type: string;
         capacity: number;
+        parallelism?: number;
         parentId?: string;
     }[];
+    /**
+     * 무버(설비). mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실). 미지정=고장 없음.
+     * `window` 지정 시 그 시간대에만 일한다(교대·가동시간) — 미지정이면 24시간 가용(기존 거동).
+     */
     movers: {
         id: string;
         kind: string;
         homeNode: string;
         mtbfMs?: number;
         mttrMs?: number;
+        window?: {
+            startHour: number;
+            endHour: number;
+        };
+    }[];
+    /**
+     * 사람 — ISA-95 `Person`. `personnelClass` 로 등급을 밝히고, `window` 로 교대를 선언한다.
+     * 선언하지 않으면 인원 제약이 없는 트윈이다(기존 거동).
+     */
+    persons?: {
+        id: string;
+        personnelClass?: string;
+        window?: {
+            startHour: number;
+            endHour: number;
+        };
+    }[];
+    /** 물리 자산(반복사용) — ISA-95 `PhysicalAsset` / GS1 `GRAI`. 선언하지 않으면 자산 제약이 없다. */
+    assets?: {
+        id: string;
+        assetClass?: string;
+        homeNode?: string;
     }[];
 }
 export interface TwinKernel {

package/dist/contract.js

@@ -9,6 +9,10 @@
 export const OP_EVENT = {
     task: 'task.status',
     equipment: 'equipment.status',
+    /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
+    person: 'person.status',
+    /** 물리 자산 상태 전이 — 어디 있나·무엇을 싣고 있나(빈 팔레트인가). */
+    asset: 'asset.status',
     order: 'order.status',
     quality: 'quality.output' // 품질 산출(양품/불량) — OEE quality 입력. live 누적기가 이걸로 good/scrap 정확 추적.
 };

package/dist/counterfactual.d.ts

@@ -7,6 +7,8 @@ export interface CounterfactualTwin {
     fork(): CounterfactualTwin;
     dispatch(cmd: Command): CommandAck;
     scenario: ScenarioControl;
+    /** 시뮬 시각(ms) — 구동 루프가 시각만 읽을 때 쓴다(스냅샷 재료화 회피, forecast.ts 주석 참조). */
+    clockMs?: number;
 }
 /** 체크포인트 이력 — 주기적으로 live 를 fork 해 저장(전체 상태 보존). 시간여행의 앵커. */
 export declare class TwinHistory {

package/dist/counterfactual.js

@@ -7,6 +7,10 @@
  * 체크포인트 fork 를 정확히 T 로 재구동(RNG 연속 → 실제와 일치)한 뒤 분기 = 결정적 반사실.
  */
 import { compareStates } from "./divergence.js";
+/** 구동 루프용 시각 읽기 — 숫자 하나 때문에 전체 상태를 만들지 않는다. */
+function clockOf(twin) {
+    return typeof twin.clockMs === 'number' ? twin.clockMs : twin.getSnapshot().simClockMs;
+}
 /** 체크포인트 이력 — 주기적으로 live 를 fork 해 저장(전체 상태 보존). 시간여행의 앵커. */
 export class TwinHistory {
     live;
@@ -18,7 +22,7 @@ export class TwinHistory {
     }
     /** 현재를 체크포인트로 저장(호스트가 주기적으로 호출). */
     checkpoint() {
-        this.checkpoints.push({ simMs: this.live.getSnapshot().simClockMs, twin: this.live.fork() });
+        this.checkpoints.push({ simMs: clockOf(this.live), twin: this.live.fork() });
     }
     get count() {
         return this.checkpoints.length;
@@ -33,7 +37,7 @@ export class TwinHistory {
             return undefined;
         const t = best.twin.fork();
         let guard = 0;
-        while (t.getSnapshot().simClockMs < simMs && guard++ < 1_000_000)
+        while (clockOf(t) < simMs && guard++ < 1_000_000)
             t.tick(this.tickMs);
         return t;
     }
@@ -51,7 +55,7 @@ export function counterfactualAt(history, atSimMs, opts) {
     const withAlt = base.fork();
     opts.alternative(withAlt);
     const baseline = base.fork();
-    const run = (t) => { let g = 0; while (t.getSnapshot().simClockMs < target && g++ < 1_000_000)
+    const run = (t) => { let g = 0; while (clockOf(t) < target && g++ < 1_000_000)
         t.tick(step); };
     run(withAlt);
     run(baseline);

package/dist/domain-definition.d.ts

@@ -32,7 +32,61 @@ export interface ResourceTypeDef {
 }
 /** 작업 의도 — FlowTask.intent 와 정합(ISA-95 이동 vs 변환). */
 export type OperationIntent = 'transport' | 'process' | 'dwell';
-/** 오퍼레이션 타입(공정 한 작업) — ISA-95 OperationsDefinition. */
+/**
+ * ISO 8601 기간 표기(예 `PT12M`·`PT1H15M`) — **ISA-95 와 같은 표기.**
+ * 근거: B2MML `OperationsSegmentType.Duration` 의 타입 `DurationType` = `xsd:restriction base="xsd:duration"`.
+ * 밀리초 숫자로 계약하지 않는 이유: 명세는 사람과 원 시스템이 주는 값이고, 표준이 이미 표기를 정해 뒀다.
+ */
+export type IsoDuration = string;
+/**
+ * 공정 모수 — **ISA-95 `OperationsSegment.ParameterSpecification`(`ParameterType`) 1:1.**
+ * 표준의 `ParameterType` = `ID` + `Value`(`ValueString` + `DataType` + `UnitOfMeasure`) 이므로 그 모양을 따른다.
+ *
+ * 표준은 **파라미터 ID 어휘를 정하지 않는다** — 상위 문서/당사자 합의 소관이다. 그래서 우리가 쓰는 ID 는
+ * `OP_PARAM` 한 곳에서만 정의한다(어휘를 코드 곳곳에서 발명하지 않기 위해 — ILMD_ATTR 과 같은 규율).
+ */
+export interface OperationParameter {
+    /** ISA-95 `Parameter.ID`. 우리 canonical ID 는 `OP_PARAM` 참조. */
+    id: string;
+    /** ISA-95 `Value.ValueString` — 표준이 문자열로 싣는다(숫자는 소비처가 해석). */
+    value: string;
+    /** ISA-95 `Value.UnitOfMeasure`. 무차원(비율 등)이면 생략. */
+    uom?: string;
+}
+/**
+ * 우리가 소비하는 canonical 파라미터 ID — **표준이 이름을 정해 주지 않는 자리**이므로 여기서 한 번 정한다.
+ * 새 모수를 쓸 때는 반드시 여기에 등록한다(문자열 리터럴을 코드에 흩뿌리지 않는다).
+ */
+export declare const OP_PARAM: {
+    /** 양품률(0..1, 무차원). 없으면 커널 기본값 — 기본값을 쓴 사실은 `specCoverage()` 가 밝힌다. */
+    readonly yield: "yield";
+    /** 셋업·체인지오버 소요(ISO 8601 기간 문자열). ISA-95 는 셋업을 별도 세그먼트로도 표현하지만,
+     *  현재 커널은 작업에 붙는 셋업으로 다루므로 모수로 받는다. */
+    readonly setupDuration: "setupDuration";
+};
+/**
+ * 소요시간 변동 — **표준 밖 확장이며, 그렇게 표시한다.**
+ * ISA-95 `Duration` 은 스칼라 하나라 분포를 담지 못한다. 그런데 시뮬레이션의 신뢰도는 분산에서 나온다
+ * (평균만 맞는 상수 모델은 대기·병목을 구조적으로 과소평가한다). 그래서 평균은 표준 자리(`duration`)에
+ * 두고, 변동은 이 확장 자리에 둔다 — 섞지 않는다.
+ *
+ * 표본은 **엔진의 난수원**으로 뽑는다(추정기가 자기 난수를 쓰면 fork 결정성이 깨진다).
+ */
+export interface DurationVariability {
+    /** `constant`=변동 없음(기본) · `exponential`(평균=duration) · `uniform`·`triangular`(min/max 필수). */
+    distribution: 'constant' | 'exponential' | 'uniform' | 'triangular';
+    min?: IsoDuration;
+    max?: IsoDuration;
+    /** triangular 최빈값. 없으면 `duration` 을 최빈값으로 본다. */
+    mode?: IsoDuration;
+}
+/**
+ * 오퍼레이션 타입(공정 한 작업) — ISA-95 `OperationsSegment`.
+ *
+ * **시뮬레이션 명세가 여기 있어야 한다.** 예전에는 이 정의가 "무엇을·어디서·누가" 만 담고 "얼마나
+ * 걸리나·얼마나 성공하나" 는 커널 소스의 상수(30·20·40초, 수율 0.8)였다. 그래서 현장마다 다른 값을
+ * 데이터로 줄 방법이 없었고, 그 상수가 주목 신호(불량률 높음)까지 만들어 냈다.
+ */
 export interface OperationDef {
     key: string;
     label: string;
@@ -43,6 +97,35 @@ export interface OperationDef {
     resourceType?: string;
     /** CBV bizStep URN(방출 이벤트 어휘). */
     bizStep?: string;
+    /**
+     * 소요시간(평균/기준) — ISA-95 `OperationsSegment.Duration` 과 1:1. 없으면 커널 기본값을 쓰고,
+     * **기본값을 썼다는 사실을 숨기지 않는다**(`specCoverage()`).
+     */
+    duration?: IsoDuration;
+    /** 소요시간 변동(표준 밖 확장). 미지정 = 상수. */
+    variability?: DurationVariability;
+    /** 공정 모수(수율·셋업 등) — ISA-95 `ParameterSpecification` 1:1. ID 어휘는 `OP_PARAM`. */
+    parameters?: OperationParameter[];
+    /**
+     * 필요 인원 — **ISA-95 `OperationsSegment.PersonnelSpecification`**(`PersonnelClassID` + `Quantity`) 1:1.
+     *
+     * 이것이 없으면 사람은 시뮬레이션에 존재하지 않는다 — 설비만 있으면 언제나 돌아가는 공장이 된다.
+     * 현장에서 가장 자주 부족한 자원이 사람인데, 그 부족이 만드는 줄이 예측에서 통째로 사라진다.
+     * 등급(class)으로 요구한다: 특정인을 지목하는 것이 아니라 "용접 자격자 2명" 이다.
+     */
+    personnelSpecification?: {
+        personnelClass?: string;
+        quantity: number;
+    }[];
+    /**
+     * 필요 물리 자산 — **ISA-95 `OperationsSegment.PhysicalAssetSpecification`** 과 같은 자리
+     * (`PhysicalAssetClassID` + `Quantity`). 빈 팔레트가 없어 출고가 못 나가는 일은 현장에서 잦다.
+     * 인원과 같은 규칙: 등급으로 요구하고, 모자라면 **부분 투입 없이 기다린다.**
+     */
+    physicalAssetSpecification?: {
+        assetClass?: string;
+        quantity: number;
+    }[];
 }
 /** 라우트(오퍼레이션 시퀀스) — ISA-95 ProcessSegment 연결. */
 export interface RouteDef {

package/dist/domain-definition.js

@@ -6,6 +6,17 @@
  * 스토어 패키지 `@operato/twin-catalog` 가 이 타입을 import 해 스토어 메타(version/supplier)를 얹어 배포한다(catalog → kernel 의존).
  * 표준 앵커: GS1 EPCIS 2.0(bizStep) · ISA-95(WorkCenter·OperationsDefinition·BOM) · ISO 55000(Asset).
  */
+/**
+ * 우리가 소비하는 canonical 파라미터 ID — **표준이 이름을 정해 주지 않는 자리**이므로 여기서 한 번 정한다.
+ * 새 모수를 쓸 때는 반드시 여기에 등록한다(문자열 리터럴을 코드에 흩뿌리지 않는다).
+ */
+export const OP_PARAM = {
+    /** 양품률(0..1, 무차원). 없으면 커널 기본값 — 기본값을 쓴 사실은 `specCoverage()` 가 밝힌다. */
+    yield: 'yield',
+    /** 셋업·체인지오버 소요(ISO 8601 기간 문자열). ISA-95 는 셋업을 별도 세그먼트로도 표현하지만,
+     *  현재 커널은 작업에 붙는 셋업으로 다루므로 모수로 받는다. */
+    setupDuration: 'setupDuration'
+};
 const INTENTS = ['transport', 'process', 'dwell'];
 function dupes(keys) {
     const seen = new Set();

package/dist/duration-estimator.d.ts

@@ -4,9 +4,33 @@ export interface DurationContext {
     toNode: string;
     resourceKind?: string;
 }
+/**
+ * 관측된 퍼짐 — **평균만 배우면 대기와 병목을 과소평가한다.**
+ *
+ * 이력에서 배운 값이 스칼라 하나뿐이면 그 작업은 늘 정확히 같은 시간이 걸린다. 실제 현장은 그렇지
+ * 않고, 그 흔들림이 줄을 만든다(변동이 없으면 대기도 없다). 그래서 추정기가 분포까지 알면 그것을
+ * 넘긴다 — **표본은 엔진이 자기 난수로 뽑는다**(추정기가 자기 난수를 쓰면 fork 결정성이 깨진다).
+ *
+ * 단위는 ms 다(ISO 8601 은 사람이 선언하는 명세의 표기이고, 이쪽은 계측에서 나온 수다).
+ */
+export interface DurationSpread {
+    distribution: 'triangular' | 'uniform';
+    minMs: number;
+    maxMs: number;
+    /** triangular 최빈값. 없으면 평균을 최빈값으로 본다. */
+    modeMs?: number;
+}
+/** 분포까지 아는 추정치 — 평균 + 관측된 퍼짐. */
+export interface DurationEstimate {
+    meanMs: number;
+    spread?: DurationSpread;
+}
 export interface DurationEstimator {
-    /** 소요(ms). undefined 반환 시 도메인 기본값(fallback) 사용 — 일부 kind 만 다루고 나머지는 defer 가능. */
-    estimate(ctx: DurationContext): number | undefined;
+    /**
+     * 소요. **숫자**(평균만 안다) 또는 **추정치 객체**(퍼짐까지 안다)를 낼 수 있다.
+     * undefined 면 도메인 기본값(fallback) — 일부 kind 만 다루고 나머지는 defer 가능.
+     */
+    estimate(ctx: DurationContext): number | DurationEstimate | undefined;
 }
 /** 균일 상수 estimator (테스트·단순 보드용). 실 duration 은 보통 씬-유도 estimator 가 제공. */
 export declare const constantDuration: (ms: number) => DurationEstimator;