@things-factory/headless-twin 10.0.6 → 10.0.7

package/server/engine/warm-start.ts

@@ -10,13 +10,13 @@
 
 /** 커널에 심을 관측 상태 — 구조가 아니라 "무엇이 어디에 얼마나". */
 export interface ObservedSeed {
-  nodes: unknown[]
+  locations: unknown[]
   items: unknown[]
-  movers: unknown[]
+  equipment: unknown[]
 }
 
 export type WarmStartPlan =
-  | { action: 'hydrate'; seed: ObservedSeed; itemCount: number; moverCount: number }
+  | { action: 'hydrate'; seed: ObservedSeed; itemCount: number; equipmentCount: number }
   /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */
   | { action: 'skip'; reason: 'bench' }
   /** 심을 상태가 없다 — 처음 만든 트윈이거나 저널·체크포인트가 비었다. 정상이다. */
@@ -32,7 +32,7 @@ export type WarmStartPlan =
  * 넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작하는 편이 정직하다.
  */
 export function planWarmStart(
-  state: { nodes?: unknown[]; items?: unknown[]; movers?: unknown[] } | null | undefined,
+  state: { locations?: unknown[]; items?: unknown[]; equipment?: unknown[] } | null | undefined,
   purpose: string | undefined,
   canHydrate: boolean
 ): WarmStartPlan {
@@ -40,14 +40,14 @@ export function planWarmStart(
   if (purpose === 'bench') return { action: 'skip', reason: 'bench' }
   if (!state) return { action: 'skip', reason: 'no-state' }
 
-  const nodes = state.nodes ?? []
+  const locations = state.locations ?? []
   const items = state.items ?? []
-  const movers = state.movers ?? []
+  const equipment = state.equipment ?? []
   /* 셋 다 비었으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */
-  if (nodes.length === 0 && items.length === 0 && movers.length === 0) return { action: 'skip', reason: 'no-state' }
+  if (locations.length === 0 && items.length === 0 && equipment.length === 0) return { action: 'skip', reason: 'no-state' }
 
   /* 지원 여부는 마지막에 본다 — 심을 게 있는데 못 심는 상황이라야 경고할 값어치가 있다. */
   if (!canHydrate) return { action: 'skip', reason: 'unsupported' }
 
-  return { action: 'hydrate', seed: { nodes, items, movers }, itemCount: items.length, moverCount: movers.length }
+  return { action: 'hydrate', seed: { locations, items, equipment }, itemCount: items.length, equipmentCount: equipment.length }
 }

package/server/service/index.ts

@@ -4,6 +4,8 @@ export * from './twin-instance/twin-instance.js'
 export * from './twin-space/twin-space.js'
 export * from './twin-space/twin-space-representation.js'
 export * from './twin-space/twin-space-area.js'
+export * from './twin-target/twin-target.js'
+export * from './twin-structure/twin-structure.js'
 export * from './twin-state/twin-state-subscription.js'
 export * from './reference/reference-master.js'
 export * from './reference/reference-registry.js'
@@ -17,7 +19,9 @@ export * from './twin-lifecycle/domain-catalog.js'
 /* IMPORT ENTITIES AND RESOLVERS */
 import { entities as TwinEventEntities } from './twin-event/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'
+import { entities as TwinTargetEntities, resolvers as TwinTargetResolvers } from './twin-target/index.js'
 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'
@@ -31,7 +35,9 @@ export const entities = [
   /* ENTITIES */
   ...TwinEventEntities,
   ...TwinInstanceEntities,
+  ...TwinStructureEntities,
   ...TwinSpaceEntities,
+  ...TwinTargetEntities,
   ...TwinReferenceEntities
 ]
 
@@ -49,6 +55,7 @@ export const schema = {
     ...TwinAttentionResolvers,
     ...TwinMetricsResolvers,
     ...TwinSpaceResolvers,
+    ...TwinTargetResolvers,
     ...TwinReferenceResolvers
   ],
   directives: {}

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

@@ -30,7 +30,8 @@ export async function startReferenceLiveFeed(
   if (!det?.board) throw new Error(`instance "${instanceId}" not provisioned (no board) — ingest master before live start`)
 
   // mirror 모드 기동 — 커널 tick 없이 projector 가 실 이벤트를 미러(startLive 가 realityMode='mirror' 설정).
-  TwinEngine.startLive(instanceId, domainId, det.kind ?? 'wms', det.board)
+  // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
+  TwinEngine.startLive(instanceId, domainId, det.kind ?? 'wms', await TwinEngine.withSpaceTimeBase(det.board, domainId))
 
   stopReferenceLiveFeed(instanceId) // 재기동 시 이전 피드 정리
   const unsubscribe = adapter.openLiveFeed(cfg, site, (records: unknown[]) => {

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

@@ -7,17 +7,84 @@
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
+import type { EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel'
+
 export interface RefLocation {
   id: string
   type: string // 노드는 커널 노드타입(dock/storage/yard-slot…), area 는 공간 region 타입
   name?: string
-  role: 'node' | 'area' | 'both'
+  role: 'location' | 'area' | 'both'
   parentId?: string
+  /** 저장 용량 — 이 자리에 동시에 놓일 수 있는 물품 수. */
   capacity?: number
+  /**
+   * 동시 처리 수 — 이 자리에서 한 번에 진행될 수 있는 작업 수. **저장 용량과 다른 축**이다
+   * (자재를 20개 쌓아 두는 절단 스테이션이 한 번에 한 대만 깎는다). 미지정=제약 없음.
+   */
+  parallelism?: number
+  /**
+   * **ISA-95 설비 계층 단계** — `EquipmentLevel` 열거값(`ProductionLine`·`StorageZone`·`WorkCenter`…).
+   *
+   * `type` 은 현장의 낱말(`paint-booth`)이고 이것은 **표준이 정한 역할**이다. 둘은 다른 축이라 함께 든다 —
+   * 연동·집계는 표준 축으로, 화면은 현장 낱말로. 미지정이면 그 자리의 표준 역할을 아직 모른다는 뜻이고,
+   * 짐작해 채우지 않는다.
+   */
+  level?: EquipmentLevel
   footprint?: { x: number; y: number; w: number; h: number } // 있으면 area 기하 + 노드 중심좌표
   gs1Id?: string // 정식 GS1 정체성(§J) — 위치=SGLN. 결합(tag)/추적 canonical id. 받아들이기 경계서 부여(로컬 id=name/xref 로 보존).
 }
 
+/**
+ * 설비 속성 — **ISA-95 `EquipmentSpecificationProperty`(`OpEquipmentSpecificationPropertyType`) 1:1.**
+ * 그 타입도 `ID` + `Value`(`ValueString`·`DataType`·`UnitOfMeasure`) 이므로 공정 모수와 같은 모양이다.
+ *
+ * 단위 코드는 **UN/CEFACT 권고 20 공통코드**(EPCIS `uom` 과 같은 코드계): 속도는 `MTS`(metre per
+ * second) 또는 `KMH`(kilometre per hour). 코드를 우리가 발명하지 않는다.
+ */
+/**
+ * 자원 속성 — **커널 `ResourceProperty` 와 같은 모양**이고, 그 모양은 ISA-95 가 세 자원에 똑같이
+ * 정의한 것이다(`EquipmentPropertyType` · `PersonPropertyType` · `PhysicalAssetPropertyType`).
+ *
+ * 그래서 자원마다 다른 속성 타입을 두지 않는다 — 예전에는 설비만 속성을 가졌고(RefEquipmentProperty),
+ * 인원·자산에 붙는 사실은 **실을 자리가 없어서 들어오지 못했다.**
+ */
+export interface RefResourceProperty {
+  id: string
+  description?: string
+  value?: string
+  /** 표준 `Value.DataType`. */
+  dataType?: string
+  /** 표준 `Value.UnitOfMeasure` — UN/CEFACT 공통코드. 물리량에 단위가 없으면 소비처가 거절한다. */
+  uom?: string
+  /** 하위 속성(재귀) — 표준 `<X>PropertyChild`. */
+  children?: RefResourceProperty[]
+  /** 이 개체 속성이 구체화하는 등급 속성 — 표준 `<X>ClassPropertyID`. */
+  classPropertyId?: string
+}
+
+/** 옛 이름 — 설비 전용이던 시절의 별칭(소비처 호환). 신규 소싱은 `RefResourceProperty`. */
+export type RefEquipmentProperty = RefResourceProperty
+
+/**
+ * 자원 **등급 정의** — 커널 `ResourceClassDef` 와 같은 모양이고, 그 모양은 ISA-95 가 세 자원에 똑같이
+ * 정의한 것이다(`PersonnelClassType`·`EquipmentClassType`·`PhysicalAssetClassType`).
+ *
+ * 왜 필요한가: 원 시스템은 등급 **체계**를 갖고 있다("6축 용접 자격자" 는 "용접 자격자" 이고, 그것은
+ * "생산직" 이다). 그 체계가 들어올 자리가 없으면 요구와 소속이 **문자열이 똑같을 때만** 맞아,
+ * 현장에서는 되는 배정이 모델에서 막힌다.
+ */
+export interface RefResourceClass {
+  id: string
+  description?: string
+  /** 상위 등급들 — 표준 `<X>ClassBaseID`(복수 = 다중 상속). */
+  baseIds?: string[]
+  properties?: RefResourceProperty[]
+  testSpecificationIds?: string[]
+  /** 유효 기간(ISO) — 표준 `EffectiveStartDate`/`EffectiveEndDate`. 밖이면 자격이 성립하지 않는다. */
+  effectiveStart?: string
+  effectiveEnd?: string
+}
+
 export interface RefEquipment {
   id: string
   kind: string
@@ -25,6 +92,192 @@ export interface RefEquipment {
   mtbfMs?: number // 평균 고장 간격(확률적 고장) — 지정 시 커널이 breakdown 시뮬 → 주목(고장) 발생
   mttrMs?: number // 평균 수리 시간
   gs1Id?: string // 정식 GS1 정체성(§J) — 설비=GIAI.
+  /**
+   * 교대(가동시간) — 이 시간대에만 배정된다. `startHour <= endHour` 면 같은 날, 넘어가면 야간(22→6).
+   * 미지정=24시간 가용. 교대 밖 자원은 고장·계획정지와 **구별되는 이유**로 쉰다(상태에 드러난다).
+   */
+  window?: { startHour: number; endHour: number }
+  /**
+   * 근무 캘린더 — 표준 `WorkCalendarEntry`(복수). 있으면 `window` 보다 이것을 본다.
+   *
+   * 축을 프레임워크 `@things-factory/work-shift` 의 `WorkShift`(`fromDate`·`fromTime`·`toDate`·`toTime`)와
+   * 맞춰 두었다 — 그 엔티티를 교대의 정본으로 결선할 때 직선 매핑이 되게. **아직 결선하지 않았다**:
+   * 그 엔티티에는 자원 연결과 비근무(휴일)가 없어 확장이 함께 필요하고, operato-twin 의 의존성 추가는
+   * 앱 아키텍처 결정이다(커버리지 §4-7 에 결선 지점으로 기록).
+   */
+  workCalendar?: WorkCalendarEntry[]
+  /**
+   * 설비 속성(속도 등) — 없으면 **이동시간을 거리에서 계산할 수 없다**(속도 없이 거리만으로는 시간이
+   * 안 나온다). 그때는 커널 상수로 떨어지고 그 사실이 `specCoverage()` 에 남는다.
+   */
+  properties?: RefResourceProperty[]
+  /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`(교정 등). */
+  testSpecificationIds?: string[]
+  /**
+   * 유효 기간 — **표준 `EffectiveStartDate` / `EffectiveEndDate`**(개체 타입 셋 모두에 있다).
+   *
+   * 없으면 **폐기한 것이 영구히 살아 있다**: 배정 대상에 남고, 가용 수에 들어가고, 화면에 뜬다.
+   * 도입 예정인 것은 반대로 오늘부터 있는 것처럼 보인다. 기간 밖이면 커널이 그 시각의 모델에서
+   * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 조용히 지우지 않는다.
+   */
+  effectiveStart?: string
+  effectiveEnd?: string
+}
+
+/**
+ * 공정 모수 — 커널 `OperationParameter`(= ISA-95 `ParameterSpecification`/`ParameterType`) 와 **같은 모양**.
+ * 이름을 바꾸지 않는다: 인제스트 경계에서 어휘가 갈리면 그 자리에서 방언이 생긴다.
+ * ID 어휘의 정본은 커널 `OP_PARAM`(표준이 파라미터 ID 를 정하지 않으므로 우리가 한 곳에서 정한다).
+ */
+export interface RefOperationParameter {
+  id: string
+  /** ISA-95 `Value.ValueString` — 표준이 문자열로 싣는다. 기간 모수는 ISO 8601(`PT8M`). */
+  value: string
+  /** ISA-95 `Value.UnitOfMeasure`. 무차원(비율)이면 생략. */
+  uom?: string
+}
+
+/**
+ * 공정의 자재 요구·산출 — **ISA-95 `OperationsSegment.MaterialSpecification`** 과 같은 모양.
+ * 인원·설비·자산 명세와 같은 자리에 있어야 4대 자원이 대칭이 된다(자재만 빠져 있었다).
+ */
+export interface RefOpMaterialSpecification {
+  id?: string
+  /** 품목 등급으로 요구 — 표준 `MaterialClassID`. */
+  materialClass?: string
+  /** 특정 품목으로 요구 — 표준 `MaterialDefinitionID`. */
+  materialDefinition?: string
+  /** 표준 `MaterialUse` — 이 공정에서의 쓰임. */
+  use: 'consumed' | 'produced' | 'consumable'
+  /** 표준 `Quantity`. 단위 미지정이면 개수. */
+  quantity: number
+  uom?: string
+}
+
+/** 소요시간 변동 — **표준 밖 확장**(ISA-95 Duration 은 스칼라). 커널 `DurationVariability` 와 동형. */
+export interface RefOperationVariability {
+  distribution: 'constant' | 'exponential' | 'uniform' | 'triangular'
+  min?: string
+  max?: string
+  mode?: string
+}
+
+/**
+ * 오퍼레이션 명세 — ISA-95 `OperationsSegment`. 커널 `OperationDef` 와 필드 이름이 1:1이다.
+ *
+ * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 박아 둔 상수다.** 원 시스템(또는 가상 레퍼런스)이
+ * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
+ * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
+ */
+export interface RefOperation {
+  /** 작업 종류 키 — 커널 `FlowTask.kind` 와 같은 값이어야 명세가 그 작업에 붙는다. */
+  key: string
+  label: string
+  intent: 'transport' | 'process' | 'dwell'
+  locationType?: string
+  resourceType?: string
+  bizStep?: string
+  /** ISA-95 `OperationsSegment.Duration` — ISO 8601 기간(`PT12M`). */
+  duration?: string
+  variability?: RefOperationVariability
+  parameters?: RefOperationParameter[]
+  /**
+   * 필요 인원 — ISA-95 `PersonnelSpecification`(`PersonnelClassID` + `Quantity`) 1:1.
+   * 없으면 사람 없이 도는 공정이다(설비만 잡는다).
+   */
+  personnelSpecification?: { personnelClass?: string; quantity: number }[]
+  /** 필요 물리 자산 — ISA-95 `PhysicalAssetSpecification`(등급 + 수량). 빈 팔레트가 없으면 못 나간다. */
+  physicalAssetSpecification?: { assetClass?: string; quantity: number }[]
+  /**
+   * 필요·산출 자재 — ISA-95 `MaterialSpecification`. **4대 자원 중 자재만 이 자리가 없었다** —
+   * 그래서 부품이 떨어져 라인이 서는 상황이 예측에 나타나지 않았다.
+   * BOM 의 "몇 개" 는 여기다(품목 정의의 조립 구조에는 수량이 없다 — 1차 출처 확인).
+   */
+  materialSpecification?: RefOpMaterialSpecification[]
+}
+
+/**
+ * 사람 — **ISA-95 `Person`.** 설비와 별개 자원이다(고장·설비효율이 아니라 등급·교대로 산다).
+ * `personnelClass` 가 ISA-95 `PersonnelClassID` — 공정은 특정인이 아니라 **등급으로** 인원을 요구한다.
+ */
+export interface RefPerson {
+  id: string
+  name?: string
+  /**
+   * 속한 등급들 — **표준 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**.
+   * 복수인 것이 표준이고 그것이 자격 표현이다: 한 사람이 용접 자격과 지게차 자격을 함께 갖는다.
+   */
+  personnelClassIds?: string[]
+  /** 교대 — 설비와 같은 모양. 미지정=24시간 가용. */
+  window?: { startHour: number; endHour: number }
+  /** 근무 캘린더 — 표준 `WorkCalendarEntry`(복수). 2교대·휴게·휴일을 함께 표현한다. */
+  workCalendar?: WorkCalendarEntry[]
+  /**
+   * 기본 위치 — 표준 `Person.OperationalLocation`. 없으면 "이 라인에 몇 명 있나" 를 물을 수 없다.
+   * 사람은 움직이므로 이 값은 **출발점**이고, 실제 위치는 관측(person.status)이 갱신한다.
+   */
+  homeLocationId?: string
+  /**
+   * 자원 속성 — 표준 `PersonProperty`. **자격증·숙련도가 여기 들어간다.**
+   *
+   * 표준에는 자격(Qualification)이라는 별도 요소가 없다(`B2MML-Personnel.xsd` 확인). 자격은
+   * ① 등급 복수 소속으로(`personnelClassIds: ['welder-certified','forklift-licensed']`) ②
+   * 증빙은 이 속성으로(자격증 번호·만료일), ③ 검증 시험은 표준 `TestSpecificationID`(아직 미구현).
+   */
+  properties?: RefResourceProperty[]
+  /** 자격을 검증한 시험 명세들 — 표준 `TestSpecificationID`(참조만; 시험 명세·결과 모델은 아직 없다). */
+  testSpecificationIds?: string[]
+  /** 유효 기간 — 사람에게는 **입사 전·퇴사 후**다(자격 만료는 등급 쪽 기간이다: 사람은 남고 자격만 끊긴다). */
+  effectiveStart?: string
+  effectiveEnd?: string
+}
+
+/**
+ * 물리 자산(반복사용) — **ISA-95 `PhysicalAsset`, GS1 `GRAI`.**
+ * 팔레트·랙·용기처럼 **나갔다 돌아오는** 것. 물류단위(SSCC)와 다르다: SSCC 는 그 팔레트에 실린 화물
+ * 한 덩어리이고, GRAI 는 팔레트 자체다(오늘은 이 화물, 내일은 저 화물을 싣는다).
+ */
+export interface RefAsset {
+  id: string
+  name?: string
+  /**
+   * 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). 팔레트가 'euro-pallet' 이면서 'food-grade' 일 수 있다.
+   * 공정의 요구는 등급 하나 + 수량이다(표준 `PhysicalAssetSpecification`).
+   */
+  assetClassIds?: string[]
+  /** 기본 위치. */
+  homeLocationId?: string
+  /** 정식 GS1 정체성 — 반복사용 자산=GRAI. */
+  gs1Id?: string
+  /** 자원 속성 — 표준 `PhysicalAssetProperty`(적재 한도·규격 등). */
+  properties?: RefResourceProperty[]
+  /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
+  testSpecificationIds?: string[]
+  /** 유효 기간 — 자산에서는 **폐기한 팔레트가 풀에서 빠지는 것**이다(회수 대상 수가 부풀지 않게). */
+  effectiveStart?: string
+  effectiveEnd?: string
+}
+
+/**
+ * 품목 정의 — **ISA-95 `MaterialDefinition`.**
+ *
+ * 없으면 로트만 관측으로 들어오고 **품목이 무엇인지는 아무 데도 없다.** 그래서 같은 로트를 100개로
+ * 받아도 "몇 kg 인가" 에 답할 수 없다(커널 `quantityIn` 이 환산을 거부하는 근거).
+ *
+ * **표준에 단위 환산 요소는 없다**(1차 출처 전수 확인) — 속성 주머니뿐이다. 그래서 환산 계수는
+ * 커널이 정한 속성 이름(`perBaseUnit`, `uom` 이 대상 단위)으로 `properties` 에 싣는다.
+ */
+export interface RefMaterialDefinition {
+  /** 표준 `ID` — GTIN(`urn:epc:idpat:sgtin:…`)을 쓴다(정체성의 정본이 EPCIS 다). */
+  id: string
+  name?: string
+  /** 속한 등급들 — 표준 `MaterialClassID`(복수). */
+  materialClassIds?: string[]
+  /** 품목 속성 — 표준 `MaterialDefinitionProperty`. 환산 계수가 여기 들어간다. */
+  properties?: RefResourceProperty[]
+  testSpecificationIds?: string[]
+  effectiveStart?: string
+  effectiveEnd?: string
 }
 
 export interface ReferenceMaster {
@@ -32,9 +285,46 @@ export interface ReferenceMaster {
   system: 'wms' | 'yms' | 'mes'
   siteName: string
   /* spaceId 명시 시 그 공간을 참조(여러 트윈이 한 공간 공유, N:1). 없으면 source 에서 파생(1:1). */
-  space: { spaceId?: string; width: number; depth: number; unit?: string; geo?: { lat: number; lon: number; rotation?: number }; representations?: any[]; primaryId?: string }
+  /**
+   * 현장(공간). **시각 기준(`timezone`)이 여기 있는 이유**: 한 테넌트가 Rosarito(태평양)와 한국
+   * 공장을 함께 가질 수 있다. 테넌트 단위(`Domain.timezone`)로 두면 **둘 중 하나는 반드시 틀린다.**
+   * 시각 기준은 **물리 현장의 성질**이므로 공간이 그것을 갖는다(공간 중심 원칙).
+   *
+   * `timezone` 은 IANA 이름(`'America/Tijuana'`) — 오프셋 숫자가 아니다. 숫자로 두면 일광절약시간을
+   * 표현할 수 없고, 나중에 절대 구간으로 옮길 때도 이름이 있어야 계산할 수 있다.
+   */
+  space: { spaceId?: string; width: number; depth: number; unit?: string; timezone?: string; geo?: { lat: number; lon: number; rotation?: number }; representations?: any[]; primaryId?: string }
   locations: RefLocation[]
   equipment?: RefEquipment[]
+  /** 공정 명세(소요·변동·수율) — 없으면 커널 기본값으로 굴러간다(그 사실은 specCoverage 가 보고). */
+  operations?: RefOperation[]
+  /**
+   * **생산 정의**(레시피·라우트·자재 바인딩) — 커널의 정의-구동 MES 모드 입구.
+   *
+   * 없으면 커널은 레거시(하드코딩) 흐름으로 돈다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
+   * 커널은 그것을 보지 못한다** — 선언과 실행이 갈라지는 지점이라 자리를 연다.
+   */
+  mesSpec?: unknown
+  /**
+   * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 돌아가는 공장).
+   * 공정이 인원을 요구하는데 사람이 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
+   */
+  persons?: RefPerson[]
+  /**
+   * 물리 자산(반복사용) — 선언하지 않으면 자산 제약이 없는 트윈이다.
+   * 공정이 자산을 요구하는데 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
+   */
+  assets?: RefAsset[]
+  /**
+   * 등급 정의 — 표준 `PersonnelClass`·`EquipmentClass`·`PhysicalAssetClass`.
+   * 안 실어도 트윈은 돈다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
+   */
+  personnelClasses?: RefResourceClass[]
+  equipmentClasses?: RefResourceClass[]
+  assetClasses?: RefResourceClass[]
+  /** 품목 정의·등급 — 표준 `MaterialDefinition` / `MaterialClass`. 없으면 단위 환산을 할 수 없다. */
+  materialDefinitions?: RefMaterialDefinition[]
+  materialClasses?: RefResourceClass[]
 }
 
 export interface IngestedTwin {
@@ -47,27 +337,110 @@ export interface IngestedTwin {
  * 마스터 → 트윈 구조 매핑(순수). 노드타입을 카탈로그로 검증(모르는 타입은 warning, 버리진 않음 — 반영 우선).
  * @param catalog DOMAIN_CATALOG (커널 SSOT). 없으면 검증 생략.
  */
+/**
+ * IANA 시간대 이름 → **그 시각의** UTC 오프셋(분). 의존성 없이 `Intl` 로 푼다.
+ *
+ * `Intl.DateTimeFormat` 의 `longOffset` 은 `"GMT-07:00"` 처럼 나오고, 이것은 **일광절약시간을 반영한**
+ * 값이다. 그래서 8월의 `America/Tijuana` 는 −420(PDT), 1월은 −480(PST)이 된다.
+ *
+ * **한계를 밝힌다**: 여기서 나오는 것은 **한 시점의** 오프셋이다. 커널은 고정 오프셋으로 하루 중 분을
+ * 읽으므로, 보드를 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
+ * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
+ *
+ * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
+ * 그렇게 바꾸면 판정이 조용히 틀린다.
+ */
+export function utcOffsetOf(timezone?: string, at: Date = new Date()): number | undefined {
+  if (!timezone) return undefined
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone: timezone, timeZoneName: 'longOffset' }).formatToParts(at)
+    const name = parts.find(p => p.type === 'timeZoneName')?.value ?? ''
+    if (name === 'GMT') return 0 // UTC 계열은 오프셋 표기가 없다
+    const m = /^GMT([+-])(\d{1,2})(?::(\d{2}))?$/.exec(name)
+    if (!m) return undefined
+    const sign = m[1] === '-' ? -1 : 1
+    return sign * (Number(m[2]) * 60 + Number(m[3] ?? 0))
+  } catch {
+    return undefined // 알 수 없는 이름 — Intl 이 던진다
+  }
+}
+
 export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTwin {
   const warnings: string[] = []
-  const known: string[] = catalog?.[master.system]?.nodeTypes ?? []
+  const known: string[] = catalog?.[master.system]?.locationTypes ?? []
 
-  const nodeLocs = master.locations.filter(l => l.role === 'node' || l.role === 'both')
+  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 nodes = nodeLocs.map(l => {
-    if (known.length && !known.includes(l.type)) warnings.push(`unknown ${master.system} node type "${l.type}" (${l.id}) — 카탈로그에 없음`)
+  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, parentId: l.parentId, gs1Id: l.gs1Id }
+    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 }
   })
 
-  const movers = (master.equipment ?? []).map(e => ({ id: e.id, kind: e.kind, homeNode: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.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,
+    ...(e.window ? { window: e.window } : {}),
+    /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
+    ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),
+    /* 유효 기간도 손대지 않고 통과 — 판정은 커널이 자기 시계로 한다(호스트가 미리 자르지 않는다). */
+    ...(e.effectiveStart ? { effectiveStart: e.effectiveStart } : {}), ...(e.effectiveEnd ? { effectiveEnd: e.effectiveEnd } : {})
+  }))
 
   // 좌표(layout) — footprint 중심. 없으면 생략(coordinate-free 유지).
   const layout: Record<string, { x: number; y: number }> = {}
-  for (const l of nodeLocs) if (l.footprint) layout[l.id] = { x: l.footprint.x + l.footprint.w / 2, y: l.footprint.y + l.footprint.h / 2 }
+  for (const l of locationEntries) if (l.footprint) layout[l.id] = { x: l.footprint.x + l.footprint.w / 2, y: l.footprint.y + l.footprint.h / 2 }
 
   const spaceId = master.space.spaceId ?? `${master.source}-site`
-  const board = { nodes, movers, layout, spaceId }
+  /*
+   * 시각 기준을 커널이 읽을 형태로 푼다 — 커널은 zero-dep 이라 시간대 데이터베이스를 들이지 않고
+   * **분 오프셋**만 받는다(계약 `BoardDef.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`)
+  }
+  /*
+   * 오퍼레이션 명세를 board 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(BoardDef 확장 필드,
+   * 모르는 커널은 무시). 여기서 값을 손대지 않는다: 기간은 표준 표기(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`)
+    }
+  }
+  /* 사람도 손대지 않고 통과 — 등급·교대 그대로 커널까지 간다(경계에서 어휘를 갈지 않는다). */
+  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 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 materialDefinitions = master.materialDefinitions?.map(d => ({
+    id: d.id,
+    ...(d.name ? { description: 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 = {
+    locations, equipment, layout, spaceId,
+    /* 생산 정의도 손대지 않고 통과 — 경계에서 어휘를 갈지 않는다(커널이 그대로 소비한다). */
+    ...(master.mesSpec ? { mesSpec: master.mesSpec } : {}),
+    ...(materialDefinitions?.length ? { materialDefinitions } : {}),
+    ...(master.materialClasses?.length ? { materialClasses: master.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 } : {}),
+    ...(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,

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

@@ -27,9 +27,9 @@ export class TwinReferenceResolver {
         source: m.source,
         system: m.system,
         siteName: m.siteName,
-        nodeCount: m.locations.filter(l => l.role === 'node' || l.role === 'both').length,
+        locationCount: m.locations.filter(l => l.role === 'location' || l.role === 'both').length,
         areaCount: m.locations.filter(l => l.role === 'area' || l.role === 'both').length,
-        moverCount: (m.equipment ?? []).length,
+        equipmentCount: (m.equipment ?? []).length,
         imported: !!reg,
         running: !!TwinEngine.instances[m.source]
       })
@@ -144,7 +144,7 @@ export class TwinReferenceResolver {
   }
 
   /** 한 Connection 그룹 노드 상세 — 그 아래 생성된 트윈 인스턴스(라이브 대조·상태·기동여부). */
-  @Query(returns => ScalarObject, { nullable: true, description: 'One connection grouping node with its produced twin instances (live-checked). (reference-management §2.3)' })
+  @Query(returns => ScalarObject, { nullable: true, description: 'One connection grouping location with its produced twin instances (live-checked). (reference-management §2.3)' })
   async twinConnection(@Arg('source') source: string, @Ctx() context: ResolverContext): Promise<any | null> {
     const domainId = context.state.domain.id
     const r = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source } })

package/server/service/reference/template-registry.ts

@@ -31,7 +31,7 @@ export interface TemplateDetail {
   phases?: { key: string; label: string; system?: string; note?: string }[]
   /** 공정 라우트(오퍼레이션 시퀀스). */
   route?: { op: string; label?: string; resource?: string; intent?: string; bizStep?: string }[]
-  nodeTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]
+  locationTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]
   resourceTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]
   /** BOM/레시피 요약. */
   recipe?: {

package/server/service/twin-attention/twin-attention-query.ts

@@ -7,7 +7,7 @@ import { TwinEngine } from '../../engine/index.js'
 /*
  * 주목 신호(Attention) 질의 — 현재 스냅샷의 요약된 "봐야 할 것".
  * 커널 computeAttentions() 파생: severity(ISA-18.2/IEC 62682) · state(OPC UA A&C) ·
- * anchor(nodeId/moverId/orderId = 공간 위치) · suggestedAction(조치 제안). kind 는 도메인 소유(무방언).
+ * anchor(locationId/moverId/orderId = 공간 위치) · suggestedAction(조치 제안). kind 는 도메인 소유(무방언).
  * full StateSnapshot 대신 이 경량 목록을 AI read 도구·insight UI 가 소싱(대용량 덤프 회피).
  * (실시간 스트림은 twinState subscription 이 attentions 를 포함. 이건 one-shot '질의' 표면.)
  */

package/server/service/twin-control/twin-control-mutation.ts

@@ -30,7 +30,7 @@ export class TwinControlMutation {
     const ack = inst.runtime.dispatch({ ...command, tenantId: domainId })
     /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
-      await TwinEngine.syncBoardMovers(domainId, instanceId).catch(err => console.error('twin syncBoardMovers fail', err))
+      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
     }
     return { accepted: !!ack?.accepted, error: ack?.error }
   }

package/server/service/twin-event/twin-event-keys.ts

@@ -85,7 +85,7 @@ export function locationOf(envelope: any): string | undefined {
  * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
  * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.
  */
-export function moverOf(envelope: any): string | undefined {
+export function equipmentIdOf(envelope: any): string | undefined {
   const d = envelope?.data ?? envelope ?? {}
   return d.moverId ?? undefined
 }
@@ -97,6 +97,6 @@ export function twinEventKeys(envelope: any): TwinEventKeys {
     epc: clip(epcOf(envelope), 'epc'),
     orderId: clip(orderOf(envelope), 'orderId'),
     locationId: clip(locationOf(envelope), 'locationId'),
-    moverId: clip(moverOf(envelope), 'moverId')
+    moverId: clip(equipmentIdOf(envelope), 'moverId')
   }
 }

package/server/service/twin-event/twin-event.ts

@@ -61,6 +61,20 @@ export class TwinEvent {
   @Field(type => Int, { nullable: true, description: 'Monotonic state revision at which the event was emitted.' })
   revision?: number
 
+  /**
+   * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.
+   *
+   * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
+   * 이벤트를 새 공장에 대고 접어 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
+   * 구조가 바뀌는 지점에서 갈아탄 뒤 이어 접는다.
+   *
+   * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
+   * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
+   */
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Structure revision (TwinStructure.rev) in force when this event happened. Absent on rows written before structure revisions existed; those belong to the oldest revision.' })
+  structureRev?: number
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Simulation event time (ISO 8601).' })
   eventTime?: string
@@ -90,7 +104,7 @@ export class TwinEvent {
   locationId?: string
 
   @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Equipment or mover identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server.' })
+  @Field({ nullable: true, description: 'Equipment identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server. The column keeps the legacy name `moverId`: the journal is append-only history and mixing two names for the same fact across time is worse than an outdated name. Renaming belongs with event-schema versioning.' })
   moverId?: string
 
   @Column({ type: 'simple-json', nullable: true })