@operato/twin-kernel 0.4.2 → 0.5.0

package/dist/contract.d.ts

@@ -1391,6 +1391,20 @@ export interface BoardDef {
      * 유통가공(VAS)은 비직렬 클래스+수량이 맞는 모양이므로 코어의 일반 경로를 쓴다.
      */
     productionSpec?: ProductionSpec;
+    /**
+     * 공정 명세 — **ISA-95 `OperationsSegment`.** 이 현장에서 각 작업이 어디서·무엇으로·얼마나 걸리나.
+     *
+     * ── 왜 이제야 선언하나 (2026-08-08) ──────────────────────────────────────────
+     * 이 자리는 **이미 쓰이고 있었다.** 마스터 인제스트가 `board.operations` 로 통과시키고 호스트가
+     * `applyOperations` 로 커널에 싣는다. 그런데 `BoardDef` 는 그것을 말한 적이 없다.
+     *
+     * 바로 위 `productionSpec` 이 겪은 것과 **같은 일**이다 — "계약에 없으니 아무도 이 자리를 발견할
+     * 수 없었다. 타입이 말해 주지 않는 필드는 없는 필드다." 그때 배운 것을 여기 적용한다.
+     *
+     * 소비 경로가 둘인 것은 그대로 둔다(여기와 `productionSpec.definition.operations`) — 후자는
+     * 라우트의 단계를 해소할 때 읽힌다. 집을 하나로 모으는 것은 별건이고, 그 전에 **선언부터** 한다.
+     */
+    operations?: import('./domain-definition.ts').OperationDef[];
 }
 /**
  * 생산 선언 — 도메인 정의(ISA-95 operations + BOM)와, 그 추상 자재 키를 실제 GS1 식별자로 잇는 바인딩.

package/dist/domain-catalog.d.ts

@@ -28,6 +28,130 @@ export interface DomainProfileInfo {
     locationTypes: readonly string[];
 }
 export declare const DOMAIN_CATALOG: Record<DomainSystem, DomainProfileInfo>;
+export interface TwinAxisInfo {
+    /**
+     * 축의 이름 — 화면·관계 선언이 쓰는 키. 최상위 축은 `BoardDef` 의 키 **그대로**다
+     * (저장·계약의 이름과 갈라지면 그 순간 방언이 생긴다).
+     */
+    axis: string;
+    /**
+     * board 안에서의 자리. 최상위면 `axis` 와 같고, 중첩이면 경로다
+     * (`productionSpec.definition.recipes`).
+     *
+     * **레시피·라우트는 저장상 `productionSpec` 안에 있지만 개념으로는 1급**이다 — 사람은
+     * "레시피" 를 찾지 "생산 정의 안의 레시피" 를 찾지 않는다. 저장 위치가 개념을 가두면
+     * 화면이 저장 구조를 흉내 내게 되고, 그건 `ADR-0032`(board 는 캐시) 뒤에 무의미해진다.
+     */
+    path: string;
+    /** i18n 키 — 사람 언어는 표현 계층이 렌더한다(L2). */
+    label: string;
+    /** 표준 온톨로지 투영. 표준에 자리가 없으면 **빈 객체**(숨기지 않는다). */
+    standardClass: {
+        epcis?: string;
+        isa95?: string;
+        iso55000?: string;
+    };
+    /**
+     * 표준이 **정의(class)와 개체(instance)를 가른다.** 같은 자재라도 `MaterialDefinition` 과
+     * `MaterialLot` 은 다른 것이다. 화면이 둘을 같은 칸에 담지 않도록 선언에 싣는다.
+     * `spec` 은 자원이 아니라 **명세**(공정·생산 정의).
+     */
+    kind: 'instance' | 'class' | 'spec';
+    /** 이 축의 항목이 카탈로그 타입을 갖는가 — 있으면 `types` 와 이어진다(자리·설비만). */
+    typeRole?: 'location' | 'equipment';
+}
+/** board 축 전체 — 인스펙션의 **개념 목록**이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
+export declare const TWIN_AXES: TwinAxisInfo[];
+export type TwinRelationTarget = {
+    kind: 'axis';
+    axis: string;
+} | {
+    kind: 'type';
+    role: 'location' | 'equipment';
+}
+/**
+ * **커널 밖**을 가리키는 참조. 커널은 대상의 이름만 말하고 해소는 호스트가 한다.
+ *
+ * 실물: `locations[].parentId` 는 자리가 아니라 **공간의 구역**을 가리킨다. 마스터에서는
+ * 구역도 자리와 같은 목록에 있다가(`role: 'area'`) 인제스트가 갈라 `TwinArea` 로 보내기 때문에,
+ * board 안에는 **대상이 없는 참조**가 남는다. 이것을 `axis: 'locations'` 로 적으면 선언이
+ * 거짓말을 하고 지도에 없는 선이 생긴다 — 실제로 그렇게 적었다가 실 데이터로 걸어 보고 잡았다.
+ *
+ * 커널이 `TwinArea` 를 알 수는 없다(공간은 호스트 개념). 그래서 **모른다는 사실을 선언한다.**
+ */
+ | {
+    kind: 'external';
+    entity: string;
+};
+export interface TwinRelationInfo {
+    /** 출발 축. */
+    from: string;
+    /**
+     * 그 축의 항목에서 대상 키를 꺼내는 경로. `[]` 는 **배열 펼침**이다.
+     * 예: `route` · `steps[]` · `inputs[].material`.
+     */
+    field: string;
+    target: TwinRelationTarget;
+    /** 관계의 이름(i18n 키) — 화면의 선과 이웃 묶음에 붙는다. */
+    via: string;
+    /** 없을 수 있는 참조인가. `false` 인데 비면 **끊어진 참조**로 보고한다. */
+    optional?: boolean;
+}
+/** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
+export declare const TWIN_RELATIONS: TwinRelationInfo[];
+export type TwinObservationKind = 
+/** 여러 번 일어난 일의 **퍼짐**. 중앙값 + p10·p90 + 표본 수. 예: 공정 소요, 체류시간. */
+'distribution'
+/** 어느 시점의 **차 있음**. 현재 · 최대 · 평균. 예: 자리 점유, 재고. */
+ | 'level'
+/** 창(window)당 **비(比)**. 값 + 추세. 예: 가동률, 처리량. */
+ | 'rate'
+/** 시간축 위의 **연속 계측**. 스파크라인 + 구간 통계. 예: 부하곡선, 온도. */
+ | 'series'
+/** 벌어진 **횟수**. 누계 + 기간. 예: 고장 횟수, 완료 건수. */
+ | 'count';
+/**
+ * 한 축의 항목이 갖는 **볼 수 있는 속성** 하나.
+ *
+ * 선언값(원본이 말한 것)과 관측값(트윈이 잰 것)은 **둘 다 없을 수 있다.**
+ *  · 선언만 있음 — 원본이 말했는데 아직 못 쟀다(표본 부족)
+ *  · 관측만 있음 — 원본이 침묵한 자리를 트윈이 채우고 있다. **트윈을 가진 이유가 여기 있다**
+ *  · 둘 다 있고 어긋남 — 원본의 표준값이 이 현장과 다르다는 **발견**
+ * 그래서 어느 쪽도 없다고 숨기지 않는다. 없으면 `—` 로 낸다.
+ */
+export interface TwinPropertyInfo {
+    /** 어느 축의 속성인가. */
+    axis: string;
+    /** 속성 키 — 화면·질의가 쓰는 이름. */
+    key: string;
+    label: string;
+    kind: TwinObservationKind;
+    /**
+     * 선언값이 항목의 어느 필드에 있나. **없으면 원본이 말하지 않는 속성**이다
+     * (그래도 관측은 있을 수 있다 — 위 두 번째 경우).
+     */
+    declaredField?: string;
+    /**
+     * 이 관측을 **누가 내나.** 커널·호스트의 실제 산출 이름을 적는다. 지어낸 관측을 선언하지
+     * 않기 위한 표식이다 — 없으면 아직 아무도 안 낸다는 뜻이고, 화면은 `—` 를 낸다.
+     */
+    observedBy?: string;
+    /** 단위(UN/CEFACT 공통코드 또는 `ms`·`ratio`). **단위 없는 물리량은 쓰지 않는다**(계약의 규율). */
+    uom?: string;
+}
+/**
+ * 오늘 **실제로 짝이 서는 것**만 선언한다. 그럴듯한 속성을 미리 적어 두면 화면이 빈칸을 줄줄이
+ * 내고, 그건 "아직 안 쟀다" 가 아니라 "이 트윈은 부실하다" 로 읽힌다.
+ * `series` 는 아직 **아무도 내지 않는다** — EMS 가 붙을 때 생산자와 함께 선언한다.
+ */
+export declare const TWIN_PROPERTIES: TwinPropertyInfo[];
+/** 이 축이 보여 줄 속성들 — 없으면 빈 배열(속성 없는 축이 정상이다). */
+export declare const propertiesOf: (axis: string) => TwinPropertyInfo[];
+/** 이 축에서 나가는 관계 · 이 축으로 들어오는 관계 — 항목 패널의 "이어진 것" 양방향. */
+export declare const relationsFrom: (axis: string) => TwinRelationInfo[];
+export declare const relationsTo: (axis: string) => TwinRelationInfo[];
+/** 축 이름 → 서술. 모르는 축이면 `undefined` — 화면은 그것을 "미선언" 으로 낸다(숨기지 않는다). */
+export declare function axisInfo(axis: string): TwinAxisInfo | undefined;
 export declare const DOMAIN_SYSTEMS: DomainSystem[];
 /** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */
 export declare function capabilitiesForType(system: DomainSystem, typeKey: string): CapabilityKey[];

package/dist/domain-catalog.js

@@ -8,6 +8,94 @@ export const DOMAIN_CATALOG = {
     yms: { system: 'yms', label: 'twin.system.yms', types: YMS_TYPES, locationTypes: locationKeys(YMS_TYPES) },
     mes: { system: 'mes', label: 'twin.system.mes', types: MES_TYPES, locationTypes: locationKeys(MES_TYPES) }
 };
+/** board 축 전체 — 인스펙션의 **개념 목록**이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
+export const TWIN_AXES = [
+    { axis: 'locations', path: 'locations', label: 'twin.axis.locations', kind: 'instance', typeRole: 'location',
+        standardClass: { epcis: 'SGLN' } },
+    { axis: 'equipment', path: 'equipment', label: 'twin.axis.equipment', kind: 'instance', typeRole: 'equipment',
+        standardClass: { isa95: 'Equipment', iso55000: 'Asset', epcis: 'GIAI' } },
+    { axis: 'persons', path: 'persons', label: 'twin.axis.persons', kind: 'instance',
+        standardClass: { isa95: 'Person' } },
+    { axis: 'assets', path: 'assets', label: 'twin.axis.assets', kind: 'instance',
+        standardClass: { isa95: 'PhysicalAsset', iso55000: 'Asset' } },
+    { axis: 'personnelClasses', path: 'personnelClasses', label: 'twin.axis.personnelClasses', kind: 'class',
+        standardClass: { isa95: 'PersonnelClass' } },
+    { axis: 'equipmentClasses', path: 'equipmentClasses', label: 'twin.axis.equipmentClasses', kind: 'class',
+        standardClass: { isa95: 'EquipmentClass' } },
+    { axis: 'assetClasses', path: 'assetClasses', label: 'twin.axis.assetClasses', kind: 'class',
+        standardClass: { isa95: 'PhysicalAssetClass' } },
+    { axis: 'materialDefinitions', path: 'materialDefinitions', label: 'twin.axis.materialDefinitions', kind: 'class',
+        standardClass: { isa95: 'MaterialDefinition' } },
+    { axis: 'materialClasses', path: 'materialClasses', label: 'twin.axis.materialClasses', kind: 'class',
+        standardClass: { isa95: 'MaterialClass' } },
+    { axis: 'operations', path: 'operations', label: 'twin.axis.operations', kind: 'spec',
+        standardClass: { isa95: 'OperationsSegment' } },
+    { axis: 'productionSpec', path: 'productionSpec', label: 'twin.axis.productionSpec', kind: 'spec',
+        standardClass: { isa95: 'OperationsSegment' } },
+    /*
+     * 아래 셋은 저장상 `productionSpec.definition` 안에 있지만 **개념으로는 1급**이다.
+     * `materials` 가 최상위 `materialDefinitions` 와 **둘 다** 있는 것은 지금 상태 그대로다 —
+     * 전자는 도메인 정의의 가벼운 목록(`{key,label}`), 후자는 ISA-95 풍부형이다. 같은 것의 집이
+     * 둘이라는 사실을 **선언이 드러낸다**(감추면 화면이 어느 쪽을 보는지 아무도 모른다).
+     */
+    { axis: 'recipes', path: 'productionSpec.definition.recipes', label: 'twin.axis.recipes', kind: 'spec',
+        standardClass: { isa95: 'OperationsSegment' } },
+    { axis: 'routes', path: 'productionSpec.definition.routes', label: 'twin.axis.routes', kind: 'spec',
+        standardClass: { isa95: 'OperationsSegment' } },
+    { axis: 'materials', path: 'productionSpec.definition.materials', label: 'twin.axis.materials', kind: 'class',
+        standardClass: { isa95: 'MaterialDefinition' } }
+];
+/** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
+export const TWIN_RELATIONS = [
+    /* 자리가 속한 구역 — **board 밖**(호스트의 `TwinArea`). 해소는 호스트가 한다. */
+    { from: 'locations', field: 'parentId', target: { kind: 'external', entity: 'space.area' }, via: 'twin.rel.area', optional: true },
+    /* 자원이 사는 자리 */
+    { from: 'equipment', field: 'homeLocation', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.home', optional: true },
+    { from: 'persons', field: 'homeLocation', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.home', optional: true },
+    { from: 'assets', field: 'homeLocation', target: { kind: 'axis', axis: 'locations' }, via: 'twin.rel.home', optional: true },
+    /* 자원의 등급 — 설비만 `kind`(타입)로 가고 사람·자산은 등급 목록으로 간다. 표준의 비대칭 그대로. */
+    { from: 'persons', field: 'personnelClassIds[]', target: { kind: 'axis', axis: 'personnelClasses' }, via: 'twin.rel.class', optional: true },
+    { from: 'assets', field: 'assetClassIds[]', target: { kind: 'axis', axis: 'assetClasses' }, via: 'twin.rel.class', optional: true },
+    { from: 'equipment', field: 'kind', target: { kind: 'type', role: 'equipment' }, via: 'twin.rel.type' },
+    { from: 'locations', field: 'type', target: { kind: 'type', role: 'location' }, via: 'twin.rel.type' },
+    /* 생산 — 레시피에서 시작해 라우트·공정·품목으로 퍼진다 */
+    { from: 'recipes', field: 'route', target: { kind: 'axis', axis: 'routes' }, via: 'twin.rel.route', optional: true },
+    { from: 'recipes', field: 'inputs[].material', target: { kind: 'axis', axis: 'materials' }, via: 'twin.rel.input' },
+    { from: 'recipes', field: 'outputs[].material', target: { kind: 'axis', axis: 'materials' }, via: 'twin.rel.output' },
+    { from: 'routes', field: 'steps[]', target: { kind: 'axis', axis: 'operations' }, via: 'twin.rel.step' },
+    /* 공정이 도는 자리·자원 — 항목이 아니라 **타입**을 가리킨다 */
+    { from: 'operations', field: 'locationType', target: { kind: 'type', role: 'location' }, via: 'twin.rel.at', optional: true },
+    { from: 'operations', field: 'resourceType', target: { kind: 'type', role: 'equipment' }, via: 'twin.rel.by', optional: true }
+];
+/**
+ * 오늘 **실제로 짝이 서는 것**만 선언한다. 그럴듯한 속성을 미리 적어 두면 화면이 빈칸을 줄줄이
+ * 내고, 그건 "아직 안 쟀다" 가 아니라 "이 트윈은 부실하다" 로 읽힌다.
+ * `series` 는 아직 **아무도 내지 않는다** — EMS 가 붙을 때 생산자와 함께 선언한다.
+ */
+export const TWIN_PROPERTIES = [
+    /* 공정 — 선언(ISO 8601 기간)과 관측(저널에서 접은 분포)이 둘 다 있는 유일한 짝. */
+    { axis: 'operations', key: 'duration', label: 'twin.prop.duration', kind: 'distribution',
+        declaredField: 'duration', observedBy: 'kpi-fold.workTime', uom: 'ms' },
+    /* 자리 — 용량은 선언, 점유는 관측. 단위가 다른 것이 아니라 **같은 축의 두 값**이다. */
+    { axis: 'locations', key: 'capacity', label: 'twin.prop.capacity', kind: 'level',
+        declaredField: 'capacity', observedBy: 'state.location.occupancy' },
+    /* 설비 — 고장 모델은 선언, 가동은 관측(OEE). 선언 없이도 관측은 선다. */
+    { axis: 'equipment', key: 'mtbf', label: 'twin.prop.mtbf', kind: 'distribution',
+        declaredField: 'mtbfMs', observedBy: 'oee.availability', uom: 'ms' },
+    { axis: 'equipment', key: 'mttr', label: 'twin.prop.mttr', kind: 'distribution',
+        declaredField: 'mttrMs', observedBy: 'oee.availability', uom: 'ms' },
+    { axis: 'equipment', key: 'availability', label: 'twin.prop.availability', kind: 'rate',
+        observedBy: 'oee.availability', uom: 'ratio' }
+];
+/** 이 축이 보여 줄 속성들 — 없으면 빈 배열(속성 없는 축이 정상이다). */
+export const propertiesOf = (axis) => TWIN_PROPERTIES.filter(p => p.axis === axis);
+/** 이 축에서 나가는 관계 · 이 축으로 들어오는 관계 — 항목 패널의 "이어진 것" 양방향. */
+export const relationsFrom = (axis) => TWIN_RELATIONS.filter(r => r.from === axis);
+export const relationsTo = (axis) => TWIN_RELATIONS.filter(r => r.target.kind === 'axis' && r.target.axis === axis);
+/** 축 이름 → 서술. 모르는 축이면 `undefined` — 화면은 그것을 "미선언" 으로 낸다(숨기지 않는다). */
+export function axisInfo(axis) {
+    return TWIN_AXES.find(a => a.axis === axis);
+}
 export const DOMAIN_SYSTEMS = ['wms', 'yms', 'mes'];
 /** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */
 export function capabilitiesForType(system, typeKey) {

package/dist/flow-engine.d.ts

@@ -376,6 +376,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     private _attentionSince;
     dispatch(cmd: Command): CommandAck;
+    private dispatchInner;
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     protected handleCommand(cmd: Command): CommandAck;
     readonly scenario: ScenarioControl;
@@ -617,6 +618,17 @@ export declare abstract class FlowEngine implements TwinKernel {
     private oeeOf;
     /** 정책에 넘길 특정 타입 자리의 관측 뷰 — 예약(그 자리로 향하는 in-flight task) 포함. */
     protected slotViews(locationType: string): SlotView[];
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    private _correlationId?;
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
     /**

package/dist/flow-engine.js

@@ -546,6 +546,20 @@ export class FlowEngine {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     _attentionSince = new Map(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
     dispatch(cmd) {
+        /*
+         * 이 커맨드가 낳는 이벤트에 상관값을 단다. 명시값이 없으면 **commandId 를 쓴다** — 호출자가
+         * 따로 챙기지 않아도 모든 지시가 자기 결과와 이어진다(감사 기록이 commandId 를 이미 갖고 있다).
+         * finally 로 반드시 걷는다: 남겨 두면 그 뒤 틱에서 일어난 무관한 일까지 이 커맨드 탓이 된다.
+         */
+        this._correlationId = cmd.correlationId ?? cmd.commandId;
+        try {
+            return this.dispatchInner(cmd);
+        }
+        finally {
+            this._correlationId = undefined;
+        }
+    }
+    dispatchInner(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
         // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
         const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
@@ -1282,15 +1296,26 @@ export class FlowEngine {
                 views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
         return views;
     }
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    _correlationId;
     emit(event) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data: event };
         for (const h of this.handlers)
             h(e);
     }
     emitOp(eventType, data) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data };
         for (const h of this.handlers)
             h(e);
     }

package/dist-cjs/index.cjs

@@ -51,6 +51,9 @@ __export(index_exports, {
   PRIORITY_UNSET: () => PRIORITY_UNSET,
   RETIRED_VOCABULARY: () => RETIRED_VOCABULARY,
   StateProjector: () => ObservedReducer,
+  TWIN_AXES: () => TWIN_AXES,
+  TWIN_PROPERTIES: () => TWIN_PROPERTIES,
+  TWIN_RELATIONS: () => TWIN_RELATIONS,
   TwinHistory: () => TwinHistory,
   TwinObserver: () => TwinObserver,
   TwinRuntime: () => TwinRuntime,
@@ -67,6 +70,7 @@ __export(index_exports, {
   activeShiftOf: () => activeShiftOf,
   aggregationEvent: () => aggregationEvent,
   analyzeCapacity: () => analyzeCapacity,
+  axisInfo: () => axisInfo,
   capabilitiesForType: () => capabilitiesForType,
   classClosure: () => classClosure,
   compareStates: () => compareStates,
@@ -102,10 +106,13 @@ __export(index_exports, {
   parseIsoDuration: () => parseIsoDuration,
   partialFitPolicy: () => partialFitPolicy,
   priorityRank: () => priorityRank,
+  propertiesOf: () => propertiesOf,
   quantityIn: () => quantityIn,
   readBoardAssets: () => readBoardAssets,
   readBoardEquipment: () => readBoardEquipment,
   readBoardLocations: () => readBoardLocations,
+  relationsFrom: () => relationsFrom,
+  relationsTo: () => relationsTo,
   replay: () => replay,
   replaySegments: () => replaySegments,
   retiredVocabularyIn: () => retiredVocabularyIn,
@@ -1555,6 +1562,189 @@ var DOMAIN_CATALOG = {
   yms: { system: "yms", label: "twin.system.yms", types: YMS_TYPES, locationTypes: locationKeys(YMS_TYPES) },
   mes: { system: "mes", label: "twin.system.mes", types: MES_TYPES, locationTypes: locationKeys(MES_TYPES) }
 };
+var TWIN_AXES = [
+  {
+    axis: "locations",
+    path: "locations",
+    label: "twin.axis.locations",
+    kind: "instance",
+    typeRole: "location",
+    standardClass: { epcis: "SGLN" }
+  },
+  {
+    axis: "equipment",
+    path: "equipment",
+    label: "twin.axis.equipment",
+    kind: "instance",
+    typeRole: "equipment",
+    standardClass: { isa95: "Equipment", iso55000: "Asset", epcis: "GIAI" }
+  },
+  {
+    axis: "persons",
+    path: "persons",
+    label: "twin.axis.persons",
+    kind: "instance",
+    standardClass: { isa95: "Person" }
+  },
+  {
+    axis: "assets",
+    path: "assets",
+    label: "twin.axis.assets",
+    kind: "instance",
+    standardClass: { isa95: "PhysicalAsset", iso55000: "Asset" }
+  },
+  {
+    axis: "personnelClasses",
+    path: "personnelClasses",
+    label: "twin.axis.personnelClasses",
+    kind: "class",
+    standardClass: { isa95: "PersonnelClass" }
+  },
+  {
+    axis: "equipmentClasses",
+    path: "equipmentClasses",
+    label: "twin.axis.equipmentClasses",
+    kind: "class",
+    standardClass: { isa95: "EquipmentClass" }
+  },
+  {
+    axis: "assetClasses",
+    path: "assetClasses",
+    label: "twin.axis.assetClasses",
+    kind: "class",
+    standardClass: { isa95: "PhysicalAssetClass" }
+  },
+  {
+    axis: "materialDefinitions",
+    path: "materialDefinitions",
+    label: "twin.axis.materialDefinitions",
+    kind: "class",
+    standardClass: { isa95: "MaterialDefinition" }
+  },
+  {
+    axis: "materialClasses",
+    path: "materialClasses",
+    label: "twin.axis.materialClasses",
+    kind: "class",
+    standardClass: { isa95: "MaterialClass" }
+  },
+  {
+    axis: "operations",
+    path: "operations",
+    label: "twin.axis.operations",
+    kind: "spec",
+    standardClass: { isa95: "OperationsSegment" }
+  },
+  {
+    axis: "productionSpec",
+    path: "productionSpec",
+    label: "twin.axis.productionSpec",
+    kind: "spec",
+    standardClass: { isa95: "OperationsSegment" }
+  },
+  /*
+   * 아래 셋은 저장상 `productionSpec.definition` 안에 있지만 **개념으로는 1급**이다.
+   * `materials` 가 최상위 `materialDefinitions` 와 **둘 다** 있는 것은 지금 상태 그대로다 —
+   * 전자는 도메인 정의의 가벼운 목록(`{key,label}`), 후자는 ISA-95 풍부형이다. 같은 것의 집이
+   * 둘이라는 사실을 **선언이 드러낸다**(감추면 화면이 어느 쪽을 보는지 아무도 모른다).
+   */
+  {
+    axis: "recipes",
+    path: "productionSpec.definition.recipes",
+    label: "twin.axis.recipes",
+    kind: "spec",
+    standardClass: { isa95: "OperationsSegment" }
+  },
+  {
+    axis: "routes",
+    path: "productionSpec.definition.routes",
+    label: "twin.axis.routes",
+    kind: "spec",
+    standardClass: { isa95: "OperationsSegment" }
+  },
+  {
+    axis: "materials",
+    path: "productionSpec.definition.materials",
+    label: "twin.axis.materials",
+    kind: "class",
+    standardClass: { isa95: "MaterialDefinition" }
+  }
+];
+var TWIN_RELATIONS = [
+  /* 자리가 속한 구역 — **board 밖**(호스트의 `TwinArea`). 해소는 호스트가 한다. */
+  { from: "locations", field: "parentId", target: { kind: "external", entity: "space.area" }, via: "twin.rel.area", optional: true },
+  /* 자원이 사는 자리 */
+  { from: "equipment", field: "homeLocation", target: { kind: "axis", axis: "locations" }, via: "twin.rel.home", optional: true },
+  { from: "persons", field: "homeLocation", target: { kind: "axis", axis: "locations" }, via: "twin.rel.home", optional: true },
+  { from: "assets", field: "homeLocation", target: { kind: "axis", axis: "locations" }, via: "twin.rel.home", optional: true },
+  /* 자원의 등급 — 설비만 `kind`(타입)로 가고 사람·자산은 등급 목록으로 간다. 표준의 비대칭 그대로. */
+  { from: "persons", field: "personnelClassIds[]", target: { kind: "axis", axis: "personnelClasses" }, via: "twin.rel.class", optional: true },
+  { from: "assets", field: "assetClassIds[]", target: { kind: "axis", axis: "assetClasses" }, via: "twin.rel.class", optional: true },
+  { from: "equipment", field: "kind", target: { kind: "type", role: "equipment" }, via: "twin.rel.type" },
+  { from: "locations", field: "type", target: { kind: "type", role: "location" }, via: "twin.rel.type" },
+  /* 생산 — 레시피에서 시작해 라우트·공정·품목으로 퍼진다 */
+  { from: "recipes", field: "route", target: { kind: "axis", axis: "routes" }, via: "twin.rel.route", optional: true },
+  { from: "recipes", field: "inputs[].material", target: { kind: "axis", axis: "materials" }, via: "twin.rel.input" },
+  { from: "recipes", field: "outputs[].material", target: { kind: "axis", axis: "materials" }, via: "twin.rel.output" },
+  { from: "routes", field: "steps[]", target: { kind: "axis", axis: "operations" }, via: "twin.rel.step" },
+  /* 공정이 도는 자리·자원 — 항목이 아니라 **타입**을 가리킨다 */
+  { from: "operations", field: "locationType", target: { kind: "type", role: "location" }, via: "twin.rel.at", optional: true },
+  { from: "operations", field: "resourceType", target: { kind: "type", role: "equipment" }, via: "twin.rel.by", optional: true }
+];
+var TWIN_PROPERTIES = [
+  /* 공정 — 선언(ISO 8601 기간)과 관측(저널에서 접은 분포)이 둘 다 있는 유일한 짝. */
+  {
+    axis: "operations",
+    key: "duration",
+    label: "twin.prop.duration",
+    kind: "distribution",
+    declaredField: "duration",
+    observedBy: "kpi-fold.workTime",
+    uom: "ms"
+  },
+  /* 자리 — 용량은 선언, 점유는 관측. 단위가 다른 것이 아니라 **같은 축의 두 값**이다. */
+  {
+    axis: "locations",
+    key: "capacity",
+    label: "twin.prop.capacity",
+    kind: "level",
+    declaredField: "capacity",
+    observedBy: "state.location.occupancy"
+  },
+  /* 설비 — 고장 모델은 선언, 가동은 관측(OEE). 선언 없이도 관측은 선다. */
+  {
+    axis: "equipment",
+    key: "mtbf",
+    label: "twin.prop.mtbf",
+    kind: "distribution",
+    declaredField: "mtbfMs",
+    observedBy: "oee.availability",
+    uom: "ms"
+  },
+  {
+    axis: "equipment",
+    key: "mttr",
+    label: "twin.prop.mttr",
+    kind: "distribution",
+    declaredField: "mttrMs",
+    observedBy: "oee.availability",
+    uom: "ms"
+  },
+  {
+    axis: "equipment",
+    key: "availability",
+    label: "twin.prop.availability",
+    kind: "rate",
+    observedBy: "oee.availability",
+    uom: "ratio"
+  }
+];
+var propertiesOf = (axis) => TWIN_PROPERTIES.filter((p) => p.axis === axis);
+var relationsFrom = (axis) => TWIN_RELATIONS.filter((r) => r.from === axis);
+var relationsTo = (axis) => TWIN_RELATIONS.filter((r) => r.target.kind === "axis" && r.target.axis === axis);
+function axisInfo(axis) {
+  return TWIN_AXES.find((a) => a.axis === axis);
+}
 var DOMAIN_SYSTEMS = ["wms", "yms", "mes"];
 function capabilitiesForType(system, typeKey) {
   return DOMAIN_CATALOG[system]?.types.find((t) => t.key === typeKey)?.capabilities ?? [];
@@ -2353,6 +2543,14 @@ var FlowEngine = class {
   _attentionSince = /* @__PURE__ */ new Map();
   // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
   dispatch(cmd) {
+    this._correlationId = cmd.correlationId ?? cmd.commandId;
+    try {
+      return this.dispatchInner(cmd);
+    } finally {
+      this._correlationId = void 0;
+    }
+  }
+  dispatchInner(cmd) {
     const ok = () => ({ commandId: cmd.commandId, accepted: true });
     const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
     switch (cmd.type) {
@@ -3014,14 +3212,25 @@ var FlowEngine = class {
     for (const n of this.locations.values()) if (n.type === locationType) views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
     return views;
   }
+  /**
+   * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+   *
+   * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+   * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+   *
+   * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+   * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+   * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+   */
+  _correlationId;
   emit(event) {
     this.revision++;
-    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, ...this._correlationId ? { correlationId: this._correlationId } : {}, data: event };
     for (const h of this.handlers) h(e);
   }
   emitOp(eventType, data) {
     this.revision++;
-    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...this._correlationId ? { correlationId: this._correlationId } : {}, data };
     for (const h of this.handlers) h(e);
   }
   /**
@@ -4660,6 +4869,9 @@ function retiredVocabularyIn(line) {
   PRIORITY_UNSET,
   RETIRED_VOCABULARY,
   StateProjector,
+  TWIN_AXES,
+  TWIN_PROPERTIES,
+  TWIN_RELATIONS,
   TwinHistory,
   TwinObserver,
   TwinRuntime,
@@ -4676,6 +4888,7 @@ function retiredVocabularyIn(line) {
   activeShiftOf,
   aggregationEvent,
   analyzeCapacity,
+  axisInfo,
   capabilitiesForType,
   classClosure,
   compareStates,
@@ -4711,10 +4924,13 @@ function retiredVocabularyIn(line) {
   parseIsoDuration,
   partialFitPolicy,
   priorityRank,
+  propertiesOf,
   quantityIn,
   readBoardAssets,
   readBoardEquipment,
   readBoardLocations,
+  relationsFrom,
+  relationsTo,
   replay,
   replaySegments,
   retiredVocabularyIn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {