@operato/twin-kernel 0.0.1

package/README.md

@@ -0,0 +1,80 @@
+# @operato-twin/kernel — 비즈니스레이어 디지털트윈 커널
+
+물류창고·야드·스마트팩토리의 **비즈니스 실행**을 시뮬레이션·모니터링하는 **헤드리스·프레임워크 무관·zero-dep** TS 커널. UI/3D/DOM 없이 순수 Node 에서 도는 것이 목적(sim=능동 생산, live=수동 미러, 계약 동일).
+
+- 실행: `node --test test/*.test.ts` (Node 25 네이티브 TS, **무의존**)
+- 상태: **38 tests green**, 3 버티컬(WMS/YMS/MES)
+
+## 계층 (아래로만 의존, 무방언)
+
+```
+contract.ts      3채널 계약(State/Command/Scenario) + 운영 델타 + TwinKernel  ← 도메인/표준 무관
+epcis.ts         GS1 EPCIS 2.0 이벤트 machinery(타입·빌더·검증기·URI·CBV disp) ← 표준(도메인 무관)
+flow-engine.ts   FlowEngine base — mechanics(RNG·clock·tick·자원배정·태스크진행·emit·snapshot)
+allocation-policy.ts  AllocationPolicy 확장 시임(selectPlacement/selectStock)
+state-projector.ts    이벤트 스트림 → State 투영(모니터링 미러)   ← 도메인 무관
+runtime.ts       TwinRuntime — host-facing facade + 구독 프로토콜  ← 도메인/전송 무관
+face2-adapter.ts 레거시 레코드 → 정규 EPCIS(선언적 매핑 + 검증)   ← ACL
+
+{wms,yms,mes}-profile.ts   도메인 어휘(bizStep/btt)만
+{wms,yms,mes}-kernel.ts    도메인 flow 동사(4 hook) — FlowEngine 확장
+```
+
+> **무방언 원칙**: 코어(contract/epcis/flow-engine/policy/projector/runtime)에 특정 도메인 용어를 넣지 않는다. EPCIS 는 표준이라 `epcis.ts`(≠wms). order.kind·task.resourceType 등은 도메인이 소유. 정책 인터페이스는 `selectPlacement`/`selectStock`(≠putaway/pallets).
+
+## FlowEngine — 단일 base, 도메인은 4 hook 만
+
+`abstract FlowEngine implements TwinKernel` 이 모든 mechanics 를 소유. 도메인 kernel 은 **flow 동사**만 구현:
+
+| hook | 역할 |
+|---|---|
+| `onArrival(spec)` | 입고/도착 자극 → 아이템 생성 + EPCIS + 반입 태스크 |
+| `onOrder(spec)` | 오더/작업지시 자극 → 오더 생성 |
+| `allocate(order)` | created 오더 할당 → 재고 선택(정책) + 태스크. **시간창 게이트도 여기**(스케줄링) |
+| `onTaskComplete(task)` | 완료의 의미 — 이동(WMS/YMS) 또는 변환(MES). occupancy·EPCIS·오더 이행 전부 도메인 |
+
+base 는 task **생명주기**(자원 배정·진행·완료·해제·델타)만 소유 → 이동-중립. 새 버티컬 = 프로파일(어휘) + kernel(4 hook), **~100줄**.
+
+## 3 버티컬 — base 가 4 flow 성격을 담음을 실증
+
+| 버티컬 | flow 성격 | base 대응 |
+|---|---|---|
+| **WMS** | 이동 (putaway/pick/pack/ship) + 백오더 | 기본 |
+| **YMS** | 이동 (spot/pull) + **시간창 스케줄링**(어포인트먼트↔도크도어 예약) | 스케줄링=도메인 게이팅으로 **base 흡수** |
+| **MES** | **변환**(TransformationEvent) + 다단계 라우팅 + **이종 자원**(cutter/welder) | 자원 매칭=`FlowTask.resourceType` **base 확장**(load-bearing 검증) |
+
+두 진화 축: 시간창 스케줄링=흡수, 자원-타입 매칭=최소 확장. 둘 다 backward-compatible(기존 도메인 무영향, 예제 바이트 동일로 검증).
+
+## 3채널 계약 (Face 1) + 구독
+
+- **State**: `getSnapshot()`(스냅샷) + 델타 이벤트 스트림. 델타 = EPCIS(재고/위치/조립/변환) + 운영 델타(`task/equipment/order.status`, EPCIS 로 재구성 불가한 절반).
+- **Command** (행위/act): `dispatch(cmd)` 가 실제로 sim 을 변이 → State 델타 유발(폐루프). 코어 공통 `order.hold`/`resume`(할당 보류/재개) + 도메인 `order.release`(즉시 투입) 등은 `handleCommand` 시임으로 확장.
+- **Scenario**: `scenario.load/start/pause/setSpeed`(시뮬 자극).
+- **TwinRuntime**: `subscribe`(snapshot→delta, revision 연속) · `resync` · `tick`. sparse 스트리밍(전이·move-start 만, 매 tick 아님).
+
+## State 이원 모델
+- **EPCIS 저널**(이산): 재고·위치·조립·변환. `epcis.ts` 로 정규 방출, `validateEpcisEvent` 검증.
+- **운영·키네마틱**(연속): 무버 motion(from/to/progress)·태스크·오더 진척. 운영 델타로 미러.
+- **StateProjector** 가 둘을 접어 재구성 → sim 이벤트든 live 이벤트든 같은 State(데이터원 스왑).
+
+## 트윈 본연 — 현재로부터 예측 + 정합 (mirror+sim 과 구별짓는 기능)
+관측·예측·행위가 따로 있는 건 mirror+simulator. 트윈의 본질은 그 **커플링**:
+- **`kernel.fork()`** — 현재 상태(in-flight 포함)를 정확히 복제한 격리 엔진. 원본(live/sim)은 계속 가고, fork 는 **현재로부터 앞으로 굴려** forecast(완료 시각·처리량)·대안 what-if 탐색.
+- **`compareStates(predicted, actual)`** — fork 예측 vs 실제 관측을 같은 시점에 대조 → **드리프트(모델↔현실 이탈) 탐지·국소화**(item/node/order 필드별). 발산 = 이상/개입 신호.
+- 루프: 관측(현재) → fork 예측(미래) → 관측(실제) → 정합(발산) → 행위(개입).
+- **`EventJournal` + `replay(board, events)`** — 트윈의 **기억**: 이벤트열이 곧 상태(이벤트-소싱). `journal.until(revision)`/`untilSimTime(iso)` 을 projector 로 재생 → **임의 과거 시점 상태 재구성(시간여행)**. 감사·리플레이·발산 비교의 기반. things-factory 에선 append 를 DB 이벤트 테이블로 교체.
+
+### 본질 심화
+- **fork = 완전한 결정적 분기** — 상태 + 시나리오(gens) + **RNG state** 까지 복제 → 미래 생성까지 원본과 동일하게 이어가는 진짜 continuation(what-if 는 fork 후 scenario 교체).
+- **`TwinObserver`** — 자동 정합 루프: 주기적으로 fork-예측 후 실제가 그 시점 도달 시 대조 → **드리프트를 알림 이벤트로**. 트윈이 자기 모델↔현실 이탈을 능동 감지(방해 없으면 발산 0).
+- **`monteCarloForecast`** — 확률적 예측: seed 변주 N개 fork → 지표를 **분포**로(min/mean/p50/p90/max). "언제 끝나?"가 아니라 "P90 완료시각·소진 확률". 원본 무간섭.
+- **`TwinHistory` + `counterfactualAt`** — 반사실(기억+분기): 주기 checkpoint(전체 커널 fork 저장) → 과거 시점 T로 되돌아가(사이 시점은 결정적 재구동) **대안 결정을 fork** → 앞으로 굴려 baseline 과 대조 → **"그때 X 했다면?"의 효과**. 사후분석·의사결정 평가.
+
+## 확장 지점
+- **버티컬 추가**: `{x}-profile.ts`(어휘) + `{x}-kernel.ts`(4 hook).
+- **할당 정책**: `AllocationPolicy` 교체(firstFit/partialFit 내장, FEFO/nearest/zone 추가 가능).
+- **Face2 어댑터**: 실 시스템 페이로드 → 선언적 매핑 → 정규 EPCIS.
+- **host 결합**: `TwinRuntime` 를 GraphQL sub·서비스로 래핑(전송은 얇은 host 계층).
+
+## 미구현(범위 밖)
+host 결합(things-factory 전송/퍼시스턴스/커넥터) · 보드 바인딩(컴포넌트↔SGLN) · 도메인 깊이(WMS 멀티라인, YMS 상하차 AggregationEvent, MES BOM/수율). 설계 SoT: `operato-twin/design/`.

package/dist/allocation-policy.d.ts

@@ -0,0 +1,48 @@
+/** 배치(placement) 대상 후보 슬롯의 관측 뷰 (내부 상태 누출 없이 결정에 필요한 만큼만). */
+export interface SlotView {
+    id: string;
+    capacity: number;
+    occupancy: number;
+    reserved: number;
+}
+/** 할당 후보 재고(가용 스톡)의 관측 뷰. */
+export interface StockView {
+    epc: string;
+    location: string;
+    qty: number;
+    expiry?: number;
+}
+export interface PlacementContext {
+    item: {
+        epc: string;
+        gtin: string;
+        qty: number;
+    };
+    slots: readonly SlotView[];
+}
+export interface StockRequest {
+    gtin: string;
+    qty: number;
+    available: readonly StockView[];
+}
+export interface AllocationPolicy {
+    /** 배치 목적지 슬롯 id. 수용 불가면 null(도크 대기 → 다음 tick 재시도). */
+    selectPlacement(ctx: PlacementContext): string | null;
+    /** 이번 라운드에 할당할 재고 epc 목록(부분 가능). 빈 배열 = 이번엔 할당 보류. */
+    selectStock(ctx: StockRequest): readonly string[];
+}
+/**
+ * 기본 정책 — first-fit slot + all-or-nothing 오더 할당.
+ * (재고가 요청 전량을 못 채우면 이번 라운드 보류 → 전량 확보 시 단일 출하.)
+ */
+export declare const firstFitPolicy: AllocationPolicy;
+/**
+ * 부분할당 정책 — first-fit slot + 가용분만큼 즉시 할당(백오더).
+ * 재고 일부만 있어도 그만큼 먼저 출하하고, 잔량은 재고 도착 시 후속 라운드로 채운다.
+ */
+export declare const partialFitPolicy: AllocationPolicy;
+/**
+ * FEFO 정책 — First-Expired-First-Out. 만료 임박 로트를 먼저 출고(신선/제약 도메인).
+ * all-or-nothing(전량 확보 전 대기)이되 선택 순서는 만료 오름차순(동률은 epc). 코어 수정 없이 정책 교체만으로 확장(원칙 2).
+ */
+export declare const fefoPolicy: AllocationPolicy;

package/dist/allocation-policy.js

@@ -0,0 +1,50 @@
+/*
+ * 할당 정책 — 확장 시임 (헌장 원칙 2: 불변 코어 + 확장 시임, open/closed).
+ *
+ * 커널 코어는 "무엇을(putaway 할 팔레트, 출고할 오더)"만 알고, "어디에·어느 것을"의
+ * 결정은 정책에 위임한다. 고객은 FIFO/FEFO/nearest/zone·부분할당 등을 정책 교체로만
+ * 확장 — 코어 수정 없이. (설계 gap #5 "할당 정책 플러그")
+ */
+function freeBinsFirstFit(slots) {
+    const sorted = [...slots].sort((a, b) => a.id.localeCompare(b.id));
+    for (const b of sorted)
+        if (b.occupancy + b.reserved < b.capacity)
+            return b.id;
+    return null;
+}
+function sortByEpc(available) {
+    return [...available].sort((a, b) => a.epc.localeCompare(b.epc));
+}
+/**
+ * 기본 정책 — first-fit slot + all-or-nothing 오더 할당.
+ * (재고가 요청 전량을 못 채우면 이번 라운드 보류 → 전량 확보 시 단일 출하.)
+ */
+export const firstFitPolicy = {
+    selectPlacement: ({ slots }) => freeBinsFirstFit(slots),
+    selectStock: ({ qty, available }) => {
+        if (available.length < qty)
+            return []; // 전량 확보 전엔 대기
+        return sortByEpc(available).slice(0, qty).map(s => s.epc);
+    }
+};
+/**
+ * 부분할당 정책 — first-fit slot + 가용분만큼 즉시 할당(백오더).
+ * 재고 일부만 있어도 그만큼 먼저 출하하고, 잔량은 재고 도착 시 후속 라운드로 채운다.
+ */
+export const partialFitPolicy = {
+    selectPlacement: ({ slots }) => freeBinsFirstFit(slots),
+    selectStock: ({ qty, available }) => sortByEpc(available).slice(0, qty).map(s => s.epc)
+};
+/**
+ * FEFO 정책 — First-Expired-First-Out. 만료 임박 로트를 먼저 출고(신선/제약 도메인).
+ * all-or-nothing(전량 확보 전 대기)이되 선택 순서는 만료 오름차순(동률은 epc). 코어 수정 없이 정책 교체만으로 확장(원칙 2).
+ */
+export const fefoPolicy = {
+    selectPlacement: ({ slots }) => freeBinsFirstFit(slots),
+    selectStock: ({ qty, available }) => {
+        if (available.length < qty)
+            return []; // 전량 확보 전엔 대기
+        const byExpiry = [...available].sort((a, b) => (a.expiry ?? Infinity) - (b.expiry ?? Infinity) || a.epc.localeCompare(b.epc));
+        return byExpiry.slice(0, qty).map(s => s.epc);
+    }
+};

package/dist/contract.d.ts

@@ -0,0 +1,205 @@
+export type ISOTime = string;
+export interface CanonicalEnvelope<T = unknown> {
+    eventId: string;
+    eventType: string;
+    eventTime: ISOTime;
+    tenantId: string;
+    correlationId?: string;
+    data: T;
+}
+export type TaskStatus = 'created' | 'assigned' | 'in-progress' | 'completed';
+export interface NodeState {
+    id: string;
+    type: string;
+    capacity?: number;
+    occupancy: number;
+    status?: string;
+}
+export interface ItemState {
+    epc: string;
+    gtin?: string;
+    location: string;
+    disposition?: string;
+    parent?: string;
+    qty?: number;
+    expiry?: number;
+}
+/**
+ * 운영·키네마틱 모션 — State 이원 모델의 "연속" 절반.
+ * 백엔드는 이동 시작 시 이 값(from/to/duration)만 방출하고, UI 는 progress 를
+ * 로컬 프레임레이트로 보간한다(매 tick 통신 아님). 좌표는 커널 토폴로지 수준이 아니라
+ * 보드 바인딩에서 노드→좌표로 해석. 상세: design/simulation/execution-model.md §4·§5
+ */
+export interface MoverMotion {
+    fromNode: string;
+    toNode: string;
+    startedAtSimMs: number;
+    durationMs: number;
+    progress: number;
+    elapsedMs: number;
+}
+/**
+ * 설비 종합효율(OEE = Availability × Performance × Quality) — 도메인-일반 설비 메트릭.
+ * 규약(단일 컨벤션): PlannedTime=설비 존재 sim 시간. Availability 손실=셋업(+고장), Performance 손실=기아(유휴),
+ * Quality 손실=불량. Availability=(planned−setup)/planned · Performance=run/(planned−setup) · Quality=good/(good+scrap).
+ * → OEE=(run/planned)×quality. 세 인자가 손실 위치(셋업·기아·불량)를 분해해 드러낸다.
+ */
+export interface OeeMetrics {
+    availability: number;
+    performance: number;
+    quality: number;
+    overall: number;
+    runMs: number;
+    setupMs: number;
+    downMs: number;
+    idleMs: number;
+    goodCount: number;
+    scrapCount: number;
+}
+export interface MoverState {
+    id: string;
+    kind: string;
+    location?: string;
+    status: string;
+    taskId?: string;
+    motion?: MoverMotion;
+    oee?: OeeMetrics;
+}
+export interface TaskState {
+    id: string;
+    kind: string;
+    status: TaskStatus;
+    itemRefs?: string[];
+    fromNode?: string;
+    toNode?: string;
+    resourceRef?: string;
+    progress?: number;
+}
+export interface OrderState {
+    id: string;
+    kind: string;
+    status: string;
+    progress?: number;
+    held?: boolean;
+}
+export interface StateSnapshot {
+    revision: number;
+    simClockMs: number;
+    nodes: NodeState[];
+    items: ItemState[];
+    movers: MoverState[];
+    tasks: TaskState[];
+    orders: OrderState[];
+}
+export interface Command<T = unknown> {
+    commandId: string;
+    type: string;
+    tenantId: string;
+    correlationId?: string;
+    args: T;
+}
+export interface CommandAck {
+    commandId: string;
+    accepted: boolean;
+    error?: string;
+}
+export interface RateSpec {
+    distribution: 'poisson' | 'uniform' | 'constant' | 'profile';
+    meanPerHour: number;
+    profile?: number[];
+}
+export interface ContentSpec {
+    skuMix: {
+        gtin: string;
+        weight: number;
+    }[];
+    qtyPerLine: {
+        min: number;
+        max: number;
+    };
+    linesPerOrder?: {
+        min: number;
+        max: number;
+    };
+}
+export interface GeneratorSpec {
+    kind: 'inbound-arrival' | 'outbound-order';
+    rate: RateSpec;
+    content: ContentSpec;
+    window?: {
+        startHour: number;
+        endHour: number;
+    };
+}
+export interface ScenarioDef {
+    seed?: number;
+    speed?: number;
+    horizon?: number;
+    generators: GeneratorSpec[];
+}
+export interface ScenarioControl {
+    load(def: ScenarioDef): void;
+    start(): void;
+    pause(): void;
+    reset(): void;
+    setSpeed(factor: number): void;
+}
+export declare const OP_EVENT: {
+    readonly task: "task.status";
+    readonly equipment: "equipment.status";
+    readonly order: "order.status";
+};
+export interface TaskStatusDelta {
+    taskId: string;
+    kind: string;
+    status: TaskStatus;
+    fromNode?: string;
+    toNode?: string;
+    itemRefs?: string[];
+    resourceRef?: string;
+}
+export interface EquipmentStatusDelta {
+    moverId: string;
+    kind: string;
+    status: string;
+    location?: string;
+    motion?: MoverMotion;
+}
+export interface OrderStatusDelta {
+    orderId: string;
+    kind: string;
+    status: string;
+    requested: number;
+    fulfilled: number;
+    held?: boolean;
+}
+export declare const CMD: {
+    readonly orderHold: "order.hold";
+    readonly orderResume: "order.resume";
+    readonly orderRelease: "order.release";
+};
+export type OperationalDelta = TaskStatusDelta | EquipmentStatusDelta | OrderStatusDelta;
+export type EventHandler = (e: CanonicalEnvelope) => void;
+export type Unsubscribe = () => void;
+export interface BoardDef {
+    nodes: {
+        id: string;
+        type: string;
+        capacity: number;
+    }[];
+    movers: {
+        id: string;
+        kind: string;
+        homeNode: string;
+        mtbfMs?: number;
+        mttrMs?: number;
+    }[];
+}
+export interface TwinKernel {
+    loadBoard(def: BoardDef): void;
+    getSnapshot(): StateSnapshot;
+    onEvent(handler: EventHandler): Unsubscribe;
+    dispatch(cmd: Command): CommandAck;
+    readonly scenario: ScenarioControl;
+    tick(dtMs: number): void;
+}

package/dist/contract.js

@@ -0,0 +1,20 @@
+/*
+ * Face 1 — 3채널 계약 (walking skeleton 범위).
+ * 설계 SoT: operato-twin/design/integration/face1-contract.md
+ */
+// ── 운영 델타(비-EPCIS) — State 채널의 나머지 절반 ──────────────────────────
+// EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·movers(equipment)·orders 의 운영 상태는
+// 이 델타로 미러한다. envelope.eventType = 'task.status' | 'equipment.status' | 'order.status'.
+// (execution-model.md §5, roadmap 발견 gap: 운영 델타 이벤트화)
+export const OP_EVENT = {
+    task: 'task.status',
+    equipment: 'equipment.status',
+    order: 'order.status'
+};
+// ── Command 채널 어휘 — 트윈의 "행위(act)" 면 (prescriptive/트랜잭션 프론트엔드) ──
+// 코어 공통: order.hold/resume(할당 보류). 도메인: order.release(즉시 투입) 등은 handleCommand 로.
+export const CMD = {
+    orderHold: 'order.hold',
+    orderResume: 'order.resume',
+    orderRelease: 'order.release'
+};

package/dist/counterfactual.d.ts

@@ -0,0 +1,40 @@
+import type { Command, CommandAck, ScenarioControl, StateSnapshot } from './contract.ts';
+import { type StateDivergence } from './divergence.ts';
+/** fork·구동·행위 가능한 트윈(FlowEngine 이 만족). */
+export interface CounterfactualTwin {
+    getSnapshot(): StateSnapshot;
+    tick(dtMs: number): void;
+    fork(): CounterfactualTwin;
+    dispatch(cmd: Command): CommandAck;
+    scenario: ScenarioControl;
+}
+/** 체크포인트 이력 — 주기적으로 live 를 fork 해 저장(전체 상태 보존). 시간여행의 앵커. */
+export declare class TwinHistory {
+    private live;
+    private tickMs;
+    private checkpoints;
+    constructor(live: CounterfactualTwin, opts?: {
+        tickMs?: number;
+    });
+    /** 현재를 체크포인트로 저장(호스트가 주기적으로 호출). */
+    checkpoint(): void;
+    get count(): number;
+    /** 시각 T 의 전체 커널 — T 이하 최신 체크포인트에서 fork 후 정확히 T 로 재구동(결정적). */
+    at(simMs: number): CounterfactualTwin | undefined;
+}
+export interface CounterfactualResult {
+    atSimMs: number;
+    withAlt: StateSnapshot;
+    baseline: StateSnapshot;
+    effect: StateDivergence;
+}
+export interface CounterfactualOptions {
+    alternative: (twin: CounterfactualTwin) => void;
+    horizonMs: number;
+    tickMs?: number;
+}
+/**
+ * 반사실: history 의 시각 T 상태에서 두 분기를 굴려 대안의 효과를 잰다.
+ *   withAlt = T 상태 + 대안 → T+H  /  baseline = T 상태 그대로 → T+H  /  effect = 둘의 발산.
+ */
+export declare function counterfactualAt(history: TwinHistory, atSimMs: number, opts: CounterfactualOptions): CounterfactualResult | undefined;

package/dist/counterfactual.js

@@ -0,0 +1,59 @@
+/*
+ * Counterfactual + Checkpointing — "과거 T에 다른 결정을 했다면?" (기억 + 분기 결합).
+ *
+ * replay(기억)는 과거를 재구성만 한다. 여기에 fork(분기)를 결합하면 반사실 분석:
+ * 과거 시점으로 되돌아가 대안 결정을 넣고 앞으로 굴려, 실제(대안 없음)와 대조 → 대안의 효과.
+ * 전체 커널 상태가 필요하므로(replay 의 projected 상태로는 부족) 주기적 checkpoint(fork 저장)를 쓴다.
+ * 체크포인트 fork 를 정확히 T 로 재구동(RNG 연속 → 실제와 일치)한 뒤 분기 = 결정적 반사실.
+ */
+import { compareStates } from "./divergence.js";
+/** 체크포인트 이력 — 주기적으로 live 를 fork 해 저장(전체 상태 보존). 시간여행의 앵커. */
+export class TwinHistory {
+    live;
+    tickMs;
+    checkpoints = [];
+    constructor(live, opts = {}) {
+        this.live = live;
+        this.tickMs = opts.tickMs ?? 1000;
+    }
+    /** 현재를 체크포인트로 저장(호스트가 주기적으로 호출). */
+    checkpoint() {
+        this.checkpoints.push({ simMs: this.live.getSnapshot().simClockMs, twin: this.live.fork() });
+    }
+    get count() {
+        return this.checkpoints.length;
+    }
+    /** 시각 T 의 전체 커널 — T 이하 최신 체크포인트에서 fork 후 정확히 T 로 재구동(결정적). */
+    at(simMs) {
+        let best;
+        for (const c of this.checkpoints)
+            if (c.simMs <= simMs)
+                best = c;
+        if (!best)
+            return undefined;
+        const t = best.twin.fork();
+        let guard = 0;
+        while (t.getSnapshot().simClockMs < simMs && guard++ < 1_000_000)
+            t.tick(this.tickMs);
+        return t;
+    }
+}
+/**
+ * 반사실: history 의 시각 T 상태에서 두 분기를 굴려 대안의 효과를 잰다.
+ *   withAlt = T 상태 + 대안 → T+H  /  baseline = T 상태 그대로 → T+H  /  effect = 둘의 발산.
+ */
+export function counterfactualAt(history, atSimMs, opts) {
+    const base = history.at(atSimMs);
+    if (!base)
+        return undefined;
+    const step = opts.tickMs ?? 1000;
+    const target = atSimMs + opts.horizonMs;
+    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)
+        t.tick(step); };
+    run(withAlt);
+    run(baseline);
+    return { atSimMs, withAlt: withAlt.getSnapshot(), baseline: baseline.getSnapshot(), effect: compareStates(withAlt.getSnapshot(), baseline.getSnapshot()) };
+}

package/dist/divergence.d.ts

@@ -0,0 +1,15 @@
+import type { StateSnapshot } from './contract.ts';
+export interface FieldDiff<T> {
+    id: string;
+    predicted: T | undefined;
+    actual: T | undefined;
+}
+export interface StateDivergence {
+    hasDrift: boolean;
+    itemLocation: FieldDiff<string>[];
+    itemDisposition: FieldDiff<string>[];
+    nodeOccupancy: FieldDiff<number>[];
+    orderStatus: FieldDiff<string>[];
+}
+/** predicted(fork forecast)와 actual(관측) 스냅샷을 대조. 같은 sim 시점에 호출하는 것이 의미 있음. */
+export declare function compareStates(predicted: StateSnapshot, actual: StateSnapshot): StateDivergence;

package/dist/divergence.js

@@ -0,0 +1,28 @@
+/*
+ * Divergence — 예측(predicted) vs 실제(actual) 상태 대조 (디지털트윈 본연: 정합/발산).
+ *
+ * 트윈을 mirror+simulator 와 구별짓는 기능: 현재에서 fork 한 forecast 와, 이후 실제로 관측된
+ * 상태를 같은 시점에 비교해 **드리프트(모델과 현실의 이탈)** 를 탐지한다. 발산 = 이상/개입 신호.
+ * (fork 로 예측 → 관측으로 실제 → 여기서 대조. execution-model.md 시뮬↔모니터링 커플링.)
+ */
+function diffBy(predicted, actual, idOf, valOf) {
+    const p = new Map(predicted.map(e => [idOf(e), valOf(e)]));
+    const a = new Map(actual.map(e => [idOf(e), valOf(e)]));
+    const out = [];
+    for (const id of new Set([...p.keys(), ...a.keys()])) {
+        const pv = p.get(id);
+        const av = a.get(id);
+        if (pv !== av)
+            out.push({ id, predicted: pv, actual: av });
+    }
+    return out.sort((x, y) => x.id.localeCompare(y.id));
+}
+/** predicted(fork forecast)와 actual(관측) 스냅샷을 대조. 같은 sim 시점에 호출하는 것이 의미 있음. */
+export function compareStates(predicted, actual) {
+    const itemLocation = diffBy(predicted.items, actual.items, i => i.epc, i => i.location);
+    const itemDisposition = diffBy(predicted.items, actual.items, i => i.epc, i => i.disposition);
+    const nodeOccupancy = diffBy(predicted.nodes, actual.nodes, n => n.id, n => n.occupancy);
+    const orderStatus = diffBy(predicted.orders, actual.orders, o => o.id, o => o.status);
+    const hasDrift = itemLocation.length > 0 || itemDisposition.length > 0 || nodeOccupancy.length > 0 || orderStatus.length > 0;
+    return { hasDrift, itemLocation, itemDisposition, nodeOccupancy, orderStatus };
+}

package/dist/duration-estimator.d.ts

@@ -0,0 +1,12 @@
+export interface DurationContext {
+    kind: string;
+    fromNode: string;
+    toNode: string;
+    resourceKind?: string;
+}
+export interface DurationEstimator {
+    /** 소요(ms). undefined 반환 시 도메인 기본값(fallback) 사용 — 일부 kind 만 다루고 나머지는 defer 가능. */
+    estimate(ctx: DurationContext): number | undefined;
+}
+/** 균일 상수 estimator (테스트·단순 보드용). 실 duration 은 보통 씬-유도 estimator 가 제공. */
+export declare const constantDuration: (ms: number) => DurationEstimator;

package/dist/duration-estimator.js

@@ -0,0 +1,10 @@
+/*
+ * Duration 시임 — task 소요시간(durationMs) 산출 확장점 (AllocationPolicy 와 동형, open/closed).
+ *
+ * 커널은 "이동/처리에 얼마 걸리나"(durationMs)만 소비하고, "왜·어떤 경로로"(거리·경로탐색·교통)는
+ * 안 묻는다. 그 물리 연산은 씬(things-scene FlowGraph·nav-graph·traffic) 소관 — 커널은 좌표-free.
+ * 보드/씬 바인딩이 거리·속도 기반 estimator 를 주입하면 가변 이동시간이 되고, 미주입 시 도메인 상수.
+ * (설계 SoT: design/integration/things-factory-host.md §6 — Kernel↔Host 경계 리뷰 결론)
+ */
+/** 균일 상수 estimator (테스트·단순 보드용). 실 duration 은 보통 씬-유도 estimator 가 제공. */
+export const constantDuration = (ms) => ({ estimate: () => ms });