@things-factory/headless-twin 10.0.5 → 10.0.7

package/test/streamline-e2e.test.ts

@@ -17,11 +17,11 @@ const wmsMaster = () => ({
   space: { width: 90, depth: 40, unit: 'm' },
   locations: [
     { id: 'a-dc', type: 'warehouse', role: 'area' as const, name: '창고' },
-    { id: 'dock-recv', type: 'dock', role: 'node' as const, name: '입고 도크', capacity: 100 },
-    { id: 'rack-1', type: 'storage', role: 'node' as const, name: '랙1', parentId: 'a-dc', capacity: 60 },
-    { id: 'rack-2', type: 'storage', role: 'node' as const, name: '랙2', parentId: 'a-dc', capacity: 60 },
-    { id: 'staging', type: 'staging', role: 'node' as const, name: '스테이징', capacity: 80 },
-    { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, name: '출고 도크', capacity: 100 }
+    { id: 'dock-recv', type: 'dock', role: 'location' as const, name: '입고 도크', capacity: 100 },
+    { id: 'rack-1', type: 'storage', role: 'location' as const, name: '랙1', parentId: 'a-dc', capacity: 60 },
+    { id: 'rack-2', type: 'storage', role: 'location' as const, name: '랙2', parentId: 'a-dc', capacity: 60 },
+    { id: 'staging', type: 'staging', role: 'location' as const, name: '스테이징', capacity: 80 },
+    { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, name: '출고 도크', capacity: 100 }
   ],
   equipment: [
     { id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' },
@@ -31,14 +31,14 @@ const wmsMaster = () => ({
 
 const snapshotState = (kernel: any) => {
   const snap = kernel.getSnapshot()
-  return snap?.nodes || snap?.movers ? snap : snap?.state ?? snap
+  return snap?.locations || snap?.equipment ? snap : snap?.state ?? snap
 }
 
 test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라이브 payload (전 사슬 결합)', () => {
   // 1) 모델 → board 토폴로지
   const { board } = masterToTwin(wmsMaster())
-  assert.equal(board.nodes.length, 5, '노드 5')
-  assert.equal(board.movers.length, 2, '무버 2')
+  assert.equal(board.locations.length, 5, '노드 5')
+  assert.equal(board.equipment.length, 2, '무버 2')
 
   // 2) 커널 로드 + 런타임 tick
   const kernel = new WmsKernel('e2e')
@@ -52,8 +52,8 @@ test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라
   const tags = new Set(deltas.map(d => d.tag))
 
   // 4) 보드의 모든 노드·무버가 payload 에 도달(커널→보드 결합 성립)
-  for (const n of board.nodes) assert.ok(tags.has(n.id), `노드 ${n.id} payload 도달`)
-  for (const m of board.movers) assert.ok(tags.has(m.id), `무버 ${m.id} 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 도달`)
 
   // 5) 능력별 상태필드가 실림 — storable 노드 occupancy/capacity, mobile+operable 무버 location/status
   const rack = deltas.find(d => d.tag === 'rack-1')!.data as any

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

@@ -0,0 +1,310 @@
+/*
+ * ★ 구조 리비전 — **실 DB로 경계를 넘어 본다.**
+ *
+ * 커널의 마디 접기(`replaySegments`)는 그쪽 테스트가 지킨다. 여기서 지키는 것은 **호스트 배선**이다:
+ * 리비전을 언제 새로 만드는가 · 이벤트에 번호를 찍는가 · 재생이 그 번호로 마디를 나누는가 ·
+ * 컬럼이 생기기 전 행(번호 없음)을 어디에 붙이는가.
+ *
+ * 이 배선은 **경계를 넘어야만** 틀리는 것이 드러난다. 그런데 지금 앱의 트윈은 전부 리비전 1이라
+ * 경계를 한 번도 안 넘어 봤다 — 오늘 하루에만 "테스트는 통과하는데 배선이 틀린" 경우를 셋 봤으므로,
+ * 그 상태로 두지 않는다.
+ *
+ * 실 엔티티·실 네이밍 전략으로 만든 sqlite in-memory 스키마에 **빌드 산출물**을 그대로 실행한다.
+ * 소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌려야 반영된다.
+ */
+import { test, before, after, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+/*
+ * **CJS 로 실어 온다.** `dist-server` 는 CJS 이고 그 안의 twin-engine 은 커널을 `require` 로 든다.
+ * 그것을 ESM `import` 로 끌면 Node 의 ESM→CJS 번역기가 내부 단언에서 터진다(ERR_INTERNAL_ASSERTION).
+ * 실 산출물을 그대로 시험하는 것이 이 스펙의 요점이므로, 부르는 쪽이 CJS 로 맞춘다.
+ */
+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 { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { TwinStructure } = req('../dist-server/service/twin-structure/twin-structure.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { WmsKernel, EventJournal } = req('@operato/twin-kernel')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+const INSTANCE = 'struct-probe'
+const GTIN = 'urn:epc:idpat:sgtin:0614141.012345.*'
+
+/** 저장 자리 `bins` 개 + 지게차 `forklifts` 대 — 구조를 다이얼한다. */
+const boardWith = (bins: number, forklifts: number): any => ({
+  spaceId: 'struct-space',
+  utcOffsetMinutes: 0,
+  locations: [
+    { id: 'dock-recv', type: 'dock', capacity: 100 },
+    { id: 'staging', type: 'staging', capacity: 100 },
+    ...Array.from({ length: bins }, (_, i) => ({ id: `bin-${i + 1}`, type: 'storage', capacity: 20 }))
+  ],
+  equipment: Array.from({ length: forklifts }, (_, i) => ({ id: `fk-${i + 1}`, kind: 'forklift', homeLocation: 'dock-recv' }))
+})
+
+/** 커널을 실제로 굴려 봉투를 얻는다 — 손으로 지어낸 모양은 검증이 아니다. */
+function realEvents(board: any, ticks: number): any[] {
+  const journal = new EventJournal()
+  const k = new WmsKernel('struct')
+  k.onEvent((e: any) => journal.append(e))
+  k.loadBoard(board)
+  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 } } }]
+  })
+  k.scenario.start()
+  for (let i = 0; i < ticks; i++) k.tick(1000)
+  return journal.all() as any[]
+}
+
+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 d = await ds.getRepository(Domain).save({ name: 'struct-test', subdomain: 'struct-test' } as any)
+  domainId = d.id
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+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]
+})
+
+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 revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
+  assert.equal(revs.length, 1)
+  assert.equal(revs[0].rev, 1)
+})
+
+test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다**', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const first = realEvents(boardWith(2, 1), 300)
+  assert.ok(first.length > 0, '이벤트가 있어야 "살아남는지" 를 물을 수 있다')
+  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
+
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+
+  const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
+  assert.equal(kept, first.length, '구조가 바뀌었다고 이력을 지우면 안 된다 — 그것이 이 작업의 전부다')
+
+  const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE }, order: { rev: 'ASC' } })
+  assert.deepEqual(revs.map(r => r.rev), [1, 2])
+  assert.notEqual(revs[0].signature, revs[1].signature)
+})
+
+test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면 나중에 어느 공장인지 알 길이 없다', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(2, 1), 200), 0)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  const before = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
+  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 200), before)
+
+  const rows = await ds.getRepository(TwinEvent).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
+  const byRev = new Map<number | undefined, number>()
+  for (const r of rows) byRev.set(r.structureRev, (byRev.get(r.structureRev) ?? 0) + 1)
+  assert.deepEqual([...byRev.keys()].sort(), [1, 2], '두 구조에서 각각 쓰인 이벤트가 있어야 한다')
+  assert.ok((byRev.get(1) ?? 0) > 0 && (byRev.get(2) ?? 0) > 0)
+})
+
+test('★ 재생이 경계를 넘는다 — 앞선 사실은 남고, 새 구조의 설비가 들어온다', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const first = realEvents(boardWith(2, 1), 300)
+  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
+
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 300), first.length)
+
+  const state = await TwinEngine.recover(domainId, INSTANCE)
+  assert.ok(state.items.length > 0, '앞 마디의 물품이 사라지면 이력을 지운 것과 다를 바 없다')
+  assert.equal(state.equipment.length, 3, '새 구조의 지게차 셋이 상태에 들어와야 한다')
+  assert.equal(state.locations.filter((n: any) => n.type === 'storage').length, 6, '늘린 자리가 안 보이면 늘린 의미가 없다')
+})
+
+test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는다 — 새 공장에 대고 접지 않는다', async () => {
+  /*
+   * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 접으면 그때 없던
+   * 설비에서 일이 있었던 것처럼 보인다 — 이 규칙이 그 행들을 제자리에 붙인다.
+   */
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const legacy = realEvents(boardWith(2, 1), 300)
+  await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
+  /* 컬럼이 없던 시절을 흉내 낸다 — 번호를 지운다. */
+  await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
+
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  const state = await TwinEngine.recover(domainId, INSTANCE)
+  assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 조용히 버리지 않는다')
+  assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
+})
+
+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)
+
+  const state = await TwinEngine.recover(domainId, INSTANCE)
+  assert.equal(state.equipment.length, 2)
+  assert.equal(state.locations.filter((n: any) => n.type === 'storage').length, 3)
+  assert.ok(state.items.length > 0)
+})
+
+test('꺼진 트윈의 이력도 읽을 수 있다 — 저널은 트윈이 꺼져 있을 때 가장 필요하다', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  assert.equal(TwinEngine.owns(domainId, INSTANCE), false, '떠 있지 않다')
+  assert.equal(await TwinEngine.ownsRegistered(domainId, INSTANCE), true, '그래도 이 테넌트 것이다')
+  assert.equal(await TwinEngine.ownsRegistered(domainId, 'someone-elses-twin'), false)
+})
+
+test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신 구조를 얹으면 없던 설비가 선다', async () => {
+  /*
+   * "지금" 을 물으면 최신 구조를 얹는 것이 맞다(재프로비저닝 직후 늘린 설비가 보여야 하니까).
+   * 그런데 그 규칙을 과거 조회에도 적용하면, 그 시점에 존재하지도 않던 설비가 화면에 선다 —
+   * 이 작업이 막으려던 바로 그 거짓말이다. 규칙이 "지금" 에만 걸리는지 못박는다.
+   */
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const first = realEvents(boardWith(2, 1), 300)
+  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
+
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+
+  const now = await TwinEngine.recover(domainId, INSTANCE)
+  assert.equal(now.equipment.length, 3, '"지금" 은 늘린 설비를 보여준다')
+
+  const past = await TwinEngine.recover(domainId, INSTANCE, first.length)
+  assert.equal(past.equipment.length, 1, '그 시점에는 지게차가 하나뿐이었다')
+  assert.equal(past.locations.filter((n: any) => n.type === 'storage').length, 2, '그때는 자리도 둘이었다')
+})
+
+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)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), '도장 능력 보강')
+  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 100), first.length)
+
+  const history = await TwinEngine.structureHistory(domainId, INSTANCE)
+  assert.equal(history.length, 2)
+
+  /* 최초 리비전은 비교 대상이 없다 — 전부 새로 생긴 것으로 센다. */
+  assert.equal(history[0].rev, 1)
+  assert.equal(history[0].diff.locationsAdded, 4, '자리 넷(도크·스테이징·빈 둘)')
+  assert.ok(history[0].events > 0, '그 구조 아래 일어난 일의 수를 함께 말한다')
+
+  const second = history[1]
+  assert.equal(second.rev, 2)
+  assert.equal(second.comment, '도장 능력 보강')
+  assert.equal(second.diff.locationsAdded, 4, '저장 자리 넷이 늘었다')
+  assert.equal(second.diff.equipmentAdded, 2, '지게차 둘이 늘었다')
+  assert.deepEqual(
+    second.diff.locationTypes.find(c => c.key === 'storage'),
+    { key: 'storage', before: 2, after: 6, delta: 4 },
+    '"저장 자리 2 → 6" 이라고 읽혀야 한다'
+  )
+  assert.deepEqual(second.diff.equipmentKinds.find(c => c.key === 'forklift'), { key: 'forklift', before: 1, after: 3, delta: 2 })
+})
+
+test('번호 없는 옛 행도 가장 오래된 리비전의 몫으로 센다 — 재생과 같은 규칙', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const legacy = realEvents(boardWith(2, 1), 200)
+  await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
+  await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+
+  const history = await TwinEngine.structureHistory(domainId, INSTANCE)
+  assert.equal(history[0].events, legacy.length, '재생이 rev 1 로 접는 행들을 세는 쪽만 빠뜨리면 두 화면이 다른 말을 한다')
+  assert.equal(history[1].events, 0)
+})
+
+test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 — 계산 방식을 바꿔도 이력이 부풀지 않는다', async () => {
+  /*
+   * 실제로 당했다. 지문을 원문에서 해시로 바꾸자 저장된 문자열이 무엇과도 안 맞아, 아무것도 안
+   * 바뀐 트윈들이 재기동 한 번에 전부 "구조가 바뀌었다" 로 기록됐다. 저장된 **보드**와 비교하면
+   * 그런 일이 없다.
+   */
+  const board = boardWith(2, 1)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', board)
+  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)
+
+  const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
+  assert.equal(revs.length, 1, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')
+  assert.notEqual(revs[0].signature, 'old-style-signature-from-a-previous-algorithm', '표기는 새 방식으로 고쳐 둔다')
+})
+
+/*
+ * ── 이어지는 현실(sim-world) — 재기동해도 이력이 끊기지 않는다 ────────────────
+ *
+ * 예전에는 sim-world 선언이 저널을 지우고 fresh 로 띄웠다. 실제로 없던 것은 **번호 이어 세기
+ * 하나**였다: 상태 복원은 이미 저널 재생으로 하고 있었고, 막힌 것은 커널이 0부터 다시 세어 기존
+ * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 조용히 재생 순서를 뒤섞는다.
+ */
+test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지키는 약속', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const first = realEvents(boardWith(2, 1), 300)
+  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
+
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  try {
+    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)
+  }
+})
+
+test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹치면 재생 순서가 뒤섞인다', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const first = realEvents(boardWith(2, 1), 300)
+  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
+
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  try {
+    const kernel: any = rt.kernel
+    assert.ok(kernel, '커널이 떠야 이어 세기를 물을 수 있다')
+    assert.ok(
+      kernel.getSnapshot().revision >= first.length,
+      `이어 세지 않았다 — 저널 마지막 ${first.length}, 커널 ${kernel.getSnapshot().revision}`
+    )
+  } finally {
+    await TwinEngine.stop(INSTANCE)
+  }
+})
+
+test('저널이 비어 있으면 이어 셀 것이 없다 — 새로 시작하는 트윈에 영향 없음', async () => {
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  try {
+    assert.equal((rt.kernel as any).getSnapshot().revision, 0)
+  } finally {
+    await TwinEngine.stop(INSTANCE)
+  }
+})

package/test/twin-event-keys.test.ts

@@ -0,0 +1,108 @@
+/*
+ * ★ 저널 검색 키 승격 검증 — payload(JSON) 안의 값을 인덱스 가능한 실컬럼으로 꺼내는 규칙.
+ *
+ * 이 규칙이 틀리면 "저널에는 있는데 검색으로는 안 나오는 이벤트" 가 생긴다. 화면에서는 그냥
+ * **없는 것으로 보인다** — 저널에서 가장 나쁜 결함이라 규칙을 테스트로 고정한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { bizStepOf, epcOf, orderOf, locationOf, equipmentIdOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.ts'
+
+/** EPCIS ObjectEvent 한 건(입고) — 실제 인제스트가 싣는 모양. */
+const EPCIS_OBJECT = {
+  eventType: 'epcis.ObjectEvent',
+  eventTime: '2026-07-31T02:10:00.000Z',
+  data: {
+    bizStep: 'urn:epcglobal:cbv:bizstep:receiving',
+    disposition: 'urn:epcglobal:cbv:disp:in_progress',
+    epcList: ['urn:epc:id:sgtin:0614141.107346.2018'],
+    readPoint: { id: 'urn:epc:id:sgln:0614141.00777.DOCK-3' },
+    bizLocation: { id: 'urn:epc:id:sgln:0614141.00888.0' },
+    bizTransactionList: [{ type: 'urn:epcglobal:cbv:btt:po', bizTransaction: 'urn:epc:id:gdti:0614141.402.2' }]
+  }
+}
+
+test('EPCIS 이벤트에서 네 축이 모두 뽑힌다', () => {
+  const k = twinEventKeys(EPCIS_OBJECT)
+  assert.equal(k.bizStep, 'receiving')
+  assert.equal(k.epc, 'urn:epc:id:sgtin:0614141.107346.2018')
+  assert.equal(k.orderId, 'urn:epc:id:gdti:0614141.402.2')
+  assert.equal(k.locationId, 'urn:epc:id:sgln:0614141.00777.DOCK-3')
+})
+
+test('식별자는 끝마디가 아니라 전체를 저장한다 — 부분일치 검색이 양방향으로 성립해야 한다', () => {
+  const k = twinEventKeys(EPCIS_OBJECT)
+  /* 화면은 '2018' 로 축약해 보여주지만 색인은 원본을 갖는다. contains 검색이라
+   * 끝마디로도 URN 전체로도 찾힌다 — 끝마디만 저장하면 URN 경로가 사라진다. */
+  assert.ok(k.epc!.includes('2018'), '끝마디로 찾을 수 있어야 한다')
+  assert.ok(k.epc!.startsWith('urn:epc:id:sgtin'), 'URN 전체로도 찾을 수 있어야 한다')
+})
+
+test('readPoint 가 없으면 bizLocation 으로 내려간다', () => {
+  const ev = { ...EPCIS_OBJECT, data: { ...EPCIS_OBJECT.data, readPoint: undefined } }
+  assert.equal(locationOf(ev), 'urn:epc:id:sgln:0614141.00888.0')
+})
+
+test('bizStep 이 없으면 이벤트 타입에서 유추한다 — 운영 델타도 단계를 말할 수 있어야 한다', () => {
+  assert.equal(bizStepOf({ eventType: 'task.status', data: { task: 't1' } }), 'task.status')
+  assert.equal(bizStepOf({ eventType: 'epcis.AggregationEvent', data: {} }), 'AggregationEvent')
+})
+
+test('집합 이벤트는 parentID 를, 수량 이벤트는 epcClass 를 품목으로 쓴다', () => {
+  assert.equal(epcOf({ data: { parentID: 'urn:epc:id:sscc:0614141.1234567890' } }), 'urn:epc:id:sscc:0614141.1234567890')
+  assert.equal(epcOf({ data: { quantityList: [{ epcClass: 'urn:epc:idpat:sgtin:0614141.107346.*', quantity: 40 }] } }), 'urn:epc:idpat:sgtin:0614141.107346.*')
+})
+
+test('운영 델타의 오더는 bizTransactionList 가 아니라 order 필드에 있다', () => {
+  assert.equal(orderOf({ eventType: 'order.status', data: { order: 'SO-10021', status: 'released' } }), 'SO-10021')
+})
+
+test('없는 값은 빈 문자열이 아니라 undefined — 결측과 빈값을 섞지 않는다', () => {
+  const k = twinEventKeys({ eventType: 'equipment.status', data: { equipment: 'fork-1', status: 'idle' } })
+  assert.equal(k.epc, undefined)
+  assert.equal(k.orderId, undefined)
+  assert.equal(k.locationId, undefined)
+  assert.equal(k.moverId, undefined)
+  /* bizStep 은 이벤트 타입에서 유추되므로 남는다 — 이건 결측이 아니다. */
+  assert.equal(k.bizStep, 'equipment.status')
+})
+
+test('설비·무버 축 — 운영 델타의 moverId 를 뽑는다', () => {
+  const ev = { eventType: 'equipment.status', data: { moverId: 'fork-3', status: 'down', location: 'rack-1' } }
+  assert.equal(equipmentIdOf(ev), 'fork-3')
+  const k = twinEventKeys(ev)
+  assert.equal(k.moverId, 'fork-3')
+  /* 운영 델타는 readPoint/bizLocation 이 없다 — 평범한 location 을 위치로 받는다.
+   * 빠뜨리면 "이 설비가 어디서 무엇을 했나" 가 위치 축에서 통째로 사라진다. */
+  assert.equal(k.locationId, 'rack-1')
+})
+
+test('EPCIS 의 readPoint 는 운영 델타의 location 보다 우선한다', () => {
+  assert.equal(locationOf({ data: { readPoint: { id: 'DOCK-1' }, location: 'rack-9' } }), 'DOCK-1')
+})
+
+test('payload 가 data 로 감싸이지 않은 모양도 받는다', () => {
+  assert.equal(epcOf({ epcList: ['urn:epc:id:sgtin:1.2.3'] }), 'urn:epc:id:sgtin:1.2.3')
+})
+
+test('상한을 넘는 값은 조용히 사라지지 않는다 — 잘리되 경고가 남는다', () => {
+  const long = 'urn:epc:id:sgtin:' + 'x'.repeat(400)
+  const warned: string[] = []
+  const orig = console.warn
+  console.warn = (...a: unknown[]) => void warned.push(String(a[0]))
+  try {
+    const k = twinEventKeys({ data: { epcList: [long] } })
+    assert.equal(k.epc!.length, 255)
+    assert.equal(warned.length, 1, '잘렸다는 사실이 어딘가에는 남아야 한다')
+    assert.ok(warned[0].includes('epc'))
+  } finally {
+    console.warn = orig
+  }
+})
+
+test('빈 봉투에도 터지지 않는다', () => {
+  const empty = { bizStep: undefined, epc: undefined, orderId: undefined, locationId: undefined, moverId: undefined }
+  assert.deepEqual(twinEventKeys(undefined), empty)
+  assert.deepEqual(twinEventKeys({}), empty)
+})

package/test/vocabulary-guard.test.ts

@@ -0,0 +1,43 @@
+/*
+ * 어휘 가드 — 규칙은 커널이 한 벌 들고 있고(`@operato/twin-kernel` `retiredVocabularyIn`),
+ * 이 테스트는 **자기 패키지 소스를 훑는다.** 판정이 패키지마다 갈릴 수 없다.
+ *
+ * 계기(2026-08-01): 개명을 손으로 쓸다 같은 실수를 세 번 반복했다. 단어 경계로 찾으면 파생 식별자가
+ * 빠지고(`moverCount`·`locationType`), 빠진 것은 다음 파도에서야 드러난다. 그 사이 코드에는 두 어휘가
+ * 섞여 있고 다음 사람은 어느 쪽을 믿을지 모른다.
+ *
+ * 실패하면 위반 목록이 그대로 나온다 — 고치거나, 정당하면 그 줄에 `vocabulary-guard: allow <이유>` 를
+ * 남긴다(예외가 코드에 이유와 함께 남는다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { retiredVocabularyIn } from '@operato/twin-kernel'
+
+const ROOTS = ['server', 'client'].map(d => new URL(`../${d}`, import.meta.url).pathname)
+
+function walk(dir: string, out: string[] = []): string[] {
+  let entries: string[]
+  try { entries = readdirSync(dir) } catch { return out }
+  for (const e of entries) {
+    const p = join(dir, e)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+  }
+  return out
+}
+
+test('소스에 은퇴한 어휘(location·mover)가 남아 있지 않다', () => {
+  const bad: string[] = []
+  for (const root of ROOTS) {
+    for (const f of walk(root)) {
+      readFileSync(f, 'utf-8').split('\n').forEach((line, i) => {
+        const hits = retiredVocabularyIn(line)
+        if (hits.length) bad.push(`${f.split('/').slice(-2).join('/')}:${i + 1}  ${[...new Set(hits)].join(', ')}`)
+      })
+    }
+  }
+  assert.deepEqual(bad, [], `은퇴 어휘 ${bad.length}곳:\n${bad.slice(0, 60).join('\n')}${bad.length > 60 ? `\n… ${bad.length - 60} more` : ''}`)
+})

package/test/warm-start.test.ts

@@ -0,0 +1,78 @@
+/*
+ * ★ 웜스타트 판정 검증 — 재기동하는 커널에 직전 관측 상태를 심을지.
+ *
+ * 이 판정은 **양쪽으로 조용히 틀린다**: 심어야 할 때 안 심으면 있는 재고가 0 으로 보이고
+ * (2026-07-31 hatiolab-wms — 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다),
+ * 벤치에 심으면 용량 측정이 오염된다. 둘 다 화면에는 아무 이상이 없어 보인다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { planWarmStart } from '../server/engine/warm-start.ts'
+
+const STATE = {
+  locations: [{ id: 'dock-recv' }, { id: 'rack-1' }],
+  items: [{ epc: 'a' }, { epc: 'b' }, { epc: 'c' }],
+  equipment: [{ id: 'fork-1' }],
+  orders: [{ id: 'SO-1', kind: 'outbound', status: 'created', progress: 0.5 }],
+  tasks: [{ id: 't1' }]
+}
+
+test('상태가 있으면 심는다 — 재고·노드·무버', () => {
+  const plan = planWarmStart(STATE, undefined, true)
+  assert.equal(plan.action, 'hydrate')
+  if (plan.action !== 'hydrate') return
+  assert.equal(plan.itemCount, 3)
+  assert.equal(plan.equipmentCount, 1)
+  assert.deepEqual(plan.seed.locations, STATE.locations)
+})
+
+test('오더는 심지 않는다 — 스냅샷에 requested/fulfilled 가 없어 지어내야 하기 때문', () => {
+  const plan = planWarmStart(STATE, undefined, true)
+  assert.equal(plan.action, 'hydrate')
+  if (plan.action !== 'hydrate') return
+  assert.deepEqual(Object.keys(plan.seed).sort(), ['equipment', 'items', 'locations'])
+  assert.equal((plan.seed as any).orders, undefined)
+  assert.equal((plan.seed as any).tasks, undefined)
+})
+
+test('벤치 트윈에는 심지 않는다 — 새 시작에서 용량을 재는 것이 목적이다', () => {
+  const plan = planWarmStart(STATE, 'bench', true)
+  assert.deepEqual(plan, { action: 'skip', reason: 'bench' })
+})
+
+test('벤치 판정은 상태 유무보다 먼저다 — 상태가 없어도 이유는 bench 여야 한다', () => {
+  /* 이유가 뒤바뀌면 로그가 "심을 게 없었다" 로 남아, 벤치를 의도적으로 비웠다는 사실이 사라진다. */
+  assert.deepEqual(planWarmStart(null, 'bench', true), { action: 'skip', reason: 'bench' })
+})
+
+test('심을 상태가 없으면 조용히 넘어간다 — 처음 만든 트윈의 정상 경로다', () => {
+  assert.deepEqual(planWarmStart(null, undefined, true), { action: 'skip', reason: 'no-state' })
+  assert.deepEqual(planWarmStart(undefined, undefined, true), { action: 'skip', reason: 'no-state' })
+  assert.deepEqual(planWarmStart({ locations: [], items: [], equipment: [] }, undefined, true), { action: 'skip', reason: 'no-state' })
+})
+
+test('노드만 있어도 심는다 — 구조 배치가 복원되면 화면이 살아난다', () => {
+  const plan = planWarmStart({ locations: [{ id: 'n1' }], items: [], equipment: [] }, undefined, true)
+  assert.equal(plan.action, 'hydrate')
+  if (plan.action !== 'hydrate') return
+  assert.equal(plan.itemCount, 0)
+})
+
+test('커널이 주입을 지원하지 않으면 알린다 — 조용히 빈 채로 뜨면 안 된다', () => {
+  assert.deepEqual(planWarmStart(STATE, undefined, false), { action: 'skip', reason: 'unsupported' })
+})
+
+test('심을 게 없으면 미지원이어도 경고할 일이 아니다', () => {
+  /* 미지원 경고가 매 기동마다 뜨면 진짜 경고가 묻힌다. */
+  assert.deepEqual(planWarmStart(null, undefined, false), { action: 'skip', reason: 'no-state' })
+})
+
+test('빠진 배열은 빈 배열로 다뤄지되 없는 것을 지어내지 않는다', () => {
+  const plan = planWarmStart({ items: [{ epc: 'a' }] } as any, undefined, true)
+  assert.equal(plan.action, 'hydrate')
+  if (plan.action !== 'hydrate') return
+  assert.deepEqual(plan.seed.locations, [])
+  assert.deepEqual(plan.seed.equipment, [])
+  assert.equal(plan.itemCount, 1)
+})