@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/engine/warm-start.ts

@@ -1,53 +1,238 @@
 /*
- * 웜스타트 판정 — **순수**. "기동하는 커널에 직전 상태를 심을 것인가, 심는다면 무엇을" 만 정한다.
+ * 웜스타트 판정 — **순수**. "기동하는 커널에 직전 상태를 주입할 것인가, 주입한다면 무엇을" 만 정한다.
  * 실제 주입(hydrateObserved 호출)과 로그는 엔진이 한다.
  *
  * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────
- * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 심어야 할 때 안 심으면 **있는 재고가 0 으로**
+ * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 주입해야 할 때 안 주입하면 **있는 재고가 0 으로**
  * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지
- * 말아야 할 벤치에 심으면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
+ * 말아야 할 벤치에 주입하면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
+ *
+ * ── 오더를 버리던 전제가 낡았다 (2026-08-05) ────────────────────────────────
+ * 예전 주석은 "스냅샷의 오더에는 progress 밖에 없어서 역산하면 없는 숫자를 지어내는 셈이므로
+ * 넘기지 않는다" 였다. 그때는 맞았다. 그러나 커널 `OrderState` 가 **원값을 되찾은 뒤**
+ * (`requested`·`fulfilled`·`lines`) 이 판정만 그대로 남아, 재기동하면 재고는 맞는데 **진행 중
+ * 주문이 통째로 사라진** 화면이 나왔다. 오류는 나지 않는다 — 그래서 오래 남아 있었다.
+ *
+ * 두 스냅샷 생산 경로가 모두 원값을 담는다: 시뮬은 커널 `snapshot()`, 라이브(미러)는
+ * `StateProjector` 다. 사람·자산·작업도 같은 스냅샷에 있고 커널이 심을 수 있는데 넘기지 않고 있었다.
+ * 그래서 씨앗을 **관측 스냅샷 전체**로 넓힌다.
+ *
+ * 다만 넓히면서 **조용한 누락을 만들지 않는다.** 원값이 없는 오더는 커널이 걸러 내므로(지어내지
+ * 않는다), 그 수를 여기서 세어 호출부가 말할 수 있게 한다. 세지 않으면 "주문이 없다" 와 "주문을
+ * 못 심었다" 가 화면에서 같아진다.
  */
 
-/** 커널에 심을 관측 상태 — 구조가 아니라 "무엇이 어디에 얼마나". */
+/**
+ * 커널에 심을 관측 상태 — 구조가 아니라 "무엇이 어디에 얼마나".
+ *
+ * 커널 `hydrateObserved` 가 받는 스냅샷 모양을 그대로 따른다. 여기서 골라 담지 않는 이유: 무엇을
+ * 심을 수 있는지는 커널이 알고, 그 규칙(고아 작업 제외·이행 완료 오더 제외 등)도 커널에 있다.
+ * 호스트가 미리 골라내면 규칙이 두 곳으로 갈린다.
+ */
 export interface ObservedSeed {
   locations: unknown[]
   items: unknown[]
   equipment: unknown[]
+  persons?: unknown[]
+  assets?: unknown[]
+  tasks?: unknown[]
+  orders?: unknown[]
+  /** 확인해 둔 주목 신호 id — 상태에서 파생되지 않아 반드시 함께 넘긴다. */
+  acked?: string[]
+  /**
+   * 주목 신호가 **처음 성립한 시각** — 확인과 같은 성질이다(계산으로 되살릴 수 없다).
+   *
+   * 넘기지 않으면 재기동 뒤 세 시간째 지속된 조건이 「0초째」로 되살아난다. 방금 찬 자리와 세 시간째
+   * 막힌 자리는 할 일이 다르므로, 그 값이 거짓이면 화면이 사람을 잘못된 순서로 움직인다.
+   */
+  attentionSince?: { id: string; since: string }[]
+}
+
+/** 심은 것의 내역 — 로그와 테스트가 같은 숫자를 본다. */
+export interface WarmStartCounts {
+  itemCount: number
+  equipmentCount: number
+  personCount: number
+  assetCount: number
+  taskCount: number
+  /** 원값(requested)이 있어 커널이 실제로 심을 수 있는 오더. */
+  orderCount: number
+  /** 이어받은 확인 처리 수 — 잃으면 확인해 둔 신호가 다시 빨개진다. */
+  ackedCount: number
+  /** 이어받은 시작 시각 수 — 잃으면 지속된 조건이 모두 「방금」이 된다. */
+  attentionSinceCount: number
+  /**
+   * 원값이 없어 심지 못하는 오더 — **0 이 아니면 반드시 말한다.**
+   * progress 만 있는 오더는 남은 수량을 알 수 없어 재계획의 근거가 되지 못한다. 지어내지 않고 뺀다.
+   */
+  ordersWithoutDemand: number
 }
 
 export type WarmStartPlan =
-  | { action: 'hydrate'; seed: ObservedSeed; itemCount: number; equipmentCount: number }
-  /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */
+  | ({ 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[]
+  equipment?: unknown[]
+  persons?: unknown[]
+  assets?: unknown[]
+  tasks?: unknown[]
+  orders?: unknown[]
+  acked?: string[]
+  attentionSince?: { id: string; since: string }[]
+}
+
+/** 관측 상태가 실려 있는지 — 축 하나라도 있으면 상태다(봉투에는 없다). */
+const looksLikeState = (x: any): boolean =>
+  !!x && typeof x === 'object' && ['locations', 'items', 'equipment', 'orders', 'tasks', 'persons', 'assets', 'acked'].some(k => k in x)
+
+/**
+ * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 조용히 죽던 자리.**
+ *
+ * `TwinEngine.snapshot()` 은 라이브에서는 상태를, 시뮬에서는 `runtime.resync()` 봉투(`{revision,state}`)를
+ * 돌려준다. 그 봉투를 다시 `{revision, state}` 로 감싸 캐시에 넣었으므로, 꺼낸 `state` 는 축이 하나도
+ * 없는 껍데기였다 → `planWarmStart` 가 "심을 것이 없다" 로 판정하고 **조용히** 넘어갔다. 저널에 수천 건이
+ * 있고 캐시도 최신인데 트윈이 빈 채로 떴다(오류도 로그도 없다).
+ *
+ * 반환 모양을 통일하는 것이 뿌리 수정이지만, 그 값은 State 구독 페이로드로도 나가므로 클라이언트 계약을
+ * 건드린다. 그래서 **복원 경로에서만** 벗긴다. 겹겹이 싸여 있어도 벗긴다(과거에 저장된 값이 남아 있다).
+ */
+export function unwrapState(x: any, depth = 4): any {
+  if (!x || typeof x !== 'object') return x
+  if (looksLikeState(x)) return x
+  if (depth > 0 && x.state && typeof x.state === 'object') return unwrapState(x.state, depth - 1)
+  return x
+}
+
+const arr = (v: unknown[] | undefined): unknown[] => (Array.isArray(v) ? v : [])
+
+/** 원값이 있는 오더인가 — 커널 `hydrateObserved` 의 판정(`requested !== undefined`)과 같은 기준. */
+const hasDemand = (o: unknown): boolean =>
+  !!o && typeof o === 'object' && (o as { requested?: unknown }).requested !== undefined
+
 /**
  * 무엇을 할지 정한다.
  *
- * **오더는 의도적으로 심지 않는다.** 커널의 관측 주입은 오더에 requested/fulfilled/lines 를 요구하는데
- * 스냅샷의 오더에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이므로
- * 넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작하는 편이 정직하다.
+ * 오더·작업·사람·자산도 함께 주입한다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),
+ * 여기서는 **심을 수 없는 오더의 수만 센다** — 호출부가 그 사실을 말할 수 있어야 하기 때문이다.
  */
-export function planWarmStart(
-  state: { locations?: unknown[]; items?: unknown[]; equipment?: unknown[] } | null | undefined,
-  purpose: string | undefined,
-  canHydrate: boolean
-): WarmStartPlan {
-  /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 심지 않는다는 사실이 바뀌지 않는다. */
+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' }
+  /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 조용히 죽는다(실제로 그랬다). */
+  state = unwrapState(state)
 
-  const locations = state.locations ?? []
-  const items = state.items ?? []
-  const equipment = state.equipment ?? []
-  /* 셋 다 비었으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */
-  if (locations.length === 0 && items.length === 0 && equipment.length === 0) return { action: 'skip', reason: 'no-state' }
+  const locations = arr(state.locations)
+  const items = arr(state.items)
+  const equipment = arr(state.equipment)
+  const persons = arr(state.persons)
+  const assets = arr(state.assets)
+  const tasks = arr(state.tasks)
+  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 && !attentionSince.length) {
+    return { action: 'skip', reason: 'no-state' }
+  }
+
+  /* 지원 여부는 마지막에 본다 — 주입할 것이 있는데 주입하지 못하는 상황이라야 경고할 가치가 있다. */
   if (!canHydrate) return { action: 'skip', reason: 'unsupported' }
 
-  return { action: 'hydrate', seed: { locations, items, equipment }, itemCount: items.length, equipmentCount: equipment.length }
+  const seedable = orders.filter(hasDemand)
+
+  return {
+    action: 'hydrate',
+    seed: {
+      locations,
+      items,
+      equipment,
+      ...(persons.length ? { persons } : {}),
+      ...(assets.length ? { assets } : {}),
+      ...(tasks.length ? { tasks } : {}),
+      /* 원값 없는 오더는 넘기지 않는다 — 커널도 걸러 내지만, 넘기지 않으면 세어 둔 수와 어긋날 일이 없다. */
+      ...(seedable.length ? { orders: seedable } : {}),
+      /* 확인 처리는 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 그 신호가 없으면 표시할 대상이 없다. */
+      ...(acked.length ? { acked } : {}),
+      /* 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 커널이 그 신호가 없으면 함께 지운다. */
+      ...(attentionSince.length ? { attentionSince } : {})
+    },
+    itemCount: items.length,
+    equipmentCount: equipment.length,
+    personCount: persons.length,
+    assetCount: assets.length,
+    taskCount: tasks.length,
+    orderCount: seedable.length,
+    ordersWithoutDemand: orders.length - seedable.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

@@ -0,0 +1,95 @@
+/*
+ * 사이트 발견 결과 — **"못 찾았다" 와 "없다" 를 구분한다.** 순수.
+ *
+ * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────
+ * 실 시스템을 연결해 "거기 있는 것" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이
+ * **"사이트를 찾지 못했습니다"** 라고만 말했다. 네 가지가 그 한 문장으로 접혀 있었다.
+ *
+ *  ① 그 레퍼런스가 등록돼 있지 않다        (`!ref → []`)
+ *  ② 어댑터 종류를 모른다                  (`!adapter → []`)
+ *  ③ 연결·조회가 실패했다                  (`catch { return [] }`)
+ *  ④ 정말로 사이트가 없다                  (빈 배열)
+ *
+ * ①②③ 은 **고칠 수 있는 문제**이고 ④ 는 사실이다. 그런데 화면이 같은 말을 하므로 사용자는 자격이
+ * 틀렸는지, 주소가 틀렸는지, 정말 공장이 없는지 알 수 없다 — 실 시스템 연결에서 가장 자주 막히는
+ * 자리인데 거기서 아무 단서도 주지 않았다.
+ *
+ * ── 왜 문장이 아니라 코드인가 ───────────────────────────────────────────────
+ * 이 프로젝트가 이미 쓰는 규약을 따른다(주의 신호·커맨드 거절·인제스트 경고와 같은 모양):
+ * `code`(언어 중립) + `params`(문장에 끼울 값) + `message`(영어 canonical, 로그·폴백).
+ * 화면은 `twin.connect.discover.<code>` 로 사람 말을 만든다.
+ *
+ * ── 원 시스템의 오류 문장을 감추지 않는다 ────────────────────────────────────
+ * 어댑터가 준 사유(자격 거부·타임아웃·404)는 **그 시스템만 아는 사실**이라 우리가 다시 쓸 수 없다.
+ * `detail` 로 그대로 실어 보내 화면이 보조 문장으로 보인다 — 원문이 있으면 사용자가 자기 관리자에게
+ * 물어볼 수 있고, 없으면 우리 짐작만 남는다.
+ */
+
+/** 발견이 왜 아무것도 주지 못했나 — 언어 중립 코드. */
+export type DiscoveryErrorCode = 'reference-not-found' | 'adapter-unknown' | 'discovery-failed' | 'discovery-timeout'
+
+export interface DiscoveryError {
+  code: DiscoveryErrorCode
+  params?: Record<string, string | number>
+  /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다. */
+  message: string
+}
+
+export interface DiscoveryResult<S = unknown> {
+  /** 발견된 사이트들. 실패했으면 빈 배열이고 `error` 가 이유를 말한다. */
+  sites: S[]
+  /** 실패 사유. **없으면 성공이다** — 빈 배열 + 사유 없음 = "연결은 됐지만 사이트가 없다". */
+  error?: DiscoveryError
+}
+
+/** 등록된 레퍼런스가 없다 — 목록이 낡았거나 다른 테넌트의 것이다. */
+export const referenceNotFound = (source: string): DiscoveryError => ({
+  code: 'reference-not-found',
+  params: { source },
+  message: `reference "${source}" is not registered in this tenant`
+})
+
+/** 어댑터 종류를 모른다 — 배포에 그 커넥터가 없다(패키지 미설치·오타). */
+export const adapterUnknown = (adapterType: string, source: string): DiscoveryError => ({
+  code: 'adapter-unknown',
+  params: { adapterType, source },
+  message: `no connector of type "${adapterType}" is available for reference "${source}"`
+})
+
+/** 연결·조회가 실패했다 — 원 시스템이 준 사유를 그대로 싣는다. */
+export const discoveryFailed = (source: string, detail: string): DiscoveryError => ({
+  code: 'discovery-failed',
+  params: { source, detail },
+  message: `could not read sites from "${source}": ${detail}`
+})
+
+/** 기다려도 답이 없었다 — 무한히 도는 화면보다 사유가 낫다. */
+export const discoveryTimedOut = (source: string, seconds: number): DiscoveryError => ({
+  code: 'discovery-timeout',
+  params: { source, seconds },
+  message: `"${source}" did not answer within ${seconds}s`
+})
+
+/**
+ * 어댑터가 준 것을 결과로 접는다.
+ *
+ * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
+ * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
+ * 말해야 한다. 실패로 합치면 사용자가 있지도 않은 문제를 찾는다.
+ */
+export function discovered<S>(sites: readonly S[] | undefined | null): DiscoveryResult<S> {
+  return { sites: Array.isArray(sites) ? [...sites] : [] }
+}
+
+/** 실패를 결과로 접는다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
+export function failed<S>(error: DiscoveryError): DiscoveryResult<S> {
+  return { sites: [], error }
+}
+
+/** 어댑터가 던진 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
+export function detailOf(e: unknown): string {
+  if (e instanceof Error && e.message) return e.message
+  if (typeof e === 'string' && e) return e
+  /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */
+  return 'the connector failed without a message'
+}

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

@@ -0,0 +1,104 @@
+/*
+ * 인제스트가 어느 공간으로 들어갈지 정한다 — **순수**.
+ *
+ * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────
+ * 한 현실(공장·물류센터)을 여러 렌즈가 비춘다: 창고(WMS)·공정(MES)·야드(YMS) 가 같은 부지에 있다.
+ * 엔진은 이미 그것을 지원한다 — 같은 `spaceId` 로 들어오면 공간 content 를 병합하고 기존 값을 이긴다.
+ *
+ * 그런데 **만드는 흐름에 그 선택이 없었다.** 템플릿은 `space.spaceId` 를 정하지 않으므로 항상
+ * `<source>-site` 로 파생돼, 새 트윈은 늘 새 현장처럼 생겼다. 데이터로는 가능한 일이 저작으로는
+ * 불가능했다.
+ *
+ * ── 없는 공간에 조용히 새 공간을 만들지 않는다 ────────────────────────────────
+ * "이 현장에 더한다" 는 요청이 오타·낡은 목록으로 빗나갔을 때 새 공간을 만들어 주면, 사용자는
+ * 합쳤다고 믿고 화면에서는 따로 놀게 된다 — 나중에 두 현장을 손으로 합쳐야 하고, 그때는 이미
+ * 이벤트가 양쪽에 쌓여 있다. 그래서 **모르는 공간이면 거절한다.**
+ *
+ * ── 같은 id 를 쓰는 구역은 조용히 합쳐지므로 알린다 ──────────────────────────
+ * 공간 content 의 구역·랜드마크는 id 로 합집합을 만든다(`unionById`). 두 렌즈가 우연히 같은 구역
+ * id(`a-yard` 따위)를 쓰면 서로 다른 구역이 하나로 접힌다. 막을 일은 아니다(같은 현장의 같은 구역을
+ * 가리키는 정당한 경우가 많다) — 다만 **모르고 지나가지 않게** 경고로 돌려준다.
+ */
+
+/** 공간 판정 결과. */
+export interface IngestSpaceChoice {
+  /** 실제로 쓸 공간 id. */
+  spaceId: string
+  /** 사용자가 기존 현장에 합치기를 골랐나(마스터가 파생한 공간과 다른 곳으로 들어가나). */
+  joined: boolean
+}
+
+/** 거절 사유 — 호출측이 문장을 만들 때 쓴다(언어 중립 코드). */
+export const INGEST_SPACE_NOT_FOUND = 'space-not-found'
+
+/**
+ * 요청받은 공간과 마스터가 파생한 공간 중 무엇으로 들어갈지 정한다.
+ *
+ * @param masterSpaceId 마스터에서 파생된 공간 id(요청이 없을 때의 기본).
+ * @param requested     사용자가 고른 기존 공간 id. 없으면 빈 값/undefined.
+ * @param requestedExists 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다).
+ * @throws 요청한 공간이 없으면 — 조용히 새로 만들지 않는다.
+ */
+export function resolveIngestSpace(masterSpaceId: string, requested: string | undefined | null, requestedExists: boolean): IngestSpaceChoice {
+  const want = (requested ?? '').trim()
+  if (!want) return { spaceId: masterSpaceId, joined: false }
+  if (!requestedExists) {
+    const e = new Error(`space "${want}" not found — cannot co-locate into a space that does not exist`)
+    ;(e as any).code = INGEST_SPACE_NOT_FOUND
+    throw e
+  }
+  /* 마스터가 이미 그 공간을 가리키면 합치기가 아니다 — 같은 공간의 재인제스트다. */
+  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
+}
+
+/**
+ * 합치는 쪽과 기존 쪽이 같은 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[])
+  const hits = new Set<string>()
+  for (const x of incoming ?? []) if (x?.id && have.has(x.id)) hits.add(x.id)
+  return [...hits].sort()
+}