@operato/twin-kernel 0.4.3 → 0.6.0

package/dist/contract.d.ts

@@ -362,7 +362,7 @@ export declare function conversionFactorOf(def: MaterialDefinition | undefined,
  * 되풀이를 간단히 적기 위한 선택이고, 그러면 **어느 기준의 06:00 인가**가 반드시 필요하다 —
  * Rosarito(UTC−7)의 06:00 을 UTC 로 읽으면 7시간이 틀린다.
  *
- * 그래서 `BoardDef.utcOffsetMinutes` 가 그 기준이다. **선언하지 않으면 UTC 로 읽고, 그 사실을 여기
+ * 그래서 `TwinModelDef.utcOffsetMinutes` 가 그 기준이다. **선언하지 않으면 UTC 로 읽고, 그 사실을 여기
  * 밝힌다**(조용히 가정하지 않기 위해). 프레임워크에는 이미 테넌트 시간대(`Domain.timezone`)와
  * 교대→절대구간 변환(`@things-factory/work-shift` `work-shift-range`, moment-timezone)이 있으므로,
  * **기준을 푸는 일은 호스트의 몫**이다(커널은 zero-dep — 시간대 데이터를 들 수 없다).
@@ -1267,14 +1267,14 @@ export type Unsubscribe = () => void;
  * 이 함수를 거치지 않고 `def.locations` 를 직접 읽는 코드를 두지 않는다 — 하나라도 남으면 그 경로에서만
  * 옛 보드의 자리가 조용히 사라진다(빈 배열 = 자리 없는 트윈 = 아무 일도 일어나지 않는다).
  */
-export declare function readBoardLocations(def: BoardDef | (Record<string, unknown> & {
+export declare function readBoardLocations(def: TwinModelDef | (Record<string, unknown> & {
     locations?: unknown;
     nodes?: unknown;
-})): BoardDef['locations'];
-export declare function readBoardEquipment(def: BoardDef | Record<string, unknown>): BoardDef['equipment'];
+})): TwinModelDef['locations'];
+export declare function readBoardEquipment(def: TwinModelDef | Record<string, unknown>): TwinModelDef['equipment'];
 /** 저장된 보드의 반복사용 자산 — 설비와 같은 정규화를 거친다. */
-export declare function readBoardAssets(def: BoardDef | Record<string, unknown>): NonNullable<BoardDef['assets']>;
-export interface BoardDef {
+export declare function readBoardAssets(def: TwinModelDef | Record<string, unknown>): NonNullable<TwinModelDef['assets']>;
+export interface TwinModelDef {
     /** parallelism = 동시 처리 수(LocationState.parallelism 참조). capacity 는 저장 용량. */
     locations: {
         id: string;
@@ -1391,6 +1391,20 @@ export interface BoardDef {
      * 유통가공(VAS)은 비직렬 클래스+수량이 맞는 모양이므로 코어의 일반 경로를 쓴다.
      */
     productionSpec?: ProductionSpec;
+    /**
+     * 공정 명세 — **ISA-95 `OperationsSegment`.** 이 현장에서 각 작업이 어디서·무엇으로·얼마나 걸리나.
+     *
+     * ── 왜 이제야 선언하나 (2026-08-08) ──────────────────────────────────────────
+     * 이 자리는 **이미 쓰이고 있었다.** 마스터 인제스트가 `board.operations` 로 통과시키고 호스트가
+     * `applyOperations` 로 커널에 싣는다. 그런데 `TwinModelDef` 는 그것을 말한 적이 없다.
+     *
+     * 바로 위 `productionSpec` 이 겪은 것과 **같은 일**이다 — "계약에 없으니 아무도 이 자리를 발견할
+     * 수 없었다. 타입이 말해 주지 않는 필드는 없는 필드다." 그때 배운 것을 여기 적용한다.
+     *
+     * 소비 경로가 둘인 것은 그대로 둔다(여기와 `productionSpec.definition.operations`) — 후자는
+     * 라우트의 단계를 해소할 때 읽힌다. 집을 하나로 모으는 것은 별건이고, 그 전에 **선언부터** 한다.
+     */
+    operations?: import('./domain-definition.ts').OperationDef[];
 }
 /**
  * 생산 선언 — 도메인 정의(ISA-95 operations + BOM)와, 그 추상 자재 키를 실제 GS1 식별자로 잇는 바인딩.
@@ -1408,7 +1422,7 @@ export interface ProductionSpec {
     recipeKey?: string;
 }
 export interface TwinKernel {
-    loadBoard(def: BoardDef): void;
+    loadTwinModel(def: TwinModelDef): void;
     getSnapshot(): StateSnapshot;
     onEvent(handler: EventHandler): Unsubscribe;
     dispatch(cmd: Command): CommandAck;

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 {
+    /**
+     * 축의 이름 — 화면·관계 선언이 쓰는 키. 최상위 축은 `TwinModelDef` 의 키 **그대로**다
+     * (저장·계약의 이름과 갈라지면 그 순간 방언이 생긴다).
+     */
+    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/domain-definition.js

@@ -1,5 +1,5 @@
 /*
- * 도메인 정의(DomainDefinition) — 커널의 선언적 도메인 계약. `BoardDef`(토폴로지 입력)의 확장 격.
+ * 도메인 정의(DomainDefinition) — 커널의 선언적 도메인 계약. `TwinModelDef`(토폴로지 입력)의 확장 격.
  * 커널이 "무엇이 있고 어떻게 흐르나"(타입 + 공정 route/BOM)를 **데이터로** 받는 형식. zero-dep(자기 타입).
  *
  * 특정 공정이 커널 코드에 하드코딩되던 것을 이 데이터 계약으로 대체한다(design/plans/domain-catalog-layering.md).

package/dist/event-journal.d.ts

@@ -1,4 +1,4 @@
-import type { BoardDef, CanonicalEnvelope } from './contract.ts';
+import type { TwinModelDef, CanonicalEnvelope } from './contract.ts';
 import { type ProjectedState } from './state-projector.ts';
 export declare class EventJournal {
     private events;
@@ -14,10 +14,10 @@ export declare class EventJournal {
     untilSimTime(iso: string): CanonicalEnvelope[];
 }
 /** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
-export declare function replay(board: BoardDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+export declare function replay(board: TwinModelDef, events: readonly CanonicalEnvelope[]): ProjectedState;
 /** 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디. */
 export interface StructureSegment {
-    board: BoardDef;
+    board: TwinModelDef;
     events: readonly CanonicalEnvelope[];
 }
 /** 구조가 바뀐 지점마다 무엇이 사라졌는지. 조용히 넘어가지 않는다. */

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, BoardDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState } from './contract.ts';
+import type { ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, 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';
@@ -283,7 +283,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     private observedDirty;
     private observeMode;
     /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
-    protected boardDef?: BoardDef;
+    protected boardDef?: TwinModelDef;
     /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
     private specUse;
     protected epcSeq: number;
@@ -310,9 +310,9 @@ export declare abstract class FlowEngine implements TwinKernel {
      * 이동(WMS/YMS: from→to 이동) 이든 변환(MES: 소비→생산) 이든 여기서 결정 → base 가 이동-중립.
      */
     protected abstract onTaskComplete(task: FlowTask): void;
-    loadBoard(def: BoardDef): void;
+    loadTwinModel(def: TwinModelDef): void;
     /**
-     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
      * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
      */
     addEquipment(m: {

package/dist/flow-engine.js

@@ -253,7 +253,7 @@ export class FlowEngine {
         this.policy = policy;
     }
     // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
-    loadBoard(def) {
+    loadTwinModel(def) {
         this.boardDef = def;
         /*
          * **생산 선언은 어느 커널이든 싣는다.** 예전에는 MES 커널만 생성자에서 이것을 실었고(그 시절
@@ -283,7 +283,7 @@ export class FlowEngine {
         }
     }
     /**
-     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
      * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
      */
     addEquipment(m) {

package/dist/observed-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { AssetState, BoardDef, CanonicalEnvelope, LocationState, ItemState, EquipmentState, PersonState, TaskState, OrderState } from './contract.ts';
+import type { AssetState, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, EquipmentState, PersonState, TaskState, OrderState } from './contract.ts';
 /**
  * 마스터 동기 — 선언적 로케이션 upsert/remove.
  *
@@ -72,7 +72,7 @@ export declare class ObservedReducer {
     private shifts;
     /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
     private utcOffsetMinutes?;
-    constructor(board: BoardDef);
+    constructor(board: TwinModelDef);
     /**
      * **구조를 갈아탄다** — 관측된 사실은 지키고 토폴로지만 새 선언으로 바꾼다.
      *
@@ -91,7 +91,7 @@ export declare class ObservedReducer {
      * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
      * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
      */
-    adoptStructure(board: BoardDef): {
+    adoptStructure(board: TwinModelDef): {
         locationsAdded: number;
         locationsDropped: number;
         equipmentDropped: number;

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 ?? [];
@@ -2090,7 +2280,7 @@ var FlowEngine = class {
     this.policy = policy;
   }
   // ── TwinKernel (mechanics, 도메인 무관) ───────────────────────────────────
-  loadBoard(def) {
+  loadTwinModel(def) {
     this.boardDef = def;
     if (def.productionSpec?.definition?.operations?.length) this.loadOperations(def.productionSpec.definition.operations);
     for (const n of readBoardLocations(def)) this.locations.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, occupancy: 0, status: "idle", parentId: n.parentId });
@@ -2109,7 +2299,7 @@ var FlowEngine = class {
     }
   }
   /**
-   * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
+   * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
    * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
    */
   addEquipment(m) {
@@ -4679,6 +4869,9 @@ function retiredVocabularyIn(line) {
   PRIORITY_UNSET,
   RETIRED_VOCABULARY,
   StateProjector,
+  TWIN_AXES,
+  TWIN_PROPERTIES,
+  TWIN_RELATIONS,
   TwinHistory,
   TwinObserver,
   TwinRuntime,
@@ -4695,6 +4888,7 @@ function retiredVocabularyIn(line) {
   activeShiftOf,
   aggregationEvent,
   analyzeCapacity,
+  axisInfo,
   capabilitiesForType,
   classClosure,
   compareStates,
@@ -4730,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.3",
+  "version": "0.6.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": {