@things-factory/headless-twin 10.0.9 → 10.0.11

package/server/engine/model-basis.ts

@@ -10,7 +10,7 @@
  * 적용하지 않고 **그 사실을 응답에 싣는다**(조용히 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
  *
  * 비교는 **상대 허용오차**로 한다(양자화 지문이 아니라). 실측 p50 은 새 기록이 쌓일 때마다 1~2초씩
- * 흔들리는데, 값을 버킷으로 뭉개 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
+ * 흔들리는데, 값을 버킷으로 합쳐 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
  * "작은 드리프트로 학습을 무효화하지 않는다" 는 목적을 경계에서 못 지킨다. 비율로 비교하면 어디서든
  * 같은 규칙이 성립한다: 10% 이내는 같은 모델, 30초→47초(57%)는 다른 모델.
  *
@@ -18,7 +18,17 @@
  *  ① 실측으로 배운 작업 종류별 소요 ② 자원 종류별 속도 ③ 선언된 공정 소요.
  */
 
-/** 같은 모델로 볼 상대 허용오차 — 이 비율 안의 변화는 드리프트, 넘으면 다른 모델. */
+/**
+ * 허용오차의 **기본값** — 선언이 아무 말도 없을 때만 쓴다.
+ *
+ * 10% 는 근거에서 나온 수가 아니라 **판단값**이다(그 사실을 적어 두는 것이 이 주석의 목적이다). 그리고
+ * 단일 잣대로 쓰면 틀린다 — 우리 트레일러 템플릿이 그것을 보여 준다: 용접은 변동폭을 `PT55M~PT1H35M`
+ * (선언 소요 `PT1H10M` 기준 −21%~+36%)로 **스스로 선언한다.** 10% 관문은 그 공정의 **정상 변동조차**
+ * "다른 모델" 로 판정해 보정을 끊는다. 반대로 1% 변동도 치명적인 공정에는 10% 가 너무 느슨하다.
+ *
+ * 그래서 허용오차는 **그 공정이 선언한 변동폭에서 나온다**(§toleranceOf). 선언이 있으면 선언이 이기고,
+ * 없을 때만 이 값으로 떨어진다 — 도메인 설정을 새로 만들지 않는다(현장이 이미 말한 것을 읽는다).
+ */
 export const BASIS_TOLERANCE = 0.1
 
 export interface ModelBasis {
@@ -26,8 +36,51 @@ export interface ModelBasis {
   measured?: Record<string, number>
   /** 자원 종류 → 속도(m/s). `buildTravelEstimator().speedsByKind`. */
   speeds?: Record<string, number>
-  /** 선언된 공정 소요 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델). */
-  declared?: { key: string; duration?: string }[]
+  /**
+   * 선언된 공정 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델).
+   *
+   * **변동폭도 지문에 든다.** 변동폭이 허용오차를 정하므로(§toleranceOf), 그것이 바뀌었는데 "같은 모델"
+   * 이라고 하면 판정의 잣대가 조용히 바뀐 채로 학습이 이어진다.
+   */
+  declared?: DeclaredOperation[]
+}
+
+/** 선언된 공정 하나 — 소요와 변동폭(모델의 `operations` 원형에서 필요한 만큼만). */
+export interface DeclaredOperation {
+  key: string
+  duration?: string
+  variability?: { distribution?: string; min?: string; max?: string; mode?: string }
+}
+
+/** ISO 8601 기간 → 밀리초. 읽을 수 없으면 `undefined`(짐작해 고치지 않는다). */
+function isoMs(iso?: string): number | undefined {
+  if (!iso) return undefined
+  const m = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?)?$/.exec(iso)
+  if (!m || !m.slice(1).some(Boolean)) return undefined
+  return ((Number(m[1] ?? 0) * 24 + Number(m[2] ?? 0)) * 60 + Number(m[3] ?? 0)) * 60_000 + Number(m[4] ?? 0) * 1000
+}
+
+/**
+ * 작업 종류별 **허용오차** — 그 공정이 선언한 변동폭에서 나온다.
+ *
+ * 실측 p50 은 정상 변동 안에서 흔들린다. 그 흔들림을 "다른 모델" 로 읽으면 보정이 자꾸 끊기고, 사용자는
+ * 학습이 왜 안 듣는지 모른다. 얼마나 흔들리는 것이 정상인지는 **현장이 이미 선언했다**(`variability`).
+ *
+ * 반폭을 쓴다(`(max − min) / 2 / 소요`) — 중앙에서 어느 쪽으로든 그만큼은 정상이라는 뜻이다.
+ * 선언이 없거나 읽을 수 없으면 기본값으로 떨어진다(짐작해 만들지 않는다).
+ */
+export function toleranceOf(declared?: DeclaredOperation[]): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const o of declared ?? []) {
+    if (!o?.key) continue
+    const base = isoMs(o.duration)
+    const min = isoMs(o.variability?.min)
+    const max = isoMs(o.variability?.max)
+    if (!base || min === undefined || max === undefined || !(max > min)) continue
+    const half = (max - min) / 2 / base
+    if (Number.isFinite(half) && half > 0) out[o.key] = half
+  }
+  return out
 }
 
 /** 뜻 있는 수만 남긴다 — 0·음수·NaN 은 모델이 아니다. */
@@ -37,21 +90,27 @@ function clean(map?: Record<string, number>): Record<string, number> {
   return out
 }
 
-function declaredMap(list?: { key: string; duration?: string }[]): Record<string, string> {
+function declaredMap(list?: DeclaredOperation[]): Record<string, string> {
   const out: Record<string, string> = {}
-  for (const o of list ?? []) if (o?.key && o.duration) out[o.key] = o.duration
+  for (const o of list ?? []) {
+    if (!o?.key) continue
+    const v = o.variability
+    /* 변동폭까지 한 문장으로 — 순서를 고정해 같은 선언이 같은 문자열이 되게 한다. */
+    const spread = v ? `~${v.distribution ?? '?'}:${v.min ?? ''}..${v.max ?? ''}@${v.mode ?? ''}` : ''
+    if (o.duration || spread) out[o.key] = `${o.duration ?? ''}${spread}`
+  }
   return out
 }
 
 /** 두 수치 지도가 실질적으로 다른가 — 키 집합이 다르거나, 값이 허용오차를 넘어 다르면 다르다. */
-function numericChanged(a: Record<string, number>, b: Record<string, number>, tol: number): boolean {
+function numericChanged(a: Record<string, number>, b: Record<string, number>, tolOf: (key: string) => number): boolean {
   const keys = new Set([...Object.keys(a), ...Object.keys(b)])
   for (const k of keys) {
     const x = a[k]
     const y = b[k]
     if (x === undefined || y === undefined) return true // 새로 배운 종류·사라진 종류 = 다른 모델
     const base = Math.max(Math.abs(x), Math.abs(y))
-    if (base > 0 && Math.abs(x - y) / base > tol) return true
+    if (base > 0 && Math.abs(x - y) / base > tolOf(k)) return true
   }
   return false
 }
@@ -62,8 +121,17 @@ function numericChanged(a: Record<string, number>, b: Record<string, number>, to
  */
 export function modelBasisChanged(before?: ModelBasis, after?: ModelBasis, tol: number = BASIS_TOLERANCE): boolean {
   if (!before || !after) return false
-  if (numericChanged(clean(before.measured), clean(after.measured), tol)) return true
-  if (numericChanged(clean(before.speeds), clean(after.speeds), tol)) return true
+  /*
+   * 허용오차는 **선언이 정한다** — 배운 시점과 지금의 선언이 다를 수 있으므로 둘 중 **넓은 쪽**을 쓴다.
+   * 좁은 쪽을 쓰면 선언을 넓힌 직후에 정상 변동이 "다른 모델" 로 잡힌다(그 변경 자체는 아래 선언 비교가
+   * 이미 잡으므로, 여기서 또 잡을 필요가 없다).
+   */
+  const tolBefore = toleranceOf(before.declared)
+  const tolAfter = toleranceOf(after.declared)
+  const tolOf = (key: string): number => Math.max(tolBefore[key] ?? tol, tolAfter[key] ?? tol)
+  if (numericChanged(clean(before.measured), clean(after.measured), tolOf)) return true
+  /* 속도는 자원 종류별이고 선언된 변동폭이 없다 — 기본값이 그대로 쓰인다. */
+  if (numericChanged(clean(before.speeds), clean(after.speeds), () => tol)) return true
   const da = declaredMap(before.declared)
   const db = declaredMap(after.declared)
   const keys = new Set([...Object.keys(da), ...Object.keys(db)])

package/server/engine/{board-vocabulary.ts → model-vocabulary.ts}

@@ -1,52 +1,73 @@
 /*
- * 저장된 보드의 **어휘 세대를 흡수한다** — 읽는 순간 한 어휘로. 순수.
+ * 저장된 트윈 모델의 **어휘 세대를 흡수한다** — 읽는 순간 한 어휘로. 순수.
  *
  * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
- * 트윈 모델러의 엔티티 목록이 **통째로 비어 있었다.** 오류도 없었다. 원인은 이 인스턴스의 저장된 보드가
+ * 트윈 모델러의 엔티티 목록이 **통째로 비어 있었다.** 오류도 없었다. 원인은 이 인스턴스의 저장된 모델가
  * 옛 어휘였고 화면과 호스트는 새 어휘(`locations`/`equipment`)를 읽었기 때문이다. 그 옛 이름들은
  * 아래 `RETIRED_KEYS` 에 있다 — 흡수할 세대의 이름을 적지 않고는 이 파일을 쓸 수 없다.
  *
  * 커널에는 이미 세대를 흡수하는 리더가 있다(`readBoardLocations`·`readBoardEquipment` — 세 세대
- * `movers`→`equipmentList`→`equipment`, 실측 주석에 "저장된 보드 23개 중 13개가 `movers`"). 그런데 **그
+ * `movers`→`equipmentList`→`equipment`, 실측 주석에 "저장된 모델 23개 중 13개가 `movers`"). 그런데 **그
  * 리더를 거치는 곳이 목록뿐**이었다. 상세·구조 서명·주행 추정기·설비 동기는 컬렉션을 직접 읽어
  * **오류 없이 빈 공장**으로 읽었다:
  *
  *  · 모델러·팔레트·보드 자동생성 → 엔티티 0(사용자가 본 증상)
  *  · 구조 서명 → `N[]M[]` — **서로 다른 두 공장이 구조적으로 같아 보인다**(변경 감지가 죽는다)
  *  · 주행 추정기 → 설비 0이라 거리 기반 소요시간을 못 만든다
- *  · 설비 동기 → 아는 설비가 0이라 중복 append + 한 보드에 두 세대가 섞인다
+ *  · 설비 동기 → 아는 설비가 0이라 중복 append + 한 모델에 두 세대가 섞인다
  *
  * ── 왜 자리마다 고치지 않나 ─────────────────────────────────────────────────
- * 저장된 보드를 읽는 자리가 **27곳**이다. 자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠진다 —
+ * 저장된 모델를 읽는 자리가 **27곳**이다. 자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠진다 —
  * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 조용하다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
  * (엔티티 컬럼 변환기). 그 뒤로는 코드가 세대를 알 필요가 없다.
  *
  * ── 쓰기는 건드리지 않는다 ──────────────────────────────────────────────────
- * 저장은 주는 대로 한다(새 쓰기는 이미 새 어휘다). 읽기가 정규화되므로, 저장된 옛 보드는 **다음에
- * 저장될 때 자연히 새 어휘로 옮겨간다** — 마이그레이션을 따로 돌리지 않는다.
+ * 저장은 주는 대로 한다(새 쓰기는 이미 새 어휘다). 읽기가 정규화되므로, 저장된 옛 모델는 **다음에
+ * 저장될 때 자연히 새 어휘로 옮겨간다** — 마이그레이션을 따로 실행하지 않는다.
  */
 import { readBoardLocations, readBoardEquipment } from '@operato/twin-kernel'
 
 /** 흡수하고 **내보내지 않는** 옛 키 — 남겨 두면 소비처가 두 어휘를 다시 보게 된다. */
 const RETIRED_KEYS = ['nodes', 'movers', 'equipmentList'] as const // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
 
+/** 등급 축들 — 넷이 같은 모양이라 같은 규칙을 쓴다(어느 자원이든 표시명은 `name`). */
+const CLASS_KEYS = ['personnelClasses', 'equipmentClasses', 'assetClasses', 'materialClasses'] as const
+
 /**
- * 보드를 정본 어휘로 — `locations`·`equipment` 만 남는다. 새 어휘 보드에는 **아무 일도 하지 않는다**
+ * 보드를 정본 어휘로 — `locations`·`equipment` 만 남는다. 새 어휘 모델에는 **아무 일도 하지 않는다**
  * (같은 값을 다시 담을 뿐이라 멱등).
  *
- * 보드가 아닌 것(없음·배열·원시값)은 **그대로 통과**시킨다 — 모양을 짐작해 고치지 않는다.
+ * 모델이 아닌 것(없음·배열·원시값)은 **그대로 통과**시킨다 — 모양을 짐작해 고치지 않는다.
  */
-export function canonicalBoard<T = any>(board: T): T {
-  if (!board || typeof board !== 'object' || Array.isArray(board)) return board
+export function canonicalModel<T = any>(model: T): T {
+  if (!model || typeof model !== 'object' || Array.isArray(model)) return model
 
   const rest: Record<string, unknown> = {}
-  for (const [k, v] of Object.entries(board as Record<string, unknown>)) {
+  for (const [k, v] of Object.entries(model as Record<string, unknown>)) {
     if ((RETIRED_KEYS as readonly string[]).includes(k)) continue
     rest[k] = v
   }
 
+  /*
+   * **등급의 표시명은 `name` 이다** — 옛 모델는 `description` 에 담았다.
+   *
+   * 표준 마스터가 등급 표시명을 `description` 으로 주기 때문에 그대로 저장돼 있었고, 화면은 그것을
+   * "설명" 열에 앉혔다 — 사용자에게는 이름인데 머리글은 설명이라, 같은 것을 축마다 다른 이름으로
+   * 부르게 된다. 인제스트 문에서 이미 `name` 으로 옮기고 있지만, **이미 저장된 모델**가 그대로 남아
+   * 새 트윈만 고쳐진다. 정규화의 집은 여기 하나다(위 머리말의 이유 그대로).
+   */
+  for (const key of CLASS_KEYS) {
+    const list = rest[key]
+    if (!Array.isArray(list)) continue
+    rest[key] = list.map((c: any) =>
+      c && typeof c === 'object' && !c.name && c.description
+        ? (({ description, ...keep }) => ({ ...keep, name: description }))(c)
+        : c
+    )
+  }
+
   /* 리더가 세대를 고른다 — 여기서 `??` 사슬을 다시 적으면 세대 규칙이 두 곳이 된다. */
-  return { ...rest, locations: readBoardLocations(board as any), equipment: readBoardEquipment(board as any) } as T
+  return { ...rest, locations: readBoardLocations(model as any), equipment: readBoardEquipment(model as any) } as T
 }
 
 /**
@@ -55,7 +76,7 @@ export function canonicalBoard<T = any>(board: T): T {
  * `to`(쓰기)는 손대지 않는다: 저장은 호출부가 준 그대로가 진실이고, 읽기가 정규화되므로 다음 저장에서
  * 자연히 새 어휘가 된다.
  */
-export const boardColumnTransformer = {
-  from: (value: any) => canonicalBoard(value),
+export const modelColumnTransformer = {
+  from: (value: any) => canonicalModel(value),
   to: (value: any) => value
 }

package/server/engine/oee-accumulator.ts

@@ -23,6 +23,12 @@ interface Acc {
   scrapCount: number
 }
 
+/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 접을 수 있다. */
+export interface OeeCheckpoint {
+  maxMs: number
+  acc: ({ moverId: string } & Acc)[]
+}
+
 export class OeeAccumulator {
   private acc = new Map<string, Acc>()
   private maxMs = 0 // 최신 이벤트 시각 — nowMs 기본값(현재 계측 시점)
@@ -36,6 +42,27 @@ export class OeeAccumulator {
     return a
   }
 
+  /**
+   * **재개점** — 이 누적기의 상태 전부(이어 접기의 씨앗).
+   *
+   * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
+   * 가동 이력은 원 시스템이 누적을 주지 않아 **우리가 이벤트를 적분해** 만든다. 그래서 저널을 꼬리만
+   * 접으면 이 누적기는 꼬리분만 갖게 되고, 화면의 가용률·수율이 조용히 작아진다(오류는 나지 않는다).
+   * 재개점을 함께 저장·복원해야 「이어 접은 값」이 「0부터 접은 값」과 같아진다.
+   */
+  serialize(): OeeCheckpoint {
+    return {
+      maxMs: this.maxMs,
+      acc: [...this.acc.entries()].map(([moverId, a]) => ({ moverId, ...a }))
+    }
+  }
+
+  /** 재개점에서 되세운다 — 모르는 것은 지어내지 않는다(없으면 빈 누적기다). */
+  restore(cp: OeeCheckpoint | undefined | null): void {
+    this.maxMs = cp?.maxMs ?? 0
+    this.acc = new Map((cp?.acc ?? []).map(({ moverId, ...a }) => [moverId, { ...a }]))
+  }
+
   /** equipment.status(시간-in-상태) + quality.output(양품/불량) 소비. 다른 eventType 무시. */
   apply(env: CanonicalEnvelope): void {
     const t = Date.parse(env.eventTime)
@@ -62,7 +89,13 @@ export class OeeAccumulator {
   /** 무버 OEE 카운터 — 마지막 상태 구간을 nowMs(기본=최신 이벤트 시각)까지 flush. busy→run 근사, setup=0. */
   counters(moverId: string, nowMs: number = this.maxMs): OeeCounters {
     const a = this.acc.get(moverId)
-    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, metricsSinceMs: 0 }
+    /*
+     * **이 설비의 이벤트를 하나도 못 봤다** — 계측 창이 없다는 뜻이고, 그것을 `0` 으로 메우면
+     * "1970년부터 재고 있었다" 가 된다. 시각이 밀리초 epoch 이므로 그 값이 곧 지금 시각이 되어,
+     * 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다. 창을 **말하지 않는다** — 공식이
+     * 없음을 없음으로 다룬다(§computeOee).
+     */
+    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 }
     const dt = Math.max(0, nowMs - a.lastMs)
     let busyMs = a.busyMs
     let downMs = a.downMs

package/server/engine/operation-basis.ts

@@ -0,0 +1,100 @@
+/*
+ * 이 트윈이 **어떤 공정을 돌리고, 그 시간이 어디서 오나.**
+ *
+ * ── 왜 이 목록이 필요한가 (2026-08-18) ─────────────────────────────────────
+ * 「측정이 없을 때의 표준 시간」을 현장이 선언하려면 먼저 **무엇에 선언할지** 보여야 한다. 그런데 공정은
+ * 자리·설비와 달리 모델에 행이 없을 수 있다 — 실측: 운영 중인 트윈 35개 중 창고·야드는 공정 명세 행이
+ * 0개였고(MES만 4개), 그 트윈들의 시간은 전부 커널 상수에서 왔다.
+ *
+ * 그래서 목록을 **지어내지 않고 네 곳에서 모은다**:
+ *  ① 원천 명세 행(`model.operations`) — 원 시스템이 말한 공정.
+ *  ② 커널의 자기보고(`specCoverage()`) — **실제로 돌린** 공정과 그 시간의 출처.
+ *  ③ 이력에서 배운 종류(`measuredOperationKinds`) — 재기동에도 남는 근거.
+ *  ④ 우리가 이미 선언한 것(`model.localDurations`) — 선언해 둔 공정이 목록에서 사라지지 않게.
+ *
+ * ③이 필요한 이유는 실측으로 드러났다: ②는 **작업이 새로 생길 때** 채워지므로, 이력이 풍부한 창고
+ * 트윈도 재기동 직후에는 목록이 비었다 — 값을 채울 곳을 보여야 하는 화면이 정작 그때 아무 말도 못 한다.
+ *
+ * 그래도 셋 다 비는 트윈은 있다(한 번도 돌지 않고 명세 행도 없는 새 트윈). 그때 「공정이 없다」고 말하지
+ * 않는다(모르는 것이다) — 부르는 쪽이 그 사실을 그대로 화면에 옮긴다.
+ */
+import { readSpecCoverage } from './spec-coverage.ts'
+
+/** 공정 한 종류 — 이름과 「지금 무엇으로 도나」. */
+export interface OperationBasisRow {
+  /** 작업 종류(`FlowTask.kind` = `OperationDef.key`) — 선언이 겨누는 id 다. */
+  kind: string
+  /** 사람이 읽는 이름 — 원천 명세 행이 있을 때만(없으면 종류 이름이 곧 이름이다). */
+  label?: string
+  /**
+   * 지금 이 종류의 시간이 어디서 오나 — 커널의 자기보고, 또는 **이력에서 배운 사실**. 없으면 모른다.
+   *  · `measured` — 이 현장의 이력에서 배운 값(가장 강한 근거). **선언보다 이긴다.**
+   *  · `declared` — 선언된 값(현장이 정한 것 또는 원천 명세 행).
+   *  · `default`  — 커널 소스의 상수. 이 목록의 존재 이유다.
+   */
+  basis?: 'measured' | 'declared' | 'default'
+  /** 원천 명세 행이 말한 시간(ISO 8601) — 있으면. 우리 선언이 이것을 이긴다. */
+  referenceDuration?: string
+  /** 우리가 선언해 둔 시간(ISO 8601) — 있으면. */
+  localDuration?: string
+}
+
+/**
+ * 공정 목록을 모은다 — **넷의 합집합**, 순서는 원천 행 → 돌린 것 → 이력에서 배운 것 → 선언한 것.
+ *
+ * `kernel` 이 없으면(정지 트윈) ②가 빠지고, `measuredKinds` 를 주지 않으면 ③이 빠진다: 그 사실은
+ * `basis` 가 비는 것으로 드러난다(빈칸이 곧 「모른다」다).
+ */
+export function operationBasis(model: any, kernel?: any, measuredKinds?: readonly string[]): OperationBasisRow[] {
+  const rows = new Map<string, OperationBasisRow>()
+  const at = (kind: string): OperationBasisRow => {
+    const cur = rows.get(kind)
+    if (cur) return cur
+    const row: OperationBasisRow = { kind }
+    rows.set(kind, row)
+    return row
+  }
+
+  for (const o of (model?.operations ?? []) as any[]) {
+    if (!o?.key) continue
+    const row = at(String(o.key))
+    if (o.label) row.label = String(o.label)
+    if (o.duration) row.referenceDuration = String(o.duration)
+  }
+
+  const coverage = kernel ? readSpecCoverage(kernel) : undefined
+  for (const o of coverage?.operations ?? []) {
+    if (!o?.kind) continue
+    at(String(o.kind)).basis = o.duration
+  }
+
+  /*
+   * 이력에서 배운 종류 — 커널이 아직 이 종류를 돌리지 않았어도 **추정기가 답할 수 있다**. 그래서 근거를
+   * `measured` 로 채운다: 짐작이 아니라 설치된 추정기가 그 종류에 실측값을 줄 것이라는 사실이다.
+   * 커널이 이미 보고한 종류는 **덮지 않는다** — 실제로 돌린 것이 더 강한 사실이다.
+   */
+  for (const kind of measuredKinds ?? []) {
+    if (!kind) continue
+    const row = at(String(kind))
+    if (!row.basis) row.basis = 'measured'
+  }
+
+  const declared = (model?.localDurations ?? {}) as Record<string, string>
+  for (const [kind, iso] of Object.entries(declared)) {
+    if (!kind) continue
+    at(kind).localDuration = String(iso)
+  }
+
+  return [...rows.values()]
+}
+
+/**
+ * 선언을 받아도 되는 공정 이름들 — **하나도 확인할 수 없으면 `undefined`**(모른다).
+ *
+ * 빈 배열로 답하지 않는 이유: 빈 배열은 「어떤 이름도 안 된다」로 읽히고, 그러면 아직 돌지 않은 트윈에는
+ * 아무것도 선언할 수 없다. 모르는 것과 없는 것은 다르다 — 모를 때는 받아 주고 그 사실을 말한다.
+ */
+export function knownOperationKinds(model: any, kernel?: any, measuredKinds?: readonly string[]): string[] | undefined {
+  const kinds = operationBasis(model, kernel, measuredKinds).map(r => r.kind)
+  return kinds.length ? kinds : undefined
+}

package/server/engine/property-effects.ts

@@ -0,0 +1,199 @@
+/*
+ * 자원 속성의 **효과 등록부** — 이 속성이 무엇을 바꾸나.
+ *
+ * ── 왜 있나 ─────────────────────────────────────────────────────────────────
+ * 속성은 **열려 있다**: 템플릿·마스터가 아무 id 로나 사실을 실어 보낼 수 있고, 커널은 그것을 그대로
+ * 나르고 화면은 단위와 함께 보인다(표준이 속성 어휘를 정하지 않으므로 그것이 옳다).
+ *
+ * 그런데 **효과는 닫혀 있다**: 값이 계산·배정·판정을 바꾸려면 그 규칙을 코드가 알아야 한다. 지금
+ * 효과가 있는 것은 둘뿐이다. 문제는 그 사실이 **어디에도 드러나지 않는다**는 것이었다 — 사용자는
+ * 속성을 넣으면 무언가 달라질 것으로 기대하는데, 실제로는 표에 한 줄이 늘 뿐이다.
+ *
+ * 그래서 이 등록부는 **지어내지 않고 드러낸다**: 읽는 코드가 있는 것만 적고, 없는 것은 "표시만 된다"
+ * 고 화면이 말한다. 새 효과를 코드로 붙이는 사람은 **여기 한 줄을 더한다** — 그러지 않으면 사용자는
+ * 그 효과가 있는지 알 수 없다.
+ *
+ * ⚠️ 이 파일은 등록부이고 판정이 아니다. 값을 실제로 읽는 곳은 각자다(아래 `readBy` 가 그 자리를
+ * 가리킨다) — 여기에 계산을 옮겨 오면 규칙이 두 벌이 된다.
+ */
+
+/** 효과가 있는 속성 하나. */
+export interface PropertyEffect {
+  /** 속성 id — 선언에 적히는 그 이름(`ResourceProperty.id`). */
+  id: string
+  /** 어느 축의 속성인가 — 그 축의 항목에만 이 효과를 말한다. */
+  axes: string[]
+  /** 무엇을 바꾸나 — 화면이 읽는 i18n 키(언어중립: 서버는 사람 말을 만들지 않는다). */
+  effect: string
+  /** 실제로 읽는 코드 — 지어낸 효과를 등록하지 않기 위한 표식이다(없는 자리를 가리키면 리뷰가 잡는다). */
+  readBy: string
+}
+
+export const PROPERTY_EFFECTS: PropertyEffect[] = [
+  {
+    id: 'speed',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.speed',
+    readBy: 'headless-twin/server/engine/travel-estimator.ts (buildTravelEstimator)'
+  },
+  {
+    id: 'perBaseUnit',
+    axes: ['materialDefinitions'],
+    effect: 'twin.propeffect.perBaseUnit',
+    readBy: '@operato/twin-kernel conversionFactorOf'
+  },
+  /*
+   * ── 에너지 속성 (2026-08-18) ──────────────────────────────────────────────
+   *
+   * 이 값들은 **오래전부터 읽히고 있었다** — 커널이 부하·피크·배터리를 그것으로 계산하고, 호스트가
+   * 금액을 그것으로 만든다. 그런데 등록부에 없어서 화면은 그 값들에 대해 「표시만 됩니다」라고 말했다.
+   * 조용한 거짓말이다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다.
+   *
+   * 효과를 새로 만든 것이 아니라 **있는 효과를 드러낸다.** `readBy` 는 실제로 읽는 자리를 가리킨다.
+   */
+  {
+    id: 'contract.kW',
+    axes: ['locations'],
+    effect: 'twin.propeffect.contractKW',
+    readBy: '@operato/twin-kernel EmsKernel.declaredContractKW (계약 대비 판정·초과 주의)'
+  },
+  {
+    id: 'power.ratedKW',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.ratedKW',
+    readBy: '@operato/twin-kernel EmsKernel.deriveEquipmentLoad (가동 중 부하)'
+  },
+  {
+    id: 'power.standbyKW',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.standbyKW',
+    readBy: '@operato/twin-kernel EmsKernel.deriveEquipmentLoad (대기 중 부하)'
+  },
+  {
+    id: 'storage.capacityKWh',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.capacityKWh',
+    readBy: '@operato/twin-kernel EmsKernel (축전지 방전 가능량)'
+  },
+  {
+    id: 'dispatch.dischargeAboveKW',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.dischargeAboveKW',
+    readBy: '@operato/twin-kernel EmsKernel (방전 시작 문턱)'
+  },
+  {
+    id: 'dispatch.maxDischargeKW',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.maxDischargeKW',
+    readBy: '@operato/twin-kernel EmsKernel (인버터 방전 상한)'
+  },
+  {
+    id: 'dispatch.reserveSoc',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.reserveSoc',
+    readBy: '@operato/twin-kernel EmsKernel (이 아래로는 방전하지 않는다)'
+  },
+  {
+    id: 'storage.initialSoc',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.initialSoc',
+    readBy: '@operato/twin-kernel EmsKernel (시작 충전율 — 예측·what-if 의 씨앗)'
+  },
+  {
+    id: 'generation.ratedKW',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.genRatedKW',
+    readBy: '@operato/twin-kernel EmsKernel.deriveGeneration (정격 발전)'
+  },
+  {
+    id: 'generation.dailyProfile',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.genDailyProfile',
+    readBy: '@operato/twin-kernel generationFractionAt (시각별 발전 비율)'
+  },
+  /* 요금은 커널이 읽지 않는다 — 금액은 저널을 접는 호스트가 만든다. readBy 가 그 사실을 말한다. */
+  {
+    id: 'tariff.demandChargePerKW',
+    axes: ['locations'],
+    effect: 'twin.propeffect.demandChargePerKW',
+    readBy: 'headless-twin/server/engine/kpi-query.ts (수요요금 계산)'
+  },
+  {
+    id: 'tariff.energyChargePerKWh',
+    axes: ['locations'],
+    effect: 'twin.propeffect.energyChargePerKWh',
+    readBy: 'headless-twin/server/engine/kpi-query.ts (전력량 요금 계산)'
+  },
+  /* 판정 기준 — 값이 경보의 유무를 바꾼다(가장 눈에 보이는 효과다). */
+  {
+    id: 'attention.congestionRatio',
+    axes: ['locations'],
+    effect: 'twin.propeffect.congestionRatio',
+    readBy: '@operato/twin-kernel deriveAttentions (병목 판정 기준)'
+  },
+  {
+    id: 'attention.scrapRate',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.scrapRate',
+    readBy: '@operato/twin-kernel deriveAttentions (불량 과다 판정 기준)'
+  },
+  {
+    id: 'attention.scrapMinSamples',
+    axes: ['equipment'],
+    effect: 'twin.propeffect.scrapMinSamples',
+    readBy: '@operato/twin-kernel deriveAttentions (불량률을 재기 시작할 표본 수)'
+  },
+  /*
+   * ── 공정 소요시간 (2026-08-18) ────────────────────────────────────────────
+   *
+   * 실측: 운영 중인 트윈 35개 중 **창고·야드는 공정 명세 행이 0개**였다 — 그 트윈들의 시간은 전부 커널
+   * 상수에서 왔고, 예측은 「같은 조건에서의 상대 비교」에 머물렀다(절대 시각 주장 불가). 이 선언이
+   * 그 사다리를 한 칸 올린다: 실측이 없어도 **현장이 정한 시간**으로 굴러간다.
+   *
+   * 실측(이력에서 배운 값)은 여전히 이 선언을 이긴다 — 화면이 그 사실을 함께 말한다.
+   */
+  {
+    id: 'operation.duration',
+    axes: ['operations'],
+    effect: 'twin.propeffect.operationDuration',
+    readBy: '@operato/twin-kernel FlowEngine.durationOf ← declareDurations (engine/local-declarations.ts 가 실어 보낸다)'
+  },
+  {
+    id: 'tariff.currency',
+    axes: ['locations'],
+    effect: 'twin.propeffect.currency',
+    readBy: 'headless-twin/server/engine/kpi-query.ts (금액 표기 통화)'
+  }
+]
+
+/**
+ * 이 축의 속성 효과 — `속성 id → i18n 키`.
+ *
+ * 없는 속성은 **여기 없다**(빈 값으로 채우지 않는다) — 화면이 "등록된 효과가 없다" 를 스스로 말한다.
+ */
+export function propertyEffectsOf(axis: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const e of PROPERTY_EFFECTS) if (e.axes.includes(axis)) out[e.id] = e.effect
+  return out
+}
+
+/** 등록부의 축 이름 → 선언이 겨누는 대상 이름. 대상이 아닌 축(자재 정의 등)은 여기 없다. */
+const AXIS_TO_TARGET: Record<string, string> = { locations: 'location', equipment: 'equipment', operations: 'operation' }
+
+/**
+ * 이 속성을 **어느 대상에 얹을 수 있나** — 등록부의 축이 그대로 답한다.
+ *
+ * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
+ * 지게차에 계약전력을 선언할 수 있었다. 문은 받아 주고 화면은 「넣었습니다」라고 말하는데, 그 값을 읽는
+ * 코드는 자리(수전)만 본다 — 아무 일도 일어나지 않고 그 사실이 어디에도 나오지 않았다. 효과가 어느 축의
+ * 것인지는 이미 등록부가 알고 있으므로, 그 지식을 검사에 쓴다(두 곳에 적지 않는다).
+ *
+ * 등록부에 없는 속성은 **비어 있는 목록이 아니라 `undefined`** 다: 「어디에도 못 얹는다」와 「우리가
+ * 제한을 모른다」는 다르다(후자는 받아 준다 — 속성은 열려 있다는 규약을 지킨다).
+ */
+export function declarationTargetsOf(propertyId: string): string[] | undefined {
+  const e = PROPERTY_EFFECTS.find(x => x.id === propertyId)
+  if (!e) return undefined
+  const targets = e.axes.map(a => AXIS_TO_TARGET[a]).filter((t): t is string => !!t)
+  return targets.length ? targets : undefined
+}

package/server/engine/runtime-key.ts

@@ -52,7 +52,7 @@ export function parseRuntimeKey(key: string): { domainId: string; instanceId: st
   return { domainId: key.slice(0, at), instanceId: key.slice(at + 1) }
 }
 
-/** 이 키가 이 테넌트의 것인가 — 레지스트리를 훑을 때 도메인으로 걸러낸다. */
+/** 이 키가 이 테넌트의 것인가 — 레지스트리를 조회할 때 도메인으로 걸러낸다. */
 export function isOfDomain(key: string, domainId: string): boolean {
   return !!domainId && key.startsWith(`${domainId}${RUNTIME_KEY_SEP}`)
 }

package/server/engine/spec-coverage.ts

@@ -2,9 +2,9 @@
  * 시뮬 명세 자기보고 — **"이 예측으로 무엇을 말할 수 있나" 를 예측과 함께 내보낸다.**
  *
  * 배경(operato-twin design/plans/simulation-spec.md): 공정 소요·수율이 커널 소스의 상수였다. 이제
- * 마스터가 명세를 실어 오면 커널이 그것으로 굴리고, `specCoverage()` 가 무엇을 선언값으로 무엇을
- * 기본값으로 썼는지 보고한다. 그 보고를 **예측 응답에 붙이지 않으면** 받는 쪽은 상수로 굴린 숫자와
- * 현장 명세로 굴린 숫자를 구별할 수 없다 — 똑같이 "p50 168" 로 보인다.
+ * 마스터가 명세를 실어 오면 커널이 그것으로 실행하고, `specCoverage()` 가 무엇을 선언값으로 무엇을
+ * 기본값으로 썼는지 보고한다. 그 보고를 **예측 응답에 붙이지 않으면** 받는 쪽은 상수로 계산한 숫자와
+ * 현장 명세로 계산한 숫자를 구별할 수 없다 — 똑같이 "p50 168" 로 보인다.
  *
  * 언어 중립: 여기서는 **코드와 수치만** 낸다(`qualification` + 카운트). 사람이 읽는 문장은 표현
  * 계층(클라 i18next / AI 답변)이 만든다 — attention 과 같은 규율.

package/server/engine/state-axes.ts

@@ -18,12 +18,17 @@
  * 채로 뜨는 것이 가장 나쁘다.
  */
 
-/** 상태가 들고 있는 축 — 이 목록 밖의 이름은 고를 수 없다. */
-export const STATE_AXES = ['locations', 'items', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'attentions', 'acked'] as const
+/**
+ * 상태가 들고 있는 축 — 이 목록 밖의 이름은 고를 수 없다.
+ *
+ * `energy` 는 에너지 트윈만 채운다(계량 지점·수요 구간·피크). `ALWAYS` 에 두지 않는다: 마감 구간을
+ * 하루치 들고 있어 작지 않고, 그것이 필요한 화면이 스스로 이름을 말하는 편이 맞다.
+ */
+export const STATE_AXES = ['locations', 'items', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'attentions', 'acked', 'energy'] as const
 export type StateAxis = (typeof STATE_AXES)[number]
 
 /** 축과 무관하게 늘 남는 것 — 이것이 없으면 무엇을 받았는지 알 수 없다. */
-const ALWAYS = ['revision', 'nowTime', 'simClockMs', 'corrections'] as const
+const ALWAYS = ['revision', 'nowTime', 'simClockMs', 'corrections', 'unhandled'] as const
 
 export interface PickedAxes {
   /** 고른 축만 남은 상태. `axes` 가 비었으면 원본 그대로(자르지 않는다). */

package/server/engine/structure-diff.ts

@@ -2,7 +2,7 @@
  * 구조 이력의 **차이** — "2번째에 도장 부스가 넷 늘었다" 를 말할 수 있게.
  *
  * 리비전은 그 시절 공장을 통째로 담는다(재생하려면 전체 위상이 필요하다). 그런데 사람이 보고 싶은
- * 것은 통째가 아니라 **무엇이 달라졌나** 다 — 62KB 짜리 보드 두 개를 나란히 놓고 눈으로 비교할 수는
+ * 것은 통째가 아니라 **무엇이 달라졌나** 다 — 62KB 짜리 모델 두 개를 나란히 놓고 눈으로 비교할 수는
  * 없다. 그 한 줄을 여기서 만든다.
  *
  * 순수 함수인 이유: 같은 문장을 화면과 AI 가 함께 써야 한다. 한쪽에서만 계산하면 둘이 다른 말을 한다.