@operato/twin-kernel 0.2.2 → 0.3.0

package/dist/contract.js

@@ -5,22 +5,168 @@
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.
  *
- * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 노드 상태 채널이
+ * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 자리 상태 채널이
  * 없어 비어 있었다. 화면은 그 값을 그대로 보여 주고 있었다 — **정보처럼 보이는데 정보가 아니었다.**
  *
  * 문턱은 병목 주목(`deriveAttentions`)이 쓰는 것과 **같다**: 90% 이상이면 임박, 100% 이상이면 포화.
  * 규칙이 둘이면 화면과 주목이 다른 말을 한다. 용량을 모르면 상태도 모른다(undefined — 꾸미지 않는다).
  */
-export const NODE_SATURATION_NEAR = 0.9;
-export function nodeStatusOf(n) {
+export const LOCATION_SATURATION_NEAR = 0.9;
+export function locationStatusOf(n) {
     const cap = n.capacity;
     if (!(typeof cap === 'number' && cap > 0))
         return undefined;
     const r = (n.occupancy ?? 0) / cap;
-    return r >= 1 ? 'full' : r >= NODE_SATURATION_NEAR ? 'near-full' : 'available';
+    return r >= 1 ? 'full' : r >= LOCATION_SATURATION_NEAR ? 'near-full' : 'available';
+}
+/**
+ * 설비 계층 단계 — **ISA-95 표준 어휘.** 1차 출처: B2MML `B2MML-Common.xsd` /
+ * `EquipmentLevel1Type` 열거값 + `EquipmentLevelType` 주석("role based equipment hierarchy level
+ * as defined in ISA 95").
+ *
+ * 우리가 단의 이름을 발명하지 않는다. "라인" 은 `ProductionLine`, "존" 은 `StorageZone` 으로
+ * 표준이 이미 정해 뒀다. 발명하면 그 순간 방언이 되고, 연동 상대와 매핑 표가 필요해진다.
+ *
+ * **`Other` 는 탈출구다** — 표준도 열거값 밖을 인정한다(`OtherValue` 속성). 억지로 끼워 맞추는 대신
+ * `Other` 로 두고 현장의 낱말은 `type` 에 남긴다.
+ *
+ * `StorageZone`·`StorageUnit` 도 이 계층 안에 있다. 다만 **자리 자체는 다른 축**이다 —
+ * ISA-95 는 `OperationalLocation`("자원이 놓이거나 놓일 것으로 예상되는 논리적·물리적 장소",
+ * `B2MML-OperationalLocation.xsd`)을 별도 스키마로 두고, `Equipment` 가 자기 위치를 그것으로 가리킨다.
+ * 우리 `locations` 가 그 개념이다(2026-08-01 개명 — `plans/isa95-coverage.md` §3-1).
+ */
+export const EQUIPMENT_LEVEL = [
+    'Enterprise',
+    'Site',
+    'Area',
+    'ProcessCell',
+    'Unit',
+    'ProductionLine',
+    'WorkCell',
+    'ProductionUnit',
+    'StorageZone',
+    'StorageUnit',
+    'WorkCenter',
+    'WorkUnit',
+    'EquipmentModule',
+    'ControlModule',
+    'Other'
+];
+/** 표준 열거값인지 — 상류에서 들어온 값을 조용히 통과시키지 않고 확인하는 용도. */
+export function isEquipmentLevel(v) {
+    return typeof v === 'string' && EQUIPMENT_LEVEL.includes(v);
+}
+/**
+ * 계층 색인을 만든다. **순환은 만들 때 잡고 던진다** — 렌더 도중에 터지는 대신 여기서 한 번에.
+ * 순환을 조용히 잘라 내면 롤업이 틀린 값을 내고, 그건 이 함수가 막으려는 바로 그 실패다.
+ */
+export function hierarchyOf(s) {
+    const push = (m, k, v) => {
+        const cur = m.get(k);
+        if (cur)
+            cur.push(v);
+        else
+            m.set(k, [v]);
+    };
+    const parent = new Map();
+    const kids = new Map();
+    const known = new Set(s.locations.map(n => n.id));
+    for (const n of s.locations) {
+        if (!n.parentId || n.parentId === n.id)
+            continue; // 자기 부모는 선언 오류 — 사슬에 넣지 않는다
+        parent.set(n.id, n.parentId);
+        if (known.has(n.parentId))
+            push(kids, n.parentId, n.id);
+    }
+    /* 순환 검출 — 자리마다 사슬을 끝까지 밀어 본다. 방문한 자리를 다시 만나면 그 경로를 그대로 알린다. */
+    for (const start of known) {
+        const seen = [start];
+        for (let at = parent.get(start); at !== undefined; at = parent.get(at)) {
+            if (seen.includes(at))
+                throw new Error(`location hierarchy has a cycle: ${[...seen, at].join(' → ')}`);
+            seen.push(at);
+            if (!known.has(at))
+                break; // 구역에 닿았다 — 사슬 끝
+        }
+    }
+    const homes = new Map();
+    for (const m of s.equipment ?? [])
+        if (m.homeLocation)
+            push(homes, m.homeLocation, m.id);
+    const ancestorsOf = (id) => {
+        const out = [];
+        for (let at = parent.get(id); at !== undefined; at = parent.get(at)) {
+            out.push(at);
+            if (!known.has(at))
+                break;
+        }
+        return out;
+    };
+    const descendantsOf = (id) => {
+        const out = [];
+        const stack = [...(kids.get(id) ?? [])];
+        while (stack.length) {
+            const cur = stack.pop();
+            out.push(cur);
+            stack.push(...(kids.get(cur) ?? []));
+        }
+        return out;
+    };
+    const typeOf = new Map(s.locations.map(n => [n.id, n.type]));
+    const levelOf = new Map(s.locations.map(n => [n.id, n.level]));
+    return {
+        childrenOf: id => [...(kids.get(id) ?? [])],
+        ancestorsOf,
+        descendantsOf,
+        rollupOf: id => ancestorsOf(id).find(a => !known.has(a)),
+        ancestorOfLevel: (id, level) => ancestorsOf(id).find(a => known.has(a) && levelOf.get(a) === level),
+        ancestorOfType: (id, type) => ancestorsOf(id).find(a => known.has(a) && typeOf.get(a) === type),
+        equipmentOf: (id, opts) => {
+            const scope = opts?.deep ? [id, ...descendantsOf(id)] : [id];
+            return scope.flatMap(n => homes.get(n) ?? []);
+        }
+    };
+}
+/**
+ * 등급 소속을 **상속을 타고 닫는다** — "이 개체가 이 등급으로 통하는가".
+ *
+ * 순환은 방문 집합으로 끊는다(잘못된 마스터가 무한 루프를 만들지 않게). 등급 정의가 없으면 소속
+ * 그대로만 본다 — 정의를 요구하지 않는다(정의를 싣지 않은 트윈이 그대로 돌아야 한다).
+ *
+ * `at` 를 주면 **유효 기간 밖의 등급은 제외**한다. 안 주면 기간을 보지 않는다(모르면 판단하지 않는다).
+ */
+export function classClosure(directIds, defs, at) {
+    const byId = new Map((defs ?? []).map(d => [d.id, d]));
+    const atMs = at ? Date.parse(at) : NaN;
+    const inWindow = (d) => {
+        if (!d || !Number.isFinite(atMs))
+            return true;
+        const from = d.effectiveStart ? Date.parse(d.effectiveStart) : NaN;
+        const to = d.effectiveEnd ? Date.parse(d.effectiveEnd) : NaN;
+        if (Number.isFinite(from) && atMs < from)
+            return false;
+        if (Number.isFinite(to) && atMs > to)
+            return false;
+        return true;
+    };
+    const out = new Set();
+    const stack = [...(directIds ?? [])];
+    while (stack.length) {
+        const id = stack.pop();
+        if (out.has(id))
+            continue;
+        const def = byId.get(id);
+        if (!inWindow(def))
+            continue; // 만료된 등급은 자기도, 그 상위도 타지 않는다
+        out.add(id);
+        for (const b of def?.baseIds ?? [])
+            if (!out.has(b))
+                stack.push(b);
+    }
+    return out;
 }
 // ── 운영 델타(비-EPCIS) — State 채널의 나머지 절반 ──────────────────────────
-// EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·movers(equipment)·orders 의 운영 상태는
+// EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·equipment·orders 의 운영 상태는
 // 이 델타로 미러한다. envelope.eventType = 'task.status' | 'equipment.status' | 'order.status'.
 // (execution-model.md §5, roadmap 발견 gap: 운영 델타 이벤트화)
 export const OP_EVENT = {
@@ -40,11 +186,57 @@ export const CMD = {
     orderResume: 'order.resume',
     orderRelease: 'order.release',
     attentionAck: 'attention.ack', // 주목 신호 확인(OPC UA A&C acknowledge) — args:{id}
-    // Operable 코어 — 모든 operable 자원(설비·이동무버) 공통. args:{resourceId}. capability-keyed(무방언, equipment.* 아님).
+    // 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)
+    resourceAdd: 'resource.add' // 라이브 자원(설비) 추가 — args:{kind, homeLocation, count?}. 런타임 구조 변이(what-if 아닌 실제 act)
 };
+// ── 보드 청사진 바인딩 (최소) ──────────────────────────────────────────────
+/**
+ * **저장된 보드를 읽는 단 하나의 입구.**
+ *
+ * `equipment` 로 개명하기 전에 저장된 보드는 `movers` 키를 갖고 있다(개명 시점 23개 인스턴스).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 저장물을 다시 쓰지 않고 **읽을 때 흡수**한다 — 마이그레이션은 되돌리기 어렵고, 읽기 호환은 값싸다.
+ *
+ * 규율 둘:
+ *  - 이 함수를 **거치지 않고** `def.equipment` 를 직접 읽는 코드를 두지 않는다. 하나라도 남으면
+ *    그 경로에서만 옛 보드의 설비가 조용히 사라진다(빈 배열).
+ *  - **쓸 때는 새 이름만** 쓴다. 두 이름으로 쓰기 시작하면 저장물에 두 벌이 영구히 섞인다.
+ *
+ * 제거 시점: 저장된 보드가 모두 `equipment` 키로 바뀐 것이 확인되면(운영 데이터 점검 후) 이 함수는
+ * 사라진다. 그때까지 남겨 두는 이유를 여기 적어 두는 것이 주석의 일이다.
+ */
+/**
+ * **저장된 보드의 자리를 읽는 단 하나의 입구.** `readBoardEquipment` 와 같은 규율.
+ *
+ * `nodes` → `locations` 개명(2026-08-01) 전에 저장된 보드는 `nodes` 키를 갖고 있다(개명 시점 23개).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 이 함수를 거치지 않고 `def.locations` 를 직접 읽는 코드를 두지 않는다 — 하나라도 남으면 그 경로에서만
+ * 옛 보드의 자리가 조용히 사라진다(빈 배열 = 자리 없는 트윈 = 아무 일도 일어나지 않는다).
+ */
+export function readBoardLocations(def) {
+    const d = def; // vocabulary-guard: allow — 옛 키 캐스트
+    return d.locations ?? d.nodes ?? []; // vocabulary-guard: allow — 옛 키 흡수
+}
+export function readBoardEquipment(def) {
+    const d = def; // vocabulary-guard: allow — 옛 키를 읽어야 하는 자리
+    const list = d.equipment ?? d.equipmentList ?? []; // vocabulary-guard: allow — 옛 키 흡수
+    /* 소속 자리 키도 함께 정규화한다 — `homeNode → homeLocation` 개명 전 보드가 23개 있다.  (vocabulary-guard: allow — 옛 키 정규화 설명)
+       배열만 흡수하고 안쪽 키를 놓치면 설비는 나타나지만 **소속이 전부 비어** 롤업이 통째로 사라진다. */
+    return list.map(e => normalizeHomeLocation(e));
+}
+/** 소속 자리 키 정규화 — 설비·자산이 같은 규칙을 쓴다(둘 다 옛 이름이 저장돼 있다). */
+function normalizeHomeLocation(entry) {
+    const legacy = entry.homeNode; // vocabulary-guard: allow — 옛 키를 읽어야 하는 자리
+    if (legacy === undefined || entry.homeLocation !== undefined)
+        return entry;
+    const { homeNode: _drop, ...rest } = entry; // vocabulary-guard: allow — 옛 키 제거
+    return { ...rest, homeLocation: legacy };
+}
+/** 저장된 보드의 반복사용 자산 — 설비와 같은 정규화를 거친다. */
+export function readBoardAssets(def) {
+    const list = (def.assets ?? []);
+    return list.map(a => normalizeHomeLocation(a));
+}

package/dist/divergence.d.ts

@@ -8,7 +8,7 @@ export interface StateDivergence {
     hasDrift: boolean;
     itemLocation: FieldDiff<string>[];
     itemDisposition: FieldDiff<string>[];
-    nodeOccupancy: FieldDiff<number>[];
+    locationOccupancy: FieldDiff<number>[];
     orderStatus: FieldDiff<string>[];
 }
 /** predicted(fork forecast)와 actual(관측) 스냅샷을 대조. 같은 sim 시점에 호출하는 것이 의미 있음. */

package/dist/divergence.js

@@ -21,8 +21,8 @@ function diffBy(predicted, actual, idOf, valOf) {
 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 locationOccupancy = diffBy(predicted.locations, actual.locations, 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 };
+    const hasDrift = itemLocation.length > 0 || itemDisposition.length > 0 || locationOccupancy.length > 0 || orderStatus.length > 0;
+    return { hasDrift, itemLocation, itemDisposition, locationOccupancy, orderStatus };
 }

package/dist/domain-catalog.d.ts

@@ -4,7 +4,7 @@ export interface TwinTypeInfo {
     /** 커널 권위 키 (예: 'storage', 'forklift'). */
     key: string;
     /** 로케이션(수동) vs 자원(능동). */
-    role: 'node' | 'mover';
+    role: 'location' | 'equipment';
     label: string;
     /** ① 표준 온톨로지 투영(03-reference-standards). 열린 문자열 — 하드코딩 enum 금지. */
     standardClass: {
@@ -22,10 +22,10 @@ export interface TwinTypeInfo {
 export interface DomainProfileInfo {
     system: DomainSystem;
     label: string;
-    /** 노드+무버 트윈 타입 — board·UI 팔레트 소싱 SSOT. */
+    /** 자리+설비 트윈 타입 — board·UI 팔레트 소싱 SSOT. */
     types: TwinTypeInfo[];
-    /** 로케이션 노드 타입 키(하위호환 파생 뷰 = types 중 role==='node'). 신규 소싱은 types 사용. */
-    nodeTypes: readonly string[];
+    /** 로케이션 자리 타입 키(하위호환 파생 뷰 = types 중 role==='location'). 신규 소싱은 types 사용. */
+    locationTypes: readonly string[];
 }
 export declare const DOMAIN_CATALOG: Record<DomainSystem, DomainProfileInfo>;
 export declare const DOMAIN_SYSTEMS: DomainSystem[];

package/dist/domain-catalog.js

@@ -1,12 +1,12 @@
 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);
+const locationKeys = (types) => types.filter(t => t.role === 'location').map(t => t.key);
 export const DOMAIN_CATALOG = {
     // label 은 언어 중립 i18n 키(twin.system.<code>) — 사람 언어는 표현계층이 렌더(L2).
-    wms: { system: 'wms', label: 'twin.system.wms', types: WMS_TYPES, nodeTypes: nodeKeys(WMS_TYPES) },
-    yms: { system: 'yms', label: 'twin.system.yms', types: YMS_TYPES, nodeTypes: nodeKeys(YMS_TYPES) },
-    mes: { system: 'mes', label: 'twin.system.mes', types: MES_TYPES, nodeTypes: nodeKeys(MES_TYPES) }
+    wms: { system: 'wms', label: 'twin.system.wms', types: WMS_TYPES, locationTypes: locationKeys(WMS_TYPES) },
+    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) }
 };
 export const DOMAIN_SYSTEMS = ['wms', 'yms', 'mes'];
 /** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */

package/dist/domain-definition.d.ts

@@ -15,14 +15,14 @@ export interface MaterialDef {
     identity?: Identity;
 }
 /** 로케이션(수동 위치) 타입. */
-export interface NodeTypeDef {
+export interface LocationTypeDef {
     key: string;
     label: string;
     standardClass?: StandardClass;
     identity?: Identity;
     capabilities?: string[];
 }
-/** 자원(능동 설비·무버) 타입. */
+/** 자원(능동 설비·설비) 타입. */
 export interface ResourceTypeDef {
     key: string;
     label: string;
@@ -91,8 +91,8 @@ export interface OperationDef {
     key: string;
     label: string;
     intent: OperationIntent;
-    /** 오퍼레이션이 수행되는 노드 타입(NodeTypeDef.key). 커널이 nodeByType 로 위치 해소. */
-    nodeType?: string;
+    /** 오퍼레이션이 수행되는 자리 타입(LocationTypeDef.key). 커널이 locationByType 로 위치 해소. */
+    locationType?: string;
     /** 요구 자원 종류(ResourceTypeDef.key). transport/process 는 자원 필요, dwell 은 무자원. */
     resourceType?: string;
     /** CBV bizStep URN(방출 이벤트 어휘). */
@@ -174,7 +174,7 @@ export interface DomainDefinition {
     label: string;
     vocabulary?: DomainVocabulary;
     materials?: MaterialDef[];
-    nodeTypes: NodeTypeDef[];
+    locationTypes: LocationTypeDef[];
     resourceTypes: ResourceTypeDef[];
     operations?: OperationDef[];
     routes?: RouteDef[];

package/dist/domain-definition.js

@@ -41,24 +41,24 @@ export function validateDomainDefinition(def) {
         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.locationTypes) || def.locationTypes.length === 0)
+        v.push('locationTypes 비어있음');
     if (!Array.isArray(def.resourceTypes))
         v.push('resourceTypes 배열 아님');
-    const nodeKeys = new Set((def.nodeTypes || []).map(n => n.key));
+    const locationKeys = new Set((def.locationTypes || []).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 [name, arr] of [['locationTypes', def.locationTypes], ['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.locationType && !locationKeys.has(o.locationType))
+            v.push(`operation '${o.key}' locationType '${o.locationType}' 미정의`);
         if (o.resourceType && !resKeys.has(o.resourceType))
             v.push(`operation '${o.key}' resourceType '${o.resourceType}' 미정의`);
         if (o.intent === 'dwell' && o.resourceType)

package/dist/event-journal.d.ts

@@ -13,5 +13,5 @@ export declare class EventJournal {
     /** sim 시각(ISO eventTime) 이하 이벤트. */
     untilSimTime(iso: string): CanonicalEnvelope[];
 }
-/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·무버). */
+/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
 export declare function replay(board: BoardDef, events: readonly CanonicalEnvelope[]): ProjectedState;

package/dist/event-journal.js

@@ -32,7 +32,7 @@ export class EventJournal {
         return this.events.filter(e => e.eventTime <= iso);
     }
 }
-/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·무버). */
+/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
 export function replay(board, events) {
     const proj = new StateProjector(board);
     for (const e of events)

package/dist/flow-engine.d.ts

@@ -1,9 +1,9 @@
-import type { Attention, BoardDef, CanonicalEnvelope, Command, CommandAck, EventHandler, MoverMotion, OeeMetrics, AssetState, GeneratorSpec, OrderState, PersonState, ScenarioControl, StateSnapshot, TwinKernel, Unsubscribe, NodeState, ItemState, MoverState, OrderStatusDelta, TaskState } from './contract.ts';
+import type { ResourceProperty, ResourceClassDef, 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 { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
 import type { DurationEstimator, DurationContext } from './duration-estimator.ts';
 import type { OperationDef } from './domain-definition.ts';
-export interface FlowNode {
+export interface FlowLocation {
     id: string;
     type: string;
     capacity: number;
@@ -39,29 +39,47 @@ export interface FlowItem {
 /** 물리 자산 — 반복사용(팔레트·랙·용기). 설비도 물품도 아니다(GRAI vs SSCC 구분은 계약 주석 참조). */
 export interface FlowAsset {
     id: string;
-    assetClass?: string;
+    /** 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). */
+    assetClassIds?: string[];
     location?: string;
     status: string;
     taskId: string | null;
     carrying?: string;
+    /** 자원 속성 — 표준 `PhysicalAssetProperty`. */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
 }
 /** 사람 — 설비와 별개 자원(고장·OEE 가 아니라 등급·교대로 산다). */
 export interface FlowPerson {
     id: string;
-    personnelClass?: string;
+    /** 속한 등급들 — 표준 `PersonnelClassID`(복수). 자격이 여럿인 사람을 표현한다. */
+    personnelClassIds?: string[];
     status: string;
     taskId: string | null;
     window?: {
         startHour: number;
         endHour: number;
     };
+    /** 지금 어디에 있나 — 표준 `Person.OperationalLocation`. 커널은 사람을 움직이지 않는다(마스터·관측이 말한다). */
+    location?: string;
+    /** 자원 속성 — 표준 `PersonProperty`. */
+    properties?: ResourceProperty[];
+    /** 자격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
 }
-export interface FlowMover {
+export interface FlowEquipment {
     id: string;
     kind: string;
     location: string;
     status: string;
     taskId: string | null;
+    /** 붙박인 자리 — 소속. `location` 은 지금 위치. 고정 설비는 둘이 항상 같다(EquipmentState.homeLocation 참조). */
+    homeLocation?: string;
+    /** 자원 속성 — 표준 `EquipmentProperty`(§ResourceProperty). */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: string[];
     /** 교대(가동시간) — 지정 시 이 시간대에만 배정된다. 미지정=24시간 가용. */
     window?: {
         startHour: number;
@@ -106,9 +124,9 @@ export interface FlowTask {
     appliedSetupMs?: number;
     /**
      * 작업 의도(씬 3 직교의도 정렬 · ISA-95 이동 vs 변환). 기본 'transport'.
-     *   transport: mover 가 item 을 fromNode→toNode 운반(완료 시 자원 위치 이동 + 이동 모션).
-     *   process:   노드에서 item 변환(자원=정지 설비 — 위치 불변, 모션 없음). 가공을 거리-0 운반으로 위장 안 함.
-     *   dwell:     노드에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
+     *   transport: eq 가 item 을 fromNode→toNode 운반(완료 시 자원 위치 이동 + 이동 모션).
+     *   process:   자리에서 item 변환(자원=정지 설비 — 위치 불변, 모션 없음). 가공을 거리-0 운반으로 위장 안 함.
+     *   dwell:     자리에서 시간만 소비(무자원 체류·큐어링 — 즉시 진행, 자원 불요).
      */
     intent?: 'transport' | 'process' | 'dwell';
 }
@@ -138,19 +156,19 @@ interface Rng {
     state: number;
 }
 /**
- * 주목신호 계산(순수) — State 스냅샷(movers/nodes/orders)에서 attentions 파생.
+ * 주목신호 계산(순수) — State 스냅샷(equipment/locations/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: {
+    equipment: {
         id: string;
         status?: string;
         location?: string;
         goodCount?: number;
         scrapCount?: number;
     }[];
-    nodes: {
+    locations: {
         id: string;
         capacity?: number;
         occupancy?: number;
@@ -178,9 +196,15 @@ export interface OeeCounters {
 export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;
 export declare abstract class FlowEngine implements TwinKernel {
     tenantId: string;
-    nodes: Map<string, FlowNode>;
+    locations: Map<string, FlowLocation>;
     items: Map<string, FlowItem>;
-    movers: Map<string, FlowMover>;
+    equipment: Map<string, FlowEquipment>;
+    /** 등급 정의(표준 `<X>Class`) — 상속·유효기간 판정의 재료. 선언 안 하면 비어 있고, 소속 그대로 판정한다. */
+    protected classDefs: {
+        personnel?: ResourceClassDef[];
+        equipment?: ResourceClassDef[];
+        asset?: ResourceClassDef[];
+    };
     /** 사람 — 선언하지 않으면 빈 맵(인원 제약 없는 트윈, 기존 거동). */
     persons: Map<string, FlowPerson>;
     /** 물리 자산 — 선언하지 않으면 빈 맵(자산 제약 없는 트윈, 기존 거동). */
@@ -233,34 +257,34 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected abstract onTaskComplete(task: FlowTask): void;
     loadBoard(def: BoardDef): void;
     /**
-     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 무버 추가. loadBoard 무버 삽입과 동일 규약.
+     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
      * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
      */
-    addMover(m: {
+    addEquipment(m: {
         id: string;
         kind: string;
-        homeNode: string;
+        homeLocation: string;
         mtbfMs?: number;
         mttrMs?: number;
     }): void;
     /**
-     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·무버·노드)과
+     * 관측 상태 주입(라이브 예측용, kernel-unification P1) — 외부 관측 스냅샷(재고·설비·자리)과
      * 저널 오더(원값+라인)로 이 커널의 맵을 채운다. tick 으로 만든 게 아니라 "현재 관측된 현실"을 심어
      * 이후 fork/tick 으로 예측한다. 라이브 런타임은 여전히 projector 미러 — 이 커널은 예측용 임시본.
      * 오더는 남은 데맨드(라인별 requested-fulfilled)를 'created' 로 복원(현재 재고에서 재계획).
      * 진행 중 개별 task 의 내부 상태는 관측만으론 복원 불가 → 재계획에 맡김(정직한 한계).
      */
     hydrateObserved(snap: {
-        nodes: NodeState[];
+        locations: LocationState[];
         items: ItemState[];
-        movers: MoverState[];
+        equipment: EquipmentState[];
         persons?: PersonState[];
         assets?: AssetState[];
         tasks?: TaskState[];
         orders?: OrderState[];
     }, orders?: OrderStatusDelta[]): void;
-    /** what-if 구성 변주 — 노드 용량 변경(fork 대상). 존재하면 true. */
-    setNodeCapacity(nodeId: string, capacity: number): boolean;
+    /** what-if 구성 변주 — 자리 용량 변경(fork 대상). 존재하면 true. */
+    setLocationCapacity(locationId: string, capacity: number): boolean;
     /**
      * forecast 몬테카를로 — fork 의 RNG 만 재시드(시나리오·상태·gens·in-flight 는 보존).
      * "현재 조건 지속"을 유지한 채 **미래 확률만** 변주(도착·고장 타이밍 등) → run 마다 다른 표본.
@@ -366,12 +390,12 @@ export declare abstract class FlowEngine implements TwinKernel {
         gtin: string;
         weight: number;
     }[]): string;
-    protected nodeByType(type: string): FlowNode | undefined;
+    protected locationByType(type: string): FlowLocation | undefined;
     /**
      * process 변화 대수(EPCIS TransformationEvent · ISA-95 Material Consumed/Produced · 씬 Processable.transform).
      * inputs 소비 → outputs 생산. 입출력 arity 가 곧 대수:
      *   merge N→1(조립) · split 1→N(분해) · transform 1→1(타입변경) · loss N→0(소실) · gain 0→N(부산물·생성).
-     * 아이템 상태(소비/생산)와 노드 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
+     * 아이템 상태(소비/생산)와 자리 점유를 갱신하고 계보(TransformationEvent)를 방출한다.
      * 도메인은 이 원시만 호출 — onTaskComplete 의 소비/생산/EPCIS 손코딩을 대체.
      */
     protected transform(inputs: string[], outputs: {
@@ -429,7 +453,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     }): void;
     /**
      * containment 분해(EPCIS AggregationEvent DELETE) — 부모(용기)에서 자식들을 풀어냄.
-     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 노드 배치 + occupancy + ObjectEvent ADD).
+     * materialize 지정 시 자식이 독립 아이템으로 등장(materialize: 자리 배치 + occupancy + ObjectEvent ADD).
      * 미지정 시 이벤트만.
      */
     protected disaggregate(parent: string, children: string[], opts: {
@@ -442,10 +466,10 @@ export declare abstract class FlowEngine implements TwinKernel {
     }): void;
     /** 품질 보고(OEE Quality) — 도메인이 완료 시 자원별 양품/불량 1건 계상(예: 용접 수율). */
     protected recordOutput(moverId: string | null, good: boolean): void;
-    /** 무버 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
+    /** 설비 OEE(스냅샷 파생) — Availability×Performance×Quality. planned = 설비 존재 sim 시간(clockMs). */
     private oeeOf;
-    /** 정책에 넘길 특정 타입 노드의 관측 뷰 — 예약(그 노드로 향하는 in-flight task) 포함. */
-    protected slotViews(nodeType: string): SlotView[];
+    /** 정책에 넘길 특정 타입 자리의 관측 뷰 — 예약(그 자리로 향하는 in-flight task) 포함. */
+    protected slotViews(locationType: string): SlotView[];
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
     /**
@@ -461,7 +485,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     protected emitPerson(p: FlowPerson): void;
     /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
      *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
-    protected emitMover(m: FlowMover, motion?: MoverMotion): void;
+    protected emitEquipment(m: FlowEquipment, motion?: EquipmentMotion): void;
     /** 오더 델타 — **라인까지 싣는다.** 라인이 빠지면 미러가 남은 데맨드를 라인별로 재계획할 수 없다. */
     protected emitOrder(o: FlowOrder): void;
     /**
@@ -529,7 +553,7 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     private stationFull;
     /** 교대 밖인가 — 자원이 지금 일하지 않는 이유 중 고장·계획정지와 구별되는 세 번째. */
-    protected offShift(m: FlowMover): boolean;
+    protected offShift(m: FlowEquipment): boolean;
     /** 시뮬 시각의 시(0..23) — 운영시간·시간대 배율의 기준. */
     protected hourOfDay(): number;
     /**
@@ -541,9 +565,9 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 지수분포 표본(고장/수리 간격) — mean 을 평균으로 하는 무기억 프로세스. */
     private sampleExp;
     /**
-     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 무버만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
+     * 확률적 설비 고장(MTBF/MTTR) — mtbf 지정 설비만 참여(미지정=고장 없음, rng 무소비 → byte-identical).
      * up: nextFailure 도래 시 down(수리까지 repairUntil). down: downMs 누적, repair 도래 시 up(다음 고장 예약).
-     * down 중 무버는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
+     * down 중 설비는 배정 불가 + 진행중 task 동결(processTasks 가 skip) → OEE Availability 손실.
      */
     private processFailures;
     /**