@operato/twin-kernel 0.6.0 → 0.6.2

package/dist/contract.d.ts

@@ -874,6 +874,22 @@ export interface OrderState {
     requested?: number;
     fulfilled?: number;
     lines?: ObservedOrderLine[];
+    /**
+     * 이 오더가 **확보해 둔 물품들** — 진행 중인 할당.
+     *
+     * 이것이 상태에 없으면 **웜스타트가 잃는다.** 잃으면 되살아난 오더는 아무것도 안 잡은 것처럼
+     * 보이고, 그 오더에 딸린 진행 중 작업이 완료될 때 계보(`TransformationEvent`)가 **입력 없이**
+     * 나간다 — "무엇이 무엇으로 바뀌었나" 의 절반이 사라진다. 실제로 그렇게 되고 있었다.
+     *
+     * 씨앗이 잃은 것은 예측도 모른다 — 진행 중 자재를 안 잡은 것으로 놓고 미래를 굴리면 답이
+     * 낙관 쪽으로 치우친다(`hydrateObserved` 가 상태를 지키는 이유와 같다).
+     */
+    allocated?: string[];
+    /**
+     * 이 오더의 거래번호(작업지시·PO·SO) — 계보와 EPCIS 이벤트가 **무슨 거래로** 일어났는지 잇는 축.
+     * 이것도 상태에 없어서 되살아난 오더는 빈 문자열을 갖고, 이후 모든 이벤트의 거래번호가 빈다.
+     */
+    bizTransaction?: string;
     /** 우선순위 — 표준 `OperationsRequest.Priority`. 작은 값이 급하다. 오더 할당 순서를 정한다. */
     priority?: number;
     /** 예정 착수 — 표준 `OperationsRequest.StartTime`. */
@@ -1230,6 +1246,15 @@ export interface OrderStatusDelta {
     priority?: number;
     startTime?: ISOTime;
     endTime?: ISOTime;
+    /**
+     * 이 오더가 **확보해 둔 물품들**과 그 **거래번호** — 진행 중인 할당.
+     *
+     * 델타가 나르지 않으면 웜스타트가 잃는다. 잃으면 되살아난 오더는 아무것도 안 잡은 것처럼
+     * 보이고, 그 오더의 진행 중 작업이 완료될 때 계보(`TransformationEvent`)가 **입력 없이** 나간다 —
+     * "무엇이 무엇으로 바뀌었나" 의 절반이 사라진다. 실제로 그렇게 되고 있었다.
+     */
+    allocated?: string[];
+    bizTransaction?: string;
 }
 export declare const CMD: {
     readonly orderHold: "order.hold";
@@ -1421,8 +1446,28 @@ export interface ProductionSpec {
     /** 쓸 레시피 키(미지정 시 첫 레시피) — 직렬 생산 경로(MES)만 쓴다. */
     recipeKey?: string;
 }
+/**
+ * 공장을 갈아탄 결과 — **몇 개가 늘고 몇 개가 사라졌나.**
+ *
+ * 돌려주지 않으면 조용히 사라진다. 자리 하나가 없어진 것을 사용자가 화면의 수를 세어 눈치채기를
+ * 기대할 수는 없다(특히 자리가 수천인 현장에서). 그래서 갈아타기는 **말없이 성공하지 않는다.**
+ */
+export interface StructureShift {
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}
 export interface TwinKernel {
     loadTwinModel(def: TwinModelDef): void;
+    /**
+     * 돌면서 공장을 갈아탄다 — 관측 구동(미러)에서만. 시뮬레이션은 거절한다(멈추고 다시 세운다).
+     * 관측으로 알게 된 자리는 새 선언에 없어도 남고, 선언에서 사라진 자원은 버리되 수를 돌려준다.
+     */
+    adoptStructure(def: TwinModelDef): StructureShift;
+    /** 이 커널이 관측으로 구동됨을 선언한다 — 첫 이벤트가 오기 전에도 그렇다. */
+    observe(): void;
     getSnapshot(): StateSnapshot;
     onEvent(handler: EventHandler): Unsubscribe;
     dispatch(cmd: Command): CommandAck;

package/dist/event-journal.d.ts

@@ -1,4 +1,4 @@
-import type { TwinModelDef, 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;
@@ -20,14 +20,14 @@ export interface StructureSegment {
     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, 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 { 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';
@@ -311,6 +311,36 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     protected abstract onTaskComplete(task: FlowTask): void;
     loadTwinModel(def: TwinModelDef): void;
+    private buildLocation;
+    private buildPerson;
+    private buildAsset;
+    /**
+     * 이 커널이 **관측으로 구동된다**고 선언한다 — 미러가 첫 이벤트를 받기 전에도 그렇다.
+     *
+     * 지금까지는 첫 `apply()` 가 이 사실을 뒤늦게 정했다. 그래서 "이 커널의 진실이 어디서 오나" 가
+     * **먼저 도착한 호출이 무엇이냐**에 달려 있었다 — 아직 아무 이벤트도 안 온 미러는 스스로를
+     * 시뮬레이션으로 여긴다. 세우는 쪽이 아는 사실이므로 세울 때 말하게 한다.
+     */
+    observe(): void;
+    /**
+     * 돌면서 공장을 갈아탄다 — **현실이 안 멈추므로 미러도 멈출 수 없다.**
+     *
+     * ── 왜 관측 구동에만 여는가 ────────────────────────────────────────────────
+     * 미러는 이미 있는 현실을 따라갈 뿐이라, 설비가 한 대 늘었다고 멈췄다 서는 것은 그 사이의
+     * 사실을 잃는 것이다(라이브에서 유실은 곧 거짓이다). 반면 **시뮬레이션은 멈춰도 된다** —
+     * 조건이 바뀐 실험은 다른 실험이고, 진행 중인 작업이 사라진 자리를 가리키게 두느니 새로
+     * 세우는 것이 옳다. 그래서 여기서 거절하는 것은 한계가 아니라 **규칙**이다.
+     *
+     * ── 무엇을 지키고 무엇을 버리는가 ──────────────────────────────────────────
+     * 판단은 관측층(`ObservedReducer.adoptStructure`)이 한다 — 관측은 지키고, 선언에서 사라진
+     * 자원은 버리되 **몇 개를 버렸는지 돌려준다.** 여기서는 그 판단을 커널 자신의 선언 표에도
+     * 그대로 옮긴다. 관측층만 갈면 사라진 설비가 커널 표에 남아 **화면이 없는 설비를 그린다.**
+     *
+     * 관측으로 알게 된 자리는 선언에 없어도 지운 뒤 다시 심는다 — 다음 스냅샷에서 관측층이
+     * 되살리므로(`settleObserved` → `hydrateObserved`), 여기서 지켜야 할 것은 **선언분**뿐이다.
+     */
+    adoptStructure(def: TwinModelDef): StructureShift;
+    private buildEquipment;
     /**
      * what-if 구성 변주 — fork(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
      * 기본은 mtbf 미지정(고장 없는 신뢰 자원) → sampleExp(rng) 무소비라 baseline fork 와 깨끗이 비교 가능.

package/dist/flow-engine.js

@@ -265,22 +265,115 @@ 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(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
@@ -427,7 +520,11 @@ export class FlowEngine {
                    없다.** 라이브 트윈이 납기 초과를 한 번도 보고하지 못한 원인 중 하나였다. */
                 ...(o.endTime ? { endTime: o.endTime } : {}),
                 ...(o.startTime ? { startTime: o.startTime } : {}),
-                ...(o.priority !== undefined ? { priority: o.priority } : {})
+                ...(o.priority !== undefined ? { priority: o.priority } : {}),
+                /* 확보분과 거래번호도 함께 옮긴다 — 여기서 떨구면 위에서 실어 온 것이 마지막 한 걸음에서
+                   사라진다(같은 사실이 델타·스냅샷·이 변환 **세 길**을 지난다). */
+                ...(o.allocated?.length ? { allocated: o.allocated } : {}),
+                ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {})
             }));
         for (const o of observedOrders) {
             const lines = (o.lines ?? []).map(l => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter(l => l.requested > 0);
@@ -441,7 +538,10 @@ export class FlowEngine {
                 continue; // 이미 이행 완료 → 예측 대상 아님
             this.orders.set(o.orderId, {
                 id: o.orderId, kind: o.kind, status: 'created', requested: remaining, fulfilled: 0,
-                bizTransaction: '', allocated: [], picked: [], shipmentEpc: null, lines,
+                /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
+                   보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
+                   않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
+                bizTransaction: o.bizTransaction ?? '', allocated: (o.allocated ?? []).slice(), picked: [], shipmentEpc: null, lines,
                 /* **보류를 이어받는다** — 잃으면 씨앗이 사람이 일부러 멈춘 오더를 다시 계획해 내보낸다.
                    씨앗 왕복 대조가 이것을 잡았다(그 전에는 사람이 코드를 읽어야만 알 수 있었다). */
                 ...(o.held ? { held: true } : {}),
@@ -767,6 +867,10 @@ export class FlowEngine {
                 ...(o.priority !== undefined ? { priority: o.priority } : {}),
                 ...(o.startTime ? { startTime: o.startTime } : {}),
                 ...(o.endTime ? { endTime: o.endTime } : {}),
+                /* 진행 중 확보분과 거래번호 — **스냅샷에도** 실어야 한다. 델타에만 실으면 스냅샷으로
+                   재기동하는 경로(체크포인트)에서 그대로 잃는다(같은 사실을 두 길로 나르는 값이다). */
+                ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
+                ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
                 held: o.held
             })),
             attentions: this.computeAttentions(),
@@ -1367,7 +1471,11 @@ export class FlowEngine {
             ...(o.priority !== undefined ? { priority: o.priority } : {}),
             ...(o.startTime ? { startTime: o.startTime } : {}),
             ...(o.endTime ? { endTime: o.endTime } : {}),
-            ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {})
+            ...(o.lines?.length ? { lines: o.lines.map(l => ({ gtin: l.gtin, requested: l.requested })) } : {}),
+            /* 진행 중 할당과 거래번호를 함께 싣는다 — 이것이 없으면 웜스타트가 잃고, 되살아난 오더의
+               계보가 입력 없이 나간다(무엇이 무엇으로 바뀌었나의 절반이 사라진다). */
+            ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
+            ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {})
         });
     }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────

package/dist/observed-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { AssetState, TwinModelDef, 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.
  *
@@ -91,13 +91,7 @@ export declare class ObservedReducer {
      * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
      * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
      */
-    adoptStructure(board: TwinModelDef): {
-        locationsAdded: number;
-        locationsDropped: number;
-        equipmentDropped: number;
-        personsDropped: number;
-        assetsDropped: number;
-    };
+    adoptStructure(board: TwinModelDef): StructureShift;
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u: MasterUpdate): void;
     /**

package/dist/observed-reducer.js

@@ -342,6 +342,10 @@ export class ObservedReducer {
                     ...(d.priority !== undefined ? { priority: d.priority } : {}),
                     ...(d.startTime ? { startTime: d.startTime } : {}),
                     ...(d.endTime ? { endTime: d.endTime } : {}),
+                    /* 진행 중 확보분과 거래번호 — **미러도 같은 필드를 채운다.** 시뮬만 아는 사실을 두면
+                       그 위에서 세운 예측이 두 구동에서 달라진다(패리티 검사가 지키는 것이 이것이다). */
+                    ...(d.allocated?.length ? { allocated: d.allocated.slice() } : {}),
+                    ...(d.bizTransaction ? { bizTransaction: d.bizTransaction } : {}),
                     held: d.held
                 });
                 break;

package/dist-cjs/index.cjs

@@ -1181,6 +1181,10 @@ var ObservedReducer = class {
           ...d.priority !== void 0 ? { priority: d.priority } : {},
           ...d.startTime ? { startTime: d.startTime } : {},
           ...d.endTime ? { endTime: d.endTime } : {},
+          /* 진행 중 확보분과 거래번호 — **미러도 같은 필드를 채운다.** 시뮬만 아는 사실을 두면
+             그 위에서 세운 예측이 두 구동에서 달라진다(패리티 검사가 지키는 것이 이것이다). */
+          ...d.allocated?.length ? { allocated: d.allocated.slice() } : {},
+          ...d.bizTransaction ? { bizTransaction: d.bizTransaction } : {},
           held: d.held
         });
         break;
@@ -2283,20 +2287,98 @@ var FlowEngine = class {
   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(또는 실행 중) 엔진에 설비 추가. loadTwinModel 설비 삽입과 동일 규약.
@@ -2424,7 +2506,11 @@ var FlowEngine = class {
          없다.** 라이브 트윈이 납기 초과를 한 번도 보고하지 못한 원인 중 하나였다. */
       ...o.endTime ? { endTime: o.endTime } : {},
       ...o.startTime ? { startTime: o.startTime } : {},
-      ...o.priority !== void 0 ? { priority: o.priority } : {}
+      ...o.priority !== void 0 ? { priority: o.priority } : {},
+      /* 확보분과 거래번호도 함께 옮긴다 — 여기서 떨구면 위에서 실어 온 것이 마지막 한 걸음에서
+         사라진다(같은 사실이 델타·스냅샷·이 변환 **세 길**을 지난다). */
+      ...o.allocated?.length ? { allocated: o.allocated } : {},
+      ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}
     }));
     for (const o of observedOrders) {
       const lines = (o.lines ?? []).map((l) => ({ gtin: l.gtin, requested: l.requested - (l.fulfilled ?? 0) })).filter((l) => l.requested > 0);
@@ -2436,8 +2522,11 @@ var FlowEngine = class {
         status: "created",
         requested: remaining,
         fulfilled: 0,
-        bizTransaction: "",
-        allocated: [],
+        /* **확보해 둔 것과 거래번호를 이어받는다.** 비우면 되살아난 오더가 아무것도 안 잡은 것처럼
+           보이고, 그 오더의 진행 중 작업이 완료될 때 계보가 입력 없이 나간다. 상태가 말해 주지
+           않으면(옛 저널) 그때는 비는 것이 사실이다 — 없는 것을 지어내지 않는다. */
+        bizTransaction: o.bizTransaction ?? "",
+        allocated: (o.allocated ?? []).slice(),
         picked: [],
         shipmentEpc: null,
         lines,
@@ -2745,6 +2834,10 @@ var FlowEngine = class {
         ...o.priority !== void 0 ? { priority: o.priority } : {},
         ...o.startTime ? { startTime: o.startTime } : {},
         ...o.endTime ? { endTime: o.endTime } : {},
+        /* 진행 중 확보분과 거래번호 — **스냅샷에도** 실어야 한다. 델타에만 실으면 스냅샷으로
+           재기동하는 경로(체크포인트)에서 그대로 잃는다(같은 사실을 두 길로 나르는 값이다). */
+        ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
+        ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
         held: o.held
       })),
       attentions: this.computeAttentions(),
@@ -3289,7 +3382,11 @@ var FlowEngine = class {
       ...o.priority !== void 0 ? { priority: o.priority } : {},
       ...o.startTime ? { startTime: o.startTime } : {},
       ...o.endTime ? { endTime: o.endTime } : {},
-      ...o.lines?.length ? { lines: o.lines.map((l) => ({ gtin: l.gtin, requested: l.requested })) } : {}
+      ...o.lines?.length ? { lines: o.lines.map((l) => ({ gtin: l.gtin, requested: l.requested })) } : {},
+      /* 진행 중 할당과 거래번호를 함께 싣는다 — 이것이 없으면 웜스타트가 잃고, 되살아난 오더의
+         계보가 입력 없이 나간다(무엇이 무엇으로 바뀌었나의 절반이 사라진다). */
+      ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
+      ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}
     });
   }
   // ── 내부 mechanics ─────────────────────────────────────────────────────────

package/package.json

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