@operato/twin-kernel 0.0.3 → 0.0.5

package/dist/capability.d.ts

@@ -0,0 +1,50 @@
+export type CapabilityKey = 'operable' | 'storable' | 'mobile' | 'processable' | 'trackable';
+/** 이동 관측 — Mobile 이 노출. */
+export interface Motion {
+    fromNode: string;
+    toNode: string;
+    startedAtSimMs: number;
+    durationMs: number;
+    progress: number;
+    elapsedMs: number;
+}
+export interface OperableState {
+    status: 'idle' | 'busy' | 'down';
+}
+export interface StorableState {
+    occupancy: number;
+    capacity: number;
+}
+export interface MobileState {
+    location: string;
+    motion?: Motion;
+}
+export interface ProcessableState {
+    output?: {
+        good: number;
+        scrap: number;
+    };
+}
+export interface TrackableState {
+    lifecycle: string;
+    progress?: number;
+    held: boolean;
+}
+/** 능력 관측 계약 메타(발견·검증). ops 없음(원칙 ①). */
+export interface CapabilitySpec {
+    key: CapabilityKey;
+    label: string;
+    semantics: string;
+    /** 관측 상태 필드(데이터 형식). 직교 — 어느 필드도 두 능력에 중복 없음(원칙 ②). */
+    stateFields: string[];
+    /** 교환 데이터 모델 이름. */
+    models?: string[];
+    /** 불변식(모두 준수·신뢰). */
+    invariants?: string[];
+    /** 실행 결과(이벤트) 형식. */
+    results?: string[];
+}
+export declare const CAPABILITIES: Record<CapabilityKey, CapabilitySpec>;
+export declare const CAPABILITY_KEYS: CapabilityKey[];
+/** 능력 집합이 관측 노출하는 상태 필드 합집합(직교이므로 단순 병합). */
+export declare function stateFieldsOf(caps: CapabilityKey[]): string[];

package/dist/capability.js

@@ -0,0 +1,44 @@
+/*
+ * 능력(capability) = 관측 계약(observable contract). 사상 토대: design/plans/capability-contract.md.
+ *
+ * 원칙 ① 관측만 — state(데이터형식)+models+invariants+results 만 계약. ops/구현은 없음(커널·씬 각 시뮬 자유).
+ *        "교환되는 것"을 계약하고 "계산하는 법"은 계약하지 않는다(결정성 지옥 회피·공유 가능성 핵심).
+ * 원칙 ② 직교·조합 — 교차 관심사 status 는 Operable 하나에만(중복 제거). 엔티티는 능력 *조합*.
+ * 원칙 ③ 작은 코어 + 열린 확장(무방언) — 도메인이 능력 선언, 코어는 발명 안 함.
+ * 원칙 ④ 능력 ⟂ standardClass — 다른 축, 파생 없음.
+ *
+ * things-scene 정합: 이건 "의도(intent)" 계층(관측). 씬 기제 믹스(Capacity/Transferable/CarrierLine …)가
+ * 이 의도를 *실현*한다 — 공유 계약은 관측(계층 B)뿐, 기제 methods(계층 A)는 공유 안 함.
+ * ⚠ Mobile ≠ Transferable: Mobile=자원 자신이 이동, Transferable=노드가 아이템 이동(씬 기제).
+ */
+export const CAPABILITIES = {
+    operable: {
+        key: 'operable', label: '운영', semantics: '능동 자원의 운영 상태(유휴/가동/고장). status 교차 관심사를 여기 하나로.',
+        stateFields: ['status'], results: ['statusChanged']
+    },
+    storable: {
+        key: 'storable', label: '저장', semantics: '아이템을 보유하는 위치 — 점유/용량. (씬 기제: Capacity)',
+        stateFields: ['occupancy', 'capacity'], invariants: ['0 <= occupancy <= capacity (capacity>0)'], results: ['occupancyChanged']
+    },
+    mobile: {
+        key: 'mobile', label: '이동', semantics: '자원 자신이 노드 간 이동. Transferable(아이템 이동)과 다름. (씬 기제: CarrierLine)',
+        stateFields: ['location', 'motion'], models: ['Motion'], results: ['moved', 'motionTick']
+    },
+    processable: {
+        key: 'processable', label: '가공', semantics: '변환/가공 수행 — 산출(양품/불량). 운영 status 는 Operable 조합. progress 방출은 후속.',
+        stateFields: ['output'], results: ['completed']
+    },
+    trackable: {
+        key: 'trackable', label: '추적', semantics: '오더/아이템 생애 추적 — 생애단계(도메인 라벨, 무방언)·진행·보류.',
+        stateFields: ['lifecycle', 'progress', 'held'], results: ['lifecycleChanged']
+    }
+};
+export const CAPABILITY_KEYS = ['operable', 'storable', 'mobile', 'processable', 'trackable'];
+/** 능력 집합이 관측 노출하는 상태 필드 합집합(직교이므로 단순 병합). */
+export function stateFieldsOf(caps) {
+    const out = new Set();
+    for (const c of caps)
+        for (const f of CAPABILITIES[c]?.stateFields ?? [])
+            out.add(f);
+    return [...out];
+}

package/dist/contract.d.ts

@@ -14,6 +14,7 @@ export interface NodeState {
     capacity?: number;
     occupancy: number;
     status?: string;
+    parentId?: string;
 }
 export interface ItemState {
     epc: string;
@@ -64,6 +65,7 @@ export interface MoverState {
     taskId?: string;
     motion?: MoverMotion;
     oee?: OeeMetrics;
+    held?: boolean;
 }
 export interface TaskState {
     id: string;
@@ -73,6 +75,7 @@ export interface TaskState {
     fromNode?: string;
     toNode?: string;
     resourceRef?: string;
+    orderId?: string;
     progress?: number;
 }
 export interface OrderState {
@@ -82,6 +85,36 @@ export interface OrderState {
     progress?: number;
     held?: boolean;
 }
+export type AttentionSeverity = 'low' | 'medium' | 'high' | 'critical';
+export type AttentionState = 'active' | 'acknowledged' | 'cleared';
+export interface Attention {
+    id: string;
+    kind: string;
+    severity: AttentionSeverity;
+    state?: AttentionState;
+    title: string;
+    detail?: string;
+    anchor: {
+        nodeId?: string;
+        moverId?: string;
+        orderId?: string;
+    };
+    since?: number;
+    rationale?: string;
+    recommendedActions?: RecommendedAction[];
+    suggestedAction?: {
+        command: string;
+        args?: unknown;
+        label: string;
+    };
+}
+/** 조치방향 — command 있으면 원클릭 실행, 없으면 권고 텍스트. */
+export interface RecommendedAction {
+    label: string;
+    command?: string;
+    args?: unknown;
+    hint?: string;
+}
 export interface StateSnapshot {
     revision: number;
     simClockMs: number;
@@ -90,6 +123,7 @@ export interface StateSnapshot {
     movers: MoverState[];
     tasks: TaskState[];
     orders: OrderState[];
+    attentions?: Attention[];
 }
 export interface Command<T = unknown> {
     commandId: string;
@@ -103,6 +137,16 @@ export interface CommandAck {
     accepted: boolean;
     error?: string;
 }
+/**
+ * 호스트-facing 커맨드 채널(비동기) — 씬 컴포넌트 등 클라이언트가 트윈 호스트에 커맨드를 던지는 계약.
+ * 커널 in-process `dispatch`(동기)와 달리 원격 호스트(GraphQL/HTTP/…) 전송을 추상화.
+ * 씬 컨트롤 컴포넌트는 이 인터페이스에만 의존(커널 레벨) — concrete 전송은 각 호스트(things-factory 등)가 주입.
+ * → 컴포넌트가 특정 호스트 구현(things-factory)에 갇히지 않고, 어디서든 개발/재사용 가능.
+ * 컴포넌트는 tenantId 등을 모르는 부분 커맨드를 던지고, 호스트가 보강한다(commandId/type/args 만 제공).
+ */
+export interface TwinCommandChannel {
+    dispatch(command: Pick<Command, 'commandId' | 'type' | 'args'>): Promise<CommandAck>;
+}
 export interface RateSpec {
     distribution: 'poisson' | 'uniform' | 'constant' | 'profile';
     meanPerHour: number;
@@ -123,7 +167,13 @@ export interface ContentSpec {
     };
 }
 export interface GeneratorSpec {
-    kind: 'inbound-arrival' | 'outbound-order';
+    /** 도메인 소유 라벨 — 무엇을 생성하는 자극인지 도메인이 명명(OrderState.kind 선례, 무방언). 코어는 강제하지 않음. */
+    kind: string;
+    /**
+     * 코어 라우팅 클래스: 공급(arrival, 물건이 들어옴 → onArrival) vs 수요(order, 요청이 들어옴 → onOrder).
+     * 미지정 시 레거시 kind('outbound-order'→order, 그 외→arrival)로 추론(하위호환, 카탈로그 nodeTypes 폴백과 동형).
+     */
+    stimulus?: 'arrival' | 'order';
     rate: RateSpec;
     content: ContentSpec;
     window?: {
@@ -148,9 +198,18 @@ export declare const OP_EVENT: {
     readonly task: "task.status";
     readonly equipment: "equipment.status";
     readonly order: "order.status";
+    readonly quality: "quality.output";
 };
+/** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 무버 누적값. */
+export interface QualityDelta {
+    moverId: string;
+    good: boolean;
+    goodCount: number;
+    scrapCount: number;
+}
 export interface TaskStatusDelta {
     taskId: string;
+    orderId?: string;
     kind: string;
     status: TaskStatus;
     fromNode?: string;
@@ -165,6 +224,12 @@ export interface EquipmentStatusDelta {
     location?: string;
     motion?: MoverMotion;
 }
+/** 관측된 오더 라인(SKU 데맨드) — 실 시스템 오더는 품목 라인을 가짐. 이행 예측(남은 데맨드 재계획)에 필요. */
+export interface ObservedOrderLine {
+    gtin: string;
+    requested: number;
+    fulfilled?: number;
+}
 export interface OrderStatusDelta {
     orderId: string;
     kind: string;
@@ -172,11 +237,23 @@ export interface OrderStatusDelta {
     requested: number;
     fulfilled: number;
     held?: boolean;
+    /**
+     * 오더 라인(SKU+수량) — 선택. 있으면 이행 예측이 "남은 데맨드(라인별 requested-fulfilled)를
+     * 현재 재고로 어떻게 채우나"를 재계획할 수 있다. 없으면 top-level 카운트만(이행 예측 불가, 재고 예측만).
+     */
+    lines?: ObservedOrderLine[];
 }
 export declare const CMD: {
     readonly orderHold: "order.hold";
     readonly orderResume: "order.resume";
     readonly orderRelease: "order.release";
+    readonly attentionAck: "attention.ack";
+    readonly resourceHold: "resource.hold";
+    readonly resourceResume: "resource.resume";
+    readonly resourceDown: "resource.down";
+    readonly resourceRepair: "resource.repair";
+    readonly resourceResetMetrics: "resource.reset-metrics";
+    readonly resourceAdd: "resource.add";
 };
 export type OperationalDelta = TaskStatusDelta | EquipmentStatusDelta | OrderStatusDelta;
 export type EventHandler = (e: CanonicalEnvelope) => void;
@@ -186,6 +263,7 @@ export interface BoardDef {
         id: string;
         type: string;
         capacity: number;
+        parentId?: string;
     }[];
     movers: {
         id: string;

package/dist/contract.js

@@ -9,12 +9,21 @@
 export const OP_EVENT = {
     task: 'task.status',
     equipment: 'equipment.status',
-    order: 'order.status'
+    order: 'order.status',
+    quality: 'quality.output' // 품질 산출(양품/불량) — OEE quality 입력. live 누적기가 이걸로 good/scrap 정확 추적.
 };
 // ── Command 채널 어휘 — 트윈의 "행위(act)" 면 (prescriptive/트랜잭션 프론트엔드) ──
 // 코어 공통: order.hold/resume(할당 보류). 도메인: order.release(즉시 투입) 등은 handleCommand 로.
 export const CMD = {
     orderHold: 'order.hold',
     orderResume: 'order.resume',
-    orderRelease: 'order.release'
+    orderRelease: 'order.release',
+    attentionAck: 'attention.ack', // 주목 신호 확인(OPC UA A&C acknowledge) — args:{id}
+    // Operable 코어 — 모든 operable 자원(설비·이동무버) 공통. args:{resourceId}. capability-keyed(무방언, equipment.* 아님).
+    resourceHold: 'resource.hold', // 계획 정지(정비/오프라인) — 배정 스킵
+    resourceResume: 'resource.resume', // 계획 정지 해제
+    resourceDown: 'resource.down', // 비계획 고장 주입 — args:{resourceId, durationMs?}
+    resourceRepair: 'resource.repair', // 즉시 수리
+    resourceResetMetrics: 'resource.reset-metrics', // OEE 계측 창 리셋
+    resourceAdd: 'resource.add' // 라이브 자원(무버) 추가 — args:{kind, homeNode, count?}. 런타임 구조 변이(what-if 아닌 실제 act)
 };

package/dist/domain-catalog.d.ts

@@ -0,0 +1,33 @@
+import type { CapabilityKey } from './capability.ts';
+export type DomainSystem = 'wms' | 'yms' | 'mes';
+export interface TwinTypeInfo {
+    /** 커널 권위 키 (예: 'storage', 'forklift'). */
+    key: string;
+    /** 로케이션(수동) vs 자원(능동). */
+    role: 'node' | 'mover';
+    label: string;
+    /** ① 표준 온톨로지 투영(03-reference-standards). 열린 문자열 — 하드코딩 enum 금지. */
+    standardClass: {
+        epcis?: string;
+        isa95?: string;
+        iso55000?: string;
+    };
+    /** ④ 식별자 스킴 — id 매칭 UX/검증 힌트(열린 문자열). 예: 'gs1:SGLN' | 'gs1:GIAI' | 'kernel:id'. */
+    identity: {
+        scheme: string;
+    };
+    /** ② 능력 프로파일(ADR-0018 정제) — 이 타입이 무엇을 하나. 엔티티→capability→컴포넌트 매핑의 SSOT. */
+    capabilities: CapabilityKey[];
+}
+export interface DomainProfileInfo {
+    system: DomainSystem;
+    label: string;
+    /** 노드+무버 트윈 타입 — board·UI 팔레트 소싱 SSOT. */
+    types: TwinTypeInfo[];
+    /** 로케이션 노드 타입 키(하위호환 파생 뷰 = types 중 role==='node'). 신규 소싱은 types 사용. */
+    nodeTypes: readonly string[];
+}
+export declare const DOMAIN_CATALOG: Record<DomainSystem, DomainProfileInfo>;
+export declare const DOMAIN_SYSTEMS: DomainSystem[];
+/** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */
+export declare function capabilitiesForType(system: DomainSystem, typeKey: string): CapabilityKey[];

package/dist/domain-catalog.js

@@ -0,0 +1,14 @@
+import { WMS_TYPES } from "./wms-profile.js";
+import { YMS_TYPES } from "./yms-profile.js";
+import { MES_TYPES } from "./mes-profile.js";
+const nodeKeys = (types) => types.filter(t => t.role === 'node').map(t => t.key);
+export const DOMAIN_CATALOG = {
+    wms: { system: 'wms', label: 'WMS (물류창고)', types: WMS_TYPES, nodeTypes: nodeKeys(WMS_TYPES) },
+    yms: { system: 'yms', label: 'YMS (야드)', types: YMS_TYPES, nodeTypes: nodeKeys(YMS_TYPES) },
+    mes: { system: 'mes', label: 'MES (제조)', types: MES_TYPES, nodeTypes: nodeKeys(MES_TYPES) }
+};
+export const DOMAIN_SYSTEMS = ['wms', 'yms', 'mes'];
+/** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */
+export function capabilitiesForType(system, typeKey) {
+    return DOMAIN_CATALOG[system]?.types.find(t => t.key === typeKey)?.capabilities ?? [];
+}

package/dist/domain-definition.d.ts

@@ -0,0 +1,91 @@
+/** 표준 온톨로지 투영(열린 문자열 — 하드코딩 enum 금지). */
+export interface StandardClass {
+    epcis?: string;
+    isa95?: string;
+    iso55000?: string;
+}
+export interface Identity {
+    /** GS1/커널 식별 스킴 힌트. 예: 'gs1:SGLN' | 'gs1:GIAI' | 'gs1:SSCC'. */
+    scheme: string;
+}
+/** 자재/품목 클래스. */
+export interface MaterialDef {
+    key: string;
+    label: string;
+    identity?: Identity;
+}
+/** 로케이션(수동 위치) 타입. */
+export interface NodeTypeDef {
+    key: string;
+    label: string;
+    standardClass?: StandardClass;
+    identity?: Identity;
+    capabilities?: string[];
+}
+/** 자원(능동 설비·무버) 타입. */
+export interface ResourceTypeDef {
+    key: string;
+    label: string;
+    standardClass?: StandardClass;
+    identity?: Identity;
+    capabilities?: string[];
+}
+/** 작업 의도 — FlowTask.intent 와 정합(ISA-95 이동 vs 변환). */
+export type OperationIntent = 'transport' | 'process' | 'dwell';
+/** 오퍼레이션 타입(공정 한 작업) — ISA-95 OperationsDefinition. */
+export interface OperationDef {
+    key: string;
+    label: string;
+    intent: OperationIntent;
+    /** 오퍼레이션이 수행되는 노드 타입(NodeTypeDef.key). 커널이 nodeByType 로 위치 해소. */
+    nodeType?: string;
+    /** 요구 자원 종류(ResourceTypeDef.key). transport/process 는 자원 필요, dwell 은 무자원. */
+    resourceType?: string;
+    /** CBV bizStep URN(방출 이벤트 어휘). */
+    bizStep?: string;
+}
+/** 라우트(오퍼레이션 시퀀스) — ISA-95 ProcessSegment 연결. */
+export interface RouteDef {
+    key: string;
+    label: string;
+    /** OperationDef.key 순서. */
+    steps: string[];
+}
+export interface RecipePart {
+    /** MaterialDef.key. */
+    material: string;
+    qty: number;
+}
+/** BOM/레시피 — ISA-95 Material Consumed/Produced · EPCIS TransformationEvent(input→output). */
+export interface RecipeDef {
+    key: string;
+    label: string;
+    inputs: RecipePart[];
+    outputs: RecipePart[];
+    /** RouteDef.key(선택) — 이 산출물을 만드는 공정 경로. */
+    route?: string;
+}
+/** CBV 어휘(bizStep·거래유형). */
+export interface DomainVocabulary {
+    bizSteps?: Record<string, string>;
+    transactionTypes?: Record<string, string>;
+}
+/**
+ * 도메인 정의 — 커널이 소비하는 실행 계약. (스토어 메타 version/supplier 는 catalog 래퍼가 얹음.)
+ */
+export interface DomainDefinition {
+    id: string;
+    label: string;
+    vocabulary?: DomainVocabulary;
+    materials?: MaterialDef[];
+    nodeTypes: NodeTypeDef[];
+    resourceTypes: ResourceTypeDef[];
+    operations?: OperationDef[];
+    routes?: RouteDef[];
+    recipes?: RecipeDef[];
+}
+/**
+ * 구조·참조무결성 검증(zero-dep, `validateEpcisEvent` 스타일). 위반 목록 반환(빈 배열 = 유효).
+ * 도메인 정의는 데이터 아티팩트라 로드 시점에 런타임 검증한다(컴파일타임 아님).
+ */
+export declare function validateDomainDefinition(def: DomainDefinition): string[];

package/dist/domain-definition.js

@@ -0,0 +1,76 @@
+/*
+ * 도메인 정의(DomainDefinition) — 커널의 선언적 도메인 계약. `BoardDef`(토폴로지 입력)의 확장 격.
+ * 커널이 "무엇이 있고 어떻게 흐르나"(타입 + 공정 route/BOM)를 **데이터로** 받는 형식. zero-dep(자기 타입).
+ *
+ * 특정 공정이 커널 코드에 하드코딩되던 것을 이 데이터 계약으로 대체한다(design/plans/domain-catalog-layering.md).
+ * 스토어 패키지 `@operato/twin-catalog` 가 이 타입을 import 해 스토어 메타(version/supplier)를 얹어 배포한다(catalog → kernel 의존).
+ * 표준 앵커: GS1 EPCIS 2.0(bizStep) · ISA-95(WorkCenter·OperationsDefinition·BOM) · ISO 55000(Asset).
+ */
+const INTENTS = ['transport', 'process', 'dwell'];
+function dupes(keys) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const k of keys) {
+        if (seen.has(k))
+            dup.add(k);
+        else
+            seen.add(k);
+    }
+    return [...dup];
+}
+/**
+ * 구조·참조무결성 검증(zero-dep, `validateEpcisEvent` 스타일). 위반 목록 반환(빈 배열 = 유효).
+ * 도메인 정의는 데이터 아티팩트라 로드 시점에 런타임 검증한다(컴파일타임 아님).
+ */
+export function validateDomainDefinition(def) {
+    const v = [];
+    if (!def || typeof def !== 'object')
+        return ['domain definition 없음/객체 아님'];
+    if (typeof def.id !== 'string' || !def.id)
+        v.push('id 누락');
+    if (typeof def.label !== 'string' || !def.label)
+        v.push('label 누락');
+    if (!Array.isArray(def.nodeTypes) || def.nodeTypes.length === 0)
+        v.push('nodeTypes 비어있음');
+    if (!Array.isArray(def.resourceTypes))
+        v.push('resourceTypes 배열 아님');
+    const nodeKeys = new Set((def.nodeTypes || []).map(n => n.key));
+    const resKeys = new Set((def.resourceTypes || []).map(r => r.key));
+    const matKeys = new Set((def.materials || []).map(m => m.key));
+    const opKeys = new Set((def.operations || []).map(o => o.key));
+    const routeKeys = new Set((def.routes || []).map(r => r.key));
+    for (const [name, arr] of [['nodeTypes', def.nodeTypes], ['resourceTypes', def.resourceTypes], ['materials', def.materials], ['operations', def.operations], ['routes', def.routes], ['recipes', def.recipes]]) {
+        for (const d of dupes((arr || []).map(x => x.key)))
+            v.push(`${name} 키 중복: ${d}`);
+    }
+    for (const o of def.operations || []) {
+        if (!INTENTS.includes(o.intent))
+            v.push(`operation '${o.key}' intent 부정: ${o.intent}`);
+        if (o.nodeType && !nodeKeys.has(o.nodeType))
+            v.push(`operation '${o.key}' nodeType '${o.nodeType}' 미정의`);
+        if (o.resourceType && !resKeys.has(o.resourceType))
+            v.push(`operation '${o.key}' resourceType '${o.resourceType}' 미정의`);
+        if (o.intent === 'dwell' && o.resourceType)
+            v.push(`operation '${o.key}' dwell 인데 resourceType 지정됨(무자원이어야)`);
+    }
+    for (const r of def.routes || []) {
+        if (!Array.isArray(r.steps) || r.steps.length === 0)
+            v.push(`route '${r.key}' steps 비어있음`);
+        for (const s of r.steps || [])
+            if (!opKeys.has(s))
+                v.push(`route '${r.key}' step '${s}' 미정의 operation`);
+    }
+    for (const rc of def.recipes || []) {
+        if (rc.route && !routeKeys.has(rc.route))
+            v.push(`recipe '${rc.key}' route '${rc.route}' 미정의`);
+        if (!rc.outputs?.length)
+            v.push(`recipe '${rc.key}' outputs 비어있음`);
+        for (const p of [...(rc.inputs || []), ...(rc.outputs || [])]) {
+            if (!matKeys.has(p.material))
+                v.push(`recipe '${rc.key}' material '${p.material}' 미정의`);
+            if (typeof p.qty !== 'number' || p.qty <= 0)
+                v.push(`recipe '${rc.key}' material '${p.material}' qty 부정`);
+        }
+    }
+    return v;
+}

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { BoardDef, Command, CommandAck, EventHandler, MoverMotion, GeneratorSpec, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe } from './contract.ts';
+import type { Attention, BoardDef, Command, CommandAck, EventHandler, MoverMotion, OeeMetrics, GeneratorSpec, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, NodeState, ItemState, MoverState, OrderStatusDelta } 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';
@@ -8,6 +8,7 @@ export interface FlowNode {
     capacity: number;
     occupancy: number;
     status: string;
+    parentId?: string;
 }
 export interface FlowItem {
     epc: string;
@@ -33,6 +34,9 @@ export interface FlowMover {
     mttrMs?: number;
     nextFailureMs?: number;
     repairUntilMs?: number;
+    held?: boolean;
+    holdMs?: number;
+    metricsSinceMs?: number;
 }
 export interface FlowTask {
     id: string;
@@ -82,6 +86,45 @@ interface Rng {
     (): number;
     state: number;
 }
+/**
+ * 주목신호 계산(순수) — State 스냅샷(movers/nodes/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: {
+        id: string;
+        status?: string;
+        location?: string;
+        goodCount?: number;
+        scrapCount?: number;
+    }[];
+    nodes: {
+        id: string;
+        capacity?: number;
+        occupancy?: number;
+    }[];
+    orders: {
+        id: string;
+        held?: boolean;
+    }[];
+}, acked?: ReadonlySet<string>): Attention[];
+/** OEE 계측 카운터 — sim 은 tick 으로 누적, live 는 실 텔레메트리 또는 이벤트 누적기가 채운다(face2-inbound-live §1.1). */
+export interface OeeCounters {
+    runMs: number;
+    setupMs: number;
+    downMs: number;
+    goodCount: number;
+    scrapCount: number;
+    holdMs?: number;
+    metricsSinceMs?: number;
+}
+/**
+ * OEE 공식(순수) — 누적 카운터 + 현재 시각 → OEE. sim(oeeOf)과 live 가 **공유하는 계산 층**(face2-inbound-live §1.1).
+ * ⚠ attentions 와 달리: 입력(카운터)이 관측 State·이벤트에 없다 → live 는 카운터를 텔레메트리(정확) 또는
+ *    이벤트 누적기(근사)로 별도 공급해야 한다. 공식만 공유되고 입력원은 live 데이터-생산 결정.
+ */
+export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;
 export declare abstract class FlowEngine implements TwinKernel {
     tenantId: string;
     nodes: Map<string, FlowNode>;
@@ -118,18 +161,51 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     protected abstract onTaskComplete(task: FlowTask): void;
     loadBoard(def: BoardDef): void;
+    /**
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 무버 추가. loadBoard 무버 삽입과 동일 규약.
+     * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
+     */
+    addMover(m: {
+        id: string;
+        kind: string;
+        homeNode: string;
+        mtbfMs?: number;
+        mttrMs?: number;
+    }): void;
+    /**
+     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·무버·노드)과
+     * 저널 오더(원값+라인)로 이 커널의 맵을 채운다. tick 으로 만든 게 아니라 "현재 관측된 현실"을 심어
+     * 이후 fork/tick 으로 예측한다. 라이브 런타임은 여전히 projector 미러 — 이 커널은 예측용 임시본.
+     * 오더는 남은 데맨드(라인별 requested-fulfilled)를 'created' 로 복원(현재 재고에서 재계획).
+     * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
+     */
+    hydrateObserved(snap: {
+        nodes: NodeState[];
+        items: ItemState[];
+        movers: MoverState[];
+    }, orders?: OrderStatusDelta[]): void;
+    /** what-if 구성 변주 — 노드 용량 변경(fork 대상). 존재하면 true. */
+    setNodeCapacity(nodeId: string, capacity: number): boolean;
+    /**
+     * forecast 몬테카를로 — fork 의 RNG 만 재시드(시나리오·상태·gens·in-flight 는 보존).
+     * "현재 조건 지속"을 유지한 채 **미래 확률만** 변주(도착·고장 타이밍 등) → run 마다 다른 표본.
+     * (monteCarloForecast 은 scenario.load 로 gens 를 갈아끼우므로 "현재 조건"이 깨진다 — 그 대안.)
+     */
+    reseed(seed: number): void;
     onEvent(handler: EventHandler): Unsubscribe;
     /**
      * Command 채널 — 트윈의 "행위(act)" 면. 코어 공통 커맨드(order.hold/resume)는 여기서,
      * 도메인 커맨드(order.release 등)는 handleCommand 로 위임. 커맨드는 sim 상태를 변이하고
      * State 델타를 유발한다(command → 행위 → 관측 폐루프).
      */
+    private _acked;
     dispatch(cmd: Command): CommandAck;
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     protected handleCommand(cmd: Command): CommandAck;
     readonly scenario: ScenarioControl;
     tick(dtMs: number): void;
     getSnapshot(): StateSnapshot;
+    protected computeAttentions(): Attention[];
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 굴려 forecast·발산(predicted vs actual) 검사에 쓴다.