@things-factory/headless-twin 10.0.6 → 10.0.7

package/dist-server/engine/twin-engine.js

@@ -3,7 +3,7 @@
  * TwinEngine — operato-twin 커널 인스턴스를 things-factory 위에서 호스팅.
  * integration-base 의 ScenarioEngine 패턴 미러: 메모리 인스턴스 맵 + 백그라운드 tick + pubsub 상태 발행.
  *
- * 커널(zero-dep, ESM+CJS 이중배포)은 CJS require 로 로드(Node 20 CommonJS 소비 — require(ESM) 회피).
+ * 커널(zero-dep, ESM+CJS 이중배포)은 CJS require 로 로드(Node 20 CommonJS 소비 — require(ESM) 회피).  (vocabulary-guard: allow — Node 런타임 버전 표기)
  * 커널은 결정적 논리 연산 코어 — 이 host 가 전송(pubsub)·영속(TypeORM)·스케줄(tick)·복구(replay)만 얇게 래핑.
  * (설계 SoT: operato-twin/design/integration/things-factory-host.md)
  */
@@ -15,16 +15,22 @@ const twin_event_js_1 = require("../service/twin-event/twin-event.js");
 const twin_event_keys_js_1 = require("../service/twin-event/twin-event-keys.js");
 const warm_start_js_1 = require("./warm-start.js");
 const twin_instance_js_1 = require("../service/twin-instance/twin-instance.js");
+const twin_structure_js_1 = require("../service/twin-structure/twin-structure.js");
 const twin_space_js_1 = require("../service/twin-space/twin-space.js");
+const reference_master_js_1 = require("../service/reference/reference-master.js");
 const twin_space_representation_js_1 = require("../service/twin-space/twin-space-representation.js");
 const twin_space_area_js_1 = require("../service/twin-space/twin-space-area.js");
 const twin_area_js_1 = require("../service/twin-space/twin-area.js");
-const reference_master_js_1 = require("../service/reference/reference-master.js");
+const reference_master_js_2 = require("../service/reference/reference-master.js");
+const travel_estimator_js_1 = require("./travel-estimator.js");
+const measured_estimator_js_1 = require("./measured-estimator.js");
+const kpi_query_js_1 = require("./kpi-query.js");
+const node_crypto_1 = require("node:crypto");
 const entity_delta_js_1 = require("./entity-delta.js");
+const structure_diff_js_1 = require("./structure-diff.js");
 const oee_accumulator_js_1 = require("./oee-accumulator.js");
-const live_attentions_js_1 = require("./live-attentions.js");
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
-const { WmsKernel, YmsKernel, MesKernel, TwinRuntime, StateProjector, replay, DOMAIN_CATALOG, OP_EVENT } = require('@operato/twin-kernel');
+const { WmsKernel, YmsKernel, MesKernel, TwinRuntime, StateProjector, replay, replaySegments, DOMAIN_CATALOG, OP_EVENT } = require('@operato/twin-kernel');
 const KERNELS = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel };
 exports.DEFAULT_REALITY_MODE = 'sim-experiment';
 class TwinEngine {
@@ -157,17 +163,153 @@ class TwinEngine {
             return;
         }
         hydrate.call(kernel, plan.seed);
-        console.log(`[twin-engine] warm-started "${id}" — ${plan.itemCount} item(s), ${plan.moverCount} mover(s) restored. ` +
+        console.log(`[twin-engine] warm-started "${id}" — ${plan.itemCount} item(s), ${plan.equipmentCount} equipment restored. ` +
             'Open orders are not restored (the snapshot carries no requested/fulfilled counts).');
     }
     /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + 직전 상태 웜스타트 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
-    static start(id, domainId, kind, board, realityMode, purpose) {
+    /**
+     * 공정 명세를 커널에 싣는다 — **시뮬레이션의 시간을 데이터가 말하게 하는 마지막 한 칸.**
+     *
+     * `board.operations`(마스터 인제스트가 통과시킨 ISA-95 OperationsSegment 명세)를 커널이 소비한다.
+     * 없으면 커널 기본 상수로 굴러가고, 커널 `specCoverage()` 가 무엇을 기본값으로 썼는지 보고한다.
+     *
+     * 커널이 아직 이 API 를 갖지 않은 버전이면(발행 이전) **조용히 넘어가지 않고 경고한다** — 명세를
+     * 선언했는데 반영되지 않는 상태를 모르고 지나가면, 예측이 상수로 돌아간 것을 아무도 알 수 없다.
+     */
+    static applyOperations(kernel, board, id) {
+        const ops = board?.operations;
+        if (!ops?.length)
+            return;
+        if (typeof kernel?.loadOperations !== 'function') {
+            console.warn(`[twin-engine] "${id}": board declares ${ops.length} operation spec(s) but the kernel cannot consume them (loadOperations missing — kernel needs publishing). Simulation will use built-in default durations.`);
+            return;
+        }
+        kernel.loadOperations(ops);
+    }
+    /**
+     * 소요시간 추정기 주입 — **상수를 데이터로 바꾸는 두 번째·세 번째 층.**
+     *
+     * 커널 `durationOf` 의 우선순위는 추정기 > 명세 > 상수다. 그 추정기 자리에 두 가지를 사슬로 넣는다:
+     *  ① **실측**(저널의 작업 종류별 작업시간 p50) — 그 현장에서 실제로 얼마 걸렸나. 가장 강한 근거.
+     *  ② **거리 × 속도**(board.layout + 설비 속도 속성) — 이동은 거리에 비례한다. 커널은 좌표를 모르므로
+     *     호스트가 계산해 넣는다.
+     * 둘 다 못 만들면 주입하지 않는다 — 커널이 명세·상수로 굴러가고 `specCoverage()` 가 그 사실을 남긴다.
+     *
+     * 실측은 DB 조회라 비동기다. 그래서 이 함수는 **await 하지 않는 쪽에서도 안전**하도록 실패를 삼키되,
+     * 무엇을 왜 못 넣었는지는 로그로 남긴다(조용한 무효화 금지).
+     */
+    static async installEstimators(kernel, domainId, instanceId, board) {
+        if (!kernel || typeof kernel !== 'object')
+            return;
+        const travel = (0, travel_estimator_js_1.buildTravelEstimator)({ layout: board?.layout, equipment: board?.equipment, unit: board?.unit });
+        const measured = await this.measuredEstimator(domainId, instanceId);
+        const chained = (0, travel_estimator_js_1.chainEstimators)([measured?.estimator, travel.estimator]);
+        if (!chained) {
+            /* 왜 못 넣었는지 한 번만 알린다 — 이동시간이 상수로 남은 이유를 모르고 지나가지 않게. */
+            if (travel.reasons.length)
+                console.warn(`[twin-engine] "${instanceId}": no duration estimator installed — ${travel.reasons.join('; ')}`);
+            return;
+        }
+        kernel.durationEstimator = chained;
+        const learned = Object.keys(measured?.learned ?? {});
+        const spread = Object.keys(measured?.spreads ?? {});
+        console.log(`[twin-engine] "${instanceId}": duration estimator installed — measured kinds: ${learned.length ? learned.join(',') : 'none'}` +
+            ` (with observed spread: ${spread.length ? spread.join(',') : 'none'})` +
+            `${travel.estimator ? `, travel from distance (speeds: ${Object.keys(travel.speedsByKind).join(',')})` : `, travel not derived (${travel.reasons.join('; ')})`}`);
+    }
+    /**
+     * 실측 추정기 — **예측 요청마다 저널을 다시 접지 않는다.**
+     *
+     * 예측 커널은 요청마다 새로 세워지고(미러 예측·백테스트), 화면은 시각을 긁으면 계속 재예측한다.
+     * 거기에 KPI 조회를 그대로 달면 요청당 저널 스캔이 하나씩 붙는다 — 실측은 분 단위로 바뀌지 않으므로
+     * 짧은 TTL 로 재사용한다. 캐시는 인스턴스별이고, 만료 전에는 같은 값을 쓴다(예측 간 일관성도 얻는다).
+     */
+    static { this.measuredCache = new Map(); }
+    static { this.MEASURED_TTL_MS = 60_000; }
+    static async measuredEstimator(domainId, instanceId) {
+        const key = `${domainId}:${instanceId}`;
+        const hit = this.measuredCache.get(key);
+        if (hit && Date.now() - hit.at < this.MEASURED_TTL_MS)
+            return hit.value;
+        let value;
+        try {
+            /* 작업 종류별 실측 — 창은 넉넉히(하루) 두고 표본이 모자란 종류는 추정기가 스스로 뺀다. */
+            const kpi = await (0, kpi_query_js_1.computeTwinKpi)({ domainId, instanceId, windowMinutes: 24 * 60, groupBy: 'taskKind' });
+            value = (0, measured_estimator_js_1.buildMeasuredEstimator)(kpi?.groups?.items, {});
+        }
+        catch (err) {
+            console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, err?.message);
+        }
+        this.measuredCache.set(key, { at: Date.now(), value });
+        return value;
+    }
+    /**
+     * 지금 이 트윈이 어떤 모델로 굴러가는가 — 예측 출력 보정이 **자기가 배운 모델**에만 적용되도록
+     * 비교하는 지문. 재료는 호스트가 아는 것(실측·속도·선언 명세)이라 커널 발행 상태와 무관하다.
+     * 실패하면 undefined — 그때는 비교를 하지 않는다(모르는 것을 근거로 보정을 끊지 않는다).
+     */
+    static async modelBasis(domainId, instanceId) {
+        try {
+            const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+            const board = reg?.board;
+            const measured = await this.measuredEstimator(domainId, instanceId);
+            const travel = (0, travel_estimator_js_1.buildTravelEstimator)({ layout: board?.layout, equipment: board?.equipment, unit: board?.unit });
+            return { measured: measured?.learned, speeds: travel.speedsByKind, declared: board?.operations };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * **이 트윈이 하루 몇 대를 낼 수 있는가** — 굴려 보지 않고 답한다.
+     *
+     * 계산은 커널이 자기 상태에서 한다(`kernel.capacity`). 여기서 하는 일은 **기준 주를 정해 주는
+     * 것**뿐이다: 공휴일이 없는 평상주여야 한다 — 공휴일은 연간 가용량을 따로 깎지, 이 공장의 평상시
+     * 천장을 정하지 않는다. 커널이 임의로 고르게 두면 그 주에 공휴일이 끼었을 때 천장이 조용히 낮아진다.
+     *
+     * 트윈이 안 떠 있으면 `undefined` 다 — 0 이 아니다. 안 뜬 트윈의 천장을 0 이라고 답하면 화면은
+     * "이 공장은 아무것도 못 만든다" 고 말한다.
+     */
+    static async capacity(domainId, target, unitsPerDay, sampleWeekStartMs) {
+        /* 대상은 **등록부**가 정한다 — 떠 있는 런타임만 훑으면 "안 떠 있어서 안 보이는 것" 과 "없는 것" 이
+           구별되지 않는다. 화면은 그 둘을 다르게 말해야 한다. */
+        const where = { domain: { id: domainId } };
+        if (target.instanceId)
+            where.instanceId = target.instanceId;
+        else
+            where.spaceId = target.spaceId;
+        const registered = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where });
+        return registered.map(reg => {
+            const rt = this.instances[reg.instanceId];
+            const kernel = rt?.domainId === domainId ? rt.kernel : undefined;
+            if (typeof kernel?.capacity !== 'function')
+                return { instanceId: reg.instanceId, kind: reg.kind, reason: 'not-running' };
+            const analysis = kernel.capacity({ unitsPerDay, sampleWeekStartMs });
+            /* 공정을 선언하지 않은 트윈(대개 YMS·WMS)은 **판정 대상이 아니다.** 0 으로 채워 넣으면
+               "야드가 병목" 이라는 없는 사실이 생긴다 — 잴 것이 없다고 말한다. */
+            if (!analysis?.operations?.length)
+                return { instanceId: reg.instanceId, kind: reg.kind, reason: 'no-operations' };
+            return { instanceId: reg.instanceId, kind: reg.kind, analysis };
+        });
+    }
+    static start(id, domainId, kind, board, realityMode, purpose, resumeFrom) {
         if (this.instances[id])
             return this.instances[id];
         const Kernel = KERNELS[kind] ?? WmsKernel;
-        const kernel = new Kernel(domainId);
+        const kernel = new Kernel(domainId, undefined, this.mesSpecOf(board));
         kernel.loadBoard(board); // 구조만. 상태는 아래 웜스타트가 심는다.
+        this.applyOperations(kernel, board, id); // 시간·수율 명세(있으면) — 없으면 커널 기본값
+        /* 추정기는 DB 조회를 포함해 비동기 — 기동을 막지 않고 붙는다(붙기 전 작업은 명세·상수로 산출). */
+        this.installEstimators(kernel, domainId, id, board).catch(err => console.warn('[twin-engine] estimator install failed', err?.message));
         this.warmStart(id, kernel, purpose);
+        /*
+         * **번호를 이어 센다** — 저널에 이미 있는 번호와 겹치지 않게.
+         *
+         * 저널이 비어 있으면(0) 아무 일도 안 한다. 비어 있지 않은데 0부터 다시 세면 같은 트윈에 같은
+         * 리비전이 둘 생기고, 재생 순서가 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다 — 오류는 안 난다.
+         */
+        if (resumeFrom && typeof kernel.resumeRevision === 'function')
+            kernel.resumeRevision(resumeFrom);
         const runtime = new TwinRuntime(kernel);
         /* subscribe 는 RuntimeSubscription({ unsubscribe() }) 반환 → () => void 로 감쌈. */
         const inst = { id, domainId, runtime, kernel, realityMode: realityMode ?? exports.DEFAULT_REALITY_MODE, unsub: () => { } };
@@ -194,16 +336,67 @@ class TwinEngine {
         return inst;
     }
     /**
-     * live-모드 기동(face2-inbound-live §1.1) — 커널 tick 대신 StateProjector 로 실 이벤트를 미러.
-     * 관측 상태(점유·위치·아이템)는 projector 가 재구성 → sim 과 동일 data(tag) payload → **보드 컴포넌트 동일 렌더**
-     * (live-mirror-parity 로 payload 층 검증됨). 계산 층(attentions·OEE)은 이벤트에 없어 부재 — derive 층은 후속.
+     * live-모드 기동 — **관측 모드 커널**로 실 이벤트를 미러한다(통합 P2).
+     *
+     * 예전에는 `StateProjector` 를 세웠다. 그래서 라이브에는 **커널이 없었고**, 그 하나 때문에 우회가
+     * 줄줄이 생겼다: 예측하려면 임시 커널을 세워야 했고(`buildForecastKernel`), 주목 신호를 호스트가
+     * 덧붙여야 했고(`withLiveAttentions`), AI 예측 도구는 미러에서 "찾을 수 없다" 로 끝났다.
+     *
+     * 이제 라이브 인스턴스도 **커널이다.** 같은 규칙(`ObservedReducer`)으로 이벤트를 접고, 주목 신호를
+     * 스스로 내고, 그 자리에서 `fork` 해 예측한다. 구동만 다르다 — sim 은 `tick`, live 는 `apply`.
+     *
      * 실 이벤트원 = reference 어댑터 openLiveFeed → face2-adapter.ingest → CanonicalEnvelope → ingestLive().
      */
+    /**
+     * 보드가 실은 **생산 정의**(레시피·라우트·바인딩)를 꺼낸다 — 커널의 정의-구동 모드 입구.
+     *
+     * ── 없을 때 무엇이 일어났나 ──────────────────────────────────────────────
+     * 커널에는 정의-구동 MES 경로가 있는데 **호스트가 그것을 한 번도 넘기지 않았다.** 그래서 모든 MES
+     * 트윈이 **하드코딩된 레거시 흐름**으로 돌았다 — 현장 레시피를 아무리 정성껏 적어도 커널은 그것을
+     * 보지 못하고 토이 부품으로 토이 제품을 만들었다. 선언과 실행이 갈라져 있던 자리다.
+     *
+     * 보드에 없으면 `undefined` — 레거시 경로 그대로다(기존 트윈의 거동을 바꾸지 않는다).
+     */
+    static mesSpecOf(board) {
+        return board?.mesSpec;
+    }
+    /**
+     * 현장(공간)의 **시각 기준**을 보드에 얹는다 — 커널이 교대의 `HH:MM` 을 읽을 기준.
+     *
+     * **테넌트가 아니라 공간이 권위다.** 한 테넌트가 Rosarito(태평양)와 한국 공장을 함께 가질 수 있고,
+     * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 그래서 인스턴스가 묶인 공간의
+     * `timezone` 을 읽는다. 공간이 말하지 않으면 **테넌트로 내려가지 않는다** — 잘못된 입자로 답하는 것이
+     * 모르는 것보다 나쁘다(그때는 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다).
+     *
+     * 커널은 zero-dep 이라 시간대 데이터베이스를 갖지 않으므로 **분 오프셋**으로 풀어 넘긴다. 그 값은
+     * 지금 계절의 것이다(일광절약시간) — 계절을 넘는 긴 예측은 한 시간 어긋난다(계약에 명시).
+     */
+    static async withSpaceTimeBase(board, domainId, spaceId) {
+        const sid = spaceId ?? board?.spaceId;
+        if (!sid)
+            return board;
+        const space = await (0, shell_1.getRepository)(twin_space_js_1.TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId: sid } }).catch(() => null);
+        const offset = (0, reference_master_js_1.utcOffsetOf)(space?.timezone);
+        if (offset === undefined) {
+            if (space?.timezone)
+                console.warn(`[twin-engine] space "${sid}" declares time zone "${space.timezone}" but it is not a known IANA zone — times will be read as UTC.`);
+            return board;
+        }
+        return { ...board, utcOffsetMinutes: offset };
+    }
     static startLive(id, domainId, kind, board) {
         if (this.instances[id])
             return this.instances[id];
-        const projector = new StateProjector(board);
-        const inst = { id, domainId, mode: 'live', realityMode: 'mirror', projector, oee: new oee_accumulator_js_1.OeeAccumulator(), unsub: () => { } };
+        const Kernel = KERNELS[kind] ?? WmsKernel;
+        const kernel = new Kernel(domainId, undefined, this.mesSpecOf(board));
+        kernel.loadBoard(board);
+        this.applyOperations(kernel, board, id); // 명세는 라이브에도 실린다(예측 자격이 sim 과 같아진다)
+        /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
+         * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
+        const projector = { apply: (e) => kernel.apply(e), snapshot: () => kernel.getSnapshot() };
+        const inst = { id, domainId, mode: 'live', realityMode: 'mirror', kernel, projector, oee: new oee_accumulator_js_1.OeeAccumulator(), unsub: () => { } };
+        /* 추정기(실측·거리)도 라이브에 붙인다 — 예측이 상수로 돌지 않게. 기동을 막지 않는다. */
+        this.installEstimators(kernel, domainId, id, board).catch(err => console.warn('[twin-engine] estimator install failed', err?.message));
         inst.metrics = { ingestedTotal: 0, broadcastTotal: 0, journaledTotal: 0, ingestRate: 0, broadcastRate: 0, journalRate: 0, backlog: 0, _accIngest: 0, _accBroadcast: 0, _accJournal: 0, _windowStartMs: Date.now() };
         this.instances[id] = inst;
         delete this.recovered[id];
@@ -315,22 +508,43 @@ class TwinEngine {
      * 두 곳에 각자 적으면 승격 검색 키가 한쪽에만 채워지고, 반쯤 빈 색인은 "저널에는 있는데
      * 검색으로는 안 나오는 이벤트" 를 만든다 — 저널에서 가장 나쁜 종류의 결함이다.
      */
-    static journalRow(repo, domainId, instanceId, e, revision) {
+    static journalRow(repo, domainId, instanceId, e, revision, structureRev) {
         return repo.create({
             domain: { id: domainId },
             instanceId,
             tenantId: e?.tenantId,
             eventType: e?.eventType,
             revision,
+            /* **이 사실이 일어난 공장**을 함께 찍는다 — 이것이 없으면 나중에 구조가 바뀌었을 때 이 행을
+               새 공장에 대고 접게 되고, 그때 없던 설비에서 일이 있었던 것처럼 보인다. */
+            ...(structureRev === undefined ? {} : { structureRev }),
             eventTime: e?.eventTime,
             ...(0, twin_event_keys_js_1.twinEventKeys)(e),
             payload: e
         });
     }
+    /**
+     * 이 트윈이 지금 어느 구조로 도는가 — 이벤트에 찍을 번호. 한 번 읽고 캐시한다(쓰기마다 조회 금지).
+     *
+     * 없으면 `undefined` 다 — 0 이 아니다. 구조 리비전이 생기기 전에 만들어진 트윈은 아직 리비전이
+     * 없고, 그 사실을 0 이라는 **유효해 보이는 번호**로 위장하면 안 된다.
+     */
+    static { this.structureRevCache = {}; }
+    static async structureRevOf(domainId, instanceId) {
+        const key = `${domainId}:${instanceId}`;
+        const cached = this.structureRevCache[key];
+        if (cached !== undefined)
+            return cached;
+        const latest = await (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure).findOne({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'DESC' } });
+        if (latest)
+            this.structureRevCache[key] = latest.rev;
+        return latest?.rev;
+    }
     /** live 저널 배치 기록 — 모아둔 CanonicalEnvelope 들에 startRevision+1.. 을 부여해 벌크 저장(coalescer tick 당 1회). */
     static async persistBatch(domainId, instanceId, envelopes, startRevision) {
         const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
-        const rows = envelopes.map((e, i) => this.journalRow(repo, domainId, instanceId, e, startRevision + i + 1));
+        const structureRev = await this.structureRevOf(domainId, instanceId);
+        const rows = envelopes.map((e, i) => this.journalRow(repo, domainId, instanceId, e, startRevision + i + 1, structureRev));
         await repo.save(rows, { chunk: 500 });
     }
     /** 레지스트리 upsert(도메인+instanceId 유니크). status 인자로 provision(stopped)/start(running) 공용. */
@@ -352,29 +566,29 @@ class TwinEngine {
         }));
     }
     /**
-     * 라이브 구조 변이(resource.add 등)를 저장된 board 에 반영 — 런타임 커널의 무버를 registry board.movers 에 동기.
+     * 라이브 구조 변이(resource.add 등)를 저장된 board 에 반영 — 런타임 커널의 무버를 registry board.equipment 에 동기.
      * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 board 는 원본이라 프로비저닝 편집기·재기동(loadBoard)이
-     * 추가분을 잃는다. 기존 board.movers 항목은 보존(homeNode 유지)하고 새 id 만 append(추가 시점 location=homeNode).
-     * 좌표(layout)만 다루는 register 와 달리 movers 집합을 갱신하나, 재프로비전(purge)이 아니라 in-place 갱신이라
+     * 추가분을 잃는다. 기존 board.equipment 항목은 보존(homeLocation 유지)하고 새 id 만 append(추가 시점 location=homeLocation).
+     * 좌표(layout)만 다루는 register 와 달리 equipment 집합을 갱신하나, 재프로비전(purge)이 아니라 in-place 갱신이라
      * 저널은 보존된다(추가는 이미 equipment 델타로 저널됨 → replay 는 id-keyed upsert 라 이중계산 없음).
      */
-    static async syncBoardMovers(domainId, instanceId) {
+    static async syncBoardEquipment(domainId, instanceId) {
         const inst = this.instances[instanceId];
         const snap = inst?.kernel?.getSnapshot?.();
-        if (!snap?.movers)
+        if (!snap?.equipment)
             return;
         const repo = (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance);
         const reg = await repo.findOne({ where: { domain: { id: domainId }, instanceId } });
         if (!reg?.board)
             return;
         const board = reg.board;
-        const known = new Set((board.movers ?? []).map(m => m.id));
-        const added = snap.movers
+        const known = new Set((board.equipment ?? []).map(m => m.id));
+        const added = snap.equipment
             .filter((m) => !known.has(m.id))
-            .map((m) => ({ id: m.id, kind: m.kind, homeNode: m.location }));
+            .map((m) => ({ id: m.id, kind: m.kind, homeLocation: m.location }));
         if (!added.length)
             return;
-        board.movers = [...(board.movers ?? []), ...added];
+        board.equipment = [...(board.equipment ?? []), ...added];
         reg.board = board;
         await repo.save(reg);
     }
@@ -383,28 +597,122 @@ class TwinEngine {
      * 재프로비전 시 구조 시그니처가 바뀌면(노드·무버 집합/속성 변경) 기존 저널을 purge 한다(ADR-0015):
      * board 는 replay 의 마스터라 구조가 바뀌면 과거 이벤트의 전제가 깨진다. 좌표(layout)만 바뀌면 저널 보존.
      */
-    static async provision(domainId, instanceId, kind, board) {
+    static async provision(domainId, instanceId, kind, board, comment) {
         if (this.instances[instanceId])
             throw new Error(`instance "${instanceId}" is running — stop before re-provisioning`);
         const repo = (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance);
         const existing = await repo.findOne({ where: { domain: { id: domainId }, instanceId } });
-        if (existing?.board && this.structureSignature(existing.board) !== this.structureSignature(board)) {
-            await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).delete({ domain: { id: domainId }, instanceId });
-            delete this.recovered[instanceId];
-        }
+        /*
+         * **구조가 바뀌어도 역사를 지우지 않는다.**
+         *
+         * 예전에는 서명이 다르면 그 트윈의 저널을 통째로 지웠다. 안 지우면 옛 이벤트를 새 공장에 대고
+         * 접게 되어 이력이 거짓말을 했기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에
+         * 접으면 그때 없던 부스에서 일이 있었던 것처럼 보인다. 선택지가 **역사를 잃거나 거짓말을
+         * 하거나** 둘뿐이었고, 그래서 공장을 고칠 때마다 이력을 버려야 했다.
+         *
+         * 이제 셋째 길로 간다: 바뀐 구조를 **새 리비전**으로 남기고, 앞으로 쓰이는 이벤트가 그 번호를
+         * 달고 다닌다. 재생은 구조가 바뀌는 지점에서 갈아탄 뒤 이어 접는다(`replaySegments`).
+         */
+        await this.recordStructure(domainId, instanceId, board, comment);
         await this.register(domainId, instanceId, kind, board, existing?.status === 'running' ? 'stopped' : existing?.status ?? 'stopped');
     }
+    /**
+     * 이 구조를 리비전으로 남기고 그 번호를 돌려준다 — **바뀌었을 때만** 새 번호가 생긴다.
+     *
+     * 프로비저닝은 부팅마다 다시 도는데, 그때마다 리비전이 늘면 이력이 뜻 없는 마디로 잘게 쪼개진다.
+     * 그래서 **구조 서명이 같으면 있던 리비전을 그대로 쓴다.**
+     */
+    static async recordStructure(domainId, instanceId, board, comment) {
+        const repo = (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure);
+        const signature = this.structureFingerprint(board);
+        const latest = await repo.findOne({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'DESC' } });
+        /*
+         * **저장된 지문이 아니라 저장된 공장과 비교한다.**
+         *
+         * 지문 계산 방식을 한 번이라도 바꾸면(원문 → 해시로 바꿨다) 저장된 문자열은 전부 옛 방식의
+         * 것이라 무엇과도 안 맞는다. 그러면 **아무것도 안 바뀐 트윈들이 전부 "구조가 바뀌었다"** 로
+         * 기록된다 — 실제로 그렇게 됐고, 재기동 한 번에 리비전이 통째로 하나씩 늘었다.
+         *
+         * 그래서 안 맞을 때 한 번 더 묻는다: 저장된 **보드**로 지문을 다시 계산하면 같은가? 같다면
+         * 공장은 그대로이고 지문 표기만 낡은 것이니, 리비전을 만들지 않고 표기만 고친다.
+         */
+        if (latest && latest.signature !== signature && this.structureFingerprint(latest.board) === signature) {
+            latest.signature = signature;
+            await repo.save(latest);
+        }
+        if (latest?.signature === signature) {
+            this.structureRevCache[`${domainId}:${instanceId}`] = latest.rev;
+            return latest.rev;
+        }
+        const rev = (latest?.rev ?? 0) + 1;
+        await repo.save(repo.create({ domain: { id: domainId }, instanceId, rev, signature, board: board, ...(comment ? { comment } : {}) }));
+        this.structureRevCache[`${domainId}:${instanceId}`] = rev;
+        /* 구조가 바뀌면 재구성 캐시는 옛 공장의 것이다 — 버린다(지우는 건 캐시뿐, 사실은 남는다). */
+        delete this.recovered[instanceId];
+        if (latest)
+            console.info(`[twin-engine] "${instanceId}" structure changed → revision ${rev} (history kept; older events stay under revision ${latest.rev}).`);
+        return rev;
+    }
+    /**
+     * 이 트윈이 거쳐 온 구조들 — **무엇이 언제 달라졌나.**
+     *
+     * 리비전은 그 시절 공장을 통째로 담지만(재생에 필요하다), 사람이 보고 싶은 것은 통째가 아니라
+     * 차이다. 보드는 빼고 **차이 요약만** 내보낸다 — 62KB 짜리 보드를 화면에 실어 보낼 이유가 없다.
+     */
+    static async structureHistory(domainId, instanceId) {
+        const revs = await (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure).find({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'ASC' } });
+        if (!revs.length)
+            return [];
+        /* 리비전마다 그 아래에서 몇 건이 일어났나 — 이력의 무게를 보여준다(짧게 스쳐간 구조인지). */
+        const counts = new Map();
+        for (const row of await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('e')
+            .select('e.structureRev', 'rev')
+            .addSelect('COUNT(1)', 'n')
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId })
+            .groupBy('e.structureRev')
+            .getRawMany())
+            counts.set(row.rev === null || row.rev === undefined ? null : Number(row.rev), Number(row.n));
+        /* 번호 없는 옛 행은 **가장 오래된 리비전**의 몫이다 — 재생이 그렇게 접으므로 세는 것도 같아야 한다. */
+        const oldest = revs[0].rev;
+        const legacy = counts.get(null) ?? 0;
+        return revs.map((r, i) => ({
+            rev: r.rev,
+            createdAt: r.createdAt,
+            ...(r.comment ? { comment: r.comment } : {}),
+            events: (counts.get(r.rev) ?? 0) + (r.rev === oldest ? legacy : 0),
+            diff: (0, structure_diff_js_1.diffStructures)(i === 0 ? undefined : revs[i - 1].board, r.board)
+        }));
+    }
+    /** 지금 쓰이는 구조 리비전 — 이벤트에 찍을 번호. 아직 없으면 기록하며 만든다. */
+    static async currentStructureRev(domainId, instanceId, board) {
+        const latest = await (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure).findOne({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'DESC' } });
+        if (latest)
+            return latest.rev;
+        return board ? this.recordStructure(domainId, instanceId, board) : undefined;
+    }
     /** 구조 동일성 지문 — 좌표(layout) 등 뷰 관심사는 제외하고 커널이 보는 위상·용량·무버만. */
+    /**
+     * 지문을 **64자로 줄인다** — 컬럼이 varchar(64) 다.
+     *
+     * 원문 지문은 자리·설비를 전부 이어 붙인 문자열이라 큰 공장에서는 수만 자가 된다. sqlite 는
+     * 길이를 강제하지 않아 그냥 들어가지만 **Postgres 는 거기서 터진다** — 개발에서는 멀쩡하고
+     * 운영에서만 죽는 종류의 실패다. 비교에만 쓰는 값이므로 해시로 충분하다.
+     */
+    static structureFingerprint(board) {
+        return (0, node_crypto_1.createHash)('sha256').update(this.structureSignature(board)).digest('hex');
+    }
     static structureSignature(board) {
-        const nodes = [...(board.nodes ?? [])]
+        const locations = [...(board.locations ?? [])]
             .map(n => `${n.id}:${n.type}:${n.capacity}`)
             .sort()
             .join('|');
-        const movers = [...(board.movers ?? [])]
-            .map(m => `${m.id}:${m.kind}:${m.homeNode}`)
+        const equipment = [...(board.equipment ?? [])]
+            .map(m => `${m.id}:${m.kind}:${m.homeLocation}`)
             .sort()
             .join('|');
-        return `N[${nodes}]M[${movers}]`;
+        return `N[${locations}]M[${equipment}]`;
     }
     /** 레지스트리 board 로 기동(프로비전된 인스턴스 start). board 인자 없이 저장된 구조로 재기동. */
     static async startFromRegistry(domainId, instanceId, realityMode) {
@@ -431,7 +739,20 @@ class TwinEngine {
                     this.recovered[instanceId] = { revision: state.revision, state };
             }
         }
-        return this.start(instanceId, domainId, reg.kind ?? 'wms', reg.board, realityMode ?? reg.realityMode ?? undefined, reg.purpose ?? undefined);
+        /*
+         * 저널에 남아 있는 마지막 번호 — **모드와 무관하게** 이것을 이어 센다.
+         *
+         * 저널을 초기화하고 기동하는 모드(sim-experiment)라면 이 값이 0이라 아무 영향이 없다. 규칙을
+         * 모드별로 가르지 않는 이유: "저널이 비어 있지 않으면 그 뒤부터" 하나면 어느 모드에서도
+         * 겹칠 수 없고, 모드가 늘어도 이 자리를 다시 손볼 일이 없다.
+         */
+        const last = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('e')
+            .select('MAX(e.revision)', 'max')
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId })
+            .getRawOne();
+        return this.start(instanceId, domainId, reg.kind ?? 'wms', reg.board, realityMode ?? reg.realityMode ?? undefined, reg.purpose ?? undefined, Number(last?.max ?? 0) || 0);
     }
     /**
      * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 가른다.
@@ -451,9 +772,18 @@ class TwinEngine {
             return this.startLive(instanceId, domainId, reg.kind ?? 'wms', reg.board);
         }
         if (mode === 'sim-world') {
-            // 선언은 world(지속)지만 resume 기계장치(커널 상태 복원)가 아직 없다 → 정직하게 큰 경고 후 fresh 기동.
-            console.warn(`[twin-engine] "${instanceId}" declared sim-world but resume is not yet implemented (runtime-state-model §8 gate ②③) — booting FRESH (journal reset). Persisted continuity will attach here once kernel-state resume lands.`);
-            await this.resetJournal(domainId, instanceId);
+            /*
+             * **이어지는 현실** — 저널을 지우지 않는다.
+             *
+             * 예전에는 여기서 저널을 지우고 fresh 로 띄웠다. resume 기계장치가 없다고 봤기 때문인데,
+             * 실제로 없던 것은 **번호 이어 세기 하나**였다: 상태 복원은 이미 `startFromRegistry` 가
+             * 저널 재생(또는 체크포인트)으로 하고 있었고, 막힌 것은 커널이 리비전을 0부터 다시 세어
+             * 기존 행과 겹치는 문제였다. 그 하나를 `resumeRevision` 으로 풀었으므로 이제 이어 간다.
+             *
+             * 아직 이어지지 않는 것(정직하게): 시나리오 생성기의 난수 흐름은 재기동에 이어지지 않는다 —
+             * 같은 씨앗에서 다시 시작하므로 자극의 패턴이 재기동 지점에서 한 번 끊긴다. 쌓인 사실과
+             * 상태는 이어지고, 앞으로 일어날 일의 무작위 순서만 새로 시작한다.
+             */
             return this.startFromRegistry(domainId, instanceId, 'sim-world');
         }
         // sim-experiment(기본): seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
@@ -481,7 +811,7 @@ class TwinEngine {
         const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } });
         const out = [];
         for (const r of rows) {
-            const board = r.board ?? { nodes: [], movers: [] };
+            const board = r.board ?? { locations: [], equipment: [] };
             const last = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).findOne({
                 where: { domain: { id: domainId }, instanceId: r.instanceId },
                 order: { revision: 'DESC' }
@@ -496,8 +826,8 @@ class TwinEngine {
                 copyOf: r.copyOf ?? undefined,
                 running: !!this.instances[r.instanceId],
                 revision: last?.revision ?? 0,
-                nodeCount: board.nodes?.length ?? 0,
-                moverCount: board.movers?.length ?? 0
+                locationCount: board.locations?.length ?? 0,
+                equipmentCount: board.equipment?.length ?? 0
             });
         }
         return out;
@@ -515,10 +845,10 @@ class TwinEngine {
             if (!r.spaceId || r.purpose === 'bench' || this.isBenchSpace(r.spaceId))
                 continue; // 벤치·잔재 제외
             const board = r.board ?? {};
-            const a = agg.get(r.spaceId) ?? { spaceId: r.spaceId, name: nameOf.get(r.spaceId) ?? r.spaceId, instances: 0, nodes: 0, movers: 0 };
+            const a = agg.get(r.spaceId) ?? { spaceId: r.spaceId, name: nameOf.get(r.spaceId) ?? r.spaceId, instances: 0, locations: 0, equipment: 0 };
             a.instances++;
-            a.nodes += board.nodes?.length ?? 0;
-            a.movers += board.movers?.length ?? 0;
+            a.locations += board.locations?.length ?? 0;
+            a.equipment += board.equipment?.length ?? 0;
             agg.set(r.spaceId, a);
         }
         return [...agg.values()];
@@ -559,7 +889,7 @@ class TwinEngine {
      * 노드타입은 커널 카탈로그로 검증(warning). start 는 호출측(bootstrap/mutation)이 결정.
      */
     static async ingestMaster(domainId, master) {
-        const { board, spaceContent, warnings } = (0, reference_master_js_1.masterToTwin)(master, DOMAIN_CATALOG);
+        const { board, spaceContent, warnings } = (0, reference_master_js_2.masterToTwin)(master, DOMAIN_CATALOG);
         const spaceId = board.spaceId;
         const repo = (0, shell_1.getRepository)(twin_space_js_1.TwinSpace);
         const existing = await repo.findOne({ where: { domain: { id: domainId }, spaceId } });
@@ -586,7 +916,17 @@ class TwinEngine {
             // areas 는 content 에 더 이상 쓰지 않는다(area 단일화 P3) — 권위=TwinArea. 아래 TwinArea 로만 기록.
             landmarks: unionById(prev.landmarks, cur.landmarks)
         };
-        const savedSpace = await repo.save(repo.create({ ...(existing ?? {}), domain: { id: domainId }, spaceId, name: existing?.name || master.siteName, content: mergedContent }));
+        /*
+         * **현장의 시각 기준을 공간에 남긴다** — 그러지 않으면 공간이 권위인데 그 값을 영원히 모른다.
+         *
+         * 마스터가 보드에 오프셋을 실어 주므로 갓 프로비저닝한 트윈은 맞게 돌지만, `withSpaceTimeBase` 가
+         * 읽는 곳은 **공간**이다. 여기서 옮기지 않으면 공간의 시간대가 계속 비어 있고, 사용자가 화면에서
+         * 그것을 보거나 고칠 수도 없다(만들고 잇지 않으면 없는 것이다).
+         *
+         * **사용자가 고친 값을 마스터가 덮지 않는다** — 이미 있으면 그대로 둔다(현장이 정본을 이긴다).
+         */
+        const timezone = existing?.timezone || master.space.timezone;
+        const savedSpace = await repo.save(repo.create({ ...(existing ?? {}), domain: { id: domainId }, spaceId, name: existing?.name || master.siteName, ...(timezone ? { timezone } : {}), content: mergedContent }));
         /*
          * 표현을 twin_space_representations 테이블에 저장한다 — 뷰(twin-map-page 등)는 content 가 아니라 테이블 표현을 소싱하므로,
          * 저장하지 않으면 인제스트 사이트에 "대표 표현" 이 없어 지도로 시작하지 못한다. rep.areas 가 있으면 TwinSpaceArea 도 함께 저장.
@@ -660,7 +1000,7 @@ class TwinEngine {
         /* 상태 출처 스왑 — sim: 커널 runtime, live: projector 미러(+OEE 계산 층 보강). 계약·payload 동일, 드라이버만 다름. */
         const st = inst.mode === 'live'
             ? inst.oee
-                ? (0, oee_accumulator_js_1.withLiveOee)(inst.projector?.snapshot?.(), inst.oee) // 관측 미러 + 계산(OEE) → mover payload 에 oee 포함(sim 동형)
+                ? (0, oee_accumulator_js_1.withLiveOee)(inst.projector?.snapshot?.(), inst.oee) // 관측 커널 + 계산(OEE) → equipment payload 에 oee 포함(sim 동형)
                 : inst.projector?.snapshot?.()
             : inst.runtime?.resync?.()?.state;
         if (!st)
@@ -690,7 +1030,7 @@ class TwinEngine {
     }
     static async persist(domainId, instanceId, msg) {
         const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
-        await repo.save(this.journalRow(repo, domainId, instanceId, msg.event, msg.revision));
+        await repo.save(this.journalRow(repo, domainId, instanceId, msg.event, msg.revision, await this.structureRevOf(domainId, instanceId)));
     }
     /**
      * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
@@ -720,17 +1060,67 @@ class TwinEngine {
             order: { revision: 'ASC' }
         });
         const cutoffMs = untilTime != null ? Date.parse(untilTime) : NaN;
-        const events = rows
-            .filter(r => {
+        const wanted = rows.filter(r => {
             if (untilTime != null && !Number.isNaN(cutoffMs)) {
                 const t = r.eventTime != null ? Date.parse(String(r.eventTime)) : NaN;
                 return Number.isNaN(t) ? true : t <= cutoffMs; // eventTime 없는 레거시 행은 포함(보수적)
             }
             return untilRevision == null || (r.revision ?? 0) <= untilRevision;
-        })
-            .map(r => r.payload)
-            .filter(Boolean);
-        return replay(reg.board, events);
+        });
+        /*
+         * **그때의 공장으로 접는다.**
+         *
+         * 예전에는 모든 이벤트를 지금 등록된 보드 하나로 접었다. 구조가 바뀐 적 없으면 맞지만, 바뀐
+         * 뒤에는 옛 사실을 새 공장에 대고 접게 되어 — 그때 없던 설비에서 일이 있었던 것처럼 보인다.
+         * (그래서 예전 프로비저닝은 구조가 바뀌면 저널을 아예 지웠다. 역사를 잃거나 거짓말을 하거나.)
+         *
+         * 이제 이벤트가 자기 구조를 달고 오므로, 리비전이 바뀌는 지점에서 구조를 갈아타며 이어 접는다.
+         * 리비전이 하나뿐이거나(대다수) 아예 없으면(구조 이력 이전) 예전과 똑같이 한 번에 접는다.
+         */
+        const structures = await (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure).find({
+            where: { domain: { id: domainId }, instanceId },
+            order: { rev: 'ASC' }
+        });
+        const boardOf = new Map(structures.map(x => [x.rev, x.board]));
+        /* 컬럼이 생기기 전 행은 리비전이 비어 있다 — **가장 오래된 구조**에 속한다(0 으로 채우지 않는다). */
+        const oldest = structures[0]?.rev;
+        const revOf = (r) => r.structureRev ?? oldest;
+        const segments = [];
+        for (const r of wanted) {
+            if (!r.payload)
+                continue;
+            const rev = revOf(r);
+            const board = (rev !== undefined && boardOf.get(rev)) || reg.board;
+            const last = segments[segments.length - 1];
+            if (last && last.board === board)
+                last.events.push(r.payload);
+            else
+                segments.push({ board, events: [r.payload] });
+        }
+        /*
+         * **가장 새 구조가 지금의 공장이다** — 그 아래에서 아직 아무 일도 없었더라도.
+         *
+         * 재프로비저닝 직후가 정확히 그 상태다: 부스를 넷 늘렸는데 새 이벤트는 아직 하나도 없다. 이때
+         * 마지막 이벤트의 구조로만 접으면 화면은 **옛 공장**을 보여준다 — 방금 늘린 것이 안 보인다.
+         * 그래서 마디의 끝에 지금 구조를 한 번 더 얹는다(이벤트 없는 마디).
+         *
+         * **다만 "지금" 을 물었을 때만이다.** 과거 시점을 물었는데 최신 구조를 얹으면, 그 시점에 없던
+         * 설비가 화면에 서고 — 이 작업이 막으려던 바로 그 거짓말이 된다.
+         */
+        const asOfNow = untilRevision == null && untilTime == null;
+        const newest = structures[structures.length - 1]?.board;
+        if (asOfNow && newest && segments[segments.length - 1]?.board !== newest)
+            segments.push({ board: newest, events: [] });
+        if (!segments.length)
+            return replay(((asOfNow && newest) || reg.board), []);
+        if (segments.length === 1)
+            return replay(segments[0].board, segments[0].events);
+        const { state, shifts } = replaySegments(segments);
+        /* 경계에서 사라진 것을 조용히 넘기지 않는다 — 수가 줄어든 이유를 어딘가에는 남겨야 한다. */
+        for (const sh of shifts)
+            if (sh.equipmentDropped || sh.locationsDropped || sh.personsDropped || sh.assetsDropped)
+                console.info(`[twin-engine] "${instanceId}" replay crossed a structure change — dropped ${sh.equipmentDropped} equipment, ${sh.locationsDropped} locations, ${sh.personsDropped} persons, ${sh.assetsDropped} assets that no longer exist.`);
+        return state;
     }
     /**
      * 공간(공동배치) 시각 범위 — 스크러버 앵커(runtime-state-model §4·§6). 그 공간 전 인스턴스 저널의 min/max eventTime.
@@ -793,6 +1183,21 @@ class TwinEngine {
     static owns(domainId, id) {
         return this.instances[id]?.domainId === domainId;
     }
+    /**
+     * 이 트윈이 이 테넌트 것인가 — **떠 있든 아니든.**
+     *
+     * `owns()` 는 **떠 있는** 런타임만 안다. 그것을 이력 조회의 관문으로 쓰면, 꺼진 트윈의 저널을
+     * 읽으려 할 때 "이 테넌트에 없다" 는 답이 돌아온다 — 두 가지가 틀렸다. 첫째, 저널은 트윈이 꺼져
+     * 있을 때 **가장 필요한 것**이다(그게 이력의 존재 이유다). 둘째, 그 문장은 남의 것이라는 뜻이라
+     * 사용자가 권한 문제로 오해한다. 실제로는 그냥 안 돌고 있을 뿐이다.
+     *
+     * 소유는 **등록부**가 안다. 이력·집계처럼 런타임과 무관한 질문은 이쪽에 묻는다.
+     */
+    static async ownsRegistered(domainId, instanceId) {
+        if (this.owns(domainId, instanceId))
+            return true;
+        return !!(await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } }));
+    }
     /** 라이브 커널(ForecastTwin) — forecast/divergence 예측 연산용. */
     static kernel(id) {
         return this.instances[id]?.kernel;
@@ -828,32 +1233,15 @@ class TwinEngine {
         }
         return rows;
     }
-    /**
-     * 라이브 예측용 임시 커널(kernel-unification P1) — 라이브는 projector 미러라 커널이 없어 예측을 못 한다.
-     * 관측 스냅샷(재고·무버·노드) + 저널의 오더 원값·라인을 hydrate 해 예측 가능한 임시 커널을 만든다.
-     * 라이브 런타임은 무간섭(이 커널은 fork 대상 임시본, instances 에 넣지 않음). sim 인스턴스면 null(그쪽은 kernel() 사용).
+    /*
+     * `buildForecastKernel` 은 **사라졌다**(통합 P3, 2026-08-01).
+     *
+     * 라이브가 `StateProjector` 였을 때는 커널이 없어서, 예측하려면 관측 스냅샷 + 저널의 오더 원값으로
+     * **일회용 커널을 세워야** 했다. 이제 라이브 인스턴스가 곧 커널이므로(`startLive`) 그 자리에서
+     * `fork` 하면 된다 — `TwinEngine.kernel(id)` 가 sim·live 둘 다 돌려준다.
+     *
+     * (오더 원값을 저널에서 되찾던 이유도 사라졌다 — 상태가 requested·fulfilled·lines 를 지킨다.)
      */
-    static async buildForecastKernel(domainId, instanceId) {
-        const inst = this.instances[instanceId];
-        if (inst?.mode !== 'live' || !inst.projector)
-            return null;
-        const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
-        if (!reg?.board)
-            return null;
-        const Kernel = KERNELS[reg.kind ?? 'wms'] ?? WmsKernel;
-        const k = new Kernel(domainId);
-        k.loadBoard(reg.board);
-        // 저널에서 오더별 최신 관측(원값+라인) 수집 — projector 스냅샷은 오더에 손실적(progress 만)이라 저널을 쓴다.
-        const rows = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order }, order: { revision: 'ASC' } });
-        const latest = new Map();
-        for (const r of rows) {
-            const d = r.payload?.data;
-            if (d?.orderId)
-                latest.set(d.orderId, d);
-        }
-        k.hydrateObserved(this.snapshot(instanceId), [...latest.values()]);
-        return k;
-    }
     /**
      * 예측용 커널을 **임의 시각 T 기준**으로 재구성 — 과거-vantage 예측(백테스트)·"그때 서서 본 미래".
      * recover(untilTime)로 T 시점 상태를, T 이하 오더 관측을 모아 hydrate → monteCarloForecast 가 T 에서 앞으로 굴린다.
@@ -864,8 +1252,10 @@ class TwinEngine {
         if (!reg?.board)
             return null;
         const Kernel = KERNELS[reg.kind ?? 'wms'] ?? WmsKernel;
-        const k = new Kernel(domainId);
+        const k = new Kernel(domainId, undefined, this.mesSpecOf(reg.board));
         k.loadBoard(reg.board);
+        this.applyOperations(k, reg.board, instanceId); // 예측도 같은 명세로 굴러야 한다(화면과 다른 숫자 금지)
+        await this.installEstimators(k, domainId, instanceId, reg.board); // 예측은 기다린다 — 실측을 놓치면 예측이 상수로 돈다
         const state = await this.recover(domainId, instanceId, undefined, untilTime).catch(() => null);
         if (!state)
             return null;
@@ -886,9 +1276,11 @@ class TwinEngine {
     static snapshot(id) {
         const inst = this.instances[id];
         if (inst?.mode === 'live' && inst.projector) {
-            // live: projector 미러 + 계산 층(OEE·attentions) 보강 → 질의(attention 등)가 sim 동형 스냅샷을 봄.
-            const st = inst.oee ? (0, oee_accumulator_js_1.withLiveOee)(inst.projector.snapshot(), inst.oee) : inst.projector.snapshot();
-            return (0, live_attentions_js_1.withLiveAttentions)(st);
+            /* live: **커널이 주목 신호를 스스로 낸다**(관측 모드) — 호스트가 덧붙이던 withLiveAttentions 는
+             * 필요 없다. OEE 만 호스트가 채운다: 원 시스템이 시간 누적을 보내 주지 않아 상태 전이를 적분해
+             * 만드는 값이라 커널이 대신할 수 없다(적합성 하네스의 유일한 예외). */
+            const st = inst.projector.snapshot();
+            return inst.oee ? (0, oee_accumulator_js_1.withLiveOee)(st, inst.oee) : st;
         }
         return inst?.runtime?.resync() ?? this.recovered[id];
     }