@things-factory/headless-twin 10.0.5 → 10.0.7

package/server/engine/twin-engine.ts

@@ -2,7 +2,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)
  */
@@ -11,20 +11,30 @@ import { pubsub, getRepository, Domain } from '@things-factory/shell'
 import { cacheService } from '@things-factory/cache-service'
 
 import { TwinEvent } from '../service/twin-event/twin-event.js'
+import { twinEventKeys } from '../service/twin-event/twin-event-keys.js'
+import { planWarmStart } from './warm-start.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
+import { TwinStructure } from '../service/twin-structure/twin-structure.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
+import { utcOffsetOf } from '../service/reference/reference-master.js'
 import { TwinSpaceRepresentation } from '../service/twin-space/twin-space-representation.js'
 import { TwinSpaceArea } from '../service/twin-space/twin-space-area.js'
 import { TwinArea } from '../service/twin-space/twin-area.js'
 import { masterToTwin, type ReferenceMaster } from '../service/reference/reference-master.js'
+import { buildTravelEstimator, chainEstimators } from './travel-estimator.js'
+import { buildMeasuredEstimator } from './measured-estimator.js'
+import { describeModelBasis, type ModelBasis } from './model-basis.js'
+import { computeTwinKpi } from './kpi-query.js'
+import { createHash } from 'node:crypto'
+
 import { buildEntityDeltas } from './entity-delta.js'
+import { diffStructures, type StructureDiff } from './structure-diff.js'
 import { OeeAccumulator, withLiveOee } from './oee-accumulator.js'
-import { withLiveAttentions } from './live-attentions.js'
 
 import type { TwinKernel, BoardDef, SubscriptionMessage, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel'
 
 /* 커널 런타임 로드 — 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: Record<string, any> = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel }
 
@@ -62,8 +72,12 @@ interface InstanceRuntime {
   runtime?: TwinRuntimeType // sim: 커널 런타임(tick/subscribe/dispatch). live 는 projector 사용.
   kernel?: any // sim: ForecastTwin(fork/getSnapshot/tick/scenario). live 미사용.
   mode?: 'sim' | 'live' // 상태 드라이버 — sim=커널 tick / live=projector 미러(face2-inbound-live). 미지정=sim.
-  projector?: any // live: StateProjector(이벤트→State 재구성). sim 미사용.
-  oee?: OeeAccumulator // live: OEE 계산 층(이벤트 누적 → mover payload 보강). sim 은 커널이 계산.
+  /**
+   * live 의 상태 접근 어댑터 — 이제 **관측 모드 커널**을 가리킨다(`kernel` 과 같은 것).
+   * 이름은 소비처 호환으로 남았고, P3 에서 커널 어휘로 정리하면 사라진다.
+   */
+  projector?: any
+  oee?: OeeAccumulator // live: OEE 계산 층(이벤트 누적 → equipment payload 보강). sim 은 커널이 계산.
   unsub: () => void
   timer?: any
   /** 엔티티별 마지막 발행 시그니처 — 값이 바뀐 엔티티만 재발행(무변화 반복 push 방지). */
@@ -177,19 +191,202 @@ export class TwinEngine {
     }
   }
 
-  /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
-  static start(id: string, domainId: string, kind: string, board: BoardDef, realityMode?: RealityMode): InstanceRuntime {
+  /**
+   * 웜스타트 — 기동하는 커널에 **직전 관측 상태**를 심는다.
+   *
+   * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+   * `loadBoard` 는 **구조만** 싣는다(노드·무버). 상태(무엇이 어디에 얼마나)는 없다. 그래서 재기동한
+   * 트윈은 저널에 입고 540건이 남아 있어도 재고가 0 이었고, 화면은 "보유 중인 것이 없습니다" 라고
+   * 말했다 — 있는 재고를 없다고 하는 셈이다(2026-07-31 hatiolab-wms 실측으로 확인).
+   * `bootstrap()` 이 이미 체크포인트 캐시(없으면 저널 replay)로 상태를 복구해 `recovered` 에 담아 두는데,
+   * 기동 순간 그걸 **버리고** 있었다. 반만 연결돼 있던 장치를 잇는다.
+   *
+   * ── 정직한 한계 ─────────────────────────────────────────────────────────────
+   *  · **오더는 복원하지 않는다.** `hydrateObserved` 의 오더 인자는 requested/fulfilled/lines 를 요구하는데
+   *    스냅샷의 `OrderState` 에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이라
+   *    넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작한다.
+   *  · 진행 중 개별 task 의 내부 상태도 관측만으로는 복원되지 않는다(커널이 명시한 한계, 재계획에 맡김).
+   *  · 근본 해법(상태 영속 계약·revision 이어붙임)은 별도 과제.
+   *
+   * ── 벤치는 시드하지 않는다 ──────────────────────────────────────────────────
+   * 부하 벤치는 **새 시작에서 용량을 재는 것**이 목적이라 현재 상태를 심으면 측정이 오염된다.
+   */
+  private static warmStart(id: string, kernel: TwinKernel, purpose?: string): void {
+    const hydrate = (kernel as any).hydrateObserved
+    const plan = planWarmStart(this.recovered[id]?.state, purpose, typeof hydrate === 'function')
+
+    if (plan.action === 'skip') {
+      if (plan.reason === 'bench') {
+        console.log(`[twin-engine] "${id}" is a bench twin — starting empty on purpose (seeding would skew the measurement).`)
+      } else if (plan.reason === 'unsupported') {
+        console.warn(
+          `[twin-engine] kernel for "${id}" cannot be warm-started (no hydrateObserved) — it starts with structure only, so held stock will read as zero.`
+        )
+      }
+      return
+    }
+
+    hydrate.call(kernel, plan.seed)
+    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 + 레지스트리 영속. */
+  /**
+   * 공정 명세를 커널에 싣는다 — **시뮬레이션의 시간을 데이터가 말하게 하는 마지막 한 칸.**
+   *
+   * `board.operations`(마스터 인제스트가 통과시킨 ISA-95 OperationsSegment 명세)를 커널이 소비한다.
+   * 없으면 커널 기본 상수로 굴러가고, 커널 `specCoverage()` 가 무엇을 기본값으로 썼는지 보고한다.
+   *
+   * 커널이 아직 이 API 를 갖지 않은 버전이면(발행 이전) **조용히 넘어가지 않고 경고한다** — 명세를
+   * 선언했는데 반영되지 않는 상태를 모르고 지나가면, 예측이 상수로 돌아간 것을 아무도 알 수 없다.
+   */
+  private static applyOperations(kernel: any, board: any, id: string): void {
+    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: any, domainId: string, instanceId: string, board: any): Promise<void> {
+    if (!kernel || typeof kernel !== 'object') return
+    const travel = buildTravelEstimator({ layout: board?.layout, equipment: board?.equipment, unit: board?.unit })
+    const measured = await this.measuredEstimator(domainId, instanceId)
+    const chained = 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 로 재사용한다. 캐시는 인스턴스별이고, 만료 전에는 같은 값을 쓴다(예측 간 일관성도 얻는다).
+   */
+  private static measuredCache = new Map<string, { at: number; value: ReturnType<typeof buildMeasuredEstimator> | undefined }>()
+  private static readonly MEASURED_TTL_MS = 60_000
+
+  private static async measuredEstimator(domainId: string, instanceId: string) {
+    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: ReturnType<typeof buildMeasuredEstimator> | undefined
+    try {
+      /* 작업 종류별 실측 — 창은 넉넉히(하루) 두고 표본이 모자란 종류는 추정기가 스스로 뺀다. */
+      const kpi: any = await computeTwinKpi({ domainId, instanceId, windowMinutes: 24 * 60, groupBy: 'taskKind' })
+      value = buildMeasuredEstimator(kpi?.groups?.items, {})
+    } catch (err) {
+      console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, (err as any)?.message)
+    }
+    this.measuredCache.set(key, { at: Date.now(), value })
+    return value
+  }
+
+  /**
+   * 지금 이 트윈이 어떤 모델로 굴러가는가 — 예측 출력 보정이 **자기가 배운 모델**에만 적용되도록
+   * 비교하는 지문. 재료는 호스트가 아는 것(실측·속도·선언 명세)이라 커널 발행 상태와 무관하다.
+   * 실패하면 undefined — 그때는 비교를 하지 않는다(모르는 것을 근거로 보정을 끊지 않는다).
+   */
+  static async modelBasis(domainId: string, instanceId: string): Promise<ModelBasis | undefined> {
+    try {
+      const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+      const board: any = reg?.board
+      const measured = await this.measuredEstimator(domainId, instanceId)
+      const travel = 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: string,
+    target: { instanceId?: string; spaceId?: string },
+    unitsPerDay: number,
+    sampleWeekStartMs: number
+  ): Promise<{ instanceId: string; kind?: string; analysis?: any; reason?: 'not-running' | 'no-operations' }[]> {
+    /* 대상은 **등록부**가 정한다 — 떠 있는 런타임만 훑으면 "안 떠 있어서 안 보이는 것" 과 "없는 것" 이
+       구별되지 않는다. 화면은 그 둘을 다르게 말해야 한다. */
+    const where: any = { domain: { id: domainId } }
+    if (target.instanceId) where.instanceId = target.instanceId
+    else where.spaceId = target.spaceId
+    const registered = await getRepository(TwinInstance).find({ where })
+
+    return registered.map(reg => {
+      const rt = this.instances[reg.instanceId]
+      const kernel: any = rt?.domainId === domainId ? rt.kernel : undefined
+      if (typeof kernel?.capacity !== 'function') return { instanceId: reg.instanceId, kind: reg.kind, reason: 'not-running' as const }
+
+      const analysis = kernel.capacity({ unitsPerDay, sampleWeekStartMs })
+      /* 공정을 선언하지 않은 트윈(대개 YMS·WMS)은 **판정 대상이 아니다.** 0 으로 채워 넣으면
+         "야드가 병목" 이라는 없는 사실이 생긴다 — 잴 것이 없다고 말한다. */
+      if (!analysis?.operations?.length) return { instanceId: reg.instanceId, kind: reg.kind, reason: 'no-operations' as const }
+      return { instanceId: reg.instanceId, kind: reg.kind, analysis }
+    })
+  }
+
+  static start(id: string, domainId: string, kind: string, board: BoardDef, realityMode?: RealityMode, purpose?: string, resumeFrom?: number): InstanceRuntime {
     if (this.instances[id]) return this.instances[id]
 
     const Kernel = KERNELS[kind] ?? WmsKernel
-    const kernel: TwinKernel = new Kernel(domainId)
-    kernel.loadBoard(board)
+    const kernel: TwinKernel = 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 as any).resumeRevision === 'function') (kernel as any).resumeRevision(resumeFrom)
     const runtime: TwinRuntimeType = new TwinRuntime(kernel)
 
     /* subscribe 는 RuntimeSubscription({ unsubscribe() }) 반환 → () => void 로 감쌈. */
     const inst: InstanceRuntime = { id, domainId, runtime, kernel, realityMode: realityMode ?? DEFAULT_REALITY_MODE, unsub: () => {} }
     this.instances[id] = inst
-    delete this.recovered[id] // 라이브가 우선
+    delete this.recovered[id] // 웜스타트로 커널에 옮겨 심었다 — 이제 라이브가 진실이다.
 
     /* 라이브 바인딩(P3): data 채널 필터가 subdomain 을 보므로 Domain 객체를 1회 해석해 둔다. */
     getRepository(Domain).findOne({ where: { id: domainId } }).then(d => (inst.domain = d)).catch(() => {})
@@ -216,15 +413,66 @@ export class TwinEngine {
   }
 
   /**
-   * 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` — 레거시 경로 그대로다(기존 트윈의 거동을 바꾸지 않는다).
+   */
+  private static mesSpecOf(board: BoardDef | undefined): any {
+    return (board as any)?.mesSpec
+  }
+
+  /**
+   * 현장(공간)의 **시각 기준**을 보드에 얹는다 — 커널이 교대의 `HH:MM` 을 읽을 기준.
+   *
+   * **테넌트가 아니라 공간이 권위다.** 한 테넌트가 Rosarito(태평양)와 한국 공장을 함께 가질 수 있고,
+   * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 그래서 인스턴스가 묶인 공간의
+   * `timezone` 을 읽는다. 공간이 말하지 않으면 **테넌트로 내려가지 않는다** — 잘못된 입자로 답하는 것이
+   * 모르는 것보다 나쁘다(그때는 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다).
+   *
+   * 커널은 zero-dep 이라 시간대 데이터베이스를 갖지 않으므로 **분 오프셋**으로 풀어 넘긴다. 그 값은
+   * 지금 계절의 것이다(일광절약시간) — 계절을 넘는 긴 예측은 한 시간 어긋난다(계약에 명시).
+   */
+  static async withSpaceTimeBase(board: BoardDef, domainId: string, spaceId?: string): Promise<BoardDef> {
+    const sid = spaceId ?? (board as any)?.spaceId
+    if (!sid) return board
+    const space = await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId: sid } }).catch(() => null)
+    const offset = 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: string, domainId: string, kind: string, board: BoardDef): InstanceRuntime {
     if (this.instances[id]) return this.instances[id]
-    const projector = new StateProjector(board)
-    const inst: InstanceRuntime = { id, domainId, mode: 'live', realityMode: 'mirror', projector, oee: new OeeAccumulator(), unsub: () => {} }
+    const Kernel = KERNELS[kind] ?? WmsKernel
+    const kernel: any = new Kernel(domainId, undefined, this.mesSpecOf(board))
+    kernel.loadBoard(board)
+    this.applyOperations(kernel, board, id) // 명세는 라이브에도 실린다(예측 자격이 sim 과 같아진다)
+    /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
+     * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
+    const projector = { apply: (e: CanonicalEnvelope) => kernel.apply(e), snapshot: () => kernel.getSnapshot() }
+    const inst: InstanceRuntime = { id, domainId, mode: 'live', realityMode: 'mirror', kernel, projector, oee: new 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]
@@ -312,20 +560,48 @@ export class TwinEngine {
     if (!anyLive && this.broadcastTimer) { clearInterval(this.broadcastTimer); this.broadcastTimer = undefined } // live 없으면 tick 정지
   }
 
+  /**
+   * 저널 행 한 줄 — **기록 경로가 둘이라(라이브 벌크·심 단건) 행 모양은 반드시 한 곳에서 만든다.**
+   * 두 곳에 각자 적으면 승격 검색 키가 한쪽에만 채워지고, 반쯤 빈 색인은 "저널에는 있는데
+   * 검색으로는 안 나오는 이벤트" 를 만든다 — 저널에서 가장 나쁜 종류의 결함이다.
+   */
+  private static journalRow(repo: any, domainId: string, instanceId: string, e: any, revision: number, structureRev?: number) {
+    return repo.create({
+      domain: { id: domainId } as any,
+      instanceId,
+      tenantId: e?.tenantId,
+      eventType: e?.eventType,
+      revision,
+      /* **이 사실이 일어난 공장**을 함께 찍는다 — 이것이 없으면 나중에 구조가 바뀌었을 때 이 행을
+         새 공장에 대고 접게 되고, 그때 없던 설비에서 일이 있었던 것처럼 보인다. */
+      ...(structureRev === undefined ? {} : { structureRev }),
+      eventTime: e?.eventTime,
+      ...twinEventKeys(e),
+      payload: e
+    })
+  }
+
+  /**
+   * 이 트윈이 지금 어느 구조로 도는가 — 이벤트에 찍을 번호. 한 번 읽고 캐시한다(쓰기마다 조회 금지).
+   *
+   * 없으면 `undefined` 다 — 0 이 아니다. 구조 리비전이 생기기 전에 만들어진 트윈은 아직 리비전이
+   * 없고, 그 사실을 0 이라는 **유효해 보이는 번호**로 위장하면 안 된다.
+   */
+  private static structureRevCache: Record<string, number> = {}
+  static async structureRevOf(domainId: string, instanceId: string): Promise<number | undefined> {
+    const key = `${domainId}:${instanceId}`
+    const cached = this.structureRevCache[key]
+    if (cached !== undefined) return cached
+    const latest = await getRepository(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: string, instanceId: string, envelopes: any[], startRevision: number): Promise<void> {
     const repo = getRepository(TwinEvent)
-    const rows = envelopes.map((e, i) =>
-      repo.create({
-        domain: { id: domainId } as any,
-        instanceId,
-        tenantId: e?.tenantId,
-        eventType: e?.eventType,
-        revision: startRevision + i + 1,
-        eventTime: e?.eventTime,
-        payload: e
-      })
-    )
+    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 })
   }
 
@@ -358,26 +634,26 @@ export 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: string, instanceId: string): Promise<void> {
+  static async syncBoardEquipment(domainId: string, instanceId: string): Promise<void> {
     const inst = this.instances[instanceId]
     const snap = inst?.kernel?.getSnapshot?.()
-    if (!snap?.movers) return
+    if (!snap?.equipment) return
     const repo = getRepository(TwinInstance)
     const reg = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })
     if (!reg?.board) return
     const board = reg.board as BoardDef
-    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: any) => !known.has(m.id))
-      .map((m: any) => ({ id: m.id, kind: m.kind, homeNode: m.location }))
+      .map((m: any) => ({ 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)
   }
@@ -387,29 +663,133 @@ export class TwinEngine {
    * 재프로비전 시 구조 시그니처가 바뀌면(노드·무버 집합/속성 변경) 기존 저널을 purge 한다(ADR-0015):
    * board 는 replay 의 마스터라 구조가 바뀌면 과거 이벤트의 전제가 깨진다. 좌표(layout)만 바뀌면 저널 보존.
    */
-  static async provision(domainId: string, instanceId: string, kind: string, board: BoardDef): Promise<void> {
+  static async provision(domainId: string, instanceId: string, kind: string, board: BoardDef, comment?: string): Promise<void> {
     if (this.instances[instanceId]) throw new Error(`instance "${instanceId}" is running — stop before re-provisioning`)
     const repo = getRepository(TwinInstance)
     const existing = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })
 
-    if (existing?.board && this.structureSignature(existing.board as BoardDef) !== this.structureSignature(board)) {
-      await getRepository(TwinEvent).delete({ domain: { id: domainId } as any, 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 as any) ?? 'stopped')
   }
 
+  /**
+   * 이 구조를 리비전으로 남기고 그 번호를 돌려준다 — **바뀌었을 때만** 새 번호가 생긴다.
+   *
+   * 프로비저닝은 부팅마다 다시 도는데, 그때마다 리비전이 늘면 이력이 뜻 없는 마디로 잘게 쪼개진다.
+   * 그래서 **구조 서명이 같으면 있던 리비전을 그대로 쓴다.**
+   */
+  static async recordStructure(domainId: string, instanceId: string, board: BoardDef, comment?: string): Promise<number> {
+    const repo = getRepository(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 as BoardDef) === 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 } as any, instanceId, rev, signature, board: board as any, ...(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: string,
+    instanceId: string
+  ): Promise<{ rev: number; createdAt?: Date; comment?: string; events: number; diff: StructureDiff }[]> {
+    const revs = await getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'ASC' } })
+    if (!revs.length) return []
+
+    /* 리비전마다 그 아래에서 몇 건이 일어났나 — 이력의 무게를 보여준다(짧게 스쳐간 구조인지). */
+    const counts = new Map<number | null, number>()
+    for (const row of await getRepository(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: diffStructures(i === 0 ? undefined : (revs[i - 1].board as any), r.board as any)
+    }))
+  }
+
+  /** 지금 쓰이는 구조 리비전 — 이벤트에 찍을 번호. 아직 없으면 기록하며 만든다. */
+  static async currentStructureRev(domainId: string, instanceId: string, board?: BoardDef): Promise<number | undefined> {
+    const latest = await getRepository(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 는 거기서 터진다** — 개발에서는 멀쩡하고
+   * 운영에서만 죽는 종류의 실패다. 비교에만 쓰는 값이므로 해시로 충분하다.
+   */
+  private static structureFingerprint(board: BoardDef): string {
+    return createHash('sha256').update(this.structureSignature(board)).digest('hex')
+  }
+
   private static structureSignature(board: BoardDef): string {
-    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 인자 없이 저장된 구조로 재기동. */
@@ -417,7 +797,47 @@ export class TwinEngine {
     if (this.instances[instanceId]) return this.instances[instanceId]
     const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
     if (!reg?.board) throw new Error(`instance "${instanceId}" not provisioned (no board)`)
-    return this.start(instanceId, domainId, reg.kind ?? 'wms', reg.board as BoardDef, realityMode ?? (reg.realityMode as RealityMode) ?? undefined)
+
+    /*
+     * 웜스타트 재료를 **여기서 확실히 확보한다.**
+     * `start()` 는 동기라 스스로 캐시를 읽을 수 없어서 `recovered` 에 미리 담겨 있기를 기대하는데,
+     * 그건 `bootstrap()` 이 먼저 돌았을 때만 참이다. 부팅 순서에 기대면 어떤 날은 재고가 살아나고
+     * 어떤 날은 조용히 빈 채로 뜬다 — 재현되지 않는 결함이 가장 나쁘다.
+     * 체크포인트 캐시 우선(O(1) + 라이브 파생상태 보존), 없으면 저널 replay 폴백(부팅과 같은 순서).
+     */
+    if (!this.recovered[instanceId] && reg.purpose !== 'bench') {
+      const cached = await this.loadSnapshot(domainId, instanceId).catch(() => null)
+      if (cached?.state) {
+        this.recovered[instanceId] = { revision: cached.revision, state: cached.state }
+      } else {
+        const state = await this.recover(domainId, instanceId).catch(() => null)
+        if (state) this.recovered[instanceId] = { revision: state.revision, state }
+      }
+    }
+
+    /*
+     * 저널에 남아 있는 마지막 번호 — **모드와 무관하게** 이것을 이어 센다.
+     *
+     * 저널을 초기화하고 기동하는 모드(sim-experiment)라면 이 값이 0이라 아무 영향이 없다. 규칙을
+     * 모드별로 가르지 않는 이유: "저널이 비어 있지 않으면 그 뒤부터" 하나면 어느 모드에서도
+     * 겹칠 수 없고, 모드가 늘어도 이 자리를 다시 손볼 일이 없다.
+     */
+    const last = await getRepository(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 as BoardDef,
+      realityMode ?? (reg.realityMode as RealityMode) ?? undefined,
+      reg.purpose ?? undefined,
+      Number(last?.max ?? 0) || 0
+    )
   }
 
   /**
@@ -437,11 +857,18 @@ export class TwinEngine {
       return this.startLive(instanceId, domainId, reg.kind ?? 'wms', reg.board as BoardDef)
     }
     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 부터 재실행.
@@ -472,7 +899,7 @@ export class TwinEngine {
     const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId } } })
     const out: any[] = []
     for (const r of rows) {
-      const board = (r.board as BoardDef) ?? { nodes: [], movers: [] }
+      const board = (r.board as BoardDef) ?? { locations: [], equipment: [] }
       const last = await getRepository(TwinEvent).findOne({
         where: { domain: { id: domainId } as any, instanceId: r.instanceId },
         order: { revision: 'DESC' }
@@ -487,8 +914,8 @@ export 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
@@ -500,17 +927,17 @@ export class TwinEngine {
   }
 
   /** 운영 공간 목록(벤치 소스 선택기) — 이름·규모 포함, 벤치 사본·잔재 제외. */
-  static async listSpaces(domainId: string): Promise<{ spaceId: string; name: string; instances: number; nodes: number; movers: number }[]> {
+  static async listSpaces(domainId: string): Promise<{ spaceId: string; name: string; instances: number; locations: number; equipment: number }[]> {
     const nameOf = new Map((await getRepository(TwinSpace).find({ where: { domain: { id: domainId } } })).map(s => [s.spaceId, s.name]))
     const insts = await getRepository(TwinInstance).find({ where: { domain: { id: domainId } } })
-    const agg = new Map<string, { spaceId: string; name: string; instances: number; nodes: number; movers: number }>()
+    const agg = new Map<string, { spaceId: string; name: string; instances: number; locations: number; equipment: number }>()
     for (const r of insts) {
       if (!r.spaceId || r.purpose === 'bench' || this.isBenchSpace(r.spaceId)) continue // 벤치·잔재 제외
       const board: any = 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()]
@@ -578,7 +1005,17 @@ export 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 } as any, 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 } as any, spaceId, name: existing?.name || master.siteName, ...(timezone ? { timezone } : {}), content: mergedContent }))
     /*
      * 표현을 twin_space_representations 테이블에 저장한다 — 뷰(twin-map-page 등)는 content 가 아니라 테이블 표현을 소싱하므로,
      * 저장하지 않으면 인제스트 사이트에 "대표 표현" 이 없어 지도로 시작하지 못한다. rep.areas 가 있으면 TwinSpaceArea 도 함께 저장.
@@ -655,7 +1092,7 @@ export class TwinEngine {
     const st: any =
       inst.mode === 'live'
         ? inst.oee
-          ? withLiveOee(inst.projector?.snapshot?.(), inst.oee) // 관측 미러 + 계산(OEE) → mover payload 에 oee 포함(sim 동형)
+          ? withLiveOee(inst.projector?.snapshot?.(), inst.oee) // 관측 커널 + 계산(OEE) → equipment payload 에 oee 포함(sim 동형)
           : inst.projector?.snapshot?.()
         : inst.runtime?.resync?.()?.state
     if (!st) return
@@ -681,18 +1118,7 @@ export class TwinEngine {
 
   static async persist(domainId: string, instanceId: string, msg: any): Promise<void> {
     const repo = getRepository(TwinEvent)
-    const e = msg.event
-    await repo.save(
-      repo.create({
-        domain: { id: domainId } as any,
-        instanceId,
-        tenantId: e?.tenantId,
-        eventType: e?.eventType,
-        revision: msg.revision,
-        eventTime: e?.eventTime,
-        payload: e
-      })
-    )
+    await repo.save(this.journalRow(repo, domainId, instanceId, msg.event, msg.revision, await this.structureRevOf(domainId, instanceId)))
   }
 
   /**
@@ -721,18 +1147,65 @@ export class TwinEngine {
       order: { revision: 'ASC' }
     })
     const cutoffMs = untilTime != null ? Date.parse(untilTime) : NaN
-    const events = 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)
+    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
+    })
+
+    /*
+     * **그때의 공장으로 접는다.**
+     *
+     * 예전에는 모든 이벤트를 지금 등록된 보드 하나로 접었다. 구조가 바뀐 적 없으면 맞지만, 바뀐
+     * 뒤에는 옛 사실을 새 공장에 대고 접게 되어 — 그때 없던 설비에서 일이 있었던 것처럼 보인다.
+     * (그래서 예전 프로비저닝은 구조가 바뀌면 저널을 아예 지웠다. 역사를 잃거나 거짓말을 하거나.)
+     *
+     * 이제 이벤트가 자기 구조를 달고 오므로, 리비전이 바뀌는 지점에서 구조를 갈아타며 이어 접는다.
+     * 리비전이 하나뿐이거나(대다수) 아예 없으면(구조 이력 이전) 예전과 똑같이 한 번에 접는다.
+     */
+    const structures = await getRepository(TwinStructure).find({
+      where: { domain: { id: domainId }, instanceId },
+      order: { rev: 'ASC' }
+    })
+    const boardOf = new Map<number, BoardDef>(structures.map(x => [x.rev, x.board as BoardDef]))
+    /* 컬럼이 생기기 전 행은 리비전이 비어 있다 — **가장 오래된 구조**에 속한다(0 으로 채우지 않는다). */
+    const oldest = structures[0]?.rev
+    const revOf = (r: { structureRev?: number }): number | undefined => r.structureRev ?? oldest
 
-    return replay(reg.board as BoardDef, events)
+    const segments: { board: BoardDef; events: any[] }[] = []
+    for (const r of wanted) {
+      if (!r.payload) continue
+      const rev = revOf(r)
+      const board = (rev !== undefined && boardOf.get(rev)) || (reg.board as BoardDef)
+      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 as BoardDef | undefined
+    if (asOfNow && newest && segments[segments.length - 1]?.board !== newest) segments.push({ board: newest, events: [] })
+
+    if (!segments.length) return replay(((asOfNow && newest) || reg.board) as BoardDef, [])
+    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
   }
 
   /**
@@ -791,6 +1264,21 @@ export class TwinEngine {
     return this.instances[id]?.domainId === domainId
   }
 
+  /**
+   * 이 트윈이 이 테넌트 것인가 — **떠 있든 아니든.**
+   *
+   * `owns()` 는 **떠 있는** 런타임만 안다. 그것을 이력 조회의 관문으로 쓰면, 꺼진 트윈의 저널을
+   * 읽으려 할 때 "이 테넌트에 없다" 는 답이 돌아온다 — 두 가지가 틀렸다. 첫째, 저널은 트윈이 꺼져
+   * 있을 때 **가장 필요한 것**이다(그게 이력의 존재 이유다). 둘째, 그 문장은 남의 것이라는 뜻이라
+   * 사용자가 권한 문제로 오해한다. 실제로는 그냥 안 돌고 있을 뿐이다.
+   *
+   * 소유는 **등록부**가 안다. 이력·집계처럼 런타임과 무관한 질문은 이쪽에 묻는다.
+   */
+  static async ownsRegistered(domainId: string, instanceId: string): Promise<boolean> {
+    if (this.owns(domainId, instanceId)) return true
+    return !!(await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } }))
+  }
+
   /** 라이브 커널(ForecastTwin) — forecast/divergence 예측 연산용. */
   static kernel(id: string): any {
     return this.instances[id]?.kernel
@@ -827,26 +1315,15 @@ export 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: string, instanceId: string): Promise<any | null> {
-    const inst = this.instances[instanceId]
-    if (inst?.mode !== 'live' || !inst.projector) return null
-    const reg = await getRepository(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 as BoardDef)
-    // 저널에서 오더별 최신 관측(원값+라인) 수집 — projector 스냅샷은 오더에 손실적(progress 만)이라 저널을 쓴다.
-    const rows = await getRepository(TwinEvent).find({ where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order }, order: { revision: 'ASC' } })
-    const latest = new Map<string, any>()
-    for (const r of rows) { const d = (r.payload as any)?.data; if (d?.orderId) latest.set(d.orderId, d) }
-    k.hydrateObserved(this.snapshot(instanceId), [...latest.values()])
-    return k
-  }
 
   /**
    * 예측용 커널을 **임의 시각 T 기준**으로 재구성 — 과거-vantage 예측(백테스트)·"그때 서서 본 미래".
@@ -857,8 +1334,10 @@ export class TwinEngine {
     const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
     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 as BoardDef))
     k.loadBoard(reg.board as BoardDef)
+    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
     const cutoff = untilTime != null ? Date.parse(untilTime) : Infinity
@@ -877,9 +1356,11 @@ export class TwinEngine {
   static snapshot(id: string): any {
     const inst = this.instances[id]
     if (inst?.mode === 'live' && inst.projector) {
-      // live: projector 미러 + 계산 층(OEE·attentions) 보강 → 질의(attention 등)가 sim 동형 스냅샷을 봄.
-      const st = inst.oee ? withLiveOee(inst.projector.snapshot(), inst.oee) : inst.projector.snapshot()
-      return withLiveAttentions(st)
+      /* live: **커널이 주목 신호를 스스로 낸다**(관측 모드) — 호스트가 덧붙이던 withLiveAttentions 는
+       * 필요 없다. OEE 만 호스트가 채운다: 원 시스템이 시간 누적을 보내 주지 않아 상태 전이를 적분해
+       * 만드는 값이라 커널이 대신할 수 없다(적합성 하네스의 유일한 예외). */
+      const st = inst.projector.snapshot()
+      return inst.oee ? withLiveOee(st, inst.oee) : st
     }
     return inst?.runtime?.resync() ?? this.recovered[id]
   }