@operato/twin-kernel 0.5.0 → 0.6.1

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;
@@ -1396,7 +1396,7 @@ export interface BoardDef {
      *
      * ── 왜 이제야 선언하나 (2026-08-08) ──────────────────────────────────────────
      * 이 자리는 **이미 쓰이고 있었다.** 마스터 인제스트가 `board.operations` 로 통과시키고 호스트가
-     * `applyOperations` 로 커널에 싣는다. 그런데 `BoardDef` 는 그것을 말한 적이 없다.
+     * `applyOperations` 로 커널에 싣는다. 그런데 `TwinModelDef` 는 그것을 말한 적이 없다.
      *
      * 바로 위 `productionSpec` 이 겪은 것과 **같은 일**이다 — "계약에 없으니 아무도 이 자리를 발견할
      * 수 없었다. 타입이 말해 주지 않는 필드는 없는 필드다." 그때 배운 것을 여기 적용한다.
@@ -1421,8 +1421,28 @@ export interface ProductionSpec {
     /** 쓸 레시피 키(미지정 시 첫 레시피) — 직렬 생산 경로(MES)만 쓴다. */
     recipeKey?: string;
 }
+/**
+ * 공장을 갈아탄 결과 — **몇 개가 늘고 몇 개가 사라졌나.**
+ *
+ * 돌려주지 않으면 조용히 사라진다. 자리 하나가 없어진 것을 사용자가 화면의 수를 세어 눈치채기를
+ * 기대할 수는 없다(특히 자리가 수천인 현장에서). 그래서 갈아타기는 **말없이 성공하지 않는다.**
+ */
+export interface StructureShift {
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}
 export interface TwinKernel {
-    loadBoard(def: BoardDef): void;
+    loadTwinModel(def: TwinModelDef): void;
+    /**
+     * 돌면서 공장을 갈아탄다 — 관측 구동(미러)에서만. 시뮬레이션은 거절한다(멈추고 다시 세운다).
+     * 관측으로 알게 된 자리는 새 선언에 없어도 남고, 선언에서 사라진 자원은 버리되 수를 돌려준다.
+     */
+    adoptStructure(def: TwinModelDef): StructureShift;
+    /** 이 커널이 관측으로 구동됨을 선언한다 — 첫 이벤트가 오기 전에도 그렇다. */
+    observe(): void;
     getSnapshot(): StateSnapshot;
     onEvent(handler: EventHandler): Unsubscribe;
     dispatch(cmd: Command): CommandAck;

package/dist/domain-catalog.d.ts

@@ -30,7 +30,7 @@ export interface DomainProfileInfo {
 export declare const DOMAIN_CATALOG: Record<DomainSystem, DomainProfileInfo>;
 export interface TwinAxisInfo {
     /**
-     * 축의 이름 — 화면·관계 선언이 쓰는 키. 최상위 축은 `BoardDef` 의 키 **그대로**다
+     * 축의 이름 — 화면·관계 선언이 쓰는 키. 최상위 축은 `TwinModelDef` 의 키 **그대로**다
      * (저장·계약의 이름과 갈라지면 그 순간 방언이 생긴다).
      */
     axis: string;

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, StructureShift } from './contract.ts';
 import { type ProjectedState } from './state-projector.ts';
 export declare class EventJournal {
     private events;
@@ -14,20 +14,20 @@ 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[];
 }
-/** 구조가 바뀐 지점마다 무엇이 사라졌는지. 조용히 넘어가지 않는다. */
-export interface StructureShift {
+/**
+ * 구조가 바뀐 지점마다 무엇이 사라졌는지. 조용히 넘어가지 않는다.
+ *
+ * 갈아타기의 결과 자체는 `StructureShift`(계약) 한 벌이고, 재생은 거기에 **몇 번째 마디였나**만
+ * 더한다 — 두 벌로 두면 한쪽에 필드가 늘어날 때 다른 쪽이 조용히 뒤처진다.
+ */
+export interface SegmentShift extends StructureShift {
     index: number;
-    locationsAdded: number;
-    locationsDropped: number;
-    equipmentDropped: number;
-    personsDropped: number;
-    assetsDropped: number;
 }
 /**
  * **구조가 바뀐 이력까지 이어서 재생한다.**
@@ -43,5 +43,5 @@ export interface StructureShift {
  */
 export declare function replaySegments(segments: readonly StructureSegment[]): {
     state: ProjectedState;
-    shifts: StructureShift[];
+    shifts: SegmentShift[];
 };

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, StructureShift } 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,39 @@ 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;
+    private buildLocation;
+    private buildPerson;
+    private buildAsset;
     /**
-     * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
+     * 이 커널이 **관측으로 구동된다**고 선언한다 — 미러가 첫 이벤트를 받기 전에도 그렇다.
+     *
+     * 지금까지는 첫 `apply()` 가 이 사실을 뒤늦게 정했다. 그래서 "이 커널의 진실이 어디서 오나" 가
+     * **먼저 도착한 호출이 무엇이냐**에 달려 있었다 — 아직 아무 이벤트도 안 온 미러는 스스로를
+     * 시뮬레이션으로 여긴다. 세우는 쪽이 아는 사실이므로 세울 때 말하게 한다.
+     */
+    observe(): void;
+    /**
+     * 돌면서 공장을 갈아탄다 — **현실이 안 멈추므로 미러도 멈출 수 없다.**
+     *
+     * ── 왜 관측 구동에만 여는가 ────────────────────────────────────────────────
+     * 미러는 이미 있는 현실을 따라갈 뿐이라, 설비가 한 대 늘었다고 멈췄다 서는 것은 그 사이의
+     * 사실을 잃는 것이다(라이브에서 유실은 곧 거짓이다). 반면 **시뮬레이션은 멈춰도 된다** —
+     * 조건이 바뀐 실험은 다른 실험이고, 진행 중인 작업이 사라진 자리를 가리키게 두느니 새로
+     * 세우는 것이 옳다. 그래서 여기서 거절하는 것은 한계가 아니라 **규칙**이다.
+     *
+     * ── 무엇을 지키고 무엇을 버리는가 ──────────────────────────────────────────
+     * 판단은 관측층(`ObservedReducer.adoptStructure`)이 한다 — 관측은 지키고, 선언에서 사라진
+     * 자원은 버리되 **몇 개를 버렸는지 돌려준다.** 여기서는 그 판단을 커널 자신의 선언 표에도
+     * 그대로 옮긴다. 관측층만 갈면 사라진 설비가 커널 표에 남아 **화면이 없는 설비를 그린다.**
+     *
+     * 관측으로 알게 된 자리는 선언에 없어도 지운 뒤 다시 심는다 — 다음 스냅샷에서 관측층이
+     * 되살리므로(`settleObserved` → `hydrateObserved`), 여기서 지켜야 할 것은 **선언분**뿐이다.
+     */
+    adoptStructure(def: TwinModelDef): StructureShift;
+    private buildEquipment;
+    /**
+     * 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 커널만 생성자에서 이것을 실었고(그 시절
@@ -265,25 +265,118 @@ export class FlowEngine {
         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 });
+            this.locations.set(n.id, this.buildLocation(n));
         this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
         this.materialDefs = new Map((def.materialDefinitions ?? []).filter(d => d?.id).map(d => [d.id, d]));
         for (const p of def.persons ?? [])
-            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', taskId: null, window: p.window, ...(p.workCalendar ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}), ...effectiveOnly(p) });
+            this.persons.set(p.id, this.buildPerson(p));
         for (const a of readBoardAssets(def))
-            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', taskId: null, ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}), ...effectiveOnly(a) });
-        for (const m of readBoardEquipment(def)) {
-            const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window, ...(m.workCalendar ? { workCalendar: m.workCalendar } : {}), ...effectiveOnly(m) };
-            if (m.mtbfMs !== undefined) {
-                eq.mtbfMs = m.mtbfMs;
-                eq.mttrMs = m.mttrMs;
-                eq.nextFailureMs = this.sampleExp(m.mtbfMs);
-            }
-            this.equipment.set(m.id, eq);
+            this.assets.set(a.id, this.buildAsset(a));
+        for (const m of readBoardEquipment(def))
+            this.equipment.set(m.id, this.buildEquipment(m));
+    }
+    /*
+     * ── 선언 하나를 상태 하나로 짓는 자리 ─────────────────────────────────────
+     * 최초 적재(`loadTwinModel`)와 가동 중 교체(`adoptStructure`)가 **같은 구성을 쓴다.** 두 곳에서
+     * 따로 지으면 곧 갈라지고, 갈라진 쪽으로 들어온 자원만 필드 하나가 비는 식으로 조용히 다르다.
+     */
+    buildLocation(n) {
+        return { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, occupancy: 0, status: 'idle', parentId: n.parentId };
+    }
+    buildPerson(p) {
+        return { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', taskId: null, window: p.window, ...(p.workCalendar ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}), ...effectiveOnly(p) };
+    }
+    buildAsset(a) {
+        return { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', taskId: null, ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}), ...effectiveOnly(a) };
+    }
+    /**
+     * 이 커널이 **관측으로 구동된다**고 선언한다 — 미러가 첫 이벤트를 받기 전에도 그렇다.
+     *
+     * 지금까지는 첫 `apply()` 가 이 사실을 뒤늦게 정했다. 그래서 "이 커널의 진실이 어디서 오나" 가
+     * **먼저 도착한 호출이 무엇이냐**에 달려 있었다 — 아직 아무 이벤트도 안 온 미러는 스스로를
+     * 시뮬레이션으로 여긴다. 세우는 쪽이 아는 사실이므로 세울 때 말하게 한다.
+     */
+    observe() {
+        this.observeMode = true;
+    }
+    /**
+     * 돌면서 공장을 갈아탄다 — **현실이 안 멈추므로 미러도 멈출 수 없다.**
+     *
+     * ── 왜 관측 구동에만 여는가 ────────────────────────────────────────────────
+     * 미러는 이미 있는 현실을 따라갈 뿐이라, 설비가 한 대 늘었다고 멈췄다 서는 것은 그 사이의
+     * 사실을 잃는 것이다(라이브에서 유실은 곧 거짓이다). 반면 **시뮬레이션은 멈춰도 된다** —
+     * 조건이 바뀐 실험은 다른 실험이고, 진행 중인 작업이 사라진 자리를 가리키게 두느니 새로
+     * 세우는 것이 옳다. 그래서 여기서 거절하는 것은 한계가 아니라 **규칙**이다.
+     *
+     * ── 무엇을 지키고 무엇을 버리는가 ──────────────────────────────────────────
+     * 판단은 관측층(`ObservedReducer.adoptStructure`)이 한다 — 관측은 지키고, 선언에서 사라진
+     * 자원은 버리되 **몇 개를 버렸는지 돌려준다.** 여기서는 그 판단을 커널 자신의 선언 표에도
+     * 그대로 옮긴다. 관측층만 갈면 사라진 설비가 커널 표에 남아 **화면이 없는 설비를 그린다.**
+     *
+     * 관측으로 알게 된 자리는 선언에 없어도 지운 뒤 다시 심는다 — 다음 스냅샷에서 관측층이
+     * 되살리므로(`settleObserved` → `hydrateObserved`), 여기서 지켜야 할 것은 **선언분**뿐이다.
+     */
+    adoptStructure(def) {
+        if (!this.observeMode)
+            throw new Error('adoptStructure is for observation-driven kernels (mirrors) — a simulation cannot swap its factory mid-run; stop and re-provision instead');
+        this.boardDef = def;
+        if (def.productionSpec?.definition?.operations?.length)
+            this.loadOperations(def.productionSpec.definition.operations);
+        this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
+        this.materialDefs = new Map((def.materialDefinitions ?? []).filter(d => d?.id).map(d => [d.id, d]));
+        /* **살아남은 것은 그대로 둔다** — 다시 지으면 가동시간·양품수가 0 으로 돌아간다(OEE 가 리셋된다).
+           선언이 바뀐 트윈에서 성과 지표가 조용히 끊기는 것이 이 갈아타기의 가장 비싼 오류다. */
+        const sync = (map, declared, build) => {
+            const ids = new Set(declared.map(d => d.id));
+            let dropped = 0;
+            for (const id of [...map.keys()])
+                if (!ids.has(id)) {
+                    map.delete(id);
+                    dropped++;
+                }
+            for (const d of declared)
+                if (!map.has(d.id))
+                    map.set(d.id, build(d));
+            return dropped;
+        };
+        const declaredLocations = readBoardLocations(def);
+        const locationsBefore = this.locations.size;
+        const locationsDropped = sync(this.locations, declaredLocations, n => this.buildLocation(n));
+        const equipmentDropped = sync(this.equipment, readBoardEquipment(def), m => this.buildEquipment(m));
+        const personsDropped = sync(this.persons, def.persons ?? [], p => this.buildPerson(p));
+        const assetsDropped = sync(this.assets, readBoardAssets(def), a => this.buildAsset(a));
+        const observed = this.observer?.adoptStructure(def);
+        if (this.observer)
+            this.observedDirty = true;
+        this.revision++;
+        /*
+         * **돌려주는 수는 실제로 일어난 일이어야 한다.**
+         *
+         * 자리는 관측층의 셈을 쓴다 — 관측으로 알게 된 자리는 선언에 없어도 남으므로, 커널 표만 보면
+         * "버렸다" 고 세었다가 다음 스냅샷에서 되살아난다(그 수를 그대로 보고하면 거짓말이 된다).
+         * 관측층이 아직 없으면(첫 이벤트 전) 커널 표의 셈이 곧 사실이다.
+         *
+         * 자원은 어느 층에서나 **선언이 전부**라 셈이 같고, 화면이 그리는 것은 커널 표이므로 이쪽을 쓴다.
+         */
+        return {
+            locationsAdded: observed?.locationsAdded ?? Math.max(0, this.locations.size - locationsBefore + locationsDropped),
+            locationsDropped: observed?.locationsDropped ?? locationsDropped,
+            equipmentDropped,
+            personsDropped,
+            assetsDropped
+        };
+    }
+    buildEquipment(m) {
+        const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), status: 'idle', taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window, ...(m.workCalendar ? { workCalendar: m.workCalendar } : {}), ...effectiveOnly(m) };
+        if (m.mtbfMs !== undefined) {
+            eq.mtbfMs = m.mtbfMs;
+            eq.mttrMs = m.mttrMs;
+            eq.nextFailureMs = this.sampleExp(m.mtbfMs);
         }
+        return eq;
     }
     /**
-     * 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, StructureShift } 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,13 +91,7 @@ export declare class ObservedReducer {
      * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
      * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
      */
-    adoptStructure(board: BoardDef): {
-        locationsAdded: number;
-        locationsDropped: number;
-        equipmentDropped: number;
-        personsDropped: number;
-        assetsDropped: number;
-    };
+    adoptStructure(board: TwinModelDef): StructureShift;
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u: MasterUpdate): void;
     /**

package/dist-cjs/index.cjs

@@ -2280,26 +2280,104 @@ 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 });
+    for (const n of readBoardLocations(def)) this.locations.set(n.id, this.buildLocation(n));
     this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
     this.materialDefs = new Map((def.materialDefinitions ?? []).filter((d) => d?.id).map((d) => [d.id, d]));
-    for (const p of def.persons ?? []) this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: "idle", taskId: null, window: p.window, ...p.workCalendar ? { workCalendar: p.workCalendar } : {}, ...p.homeLocation ? { location: p.homeLocation } : {}, ...p.properties ? { properties: p.properties } : {}, ...p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}, ...effectiveOnly(p) });
-    for (const a of readBoardAssets(def)) this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: "idle", taskId: null, ...a.properties ? { properties: a.properties } : {}, ...a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}, ...effectiveOnly(a) });
-    for (const m of readBoardEquipment(def)) {
-      const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...m.properties ? { properties: m.properties } : {}, ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}, status: "idle", taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window, ...m.workCalendar ? { workCalendar: m.workCalendar } : {}, ...effectiveOnly(m) };
-      if (m.mtbfMs !== void 0) {
-        eq.mtbfMs = m.mtbfMs;
-        eq.mttrMs = m.mttrMs;
-        eq.nextFailureMs = this.sampleExp(m.mtbfMs);
+    for (const p of def.persons ?? []) this.persons.set(p.id, this.buildPerson(p));
+    for (const a of readBoardAssets(def)) this.assets.set(a.id, this.buildAsset(a));
+    for (const m of readBoardEquipment(def)) this.equipment.set(m.id, this.buildEquipment(m));
+  }
+  /*
+   * ── 선언 하나를 상태 하나로 짓는 자리 ─────────────────────────────────────
+   * 최초 적재(`loadTwinModel`)와 가동 중 교체(`adoptStructure`)가 **같은 구성을 쓴다.** 두 곳에서
+   * 따로 지으면 곧 갈라지고, 갈라진 쪽으로 들어온 자원만 필드 하나가 비는 식으로 조용히 다르다.
+   */
+  buildLocation(n) {
+    return { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, occupancy: 0, status: "idle", parentId: n.parentId };
+  }
+  buildPerson(p) {
+    return { id: p.id, personnelClassIds: p.personnelClassIds, status: "idle", taskId: null, window: p.window, ...p.workCalendar ? { workCalendar: p.workCalendar } : {}, ...p.homeLocation ? { location: p.homeLocation } : {}, ...p.properties ? { properties: p.properties } : {}, ...p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}, ...effectiveOnly(p) };
+  }
+  buildAsset(a) {
+    return { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: "idle", taskId: null, ...a.properties ? { properties: a.properties } : {}, ...a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}, ...effectiveOnly(a) };
+  }
+  /**
+   * 이 커널이 **관측으로 구동된다**고 선언한다 — 미러가 첫 이벤트를 받기 전에도 그렇다.
+   *
+   * 지금까지는 첫 `apply()` 가 이 사실을 뒤늦게 정했다. 그래서 "이 커널의 진실이 어디서 오나" 가
+   * **먼저 도착한 호출이 무엇이냐**에 달려 있었다 — 아직 아무 이벤트도 안 온 미러는 스스로를
+   * 시뮬레이션으로 여긴다. 세우는 쪽이 아는 사실이므로 세울 때 말하게 한다.
+   */
+  observe() {
+    this.observeMode = true;
+  }
+  /**
+   * 돌면서 공장을 갈아탄다 — **현실이 안 멈추므로 미러도 멈출 수 없다.**
+   *
+   * ── 왜 관측 구동에만 여는가 ────────────────────────────────────────────────
+   * 미러는 이미 있는 현실을 따라갈 뿐이라, 설비가 한 대 늘었다고 멈췄다 서는 것은 그 사이의
+   * 사실을 잃는 것이다(라이브에서 유실은 곧 거짓이다). 반면 **시뮬레이션은 멈춰도 된다** —
+   * 조건이 바뀐 실험은 다른 실험이고, 진행 중인 작업이 사라진 자리를 가리키게 두느니 새로
+   * 세우는 것이 옳다. 그래서 여기서 거절하는 것은 한계가 아니라 **규칙**이다.
+   *
+   * ── 무엇을 지키고 무엇을 버리는가 ──────────────────────────────────────────
+   * 판단은 관측층(`ObservedReducer.adoptStructure`)이 한다 — 관측은 지키고, 선언에서 사라진
+   * 자원은 버리되 **몇 개를 버렸는지 돌려준다.** 여기서는 그 판단을 커널 자신의 선언 표에도
+   * 그대로 옮긴다. 관측층만 갈면 사라진 설비가 커널 표에 남아 **화면이 없는 설비를 그린다.**
+   *
+   * 관측으로 알게 된 자리는 선언에 없어도 지운 뒤 다시 심는다 — 다음 스냅샷에서 관측층이
+   * 되살리므로(`settleObserved` → `hydrateObserved`), 여기서 지켜야 할 것은 **선언분**뿐이다.
+   */
+  adoptStructure(def) {
+    if (!this.observeMode)
+      throw new Error(
+        "adoptStructure is for observation-driven kernels (mirrors) \u2014 a simulation cannot swap its factory mid-run; stop and re-provision instead"
+      );
+    this.boardDef = def;
+    if (def.productionSpec?.definition?.operations?.length) this.loadOperations(def.productionSpec.definition.operations);
+    this.classDefs = { personnel: def.personnelClasses, equipment: def.equipmentClasses, asset: def.assetClasses, material: def.materialClasses };
+    this.materialDefs = new Map((def.materialDefinitions ?? []).filter((d) => d?.id).map((d) => [d.id, d]));
+    const sync = (map, declared, build) => {
+      const ids = new Set(declared.map((d) => d.id));
+      let dropped = 0;
+      for (const id of [...map.keys()]) if (!ids.has(id)) {
+        map.delete(id);
+        dropped++;
       }
-      this.equipment.set(m.id, eq);
+      for (const d of declared) if (!map.has(d.id)) map.set(d.id, build(d));
+      return dropped;
+    };
+    const declaredLocations = readBoardLocations(def);
+    const locationsBefore = this.locations.size;
+    const locationsDropped = sync(this.locations, declaredLocations, (n) => this.buildLocation(n));
+    const equipmentDropped = sync(this.equipment, readBoardEquipment(def), (m) => this.buildEquipment(m));
+    const personsDropped = sync(this.persons, def.persons ?? [], (p) => this.buildPerson(p));
+    const assetsDropped = sync(this.assets, readBoardAssets(def), (a) => this.buildAsset(a));
+    const observed = this.observer?.adoptStructure(def);
+    if (this.observer) this.observedDirty = true;
+    this.revision++;
+    return {
+      locationsAdded: observed?.locationsAdded ?? Math.max(0, this.locations.size - locationsBefore + locationsDropped),
+      locationsDropped: observed?.locationsDropped ?? locationsDropped,
+      equipmentDropped,
+      personsDropped,
+      assetsDropped
+    };
+  }
+  buildEquipment(m) {
+    const eq = { id: m.id, kind: m.kind, location: m.homeLocation, homeLocation: m.homeLocation, ...m.properties ? { properties: m.properties } : {}, ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}, status: "idle", taskId: null, runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, window: m.window, ...m.workCalendar ? { workCalendar: m.workCalendar } : {}, ...effectiveOnly(m) };
+    if (m.mtbfMs !== void 0) {
+      eq.mtbfMs = m.mtbfMs;
+      eq.mttrMs = m.mttrMs;
+      eq.nextFailureMs = this.sampleExp(m.mtbfMs);
     }
+    return eq;
   }
   /**
-   * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadBoard 설비 삽입과 동일 규약.
+   * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
    * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.
    */
   addEquipment(m) {

package/package.json

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