@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/registry-key-guard.test.ts

@@ -0,0 +1,80 @@
+/*
+ * 런타임 레지스트리 색인 가드 — **엔진 밖에서 맵을 직접 만지지 않는다.**
+ *
+ * 계기(2026-08-06): `TwinEngine.instances` 가 `instanceId` 하나로 키를 잡던 시절, 엔진 밖 네 곳이 그 맵을
+ * **직접 색인**했다(`TwinEngine.instances[instanceId]`, 심지어 `(TwinEngine as any).instances?.[…]`).
+ * 그래서 도메인 확인이 자리마다 제각각이었고 한 곳은 아예 없었다.
+ *
+ * 키를 `(domainId, instanceId)` 로 고쳤지만, **직접 색인이 남아 있으면 같은 부류가 다시 자란다** — 밖에서
+ * `instances[id]` 를 쓰면 이제는 항상 `undefined` 가 나와 조용히 "안 돌고 있다" 로 읽힌다(더 나쁘다:
+ * 오류가 아니라 거짓 사실이 된다). 그래서 접근자(`owns`·`runtime`·`kernel`·`metrics`·`snapshot`)만 쓴다.
+ *
+ * 이 부류는 이미 한 번 물었다 — `twin-lifecycle-mutation.ts` 주석이 증언한다("과거엔
+ * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그"). 그때는 그 자리만
+ * 고쳤다. 이번에는 기계가 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SERVER = new URL('../server', import.meta.url).pathname
+
+/** 맵을 소유한 자리 — 여기서는 색인해야 한다. */
+const OWNERS = ['engine/twin-engine.ts', 'engine/runtime-key.ts']
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+  }
+  return out
+}
+
+/** 주석 줄은 뺀다 — 이 결함을 설명하는 주석이 여러 곳에 있고, 그것을 위반으로 셀 수 없다. */
+const isComment = (line: string) => /^\s*(\/\/|\/\*|\*)/.test(line)
+
+test('엔진 밖에서 런타임 레지스트리를 직접 색인하지 않는다', () => {
+  const offenders: string[] = []
+
+  for (const file of walk(SERVER)) {
+    const rel = file.slice(SERVER.length + 1)
+    if (OWNERS.includes(rel)) continue
+
+    readFileSync(file, 'utf-8')
+      .split('\n')
+      .forEach((line, i) => {
+        if (isComment(line)) return
+        /*
+         * **엔진 참조가 같은 줄에 있을 때만** 위반이다(`as any` 우회 포함). `.instances[` 만 보면
+         * 무관한 배열(응답·지역 변수)까지 잡아 정당한 코드를 막는다.
+         */
+        if (/TwinEngine\s*(as\s+any\s*)?\)?\s*\.\s*(instances|recovered)/.test(line)) {
+          offenders.push(`${rel}:${i + 1}  ${line.trim().slice(0, 100)}`)
+        }
+      })
+  }
+
+  assert.deepEqual(
+    offenders,
+    [],
+    `레지스트리를 직접 색인하는 곳 ${offenders.length}곳 — 접근자(owns·runtime·kernel·metrics·snapshot)를 쓴다:\n` +
+      offenders.join('\n')
+  )
+})
+
+test('엔진이 맵을 만질 때는 항상 키 함수를 거친다', () => {
+  const src = readFileSync(join(SERVER, 'engine/twin-engine.ts'), 'utf-8')
+  const bad: string[] = []
+
+  src.split('\n').forEach((line, i) => {
+    if (isComment(line)) return
+    /* 색인하는 줄에는 `runtimeKey(` 또는 미리 만들어 둔 `key` 변수가 있어야 한다. */
+    if (!/this\.(instances|recovered)\s*\[/.test(line)) return
+    if (/runtimeKey\(/.test(line) || /\[key\]/.test(line)) return
+    bad.push(`engine/twin-engine.ts:${i + 1}  ${line.trim().slice(0, 100)}`)
+  })
+
+  assert.deepEqual(bad, [], `키 함수를 거치지 않고 색인하는 곳 ${bad.length}곳:\n${bad.join('\n')}`)
+})

package/test/resync-origin-site.test.ts

@@ -0,0 +1,77 @@
+/*
+ * 다시 읽기가 **자기 사이트**를 찾는가 — 사이트가 여럿인 참조에서 온 트윈의 재동기.
+ *
+ * ── 무엇이 났나 (2026-08-18 실측) ───────────────────────────────────────────
+ * `resyncTwin` 이 「reference "ems-gw-live" no longer reports this site」로 거절했다. 사이트는 멀쩡히
+ * 있었다 — 코드가 **다른 것을 견주고** 있었다: `origin.source` 는 레퍼런스 등록 이름(그 참조의 사이트
+ * 전부에 같다)이고 `master.source` 는 사이트별 인스턴스 id 다. 그래서 사이트가 여럿인 참조에서 온
+ * 트윈은 전부 재동기가 불가했고, 오류 문장은 원인을 참조 쪽으로 잘못 가리켰다(내가 그 문장을 읽고
+ * 커넥터를 의심했다).
+ *
+ * 고친 뒤의 규율: ① 가져올 때 사이트 정체를 남긴다 ② 다시 읽기는 그 사이트로 곧장 간다 ③ 기억이 없는
+ * 옛 트윈은 마스터의 정체(=인스턴스 id)로 찾는다 ④ 어느 쪽도 못 찾으면 **첫 사이트로 때우지 않는다**.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { pickOriginSite } from '../server/service/reference/reference-master.ts'
+
+const sites = [{ siteId: 'plant-1' }, { siteId: 'plant-2' }, { siteId: 'plant-3' }]
+
+test('기억해 둔 사이트로 곧장 간다', () => {
+  const { site, reason } = pickOriginSite(sites, { siteId: 'plant-2' })
+  assert.equal(site?.siteId, 'plant-2')
+  assert.equal(reason, undefined)
+})
+
+test('기억이 없으면 그렇게 말한다 — 첫 사이트로 때우지 않는다', () => {
+  const { site, reason } = pickOriginSite(sites, {})
+  assert.equal(site, undefined)
+  assert.equal(reason, 'no-remembered-site')
+})
+
+test('기억한 사이트가 사라졌으면 다른 사이트로 덮지 않는다', () => {
+  const { site, reason } = pickOriginSite(sites, { siteId: 'plant-9' })
+  assert.equal(site, undefined)
+  assert.equal(reason, 'site-gone', '다른 현장의 구조를 이 트윈에 덮는 것은 조용히 틀린 공장이 된다')
+})
+
+test('빈 문자열은 기억이 아니다', () => {
+  assert.equal(pickOriginSite(sites, { siteId: '  ' }).reason, 'no-remembered-site')
+})
+
+/* 배선이 사라지면 조용히 예전으로 돌아간다 — 소스 모양으로 못 박는다(리졸버는 DB·어댑터를 물고 있다). */
+test('다시 읽기는 인스턴스 정체로 견주고, 가져오기는 사이트 정체를 남긴다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-resolver.ts', import.meta.url)), 'utf-8')
+  /* 옛 비교식은 **설명문에 남아 있어야 한다**(왜 고쳤는지가 사라지면 되돌아간다) — 그래서 코드 줄만 본다. */
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\*|\/\/)/.test(line))
+    .join('\n')
+  assert.match(code, /pickOriginSite\(sites, origin\)/, '기억한 사이트로 곧장 가는 길이 있어야 한다')
+  assert.match(code, /master\.source === instanceId/, '옛 트윈은 마스터의 정체로 찾는다(참조 이름이 아니다)')
+  assert.equal(/master\.source === origin\.source/.test(code), false, '참조 이름과 인스턴스 id 를 견주지 않는다')
+  /* 사이트 정체는 남아 있어야 한다 — 현장 기억(spaceId)이 함께 붙어도 그 사실은 변하지 않는다. */
+  assert.match(code, /origin: \{ kind: 'reference', source, siteId: site\.siteId/, '가져올 때 사이트 정체를 남긴다')
+})
+
+/*
+ * ── 다시 읽기가 **현장 소속**을 지킨다 (2026-08-18 실측) ─────────────────────
+ * 한 현장에 합쳐 둔 EMS 트윈 여덟을 재동기했더니 각자 공간으로 흩어졌다 — 템플릿이 낸 기본 공간으로
+ * 돌아갔기 때문이다. 조용하다: 오류도 경고도 없고, 트윈은 멀쩡히 돌아간다. 그런데 그 순간 **그 현장의
+ * 값(요금·통화)을 함께 잃는다** — 현장 겹은 소속으로 얹히기 때문이다.
+ *
+ * 원인은 origin 이 「어느 현장에 합쳤나」를 기억하지 않은 것이다(구조만 기억했다).
+ */
+test('프로비저닝이 고른 현장을 origin 에 남기고, 다시 읽기가 그것을 따른다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-resolver.ts', import.meta.url)), 'utf-8')
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\*|\/\/)/.test(line))
+    .join('\n')
+  assert.match(code, /kind: 'template', templateId, params: effective, \.\.\.\(spaceId \? \{ spaceId \} : \{\}\)/, '템플릿 트윈이 현장을 기억한다')
+  assert.match(code, /const keepSpace = origin\.spaceId \|\| inst\.spaceId/, '기억이 없으면 지금 있는 현장을 지킨다')
+  assert.match(code, /ingestMaster\(domainId, master, keepSpace \? \{ spaceId: keepSpace \} : undefined/, '다시 읽기가 그 현장으로 넣는다')
+})

package/test/runtime-key.test.ts

@@ -0,0 +1,66 @@
+/*
+ * 런타임 키 — **트윈의 정체성은 `(도메인, 인스턴스 id)`.**
+ *
+ * 계기(2026-08-06): 런타임 레지스트리가 `instanceId` 하나로 키를 잡고 있었다. 레퍼런스 경로가 소스
+ * 이름을 그대로 id 로 쓰므로(`sap-ewm-1710`) 두 테넌트가 같은 벤더 시스템에 연결하면 같은 id 가 된다 —
+ * 그때 남의 커널에 이벤트가 적용되거나, 웜스타트 씨앗이 남의 스냅샷이 됐다.
+ *
+ * 이 테스트가 지키는 것은 **키가 모호해지지 않는 것** 하나다. 모호한 키는 조용히 틀린다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { RUNTIME_KEY_SEP, isOfDomain, parseRuntimeKey, runtimeKey } from '../server/engine/runtime-key.ts'
+
+const D1 = '11111111-1111-1111-1111-111111111111'
+const D2 = '22222222-2222-2222-2222-222222222222'
+
+test('같은 인스턴스 id 라도 테넌트가 다르면 다른 키다 — 이 작업의 요점', () => {
+  assert.notEqual(runtimeKey(D1, 'sap-ewm-1710'), runtimeKey(D2, 'sap-ewm-1710'))
+})
+
+test('같은 테넌트·같은 id 는 같은 키다 — 재기동이 자기 자리를 찾는다', () => {
+  assert.equal(runtimeKey(D1, 'hatiolab-wms'), runtimeKey(D1, 'hatiolab-wms'))
+})
+
+test('되돌리면 원래 둘이 나온다', () => {
+  const { domainId, instanceId } = parseRuntimeKey(runtimeKey(D1, 'hatiolab-wms'))
+
+  assert.equal(domainId, D1)
+  assert.equal(instanceId, 'hatiolab-wms')
+})
+
+test('인스턴스 id 안의 구분자를 보존한다 — 첫 구분자에서만 자른다', () => {
+  /* 레퍼런스 소스 이름에 `:` 가 들어갈 수 있다. 마지막 구분자에서 자르면 id 가 잘려 다른 트윈이 된다. */
+  const weird = 'urn:epc:id:sgln:0614141.12345'
+  const { domainId, instanceId } = parseRuntimeKey(runtimeKey(D1, weird))
+
+  assert.equal(domainId, D1)
+  assert.equal(instanceId, weird)
+})
+
+test('도메인 id 에 구분자가 있으면 던진다 — 조용히 모호한 키를 만들지 않는다', () => {
+  /* 조용히 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
+  assert.throws(() => runtimeKey(`a${RUNTIME_KEY_SEP}b`, 'x'), /ambiguous/)
+})
+
+test('빈 값은 키가 될 수 없다 — 테넌트 없는 런타임은 없다', () => {
+  assert.throws(() => runtimeKey('', 'x'), /domainId is required/)
+  assert.throws(() => runtimeKey(D1, ''), /instanceId is required/)
+})
+
+test('키가 아닌 것을 되돌리려 하면 던진다', () => {
+  for (const bad of ['', 'no-separator', `${RUNTIME_KEY_SEP}leading`, `trailing${RUNTIME_KEY_SEP}`]) {
+    assert.throws(() => parseRuntimeKey(bad), /is not a runtime key/, `입력: "${bad}"`)
+  }
+})
+
+test('도메인으로 걸러낸다 — 접두사가 아니라 경계까지 본다', () => {
+  const key = runtimeKey(D1, 'wms')
+
+  assert.equal(isOfDomain(key, D1), true)
+  assert.equal(isOfDomain(key, D2), false)
+  /* 도메인 id 의 앞부분만 같은 것에 걸리지 않는다(구분자까지 붙여 본다). */
+  assert.equal(isOfDomain(key, D1.slice(0, 8)), false)
+  assert.equal(isOfDomain(key, ''), false)
+})

package/test/scale-twin-bench.test.ts

@@ -1,7 +1,7 @@
 /*
  * 스케일 테스트 트윈 벤치 — 미국 공장(WMS+MES+YMS) 형태를 대규모로 스케일업, 5종 동기 엔티티 전부 부하.
  * 동기 엔티티 = locations·items(재고)·equipment·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
- * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송)·heap.
+ * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송, 't1')·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
 import { test } from 'node:test'
@@ -9,7 +9,7 @@ import assert from 'node:assert/strict'
 
 import { StateProjector, objectEvent, BIZSTEP, DISP, OP_EVENT } from '@operato/twin-kernel'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const T0 = '2026-07-20T00:00:00.000Z'
 const MB = (b: number) => Math.round(b / 1048576)
@@ -60,14 +60,14 @@ for (const [name, tier] of Object.entries(TIERS)) {
     // 1) 구조 생성(masterToTwin) — 노드·무버·area 계층
     const { master, locationCount, areaCount } = bigMaster(tier)
     let t = performance.now()
-    const { board, spaceContent } = masterToTwin(master)
+    const { model, spaceContent } = masterToTwin(master)
     const tMaster = performance.now() - t
     console.log(`\n  [${name}] 구조: 노드 ${locationCount.toLocaleString()} · 무버 ${tier.equipment} · area ${areaCount}(계층) · masterToTwin ${tMaster.toFixed(0)}ms`)
-    assert.equal(board.locations.length, locationCount)
+    assert.equal(model.locations.length, locationCount)
     assert.equal((spaceContent.areas ?? []).length, areaCount, 'area 계층 생성')
 
-    const proj = new StateProjector(board)
-    const equipment = board.equipment as any[]
+    const proj = new StateProjector(model)
+    const equipment = model.equipment as any[]
 
     // 2) apply 처리량 — 5종 혼합(items·equipment·tasks·orders)
     t = performance.now()
@@ -89,7 +89,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
 
     // 4) 방송 payload(buildEntityDeltas)
     t = performance.now()
-    for (let k = 0; k < iters; k++) buildEntityDeltas(s)
+    for (let k = 0; k < iters; k++) buildEntityDeltas(s, 't1')
     const tDelta = (performance.now() - t) / iters
     console.log(`  [${name}] buildEntityDeltas: ${tDelta.toFixed(2)}ms/call`)
     console.log(`  [${name}] heap: ${MB(process.memoryUsage().heapUsed)}MB`)

package/test/snapshot-freshness.test.ts

@@ -0,0 +1,60 @@
+/*
+ * 영속 스냅샷이 **사실을 이기지 않는다** — 쓸 수 있는 조건을 못 박는다.
+ *
+ * 멈춘 트윈을 조회할 때마다 저널을 전량 접고 있었다(23,731건짜리 트윈에서 4.6초). 스냅샷은 같은
+ * 폴드의 결과이므로 그 뒤로 아무 일도 없었다면 다시 접어 봐야 같은 값이다 — 그래서 쓴다.
+ *
+ * 위험은 하나다: **낡은 스냅샷을 "지금" 이라고 내는 것.** 그래서 쓰는 조건을 좁게 잡았고, 그 조건을
+ * 여기서 고정한다. 엔진 본체는 DB 를 물고 있어 부를 수 없으므로 판정식만 떼어 시험한다 —
+ * 엔진이 쓰는 식과 **같은 식**이어야 의미가 있으므로, 식이 바뀌면 이 시험이 먼저 깨진다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+/** 엔진의 조건과 같은 식(twin-engine.recover 의 스냅샷 사용 조건). */
+const usable = (
+  cached: { revision?: number; structureRev?: number | null; state?: any } | null,
+  tip: { revision: number; structureRev: number | null },
+  asOfNow: boolean
+): boolean =>
+  !!(asOfNow && cached?.state && (cached.revision ?? 0) === tip.revision && (cached.structureRev ?? null) === tip.structureRev)
+
+const TIP = { revision: 23731, structureRev: 2 }
+const FRESH = { revision: 23731, structureRev: 2, state: { locations: [] } }
+
+test('끝에 있고 구조도 같으면 쓴다 — 다시 접어도 같은 값이다', () => {
+  assert.equal(usable(FRESH, TIP, true), true)
+})
+
+test('이벤트가 더 있으면 쓰지 않는다 — 그 사이의 사실이 빠진다', () => {
+  assert.equal(usable({ ...FRESH, revision: 23730 }, TIP, true), false)
+})
+
+test('구조가 바뀌었으면 쓰지 않는다 — 이벤트가 안 늘어도 공장이 달라졌다', () => {
+  /* 재프로비저닝이 정확히 이 모양이다: 부스를 넷 늘렸는데 새 이벤트는 아직 없다.
+     리비전만 보면 "끝" 이라 새 설비가 없는 옛 상태를 지금으로 내게 된다. */
+  assert.equal(usable({ ...FRESH, structureRev: 1 }, TIP, true), false)
+})
+
+test('구조 이력이 없던 시절의 스냅샷은 쓰지 않는다 — 모르는 것을 같다고 하지 않는다', () => {
+  const legacy = { revision: 23731, state: { locations: [] } } // structureRev 없음
+  assert.equal(usable(legacy, TIP, true), false)
+})
+
+test('구조가 양쪽 다 없으면 그것은 같은 것이다 — 없는 것끼리는 어긋나지 않는다', () => {
+  assert.equal(usable({ revision: 5, structureRev: null, state: {} }, { revision: 5, structureRev: null }, true), true)
+  assert.equal(usable({ revision: 5, state: {} }, { revision: 5, structureRev: null }, true), true)
+})
+
+test('시간여행에는 쓰지 않는다 — 그 시점까지 접어야 한다', () => {
+  assert.equal(usable(FRESH, TIP, false), false)
+})
+
+test('상태가 비어 있는 스냅샷은 쓰지 않는다 — 빈 공장을 지금으로 내지 않는다', () => {
+  assert.equal(usable({ revision: 23731, structureRev: 2, state: null }, TIP, true), false)
+  assert.equal(usable(null, TIP, true), false)
+})
+
+test('이벤트가 하나도 없는 트윈도 성립한다 — 0 과 0 은 같다', () => {
+  assert.equal(usable({ revision: 0, structureRev: null, state: { locations: [] } }, { revision: 0, structureRev: null }, true), true)
+})

package/test/space-integrity.test.ts

@@ -0,0 +1,223 @@
+/*
+ * 공간 ↔ 트윈 ↔ 가시화 정합성 — 어긋난 모양마다 하나씩 세운다.
+ *
+ * 검사가 **무는지** 확인하는 것이 이 파일의 일이다: 정합한 입력에서는 아무것도 내지 않고, 어긋난
+ * 입력에서는 그 자리를 코드와 id 로 지목해야 한다. 지목하지 못하면 사람이 어디를 볼지 알 수 없다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { checkSpaceIntegrity, sortFindings, type SpaceIntegrityInput } from '../server/service/twin-space/space-integrity.ts'
+
+/** 정합한 한 현장 — 트윈 하나(창고), 지도 표현 하나, 구역 하나, 폴리곤이 그 구역과 로케이션을 가리킨다. */
+const SOUND: SpaceIntegrityInput = {
+  spaces: [{ spaceId: 'rosarito-site', primaryRepresentationId: 'rep-map' }],
+  instances: [
+    {
+      instanceId: 'wms-a',
+      spaceId: 'rosarito-site',
+      modelSpaceId: 'rosarito-site',
+      locationIds: ['rack-1', 'dock-1'],
+      equipmentIds: ['fork-1'],
+      areaRefs: ['bldg-1']
+    }
+  ],
+  representations: [
+    {
+      id: 'rep-map',
+      spaceId: 'rosarito-site',
+      type: 'map',
+      polygons: [
+        { id: 'p1', groupId: 'bldg-1' },
+        { id: 'p2', targetKind: 'location', targetId: 'rack-1' },
+        { id: 'p3', targetKind: 'equipment', targetId: 'fork-1' }
+      ]
+    }
+  ],
+  areasBySpace: { 'rosarito-site': ['bldg-1'] },
+  boardIds: []
+}
+
+test('정합하면 아무것도 내지 않는다 — 멀쩡한 현장을 시끄럽게 만들지 않는다', () => {
+  assert.deepEqual(checkSpaceIntegrity(SOUND), [])
+})
+
+test('없는 현장을 가리키는 트윈을 잡는다 — 무대가 사라진 트윈', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], spaceId: 'gone-site', modelSpaceId: 'gone-site' }]
+  })
+  const hit = f.find(x => x.code === 'twin-space-missing')
+  assert.ok(hit)
+  assert.equal(hit.severity, 'broken')
+  assert.equal(hit.instanceId, 'wms-a')
+  assert.equal(hit.spaceId, 'gone-site')
+})
+
+test('레지스트리와 model 의 현장이 다르면 잡는다 — 어느 쪽이 사실인지 알 수 없다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], modelSpaceId: 'other-site' }]
+  })
+  const hit = f.find(x => x.code === 'twin-space-mismatch')
+  assert.ok(hit)
+  assert.equal(hit.severity, 'broken')
+  assert.equal(hit.params?.registry, 'rosarito-site')
+  assert.equal(hit.params?.model, 'other-site')
+})
+
+test('현장 없는 트윈은 경고로 낸다 — 뗀 결과일 수 있어 고장은 아니다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], spaceId: undefined, modelSpaceId: undefined }]
+  })
+  const hit = f.find(x => x.code === 'twin-without-space')
+  assert.ok(hit)
+  assert.equal(hit.severity, 'warn')
+})
+
+test('로케이션이 이 현장에 없는 구역에 소속되어 있으면 잡는다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], areaRefs: ['bldg-1', 'floor-9', 'floor-9'] }]
+  })
+  const hit = f.find(x => x.code === 'location-area-missing')
+  assert.ok(hit)
+  assert.equal(hit.params?.count, 1, '중복은 한 번만 센다')
+  assert.equal(hit.params?.areas, 'floor-9')
+})
+
+test('폴리곤이 없는 구역을 가리키면 잡는다 — 그 도형은 아무것도 보여 주지 않는다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    representations: [{ ...SOUND.representations[0], polygons: [{ id: 'p1', groupId: 'ghost-area' }] }]
+  })
+  const hit = f.find(x => x.code === 'polygon-area-missing')
+  assert.ok(hit)
+  assert.equal(hit.severity, 'broken')
+  assert.equal(hit.representationId, 'rep-map')
+  assert.equal(hit.params?.areaId, 'ghost-area')
+})
+
+test('폴리곤이 이 현장의 어느 트윈에도 없는 로케이션을 가리키면 잡는다 — 트윈을 옮긴 뒤 남는 모양', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], spaceId: 'other-site', modelSpaceId: 'other-site' }],
+    spaces: [...SOUND.spaces, { spaceId: 'other-site' }]
+  })
+  const hits = f.filter(x => x.code === 'polygon-target-missing')
+  assert.equal(hits.length, 2, '로케이션과 설비 둘 다 끊긴다')
+  assert.equal(hits[0].severity, 'broken')
+  assert.equal(hits.find(h => h.params?.kind === 'equipment')?.params?.targetId, 'fork-1')
+})
+
+test('설비 바인딩을 로케이션 목록으로 판정하지 않는다 — 종류를 섞으면 거짓 경보가 난다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    representations: [
+      { ...SOUND.representations[0], polygons: [{ id: 'p3', targetKind: 'equipment', targetId: 'rack-1' }] }
+    ]
+  })
+  assert.ok(f.find(x => x.code === 'polygon-target-missing'), '로케이션 id 를 설비로 가리키면 끊긴 것이다')
+})
+
+test('대표 표현이 이 현장의 것이 아니면 잡는다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    spaces: [{ spaceId: 'rosarito-site', primaryRepresentationId: 'rep-elsewhere' }]
+  })
+  const hit = f.find(x => x.code === 'primary-representation-missing')
+  assert.ok(hit)
+  assert.equal(hit.severity, 'broken')
+})
+
+test('보드 표현이 보드를 가리키지 않으면 잡는다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    representations: [{ id: 'rep-board', spaceId: 'rosarito-site', type: 'board', boardId: null, polygons: [] }],
+    spaces: [{ spaceId: 'rosarito-site', primaryRepresentationId: 'rep-board' }]
+  })
+  const hit = f.find(x => x.code === 'board-representation-unbound')
+  assert.ok(hit)
+  assert.equal(hit.params?.boardId, '—')
+})
+
+test('없는 보드를 가리키는 보드 표현도 잡는다', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    representations: [{ id: 'rep-board', spaceId: 'rosarito-site', type: 'board', boardId: 'gone', polygons: [] }],
+    spaces: [{ spaceId: 'rosarito-site', primaryRepresentationId: 'rep-board' }],
+    boardIds: ['other-board']
+  })
+  assert.ok(f.find(x => x.code === 'board-representation-unbound'))
+})
+
+test('트윈이 사는데 표현이 없으면 경고한다 — 볼 화면이 없다', () => {
+  const f = checkSpaceIntegrity({ ...SOUND, representations: [], spaces: [{ spaceId: 'rosarito-site' }] })
+  const hit = f.find(x => x.code === 'space-without-representation')
+  assert.ok(hit)
+  assert.equal(hit.params?.twins, 1)
+})
+
+test('트윈이 없는 빈 현장은 정상이다 — 만들어 두고 아직 안 쓴 현장', () => {
+  const f = checkSpaceIntegrity({
+    spaces: [{ spaceId: 'empty-site' }],
+    instances: [],
+    representations: [],
+    areasBySpace: {},
+    boardIds: []
+  })
+  assert.deepEqual(f, [])
+})
+
+test('벤치 사본은 검사 대상이 아니다 — 잠깐 살고 지워지는 사본', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [
+      ...SOUND.instances,
+      { instanceId: 'bench-1', spaceId: 'nowhere-site', modelSpaceId: 'else', purpose: 'bench' }
+    ]
+  })
+  assert.deepEqual(f, [], '사본의 어긋남은 세지 않는다')
+})
+
+test('심각한 것이 먼저 온다 — 사람이 무엇부터 볼지 정하지 않아도 되게', () => {
+  const f = sortFindings([
+    { code: 'twin-without-space', severity: 'warn', message: 'w' },
+    { code: 'twin-space-missing', severity: 'broken', message: 'b' }
+  ])
+  assert.equal(f[0].severity, 'broken')
+})
+
+/*
+ * ── 어휘가 맞지 않는 트윈 (2026-08-14, EMS 를 붙이며) ────────────────────────
+ *
+ * 커널은 모르는 `eventType` 을 버리고 종류별로 센다(`state.unhandled`). 그 수가 0이 아니면 저널은
+ * 들어오는데 상태가 채워지지 않는 것이고, 화면에는 「정상인데 빈」 트윈으로 보인다.
+ *
+ * 이 검사가 지키는 것은 **모른다와 없다의 구별**이다: 정지한 트윈은 확인한 바가 없으므로 세지 않는다.
+ */
+test('담을 줄 모르는 어휘가 들어오는 트윈을 잡는다 — 리비전만 오르는 빈 트윈', () => {
+  const f = checkSpaceIntegrity({
+    ...SOUND,
+    instances: [{ ...SOUND.instances[0], unhandled: [{ eventType: 'energy.measured', count: 96 }, { eventType: 'energy.peak', count: 4 }] }]
+  })
+  const hit = f.find(x => x.code === 'twin-unhandled-vocabulary')!
+  assert.ok(hit, '이것을 놓치면 사용자는 커넥터가 잘못 붙은 것을 알 수 없다')
+  assert.equal(hit.severity, 'warn')
+  assert.equal(hit.instanceId, 'wms-a', '어느 트윈인지 지목해야 한다')
+  assert.equal(hit.params?.events, 100, '건수를 합쳐 낸다')
+  assert.equal(hit.params?.kinds, 2)
+  assert.match(String(hit.params?.types), /energy\.measured/, '많은 것부터 이름을 낸다')
+})
+
+test('정지한 트윈은 세지 않는다 — 확인하지 않은 것을 정합으로도 결함으로도 세지 않는다', () => {
+  /* `unhandled` 가 undefined 인 것은 「없다」가 아니라 「모른다」다(런타임이 없으면 알 수 없다). */
+  const f = checkSpaceIntegrity(SOUND)
+  assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
+})
+
+test('빈 배열은 결함이 아니다 — 받은 것이 없으면 조용하다', () => {
+  const f = checkSpaceIntegrity({ ...SOUND, instances: [{ ...SOUND.instances[0], unhandled: [] }] })
+  assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
+})

package/test/standard-coverage.test.ts

@@ -0,0 +1,94 @@
+/*
+ * 적합성 패널이 **그 트윈이 기대는 표준들**을 낸다 — 하나만 말하지 않는다.
+ *
+ * ── 무엇이 부족했나 (2026-08-15) ────────────────────────────────────────────
+ * 패널이 트윈 종류와 무관하게 ISA-95 하나만 말했다. 에너지 트윈에서 그것은 거짓은 아니지만
+ * (설비·계층·속성은 에너지에서도 ISA-95 자원이다) **부족하다**: 계량기·차단기·태양광·축전지의 어휘를
+ * 주는 것은 IEC 61850 이고, 무엇이 비었는지도 그 목록으로만 셀 수 있다.
+ *
+ * 그리고 주장 수준을 못 박는다 — 우리가 재는 것은 **어휘와 모델**이지 프로토콜 구현이 아니다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { standardsForKind } from '../server/service/twin-model/standard-coverage.ts'
+import { iec61850Coverage } from '../server/service/twin-model/iec61850-coverage.ts'
+import { epcisCoverage } from '../server/service/twin-model/epcis-coverage.ts'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const query = readFileSync(fileURLToPath(new URL('../server/service/twin-model/twin-model-query.ts', import.meta.url)), 'utf-8')
+
+const AXES = ['equipment', 'demandWindows', 'locations', 'persons', 'assets', 'orders', 'tasks', 'operations']
+
+test('ISA-95 는 종류와 상관없이 낸다 — 자원과 계층은 어느 도메인에서나 그 표준의 것이다', () => {
+  for (const kind of ['wms', 'yms', 'mes', 'ems']) {
+    assert.equal(standardsForKind(kind)[0], 'isa95', `${kind}: ISA-95 가 먼저다`)
+  }
+})
+
+test('에너지 트윈은 IEC 61850 을 함께 낸다 — 다른 종류에는 붙지 않는다', () => {
+  assert.deepEqual(standardsForKind('ems'), ['isa95', 'iec61850'])
+  for (const kind of ['wms', 'yms', 'mes']) {
+    assert.deepEqual(standardsForKind(kind), ['isa95', 'epcis'], `${kind}: 물류·제조는 EPCIS 다`)
+  }
+  /* 에너지에 EPCIS 를 붙이지 않는다 — 오가는 물건이 없고, 계측은 사건이 아니라 표본으로 들어온다. */
+  assert.equal(standardsForKind('ems').includes('epcis' as any), false)
+  assert.deepEqual(standardsForKind(undefined), ['isa95'], '종류를 모르면 공통 표준만')
+})
+
+test('질의가 그 정책으로 조립한다 — 규칙이 두 벌이 되지 않게', () => {
+  assert.match(query, /standardsForKind\(inst\.kind\)/, '질의가 정책 함수를 써야 한다')
+  assert.match(query, /COVERAGE\[id\]/, '표는 id 로 찾는다(종류 분기를 다시 쓰지 않는다)')
+})
+
+test('주장 수준을 이름에 적는다 — 프로토콜 적합성으로 읽히지 않게', () => {
+  const iec = iec61850Coverage(AXES)
+  assert.match(iec.model, /vocabulary/, '어휘를 쓴다는 뜻이지 MMS·GOOSE 를 구현했다는 뜻이 아니다')
+})
+
+test('개폐·발전·저장이 세 층 모두 올라갔다 — 값이 먼저, 컴포넌트는 그 다음', () => {
+  const iec = iec61850Coverage(AXES)
+  const by = Object.fromEntries(iec.concepts.map(c => [c.std, c]))
+  /*
+   * 오래 「구조만 있음」이던 셋이다. 능력이 상태 필드를 선언해 두었는데 값을 받는 문이 없었다 —
+   * 이제 커널이 `energy.equipment` 로 받아 설비에 적고, 씬 컴포넌트가 그린다.
+   */
+  for (const std of ['XCBR', 'DPVA', 'ZBAT']) {
+    assert.equal(by[std].behavior, 'full', `${std}: 값을 채우는 곳이 있다`)
+    assert.equal(by[std].surface, 'full', `${std}: 그리는 컴포넌트가 있다`)
+    assert.ok(by[std].note, `${std}: 근거를 한 줄로 적어야 한다`)
+  }
+  /* 채운 수는 `full` 만 센다 — 부분을 채운 것으로 세면 기준이 스스로를 속인다. */
+  assert.equal(iec.totals.behavior, 5, '다섯 논리 노드가 모두 실제로 돈다')
+})
+
+test('커널 축이 사라지면 구조가 없는 것으로 떨어진다 — 오타·개명이 조용히 통과하지 않게', () => {
+  const iec = iec61850Coverage(['equipment']) // demandWindows 축이 없는 세상
+  const mmxu = iec.concepts.find(c => c.std === 'MMXU')!
+  assert.equal(mmxu.structure, 'none')
+  assert.equal((mmxu as any).axisMissing, true)
+})
+
+test('EPCIS 표는 실제로 쓰는 것만 「있음」으로 센다 — 모양만 있는 필드는 구조만', () => {
+  const epcis = epcisCoverage(['items', 'orders', 'locations', 'tasks', 'operations'])
+  const by = Object.fromEntries(epcis.concepts.map(c => [c.std, c]))
+  /* 커널이 실제로 만들어 내보내는 사건들. */
+  for (const std of ['ObjectEvent', 'AggregationEvent', 'TransactionEvent', 'TransformationEvent']) {
+    assert.equal(by[std].behavior, 'full', `${std}: 커널이 실제로 낸다`)
+  }
+  /* 타입조차 없는 것은 없다고 적는다(EPCIS 2.0 이 더한 사건). */
+  assert.equal(by['AssociationEvent'].structure, 'none')
+  /* 모양만 있고 아무도 채우지 않는 것들 — 「구조만 있음」이지 「있음」이 아니다. */
+  for (const std of ['sourceList / destinationList', 'persistentDisposition', 'sensorElementList']) {
+    assert.equal(by[std].structure, 'partial', `${std}: 모양은 있다`)
+    assert.equal(by[std].behavior, 'none', `${std}: 아무도 채우지 않는다`)
+    assert.ok(by[std].note, `${std}: 왜 그 수준인지 적어야 한다`)
+  }
+})
+
+test('계측은 EPCIS 센서 필드로 오지 않는다 — 그 사실을 표가 말한다', () => {
+  const sensor = epcisCoverage(['items']).concepts.find(c => c.std === 'sensorElementList')!
+  assert.equal(sensor.behavior, 'none')
+  assert.ok(sensor.note, '에너지가 다른 층으로 들어온다는 사실을 근거로 적는다')
+})