@things-factory/headless-twin 10.0.9 → 10.0.11

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/column-type-portability.test.ts

@@ -0,0 +1,122 @@
+/*
+ * 컬럼 타입은 **드라이버 방언을 적지 않는다.**
+ *
+ * ── 무엇이 났나 (2026-08-19) ────────────────────────────────────────────────
+ * 릴리즈 부팅이 Postgres 에서 막혔다:
+ *
+ *   DataTypeNotSupportedError: Data type "datetime" in "TwinEvent.eventTime" is not supported by "postgres"
+ *
+ * `datetime` 은 **MySQL·MSSQL 의 이름**이다(Postgres·Oracle 은 거절한다). 거꾸로 `timestamp` 는 MySQL
+ * 이 받지만 예전 주석은 「sqlite 가 지원하지 않는다」고 적어 두었다 — sqlite 드라이버는 타입 목록이
+ * 비어 있어 **아무 이름도 검증하지 않는다**(그래서 개발 중에는 무엇을 적어도 통과했다). 결국 다섯
+ * 드라이버에 다 통하는 날짜 이름은 **없다.**
+ *
+ * 그래서 이름을 고르는 일을 TypeORM 에 맡긴다: `emitDecoratorMetadata` 가 켜져 있으므로 `Date` 속성에
+ * `@Column()` 만 달면 드라이버별로 알맞게 바뀐다(Postgres `timestamp without time zone` · sqlite·MySQL
+ * `datetime` · Oracle `timestamp`) — sqlite 거동은 그대로다.
+ *
+ * 이 시험은 그 규율을 **소스에서** 지킨다: 이 패키지의 엔티티가 명시한 타입 이름은 네 드라이버(검증을
+ * 하는 쪽) 모두가 아는 것이어야 한다. 개발 DB 가 sqlite 라 아무것도 못 잡아 주기 때문에 필요하다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+const req = createRequire(import.meta.url)
+
+/** 드라이버가 아는 타입 이름 — **TypeORM 소스에서 읽는다**(우리가 목록을 옮겨 적지 않는다). */
+function supportedTypes(driverPath: string): Set<string> {
+  const src = readFileSync(req.resolve(driverPath), 'utf-8')
+  const m = src.match(/supportedDataTypes = \[([\s\S]*?)\];/)
+  assert.ok(m, `${driverPath}: supportedDataTypes 를 찾지 못했다(TypeORM 구조가 바뀌었다)`)
+  return new Set((m![1].match(/"[^"]+"/g) ?? []).map(s => s.slice(1, -1)))
+}
+
+/*
+ * sqlite 는 목록이 비어 있다 = **검증하지 않는다.** 그래서 여기 넣지 않는다 — 넣으면 모든 타입이
+ * 「sqlite 가 모른다」로 걸려 이 시험이 소음이 된다. 개발 DB 가 아무것도 못 잡는다는 사실이 이 시험의 이유다.
+ */
+const DRIVERS: Record<string, string> = {
+  postgres: 'typeorm/driver/postgres/PostgresDriver.js',
+  mysql: 'typeorm/driver/mysql/MysqlDriver.js',
+  oracle: 'typeorm/driver/oracle/OracleDriver.js',
+  mssql: 'typeorm/driver/sqlserver/SqlServerDriver.js'
+}
+
+function entitySources(): { file: string; src: string }[] {
+  const root = fileURLToPath(new URL('../server', import.meta.url))
+  const out: { file: string; src: string }[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) { walk(path); continue }
+      if (!name.endsWith('.ts')) continue
+      const src = readFileSync(path, 'utf-8')
+      if (/@Entity\(/.test(src)) out.push({ file: path.slice(root.length + 1), src })
+    }
+  }
+  walk(root)
+  return out
+}
+
+test('엔티티가 있다 — 훑을 대상이 없으면 이 시험은 아무것도 지키지 않는다', () => {
+  assert.ok(entitySources().length >= 5, '이 패키지의 엔티티를 찾아야 한다')
+})
+
+/*
+ * **드라이버마다 이름이 다른 컬럼은 코드가 고른다.**
+ *
+ * 긴 글이 그렇다: `text` 를 Oracle 이 모르고(그쪽은 `clob`), MySQL 계열은 `longtext`, MSSQL 은
+ * `nvarchar(MAX)` 를 쓴다. 이 레포의 정본 관행은 `DATABASE_TYPE` 으로 분기하는 것이다
+ * (`board-service` 의 `Board.model`) — 그 분기는 이 시험의 리터럴 검사에 걸리지 않는다(정상이다).
+ *
+ * 그래서 면제 목록을 두지 않는다: 고정 리터럴은 전부 잡고, 갈라야 하는 컬럼은 관행대로 가른다.
+ */
+const KNOWN_GAPS = new Set<string>()
+
+test('명시한 컬럼 타입은 네 드라이버가 모두 아는 이름이다 — 개발 DB(sqlite)는 아무것도 잡아 주지 않는다', () => {
+  const supported = Object.fromEntries(Object.entries(DRIVERS).map(([n, p]) => [n, supportedTypes(p)]))
+  const violations: string[] = []
+  for (const { file, src } of entitySources()) {
+    for (const m of src.matchAll(/type:\s*'([a-z][a-z0-9 _]*)'/g)) {
+      const type = m[1]
+      const missing = Object.entries(supported).filter(([, s]) => !s.has(type)).map(([n]) => n)
+      if (!missing.length) continue
+      const line = `${file}: type '${type}' — ${missing.join(', ')} 가 모른다`
+      if (!KNOWN_GAPS.has(line)) violations.push(line)
+    }
+  }
+  assert.deepEqual(violations, [], `드라이버 방언을 적은 컬럼:\n${violations.join('\n')}`)
+})
+
+test('면제를 남겨 두면 그것이 아직 사실인지 확인한다 — 유령 면제를 남기지 않는다', () => {
+  const supported = Object.fromEntries(Object.entries(DRIVERS).map(([n, p]) => [n, supportedTypes(p)]))
+  const present = new Set<string>()
+  for (const { file, src } of entitySources()) {
+    for (const m of src.matchAll(/type:\s*'([a-z][a-z0-9 _]*)'/g)) {
+      const missing = Object.entries(supported).filter(([, s]) => !s.has(m[1])).map(([n]) => n)
+      if (missing.length) present.add(`${file}: type '${m[1]}' — ${missing.join(', ')} 가 모른다`)
+    }
+  }
+  for (const gap of KNOWN_GAPS) assert.ok(present.has(gap), `이 예외는 이제 사실이 아니다(목록에서 지워라): ${gap}`)
+})
+
+test('날짜 컬럼은 이름을 적지 않는다 — TypeORM 이 드라이버별로 고르게 둔다', () => {
+  for (const { file, src } of entitySources()) {
+    assert.equal(/type:\s*'(datetime|timestamp|timestamptz|datetime2|smalldatetime)'/.test(src), false, `${file}: 날짜 타입 이름을 적었다`)
+  }
+})
+
+/*
+ * 드라이버별로 갈라야 하는 컬럼은 **갈린 상태로** 있어야 한다 — 다시 고정 리터럴로 돌아가면 그 드라이버가
+ * 부팅에서 거절한다(감사 사유는 사람이 쓰는 글이라 길이를 자르지 않는다).
+ */
+test('긴 글 컬럼은 DATABASE_TYPE 으로 갈린다 — 관행을 되돌리지 않는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-audit/twin-audit-event.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /const DATABASE_TYPE = config\.get\('ormconfig', \{\}\)\.type/, '관행과 같은 자리에서 읽는다')
+  for (const name of ['longtext', 'clob', 'nvarchar', 'text']) assert.ok(src.includes(`'${name}'`), `${name} 갈래가 있어야 한다`)
+  assert.match(src, /length: DATABASE_TYPE == 'mssql' \? 'MAX' : undefined/, 'MSSQL 은 길이까지 말해야 잘리지 않는다')
+})

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