@things-factory/headless-twin 10.0.9 → 10.0.11

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

@@ -1,10 +1,18 @@
-import type { EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel';
+import type { DomainSystem, EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel';
 export interface RefLocation {
     id: string;
     type: string;
     name?: string;
+    description?: string;
     role: 'location' | 'area' | 'both';
     parentId?: string;
+    /**
+     * **전기적으로 어디서 받는가** — 이 자리에 전기를 주는 상류 자리(커널 계약의 `upstreamId`).
+     *
+     * `parentId`(공간 포함)와 따로 두는 이유는 커널 계약에 적혀 있다. 여기서 빠뜨리면 마스터가 말한 계통이
+     * 모델까지 오지 못하고, 뿌리 계량 판정이 분기 계량기까지 뿌리로 세어 **부하가 두 배로** 보인다.
+     */
+    upstreamId?: string;
     /** 저장 용량 — 이 자리에 동시에 놓일 수 있는 물품 수. */
     capacity?: number;
     /**
@@ -20,6 +28,14 @@ export interface RefLocation {
      * 짐작해 채우지 않는다.
      */
     level?: EquipmentLevel;
+    /**
+     * 자리의 **열린 속성** — 표준 `OperationalLocationProperty`(설비·사람·자산과 같은 모양).
+     *
+     * 무엇이 여기 실리나: **자리의 물리량**이다. 에너지의 계약전력(`contract.kW`)이 첫 사례다 —
+     * 그 값이 앉을 자리가 없어서 EMS 커널은 계약 대비 판정을 할 수 없었다(자리가 없으면 사실이
+     * 들어오지 못한다). 커널은 자기가 **읽는** 속성 id 만 선언하고(`EMS_PROPERTY`) 나머지는 나른다.
+     */
+    properties?: RefResourceProperty[];
     footprint?: {
         x: number;
         y: number;
@@ -76,9 +92,40 @@ export interface RefResourceClass {
     effectiveStart?: string;
     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;
     mttrMs?: number;
@@ -155,7 +202,7 @@ export interface RefOperationVariability {
 /**
  * 오퍼레이션 명세 — ISA-95 `OperationsSegment`. 커널 `OperationDef` 와 필드 이름이 1:1이다.
  *
- * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 박아 둔 상수다.** 원 시스템(또는 가상 레퍼런스)이
+ * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
  * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
  */
@@ -198,6 +245,8 @@ export interface RefOperation {
 export interface RefPerson {
     id: string;
     name?: string;
+    /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+    testResults?: RefTestResult[];
     /**
      * 속한 등급들 — **표준 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**.
      * 복수인 것이 표준이고 그것이 자격 표현이다: 한 사람이 용접 자격과 지게차 자격을 함께 갖는다.
@@ -237,6 +286,8 @@ export interface RefPerson {
 export interface RefAsset {
     id: string;
     name?: string;
+    /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+    testResults?: RefTestResult[];
     /**
      * 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). 팔레트가 'euro-pallet' 이면서 'food-grade' 일 수 있다.
      * 공정의 요구는 등급 하나 + 수량이다(표준 `PhysicalAssetSpecification`).
@@ -275,10 +326,61 @@ export interface RefMaterialDefinition {
     effectiveStart?: string;
     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;
     /**
      * 현장(공간). **시각 기준(`timezone`)이 여기 있는 이유**: 한 테넌트가 Rosarito(태평양)와 한국
      * 공장을 함께 가질 수 있다. 테넌트 단위(`Domain.timezone`)로 두면 **둘 중 하나는 반드시 틀린다.**
@@ -308,11 +410,11 @@ export interface ReferenceMaster {
     /**
      * **생산 정의**(레시피·라우트·자재 바인딩) — 커널의 정의-구동 MES 모드 입구.
      *
-     * 없으면 커널은 레거시(하드코딩) 흐름으로 돈다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
-     * 커널은 그것을 보지 못한다** — 선언과 실행이 갈라지는 지점이라 자리를 연다.
+     * 없으면 커널은 레거시(하드코딩) 흐름으로 동작한다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
+     * 커널은 그것을 보지 못한다** — 선언과 실행이 어긋나는 지점이라 자리를 연다.
      */
     /**
-     * 생산 선언 — `BoardDef.productionSpec` 으로 통과한다(ISA-95 OperationsSegment + BOM).
+     * 생산 선언 — `TwinModelDef.productionSpec` 으로 통과한다(ISA-95 OperationsSegment + BOM).
      *
      * 예전 이름은 `mesSpec` 이었다. 담긴 것은 MES 만의 것이 아니라 "자재를 소비해 자재를 산출하는
      * 공정" 이고, 이름이 MES 였기 때문에 창고 트윈은 이 자리를 쓸 생각조차 하지 못했다(유통가공 창고가
@@ -320,7 +422,7 @@ export interface ReferenceMaster {
      */
     productionSpec?: unknown;
     /**
-     * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 돌아가는 공장).
+     * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 가동되는 공장).
      * 공정이 인원을 요구하는데 사람이 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
      */
     persons?: RefPerson[];
@@ -331,7 +433,7 @@ export interface ReferenceMaster {
     assets?: RefAsset[];
     /**
      * 등급 정의 — 표준 `PersonnelClass`·`EquipmentClass`·`PhysicalAssetClass`.
-     * 안 실어도 트윈은 돈다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
+     * 안 실어도 트윈은 동작한다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
      */
     personnelClasses?: RefResourceClass[];
     equipmentClasses?: RefResourceClass[];
@@ -339,9 +441,17 @@ export interface ReferenceMaster {
     /** 품목 정의·등급 — 표준 `MaterialDefinition` / `MaterialClass`. 없으면 단위 환산을 할 수 없다. */
     materialDefinitions?: RefMaterialDefinition[];
     materialClasses?: RefResourceClass[];
+    /**
+     * 커넥터가 **옮기는 동안 알게 된 것.** 외부 시스템의 값을 우리 어휘로 못 옮겨 기본값을 넣었다면
+     * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
+     *
+     * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
+     * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+     */
+    warnings?: IngestWarning[];
 }
 export interface IngestedTwin {
-    board: any;
+    model: any;
     spaceContent: any;
     warnings: IngestWarning[];
 }
@@ -356,7 +466,7 @@ export interface IngestedTwin {
  * 값이다. 그래서 8월의 `America/Tijuana` 는 −420(PDT), 1월은 −480(PST)이 된다.
  *
  * **한계를 밝힌다**: 여기서 나오는 것은 **한 시점의** 오프셋이다. 커널은 고정 오프셋으로 하루 중 분을
- * 읽으므로, 보드를 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
+ * 읽으므로, 모델을 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
@@ -372,16 +482,65 @@ export interface IngestWarning {
     /** 영어 canonical 문장 — 로그·폴백용. 번역이 없어도 읽을 수 있어야 한다. */
     message: string;
 }
+/**
+ * **시각을 모르는 채 시각으로 판정하려 한다** — 발전 형상은 하루의 시각을 읽는데 이 트윈의 공간이
+ * 시간대를 말하지 않았다.
+ *
+ * ── 왜 경고인가 (2026-08-18) ────────────────────────────────────────────────
+ * 커널은 시간대를 모르면 UTC 로 읽는다(계약에 밝혀 둔 규율 — 모르는 값을 지어내지 않는다). 그런데 발전
+ * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
+ * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
+ *
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
+ */
+export declare const generationWithoutTimeZone: (spaceId: string, equipmentId: string) => IngestWarning;
 /** 커널 카탈로그가 모르는 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다. */
 export declare const unknownLocationType: (system: string, type: string, id: string) => IngestWarning;
 /** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
 export declare const unknownTimezone: (timezone: string) => IngestWarning;
-/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 돈다. */
+/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 동작한다. */
 export declare const operationWithoutDuration: (operation: string) => IngestWarning;
 /** 볼 수 있는 표현이 없다 — 현장이 화면에 뜨지 않는다. */
 export declare const noViewableRepresentation: () => IngestWarning;
-/** 합치는 공간에 같은 id 의 랜드마크가 이미 있다 — 서로 다른 것이 하나로 접혔을 수 있다. */
-export declare const landmarkIdsMerged: (spaceId: string, ids: readonly string[]) => IngestWarning;
+/**
+ * 구조 투영에서 **가리키는 대상을 못 찾았다.**
+ *
+ * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
+ * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ */
+export declare const unresolvedReference: (field: string, ref: string) => IngestWarning;
+/**
+ * 구조 투영 자체가 실패했다 — 조회는 못 하지만 **트윈은 동작한다**(커널은 model 를 이미 받았다).
+ * 행은 원본에서 다시 그릴 수 있으므로 인제스트를 실패로 만들지 않되, 침묵하지도 않는다.
+ */
+export declare const projectionFailed: (reason: string) => IngestWarning;
+/**
+ * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
+ *
+ * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
+ * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
+ */
+export declare const structureAdopted: (rev: number, shift: {
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}) => IngestWarning;
+/**
+ * 커넥터가 외부 시스템의 값을 **우리 어휘로 옮기지 못해 기본값을 넣었다.**
+ *
+ * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
+ * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
+ * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
+ *
+ * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
+ */
+export declare const connectorMappingFallback: (field: string, fallback: string, values: readonly string[], count: number) => IngestWarning;
 /** 로그 한 줄 — 개발자가 읽는 것이므로 영어 canonical 문장을 쓴다. */
 export declare const describeWarnings: (warnings: readonly IngestWarning[]) => string;
 /**
@@ -391,4 +550,26 @@ export declare const describeWarnings: (warnings: readonly IngestWarning[]) => s
  * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
  */
 export declare const knobDefaultsFilled: (keys: readonly string[]) => IngestWarning;
+/**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ *
+ * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
+ * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
+ */
+export declare const siteEquipmentAdopted: (key: string, count: number) => IngestWarning;
 export declare function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTwin;
+/**
+ * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
+ *
+ * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
+ * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
+ */
+export declare function pickOriginSite<T extends {
+    siteId: string;
+}>(sites: readonly T[], origin: {
+    siteId?: string;
+} | undefined | null): {
+    site?: T;
+    reason?: 'no-remembered-site' | 'site-gone';
+};

package/dist-server/service/reference/reference-master.js

@@ -1,16 +1,17 @@
 "use strict";
 /*
  * 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 없이 위상만 인제스트.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.knobDefaultsFilled = exports.describeWarnings = exports.landmarkIdsMerged = exports.noViewableRepresentation = exports.operationWithoutDuration = exports.unknownTimezone = exports.unknownLocationType = void 0;
+exports.siteEquipmentAdopted = exports.knobDefaultsFilled = exports.describeWarnings = exports.connectorMappingFallback = exports.structureAdopted = exports.projectionFailed = exports.unresolvedReference = exports.noViewableRepresentation = exports.operationWithoutDuration = exports.unknownTimezone = exports.unknownLocationType = exports.generationWithoutTimeZone = void 0;
 exports.utcOffsetOf = utcOffsetOf;
 exports.masterToTwin = masterToTwin;
+exports.pickOriginSite = pickOriginSite;
 /**
  * 마스터 → 트윈 구조 매핑(순수). 노드타입을 카탈로그로 검증(모르는 타입은 warning, 버리진 않음 — 반영 우선).
  * @param catalog DOMAIN_CATALOG (커널 SSOT). 없으면 검증 생략.
@@ -22,7 +23,7 @@ exports.masterToTwin = masterToTwin;
  * 값이다. 그래서 8월의 `America/Tijuana` 는 −420(PDT), 1월은 −480(PST)이 된다.
  *
  * **한계를 밝힌다**: 여기서 나오는 것은 **한 시점의** 오프셋이다. 커널은 고정 오프셋으로 하루 중 분을
- * 읽으므로, 보드를 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
+ * 읽으므로, 모델을 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
@@ -46,6 +47,25 @@ function utcOffsetOf(timezone, at = new Date()) {
         return undefined; // 알 수 없는 이름 — Intl 이 던진다
     }
 }
+/**
+ * **시각을 모르는 채 시각으로 판정하려 한다** — 발전 형상은 하루의 시각을 읽는데 이 트윈의 공간이
+ * 시간대를 말하지 않았다.
+ *
+ * ── 왜 경고인가 (2026-08-18) ────────────────────────────────────────────────
+ * 커널은 시간대를 모르면 UTC 로 읽는다(계약에 밝혀 둔 규율 — 모르는 값을 지어내지 않는다). 그런데 발전
+ * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
+ * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
+ *
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
+ */
+const generationWithoutTimeZone = (spaceId, equipmentId) => ({
+    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).'
+});
+exports.generationWithoutTimeZone = generationWithoutTimeZone;
 /** 커널 카탈로그가 모르는 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다. */
 const unknownLocationType = (system, type, id) => ({
     code: 'unknown-location-type',
@@ -60,7 +80,7 @@ const unknownTimezone = (timezone) => ({
     message: `space timezone "${timezone}" is not a known IANA zone — the twin will read times as UTC`
 });
 exports.unknownTimezone = unknownTimezone;
-/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 돈다. */
+/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 동작한다. */
 const operationWithoutDuration = (operation) => ({
     code: 'operation-without-duration',
     params: { operation },
@@ -73,13 +93,60 @@ const noViewableRepresentation = () => ({
     message: 'the space has no viewable representation (no representations and no geo) — add one, or provide geo/board'
 });
 exports.noViewableRepresentation = noViewableRepresentation;
-/** 합치는 공간에 같은 id 의 랜드마크가 이미 있다 — 서로 다른 것이 하나로 접혔을 수 있다. */
-const landmarkIdsMerged = (spaceId, ids) => ({
-    code: 'landmark-ids-merged',
-    params: { spaceId, ids: ids.join(', '), count: ids.length },
-    message: `landmark ids already present in space "${spaceId}" — merged: ${ids.join(', ')}`
+/**
+ * 구조 투영에서 **가리키는 대상을 못 찾았다.**
+ *
+ * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
+ * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ */
+const unresolvedReference = (field, ref) => ({
+    code: 'unresolved-reference',
+    params: { field, ref },
+    message: `${field} points at something that is not in this twin (${ref}) — the link was left empty`
+});
+exports.unresolvedReference = unresolvedReference;
+/**
+ * 구조 투영 자체가 실패했다 — 조회는 못 하지만 **트윈은 동작한다**(커널은 model 를 이미 받았다).
+ * 행은 원본에서 다시 그릴 수 있으므로 인제스트를 실패로 만들지 않되, 침묵하지도 않는다.
+ */
+const projectionFailed = (reason) => ({
+    code: 'projection-failed',
+    params: { reason },
+    message: `structure projection failed (${reason}) — the twin runs, but model inspection will be stale until the next ingest`
 });
-exports.landmarkIdsMerged = landmarkIdsMerged;
+exports.projectionFailed = projectionFailed;
+/**
+ * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
+ *
+ * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
+ * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
+ */
+const structureAdopted = (rev, shift) => ({
+    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)`
+});
+exports.structureAdopted = structureAdopted;
+/**
+ * 커넥터가 외부 시스템의 값을 **우리 어휘로 옮기지 못해 기본값을 넣었다.**
+ *
+ * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
+ * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
+ * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
+ *
+ * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
+ */
+const connectorMappingFallback = (field, fallback, values, count) => ({
+    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`
+});
+exports.connectorMappingFallback = connectorMappingFallback;
 /** 로그 한 줄 — 개발자가 읽는 것이므로 영어 canonical 문장을 쓴다. */
 const describeWarnings = (warnings) => warnings.map(w => `${w.code}: ${w.message}`).join(' | ');
 exports.describeWarnings = describeWarnings;
@@ -95,19 +162,43 @@ const knobDefaultsFilled = (keys) => ({
     message: `values you did not provide were filled from the template defaults: ${keys.join(', ')}`
 });
 exports.knobDefaultsFilled = knobDefaultsFilled;
+/**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ *
+ * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
+ * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
+ */
+const siteEquipmentAdopted = (key, count) => ({
+    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`
+});
+exports.siteEquipmentAdopted = siteEquipmentAdopted;
 function masterToTwin(master, catalog) {
-    const warnings = [];
+    /* 커넥터가 옮기며 알게 된 것을 먼저 싣는다 — 원인이 앞에 오는 편이 읽기 쉽다(대체가 먼저, 그 결과가 뒤). */
+    const warnings = [...(master.warnings ?? [])];
     const known = 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((0, exports.unknownLocationType)(master.system, 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 };
+        // 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 } : {}),
@@ -122,7 +213,7 @@ function masterToTwin(master, catalog) {
     const spaceId = master.space.spaceId ?? `${master.source}-site`;
     /*
      * 시각 기준을 커널이 읽을 형태로 푼다 — 커널은 zero-dep 이라 시간대 데이터베이스를 들이지 않고
-     * **분 오프셋**만 받는다(계약 `BoardDef.utcOffsetMinutes`). 푸는 일은 호스트의 몫이다.
+     * **분 오프셋**만 받는다(계약 `TwinModelDef.utcOffsetMinutes`). 푸는 일은 호스트의 몫이다.
      *
      * 선언이 없으면 **필드를 만들지 않는다** — 그러면 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다.
      * 여기서 0 을 넣으면 "UTC 라고 선언했다" 와 "선언하지 않았다" 가 구별되지 않는다.
@@ -132,7 +223,7 @@ function masterToTwin(master, catalog) {
         warnings.push((0, exports.unknownTimezone)(String(master.space.timezone)));
     }
     /*
-     * 오퍼레이션 명세를 board 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(BoardDef 확장 필드,
+     * 오퍼레이션 명세를 model 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(TwinModelDef 확장 필드,
      * 모르는 커널은 무시). 여기서 값을 손대지 않는다: 기간은 표준 표기(ISO 8601)로 커널까지 그대로 간다.
      */
     const operations = master.operations;
@@ -143,35 +234,61 @@ function masterToTwin(master, catalog) {
         }
     }
     /* 사람도 손대지 않고 통과 — 등급·교대 그대로 커널까지 간다(경계에서 어휘를 갈지 않는다). */
-    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) => 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.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 표현 합성.
@@ -190,8 +307,22 @@ function masterToTwin(master, catalog) {
     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)로 찾는 길을 택한다.
+ */
+function pickOriginSite(sites, origin) {
+    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' };
 }
 //# sourceMappingURL=reference-master.js.map