@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -1,20 +1,28 @@
 /*
  * Face2 마스터 인제스트(ADR-0018 반영 모드) — 레퍼런스 시스템(실 WMS/YMS/MES 또는 가상 레퍼런스)의
- * 마스터를 읽어 트윈 구조(BoardDef) + 공간(Space content)을 생성. 손배선이 아니라 인제스트로 엔티티가 흐른다.
+ * 마스터를 읽어 트윈 구조(TwinModelDef) + 공간(Space content)을 생성. 손배선이 아니라 인제스트로 엔티티가 흐른다.
  *
  * 규율(ADR-0018): 도메인 타입(location.type=노드용)은 커널 카탈로그 어휘를 그대로 반영(발명 금지).
- * location 은 role 로 노드(운영점)·area(공간영역)·both 를 구분 — 노드→BoardDef, area→Space.areas.
+ * location 은 role 로 노드(운영점)·area(공간영역)·both 를 구분 — 노드→TwinModelDef, area→Space.areas.
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
-import type { EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel'
+import type { DomainSystem, EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel'
 
 export interface RefLocation {
   id: string
   type: string // 노드는 커널 노드타입(dock/storage/yard-slot…), area 는 공간 region 타입
   name?: string
+  description?: string
   role: 'location' | 'area' | 'both'
   parentId?: string
+  /**
+   * **전기적으로 어디서 받는가** — 이 자리에 전기를 주는 상류 자리(커널 계약의 `upstreamId`).
+   *
+   * `parentId`(공간 포함)와 따로 두는 이유는 커널 계약에 적혀 있다. 여기서 빠뜨리면 마스터가 말한 계통이
+   * 모델까지 오지 못하고, 뿌리 계량 판정이 분기 계량기까지 뿌리로 세어 **부하가 두 배로** 보인다.
+   */
+  upstreamId?: string
   /** 저장 용량 — 이 자리에 동시에 놓일 수 있는 물품 수. */
   capacity?: number
   /**
@@ -30,6 +38,14 @@ export interface RefLocation {
    * 짐작해 채우지 않는다.
    */
   level?: EquipmentLevel
+  /**
+   * 자리의 **열린 속성** — 표준 `OperationalLocationProperty`(설비·사람·자산과 같은 모양).
+   *
+   * 무엇이 여기 실리나: **자리의 물리량**이다. 에너지의 계약전력(`contract.kW`)이 첫 사례다 —
+   * 그 값이 앉을 자리가 없어서 EMS 커널은 계약 대비 판정을 할 수 없었다(자리가 없으면 사실이
+   * 들어오지 못한다). 커널은 자기가 **읽는** 속성 id 만 선언하고(`EMS_PROPERTY`) 나머지는 나른다.
+   */
+  properties?: RefResourceProperty[]
   footprint?: { x: number; y: number; w: number; h: number } // 있으면 area 기하 + 노드 중심좌표
   gs1Id?: string // 정식 GS1 정체성(§J) — 위치=SGLN. 결합(tag)/추적 canonical id. 받아들이기 경계서 부여(로컬 id=name/xref 로 보존).
 }
@@ -85,9 +101,42 @@ export interface RefResourceClass {
   effectiveEnd?: string
 }
 
+/**
+ * 검사 명세 — **자원이 가리키는 대상**(ISA-95 `TestSpecification`).
+ *
+ * 표준 필드는 셋만 담는다(`ID`·`Description`·`Version`) — 재는 속성과 합격 기준은 아직 1차 출처와
+ * 대조하지 않았다(커널 계약의 머리말이 그 사실을 적어 두었다).
+ */
+/**
+ * 시험 결과 — **"이 개체가 그 시험을 통과했다"** 는 기록(ISA-95 결과).
+ *
+ * 결과를 낳는 곳은 트윈이 아니다(인사·정비 시스템이 기록한다) — 그래서 관측이면서 **선언 경로로** 온다.
+ * 커널은 이 값이 있을 때만 자격을 판정한다: 없으면 제약이 아니고(라인이 굶지 않는다), 있으면 만료·
+ * 불합격이 배정을 막는다.
+ */
+export interface RefTestResult {
+  specId: string
+  result: 'pass' | 'fail'
+  at?: string
+  /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 조용히 사라진다. */
+  expiresAt?: string
+}
+
+export interface RefTestSpecification {
+  id: string
+  /** 표시명 — i18n 키일 수 있다. 읽는 어휘를 하나로 맞추려고 인제스트가 `name` 으로 옮긴다. */
+  description?: string
+  version?: string
+}
+
 export interface RefEquipment {
   id: string
   kind: string
+  /** 사람이 부르는 이름 — 없으면 화면이 id 를 보인다(id 를 이름으로 베끼지 않는다). */
+  name?: string
+  /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+  testResults?: RefTestResult[]
+  description?: string
   homeLocationId: string
   mtbfMs?: number // 평균 고장 간격(확률적 고장) — 지정 시 커널이 breakdown 시뮬 → 주목(고장) 발생
   mttrMs?: number // 평균 수리 시간
@@ -165,7 +214,7 @@ export interface RefOperationVariability {
 /**
  * 오퍼레이션 명세 — ISA-95 `OperationsSegment`. 커널 `OperationDef` 와 필드 이름이 1:1이다.
  *
- * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 박아 둔 상수다.** 원 시스템(또는 가상 레퍼런스)이
+ * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
  * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
  */
@@ -203,6 +252,8 @@ export interface RefOperation {
 export interface RefPerson {
   id: string
   name?: string
+  /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+  testResults?: RefTestResult[]
   /**
    * 속한 등급들 — **표준 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**.
    * 복수인 것이 표준이고 그것이 자격 표현이다: 한 사람이 용접 자격과 지게차 자격을 함께 갖는다.
@@ -240,6 +291,8 @@ export interface RefPerson {
 export interface RefAsset {
   id: string
   name?: string
+  /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+  testResults?: RefTestResult[]
   /**
    * 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). 팔레트가 'euro-pallet' 이면서 'food-grade' 일 수 있다.
    * 공정의 요구는 등급 하나 + 수량이다(표준 `PhysicalAssetSpecification`).
@@ -280,10 +333,52 @@ export interface RefMaterialDefinition {
   effectiveEnd?: string
 }
 
+/**
+ * **이 마스터를 다시 만들 수 있는 방법** — 트윈이 자기 원본을 기억하는 자리.
+ *
+ * 트윈은 원본을 비출 뿐이므로(ADR-0028), 원본이 달라지면 **다시 읽어야** 합니다. 그런데 지금까지
+ * 트윈은 "내가 무엇에서 나왔나" 를 남기지 않았다 — 어댑터로 들어온 트윈은 `TwinReference` 행이
+ * 있었지만 템플릿으로 세운 트윈에는 아무것도 없었고, 그래서 **다시 읽을 대상이 없는 트윈**이
+ * 만들어졌다. 원본을 잃은 트윈은 첫날의 모습에 영원히 머문다.
+ *
+ * 그래서 원천이 무엇이든 여기 한 자리에 남긴다. 다시 읽기는 이 값 하나만 보면 된다.
+ */
+export type MasterOrigin =
+  /**
+   * 등록된 레퍼런스(어댑터)에서 왔다 — 다시 읽기 = 그 어댑터로 마스터를 다시 가져온다.
+   *
+   * `source` 는 **레퍼런스 등록 이름**이고 그 참조가 보고하는 사이트 전부에 같다. 그래서 어느 사이트에서
+   * 온 트윈인지는 `siteId` 가 있어야 안다 — 없으면 다시 읽기가 사이트를 찾지 못한다(2026-08-18 실측:
+   * 사이트가 여러 개인 참조에서 온 트윈은 재동기가 전부 거절됐다. 참조 이름을 사이트별 마스터의
+   * `source`(=인스턴스 id)와 견주고 있었다 — 서로 다른 것을 비교한 것이다).
+   */
+  | { kind: 'reference'; source: string; siteId?: string; spaceId?: string }
+  /**
+   * 템플릿 + 노브로 합성했다 — 다시 읽기 = 같은 노브로 다시 짓는다(합성은 결정적이다).
+   *
+   * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 조용히 자기
+   * 현장을 떠난다 — 템플릿이 낸 기본 공간으로 돌아가기 때문이다. 그러면 그 현장의 값(요금 등)도 함께
+   * 잃는다(2026-08-18 실측: 한 현장에 합쳐 둔 EMS 트윈 여덟이 재동기 뒤 각자 공간으로 흩어졌다).
+   */
+  | { kind: 'template'; templateId: string; params: Record<string, unknown>; spaceId?: string }
+
 export interface ReferenceMaster {
   source: string
-  system: 'wms' | 'yms' | 'mes'
+  /**
+   * 어느 종류의 트윈인가 — **커널 카탈로그가 정본**이다(`DomainSystem`).
+   *
+   * 예전에는 `'wms' | 'yms' | 'mes'` 를 여기 적어 뒀다. 커널에 종류가 하나 늘 때(에너지) 이 줄이
+   * 함께 움직여야 하는데, 손으로 적힌 목록은 그것을 알려 주지 않는다 — 어휘의 집은 한 곳이어야 한다.
+   */
+  system: DomainSystem
   siteName: string
+  /** 검사 명세 — 자원·등급의 `testSpecificationIds` 가 가리키는 대상. */
+  testSpecifications?: RefTestSpecification[]
+  /**
+   * 이 마스터가 어디서 나왔나 — **다시 읽기의 유일한 근거.** 없으면 그 트윈은 다시 읽을 수 없고,
+   * 조회 화면이 그 사실을 그대로 말한다(없는 것을 있는 척하지 않는다).
+   */
+  origin?: MasterOrigin
   /* spaceId 명시 시 그 공간을 참조(여러 트윈이 한 공간 공유, N:1). 없으면 source 에서 파생(1:1). */
   /**
    * 현장(공간). **시각 기준(`timezone`)이 여기 있는 이유**: 한 테넌트가 Rosarito(태평양)와 한국
@@ -301,12 +396,19 @@ export interface ReferenceMaster {
   /**
    * **생산 정의**(레시피·라우트·자재 바인딩) — 커널의 정의-구동 MES 모드 입구.
    *
-   * 없으면 커널은 레거시(하드코딩) 흐름으로 돈다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
-   * 커널은 그것을 보지 못한다** — 선언과 실행이 갈라지는 지점이라 자리를 연다.
+   * 없으면 커널은 레거시(하드코딩) 흐름으로 동작한다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
+   * 커널은 그것을 보지 못한다** — 선언과 실행이 어긋나는 지점이라 자리를 연다.
+   */
+  /**
+   * 생산 선언 — `TwinModelDef.productionSpec` 으로 통과한다(ISA-95 OperationsSegment + BOM).
+   *
+   * 예전 이름은 `mesSpec` 이었다. 담긴 것은 MES 만의 것이 아니라 "자재를 소비해 자재를 산출하는
+   * 공정" 이고, 이름이 MES 였기 때문에 창고 트윈은 이 자리를 쓸 생각조차 하지 못했다(유통가공 창고가
+   * BOM 을 설명 문서에만 적어 둔 채 키트를 못 만드는 트윈을 만든 원인). 근거는 커널 계약 주석에.
    */
-  mesSpec?: unknown
+  productionSpec?: unknown
   /**
-   * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 돌아가는 공장).
+   * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 가동되는 공장).
    * 공정이 인원을 요구하는데 사람이 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
    */
   persons?: RefPerson[]
@@ -317,7 +419,7 @@ export interface ReferenceMaster {
   assets?: RefAsset[]
   /**
    * 등급 정의 — 표준 `PersonnelClass`·`EquipmentClass`·`PhysicalAssetClass`.
-   * 안 실어도 트윈은 돈다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
+   * 안 실어도 트윈은 동작한다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
    */
   personnelClasses?: RefResourceClass[]
   equipmentClasses?: RefResourceClass[]
@@ -325,12 +427,20 @@ export interface ReferenceMaster {
   /** 품목 정의·등급 — 표준 `MaterialDefinition` / `MaterialClass`. 없으면 단위 환산을 할 수 없다. */
   materialDefinitions?: RefMaterialDefinition[]
   materialClasses?: RefResourceClass[]
+  /**
+   * 커넥터가 **옮기는 동안 알게 된 것.** 외부 시스템의 값을 우리 어휘로 못 옮겨 기본값을 넣었다면
+   * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
+   *
+   * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
+   * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+   */
+  warnings?: IngestWarning[]
 }
 
 export interface IngestedTwin {
-  board: any // BoardDef(+layout+spaceId) — 커널 소비
+  model: any // TwinModelDef(+layout+spaceId) — 커널 소비
   spaceContent: any // TwinSpace content — 뷰 소비
-  warnings: string[]
+  warnings: IngestWarning[]
 }
 
 /**
@@ -344,7 +454,7 @@ export interface IngestedTwin {
  * 값이다. 그래서 8월의 `America/Tijuana` 는 −420(PDT), 1월은 −480(PST)이 된다.
  *
  * **한계를 밝힌다**: 여기서 나오는 것은 **한 시점의** 오프셋이다. 커널은 고정 오프셋으로 하루 중 분을
- * 읽으므로, 보드를 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
+ * 읽으므로, 모델을 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
@@ -365,21 +475,193 @@ export function utcOffsetOf(timezone?: string, at: Date = new Date()): number |
   }
 }
 
+
+/* ── 인제스트 경고 ──────────────────────────────────────────────────────────
+ * 인제스트는 구조에 문제가 있어도 트윈을 만들어 준다(막지 않는 것이 옳다 — 부분적으로라도 세우고
+ * 고쳐 나가는 것이 이 시스템의 방식이다). 그래서 **경고가 유일한 신호**인데, 그 경고를 화면이 하나도
+ * 보여주지 않고 있었다: 유통가공 창고 템플릿은 커널이 모르는 자리 타입(`vas-station`)으로 트윈을
+ * 만들면서 경고를 냈지만, 위자드는 그것을 버렸고 사용자는 아무 말 없이 막히는 트윈을 받았다.
+ *
+ * 문장이 아니라 코드로 실어 보낸다. 예전 경고는 프로즈였고 그중 하나에는 한글이 섞여 있었다
+ * (`— 카탈로그에 없음`) — 다섯 언어 화면에 그대로 내보내면 이번에 걷어낸 문제를 다시 만든다.
+ * 이 프로젝트가 이미 쓰는 규약과 같은 모양이다: 주의 신호(kind+params)·커맨드 거절(errorCode+params)·
+ * 만만함 판정(code+영어 canonical message).
+ *
+ *   code    언어 중립 — 화면이 `twin.ingest.<code>` 로 사람 말을 만든다
+ *   params  문장에 끼울 값 — 번역이 언어마다 어순을 바꿀 수 있게
+ *   message 영어 canonical — 로그에 남고, 번역이 없을 때 그대로 보인다(빈칸보다 낫다)
+ *
+ * **여기 사는 이유**: 이 파일이 경고의 생산자이고, 테스트가 소스에서 직접 읽는 모듈이라
+ * 런타임 상대 import 를 가질 수 없다(이 저장소의 규약 — 그런 모듈은 자기완결이다).
+ * ────────────────────────────────────────────────────────────────────────── */
+/** 인제스트가 알리는 한 가지. */
+export interface IngestWarning {
+  /** 언어 중립 코드. 화면은 `twin.ingest.<code>` 로 렌더한다. */
+  code: string
+  /** 문장에 끼울 값. 번역이 어순을 바꿀 수 있게 이름으로 넘긴다. */
+  params?: Record<string, string | number>
+  /** 영어 canonical 문장 — 로그·폴백용. 번역이 없어도 읽을 수 있어야 한다. */
+  message: string
+}
+
+/**
+ * **시각을 모르는 채 시각으로 판정하려 한다** — 발전 형상은 하루의 시각을 읽는데 이 트윈의 공간이
+ * 시간대를 말하지 않았다.
+ *
+ * ── 왜 경고인가 (2026-08-18) ────────────────────────────────────────────────
+ * 커널은 시간대를 모르면 UTC 로 읽는다(계약에 밝혀 둔 규율 — 모르는 값을 지어내지 않는다). 그런데 발전
+ * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
+ * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
+ *
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
+ */
+export const generationWithoutTimeZone = (spaceId: string, equipmentId: string): IngestWarning => ({
+  code: 'generation-without-time-zone',
+  params: { spaceId, equipmentId },
+  message:
+    `"${equipmentId}" declares a daily generation shape but space "${spaceId}" declares no time zone — the hourly fractions will be read in UTC, ` +
+    'so the generation peak will not land at local noon. Declare the space time zone (we do not guess one).'
+})
+
+/** 커널 카탈로그가 모르는 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다. */
+export const unknownLocationType = (system: string, type: string, id: string): IngestWarning => ({
+  code: 'unknown-location-type',
+  params: { system, type, id },
+  message: `"${type}" is not a known ${system} location type (${id}) — the kernel may not include this location in the flow`
+})
+
+/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
+export const unknownTimezone = (timezone: string): IngestWarning => ({
+  code: 'unknown-timezone',
+  params: { timezone },
+  message: `space timezone "${timezone}" is not a known IANA zone — the twin will read times as UTC`
+})
+
+/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 동작한다. */
+export const operationWithoutDuration = (operation: string): IngestWarning => ({
+  code: 'operation-without-duration',
+  params: { operation },
+  message: `operation "${operation}" has no duration or parameters — kernel defaults will be used`
+})
+
+/** 볼 수 있는 표현이 없다 — 현장이 화면에 뜨지 않는다. */
+export const noViewableRepresentation = (): IngestWarning => ({
+  code: 'no-viewable-representation',
+  message: 'the space has no viewable representation (no representations and no geo) — add one, or provide geo/board'
+})
+
+/**
+ * 구조 투영에서 **가리키는 대상을 못 찾았다.**
+ *
+ * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
+ * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ */
+export const unresolvedReference = (field: string, ref: string): IngestWarning => ({
+  code: 'unresolved-reference',
+  params: { field, ref },
+  message: `${field} points at something that is not in this twin (${ref}) — the link was left empty`
+})
+
+/**
+ * 구조 투영 자체가 실패했다 — 조회는 못 하지만 **트윈은 동작한다**(커널은 model 를 이미 받았다).
+ * 행은 원본에서 다시 그릴 수 있으므로 인제스트를 실패로 만들지 않되, 침묵하지도 않는다.
+ */
+export const projectionFailed = (reason: string): IngestWarning => ({
+  code: 'projection-failed',
+  params: { reason },
+  message: `structure projection failed (${reason}) — the twin runs, but model inspection will be stale until the next ingest`
+})
+
+/**
+ * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
+ *
+ * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
+ * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
+ */
+export const structureAdopted = (rev: number, shift: { locationsAdded: number; locationsDropped: number; equipmentDropped: number; personsDropped: number; assetsDropped: number }): IngestWarning => ({
+  code: 'structure-adopted',
+  params: { rev, ...shift },
+  message:
+    `the running mirror adopted a new structure (revision ${rev}) — ` +
+    `+${shift.locationsAdded} location(s), -${shift.locationsDropped} location(s), ` +
+    `-${shift.equipmentDropped} equipment, -${shift.personsDropped} person(s), -${shift.assetsDropped} asset(s)`
+})
+
+/**
+ * 커넥터가 외부 시스템의 값을 **우리 어휘로 옮기지 못해 기본값을 넣었다.**
+ *
+ * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
+ * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
+ * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
+ *
+ * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
+ */
+export const connectorMappingFallback = (field: string, fallback: string, values: readonly string[], count: number): IngestWarning => ({
+  code: 'connector-mapping-fallback',
+  params: { field, fallback, values: values.join(', '), count },
+  message: `${count} ${field} value(s) had no mapping and fell back to "${fallback}" (${values.join(', ')}) — the twin's shape differs from the source system here`
+})
+
+
+/** 로그 한 줄 — 개발자가 읽는 것이므로 영어 canonical 문장을 쓴다. */
+export const describeWarnings = (warnings: readonly IngestWarning[]): string =>
+  warnings.map(w => `${w.code}: ${w.message}`).join(' | ')
+
+/**
+ * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
+ *
+ * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
+ */
+export const knobDefaultsFilled = (keys: readonly string[]): IngestWarning => ({
+  code: 'knob-defaults-filled',
+  params: { keys: keys.join(', '), count: keys.length },
+  message: `values you did not provide were filled from the template defaults: ${keys.join(', ')}`
+})
+
+/**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ *
+ * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
+ * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
+ */
+export const siteEquipmentAdopted = (key: string, count: number): IngestWarning => ({
+  code: 'site-equipment-adopted',
+  params: { key, count },
+  message: `${count} piece(s) of equipment already on this site were adopted as loads (knob "${key}") — set their coefficients before trusting the numbers`
+})
+
 export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTwin {
-  const warnings: string[] = []
+  /* 커넥터가 옮기며 알게 된 것을 먼저 싣는다 — 원인이 앞에 오는 편이 읽기 쉽다(대체가 먼저, 그 결과가 뒤). */
+  const warnings: IngestWarning[] = [...(master.warnings ?? [])]
   const known: string[] = catalog?.[master.system]?.locationTypes ?? []
 
   const locationEntries = master.locations.filter(l => l.role === 'location' || l.role === 'both')
   const areaLocs = master.locations.filter(l => l.role === 'area' || l.role === 'both')
 
   const locations = locationEntries.map(l => {
-    if (known.length && !known.includes(l.type)) warnings.push(`unknown ${master.system} location type "${l.type}" (${l.id}) — 카탈로그에 없음`)
-    // gs1Id(정식 정체성)를 보드 노드로 통과 — 결합(tag)/추적이 GS1 로(§J). 로컬 id 는 그대로 유지(name/xref).
-    return { id: l.id, type: l.type, capacity: l.capacity ?? 0, ...(l.parallelism !== undefined ? { parallelism: l.parallelism } : {}), ...(l.level ? { level: l.level } : {}), parentId: l.parentId, gs1Id: l.gs1Id }
+    if (known.length && !known.includes(l.type)) warnings.push(unknownLocationType(master.system, l.type, l.id))
+    // gs1Id(정식 정체성)를 모델의 자리로 통과 — 결합(tag)/추적이 GS1 로(§J). 로컬 id 는 그대로 유지(name/xref).
+    /*
+     * **이름을 통과시킨다.** 여기서 버리고 있었다 — 그래서 모델에도, 투영한 행에도 이름이 없고
+     * 화면은 자리 id 를 그대로 찍었다(`cut-station`). 목록·표·관계 그림에서 같은 결함이 따로
+     * 보였던 이유가 이 한 줄이다. 이름 없는 원본은 이름 없이 통과한다(id 로 메우지 않는다).
+     */
+    /*
+     * **속성도 통과시킨다** — 설비와 같은 규율(손대지 않고 나른다). 여기가 없으면 자리에 실은 값이
+     * 커널에 닿지 않는다: 에너지의 계약전력(`contract.kW`)이 그 경로이고, 통과하지 않으면 커널이
+     * 계약을 모르는 채로 서서 **판정을 아예 하지 않는다**(오류 없이 조용히).
+     */
+    return { id: l.id, type: l.type, ...(l.name ? { name: l.name } : {}), ...(l.description ? { description: l.description } : {}), capacity: l.capacity ?? 0, ...(l.parallelism !== undefined ? { parallelism: l.parallelism } : {}), ...(l.level ? { level: l.level } : {}), ...(l.properties?.length ? { properties: l.properties } : {}), parentId: l.parentId, ...(l.upstreamId ? { upstreamId: l.upstreamId } : {}), gs1Id: l.gs1Id }
   })
 
   const equipment = (master.equipment ?? []).map(e => ({
-    id: e.id, kind: e.kind, homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
+    id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
+    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
     ...(e.window ? { window: e.window } : {}),
     /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
     ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),
@@ -394,56 +676,84 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
   const spaceId = master.space.spaceId ?? `${master.source}-site`
   /*
    * 시각 기준을 커널이 읽을 형태로 푼다 — 커널은 zero-dep 이라 시간대 데이터베이스를 들이지 않고
-   * **분 오프셋**만 받는다(계약 `BoardDef.utcOffsetMinutes`). 푸는 일은 호스트의 몫이다.
+   * **분 오프셋**만 받는다(계약 `TwinModelDef.utcOffsetMinutes`). 푸는 일은 호스트의 몫이다.
    *
    * 선언이 없으면 **필드를 만들지 않는다** — 그러면 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다.
    * 여기서 0 을 넣으면 "UTC 라고 선언했다" 와 "선언하지 않았다" 가 구별되지 않는다.
    */
   const utcOffsetMinutes = utcOffsetOf(master.space.timezone)
   if (master.space.timezone && utcOffsetMinutes === undefined) {
-    warnings.push(`space timezone "${master.space.timezone}" is not a known IANA zone — the twin will read times as UTC`)
+    warnings.push(unknownTimezone(String(master.space.timezone)))
   }
   /*
-   * 오퍼레이션 명세를 board 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(BoardDef 확장 필드,
+   * 오퍼레이션 명세를 model 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(TwinModelDef 확장 필드,
    * 모르는 커널은 무시). 여기서 값을 손대지 않는다: 기간은 표준 표기(ISO 8601)로 커널까지 그대로 간다.
    */
   const operations = master.operations
   if (operations?.length) {
     for (const o of operations) {
-      if (!o.duration && !o.parameters?.length) warnings.push(`operation "${o.key}" has no duration or parameters — kernel defaults will be used`)
+      if (!o.duration && !o.parameters?.length) warnings.push(operationWithoutDuration(o.key))
     }
   }
   /* 사람도 손대지 않고 통과 — 등급·교대 그대로 커널까지 간다(경계에서 어휘를 갈지 않는다). */
-  const persons = master.persons?.map(p => ({ id: p.id, personnelClassIds: p.personnelClassIds, ...(p.window ? { window: p.window } : {}), ...(p.workCalendar?.length ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocationId ? { homeLocation: p.homeLocationId } : {}), ...(p.properties?.length ? { properties: p.properties } : {}), ...(p.testSpecificationIds?.length ? { testSpecificationIds: p.testSpecificationIds } : {}), ...(p.effectiveStart ? { effectiveStart: p.effectiveStart } : {}), ...(p.effectiveEnd ? { effectiveEnd: p.effectiveEnd } : {}) }))
+  const persons = master.persons?.map(p => ({ id: p.id, ...(p.name ? { name: p.name } : {}), ...(p.testResults?.length ? { testResults: p.testResults } : {}), personnelClassIds: p.personnelClassIds, ...(p.window ? { window: p.window } : {}), ...(p.workCalendar?.length ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocationId ? { homeLocation: p.homeLocationId } : {}), ...(p.properties?.length ? { properties: p.properties } : {}), ...(p.testSpecificationIds?.length ? { testSpecificationIds: p.testSpecificationIds } : {}), ...(p.effectiveStart ? { effectiveStart: p.effectiveStart } : {}), ...(p.effectiveEnd ? { effectiveEnd: p.effectiveEnd } : {}) }))
   /* 자산도 손대지 않고 통과 — 등급·자리 그대로 커널까지. */
-  const assets = master.assets?.map(a => ({ id: a.id, assetClassIds: a.assetClassIds, homeLocation: a.homeLocationId, gs1Id: a.gs1Id, ...(a.properties?.length ? { properties: a.properties } : {}), ...(a.testSpecificationIds?.length ? { testSpecificationIds: a.testSpecificationIds } : {}), ...(a.effectiveStart ? { effectiveStart: a.effectiveStart } : {}), ...(a.effectiveEnd ? { effectiveEnd: a.effectiveEnd } : {}) }))
+  const assets = master.assets?.map(a => ({ id: a.id, ...(a.name ? { name: a.name } : {}), ...(a.testResults?.length ? { testResults: a.testResults } : {}), assetClassIds: a.assetClassIds, homeLocation: a.homeLocationId, gs1Id: a.gs1Id, ...(a.properties?.length ? { properties: a.properties } : {}), ...(a.testSpecificationIds?.length ? { testSpecificationIds: a.testSpecificationIds } : {}), ...(a.effectiveStart ? { effectiveStart: a.effectiveStart } : {}), ...(a.effectiveEnd ? { effectiveEnd: a.effectiveEnd } : {}) }))
   /* 품목 정의·등급도 손대지 않고 통과 — 경계에서 어휘를 갈지 않는다(환산 계수는 커널이 읽는다). */
   const materialDefinitions = master.materialDefinitions?.map(d => ({
     id: d.id,
-    ...(d.name ? { description: d.name } : {}),
+    /* 이름은 이름 자리에 — 예전에는 `name` 을 `description` 으로 옮겨 담았다(어휘가 뒤집혀 있었다). */
+    ...(d.name ? { name: d.name } : {}),
     ...(d.materialClassIds?.length ? { materialClassIds: d.materialClassIds } : {}),
     ...(d.properties?.length ? { properties: d.properties } : {}),
     ...(d.testSpecificationIds?.length ? { testSpecificationIds: d.testSpecificationIds } : {}),
     ...(d.effectiveStart ? { effectiveStart: d.effectiveStart } : {}),
     ...(d.effectiveEnd ? { effectiveEnd: d.effectiveEnd } : {})
   }))
-  const board = {
+  /*
+   * **등급의 표시명은 `name` 이다.**
+   *
+   * 표준 마스터는 등급의 표시명을 `description` 에 담는다(`RefResourceClass.description` = i18n 키).
+   * 그것을 그대로 모델에 실으면 화면의 "설명" 열에 이름이 앉는다 — 사용자에게는 이름인데 머리글은
+   * 설명이라, 같은 것을 축마다 다른 이름으로 부르게 된다.
+   *
+   * 그래서 **문 하나에서 어휘를 맞춘다**: 표시명은 어느 축이든 `name`. 원래의 `description` 은
+   * 남겨 두지 않는다 — 두 자리에 같은 값이 있으면 어느 것이 정본인지 다시 헷갈린다.
+   */
+  const asName = (list?: RefResourceClass[]) =>
+    list?.map(({ description, ...rest }) => ({ ...rest, ...(description ? { name: description } : {}) }))
+  /*
+   * 검사 명세도 **표시명은 `name`** 이다 — 등급과 같은 규칙을 쓴다(어휘를 하나로). 표준 마스터는
+   * 표시명을 `description` 에 담으므로 문 하나에서 옮긴다. 그러지 않으면 화면의 "설명" 열에 이름이
+   * 앉아 축마다 다른 이름으로 같은 것을 부르게 된다(등급에서 이미 겪었다).
+   */
+  const testSpecifications = master.testSpecifications?.map(({ description, ...rest }) => ({
+    ...rest,
+    ...(description ? { name: description } : {})
+  }))
+  const personnelClasses = asName(master.personnelClasses)
+  const equipmentClasses = asName(master.equipmentClasses)
+  const assetClasses = asName(master.assetClasses)
+  const materialClasses = asName(master.materialClasses)
+
+  const model = {
     locations, equipment, layout, spaceId,
     /* 생산 정의도 손대지 않고 통과 — 경계에서 어휘를 갈지 않는다(커널이 그대로 소비한다). */
-    ...(master.mesSpec ? { mesSpec: master.mesSpec } : {}),
+    ...(master.productionSpec ? { productionSpec: master.productionSpec } : {}),
     ...(materialDefinitions?.length ? { materialDefinitions } : {}),
-    ...(master.materialClasses?.length ? { materialClasses: master.materialClasses } : {}),
+    ...(materialClasses?.length ? { materialClasses } : {}),
     ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),
     ...(operations?.length ? { operations } : {}),
-    ...(master.personnelClasses?.length ? { personnelClasses: master.personnelClasses } : {}),
-    ...(master.equipmentClasses?.length ? { equipmentClasses: master.equipmentClasses } : {}),
-    ...(master.assetClasses?.length ? { assetClasses: master.assetClasses } : {}),
+    ...(testSpecifications?.length ? { testSpecifications } : {}),
+    ...(personnelClasses?.length ? { personnelClasses } : {}),
+    ...(equipmentClasses?.length ? { equipmentClasses } : {}),
+    ...(assetClasses?.length ? { assetClasses } : {}),
     ...(persons?.length ? { persons } : {}),
     ...(assets?.length ? { assets } : {})
   }
 
   const areas = areaLocs.map(l => ({
-    id: l.id, type: l.type, name: l.name ?? l.id, parentId: l.parentId,
+    id: l.id, type: l.type, name: l.name ?? l.id, parentId: l.parentId, ...(l.upstreamId ? { upstreamId: l.upstreamId } : {}),
     x: l.footprint?.x ?? 0, y: l.footprint?.y ?? 0, w: l.footprint?.w ?? 10, h: l.footprint?.h ?? 10
   }))
   // 인제스트 현장 물질화(space facet #4) — 표현이 없고 geo 가 있으면 기본 map 표현 합성.
@@ -458,13 +768,30 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
         ? [{ id: 'r-map', type: 'map', name: '위성 지도', primary: true, center: { lat: geo.lat, lon: geo.lon }, zoom: 17 }]
         : []
   if (representations.length === 0) {
-    warnings.push('space has no viewable representation (no representations and no geo) — add one manually or provide geo/board')
+    warnings.push(noViewableRepresentation())
   }
   const spaceContent = {
     width: master.space.width, depth: master.space.depth, unit: master.space.unit ?? 'm',
     geo, representations, primaryId: master.space.primaryId ?? representations[0]?.id,
-    areas, landmarks: []
+    areas
   }
 
-  return { board, spaceContent, warnings }
+  return { model, spaceContent, warnings }
+}
+
+/**
+ * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
+ *
+ * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
+ * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
+ */
+export function pickOriginSite<T extends { siteId: string }>(
+  sites: readonly T[],
+  origin: { siteId?: string } | undefined | null
+): { site?: T; reason?: 'no-remembered-site' | 'site-gone' } {
+  const wanted = String(origin?.siteId ?? '').trim()
+  if (!wanted) return { reason: 'no-remembered-site' }
+  const site = sites.find(s => String(s.siteId) === wanted)
+  return site ? { site } : { reason: 'site-gone' }
 }