@things-factory/headless-twin 10.0.9 → 10.0.10

package/test/canonical-ingest-vocabularies.test.ts

@@ -0,0 +1,118 @@
+/*
+ * 정규 인제스트 — **어휘가 둘이다**(물류 EPCIS · 에너지 계측).
+ *
+ * ── 왜 있나 (2026-08-14, EMS 5단계 준비) ────────────────────────────────────
+ * 이 seam 은 무조건 `type: 'ObjectEvent'` 를 만들었다. 그래서 커넥터가 계측을 이 길로 보내면 둘 중
+ * 하나가 됐다: `epc` 가 없어 거부되거나(그나마 나은 쪽), **엉뚱한 물품 관측**으로 읽혀 재고가 흔들린다.
+ * 오류 없이 틀리는 쪽이 더 나쁘다.
+ *
+ * 이 시험이 지키는 것 둘:
+ *  ① 한 배치에 두 어휘가 섞여 와도 각자의 봉투가 된다(커넥터가 나눠 보낼 의무를 지지 않는다).
+ *  ② **거부분이 사라지지 않는다** — 예전에는 호출부가 `rejected` 를 받지도 않았다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const NOW = '2026-08-14T09:00:00.000Z'
+
+const epcisRecord = {
+  epc: 'urn:epc:id:sgtin:0614141.107346.2017',
+  action: 'OBSERVE',
+  bizStep: 'urn:epcglobal:cbv:bizstep:storing',
+  disposition: 'urn:epcglobal:cbv:disp:in_progress',
+  readPoint: 'rack-1'
+}
+const energyRecord = { meterId: 'meter-incoming', kW: 1200, at: '2026-08-14T09:00:30.000Z' }
+
+test('한 배치에 두 어휘가 섞여도 각자의 봉투가 된다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords([epcisRecord, energyRecord] as any, 't', NOW)
+  assert.equal(rejected.length, 0, `거부 없음이어야 한다: ${JSON.stringify(rejected)}`)
+  const types = accepted.map(e => e.eventType).sort()
+  assert.deepEqual(types, ['energy.measured', 'epcis.ObjectEvent'])
+})
+
+test('계측을 물품 관측으로 만들지 않는다 — 이것이 이 갈림의 이유다', () => {
+  const { accepted } = ingestCanonicalRecords([energyRecord] as any, 't', NOW)
+  assert.equal(accepted.length, 1)
+  assert.equal(accepted[0].eventType, 'energy.measured')
+  /* EPCIS 페이로드의 흔적이 없어야 한다 — 있으면 미러가 물품을 지어낸다. */
+  assert.equal((accepted[0].data as any).epcList, undefined)
+  assert.equal((accepted[0].data as any).type, undefined)
+})
+
+test('거부분이 사라지지 않는다 — 커넥터 매핑이 틀린 것을 알 수 있어야 한다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      energyRecord,
+      { meterId: 'm-2', kW: 10, at: '어제' }, // 시각 형식 오류
+      { epc: '', action: 'OBSERVE', bizStep: 'x' } // EPCIS 쪽 결손
+    ] as any,
+    't',
+    NOW
+  )
+  assert.equal(accepted.length, 1, '유효한 것은 통과한다')
+  assert.equal(rejected.length, 2)
+  for (const r of rejected) assert.ok(r.errors.length > 0, '이유 없는 거부가 없다')
+})
+
+test('빈 입력에서 두 경로 모두 조용하다 — 없는 것을 만들지 않는다', () => {
+  const empty = ingestCanonicalRecords([], 't', NOW)
+  assert.deepEqual(empty, { accepted: [], rejected: [] })
+  const nothing = ingestCanonicalRecords(null, 't', NOW)
+  assert.deepEqual(nothing, { accepted: [], rejected: [] })
+})
+
+test('시각이 없는 계측은 호출자의 기준 시각을 쓴다 — 도착 시각이 근거다', () => {
+  const { accepted } = ingestCanonicalRecords([{ meterId: 'm-1', kW: 5 }] as any, 't', NOW)
+  assert.equal(accepted[0].eventTime, NOW)
+})
+
+/*
+ * ── 세 번째 어휘: 설비 에너지 상태 (2026-08-15) ─────────────────────────────
+ * 능력 계약은 태양광·축전지·감축 부하·차단기의 상태 필드를 선언해 두었는데 받는 길이 없었다.
+ * 계량과 갈라 두는 이유는 커널에 적혀 있다 — 계량은 구간에 누적되고, 이것들은 그 설비의 지금이다.
+ */
+test('설비 에너지 상태는 EPCIS 도 계량도 아닌 자기 어휘로 들어온다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [
+      { equipmentId: 'pv-1', at: '2026-08-15T09:00:00.000Z', generatedKW: 210 },
+      { meterId: 'm-1', kW: 800, at: '2026-08-15T09:00:00.000Z' },
+      { epc: 'urn:epc:id:sgtin:1.2.3', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing' }
+    ] as any,
+    'tenant-1',
+    '2026-08-15T09:00:00.000Z'
+  )
+  assert.equal(rejected.length, 0, JSON.stringify(rejected))
+  const types = accepted.map(a => a.eventType).sort()
+  assert.deepEqual(types, ['energy.equipment', 'energy.measured', 'epcis.ObjectEvent'].sort(), '세 어휘가 각자 봉투로')
+})
+
+test('바꿀 상태가 없는 보고는 거부한다 — 이유와 함께', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ equipmentId: 'pv-1', at: '2026-08-15T09:00:00.000Z' }] as any,
+    'tenant-1',
+    '2026-08-15T09:00:00.000Z'
+  )
+  assert.equal(accepted.length, 0)
+  assert.match(rejected[0].errors.join(' '), /바꿀 상태/)
+})
+
+test('충전율이 백분율 범위를 벗어나면 거부한다 — 단위를 잘못 맞춘 커넥터를 통과시키지 않는다', () => {
+  const { rejected } = ingestCanonicalRecords(
+    [{ equipmentId: 'ess-1', at: '2026-08-15T09:00:00.000Z', soc: 380 }] as any,
+    'tenant-1',
+    '2026-08-15T09:00:00.000Z'
+  )
+  assert.equal(rejected.length, 1)
+  assert.match(rejected[0].errors.join(' '), /soc/)
+})
+
+test('개폐 위치는 표준의 네 값만 받는다 — 과도·불량을 열림/닫힘으로 반올림하지 않는다', () => {
+  const ok = ingestCanonicalRecords([{ equipmentId: 'cb-1', at: '2026-08-15T09:00:00.000Z', position: 'intermediate' }] as any, 't', '2026-08-15T09:00:00.000Z')
+  assert.equal(ok.accepted.length, 1)
+  const bad = ingestCanonicalRecords([{ equipmentId: 'cb-1', at: '2026-08-15T09:00:00.000Z', position: 'ON' }] as any, 't', '2026-08-15T09:00:00.000Z')
+  assert.equal(bad.rejected.length, 1)
+  assert.match(bad.rejected[0].errors.join(' '), /position/)
+})

package/test/capability-mapping.test.ts

@@ -9,7 +9,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { DOMAIN_CATALOG, CAPABILITIES, CAPABILITY_KEYS, capabilitiesForType, stateFieldsOf } from '@operato/twin-kernel'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const SYSTEMS = ['wms', 'yms', 'mes'] as const
 

package/test/command-routing.test.ts

@@ -43,7 +43,7 @@ test('없는 인스턴스와 다른 도메인은 같은 사유로 거절한다
   assert.deepEqual(routeCommand(sim, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
 })
 
-test('런타임이 없는 시뮬 — 터뜨리지 않고 이유를 말한다', () => {
+test('런타임이 없는 시뮬 — 예외를 던지지 않고 이유를 알린다', () => {
   assert.deepEqual(routeCommand({ hasRuntime: false, hasKernelDispatch: true }, true, 'order.hold'), { target: 'reject', errorCode: 'no-runtime' })
 })
 

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

@@ -59,7 +59,7 @@ test('원 시스템이 준 사유를 감추지 않는다 — 사용자가 관리
   assert.match(e.message, /401 Unauthorized/)
 })
 
-test('타임아웃은 초 단위로 말한다 — 얼마를 기다렸는지 알 수 있게', () => {
+test('타임아웃은 초 단위로 알린다 — 얼마를 기다렸는지 알 수 있게', () => {
   const e = discoveryTimedOut('s', 15)
   assert.equal(e.params?.seconds, 15)
   assert.match(e.message, /15s/)

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, '방전을 보내지 않았으면 모르는 것이다')
+})

package/test/entity-delta.test.ts

@@ -11,7 +11,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, itemsTag, ordersTag, personsTag, tasksTag } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, itemsTag, ordersTag, personsTag, tasksTag, energyTag } from '../shared/entity-delta.ts'
 
 const byTag = (arr: any[], tag: string) => arr.find(x => x.tag === tag)
 
@@ -180,3 +180,173 @@ test('사람 집약 태그가 항상 나간다 — 선언하지 않은 트윈은
   const withTwo = buildEntityDeltas({ persons: [{ id: 'w1' }, { id: 'w2' }] }, 't1')
   assert.equal(withTwo.find(d => d.tag === personsTag('t1'))!.data.persons.length, 2)
 })
+
+/*
+ * ── 에너지 (EMS 6단계) ──────────────────────────────────────────────────────
+ *
+ * 계측은 `state.energy` 에 산다 — 자원 축이 아니다. 이 매핑이 없으면 보드에 놓은 계량기가 값을
+ * 받지 못하고 **영원히 빈 모습**이 된다(컴포넌트는 있는데 데이터가 없는, 눈에 안 보이는 결함).
+ */
+test('계량 지점의 마지막 관측이 그 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [
+          { id: 'meter-incoming', kW: 1200.5, kWh: 98_000, powerFactor: 0.95, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 3 },
+          { id: 'meter-quiet', samplesInWindow: 0 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+  const m = deltas.find(d => d.tag === 'meter-incoming')!
+  assert.equal(m.data.entity, 'meter')
+  assert.equal(m.data.kW, 1200.5)
+  assert.equal(m.data.measuredAt, '2026-08-14T09:01:00.000Z', '시각을 함께 낸다 — 화면이 계측 끊김을 스스로 안다')
+
+  /* 값이 없는 지점: 키를 넣지 않는다(0 으로 만들면 「전기를 안 썼다」가 된다). */
+  const q = deltas.find(d => d.tag === 'meter-quiet')!
+  assert.equal('kW' in q.data, false)
+  assert.equal(q.data.samplesInWindow, 0, '받은 표본 수는 사실이다')
+})
+
+test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의 사실이 아니다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [],
+        contractKW: 4000,
+        open: { startMs: 1, endMs: 2, samples: 1, maxKW: 4200 },
+        peakSince: { kW: 4200, windowStartMs: 1 },
+        closed: Array.from({ length: 20 }, (_, i) => ({ startMs: i, endMs: i + 1, samples: 1, maxKW: 100 + i })),
+        closedTotal: 137
+      }
+    },
+    'ems-1'
+  )
+  const agg = deltas.find(d => d.tag === energyTag('ems-1'))!
+  assert.ok(agg, '집약 태그가 있어야 한다')
+  assert.equal(agg.data.contractKW, 4000)
+  assert.equal(agg.data.peakSince.kW, 4200)
+  /* 하루치를 매 방송에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
+  assert.equal(agg.data.recent.length, 8)
+  assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
+})
+
+test('에너지가 없는 트윈은 에너지 태그를 내지 않는다 — 없는 것을 만들지 않는다', () => {
+  const deltas = buildEntityDeltas({ locations: [], equipment: [] }, 'wms-1')
+  assert.equal(deltas.some(d => d.tag === energyTag('wms-1')), false)
+  assert.equal(deltas.some(d => d.data?.entity === 'meter'), false)
+})
+
+test('자리에도 에너지가 실린다 — 능력이 「잰다」고 말하는데 값이 없던 자리', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [
+        { id: 'incoming-1', type: 'incoming' },
+        { id: 'feeder-a', type: 'feeder' },
+        { id: 'feeder-b', type: 'feeder' }
+      ],
+      equipment: [
+        { id: 'm-main', kind: 'meter', homeLocation: 'incoming-1' },
+        { id: 'm-a1', kind: 'meter', homeLocation: 'feeder-a' },
+        { id: 'm-a2', kind: 'meter', homeLocation: 'feeder-a' }
+      ],
+      energy: {
+        points: [
+          { id: 'm-main', kW: 3800, kWh: 1000, atMs: Date.parse('2026-08-14T09:00:00.000Z'), samplesInWindow: 3 },
+          { id: 'm-a1', kW: 1000, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 2 },
+          { id: 'm-a2', kW: 600, atMs: Date.parse('2026-08-14T09:02:00.000Z'), samplesInWindow: 1 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+
+  const incoming = deltas.find(d => d.tag === 'incoming-1')!.data
+  assert.equal(incoming.entity, 'location', '자리 payload 를 덮지 않고 합친다')
+  assert.equal(incoming.kW, 3800)
+  assert.deepEqual(incoming.meters, ['m-main'], '어느 계량기에서 온 수인지 되짚을 수 있어야 한다')
+
+  /* 자리에 계량기가 둘이면 그 자리의 수는 둘의 합이고, 나이는 **가장 최근**이다. */
+  const a = deltas.find(d => d.tag === 'feeder-a')!.data
+  assert.equal(a.kW, 1600)
+  assert.equal(a.samplesInWindow, 3)
+  assert.equal(a.measuredAt, '2026-08-14T09:02:00.000Z')
+  assert.deepEqual(a.meters, ['m-a1', 'm-a2'])
+
+  /* 계량기가 없는 자리는 예전 그대로 — 에너지 키를 만들지 않는다(0 은 「안 썼다」가 된다). */
+  const b = deltas.find(d => d.tag === 'feeder-b')!.data
+  assert.equal('kW' in b, false)
+  assert.equal('meters' in b, false)
+})
+
+test('자리를 모르는 계량기는 자리에 실리지 않는다 — 설비 태그로만 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [],
+      energy: { points: [{ id: 'm-orphan', kW: 500, samplesInWindow: 1 }], closed: [], closedTotal: 0 }
+    },
+    'ems-1'
+  )
+  assert.equal('kW' in deltas.find(d => d.tag === 'incoming-1')!.data, false)
+  assert.equal(deltas.find(d => d.tag === 'm-orphan')!.data.kW, 500, '설비 태그로는 나간다')
+})
+
+/*
+ * ── 능력 넷의 값이 컴포넌트까지 간다 (2026-08-15) ───────────────────────────
+ * 보드에 놓인 컴포넌트는 `data(tag)` 로만 값을 받는다. 커널이 값을 들고 있어도 이 페이로드에 실리지
+ * 않으면 화면은 영원히 「—」다 — 실제로 그 부류를 두 번 겪었다(스냅샷 투영이 필드를 빠뜨렸고,
+ * 값의 시각을 버렸다).
+ *
+ * 그래서 **설비 태그의 payload** 를 직접 못 박는다: 값과 그 값의 나이가 함께 실려야 한다.
+ */
+test('발전·저장·감축·개폐 값과 그 나이가 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [
+        { id: 'pv-1', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle', generatedKW: 210, exportKW: 40, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'ess-1', kind: 'battery', homeLocation: 'incoming-1', status: 'idle', soc: 62, chargeKW: 0, dischargeKW: 85, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'load-1', kind: 'curtailable-load', homeLocation: 'incoming-1', status: 'busy', curtailable: true, minKW: 30, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'cb-1', kind: 'breaker', homeLocation: 'incoming-1', status: 'idle', position: 'closed', measuredAt: '2026-08-15T09:00:00.000Z' }
+      ]
+    },
+    'ems-1'
+  )
+  const by = Object.fromEntries(deltas.map(d => [d.tag, d.data as any]))
+
+  assert.equal(by['pv-1'].generatedKW, 210)
+  assert.equal(by['pv-1'].exportKW, 40)
+  assert.equal(by['ess-1'].soc, 62)
+  assert.equal(by['ess-1'].dischargeKW, 85)
+  assert.equal(by['load-1'].curtailable, true)
+  assert.equal(by['load-1'].minKW, 30)
+  assert.equal(by['cb-1'].position, 'closed')
+  /* 나이가 없으면 화면이 멈춘 값을 지금 값처럼 그린다 — 네 컴포넌트가 모두 이 키를 읽는다. */
+  for (const id of ['pv-1', 'ess-1', 'load-1', 'cb-1']) {
+    assert.equal(by[id].measuredAt, '2026-08-15T09:00:00.000Z', `${id}: 값의 나이가 함께 가야 한다`)
+  }
+})
+
+test('값이 없는 설비에는 그 키를 만들지 않는다 — 0 으로 그리면 「안 쓴다」가 된다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [{ id: 'pv-2', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle' }]
+    },
+    'ems-1'
+  )
+  const pv = deltas.find(d => d.tag === 'pv-2')!.data as any
+  assert.equal('generatedKW' in pv, false)
+  assert.equal('measuredAt' in pv, false)
+})