@things-factory/headless-twin 10.0.6 → 10.0.8

package/test/oee-accumulator.test.ts

@@ -21,10 +21,10 @@ function runSimCollect() {
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const },
-      { id: 'dock-recv', type: 'dock', role: 'node' as const, capacity: 100 },
-      { id: 'rack-1', type: 'storage', role: 'node' as const, capacity: 60 },
-      { id: 'staging', type: 'staging', role: 'node' as const, capacity: 80 },
-      { id: 'dock-ship', type: 'dock-ship', role: 'node' as const, capacity: 100 }
+      { id: 'dock-recv', type: 'dock', role: 'location' as const, capacity: 100 },
+      { id: 'rack-1', type: 'storage', role: 'location' as const, capacity: 60 },
+      { id: 'staging', type: 'staging', role: 'location' as const, capacity: 80 },
+      { id: 'dock-ship', type: 'dock-ship', role: 'location' as const, capacity: 100 }
     ],
     equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv', mtbfMs: 5000, mttrMs: 8000 }]
   }
@@ -41,7 +41,7 @@ function runSimCollect() {
 
 test('★ OEE 누적기: downMs 정확 · busyMs=run+setup · 근사 OEE 유효', () => {
   const { events, snap } = runSimCollect()
-  const simOee = snap.movers.find((x: any) => x.id === 'fk-1')?.oee
+  const simOee = snap.equipment.find((x: any) => x.id === 'fk-1')?.oee
   assert.ok(simOee, 'sim fk-1 oee 존재')
   assert.ok(simOee.downMs > 0, '시나리오가 고장(down) 유발 — 검증 의미 있음')
 
@@ -82,20 +82,20 @@ test('★ OEE 누적기: quality.output 델타 소비 → quality 정확 (good/s
   assert.ok(Math.abs(oee.quality - 0.8) < 1e-9, 'quality = good/(good+scrap) = 0.8 (텔레메트리 없이 이벤트로 도출)')
 })
 
-test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live mover payload 에 oee 포함 (원 갭 종료)', () => {
+test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비 payload 에 oee 포함 (원 갭 종료)', () => {
   const { events, board } = runSimCollect()
   const proj = new StateProjector(board)
   const acc = new OeeAccumulator()
   for (const e of events) { proj.apply(e); acc.apply(e) }
 
   const rawLive = proj.snapshot() as any
-  // 원 갭: projector 미러 mover 엔 oee 없음.
-  assert.equal(rawLive.movers.find((m: any) => m.id === 'fk-1')?.oee, undefined, 'projector 미러엔 oee 부재(원 갭)')
+  // 원 갭: projector 미러 설비엔 oee 없음.
+  assert.equal(rawLive.equipment.find((m: any) => m.id === 'fk-1')?.oee, undefined, 'projector 미러엔 oee 부재(원 갭)')
 
   // withLiveOee 로 보강 → buildEntityDeltas payload 에 oee 포함(sim 과 동일 형상 = 보드 OEE 컴포넌트 live 렌더).
   const enriched = withLiveOee(rawLive, acc)
   const fk = buildEntityDeltas(enriched).find(d => d.tag === 'fk-1')!.data as any
-  assert.ok(fk.oee, 'withLiveOee 후 mover data(tag) payload 에 oee 포함 — live OEE 갭 종료')
+  assert.ok(fk.oee, 'withLiveOee 후 설비 data(tag) payload 에 oee 포함 — live OEE 갭 종료')
   // buildEntityDeltas shapeOee = 정수 퍼센트(0-100), raw ms 제외.
   assert.ok(fk.oee.overall >= 0 && fk.oee.overall <= 100, 'oee.overall ∈ [0,100] 정수 퍼센트')
   assert.ok(fk.oee.availability < 100, 'availability < 100 (고장 시간 반영 — 누적기 downMs)')

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

@@ -1,6 +1,6 @@
 /*
  * 스케일 테스트 트윈 벤치 — 미국 공장(WMS+MES+YMS) 형태를 대규모로 스케일업, 5종 동기 엔티티 전부 부하.
- * 동기 엔티티 = nodes·items(재고)·movers·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
+ * 동기 엔티티 = locations·items(재고)·equipment·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
  * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송)·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
@@ -15,7 +15,7 @@ const T0 = '2026-07-20T00:00:00.000Z'
 const MB = (b: number) => Math.round(b / 1048576)
 
 /** 미국 공장형 대규모 master 생성: 건물>층>존 area 계층 + 노드(storage/dock/station) + 무버(forklift/cutter/welder/hostler). */
-function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: number; nodesPerZone: number; movers: number }) {
+function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: number; nodesPerZone: number; equipment: number }) {
   const locations: any[] = []
   let nodeN = 0
   for (let b = 0; b < tier.buildings; b++) {
@@ -27,57 +27,57 @@ function bigMaster(tier: { buildings: number; floorsPer: number; zonesPer: numbe
         locations.push({ id: zid, type: 'zone', role: 'area', name: `존 ${b}-${f}-${z}`, parentId: `bld-${b}-flr-${f}` })
         for (let n = 0; n < tier.nodesPerZone; n++) {
           const t = n % 4 === 0 ? 'dock' : n % 4 === 1 ? 'staging' : 'storage'
-          locations.push({ id: `nd-${nodeN}`, type: t, role: 'node', name: `노드 ${nodeN}`, parentId: zid, capacity: 500, footprint: { x: nodeN % 100, y: (nodeN / 100) | 0, w: 1, h: 1 } })
+          locations.push({ id: `nd-${nodeN}`, type: t, role: 'location', name: `노드 ${nodeN}`, parentId: zid, capacity: 500, footprint: { x: nodeN % 100, y: (nodeN / 100) | 0, w: 1, h: 1 } })
           nodeN++
         }
       }
     }
   }
   const KINDS = ['forklift', 'cutter', 'welder', 'hostler']
-  const equipment = Array.from({ length: tier.movers }, (_, i) => ({ id: `mv-${i}`, kind: KINDS[i % 4], homeLocationId: `nd-${i % nodeN}` }))
+  const equipment = Array.from({ length: tier.equipment }, (_, i) => ({ id: `mv-${i}`, kind: KINDS[i % 4], homeLocationId: `nd-${i % nodeN}` }))
   return {
     master: { source: 'scale-us', system: 'wms' as const, siteName: 'US 공장(스케일)', space: { width: 500, depth: 300, unit: 'm', geo: { lat: 32.7, lon: -117.1 } }, locations, equipment },
-    nodeCount: nodeN,
+    locationCount: nodeN,
     areaCount: locations.filter(l => l.role === 'area').length
   }
 }
 
-function itemEnv(i: number, node: string): any {
-  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [`urn:epc:id:sscc:0614141.${i}`], readPoint: node })
+function itemEnv(i: number, location: string): any {
+  const ev = objectEvent({ eventTime: T0, action: 'OBSERVE' as any, bizStep: BIZSTEP.storing, disposition: DISP.sellable, epcList: [`urn:epc:id:sscc:0614141.${i}`], readPoint: location })
   return { eventId: `i${i}`, eventType: `epcis.${ev.type}`, eventTime: T0, tenantId: 't', data: ev }
 }
-const moverEnv = (id: string, kind: string, loc: string): any => ({ eventId: id, eventType: OP_EVENT.equipment, eventTime: T0, tenantId: 't', data: { moverId: id, kind, status: 'running', location: loc } })
+const equipmentEnv = (id: string, kind: string, loc: string): any => ({ eventId: id, eventType: OP_EVENT.equipment, eventTime: T0, tenantId: 't', data: { moverId: id, kind, status: 'running', location: loc } })
 const taskEnv = (id: string, to: string): any => ({ eventId: id, eventType: OP_EVENT.task, eventTime: T0, tenantId: 't', data: { taskId: id, kind: 'move', status: 'in-progress', toNode: to } })
 const orderEnv = (id: string): any => ({ eventId: id, eventType: OP_EVENT.order, eventTime: T0, tenantId: 't', data: { orderId: id, kind: 'inbound', status: 'in-progress', requested: 100, fulfilled: 50 } })
 
 const TIERS = {
-  medium: { buildings: 3, floorsPer: 3, zonesPer: 4, nodesPerZone: 8, movers: 80, items: 30000, tasks: 2000, orders: 500 },
-  large: { buildings: 6, floorsPer: 4, zonesPer: 6, nodesPerZone: 12, movers: 300, items: 120000, tasks: 10000, orders: 2000 }
+  medium: { buildings: 3, floorsPer: 3, zonesPer: 4, nodesPerZone: 8, equipment: 80, items: 30000, tasks: 2000, orders: 500 },
+  large: { buildings: 6, floorsPer: 4, zonesPer: 6, nodesPerZone: 12, equipment: 300, items: 120000, tasks: 10000, orders: 2000 }
 }
 
 for (const [name, tier] of Object.entries(TIERS)) {
   test(`스케일 트윈 [${name}] — 구조 생성 + 5종 엔티티 부하 실측`, () => {
     // 1) 구조 생성(masterToTwin) — 노드·무버·area 계층
-    const { master, nodeCount, areaCount } = bigMaster(tier)
+    const { master, locationCount, areaCount } = bigMaster(tier)
     let t = performance.now()
     const { board, spaceContent } = masterToTwin(master)
     const tMaster = performance.now() - t
-    console.log(`\n  [${name}] 구조: 노드 ${nodeCount.toLocaleString()} · 무버 ${tier.movers} · area ${areaCount}(계층) · masterToTwin ${tMaster.toFixed(0)}ms`)
-    assert.equal(board.nodes.length, nodeCount)
+    console.log(`\n  [${name}] 구조: 노드 ${locationCount.toLocaleString()} · 무버 ${tier.equipment} · area ${areaCount}(계층) · masterToTwin ${tMaster.toFixed(0)}ms`)
+    assert.equal(board.locations.length, locationCount)
     assert.equal((spaceContent.areas ?? []).length, areaCount, 'area 계층 생성')
 
     const proj = new StateProjector(board)
-    const movers = board.movers as any[]
+    const equipment = board.equipment as any[]
 
-    // 2) apply 처리량 — 5종 혼합(items·movers·tasks·orders)
+    // 2) apply 처리량 — 5종 혼합(items·equipment·tasks·orders)
     t = performance.now()
-    for (let i = 0; i < tier.items; i++) proj.apply(itemEnv(i, `nd-${i % nodeCount}`))
-    for (let i = 0; i < tier.movers; i++) proj.apply(moverEnv(movers[i].id, movers[i].kind, `nd-${i % nodeCount}`))
-    for (let i = 0; i < tier.tasks; i++) proj.apply(taskEnv(`tk-${i}`, `nd-${i % nodeCount}`))
+    for (let i = 0; i < tier.items; i++) proj.apply(itemEnv(i, `nd-${i % locationCount}`))
+    for (let i = 0; i < tier.equipment; i++) proj.apply(equipmentEnv(equipment[i].id, equipment[i].kind, `nd-${i % locationCount}`))
+    for (let i = 0; i < tier.tasks; i++) proj.apply(taskEnv(`tk-${i}`, `nd-${i % locationCount}`))
     for (let i = 0; i < tier.orders; i++) proj.apply(orderEnv(`or-${i}`))
-    const total = tier.items + tier.movers + tier.tasks + tier.orders
+    const total = tier.items + tier.equipment + tier.tasks + tier.orders
     const tApply = performance.now() - t
-    console.log(`  [${name}] apply: ${total.toLocaleString()} 이벤트(items+movers+tasks+orders) ${tApply.toFixed(0)}ms = ${Math.round((total / tApply) * 1000).toLocaleString()} ev/s`)
+    console.log(`  [${name}] apply: ${total.toLocaleString()} 이벤트(items+equipment+tasks+orders) ${tApply.toFixed(0)}ms = ${Math.round((total / tApply) * 1000).toLocaleString()} ev/s`)
 
     // 3) snapshot(전체 투영) — 5종 전부
     let s: any
@@ -85,7 +85,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     t = performance.now()
     for (let k = 0; k < iters; k++) s = proj.snapshot()
     const tSnap = (performance.now() - t) / iters
-    console.log(`  [${name}] snapshot: ${tSnap.toFixed(2)}ms/call (items ${s.items.length.toLocaleString()}·nodes ${s.nodes.length.toLocaleString()}·movers ${s.movers.length}·tasks ${s.tasks.length}·orders ${s.orders.length}) → 최대 ${Math.round(1000 / tSnap).toLocaleString()} snap/s`)
+    console.log(`  [${name}] snapshot: ${tSnap.toFixed(2)}ms/call (items ${s.items.length.toLocaleString()}·locations ${s.locations.length.toLocaleString()}·equipment ${s.equipment.length}·tasks ${s.tasks.length}·orders ${s.orders.length}) → 최대 ${Math.round(1000 / tSnap).toLocaleString()} snap/s`)
 
     // 4) 방송 payload(buildEntityDeltas)
     t = performance.now()
@@ -95,7 +95,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     console.log(`  [${name}] heap: ${MB(process.memoryUsage().heapUsed)}MB`)
 
     // 정합 sanity
-    assert.equal(s.movers.length, tier.movers)
+    assert.equal(s.equipment.length, tier.equipment)
     assert.equal(s.orders.length, tier.orders)
     assert.ok(s.items.length > 0)
   })

package/test/spec-coverage.test.ts

@@ -0,0 +1,113 @@
+/*
+ * 시뮬 명세 자격 판정 — **"이 예측으로 무엇을 말할 수 있나" 를 숫자로 가른다.**
+ *
+ * 배경: 공정 소요가 커널 상수였을 때와 현장 명세로 굴렸을 때가 응답에서 똑같이 "p50 168" 로 보였다.
+ * 그 둘을 구별하지 못하면 상대 비교용 숫자가 절대 예측처럼 읽힌다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { classifySpecCoverage, readSpecCoverage } from '../server/engine/spec-coverage.ts'
+
+test('전부 기본값이면 상대 비교만 — 절대 시각을 주장할 근거가 없다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'default' },
+      { kind: 'pick', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'relative')
+  assert.equal(r!.declaredDurations, 0)
+  assert.equal(r!.defaultDurations, 2)
+})
+
+test('전부 선언되면 절대 예측 시도 가능 — 단 정확도는 별개(이름이 capable 이다)', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'cut', duration: 'declared', variability: 'triangular', parameters: ['yield'] },
+      { kind: 'weld', duration: 'declared', variability: 'uniform' }
+    ]
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+  assert.equal(r!.varyingDurations, 2)
+})
+
+test('섞이면 partial — 한쪽만 접지된 사실을 감추지 않는다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'cut', duration: 'declared' },
+      { kind: 'paint', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'partial')
+  assert.equal(r!.declaredDurations, 1)
+  assert.equal(r!.defaultDurations, 1)
+})
+
+test('변동 없는 선언은 varying 0 — 고정값이면 대기·병목이 과소평가된다는 신호', () => {
+  const r = classifySpecCoverage({ operations: [{ kind: 'cut', duration: 'declared' }] })
+  assert.equal(r!.varyingDurations, 0)
+  const c = classifySpecCoverage({ operations: [{ kind: 'cut', duration: 'declared', variability: 'constant' }] })
+  assert.equal(c!.varyingDurations, 0, 'constant 는 변동이 아니다')
+})
+
+test('관측된 작업이 없으면 판정하지 않는다 — 모름을 relative 로 단정하지 않는다', () => {
+  assert.equal(classifySpecCoverage({ operations: [] }), undefined)
+  assert.equal(classifySpecCoverage({} as any), undefined)
+})
+
+test('커널이 보고 API 를 갖지 않으면 undefined — "전부 기본값" 이라 단정하지 않는다', () => {
+  assert.equal(readSpecCoverage({}), undefined)
+  assert.equal(readSpecCoverage(undefined), undefined)
+})
+
+test('커널 보고가 던져도 예측을 깨지 않는다', () => {
+  assert.equal(readSpecCoverage({ specCoverage: () => { throw new Error('boom') } }), undefined)
+})
+
+test('커널 보고를 그대로 분류한다 — 카운트를 다시 세지 않고 준 값을 존중', () => {
+  const r = readSpecCoverage({
+    specCoverage: () => ({
+      operations: [{ kind: 'cut', duration: 'declared', parameters: ['yield'] }],
+      declaredDurations: 1,
+      defaultDurations: 0
+    })
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+  assert.deepEqual(r!.operations[0].parameters, ['yield'])
+})
+
+/* ── 실측이 들어오면 자격이 한 칸 올라간다 ─────────────────────────────── */
+
+test('전부 이력에서 온 소요면 calibrated — 선언은 사람이 적은 값, 이것은 일어난 값', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'pick', duration: 'measured' }
+    ]
+  })
+  assert.equal(r!.qualification, 'calibrated')
+  assert.equal(r!.measuredDurations, 2)
+})
+
+test('실측과 선언이 섞이면 absolute-capable — 상수가 없으면 시각을 말할 수 있다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'cut', duration: 'declared' }
+    ]
+  })
+  assert.equal(r!.qualification, 'absolute-capable')
+})
+
+test('상수가 하나라도 섞이면 partial — 실측이 있어도 감추지 않는다', () => {
+  const r = classifySpecCoverage({
+    operations: [
+      { kind: 'putaway', duration: 'measured' },
+      { kind: 'pick', duration: 'default' }
+    ]
+  })
+  assert.equal(r!.qualification, 'partial')
+  assert.equal(r!.measuredDurations, 1)
+  assert.equal(r!.defaultDurations, 1)
+})

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

@@ -7,7 +7,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { bizStepOf, epcOf, orderOf, locationOf, moverOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.ts'
+import { bizStepOf, epcOf, orderOf, locationOf, equipmentIdOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.ts'
 
 /** EPCIS ObjectEvent 한 건(입고) — 실제 인제스트가 싣는 모양. */
 const EPCIS_OBJECT = {
@@ -70,7 +70,7 @@ test('없는 값은 빈 문자열이 아니라 undefined — 결측과 빈값을
 
 test('설비·무버 축 — 운영 델타의 moverId 를 뽑는다', () => {
   const ev = { eventType: 'equipment.status', data: { moverId: 'fork-3', status: 'down', location: 'rack-1' } }
-  assert.equal(moverOf(ev), 'fork-3')
+  assert.equal(equipmentIdOf(ev), 'fork-3')
   const k = twinEventKeys(ev)
   assert.equal(k.moverId, 'fork-3')
   /* 운영 델타는 readPoint/bizLocation 이 없다 — 평범한 location 을 위치로 받는다.