@things-factory/headless-twin 10.0.9 → 10.0.10

package/server/engine/travel-estimator.ts

@@ -4,7 +4,7 @@
  * 커널은 좌표를 모른다(설계: 좌표-free — "얼마 걸리나" 만 소비하고 "어떤 경로로" 는 씬 소관).
  * 그래서 거리 기반 계산은 **호스트가 추정기로 주입**한다(`DurationEstimator` 시임).
  *
- * 좌표는 이미 있다: 마스터의 `RefLocation.footprint` → `masterToTwin` 이 `board.layout`(노드 중심)으로
+ * 좌표는 이미 있다: 마스터의 `RefLocation.footprint` → `masterToTwin` 이 `model.layout`(노드 중심)으로
  * 낸다. 없던 것은 **속도**다 — 속도 없이 거리만으로는 시간이 나오지 않는다. 그래서 설비 속성
  * (ISA-95 `EquipmentSpecificationProperty`)으로 받는다.
  *
@@ -16,8 +16,13 @@
 
 import type { MeasuredEstimate } from './measured-estimator.js'
 
-/** UN/CEFACT 권고 20 공통코드 → m/s 변환. 모르는 코드는 변환하지 않는다(발명 금지). */
-const SPEED_TO_MPS: Record<string, number> = {
+/**
+ * UN/CEFACT 권고 20 공통코드 → m/s 변환. 모르는 코드는 변환하지 않는다(발명 금지).
+ *
+ * **내보내는 이유**: 선언 화면·AI 가 「어떤 단위를 받나」를 말해야 하고, 그 목록이 두 곳에 적히면
+ * 화면이 받아 준 단위를 추정기가 모르는 일이 생긴다(그때 공정 시간이 조용히 사라진다).
+ */
+export const SPEED_TO_MPS: Record<string, number> = {
   MTS: 1, // metre per second
   KMH: 1000 / 3600, // kilometre per hour
   '2M': 0.3048, // foot per second
@@ -44,9 +49,9 @@ export interface DurationEstimatorLike {
 }
 
 export interface TravelEstimatorInput {
-  /** 노드 중심 좌표(masterToTwin 산출 `board.layout`). */
+  /** 노드 중심 좌표(masterToTwin 산출 `model.layout`). */
   layout?: Record<string, { x: number; y: number }>
-  /** 무버(자원) — kind 와 속성. `board.equipment`. */
+  /** 무버(자원) — kind 와 속성. `model.equipment`. */
   equipment?: { id: string; kind: string; properties?: { id: string; value: string; uom?: string }[] }[]
   /** 좌표 단위(공간 `content.unit`). 미터가 아니면 계산하지 않는다(환산을 추측하지 않는다). */
   unit?: string
@@ -87,7 +92,7 @@ export function buildTravelEstimator(input: TravelEstimatorInput): TravelEstimat
   const layout = input.layout
   const unit = input.unit ?? 'm'
   if (unit !== 'm') reasons.push(`space unit is "${unit}", not metres — travel time is not computed (no assumed conversion)`)
-  if (!layout || !Object.keys(layout).length) reasons.push('no location coordinates (board.layout empty) — travel time cannot be derived from distance')
+  if (!layout || !Object.keys(layout).length) reasons.push('no location coordinates (model.layout empty) — travel time cannot be derived from distance')
   const speedsByKind = readSpeeds(input.equipment, reasons)
   if (!Object.keys(speedsByKind).length) reasons.push('no resource declares a speed property — distance alone cannot produce a duration')
   if (reasons.length) return { reasons, speedsByKind }