@operato/twin-kernel 0.2.3 → 0.4.0

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(방출 이벤트 어휘). */
@@ -139,6 +139,51 @@ export interface OperationDef {
         equipmentClass?: string;
         quantity: number;
     }[];
+    /**
+     * 필요·산출 자재 — **ISA-95 `OperationsSegment.MaterialSpecification`**(`OpMaterialSpecificationType`).
+     *
+     * ── 4대 자원 중 자재만 빠져 있었다 ────────────────────────────────────────
+     * 인원·설비·자산 셋은 공정이 "등급 + 수량" 으로 요구하는데 **자재만 그 자리가 없었다.** 그래서
+     * 트레일러 조립 공장을 모델링해도 *"차축 하나에 바퀴 둘"* 을 말할 방법이 없고, 부품이 없어서
+     * 라인이 서는 상황이 **예측에 아예 나타나지 않는다** — 자재는 현장에서 사람만큼 자주 부족하다.
+     *
+     * ── BOM 은 어디 있나 (1차 출처 확인) ─────────────────────────────────────
+     * `MaterialDefinition.AssemblyDefinition` 은 **재귀 구조**(무엇이 무엇으로 이루어지나)일 뿐
+     * **수량이 없다.** 수량은 공정 쪽 `MaterialSpecification` 이 든다(`Quantity` + `MaterialUse`).
+     * 즉 표준에서 **BOM 의 "몇 개" 는 공정의 사실**이다 — 같은 부품이라도 공정마다 소요가 다르다.
+     *
+     * `use` 는 표준 `MaterialUse` 를 소문자로 쓴다(우리 어휘 규약). 지금 커널이 소비하는 것은
+     * `consumed`(작업이 시작되려면 있어야 하고 시작 시 빠진다)뿐이고, 나머지는 **선언만 받아 둔다** —
+     * 자리가 없으면 사실이 들어오지 못한다.
+     */
+    materialSpecification?: OpMaterialSpecification[];
+}
+/**
+ * 공정 하나의 자재 명세 — **ISA-95 `OpMaterialSpecificationType`** 의 우리 부분집합.
+ *
+ * 1차 출처: `ID` · `MaterialClassID*` · `MaterialDefinitionID*` · `MaterialLotID*` · `MaterialSubLotID*` ·
+ * `Description*` · **`MaterialUse`** · `HierarchyScope` · `StorageLocation` · `SpatialDefinition` ·
+ * **`Quantity*`** · `AssemblySpecification*`(재귀) · `AssemblyType` · `AssemblyRelationship` ·
+ * `MaterialSpecificationProperty*` · `TestSpecificationID*`.
+ *
+ * 우리는 **요구를 표현하는 데 필요한 것**만 든다(인원·자산 명세와 같은 모양). 로트·하위로트 지목,
+ * 재귀 조립 명세, 저장 위치 한정은 아직 없다 — 필요해질 때 표준 이름 그대로 얹는다.
+ */
+export interface OpMaterialSpecification {
+    /** 표준 `ID` — 명세를 가리키는 이름(선택). */
+    id?: string;
+    /** 품목 등급으로 요구 — 표준 `MaterialClassID`. */
+    materialClass?: string;
+    /** 특정 품목으로 요구 — 표준 `MaterialDefinitionID`. 등급과 함께 주면 품목이 좁은 쪽이다. */
+    materialDefinition?: string;
+    /**
+     * 이 공정에서의 쓰임 — 표준 `MaterialUse`.
+     * `consumed` 없어지며 들어간다 · `produced` 만들어져 나온다 · `consumable` 쓰이지만 제품에 남지 않는다.
+     */
+    use: 'consumed' | 'produced' | 'consumable';
+    /** 수량 — 표준 `Quantity`. 단위 미지정이면 개수(EPCIS 규약과 같다). */
+    quantity: number;
+    uom?: string;
 }
 /** 라우트(오퍼레이션 시퀀스) — ISA-95 ProcessSegment 연결. */
 export interface RouteDef {
@@ -174,7 +219,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/epcis.d.ts

@@ -9,6 +9,18 @@ export declare const DISP: {
     readonly in_transit: "urn:epcglobal:cbv:disp:in_transit";
     readonly non_sellable: "urn:epcglobal:cbv:disp:non_sellable_other";
 };
+/**
+ * **자재 소비·산출의 CBV 단계** — 도메인 무관하게 코어가 쓴다.
+ *
+ * 업종별 단계(입고·피킹·출하…)는 각 프로파일이 갖지만, "자재가 들어갔다/나왔다" 는 셋 다 하는 일이라
+ * 코어에 있어야 한다. 프로파일 하나에 두면 다른 업종이 그것을 가져다 쓰면서 방언이 생긴다.
+ */
+export declare const CBV_BIZSTEP: {
+    /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
+    readonly consuming: "urn:epcglobal:cbv:bizstep:consuming";
+    /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
+    readonly commissioning: "urn:epcglobal:cbv:bizstep:commissioning";
+};
 export type EpcisEventType = 'ObjectEvent' | 'AggregationEvent' | 'TransactionEvent' | 'TransformationEvent';
 export type EpcisAction = 'ADD' | 'OBSERVE' | 'DELETE';
 /**

package/dist/epcis.js

@@ -18,6 +18,18 @@ export const DISP = {
     in_transit: 'urn:epcglobal:cbv:disp:in_transit',
     non_sellable: 'urn:epcglobal:cbv:disp:non_sellable_other' // 불량/scrap
 };
+/**
+ * **자재 소비·산출의 CBV 단계** — 도메인 무관하게 코어가 쓴다.
+ *
+ * 업종별 단계(입고·피킹·출하…)는 각 프로파일이 갖지만, "자재가 들어갔다/나왔다" 는 셋 다 하는 일이라
+ * 코어에 있어야 한다. 프로파일 하나에 두면 다른 업종이 그것을 가져다 쓰면서 방언이 생긴다.
+ */
+export const CBV_BIZSTEP = {
+    /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
+    consuming: 'urn:epcglobal:cbv:bizstep:consuming',
+    /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
+    commissioning: 'urn:epcglobal:cbv:bizstep:commissioning'
+};
 // ── GS1 EPC URI 헬퍼 (표준) ────────────────────────────────────────────────
 /** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
 export function ssccUri(companyPrefix, serial) {

package/dist/event-journal.d.ts

@@ -13,5 +13,35 @@ export declare class EventJournal {
     /** sim 시각(ISO eventTime) 이하 이벤트. */
     untilSimTime(iso: string): CanonicalEnvelope[];
 }
-/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·무버). */
+/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
 export declare function replay(board: BoardDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+/** 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디. */
+export interface StructureSegment {
+    board: BoardDef;
+    events: readonly CanonicalEnvelope[];
+}
+/** 구조가 바뀐 지점마다 무엇이 사라졌는지. 조용히 넘어가지 않는다. */
+export interface StructureShift {
+    index: number;
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}
+/**
+ * **구조가 바뀐 이력까지 이어서 재생한다.**
+ *
+ * 공장은 바뀐다. 지금까지는 구조가 바뀌면 저널을 지우는 것이 유일한 길이었다 — 안 지우면 옛 이벤트를
+ * 새 공장에 대고 접게 되어 이력이 거짓말을 하기 때문이다(도장 부스가 둘이던 시절의 사실을 여섯 개짜리
+ * 공장에 접는다). 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+ *
+ * 셋째 길이 이것이다: 마디마다 **그때의 구조**로 접고, 경계에서 구조만 갈아탄다(관측된 사실은 이어
+ * 간다). 그러면 이력이 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
+ */
+export declare function replaySegments(segments: readonly StructureSegment[]): {
+    state: ProjectedState;
+    shifts: StructureShift[];
+};

package/dist/event-journal.js

@@ -32,10 +32,36 @@ 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)
         proj.apply(e);
     return proj.snapshot();
 }
+/**
+ * **구조가 바뀐 이력까지 이어서 재생한다.**
+ *
+ * 공장은 바뀐다. 지금까지는 구조가 바뀌면 저널을 지우는 것이 유일한 길이었다 — 안 지우면 옛 이벤트를
+ * 새 공장에 대고 접게 되어 이력이 거짓말을 하기 때문이다(도장 부스가 둘이던 시절의 사실을 여섯 개짜리
+ * 공장에 접는다). 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+ *
+ * 셋째 길이 이것이다: 마디마다 **그때의 구조**로 접고, 경계에서 구조만 갈아탄다(관측된 사실은 이어
+ * 간다). 그러면 이력이 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
+ */
+export function replaySegments(segments) {
+    if (!segments.length)
+        throw new Error('재생할 마디가 없다 — 구조를 하나도 주지 않았다');
+    const proj = new StateProjector(segments[0].board);
+    const shifts = [];
+    for (let i = 0; i < segments.length; i++) {
+        /* 첫 마디는 생성자가 이미 그 구조로 섰다 — 두 번 세우면 관측 전 상태를 다시 덮는다. */
+        if (i > 0)
+            shifts.push({ index: i, ...proj.adoptStructure(segments[i].board) });
+        for (const e of segments[i].events)
+            proj.apply(e);
+    }
+    return { state: proj.snapshot(), shifts };
+}