@things-factory/headless-twin 10.0.9 → 10.0.11

package/server/engine/warm-start.ts

@@ -1,11 +1,11 @@
 /*
- * 웜스타트 판정 — **순수**. "기동하는 커널에 직전 상태를 심을 것인가, 심는다면 무엇을" 만 정한다.
+ * 웜스타트 판정 — **순수**. "기동하는 커널에 직전 상태를 주입할 것인가, 주입한다면 무엇을" 만 정한다.
  * 실제 주입(hydrateObserved 호출)과 로그는 엔진이 한다.
  *
  * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────
- * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 심어야 할 때 안 심으면 **있는 재고가 0 으로**
+ * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 주입해야 할 때 안 주입하면 **있는 재고가 0 으로**
  * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지
- * 말아야 할 벤치에 심으면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
+ * 말아야 할 벤치에 주입하면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
  *
  * ── 오더를 버리던 전제가 낡았다 (2026-08-05) ────────────────────────────────
  * 예전 주석은 "스냅샷의 오더에는 progress 밖에 없어서 역산하면 없는 숫자를 지어내는 셈이므로
@@ -37,8 +37,15 @@ export interface ObservedSeed {
   assets?: unknown[]
   tasks?: unknown[]
   orders?: unknown[]
-  /** 확인해 둔 주목 신호 id — 상태에서 파생되지 않는 유일한 축이라 반드시 함께 넘긴다. */
+  /** 확인해 둔 주목 신호 id — 상태에서 파생되지 않아 반드시 함께 넘긴다. */
   acked?: string[]
+  /**
+   * 주목 신호가 **처음 성립한 시각** — 확인과 같은 성질이다(계산으로 되살릴 수 없다).
+   *
+   * 넘기지 않으면 재기동 뒤 세 시간째 지속된 조건이 「0초째」로 되살아난다. 방금 찬 자리와 세 시간째
+   * 막힌 자리는 할 일이 다르므로, 그 값이 거짓이면 화면이 사람을 잘못된 순서로 움직인다.
+   */
+  attentionSince?: { id: string; since: string }[]
 }
 
 /** 심은 것의 내역 — 로그와 테스트가 같은 숫자를 본다. */
@@ -52,6 +59,8 @@ export interface WarmStartCounts {
   orderCount: number
   /** 이어받은 확인 처리 수 — 잃으면 확인해 둔 신호가 다시 빨개진다. */
   ackedCount: number
+  /** 이어받은 시작 시각 수 — 잃으면 지속된 조건이 모두 「방금」이 된다. */
+  attentionSinceCount: number
   /**
    * 원값이 없어 심지 못하는 오더 — **0 이 아니면 반드시 말한다.**
    * progress 만 있는 오더는 남은 수량을 알 수 없어 재계획의 근거가 되지 못한다. 지어내지 않고 뺀다.
@@ -61,14 +70,14 @@ export interface WarmStartCounts {
 
 export type WarmStartPlan =
   | ({ action: 'hydrate'; seed: ObservedSeed } & WarmStartCounts)
-  /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */
+  /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 주입하면 측정이 오염된다. */
   | { action: 'skip'; reason: 'bench' }
   /** 심을 상태가 없다 — 처음 만든 트윈이거나 저널·체크포인트가 비었다. 정상이다. */
   | { action: 'skip'; reason: 'no-state' }
   /** 커널이 관측 주입을 지원하지 않는다 — 구조만으로 시작하므로 보유량은 0 으로 읽힌다(알려야 한다). */
   | { action: 'skip'; reason: 'unsupported' }
 
-/** 스냅샷이 들고 올 수 있는 관측 축 — 어느 것이든 있으면 심을 값어치가 있다. */
+/** 스냅샷이 들고 올 수 있는 관측 축 — 어느 것이든 있으면 주입할 가치가 있다. */
 interface ObservedState {
   locations?: unknown[]
   items?: unknown[]
@@ -78,6 +87,7 @@ interface ObservedState {
   tasks?: unknown[]
   orders?: unknown[]
   acked?: string[]
+  attentionSince?: { id: string; since: string }[]
 }
 
 /** 관측 상태가 실려 있는지 — 축 하나라도 있으면 상태다(봉투에는 없다). */
@@ -111,11 +121,11 @@ const hasDemand = (o: unknown): boolean =>
 /**
  * 무엇을 할지 정한다.
  *
- * 오더·작업·사람·자산도 함께 심는다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),
+ * 오더·작업·사람·자산도 함께 주입한다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),
  * 여기서는 **심을 수 없는 오더의 수만 센다** — 호출부가 그 사실을 말할 수 있어야 하기 때문이다.
  */
 export function planWarmStart(state: ObservedState | null | undefined, purpose: string | undefined, canHydrate: boolean): WarmStartPlan {
-  /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 심지 않는다는 사실이 바뀌지 않는다. */
+  /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 주입하지 않는다는 사실이 바뀌지 않는다. */
   if (purpose === 'bench') return { action: 'skip', reason: 'bench' }
   if (!state) return { action: 'skip', reason: 'no-state' }
   /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 조용히 죽는다(실제로 그랬다). */
@@ -130,13 +140,18 @@ export function planWarmStart(state: ObservedState | null | undefined, purpose:
   const orders = arr(state.orders)
   /* 확인 처리는 문자열 id 목록이다 — 배열이 아니면 없는 것으로 본다(지어내지 않는다). */
   const acked = Array.isArray(state.acked) ? state.acked.filter((x): x is string => typeof x === 'string') : []
+  /* 시작 시각은 {id, since} 쌍 목록이다 — 모양이 아니면 없는 것으로 본다(지어낸 시각을 심으면 화면이
+     「세 시간째」라고 거짓을 말한다. 모르면 그 신호는 이어붙는 순간이 새 시작이다). */
+  const attentionSince = Array.isArray(state.attentionSince)
+    ? state.attentionSince.filter((x: any): x is { id: string; since: string } => !!x && typeof x.id === 'string' && typeof x.since === 'string')
+    : []
 
   /* 어느 축도 없으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */
-  if (!locations.length && !items.length && !equipment.length && !persons.length && !assets.length && !tasks.length && !orders.length && !acked.length) {
+  if (!locations.length && !items.length && !equipment.length && !persons.length && !assets.length && !tasks.length && !orders.length && !acked.length && !attentionSince.length) {
     return { action: 'skip', reason: 'no-state' }
   }
 
-  /* 지원 여부는 마지막에 본다 — 심을 게 있는데 못 심는 상황이라야 경고할 값어치가 있다. */
+  /* 지원 여부는 마지막에 본다 — 주입할 것이 있는데 주입하지 못하는 상황이라야 경고할 가치가 있다. */
   if (!canHydrate) return { action: 'skip', reason: 'unsupported' }
 
   const seedable = orders.filter(hasDemand)
@@ -153,7 +168,9 @@ export function planWarmStart(state: ObservedState | null | undefined, purpose:
       /* 원값 없는 오더는 넘기지 않는다 — 커널도 걸러 내지만, 넘기지 않으면 세어 둔 수와 어긋날 일이 없다. */
       ...(seedable.length ? { orders: seedable } : {}),
       /* 확인 처리는 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 그 신호가 없으면 표시할 대상이 없다. */
-      ...(acked.length ? { acked } : {})
+      ...(acked.length ? { acked } : {}),
+      /* 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 커널이 그 신호가 없으면 함께 지운다. */
+      ...(attentionSince.length ? { attentionSince } : {})
     },
     itemCount: items.length,
     equipmentCount: equipment.length,
@@ -162,6 +179,60 @@ export function planWarmStart(state: ObservedState | null | undefined, purpose:
     taskCount: tasks.length,
     orderCount: seedable.length,
     ordersWithoutDemand: orders.length - seedable.length,
-    ackedCount: acked.length
+    ackedCount: acked.length,
+    attentionSinceCount: attentionSince.length
+  }
+}
+
+/*
+ * ── 미러(관측 구동) 재기동의 연속성 ─────────────────────────────────────────
+ *
+ * 미러의 진실은 원천이다. 그래서 재고·위치·설비 상태는 심지 않는다 — 다음 계측·다음 마스터 재읽기가
+ * 곧 정정하므로, 심으면 **떠난 물건이 되살아나는** 위험만 남는다(그래서 `startLive` 는 오랫동안 아무것도
+ * 심지 않았다).
+ *
+ * 그런데 원천이 **애초에 다시 말해 주지 않는 축**이 있다. 우리가 접어 만든 것들이다:
+ *  · 확인(ack)·조건이 처음 성립한 시각 — 사람이 한 일과 우리가 기억한 시각
+ *  · 에너지의 열린 구간 누적·적산 기준점·관측 이후 최대 — SCADA 는 「이번 15분에 지금까지 얼마」를 모른다
+ *
+ * 잃으면 **오류 없이 값이 작아진다**(실측 2026-08-18: 재기동 뒤 그 구간의 전력량·피크가 작아지고, 세
+ * 시간째 지속된 경보가 「0초째」가 됐다). 그래서 축을 갈라 되풀어 주지 않는 것만 이어받는다.
+ *
+ * 무엇을 이어받을지는 여기서 고르고, **어떻게 흡수할지는 커널이 정한다**(`hydrateContinuity`) — 도메인
+ * 규칙이 호스트로 새면 트윈마다 다른 답이 된다.
+ */
+export interface ContinuitySeed {
+  acked?: string[]
+  attentionSince?: { id: string; since: string }[]
+  energy?: unknown
+}
+
+export interface ContinuityPlan {
+  seed: ContinuitySeed
+  /** 무엇을 이어받았나 — 로그와 시험이 같은 숫자를 본다(0 이면 이어받을 것이 없었다는 사실이다). */
+  ackedCount: number
+  attentionSinceCount: number
+  /** 에너지 연속성을 이어받았나 — 열린 구간이 있으면 그 구간의 요금 근거가 살아난다. */
+  energy: boolean
+}
+
+/** 미러가 이어받을 축만 골라낸다 — 관측 축(재고·위치·설비)은 일부러 넣지 않는다. */
+export function planLiveContinuity(raw: unknown): ContinuityPlan {
+  const state = raw ? (unwrapState(raw as any) as any) : undefined
+  const acked = Array.isArray(state?.acked) ? state.acked.filter((x: any): x is string => typeof x === 'string') : []
+  const attentionSince = Array.isArray(state?.attentionSince)
+    ? state.attentionSince.filter((x: any): x is { id: string; since: string } => !!x && typeof x.id === 'string' && typeof x.since === 'string')
+    : []
+  /* 에너지는 커널이 자기 모양을 안다 — 호스트는 「있나」만 본다(골라 담으면 규칙이 두 곳으로 갈린다). */
+  const energy = state?.energy && typeof state.energy === 'object' ? state.energy : undefined
+  return {
+    seed: {
+      ...(acked.length ? { acked } : {}),
+      ...(attentionSince.length ? { attentionSince } : {}),
+      ...(energy ? { energy } : {})
+    },
+    ackedCount: acked.length,
+    attentionSinceCount: attentionSince.length,
+    energy: !!energy
   }
 }

package/server/index.ts

@@ -1,25 +1,28 @@
 export * from './engine/index.js'
 export * from './service/index.js'
+/* 스키마 이력 — 프레임워크가 `migrations` export 를 모아 실행한다(`run migration`). */
+export { migrations } from './migrations/index.js'
 
 import './routes.js'
 
 import { TwinEngine } from './engine/index.js'
-import { backfillTwinEventKeys } from './service/twin-event/backfill-keys.js'
+import { resumeReferenceLiveFeeds } from './service/reference/reference-live.js'
 
-/* 모듈 부팅 — 영속 인스턴스 복구 훅(향후). 지금은 명시 start(mutation/부팅 설정)로 인스턴스 생성. */
+/*
+ * 모듈 부팅 — **도는 트윈을 되살린다.**
+ *
+ * 두 층이 순서대로다: ① 엔진이 등록부의 `running` 행을 선언된 `realityMode` 그대로 되살리고
+ * (`bootstrap`), ② 레퍼런스 계층이 미러 트윈의 커넥터 피드를 다시 붙인다. 순서가 뒤집히면 피드가
+ * 아직 없는 커널에 계측을 붓게 된다.
+ *
+ * 예전에는 ①도 ②도 없었다 — 재기동 한 번에 등록부만 「도는 중」이라 말하는 트윈이 남았다.
+ */
 process.on('bootstrap-module-start' as any, async ({ app, config, client }: any) => {
   try {
     await TwinEngine.bootstrap()
+    await resumeReferenceLiveFeeds()
     console.log('Headless Twin host has started.')
   } catch (ex) {
     console.error('Headless Twin host failed to start.', ex)
   }
-
-  /*
-   * 승격 검색 키 백필 — 컬럼이 생기기 전에 쌓인 저널을 채운다. 멱등·재개 가능이라 매 기동 불러도
-   * 채울 게 없으면 조각 한 번 읽고 끝난다(로그도 남기지 않는다).
-   * 기동을 막지 않는다 — 저널이 크면 오래 걸릴 수 있고, 그동안 트윈은 정상 동작해야 한다.
-   * 실패해도 서비스는 계속된다: 못 채운 만큼 **과거 이력 검색이 덜 나올 뿐**이므로 조용히 삼키지 않고 알린다.
-   */
-  backfillTwinEventKeys().catch(ex => console.error('twin-event key backfill failed — search over older journal rows will be incomplete.', ex))
 })

package/server/migrations/1786000000000-RenameTwinInstanceBoardToModel.ts

@@ -0,0 +1,43 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+
+/**
+ * `twin_instances.model` → `twin_instances.model`.
+ *
+ * ── 왜 개명하나 ────────────────────────────────────────────────────────────────
+ * 이 컬럼이 담는 것은 커널이 `TwinModelDef` 라 부르는 **트윈 모델**이다. `board` 는 저장 위치의 옛
+ * 이름이고, 이 앱에는 **진짜 board 가 따로 있다**(things-scene 보드 — 공간 표현의 `boardId`). 같은
+ * 낱말이 두 가지를 뜻하니 읽는 사람이 매번 어느 쪽인지 판단해야 했고, 코드와 주석이 "board(마스터
+ * 청사진)" 처럼 번역을 달아 설명해 왔다. 커널이 이미 옳은 이름을 갖고 있으므로 발명할 이름도 없다.
+ *
+ * ── 데이터를 잃지 않는다 ──────────────────────────────────────────────────────
+ * `renameColumn` 은 값을 그대로 둔 채 이름만 바꾼다. 지우고 다시 만들면(엔티티 변경 + synchronize)
+ * 기존 트윈의 모델이 통째로 사라지고, 원천이 없는 트윈은 되살릴 방법이 없다.
+ *
+ * `renameColumn` API 만 쓰므로 지원 대상 5개 드라이버가 각자의 DDL 로 처리한다(raw SQL 금지 규약).
+ *
+ * ── 멱등 ──────────────────────────────────────────────────────────────────────
+ * 이미 `model` 이 있으면(엔티티 선언 + synchronize 가 먼저 지나간 경우) 아무것도 하지 않는다.
+ * 그 경우 옛 컬럼이 남아 있을 수 있는데 **지우지 않는다** — 값이 든 컬럼을 마이그레이션이 조용히
+ * 버리면 안 된다. 남은 컬럼의 처분은 사람이 확인한 뒤의 일이다.
+ */
+const TABLE_NAME = 'twin_instances'
+const OLD = 'board'
+const NEW = 'model'
+
+export class RenameTwinInstanceBoardToModel1786000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const table = await queryRunner.getTable(TABLE_NAME)
+    if (!table) return
+    const has = (name: string) => table.columns.some(c => c.name === name)
+    if (has(NEW) || !has(OLD)) return
+    await queryRunner.renameColumn(table, OLD, NEW)
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    const table = await queryRunner.getTable(TABLE_NAME)
+    if (!table) return
+    const has = (name: string) => table.columns.some(c => c.name === name)
+    if (has(OLD) || !has(NEW)) return
+    await queryRunner.renameColumn(table, NEW, OLD)
+  }
+}

package/server/migrations/index.ts

@@ -0,0 +1,7 @@
+/*
+ * 마이그레이션 묶음 — 프레임워크 규약(`@things-factory/shell` · `auth-base` 와 같은 방식).
+ * 파일마다 하나씩 export 하고 여기서 모아 `server/index.ts` 가 내보낸다.
+ */
+import { RenameTwinInstanceBoardToModel1786000000000 } from './1786000000000-RenameTwinInstanceBoardToModel.js'
+
+export const migrations = [RenameTwinInstanceBoardToModel1786000000000]

package/server/service/index.ts

@@ -1,5 +1,6 @@
 /* EXPORT ENTITY TYPES */
 export * from './twin-event/twin-event.js'
+export * from './twin-audit/twin-audit-event.js'
 export * from './twin-instance/twin-instance.js'
 export * from './twin-space/twin-space.js'
 export * from './twin-space/twin-space-representation.js'
@@ -18,6 +19,7 @@ export * from './twin-lifecycle/domain-catalog.js'
 
 /* IMPORT ENTITIES AND RESOLVERS */
 import { entities as TwinEventEntities } from './twin-event/index.js'
+import { entities as TwinAuditEntities, resolvers as TwinAuditResolvers } from './twin-audit/index.js'
 import { entities as TwinInstanceEntities } from './twin-instance/index.js'
 import { entities as TwinStructureEntities } from './twin-structure/index.js'
 import { entities as TwinSpaceEntities, resolvers as TwinSpaceResolvers } from './twin-space/index.js'
@@ -25,6 +27,7 @@ import { entities as TwinTargetEntities, resolvers as TwinTargetResolvers } from
 import { entities as TwinReferenceEntities, resolvers as TwinReferenceResolvers } from './reference/index.js'
 import { resolvers as TwinStateResolvers } from './twin-state/index.js'
 import { resolvers as TwinControlResolvers } from './twin-control/index.js'
+import { entities as TwinModelEntities, resolvers as TwinModelResolvers } from './twin-model/index.js'
 import { resolvers as TwinLifecycleResolvers } from './twin-lifecycle/index.js'
 import { resolvers as TwinJournalResolvers } from './twin-journal/index.js'
 import { resolvers as TwinForecastResolvers } from './twin-forecast/index.js'
@@ -34,11 +37,14 @@ import { resolvers as TwinMetricsResolvers } from './twin-metrics/index.js'
 export const entities = [
   /* ENTITIES */
   ...TwinEventEntities,
+  ...TwinAuditEntities,
   ...TwinInstanceEntities,
   ...TwinStructureEntities,
   ...TwinSpaceEntities,
   ...TwinTargetEntities,
-  ...TwinReferenceEntities
+  ...TwinReferenceEntities,
+  /* 구조 투영 — model JSON 에서 풀어낸 표준 엔티티(ADR-0032). 원본에서 온 캐시. */
+  ...TwinModelEntities
 ]
 
 export const subscribers = []
@@ -51,9 +57,11 @@ export const schema = {
     ...TwinControlResolvers,
     ...TwinLifecycleResolvers,
     ...TwinJournalResolvers,
+    ...TwinAuditResolvers,
     ...TwinForecastResolvers,
     ...TwinAttentionResolvers,
     ...TwinMetricsResolvers,
+    ...TwinModelResolvers,
     ...TwinSpaceResolvers,
     ...TwinTargetResolvers,
     ...TwinReferenceResolvers

package/server/service/reference/discovery-result.ts

@@ -1,5 +1,5 @@
 /*
- * 사이트 발견 결과 — **"못 찾았다" 와 "없다" 를 가른다.** 순수.
+ * 사이트 발견 결과 — **"못 찾았다" 와 "없다" 를 구분한다.** 순수.
  *
  * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────
  * 실 시스템을 연결해 "거기 있는 것" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이
@@ -75,7 +75,7 @@ export const discoveryTimedOut = (source: string, seconds: number): DiscoveryErr
  *
  * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
  * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
- * 말해야 한다. 실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다.
+ * 말해야 한다. 실패로 합치면 사용자가 있지도 않은 문제를 찾는다.
  */
 export function discovered<S>(sites: readonly S[] | undefined | null): DiscoveryResult<S> {
   return { sites: Array.isArray(sites) ? [...sites] : [] }

package/server/service/reference/ingest-space.ts

@@ -51,6 +51,40 @@ export function resolveIngestSpace(masterSpaceId: string, requested: string | un
   return { spaceId: want, joined: want !== masterSpaceId }
 }
 
+/**
+ * 실 시스템 import 가 현장을 고를 때의 거절 판정 — **순수**.
+ *
+ * 레퍼런스 하나는 사이트를 여럿 발견할 수 있고(`discoverSites`), 그 사이트마다 트윈이 하나씩 생긴다.
+ * 그런데 "이 현장에 더한다" 는 **한 곳**을 가리키는 말이다. 사이트 여럿을 한 공간에 넣으면 서로 다른
+ * 현장의 구역·랜드마크가 id 로 합쳐지고(`unionById`), 그 사실을 알아차릴 때는 이미 이벤트가 양쪽에
+ * 쌓여 있다 — 손으로 되돌릴 수 없는 종류다. 그래서 **묻지 않고 합치지 않고, 거절한다.**
+ *
+ * 공간을 고르지 않으면 지금까지의 거동 그대로다: 사이트마다 마스터가 파생한 공간으로 들어간다.
+ */
+export type ImportSpaceRefusalCode = 'space-with-multiple-sites'
+
+export interface ImportSpaceRefusal {
+  code: ImportSpaceRefusalCode
+  params?: Record<string, string | number>
+  /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다(발견 오류와 같은 규약). */
+  message: string
+}
+
+/**
+ * @param siteCount 실제로 만들 사이트 수(필터 적용 후).
+ * @param requested 사용자가 고른 기존 공간 id. 없으면 판정할 것이 없다.
+ * @returns 거절 사유. 없으면 진행해도 된다.
+ */
+export function refuseImportSpace(siteCount: number, requested?: string | null): ImportSpaceRefusal | undefined {
+  const want = (requested ?? '').trim()
+  if (!want || siteCount <= 1) return undefined
+  return {
+    code: 'space-with-multiple-sites',
+    params: { spaceId: want, count: siteCount },
+    message: `cannot co-locate ${siteCount} sites into space "${want}" — pick one site, or omit the space so each site gets its own`
+  }
+}
+
 /** 구역·랜드마크처럼 id 로 합쳐지는 것들. */
 interface Identified {
   id?: string
@@ -60,7 +94,7 @@ interface Identified {
  * 합치는 쪽과 기존 쪽이 같은 id 를 쓰는 것들을 찾아 경고 문장을 만든다.
  *
  * 정당한 경우(같은 현장의 같은 구역)와 사고(서로 다른 구역이 우연히 같은 이름)를 기계가 가릴 수는
- * 없다. 가릴 수 없는 것을 고르지 않고, **무엇이 합쳐졌는지 말한다.**
+ * 없다. 구분할 수 없는 것을 고르지 않고, **무엇이 합쳐졌는지 말한다.**
  */
 export function collidingIds(existing: readonly Identified[] | undefined | null, incoming: readonly Identified[] | undefined | null): string[] {
   const have = new Set((existing ?? []).map(x => x?.id).filter(Boolean) as string[])

package/server/service/reference/reference-live.ts

@@ -1,5 +1,9 @@
+import { getRepository } from '@things-factory/shell'
+
 import { getAdapter, type ConnectionConfig, type SiteDescriptor } from './reference-adapter.js'
-import { TwinEngine, ingestCanonicalRecords, type CanonicalRecord } from '../../engine/index.js'
+import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinReference } from './twin-reference.js'
 
 /*
  * 커넥터 기반 라이브 피드 결선(reference → live, §0 프레임 ① realityMode='mirror').
@@ -27,11 +31,11 @@ export async function startReferenceLiveFeed(
   if (!adapter?.openLiveFeed) return false
 
   const det = await TwinEngine.detail(domainId, instanceId)
-  if (!det?.board) throw new Error(`instance "${instanceId}" not provisioned (no board) — ingest master before live start`)
+  if (!det?.model) throw new Error(`instance "${instanceId}" not provisioned (no model) — ingest master before live start`)
 
   // mirror 모드 기동 — 커널 tick 없이 projector 가 실 이벤트를 미러(startLive 가 realityMode='mirror' 설정).
   // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
-  TwinEngine.startLive(instanceId, domainId, det.kind ?? 'wms', await TwinEngine.withSpaceTimeBase(det.board, domainId))
+  TwinEngine.startLive(instanceId, domainId, det.kind, await TwinEngine.withSpaceTimeBase(det.model, domainId))
 
   stopReferenceLiveFeed(instanceId) // 재기동 시 이전 피드 정리
   const unsubscribe = adapter.openLiveFeed(cfg, site, (records: unknown[]) => {
@@ -39,8 +43,19 @@ export async function startReferenceLiveFeed(
       stopReferenceLiveFeed(instanceId) // 인스턴스 사라지면 자가 정지(안전망)
       return
     }
-    const { accepted } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
+    const { accepted, rejected } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
     if (accepted.length) TwinEngine.ingestLive(domainId, instanceId, accepted)
+    /*
+     * **거부한 것을 조용히 버리지 않는다.** 예전에는 `rejected` 를 받지도 않았다 — 커넥터의 매핑이
+     * 틀리면 트윈은 「아무 일도 일어나지 않는」 모습이 되고, 로그에도 아무 흔적이 없었다.
+     *
+     * 지금은 이유와 함께 남긴다. 화면까지 나르는 것은 다음 일이다(라이브 계측은 초당 여러 건이라
+     * 건마다 방송하면 그 자체가 부하가 된다 — 집계해 낼 자리가 필요하다).
+     */
+    if (rejected.length) {
+      const why = rejected[0]?.errors?.join(' · ') ?? 'unknown'
+      console.warn(`[twin-live] "${instanceId}": ${rejected.length} record(s) rejected — e.g. ${why}`)
+    }
   })
   feeds.set(instanceId, unsubscribe)
   return true
@@ -60,5 +75,105 @@ export function listReferenceLiveFeeds(): string[] {
   return [...feeds.keys()]
 }
 
+/**
+ * 부팅 때 **끊어진 피드를 다시 붙인다** — 도는 미러 트윈에 계측이 계속 들어오게.
+ *
+ * ── 무엇이 조용히 끊겼나 (2026-08-14) ───────────────────────────────────────
+ * `startReferenceLiveFeed` 를 부르는 곳은 `importTwinReference` **하나뿐**이었다. 그래서 서버를 한 번
+ * 재기동하면 미러 트윈은 「도는 중」이라 말하면서 아무 계측도 받지 않았다 — 오류도 로그도 없이,
+ * 사람은 「값이 안 변하네」로 알게 된다. 실 배포에서 재기동 한 번에 계측이 멈추는 셈이다.
+ *
+ * ── 되살릴 재료는 이미 영속돼 있다 ─────────────────────────────────────────
+ * `TwinReference` 가 어댑터 종류·접속 설정·그 레퍼런스가 만든 인스턴스(`scopeSpec.produced`)를 들고 있다.
+ * 사이트 서술자만 없는데(`hint` 는 남기지 않았다) **다시 찾아서** 얻는다(`discoverSites`) — 인제스트가
+ * 걷는 것과 같은 길이므로 규칙이 갈라지지 않는다. 되살릴 인스턴스가 없으면 그 호출도 하지 않는다.
+ *
+ * 재개 대상은 **등록부가 도는 미러라고 말하는 것**뿐이다: 멈춘 트윈을 되살리면 사람이 멈춘 것을
+ * 우리가 다시 켜는 것이고, 시뮬 트윈에 실 계측을 부으면 두 현실이 섞인다.
+ */
+export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; failed: { instanceId: string; error: string }[] }> {
+  const resumed: string[] = []
+  const failed: { instanceId: string; error: string }[] = []
+  /*
+   * **한 트윈에 피드는 하나다** (2026-08-18).
+   *
+   * 같은 사이트를 두 레퍼런스가 각각 인제스트하면 둘 다 그 인스턴스를 자기가 만든 것(`produced`)으로
+   * 들고 있다. 기동 때 그 목록을 그대로 돌면 같은 트윈에 피드를 두 번 붙이는데, 붙이는 함수가 미러를
+   * 다시 세우므로(`startLive`) **먼저 쌓인 수요 구간이 리셋된다** — 실제로 그렇게 났다
+   * (로그: `reattached 2 feed(s): ems-plant-1, ems-plant-1`).
+   *
+   * 그러니 한 번만 붙이고, **두 레퍼런스가 같은 트윈을 주장한다는 사실은 말한다** — 조용히 하나를
+   * 고르면 어느 접속이 그 트윈을 먹이고 있는지 아무도 모르게 된다.
+   */
+  const attached = new Map<string, string>() // instanceId → 먼저 붙인 레퍼런스
+  try {
+    const refs = await getRepository(TwinReference).find({ where: { status: 'connected' }, relations: ['domain'] })
+    for (const ref of refs) {
+      const domainId = (ref as any).domain?.id ?? (ref as any).domainId
+      const adapter = getAdapter(ref.adapterType)
+      if (!domainId || !adapter?.openLiveFeed) continue // 관측만 하는 어댑터에는 되살릴 피드가 없다
+
+      const produced: any[] = ((ref.scopeSpec as any)?.produced ?? []).filter((p: any) => p?.instanceId && p?.siteId)
+      if (!produced.length) continue
+
+      /* 등록부가 「도는 미러」라고 말하는 것만 고른다. */
+      const rows = await getRepository(TwinInstance).find({
+        where: produced.map((p: any) => ({ domain: { id: domainId }, instanceId: p.instanceId })) as any
+      })
+      const live = produced.filter((p: any) =>
+        rows.some(r => r.instanceId === p.instanceId && r.status === 'running' && r.realityMode === 'mirror')
+      )
+      if (!live.length) continue
+
+      let sites: SiteDescriptor[]
+      try {
+        sites = await adapter.discoverSites(ref.connectionConfig ?? {})
+      } catch (e: any) {
+        /* 원 시스템이 아직 안 떴을 수 있다 — 지어내지 않고 그렇게 적는다(트윈은 계속 「도는 미러」다). */
+        for (const p of live) failed.push({ instanceId: p.instanceId, error: `discover failed: ${e?.message ?? 'unknown'}` })
+        continue
+      }
+
+      for (const p of live) {
+        const site = sites.find(s => s.siteId === p.siteId)
+        if (!site) {
+          failed.push({ instanceId: p.instanceId, error: `site "${p.siteId}" no longer discoverable` })
+          continue
+        }
+        const owner = attached.get(p.instanceId)
+        if (owner) {
+          /* 두 접속이 같은 트윈을 주장한다 — 먼저 붙은 것을 지키고, 그 사실을 남긴다(둘 다 붙이면 미러가 리셋된다). */
+          failed.push({
+            instanceId: p.instanceId,
+            error: `also claimed by reference "${ref.source}" — kept the feed from "${owner}" (two connections feeding one twin would reset the mirror)`
+          })
+          continue
+        }
+        attached.set(p.instanceId, ref.source)
+        try {
+          const ok = await startReferenceLiveFeed(domainId, ref.adapterType, ref.connectionConfig ?? {}, site, p.instanceId)
+          if (ok) resumed.push(p.instanceId)
+          else failed.push({ instanceId: p.instanceId, error: 'adapter has no openLiveFeed' })
+        } catch (e: any) {
+          failed.push({ instanceId: p.instanceId, error: e?.message ?? 'reattach failed' })
+        }
+      }
+    }
+  } catch (e: any) {
+    console.error('[twin-live] feed resume scan failed', e?.message)
+  }
+
+  if (resumed.length) console.log(`[twin-live] reattached ${resumed.length} feed(s): ${resumed.join(', ')}`)
+  /* **조용히 넘기지 않는다** — 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다. */
+  for (const f of failed) console.warn(`[twin-live] "${f.instanceId}" feed NOT reattached — ${f.error}`)
+  return { resumed, failed }
+}
+
+/*
+ * 이 계층의 피드 장부를 등록한다 — 화면이 「끊김」을 말할 근거는 **묻는 자리 하나**여야 한다.
+ * (프리셋 기반 피드는 앱이 자기 장부를 따로 등록한다. 한쪽만 보면 흐르는 트윈을 끊겼다고 부른다.)
+ */
+registerLiveFeedProbe(() => [...feeds.keys()])
+
 /* 인스턴스 정지 시 피드 자동 정리(생명주기 대칭). */
 TwinEngine.onStop(instanceId => stopReferenceLiveFeed(instanceId))