@things-factory/headless-twin 10.0.9 → 10.0.11

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, '에너지가 다른 층으로 들어온다는 사실을 근거로 적는다')
+})

package/test/state-axes.test.ts

@@ -32,7 +32,7 @@ test('고른 축만 남는다 — 지도가 쓰는 둘', () => {
   assert.equal(state.items, undefined, '쓰지 않는 축은 오지 않는다')
 })
 
-test('축을 말하지 않으면 자르지 않는다 — 기존 호출부가 그대로 동작해야 한다', () => {
+test('축을 지정하지 않으면 자르지 않는다 — 기존 호출부가 그대로 동작해야 한다', () => {
   assert.equal(pickAxes(STATE, undefined).state, STATE)
   assert.equal(pickAxes(STATE, []).state, STATE)
   assert.equal(pickAxes(STATE, null).state, STATE)

package/test/streamline-e2e.test.ts

@@ -1,6 +1,6 @@
 /*
- * ★ 캡스톤 · 스트림라인 전 사슬(in-process) — 모델 → board → 커널 → 라이브 payload.
- * master(템플릿 산출 동형) → masterToTwin → WmsKernel.loadBoard → tick → getSnapshot → buildEntityDeltas.
+ * ★ 캡스톤 · 스트림라인 전 사슬(in-process) — 모델 → model → 커널 → 라이브 payload.
+ * master(템플릿 산출 동형) → masterToTwin → WmsKernel.loadTwinModel → tick → getSnapshot → buildEntityDeltas.
  * 이 한 테스트가 조각들이 "함께" 동작함을 증명(개별 단위테스트 위의 통합).
  */
 import { test } from 'node:test'
@@ -8,7 +8,7 @@ import assert from 'node:assert/strict'
 
 import { WmsKernel, TwinRuntime } 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 wmsMaster = () => ({
   source: 'wh-e2e',
@@ -35,14 +35,14 @@ const snapshotState = (kernel: any) => {
 }
 
 test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라이브 payload (전 사슬 결합)', () => {
-  // 1) 모델 → board 토폴로지
-  const { board } = masterToTwin(wmsMaster())
-  assert.equal(board.locations.length, 5, '노드 5')
-  assert.equal(board.equipment.length, 2, '무버 2')
+  // 1) 모델 → model 토폴로지
+  const { model } = masterToTwin(wmsMaster())
+  assert.equal(model.locations.length, 5, '노드 5')
+  assert.equal(model.equipment.length, 2, '무버 2')
 
   // 2) 커널 로드 + 런타임 tick
   const kernel = new WmsKernel('e2e')
-  kernel.loadBoard(board)
+  kernel.loadTwinModel(model)
   const runtime = new TwinRuntime(kernel)
   for (let i = 0; i < 5; i++) runtime.tick(1000)
 
@@ -51,9 +51,9 @@ test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라
   const deltas = buildEntityDeltas(state, 't1')
   const tags = new Set(deltas.map(d => d.tag))
 
-  // 4) 보드의 모든 노드·무버가 payload 에 도달(커널→보드 결합 성립)
-  for (const n of board.locations) assert.ok(tags.has(n.id), `노드 ${n.id} payload 도달`)
-  for (const m of board.equipment) assert.ok(tags.has(m.id), `무버 ${m.id} payload 도달`)
+  // 4) 모델의 모든 노드·무버가 payload 에 도달(커널→보드 결합 성립)
+  for (const n of model.locations) assert.ok(tags.has(n.id), `노드 ${n.id} payload 도달`)
+  for (const m of model.equipment) assert.ok(tags.has(m.id), `무버 ${m.id} payload 도달`)
 
   // 5) 능력별 상태필드가 실림 — storable 노드 occupancy/capacity, mobile+operable 무버 location/status
   const rack = deltas.find(d => d.tag === 'rack-1')!.data as any
@@ -63,11 +63,11 @@ test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라
   assert.ok('location' in fk && 'status' in fk, 'mobile+operable payload 필드')
 })
 
-test('캡스톤: 결정성 — 같은 board+tick 은 같은 payload 시그니처', () => {
+test('캡스톤: 결정성 — 같은 model+tick 은 같은 payload 시그니처', () => {
   const run = () => {
-    const { board } = masterToTwin(wmsMaster())
+    const { model } = masterToTwin(wmsMaster())
     const kernel = new WmsKernel('det')
-    kernel.loadBoard(board)
+    kernel.loadTwinModel(model)
     const runtime = new TwinRuntime(kernel)
     for (let i = 0; i < 8; i++) runtime.tick(1000)
     return JSON.stringify(buildEntityDeltas(snapshotState(kernel), 't1'))

package/test/structure-revision-db.test.ts

@@ -51,11 +51,11 @@ const boardWith = (bins: number, forklifts: number): any => ({
 })
 
 /** 커널을 실제로 굴려 봉투를 얻는다 — 손으로 지어낸 모양은 검증이 아니다. */
-function realEvents(board: any, ticks: number): any[] {
+function realEvents(model: any, ticks: number): any[] {
   const journal = new EventJournal()
   const k = new WmsKernel('struct')
   k.onEvent((e: any) => journal.append(e))
-  k.loadBoard(board)
+  k.loadTwinModel(model)
   k.scenario.load({
     seed: 11,
     generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 120 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }]
@@ -94,10 +94,10 @@ beforeEach(async () => {
 })
 
 test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는다 — 부팅마다 늘면 이력이 잘게 쪼개진다', async () => {
-  const board = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', board)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', board)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(board)))
+  const model = boardWith(2, 1)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)))
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1)
@@ -165,7 +165,7 @@ test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는
   assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
 })
 
-test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 갈아타기가 결과를 바꾸지 않는다', async () => {
+test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전환이 결과를 바꾸지 않는다', async () => {
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2))
   const events = realEvents(boardWith(3, 2), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, events, 0)
@@ -203,7 +203,7 @@ test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신
   assert.equal(past.locations.filter((n: any) => n.type === 'storage').length, 2, '그때는 자리도 둘이었다')
 })
 
-test('구조 이력이 **무엇이 달라졌는지** 말한다 — 보드 두 개를 눈으로 비교할 수는 없다', async () => {
+test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두 개를 눈으로 비교할 수는 없다', async () => {
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
   const first = realEvents(boardWith(2, 1), 200)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
@@ -249,12 +249,12 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
    * 바뀐 트윈들이 재기동 한 번에 전부 "구조가 바뀌었다" 로 기록됐다. 저장된 **보드**와 비교하면
    * 그런 일이 없다.
    */
-  const board = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', board)
+  const model = boardWith(2, 1)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
   const table = ds.getMetadata(TwinStructure).tableName
   await ds.query(`UPDATE "${table}" SET signature = 'old-style-signature-from-a-previous-algorithm'`)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', board)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')

package/test/tenant-registry-db.test.ts

@@ -32,7 +32,7 @@ let beta: string
 /** 두 테넌트가 같은 벤더 시스템을 연결했을 때 실제로 생기는 id. */
 const SHARED_ID = 'sap-ewm-1710'
 
-const board = (): any => ({
+const model = (): any => ({
   spaceId: 'shared-space',
   utcOffsetMinutes: 0,
   locations: [
@@ -61,8 +61,8 @@ before(async () => {
   beta = b.id
 
   /* 두 테넌트가 **같은 id** 로 각자 프로비저닝한다 — DB 유일성이 `[domain, instanceId]` 라 허용된다. */
-  await TwinEngine.provision(alpha, SHARED_ID, 'wms', board())
-  await TwinEngine.provision(beta, SHARED_ID, 'wms', board())
+  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model())
+  await TwinEngine.provision(beta, SHARED_ID, 'wms', model())
 })
 
 /**
@@ -89,7 +89,7 @@ test('두 테넌트가 같은 id 로 프로비저닝된다 — 서로를 막지
   assert.equal(listB.filter((x: any) => x.instanceId === SHARED_ID).length, 1)
 })
 
-test('한쪽만 기동하면 다른 쪽은 **돌지 않는 것으로** 보인다 — 이 회귀가 핵심', async () => {
+test('한쪽만 기동하면 다른 쪽은 **정지한 것으로** 보인다 — 이 회귀가 핵심', async () => {
   await TwinEngine.startFromRegistry(alpha, SHARED_ID)
 
   assert.equal(TwinEngine.owns(alpha, SHARED_ID), true, 'alpha 는 자기 트윈을 갖는다')
@@ -127,7 +127,7 @@ test('접근자가 테넌트별로 답한다 — 커널·스냅샷·런타임',
   }
 })
 
-test('한쪽을 정지해도 다른 쪽은 계속 돈다 — 남의 런타임을 지우지 않는다', async () => {
+test('한쪽을 정지해도 다른 쪽은 계속 동작한다 — 남의 런타임을 지우지 않는다', async () => {
   await TwinEngine.startFromRegistry(alpha, SHARED_ID)
   await TwinEngine.startFromRegistry(beta, SHARED_ID)
 

package/test/twin-audit.test.ts

@@ -0,0 +1,83 @@
+/*
+ * 커맨드 감사 기록 — 이 검사가 지키는 것은 **기록이 증명력을 갖는가** 다.
+ *
+ * 감사 기록의 가치는 "남아 있다" 가 아니라 "믿을 수 있다" 에 있다. 클라이언트가 보낸 신원을 그대로
+ * 적으면 위조가 자유로워 아무것도 증명하지 못하고, 거절된 시도를 안 남기면 "무엇을 하려 했는가" 가
+ * 사라진다. 그 둘이 이 파일의 핵심 검사다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { buildCommandAudit, normalizeOrigin } from '../server/service/twin-audit/command-audit.ts'
+
+const AT = new Date('2026-08-06T12:00:00.000Z')
+
+test('명령 종류를 그대로 싣는다 — 무엇을 하려 했는지가 감사의 시작이다', () => {
+  const row = buildCommandAudit({ command: { commandId: 'c1', type: 'order.hold' }, ack: { accepted: true }, at: AT })
+  assert.equal(row.commandType, 'order.hold')
+  assert.equal(row.commandId, 'c1')
+})
+
+test('신원은 서버가 준 것만 적는다 — 커맨드에 실려 온 신원 주장은 무시한다', () => {
+  const row = buildCommandAudit({
+    /* 위조 시도: 클라이언트가 자기를 관리자라고 주장한다. */
+    command: { type: 'order.hold', actorId: 'admin', actorEmail: 'admin@corp', actorName: '관리자' },
+    ack: { accepted: true },
+    actor: { id: 'u-7', email: 'kim@corp', name: '김현장' },
+    at: AT
+  })
+  assert.equal(row.actorId, 'u-7')
+  assert.equal(row.actorEmail, 'kim@corp')
+  assert.equal(row.actorName, '김현장')
+})
+
+test('세션에 사용자가 없으면 비운다 — 모르는 것을 지어내지 않는다', () => {
+  const row = buildCommandAudit({ command: { type: 'order.hold' }, ack: { accepted: true }, at: AT })
+  assert.equal(row.actorId, undefined)
+  assert.equal(row.actorEmail, undefined)
+})
+
+test('커널이 거절한 시도도 남는다 — 무엇을 하려 했는지가 감사의 절반이다', () => {
+  const row = buildCommandAudit({
+    command: { type: 'equipment.repair', args: { id: 'cutter-1' } },
+    ack: { accepted: false, errorCode: 'not-broken' },
+    at: AT
+  })
+  assert.equal(row.accepted, false)
+  assert.equal(row.errorCode, 'not-broken')
+  assert.deepEqual(row.args, { id: 'cutter-1' })
+})
+
+test('출처는 아는 값만 — 모르면 unknown 이지 사람이 한 것으로 치지 않는다', () => {
+  assert.equal(normalizeOrigin('ai'), 'ai')
+  assert.equal(normalizeOrigin('user'), 'user')
+  assert.equal(normalizeOrigin('automation'), 'automation')
+  assert.equal(normalizeOrigin(undefined), 'unknown')
+  assert.equal(normalizeOrigin('관리자승인'), 'unknown')
+})
+
+test('근거는 문자열일 때만 싣는다 — 객체를 그대로 넣어 화면이 [object Object] 를 띄우지 않게', () => {
+  const ok = buildCommandAudit({ command: { type: 't', reason: '대기 15분 절감' }, ack: {}, at: AT })
+  assert.equal(ok.reason, '대기 15분 절감')
+  const bad = buildCommandAudit({ command: { type: 't', reason: { why: 'x' } }, ack: {}, at: AT })
+  assert.equal(bad.reason, undefined)
+})
+
+test('args 가 지나치게 크면 자르되 잘랐다고 알린다 — 조용히 버리지 않는다', () => {
+  const huge = { blob: 'x'.repeat(9000) }
+  const row = buildCommandAudit({ command: { type: 't', args: huge }, ack: {}, at: AT })
+  assert.equal(row.argsTruncated, true)
+  assert.equal(typeof row.args, 'string')
+  assert.ok((row.args as string).length <= 4000)
+})
+
+test('작은 args 는 자르지 않고 원형 그대로 — 나중에 따질 수 있어야 한다', () => {
+  const row = buildCommandAudit({ command: { type: 't', args: { id: 'a', qty: 3 } }, ack: {}, at: AT })
+  assert.equal(row.argsTruncated, false)
+  assert.deepEqual(row.args, { id: 'a', qty: 3 })
+})
+
+test('시각은 호출부가 준 서버 시각을 그대로 쓴다 — 클라이언트 시계를 믿지 않는다', () => {
+  const row = buildCommandAudit({ command: { type: 't', eventTime: '1999-01-01T00:00:00.000Z' }, ack: {}, at: AT })
+  assert.equal(row.eventTime.toISOString(), AT.toISOString())
+})