@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/state-axes.test.ts

@@ -0,0 +1,74 @@
+/*
+ * ★ 상태 축 고르기 — 리프레시가 통째로여서 무겁던 것.
+ *
+ * 지도는 구독 신호를 받고 상태를 다시 읽는다(신호는 가볍고 리프레시는 250ms 로 합쳐진다 — 설계대로).
+ * 문제는 **읽는 양**이었다: 실 저널로 재 보니 트윈 하나가 최대 710KB, 같은 공간에 셋이면 약 2MB.
+ * 그런데 지도가 쓰는 축은 `locations`·`attentions` 둘뿐이다.
+ *
+ * 여기서 지키는 것: 말하지 않으면 자르지 않는다(기존 호출부 무영향), 오타로 화면이 비지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pickAxes, STATE_AXES } from '../server/engine/state-axes.ts'
+
+const STATE = {
+  revision: 12,
+  nowTime: '2026-08-05T00:00:00.000Z',
+  simClockMs: 1000,
+  locations: [{ id: 'dock' }],
+  items: [{ epc: 'a' }, { epc: 'b' }],
+  equipment: [{ id: 'fk-1' }],
+  tasks: [{ id: 't1' }],
+  orders: [{ id: 'o1' }],
+  attentions: [{ id: 'bottleneck:dock' }],
+  acked: ['bottleneck:dock']
+}
+
+test('고른 축만 남는다 — 지도가 쓰는 둘', () => {
+  const { state, unknown } = pickAxes(STATE, ['locations', 'attentions'])
+  assert.deepEqual(unknown, [])
+  assert.deepEqual(Object.keys(state).sort(), ['attentions', 'locations', 'nowTime', 'revision', 'simClockMs'])
+  assert.equal(state.items, undefined, '쓰지 않는 축은 오지 않는다')
+})
+
+test('축을 지정하지 않으면 자르지 않는다 — 기존 호출부가 그대로 동작해야 한다', () => {
+  assert.equal(pickAxes(STATE, undefined).state, STATE)
+  assert.equal(pickAxes(STATE, []).state, STATE)
+  assert.equal(pickAxes(STATE, null).state, STATE)
+})
+
+test('시각과 리비전은 늘 남는다 — 무엇을 언제 받았는지 알아야 한다', () => {
+  const { state } = pickAxes(STATE, ['locations'])
+  assert.equal(state.revision, 12)
+  assert.equal(state.nowTime, STATE.nowTime)
+})
+
+test('모르는 축은 무시하되 그 사실을 돌려준다 — 오타로 화면이 비지 않게', () => {
+  const { state, unknown } = pickAxes(STATE, ['locations', 'attension'])
+  assert.deepEqual(unknown, ['attension'])
+  assert.ok(state.locations, '아는 축은 그대로 온다')
+})
+
+test('전부 오타면 자르지 않는다 — 빈 화면보다 통째가 낫다', () => {
+  const { state, unknown } = pickAxes(STATE, ['nope', 'alsonope'])
+  assert.equal(state, STATE)
+  assert.deepEqual(unknown, ['nope', 'alsonope'])
+})
+
+test('없는 축을 요청해도 키를 만들지 않는다 — 없는 것을 빈 배열로 위장하지 않는다', () => {
+  const { state } = pickAxes({ revision: 1, locations: [] }, ['locations', 'persons'])
+  assert.deepEqual(Object.keys(state).sort(), ['locations', 'revision'])
+  assert.equal('persons' in state, false)
+})
+
+test('상태가 아니면 그대로 돌려준다', () => {
+  assert.equal(pickAxes(null, ['locations']).state, null)
+  assert.equal(pickAxes(undefined, ['locations']).state, undefined)
+})
+
+test('축 목록이 상태의 축과 어긋나지 않는다 — 이름이 바뀌면 여기서 걸린다', () => {
+  for (const a of ['locations', 'items', 'equipment', 'attentions', 'acked']) {
+    assert.ok((STATE_AXES as readonly string[]).includes(a), a)
+  }
+})

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,25 +35,25 @@ 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)
 
   // 3) 스냅샷 → 라이브 payload(보드 컴포넌트가 구독할 data(tag))
   const state = snapshotState(kernel)
-  const deltas = buildEntityDeltas(state)
+  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,14 +63,14 @@ 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)))
+    return JSON.stringify(buildEntityDeltas(snapshotState(kernel), 't1'))
   }
   assert.equal(run(), run(), '동일 입력 → 동일 payload(결정적)')
 })

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 } } }]
@@ -89,14 +89,15 @@ beforeEach(async () => {
   for (const target of [TwinEvent, TwinStructure, TwinInstance]) await ds.query(`DELETE FROM "${ds.getMetadata(target).tableName}"`)
   /* 엔진의 리비전 캐시도 비운다 — 스펙 간에 남으면 다음 스펙이 옛 번호를 찍는다. */
   ;(TwinEngine as any).structureRevCache = {}
-  delete (TwinEngine as any).recovered[INSTANCE]
+  /* 키가 `(domainId, instanceId)` 로 바뀌었다 — id 만으로 지우면 아무것도 지워지지 않는다. */
+  delete (TwinEngine as any).recovered[`${domainId}:${INSTANCE}`]
 })
 
 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)
@@ -164,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)
@@ -202,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)
@@ -248,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, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')
@@ -277,7 +278,7 @@ test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지
     const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
     assert.equal(kept, first.length, 'sim-world 는 이어지는 현실이다 — 지우면 선언이 거짓이 된다')
   } finally {
-    await TwinEngine.stop(INSTANCE)
+    await TwinEngine.stop(domainId, INSTANCE)
   }
 })
 
@@ -295,7 +296,7 @@ test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹
       `이어 세지 않았다 — 저널 마지막 ${first.length}, 커널 ${kernel.getSnapshot().revision}`
     )
   } finally {
-    await TwinEngine.stop(INSTANCE)
+    await TwinEngine.stop(domainId, INSTANCE)
   }
 })
 
@@ -305,6 +306,6 @@ test('저널이 비어 있으면 이어 셀 것이 없다 — 새로 시작하
   try {
     assert.equal((rt.kernel as any).getSnapshot().revision, 0)
   } finally {
-    await TwinEngine.stop(INSTANCE)
+    await TwinEngine.stop(domainId, INSTANCE)
   }
 })

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

@@ -0,0 +1,149 @@
+/*
+ * ★ 두 테넌트가 **같은 인스턴스 id** 로 각자 돈다 — 실 DB로 경계를 넘어 본다.
+ *
+ * ── 계기 (2026-08-06 테넌트 격리 전수 확인) ──────────────────────────────────
+ * 런타임 레지스트리가 `instanceId` 하나로 키를 잡고 있었다. 그런데 DB 유일성은 `[domain, instanceId]`
+ * 이고 트윈의 정체성도 그쪽이다. **충돌은 이론이 아니다** — 레퍼런스 경로가 `instanceId` 로 레퍼런스
+ * 소스 이름(`sap-ewm-1710`)을 쓰고, 벤더 시스템 이름은 테넌트가 공유하는 어휘다.
+ *
+ * 그때 무엇이 틀렸나: `start`/`startFromRegistry` 가 **남의 런타임을 돌려주고**, `ingestLive` 는 도메인을
+ * 확인하지 않아 남의 커널에 이벤트를 적용할 수 있었고, 목록의 `running` 이 남의 런타임을 봤다.
+ *
+ * 이 결함은 **유닛으로는 안 잡힌다** — 두 테넌트가 실제로 등록되고 각자 기동해야 드러난다. 그래서
+ * 실 엔티티 sqlite 스키마 + 빌드 산출물로 경계를 넘는다(`structure-revision-db.test.ts` 와 같은 하네스).
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌려야 반영된다.**
+ */
+import { test, before, after, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let alpha: string
+let beta: string
+
+/** 두 테넌트가 같은 벤더 시스템을 연결했을 때 실제로 생기는 id. */
+const SHARED_ID = 'sap-ewm-1710'
+
+const model = (): any => ({
+  spaceId: 'shared-space',
+  utcOffsetMinutes: 0,
+  locations: [
+    { id: 'dock-recv', type: 'dock', capacity: 100 },
+    { id: 'bin-1', type: 'storage', capacity: 20 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv' }]
+})
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+
+  const a = await ds.getRepository(Domain).save({ name: 'tenant-alpha', subdomain: 'tenant-alpha' } as any)
+  const b = await ds.getRepository(Domain).save({ name: 'tenant-beta', subdomain: 'tenant-beta' } as any)
+  alpha = a.id
+  beta = b.id
+
+  /* 두 테넌트가 **같은 id** 로 각자 프로비저닝한다 — DB 유일성이 `[domain, instanceId]` 라 허용된다. */
+  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model())
+  await TwinEngine.provision(beta, SHARED_ID, 'wms', model())
+})
+
+/**
+ * **스펙마다 반드시 멈춘다.** 남기면 두 가지가 따라온다: 틱 타이머 때문에 러너가 끝나지 않고, 틱이
+ * 뒤늦게 던지는 DB 쓰기가 teardown 이후에 도착해 `SQLITE_MISUSE` 로 스위트를 오염시킨다.
+ */
+afterEach(async () => {
+  await TwinEngine.stop(alpha, SHARED_ID).catch(() => {})
+  await TwinEngine.stop(beta, SHARED_ID).catch(() => {})
+})
+
+after(async () => {
+  /* 정지 직후에도 진행 중인 쓰기가 있을 수 있다 — 커넥션을 닫기 전에 가라앉힌다. */
+  await new Promise(resolve => setTimeout(resolve, 120))
+  await ds?.destroy()
+})
+
+test('두 테넌트가 같은 id 로 프로비저닝된다 — 서로를 막지 않는다', async () => {
+  /* 예전에는 한쪽이 **떠 있으면** 다른 쪽 재프로비전이 "instance is running" 으로 막혔다(존재 노출). */
+  const listA = await TwinEngine.list(alpha)
+  const listB = await TwinEngine.list(beta)
+
+  assert.equal(listA.filter((x: any) => x.instanceId === SHARED_ID).length, 1)
+  assert.equal(listB.filter((x: any) => x.instanceId === SHARED_ID).length, 1)
+})
+
+test('한쪽만 기동하면 다른 쪽은 **정지한 것으로** 보인다 — 이 회귀가 핵심', async () => {
+  await TwinEngine.startFromRegistry(alpha, SHARED_ID)
+
+  assert.equal(TwinEngine.owns(alpha, SHARED_ID), true, 'alpha 는 자기 트윈을 갖는다')
+  assert.equal(TwinEngine.owns(beta, SHARED_ID), false, 'beta 는 기동하지 않았다')
+
+  /* 목록의 running 이 남의 런타임을 보면 안 된다 — 예전에는 beta 도 running: true 였다. */
+  const rowA = (await TwinEngine.list(alpha)).find((x: any) => x.instanceId === SHARED_ID)
+  const rowB = (await TwinEngine.list(beta)).find((x: any) => x.instanceId === SHARED_ID)
+  assert.equal(rowA.running, true)
+  assert.equal(rowB.running, false)
+})
+
+test('둘 다 기동하면 **서로 다른 런타임**이다 — 남의 것을 돌려받지 않는다', async () => {
+  const rtA = await TwinEngine.startFromRegistry(alpha, SHARED_ID)
+  const rtB = await TwinEngine.startFromRegistry(beta, SHARED_ID)
+
+  /* 예전에는 두 번째 호출이 첫 번째의 런타임을 그대로 돌려줬다(조기 반환이 id 로만 찾았다). */
+  assert.notEqual(rtA, rtB, '같은 객체를 돌려주면 두 테넌트가 한 커널을 공유한다')
+  assert.notEqual(TwinEngine.kernel(alpha, SHARED_ID), TwinEngine.kernel(beta, SHARED_ID))
+  assert.equal(rtA.domainId, alpha)
+  assert.equal(rtB.domainId, beta)
+})
+
+test('접근자가 테넌트별로 답한다 — 커널·스냅샷·런타임', async () => {
+  await TwinEngine.startFromRegistry(alpha, SHARED_ID)
+  await TwinEngine.startFromRegistry(beta, SHARED_ID)
+
+  for (const [who, other] of [
+    [alpha, beta],
+    [beta, alpha]
+  ]) {
+    assert.ok(TwinEngine.kernel(who, SHARED_ID), '자기 커널은 있다')
+    assert.notEqual(TwinEngine.kernel(who, SHARED_ID), TwinEngine.kernel(other, SHARED_ID))
+    assert.notEqual(TwinEngine.runtime(who, SHARED_ID), TwinEngine.runtime(other, SHARED_ID))
+  }
+})
+
+test('한쪽을 정지해도 다른 쪽은 계속 동작한다 — 남의 런타임을 지우지 않는다', async () => {
+  await TwinEngine.startFromRegistry(alpha, SHARED_ID)
+  await TwinEngine.startFromRegistry(beta, SHARED_ID)
+
+  await TwinEngine.stop(alpha, SHARED_ID)
+
+  assert.equal(TwinEngine.owns(alpha, SHARED_ID), false, '정지한 쪽은 사라진다')
+  assert.equal(TwinEngine.owns(beta, SHARED_ID), true, '남의 트윈은 그대로다')
+  assert.ok(TwinEngine.kernel(beta, SHARED_ID), 'beta 커널이 살아 있다')
+})
+
+test('없는 테넌트로 물으면 아무것도 주지 않는다 — 추측한 id 로 새지 않는다', async () => {
+  await TwinEngine.startFromRegistry(alpha, SHARED_ID)
+  const stranger = '99999999-9999-9999-9999-999999999999'
+
+  assert.equal(TwinEngine.owns(stranger, SHARED_ID), false)
+  assert.equal(TwinEngine.kernel(stranger, SHARED_ID), undefined)
+  assert.equal(TwinEngine.runtime(stranger, SHARED_ID), undefined)
+  assert.equal(TwinEngine.metrics(stranger, SHARED_ID), null)
+})

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())
+})