@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/command-routing.test.ts

@@ -0,0 +1,61 @@
+/*
+ * ★ 커맨드 라우팅 판정 — 권위(모드) × 성격(주석/액추에이션).
+ *
+ * ── 무엇이 문제였나 ─────────────────────────────────────────────────────────
+ * 리졸버가 `inst.runtime.dispatch(...)` 를 곧바로 불렀다. 그런데 `runtime` 은 **시뮬 경로에서만**
+ * 만들어진다. 실물을 비추는 트윈(mirror)에서는 그 한 줄이 `TypeError` 로 터져 조치 채널이 통째로
+ * 닿지 않았다 — 사용자에게는 이유 있는 거절이 아니라 그냥 실패였다.
+ *
+ * ── 그냥 열면 안 되는 이유 ──────────────────────────────────────────────────
+ * 미러에서 액추에이션을 허용하면 **새 거짓말이 생긴다**: 트윈은 "보류됨" 이라 말하고 실 시스템은
+ * 모른다. 그래서 실 프로세스를 바꾸는 커맨드는 아웃바운드 어댑터가 붙기 전까지 이유를 밝혀 거절한다
+ * (`design/plans/command-routing.md` P0). 확인(ack)은 트윈 쪽 주석이라 미러에서도 통과한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { routeCommand, isActuation } from '../server/engine/command-routing.ts'
+
+const sim = { hasRuntime: true, hasKernelDispatch: true }
+const mirror = { mode: 'live', hasRuntime: false, hasKernelDispatch: true }
+
+test('시뮬 — 커맨드는 커널 런타임으로 간다(현행 경로 그대로)', () => {
+  assert.deepEqual(routeCommand(sim, true, 'order.hold'), { target: 'runtime' })
+  assert.deepEqual(routeCommand(sim, true, 'attention.ack'), { target: 'runtime' })
+})
+
+test('미러 — 확인(ack)은 관측 커널로 간다. 현실을 건드리지 않는 주석이다', () => {
+  assert.deepEqual(routeCommand(mirror, true, 'attention.ack'), { target: 'kernel' })
+})
+
+test('미러 — 실 프로세스를 바꾸는 커맨드는 이유를 밝히고 거절한다', () => {
+  for (const type of ['order.hold', 'order.resume', 'order.release', 'resource.down', 'resource.repair', 'resource.add']) {
+    const r = routeCommand(mirror, true, type)
+    assert.equal(r.target, 'reject', `${type} 은 미러에서 통과하면 안 된다`)
+    if (r.target !== 'reject') return
+    assert.equal(r.errorCode, 'actuation-not-wired')
+    assert.equal(r.errorParams?.type, type, '어느 커맨드였는지 함께 알려야 한다')
+  }
+})
+
+test('없는 인스턴스와 다른 도메인은 같은 사유로 거절한다 — 있음/없음이 구별되면 그것이 정보다', () => {
+  assert.deepEqual(routeCommand(undefined, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
+  assert.deepEqual(routeCommand(sim, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
+})
+
+test('런타임이 없는 시뮬 — 예외를 던지지 않고 이유를 알린다', () => {
+  assert.deepEqual(routeCommand({ hasRuntime: false, hasKernelDispatch: true }, true, 'order.hold'), { target: 'reject', errorCode: 'no-runtime' })
+})
+
+test('커널이 커맨드를 못 받는 미러 — 확인도 이유를 말하고 멈춘다', () => {
+  assert.deepEqual(routeCommand({ mode: 'live', hasRuntime: false, hasKernelDispatch: false }, true, 'attention.ack'), { target: 'reject', errorCode: 'no-runtime' })
+})
+
+test('빈 커맨드 종류는 거절한다 — 무엇을 하라는지 모르는 것을 보내지 않는다', () => {
+  assert.deepEqual(routeCommand(sim, true, ''), { target: 'reject', errorCode: 'unknown-command' })
+})
+
+test('성격 판정 — 확인만 주석이고 나머지는 액추에이션이다', () => {
+  assert.equal(isActuation('attention.ack'), false)
+  for (const t of ['order.hold', 'resource.add', 'order.release']) assert.equal(isActuation(t), true, t)
+})

package/test/declaration-reaches-model.test.ts

@@ -0,0 +1,178 @@
+/*
+ * 선언 적합성(경계 편) — **원본이 말한 사실은 모델까지 간다.**
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 커널 쪽에는 같은 이름의 하네스가 있다(kernel/test/declaration-in-state: 선언 ⊆ 상태). 그런데 사실이
+ * 새던 자리는 그 앞에도 있었다: **레퍼런스 마스터 → 커널 모델** 이라는 문 하나(`masterToTwin`).
+ *
+ * 여기서 새면 아무도 모른다. 원본은 말했고, 화면은 조용히 id 를 보인다. 실제로 그렇게 잃었다 —
+ * 자리의 이름(화면이 `cut-station` 을 찍었다), 사람의 이름, GS1 참조, 자원 속성, 시험 명세 참조,
+ * 사람·설비의 시험 결과. 하루 사이에 여섯 번이고, 전부 **한 줄에서 필드 하나가 빠진** 것이었다.
+ *
+ * 타입 검사는 못 잡는다: 필드가 거의 다 선택(optional)이라 **안 옮기는 것이 합법**이다.
+ *
+ * ── 무엇을 검사하나 ─────────────────────────────────────────────────────────
+ * `RefLocation`·`RefEquipment`·`RefPerson`·`RefAsset` 의 **모든 필드**가 셋 중 하나여야 한다:
+ *
+ *   1. 같은 이름으로 모델에 있다(대부분).
+ *   2. `RENAMED` 에 적힌 다른 이름으로 모델에 있다(`homeLocationId → homeLocation`).
+ *   3. `ELSEWHERE` 에 **다른 길이 무엇인지 적혀** 있다(좌표는 `layout` 으로, 역할은 분기에 쓰인다).
+ *
+ * 셋 중 어느 것도 아니면 실패한다 — 새 필드를 추가한 사람이 그때 분류해야 한다. 분류를 강제하는 것이
+ * 이 검사의 전부다: 잊는 것이 기본값이면 잊는다.
+ *
+ * 필드 목록은 **소스에서 읽는다**(손으로 적지 않는다). 손으로 적으면 새 필드가 조용히 빠지고, 그것이
+ * 바로 이 검사가 막으려는 실패다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+import { masterToTwin } from '../server/service/reference/reference-master.ts'
+
+/*
+ * 주석을 먼저 걷어낸다 — **주석 속 예시가 필드로 세어졌다.**
+ * 문서에 `effectivity: 'not-yet' | 'expired'` 라고 적어 둔 한 줄 때문에 없는 필드가 검사 대상에 들어왔다.
+ * 검사가 없는 것을 요구하면 그 검사는 유지되지 않는다(사람이 예외를 늘려 입을 막는다).
+ */
+const SOURCE = readFileSync(new URL('../server/service/reference/reference-master.ts', import.meta.url), 'utf8')
+  .replace(/\/\*[\s\S]*?\*\//g, '')
+  .replace(/\/\/[^\n]*/g, '')
+
+/** `export interface X { … }` 의 깊이 1 필드 이름 — 중첩 객체의 안쪽은 세지 않는다. */
+function fieldsOf(name: string): string[] {
+  const start = SOURCE.indexOf(`export interface ${name}`)
+  assert.ok(start >= 0, `선언 인터페이스를 못 찾았다: ${name} — 모양이 바뀌면 이 하네스도 따라가야 한다`)
+  const body = SOURCE.slice(SOURCE.indexOf('{', start))
+  const block = body.slice(0, body.indexOf('\n}') + 2)
+  const out: string[] = []
+  let depth = 0
+  let token = ''
+  for (const ch of block) {
+    if (ch === '{') { depth++; token = ''; continue }
+    if (ch === '}') { depth--; token = ''; continue }
+    if (depth === 1 && /[A-Za-z0-9_?]/.test(ch)) { token += ch; continue }
+    if (depth === 1 && ch === ':') { if (token) out.push(token.replace('?', '')); token = ''; continue }
+    token = ''
+  }
+  return out
+}
+
+/** 경계에서 이름이 바뀌는 필드 — 바뀌는 이유는 커널 어휘를 따르기 때문이다(호스트 어휘를 밀어넣지 않는다). */
+const RENAMED: Record<string, string> = { homeLocationId: 'homeLocation' }
+
+/**
+ * **다른 길로 가는 사실** — 모델의 그 자원 줄에는 없지만 잃지도 않는다. 길을 여기 적는다.
+ * 적지 않고 넘기면 "원래 안 가는 것" 과 "새는 것" 이 같아 보인다.
+ */
+const ELSEWHERE: Record<string, string> = {
+  role: '자리인가 구역인가를 가르는 입력 — 모델의 locations 와 공간의 areas 로 갈라진다(값 자체는 나를 필요가 없다).',
+  footprint: '좌표는 `model.layout`(중심점)과 구역 기하로 간다 — 자리 줄에 실리는 값이 아니다.'
+}
+
+/** 모든 필드에 값을 실은 원본 — 값을 모르는 필드가 나오면 이 하네스는 실패한다(조용히 건너뛰지 않는다). */
+const VALUE: Record<string, unknown> = {
+  id: '__ID__',
+  type: 'cut-station',
+  kind: 'welder',
+  name: '절단 스테이션',
+  description: '강판을 자르는 자리',
+  role: 'location',
+  parentId: 'zone-a',
+  /* 전기 상류 — 공간 부모(`parentId`)와 다른 관계다. 값이 모델까지 가는지 이 하네스가 지킨다. */
+  upstreamId: 'incoming-1',
+  capacity: 40,
+  parallelism: 2,
+  level: 'WorkCenter',
+  footprint: { x: 1, y: 2, w: 3, h: 4 },
+  gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
+  homeLocationId: 'cut-station',
+  mtbfMs: 600000,
+  mttrMs: 60000,
+  window: { startHour: 6, endHour: 22 },
+  workCalendar: [{ id: 'day', entryType: 'production', startTime: '06:00', endTime: '22:00' }],
+  properties: [{ id: 'speed', value: '1.2', uom: 'MTS' }],
+  testSpecificationIds: ['weld-cert'],
+  testResults: [{ specId: 'weld-cert', result: 'pass', expiresAt: '2099-01-01T00:00:00.000Z' }],
+  effectiveStart: '2020-01-01T00:00:00.000Z',
+  effectiveEnd: '2099-01-01T00:00:00.000Z',
+  personnelClassIds: ['welder-op'],
+  assetClassIds: ['euro-pallet']
+}
+
+interface Case {
+  /** 선언 인터페이스 이름 */
+  iface: string
+  /** 모델의 배열 이름 */
+  bucket: 'locations' | 'equipment' | 'persons' | 'assets'
+  id: string
+}
+
+const CASES: Case[] = [
+  { iface: 'RefLocation', bucket: 'locations', id: 'cut-station' },
+  { iface: 'RefEquipment', bucket: 'equipment', id: 'cutter-1' },
+  { iface: 'RefPerson', bucket: 'persons', id: 'cutter-op-1' },
+  { iface: 'RefAsset', bucket: 'assets', id: 'pallet-1' }
+]
+
+/** 그 인터페이스의 모든 필드에 값을 실은 항목. */
+function build(c: Case): any {
+  const o: any = {}
+  for (const f of fieldsOf(c.iface)) {
+    assert.ok(
+      f in VALUE,
+      `픽스처가 "${c.iface}.${f}" 에 실을 값을 모른다 — VALUE 에 하나 적어라.\n` +
+        '조용히 건너뛰면 그 필드는 아무도 안 보는 필드가 되고, 그것이 이 하네스가 막으려는 실패다.'
+    )
+    o[f] = f === 'id' ? c.id : VALUE[f]
+  }
+  return o
+}
+
+function master(): any {
+  return {
+    source: 'decl-conformance',
+    system: 'mes' as const,
+    siteName: '선언 적합성 공장',
+    space: { spaceId: 'decl-site', width: 100, depth: 60, unit: 'm' },
+    locations: [build(CASES[0])],
+    equipment: [build(CASES[1])],
+    persons: [build(CASES[2])],
+    assets: [build(CASES[3])]
+  }
+}
+
+test('검사할 필드가 비어 있지 않다 — 비면 이 하네스는 아무것도 지키지 않는다', () => {
+  for (const c of CASES) assert.ok(fieldsOf(c.iface).length > 2, `${c.iface}: 필드를 못 읽었다(파서가 낡았다)`)
+})
+
+for (const c of CASES) {
+  test(`${c.iface} 의 사실이 하나도 잃지 않고 모델까지 간다`, () => {
+    const src = build(c)
+    const { model } = masterToTwin(master())
+    const bucket = (model as any)[c.bucket]
+    assert.ok(Array.isArray(bucket), `모델에 ${c.bucket} 이 없다`)
+    const got = bucket.find((x: any) => x?.id === c.id)
+    assert.ok(got, `선언한 ${c.iface} "${c.id}" 이 모델에 없다 — 사실 하나가 아니라 개체가 사라졌다`)
+
+    const lost: string[] = []
+    const mangled: string[] = []
+    for (const f of Object.keys(src)) {
+      if (f in ELSEWHERE) continue
+      const key = RENAMED[f] ?? f
+      if (got[key] === undefined) { lost.push(f); continue }
+      try {
+        assert.deepEqual(got[key], src[f])
+      } catch {
+        mangled.push(`${f}→${key}`)
+      }
+    }
+    assert.deepEqual(
+      { lost, mangled },
+      { lost: [], mangled: [] },
+      `${c.iface}: 잃은 사실=[${lost}] · 옮기다 값이 바뀐 사실=[${mangled}]\n` +
+        '원본이 말한 것을 문에서 버리면 아무도 모른다 — 화면은 조용히 id 를 보인다.\n' +
+        '일부러 다른 길로 보내는 것이면 ELSEWHERE 에 그 길을 적어라(이름만 바뀌는 것은 RENAMED).'
+    )
+  })
+}

package/test/discovery-result.test.ts

@@ -0,0 +1,75 @@
+/*
+ * 사이트 발견 결과 — **"못 찾았다" 를 "없다" 로 말하지 않게.**
+ *
+ * 실 시스템을 연결해 트윈을 만드는 경로에서, 발견이 실패하면 화면이 "사이트를 찾지 못했습니다" 라고만
+ * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장으로 접혀 있었다 — 자격이
+ * 틀렸는지 주소가 틀렸는지 알 수 없었다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  discovered, failed, detailOf,
+  referenceNotFound, adapterUnknown, discoveryFailed, discoveryTimedOut
+} from '../server/service/reference/discovery-result.ts'
+
+test('사이트가 없는 것은 실패가 아니다 — 사유 없는 빈 목록이 "없다" 를 뜻한다', () => {
+  /* 권한이 좁거나 아직 등록되지 않아 공장이 하나도 없는 시스템은 있을 수 있다. 그것은 사실이므로
+     실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다. */
+  const r = discovered([])
+  assert.deepEqual(r, { sites: [] })
+  assert.equal(r.error, undefined, '사유가 없다 = 성공')
+})
+
+test('찾은 것을 그대로 돌려주되 입력을 붙들지 않는다', () => {
+  const src = [{ siteId: 'PL1' }, { siteId: 'PL2' }]
+  const r = discovered(src)
+  assert.deepEqual(r.sites, src)
+  src.push({ siteId: 'PL3' })
+  assert.equal(r.sites.length, 2, '나중에 바뀐 원본이 결과를 바꾸지 않는다')
+})
+
+test('없는 목록·null 도 견딘다', () => {
+  assert.deepEqual(discovered(null), { sites: [] })
+  assert.deepEqual(discovered(undefined), { sites: [] })
+})
+
+test('실패는 사유와 함께, 사이트는 비워서 — 반쪽 목록을 성공처럼 보이지 않게', () => {
+  const r = failed(referenceNotFound('sap-ewm-1710'))
+  assert.deepEqual(r.sites, [])
+  assert.equal(r.error?.code, 'reference-not-found')
+  assert.equal(r.error?.params?.source, 'sap-ewm-1710')
+  assert.match(r.error!.message, /not registered/, '영어 canonical 문장이 로그·폴백으로 남는다')
+})
+
+test('네 가지 사유가 서로 구별된다 — 이것이 이 작업의 요점이다', () => {
+  const codes = [
+    referenceNotFound('s').code,
+    adapterUnknown('sap-ewm', 's').code,
+    discoveryFailed('s', '401 Unauthorized').code,
+    discoveryTimedOut('s', 15).code
+  ]
+  assert.deepEqual(codes, ['reference-not-found', 'adapter-unknown', 'discovery-failed', 'discovery-timeout'])
+  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 접히지 않는다')
+})
+
+test('원 시스템이 준 사유를 감추지 않는다 — 사용자가 관리자에게 물어볼 수 있게', () => {
+  const e = discoveryFailed('sap-ewm-1710', '401 Unauthorized')
+  assert.equal(e.params?.detail, '401 Unauthorized')
+  assert.match(e.message, /401 Unauthorized/)
+})
+
+test('타임아웃은 초 단위로 알린다 — 얼마를 기다렸는지 알 수 있게', () => {
+  const e = discoveryTimedOut('s', 15)
+  assert.equal(e.params?.seconds, 15)
+  assert.match(e.message, /15s/)
+})
+
+test('어댑터가 던진 것에서 사유를 뽑는다 — 형태를 가정하지 않는다', () => {
+  assert.equal(detailOf(new Error('ECONNREFUSED')), 'ECONNREFUSED')
+  assert.equal(detailOf('404 Not Found'), '404 Not Found')
+  /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */
+  for (const weird of [undefined, null, {}, 0, new Error('')]) {
+    assert.match(detailOf(weird), /without a message/, `이상한 입력: ${JSON.stringify(weird)}`)
+  }
+})

package/test/energy-topology.test.ts

@@ -0,0 +1,113 @@
+/*
+ * 전력 계통도 — **선언된 것만 그린다.**
+ *
+ * 이 시험이 지키는 것: 계층·소속이 그림에 그대로 남고, 모르는 것(자리 없는 설비·계량 없는 구간·결선
+ * 미상 부하)이 **각자 자기 칸으로** 나온다. 그림에서 사라지면 사용자는 자기 현장이 다 그려졌다고 믿는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { buildEnergyTopology } from '../server/engine/energy-topology.ts'
+
+const plant = () => ({
+  locations: [
+    { id: 'a-plant', type: 'plant', name: '공장' }, // 공간 부모 — 계통 축이 아니다
+    { id: 'incoming-1', type: 'incoming', name: '수전', parentId: 'a-plant' },
+    { id: 'feeder-press', type: 'feeder', name: 'Press line', parentId: 'incoming-1' },
+    { id: 'feeder-weld', type: 'feeder', name: 'Weld line', parentId: 'incoming-1' },
+    { id: 'zone-1', type: 'submeter-zone', name: '도장 구역', parentId: 'feeder-weld' }
+  ],
+  equipment: [
+    { id: 'meter-incoming', kind: 'meter', homeLocation: 'incoming-1' },
+    { id: 'meter-press', kind: 'meter', homeLocation: 'feeder-press' },
+    { id: 'breaker-1', kind: 'breaker', homeLocation: 'feeder-press' },
+    { id: 'ess-1', kind: 'battery', homeLocation: 'incoming-1' },
+    { id: 'press-1', kind: 'curtailable-load', homeLocation: 'feeder-press' },
+    { id: 'load-hvac', kind: 'curtailable-load', homeLocation: 'incoming-1' }, // 결선 미상
+    { id: 'ghost', kind: 'curtailable-load', homeLocation: 'nowhere' }
+  ]
+})
+
+test('계통 계층만 잇는다 — 공간 부모(공장)는 이 축이 아니다', () => {
+  const t = buildEnergyTopology(plant())
+  assert.equal(t.roots.length, 1)
+  assert.equal(t.roots[0].id, 'incoming-1', '수전이 뿌리다(공장 아래에 있어도)')
+  assert.deepEqual(t.roots[0].children.map(c => c.id), ['feeder-press', 'feeder-weld'])
+  assert.deepEqual(t.roots[0].children[1].children.map(c => c.id), ['zone-1'], '구역은 그 분기 아래')
+})
+
+test('계량기는 「이 구간을 잰다」로, 계통 설비는 따로, 부하는 부하로 — 섞지 않는다', () => {
+  const t = buildEnergyTopology(plant())
+  const press = t.roots[0].children[0]
+  assert.deepEqual(press.meters, ['meter-press'])
+  assert.deepEqual(press.gear.map(g => g.kind), ['breaker'])
+  assert.deepEqual(press.loads.map(l => l.id), ['press-1'])
+  assert.deepEqual(t.roots[0].gear.map(g => g.kind), ['battery'], '축전지는 부하가 아니다')
+})
+
+test('자리를 모르는 설비를 그림에서 지우지 않는다', () => {
+  const t = buildEnergyTopology(plant())
+  assert.deepEqual(t.unplaced.map(u => u.id), ['ghost'])
+})
+
+test('계량 없는 구간과 결선 미상 부하를 센다 — 「어디에 더 달아야 하나」의 답', () => {
+  const t = buildEnergyTopology(plant())
+  assert.deepEqual(t.unmetered.sort(), ['feeder-weld', 'zone-1'])
+  assert.equal(t.loadsOnIncoming, 1, '수전에 직결된 부하 — 어느 분기가 주는지 모르는 것들')
+})
+
+test('폴드가 낸 몫을 노드에 얹는다 — 값을 다시 계산하지 않는다', () => {
+  const t = buildEnergyTopology(plant(), {
+    byFeeder: [
+      { key: 'feeder-press', kWh: 124, basis: 'measured' },
+      { key: 'feeder-weld', kWh: 103, basis: 'apportioned' }
+    ]
+  })
+  const [press, weld] = t.roots[0].children
+  assert.equal(press.kWh, 124)
+  assert.equal(press.basis, 'measured')
+  assert.equal(weld.basis, 'apportioned')
+  assert.equal(t.roots[0].kWh, undefined, '뿌리의 몫은 분기 표에 없다 — 지어내지 않는다')
+})
+
+test('에너지 자리가 없으면 그림을 만들지 않는다 — 빈 그림은 고장으로 읽힌다', () => {
+  const t = buildEnergyTopology({ locations: [{ id: 'dock-1', type: 'dock' }], equipment: [] })
+  assert.equal(t.roots.length, 0)
+})
+
+/*
+ * ── 발전·저장의 **지금 값**을 기호 옆에 (2026-08-18) ─────────────────────────
+ * 원천이 태양광 발전량과 축전지 충전율·방전을 보내 주는데도 그림에는 기호만 있었다 — 화면이 아는 사실을
+ * 그림이 감추는 것이다. 다만 지금 값은 구간 값과 성격이 다르므로 시각을 함께 나른다(계측이 끊기면
+ * 멈춘 값을 지금 값으로 그리게 된다).
+ */
+const withSources = () => ({
+  locations: [{ id: 'incoming-1', type: 'incoming', name: '수전' }],
+  equipment: [
+    { id: 'meter-incoming', kind: 'meter', homeLocation: 'incoming-1' },
+    { id: 'pv-roof', kind: 'pv-array', homeLocation: 'incoming-1' },
+    { id: 'ess-1', kind: 'battery', homeLocation: 'incoming-1' }
+  ]
+})
+
+test('종류가 아는 필드만 옮긴다 — 태양광에 충전율을 붙이지 않는다', () => {
+  const t = buildEnergyTopology(withSources(), undefined, [
+    { id: 'pv-roof', kind: 'pv-array', generatedKW: 16, exportKW: 0, soc: 99, measuredAt: '2026-08-18T09:00:00.000Z' },
+    { id: 'ess-1', kind: 'battery', soc: 48, dischargeKW: 200, chargeKW: 0, generatedKW: 7, measuredAt: '2026-08-18T09:00:00.000Z' }
+  ])
+  const gear = new Map(t.roots[0].gear.map(g => [g.id, g]))
+  assert.deepEqual(gear.get('pv-roof')?.live, { generatedKW: 16, exportKW: 0, measuredAt: '2026-08-18T09:00:00.000Z' })
+  assert.deepEqual(gear.get('ess-1')?.live, { soc: 48, dischargeKW: 200, chargeKW: 0, measuredAt: '2026-08-18T09:00:00.000Z' })
+})
+
+test('상태를 주지 않으면 값을 만들지 않는다 — 구조만 그린다', () => {
+  const t = buildEnergyTopology(withSources())
+  for (const g of t.roots[0].gear) assert.equal(g.live, undefined)
+})
+
+test('보내지 않은 필드는 없다 — 0 으로 채우지 않는다', () => {
+  const t = buildEnergyTopology(withSources(), undefined, [{ id: 'ess-1', kind: 'battery', soc: 30 }])
+  const ess = t.roots[0].gear.find(g => g.id === 'ess-1')
+  assert.deepEqual(ess?.live, { soc: 30 })
+  assert.equal(ess?.live?.dischargeKW, undefined, '방전을 보내지 않았으면 모르는 것이다')
+})