@operato/twin-kernel 0.2.2 → 0.3.0

package/dist/contract.d.ts

@@ -11,18 +11,189 @@ export type TaskStatus = 'created' | 'assigned' | 'in-progress' | 'completed';
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.
  *
- * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 노드 상태 채널이
+ * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 자리 상태 채널이
  * 없어 비어 있었다. 화면은 그 값을 그대로 보여 주고 있었다 — **정보처럼 보이는데 정보가 아니었다.**
  *
  * 문턱은 병목 주목(`deriveAttentions`)이 쓰는 것과 **같다**: 90% 이상이면 임박, 100% 이상이면 포화.
  * 규칙이 둘이면 화면과 주목이 다른 말을 한다. 용량을 모르면 상태도 모른다(undefined — 꾸미지 않는다).
  */
-export declare const NODE_SATURATION_NEAR = 0.9;
-export declare function nodeStatusOf(n: {
+export declare const LOCATION_SATURATION_NEAR = 0.9;
+export declare function locationStatusOf(n: {
     occupancy?: number;
     capacity?: number;
 }): 'available' | 'near-full' | 'full' | undefined;
-export interface NodeState {
+/**
+ * 설비 계층 단계 — **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 declare const EQUIPMENT_LEVEL: readonly ["Enterprise", "Site", "Area", "ProcessCell", "Unit", "ProductionLine", "WorkCell", "ProductionUnit", "StorageZone", "StorageUnit", "WorkCenter", "WorkUnit", "EquipmentModule", "ControlModule", "Other"];
+export type EquipmentLevel = (typeof EQUIPMENT_LEVEL)[number];
+/** 표준 열거값인지 — 상류에서 들어온 값을 조용히 통과시키지 않고 확인하는 용도. */
+export declare function isEquipmentLevel(v: unknown): v is EquipmentLevel;
+/**
+ * 계층 질의 — **사슬을 걷는 규칙 한 벌.**
+ *
+ * 왜 커널이 내는가: 자리는 자리 밑에 들 수 있고(라인 ⊃ 스테이션), 설비는 자리에 붙박인다. 그래서
+ * "이 라인의 처리량" 같은 질문은 사슬을 걷어야 답이 나온다. 소비처(화면·집계·AI)가 각자 걷게 두면
+ * 규칙이 여러 벌이 되고, 한 홉만 보는 코드가 하나 남는 순간 **그 아래가 집계에서 조용히 빠진다.**
+ *
+ * `locationStatusOf` 와 같은 자리에 두는 이유도 같다 — 파생은 한 곳에서만 한다.
+ */
+export interface Hierarchy {
+    /** 바로 아래 자리들. */
+    childrenOf(locationId: string): string[];
+    /** 상위 사슬 — 가까운 쪽부터. 마지막 원소는 자리가 아닐 수 있다(=구역). 자기 자신은 넣지 않는다. */
+    ancestorsOf(locationId: string): string[];
+    /**
+     * 사슬의 끝 — **자리가 아닌 최상위 소속(=구역).** 자리만으로 사슬이 끝나면(구역 미선언) `undefined`.
+     * 모름을 빈 문자열이나 자기 id 로 **꾸미지 않는다** — 구역 미상은 구역 0 이 아니다.
+     */
+    rollupOf(locationId: string): string | undefined;
+    /** 아래 전부(재귀). 자기 자신은 넣지 않는다. */
+    descendantsOf(locationId: string): string[];
+    /**
+     * 사슬을 올라가다 만나는 **그 단계의 가장 가까운 상위 자리** — "이 스테이션이 속한 라인" 은
+     * `ancestorOfLevel(st, 'ProductionLine')`. **이것이 표준 축이고 기본 질의다.**
+     *
+     * 없으면 `undefined` — 그 현장에 그 단계가 선언되지 않았다는 뜻이고, 아무 자리도 대신 내놓지 않는다.
+     */
+    ancestorOfLevel(locationId: string, level: EquipmentLevel): string | undefined;
+    /**
+     * 같은 질의를 **현장의 낱말**(`type`)로 — 단계를 아직 선언하지 않은 데이터를 위한 보조 경로다.
+     *
+     * 표준 단계가 있으면 `ancestorOfLevel` 을 쓴다. 이것은 마스터가 `level` 을 실어 주기 전까지의
+     * 임시 다리이고, 여기에 새 어휘를 쌓지 않는다(쌓으면 그게 방언이 된다).
+     */
+    ancestorOfType(locationId: string, type: string): string | undefined;
+    /**
+     * 이 자리에 **붙박인** 설비(`homeLocation` 기준) — 워크센터가 자리이자 설비인 경우의 이음.
+     * `deep` 이면 아래 자리들의 설비까지("이 라인의 설비").
+     *
+     * 지금 그 자리에 **와 있는** 설비(`location` 기준)와 다른 질문이다 — 지게차는 어디에나 와 있을 수
+     * 있지만 어디에도 붙박이지 않는다. 둘을 한 함수로 뭉개면 소속과 현재 위치가 섞인다.
+     */
+    equipmentOf(locationId: string, opts?: {
+        deep?: boolean;
+    }): string[];
+}
+/**
+ * 계층 색인을 만든다. **순환은 만들 때 잡고 던진다** — 렌더 도중에 터지는 대신 여기서 한 번에.
+ * 순환을 조용히 잘라 내면 롤업이 틀린 값을 내고, 그건 이 함수가 막으려는 바로 그 실패다.
+ */
+export declare function hierarchyOf(s: {
+    locations: readonly {
+        id: string;
+        type?: string;
+        level?: EquipmentLevel;
+        parentId?: string;
+    }[];
+    equipment?: readonly {
+        id: string;
+        homeLocation?: string;
+    }[];
+}): Hierarchy;
+/**
+ * 자원 속성 — **ISA-95 가 세 자원에 똑같이 정의한 한 모양.**
+ *
+ * 1차 출처(B2MML v0701): `EquipmentPropertyType`(B2MML-Equipment.xsd) ·
+ * `PersonPropertyType`(B2MML-Personnel.xsd) · `PhysicalAssetPropertyType`(B2MML-PhysicalAsset.xsd).
+ * 세 타입의 요소가 동일하다 — `ID` · `Description?` · `Value(ValueType)` · `<X>PropertyChild`(재귀) ·
+ * `<X>ClassPropertyID`. 그래서 우리도 **자원마다 다른 모양을 만들지 않는다**(자원별 속성 타입 셋을
+ * 두면 그게 방언이 된다).
+ *
+ * `value`·`dataType`·`uom` 은 표준 `ValueType` 의 `ValueString`·`DataType`·`UnitOfMeasure` 다.
+ * 값을 **문자열로 싣는 것도 표준 그대로**다 — 단위와 데이터형이 값 옆에 붙어 있어야 소비처가
+ * "3" 이 초속 3m 인지 시속 3km 인지 알 수 있다(단위 없는 숫자는 거절한다는 규율의 근거).
+ *
+ * 왜 이제 계약에 넣는가: 지금까지 설비 속성(`speed`)이 **계약 밖으로 흘러** 마스터에서 호스트
+ * 추정기까지 `any` 로 전달됐다. 자원에 붙는 사실이 계약에 자리가 없으면 소비처마다 다르게 읽는다.
+ */
+export interface ResourceProperty {
+    /** 속성 식별자 — 표준 `ID`. 어휘는 표준이 정하지 않으므로 우리가 한 곳에서 정한다(`EQUIPMENT_PROPERTY`). */
+    id: string;
+    description?: string;
+    /** 표준 `Value.ValueString`. 값의 표기는 문자열이고, 뜻은 `dataType`·`uom` 이 정한다. */
+    value?: string;
+    /** 표준 `Value.DataType` — 예: `xs:double`. 미지정이면 소비처가 형을 짐작하지 않는다. */
+    dataType?: string;
+    /** 표준 `Value.UnitOfMeasure` — UN/CEFACT 공통코드(예: `MTS`·`KMH`). **단위 없는 물리량은 쓰지 않는다.** */
+    uom?: string;
+    /** 하위 속성 — 표준 `<X>PropertyChild`(재귀). 구조화된 속성(예: 정격/실측 묶음)을 잃지 않기 위해. */
+    children?: ResourceProperty[];
+    /** 이 개체 속성이 구체화하는 **등급 속성** — 표준 `<X>ClassPropertyID`. */
+    classPropertyId?: string;
+}
+/**
+ * 자격·적격을 **검증한 시험 명세**들 — 표준 `TestSpecificationID`(`maxOccurs="unbounded"`).
+ *
+ * 1차 출처에서 **자원 타입 9개 중 9개**에 있다(`PersonType`·`PersonnelClassType`·`EquipmentType`·
+ * `EquipmentClassType`·`PhysicalAssetType`·`PhysicalAssetClassType`·`MaterialLotType`·
+ * `MaterialDefinitionType`·`MaterialClassType`). **`OperationalLocationType` 에만 없다** — 자리는
+ * 시험 대상이 아니기 때문이다. 그 비대칭이 표준의 판단이므로 우리도 자리에 넣지 않는다.
+ *
+ * 이 필드는 **참조만** 한다. 시험 명세 자체(`B2MML-OperationsTest.xsd`)와 시험 결과는 아직 모델에 없다
+ * (커버리지 ⬜). 그래서 이 값으로 **검증했다고 주장하지 않는다** — 상류가 "이 자격은 이 시험으로
+ * 검증됐다" 고 말해 줄 때 그 사실이 **들어올 자리**를 여는 것이 이 필드의 일이다.
+ * 자리가 없으면 사실이 들어오지 못한다.
+ */
+export type TestSpecificationRefs = string[];
+/**
+ * 자원 **등급 정의** — ISA-95 가 세 자원에 똑같이 정의한 한 모양.
+ *
+ * 1차 출처(B2MML v0701): `PersonnelClassType`(B2MML-Personnel.xsd) · `EquipmentClassType`(B2MML-Equipment.xsd)
+ * · `PhysicalAssetClassType`(B2MML-PhysicalAsset.xsd). 세 타입이 공통으로 갖는 것 —
+ * `ID` · `Description?` · `EffectiveStartDate?` · `EffectiveEndDate?` · **`<X>ClassBaseID`(복수)** ·
+ * `<X>ClassProperty`(복수) · `TestSpecificationID`(복수).
+ *
+ * **정의와 참조는 이름이 다르다.** 표준은 정의를 `<X>Class` 로, 참조를 `<X>ClassID` 로 부른다. 그래서
+ * 우리도 정의 목록은 `personnelClasses`, 개체의 소속은 `personnelClassIds` 다 — 한 낱말로 두면
+ * "이 필드가 정의인가 참조인가" 를 매번 물어야 한다.
+ *
+ * **상속이 왜 필요한가**: 요구가 "생산직 2명" 인데 현장에 있는 사람이 "용접 자격자" 라면, 상속이 없으면
+ * 그 사람은 요구를 만족하지 못한다. 표준이 `ClassBaseID` 를 복수로 둔 이유가 이것이고(다중 상속),
+ * 우리는 소속을 **상속을 타고 닫아** 판정한다(`classClosure`).
+ */
+export interface ResourceClassDef {
+    id: string;
+    description?: string;
+    /** 상위 등급들 — 표준 `<X>ClassBaseID`(복수). 순환은 `classClosure` 가 끊는다. */
+    baseIds?: string[];
+    /** 등급 속성 — 표준 `<X>ClassProperty`. 개체 속성이 `classPropertyId` 로 이것을 구체화한다. */
+    properties?: ResourceProperty[];
+    /** 이 등급의 적격을 정하는 시험 명세들 — 표준 `TestSpecificationID`. */
+    testSpecificationIds?: TestSpecificationRefs;
+    /**
+     * 유효 기간 — 표준 `EffectiveStartDate` / `EffectiveEndDate`(ISO 시각).
+     *
+     * **표준은 날짜만 정하고 "밖이면 어떻게 되는가" 는 정하지 않는다.** 그 판단은 소비처 몫이므로
+     * 우리가 정한다: **기간 밖이면 그 등급으로 자격이 성립하지 않는다**(만료된 자격으로 배정되지 않는다).
+     * 우리가 정한 규칙이라는 사실을 여기 밝힌다.
+     */
+    effectiveStart?: ISOTime;
+    effectiveEnd?: ISOTime;
+}
+/**
+ * 등급 소속을 **상속을 타고 닫는다** — "이 개체가 이 등급으로 통하는가".
+ *
+ * 순환은 방문 집합으로 끊는다(잘못된 마스터가 무한 루프를 만들지 않게). 등급 정의가 없으면 소속
+ * 그대로만 본다 — 정의를 요구하지 않는다(정의를 싣지 않은 트윈이 그대로 돌아야 한다).
+ *
+ * `at` 를 주면 **유효 기간 밖의 등급은 제외**한다. 안 주면 기간을 보지 않는다(모르면 판단하지 않는다).
+ */
+export declare function classClosure(directIds: readonly string[] | undefined, defs: readonly ResourceClassDef[] | undefined, at?: ISOTime): Set<string>;
+export interface LocationState {
     id: string;
     type: string;
     /**
@@ -43,8 +214,32 @@ export interface NodeState {
      */
     parallelism?: number;
     occupancy: number;
-    /** 포화도 파생 상태 — `nodeStatusOf` 가 낸다(두 구동이 같은 함수를 쓴다). 용량 미상이면 없다. */
+    /** 포화도 파생 상태 — `locationStatusOf` 가 낸다(두 구동이 같은 함수를 쓴다). 용량 미상이면 없다. */
     status?: string;
+    /**
+     * **ISA-95 설비 계층 단계** — `ProductionLine`·`StorageZone`·`WorkCenter` 등(`EQUIPMENT_LEVEL`).
+     *
+     * `type` 과 다른 축이다: `type` 은 현장의 낱말(`paint-booth`·`cut-station`)이고, 이것은 **표준이
+     * 정한 역할**이다. 둘을 겹쳐 두는 이유 — 연동 상대와는 표준 축으로 말하고, 화면에는 현장 낱말을
+     * 보여줘야 한다. 하나만 두면 한쪽을 잃는다.
+     *
+     * 미지정이면 그 자리의 표준 역할을 **아직 모른다**는 뜻이다. 짐작해 채우지 않는다.
+     */
+    level?: EquipmentLevel;
+    /**
+     * **상위 자리** — 주목 롤업·구역 매핑용(마스터 계층에서 유래).
+     *
+     * 가리키는 대상은 **두 가지 중 하나**이고, 둘은 조회로 구별된다(`locations` 에 그 id 가 있는지):
+     *  - **다른 자리** — 중간 단(라인·셀·존). 계층은 여기서 깊어진다.
+     *  - **자리가 아닌 것** — 공간의 구역(area). 사슬의 끝이다.
+     *
+     * 왜 깊이가 필요한가: 최종조립 16개 스테이션이 두 라인에 속하는데 중간 단이 없으면 전부 구역에
+     * 평평하게 붙고, **"라인 1의 처리량"을 물을 방법이 없다.** 현장은 라인 단위로 관리되는데 모델에
+     * 그 단이 없으면 관리 단위와 모델이 어긋난다.
+     *
+     * **사슬은 직접 걷지 말 것** — `ancestorsOf`·`rollupOf`·`descendantsOf` 를 쓴다. 한 홉만 보는 코드는
+     * 중간 단이 생기는 순간 그 아래 자리를 **집계에서 조용히 빠뜨린다**(정합성이 아니라 침묵이 문제다).
+     */
     parentId?: string;
     /**
      * 이 자리를 **어떻게 알게 됐는가** — `master`(원 시스템 마스터/저작이 말해 준 자리) ·
@@ -96,9 +291,9 @@ export interface ItemState {
  * 운영·키네마틱 모션 — State 이원 모델의 "연속" 절반.
  * 백엔드는 이동 시작 시 이 값(from/to/duration)만 방출하고, UI 는 progress 를
  * 로컬 프레임레이트로 보간한다(매 tick 통신 아님). 좌표는 커널 토폴로지 수준이 아니라
- * 보드 바인딩에서 노드→좌표로 해석. 상세: design/simulation/execution-model.md §4·§5
+ * 보드 바인딩에서 자리→좌표로 해석. 상세: design/simulation/execution-model.md §4·§5
  */
-export interface MoverMotion {
+export interface EquipmentMotion {
     fromNode: string;
     toNode: string;
     startedAtSimMs: number;
@@ -124,13 +319,26 @@ export interface OeeMetrics {
     goodCount: number;
     scrapCount: number;
 }
-export interface MoverState {
+export interface EquipmentState {
     id: string;
     kind: string;
+    /** **지금 어디에 있나.** 운반 작업이 끝나면 도착 자리로 옮겨진다(제자리 작업은 안 움직인다). */
     location?: string;
+    /**
+     * **어디에 속하나** — 붙박인 자리(마스터의 `homeLocationId`). `location` 과 다른 질문이다.
+     *
+     * 이 필드가 **고정 설비와 이동 설비를 가른다** — 새 타입 플래그 없이:
+     *  - 도장기·용접로봇은 평생 그 자리에 있다 → `location === homeLocation` 가 항상 성립.
+     *  - 지게차·호슬러는 돌아다닌다 → 둘이 갈린다. 그래도 소속은 `homeLocation` 하나로 안정적이다.
+     *
+     * 그래서 "이 라인의 설비 가동률" 은 `homeLocation` 로 묻고(소속), "지금 이 자리에 누가 와 있나" 는
+     * `location` 으로 묻는다. 예전에는 소속이 적재 시점에 `location` 초기값으로 소비되고 **버려졌다** —
+     * 그래서 이동 설비가 한 번 움직이면 원래 소속을 아무도 알 수 없었다.
+     */
+    homeLocation?: string;
     status: string;
     taskId?: string;
-    motion?: MoverMotion;
+    motion?: EquipmentMotion;
     oee?: OeeMetrics;
     held?: boolean;
     /**
@@ -138,13 +346,20 @@ export interface MoverState {
      * 셋을 뭉개면 "왜 안 움직이나" 에 답할 수 없다(고쳐야 하나·풀어야 하나·기다려야 하나).
      */
     offShift?: boolean;
-    /** 이 자원을 어떻게 알게 됐는가 — NodeState.origin 과 같은 뜻(성장 정책을 한 규칙으로 선언). */
+    /** 이 자원을 어떻게 알게 됐는가 — LocationState.origin 과 같은 뜻(성장 정책을 한 규칙으로 선언). */
     origin?: 'master' | 'observed';
+    /**
+     * 자원 속성 — 표준 `EquipmentProperty`. 속도(`EQUIPMENT_PROPERTY.speed`)처럼 **소비처가 읽는 사실**이
+     * 여기 실린다. 지금까지 계약 밖으로 흘러 호스트까지 `any` 로 전달됐다(§ResourceProperty).
+     */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `Equipment.TestSpecificationID`(§TestSpecificationRefs). */
+    testSpecificationIds?: TestSpecificationRefs;
 }
 /**
  * 사람 — **ISA-95 `Person`.** 설비와 다른 자원 종류다.
  *
- * 왜 무버(설비)로 뭉개지 않는가: 사람은 고장 나지 않고(MTBF), 설비종합효율로 평가하지 않으며,
+ * 왜 설비(설비)로 뭉개지 않는가: 사람은 고장 나지 않고(MTBF), 설비종합효율로 평가하지 않으며,
  * **등급(자격)과 교대로 산다.** 같은 그릇에 담으면 설비의 어휘(고장·수리·OEE)가 사람에게 붙고
  * 사람의 어휘(등급·교대·투입 인원)가 설비에 붙는다 — 둘 다 거짓이 된다.
  *
@@ -153,13 +368,34 @@ export interface MoverState {
  */
 export interface PersonState {
     id: string;
-    /** 소속 등급 — ISA-95 `PersonnelClassID`. 배정은 개인이 아니라 **등급으로 요구**된다. */
-    personnelClass?: string;
+    /**
+     * 소속 등급들 — **ISA-95 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**(B2MML-Personnel.xsd).
+     *
+     * **복수인 것이 표준이고, 그것이 표준의 자격 표현이다.** 한 사람이 용접 자격과 지게차 자격을 함께
+     * 갖는다 — 예전에는 이 필드가 문자열 하나여서 그 사람을 두 작업 중 하나에만 배정할 수 있었다
+     * (자격 하나를 고르면 나머지 자격이 사라지는 모델).
+     *
+     * 배정은 개인 지목이 아니라 **등급으로 요구**되고(`OpPersonnelSpecification` = ClassID + Quantity),
+     * 사람이 그 등급 중 하나를 **포함**하면 자격이 성립한다.
+     */
+    personnelClassIds?: string[];
     /** 'idle' | 'busy'. 고장(down)이 없다 — 사람은 그렇게 모델링하지 않는다. */
     status: string;
     taskId?: string;
-    /** 교대 밖 — 자원(MoverState.offShift)과 같은 뜻. */
+    /** 교대 밖 — 자원(EquipmentState.offShift)과 같은 뜻. */
     offShift?: boolean;
+    /**
+     * 지금 어디에 있나 — **표준 `Person.OperationalLocation`**(B2MML-Personnel.xsd, `ResourceLocationType`).
+     *
+     * 표준은 사람에게 위치를 준다. 우리 모델에는 없어서 "이 라인에 몇 명 있나" 를 물을 수 없었다.
+     * 커널은 사람을 움직이지 않으므로(작업이 사람을 부른다) 이 값은 **마스터가 말해 주거나 관측으로
+     * 들어온다** — 그래서 사람 델타에도 자리가 있다(상태⊆이벤트).
+     */
+    location?: string;
+    /** 자원 속성 — 표준 `PersonProperty`. 자격증·숙련 등급 같은 사실이 여기 들어간다(§ResourceProperty). */
+    properties?: ResourceProperty[];
+    /** 자격을 검증한 시험 명세들 — 표준 `Person.TestSpecificationID`(§TestSpecificationRefs). */
+    testSpecificationIds?: TestSpecificationRefs;
 }
 /**
  * 물리 자산 — **ISA-95 `PhysicalAsset`, GS1 `GRAI`(반복사용 자산).**
@@ -174,7 +410,12 @@ export interface PersonState {
 export interface AssetState {
     id: string;
     /** 자산 등급 — pallet · rack · bin · trailer 등. 도메인 소유(코어는 강제하지 않는다). */
-    assetClass?: string;
+    /**
+     * 속한 등급들 — **표준 `PhysicalAsset.PhysicalAssetClassID`, `maxOccurs="unbounded"`.**
+     * 인원과 같은 이유로 복수다(팔레트가 'euro-pallet' 이면서 'food-grade' 일 수 있다).
+     * 요구 쪽(`physicalAssetSpecification`)은 표준대로 등급 하나 + 수량이다.
+     */
+    assetClassIds?: string[];
     /** 지금 있는 자리. */
     location?: string;
     /** 'idle' | 'in-use'. 고장·OEE 로 평가하지 않는다(설비가 아니다). */
@@ -186,6 +427,10 @@ export interface AssetState {
      * 비어 있으면 빈 팔레트다(회수 대상이자 다음 출고의 재료).
      */
     carrying?: string;
+    /** 자원 속성 — 표준 `PhysicalAssetProperty`(§ResourceProperty). */
+    properties?: ResourceProperty[];
+    /** 적격을 검증한 시험 명세들 — 표준 `PhysicalAsset.TestSpecificationID`(§TestSpecificationRefs). */
+    testSpecificationIds?: TestSpecificationRefs;
 }
 export interface TaskState {
     id: string;
@@ -200,7 +445,7 @@ export interface TaskState {
     /**
      * 남은 시간·총 소요(ms) — 진행 중인 작업을 이어서 굴리는 데 필요(씨앗의 충실도).
      * `remainingMs` 는 **마지막 전이 시점의 값**이다. 델타는 매 tick 오지 않으므로(설계) 미러가 든 값은
-     * 그때의 것이고, 지금 값은 `startedAtSimMs` 로 보간한다 — 모션(MoverMotion)과 같은 규율.
+     * 그때의 것이고, 지금 값은 `startedAtSimMs` 로 보간한다 — 모션(EquipmentMotion)과 같은 규율.
      */
     remainingMs?: number;
     durationMs?: number;
@@ -244,7 +489,7 @@ export interface Attention {
     severity: AttentionSeverity;
     state?: AttentionState;
     anchor: {
-        nodeId?: string;
+        locationId?: string;
         moverId?: string;
         orderId?: string;
     };
@@ -252,7 +497,7 @@ export interface Attention {
     /**
      * 표현용 원시 파라미터(언어 중립). 커널은 사람이 읽는 문장을 만들지 않는다 — kind + params 만 방출하고
      * title/detail/rationale 는 표현계층(클라 i18next 템플릿)이 kind 로 키를 골라 params 를 보간해 렌더.
-     * 예: bottleneck → { nodeId, occupancy, capacity, ratioPct, saturated }.
+     * 예: bottleneck → { locationId, occupancy, capacity, ratioPct, saturated }.
      */
     params?: Record<string, string | number>;
     recommendedActions?: RecommendedAction[];
@@ -275,9 +520,17 @@ export interface RecommendedAction {
 export interface StateSnapshot {
     revision: number;
     simClockMs: number;
-    nodes: NodeState[];
+    locations: LocationState[];
     items: ItemState[];
-    movers: MoverState[];
+    /**
+     * 설비 — **ISA-95 `Equipment`.** 고정 설비(도장기·용접로봇)와 이동 설비(지게차·호슬러)를 한 그릇에
+     * 든다. 둘의 상태 모델이 같기 때문이다(고장·가동·교대·계획정지·작업 점유). 갈리는 것은 하나뿐 —
+     * 소속(`homeLocation`)과 현재 위치(`location`)가 같은지.
+     *
+     * 예전 이름은 `movers` 였다(씬의 움직임 믹스인에서 물려받은 것). 커널에는 애니메이션이 없고  (vocabulary-guard: allow — 개명 경위 서술)
+     * 도장 부스는 아무것도 옮기지 않으므로 그 이름은 거짓이었다. 표준이 이미 정한 이름을 쓴다.
+     */
+    equipment: EquipmentState[];
     /** 사람 — 등급·교대·투입 상태. 인원을 선언하지 않은 트윈에서는 빈 배열. */
     persons: PersonState[];
     /** 물리 자산(반복사용) — 선언하지 않은 트윈에서는 빈 배열. */
@@ -352,7 +605,7 @@ export interface GeneratorSpec {
     kind: string;
     /**
      * 코어 라우팅 클래스: 공급(arrival, 물건이 들어옴 → onArrival) vs 수요(order, 요청이 들어옴 → onOrder).
-     * 미지정 시 레거시 kind('outbound-order'→order, 그 외→arrival)로 추론(하위호환, 카탈로그 nodeTypes 폴백과 동형).
+     * 미지정 시 레거시 kind('outbound-order'→order, 그 외→arrival)로 추론(하위호환, 카탈로그 locationTypes 폴백과 동형).
      */
     stimulus?: 'arrival' | 'order';
     rate: RateSpec;
@@ -393,21 +646,23 @@ export declare const OP_EVENT: {
 /** 사람 상태 델타 — 배정·해제·교대 전이 시 방출. 미러가 인원 가용을 비추는 근거. */
 export interface PersonStatusDelta {
     personId: string;
-    personnelClass?: string;
+    personnelClassIds?: string[];
     status: string;
     taskId?: string;
     offShift?: boolean;
+    /** 지금 어디에 있나 — 나가지 않으면 미러가 사람의 위치를 영영 모른다(상태⊆이벤트). */
+    location?: string;
 }
 /** 물리 자산 상태 델타 — 이동·투입·적재/하역 시 방출. 미러가 자산 가용을 비추는 근거. */
 export interface AssetStatusDelta {
     assetId: string;
-    assetClass?: string;
+    assetClassIds?: string[];
     status: string;
     location?: string;
     taskId?: string;
     carrying?: string;
 }
-/** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 무버 누적값. */
+/** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 설비 누적값. */
 export interface QualityDelta {
     moverId: string;
     good: boolean;
@@ -457,9 +712,11 @@ export interface EquipmentStatusDelta {
     kind: string;
     status: string;
     location?: string;
+    /** 붙박인 자리(`EquipmentState.homeLocation`). 나가지 않으면 미러가 소속을 영영 모른다 — 상태⊆이벤트. */
+    homeLocation?: string;
     /** 지금 붙어 있는 작업 — 사람·자산 델타와 같은 자리. 없으면 미러가 작업↔자원 연결을 모른다. */
     taskId?: string;
-    motion?: MoverMotion;
+    motion?: EquipmentMotion;
 }
 /** 관측된 오더 라인(SKU 데맨드) — 실 시스템 오더는 품목 라인을 가짐. 이행 예측(남은 데맨드 재계획)에 필요. */
 export interface ObservedOrderLine {
@@ -495,9 +752,37 @@ export declare const CMD: {
 export type OperationalDelta = TaskStatusDelta | EquipmentStatusDelta | PersonStatusDelta | AssetStatusDelta | OrderStatusDelta;
 export type EventHandler = (e: CanonicalEnvelope) => void;
 export type Unsubscribe = () => void;
+/**
+ * **저장된 보드를 읽는 단 하나의 입구.**
+ *
+ * `equipment` 로 개명하기 전에 저장된 보드는 `movers` 키를 갖고 있다(개명 시점 23개 인스턴스).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 저장물을 다시 쓰지 않고 **읽을 때 흡수**한다 — 마이그레이션은 되돌리기 어렵고, 읽기 호환은 값싸다.
+ *
+ * 규율 둘:
+ *  - 이 함수를 **거치지 않고** `def.equipment` 를 직접 읽는 코드를 두지 않는다. 하나라도 남으면
+ *    그 경로에서만 옛 보드의 설비가 조용히 사라진다(빈 배열).
+ *  - **쓸 때는 새 이름만** 쓴다. 두 이름으로 쓰기 시작하면 저장물에 두 벌이 영구히 섞인다.
+ *
+ * 제거 시점: 저장된 보드가 모두 `equipment` 키로 바뀐 것이 확인되면(운영 데이터 점검 후) 이 함수는
+ * 사라진다. 그때까지 남겨 두는 이유를 여기 적어 두는 것이 주석의 일이다.
+ */
+/**
+ * **저장된 보드의 자리를 읽는 단 하나의 입구.** `readBoardEquipment` 와 같은 규율.
+ *
+ * `nodes` → `locations` 개명(2026-08-01) 전에 저장된 보드는 `nodes` 키를 갖고 있다(개명 시점 23개).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 이 함수를 거치지 않고 `def.locations` 를 직접 읽는 코드를 두지 않는다 — 하나라도 남으면 그 경로에서만
+ * 옛 보드의 자리가 조용히 사라진다(빈 배열 = 자리 없는 트윈 = 아무 일도 일어나지 않는다).
+ */
+export declare function readBoardLocations(def: BoardDef | (Record<string, unknown> & {
+    locations?: unknown;
+    nodes?: unknown;
+})): BoardDef['locations'];
+export declare function readBoardEquipment(def: BoardDef | Record<string, unknown>): BoardDef['equipment'];
+/** 저장된 보드의 반복사용 자산 — 설비와 같은 정규화를 거친다. */
+export declare function readBoardAssets(def: BoardDef | Record<string, unknown>): NonNullable<BoardDef['assets']>;
 export interface BoardDef {
-    /** parallelism = 동시 처리 수(NodeState.parallelism 참조). capacity 는 저장 용량. */
-    nodes: {
+    /** parallelism = 동시 처리 수(LocationState.parallelism 참조). capacity 는 저장 용량. */
+    locations: {
         id: string;
         type: string;
         capacity: number;
@@ -505,38 +790,55 @@ export interface BoardDef {
         parentId?: string;
     }[];
     /**
-     * 무버(설비). mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실). 미지정=고장 없음.
+     * 설비(설비). mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실). 미지정=고장 없음.
      * `window` 지정 시 그 시간대에만 일한다(교대·가동시간) — 미지정이면 24시간 가용(기존 거동).
      */
-    movers: {
+    equipment: {
         id: string;
         kind: string;
-        homeNode: string;
+        homeLocation: string;
         mtbfMs?: number;
         mttrMs?: number;
         window?: {
             startHour: number;
             endHour: number;
         };
+        properties?: ResourceProperty[];
+        testSpecificationIds?: TestSpecificationRefs;
     }[];
     /**
-     * 사람 — ISA-95 `Person`. `personnelClass` 로 등급을 밝히고, `window` 로 교대를 선언한다.
+     * 사람 — ISA-95 `Person`. `personnelClasses` 로 **속한 등급들**을 밝히고(복수가 표준), `window` 로
+     * 교대를 선언한다.
      * 선언하지 않으면 인원 제약이 없는 트윈이다(기존 거동).
      */
     persons?: {
         id: string;
-        personnelClass?: string;
+        personnelClassIds?: string[];
         window?: {
             startHour: number;
             endHour: number;
         };
+        homeLocation?: string;
+        properties?: ResourceProperty[];
+        testSpecificationIds?: TestSpecificationRefs;
     }[];
     /** 물리 자산(반복사용) — ISA-95 `PhysicalAsset` / GS1 `GRAI`. 선언하지 않으면 자산 제약이 없다. */
     assets?: {
         id: string;
-        assetClass?: string;
-        homeNode?: string;
+        assetClassIds?: string[];
+        homeLocation?: string;
+        properties?: ResourceProperty[];
+        testSpecificationIds?: TestSpecificationRefs;
     }[];
+    /**
+     * **등급 정의** — 표준 `PersonnelClass` · `EquipmentClass` · `PhysicalAssetClass`.
+     *
+     * 선언하지 않아도 트윈은 돈다(소속 문자열 그대로 판정). 선언하면 **상속과 유효기간**이 살아난다 —
+     * "생산직 2명" 요구를 "용접 자격자" 가 만족하고, 만료된 자격은 배정되지 않는다.
+     */
+    personnelClasses?: ResourceClassDef[];
+    equipmentClasses?: ResourceClassDef[];
+    assetClasses?: ResourceClassDef[];
 }
 export interface TwinKernel {
     loadBoard(def: BoardDef): void;