@things-factory/headless-twin 10.0.7 → 10.0.9

package/test/runtime-key.test.ts

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

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

@@ -1,7 +1,7 @@
 /*
  * 스케일 테스트 트윈 벤치 — 미국 공장(WMS+MES+YMS) 형태를 대규모로 스케일업, 5종 동기 엔티티 전부 부하.
  * 동기 엔티티 = locations·items(재고)·equipment·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
- * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송)·heap.
+ * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송, 't1')·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
 import { test } from 'node:test'
@@ -89,7 +89,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
 
     // 4) 방송 payload(buildEntityDeltas)
     t = performance.now()
-    for (let k = 0; k < iters; k++) buildEntityDeltas(s)
+    for (let k = 0; k < iters; k++) buildEntityDeltas(s, 't1')
     const tDelta = (performance.now() - t) / iters
     console.log(`  [${name}] buildEntityDeltas: ${tDelta.toFixed(2)}ms/call`)
     console.log(`  [${name}] heap: ${MB(process.memoryUsage().heapUsed)}MB`)

package/test/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

@@ -48,7 +48,7 @@ test('★ 캡스톤: master → masterToTwin → 커널 로드 → tick → 라
 
   // 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 에 도달(커널→보드 결합 성립)
@@ -70,7 +70,7 @@ test('캡스톤: 결정성 — 같은 board+tick 은 같은 payload 시그니처
     kernel.loadBoard(board)
     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

@@ -89,7 +89,8 @@ 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 () => {
@@ -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 board = (): 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', board())
+  await TwinEngine.provision(beta, SHARED_ID, 'wms', board())
+})
+
+/**
+ * **스펙마다 반드시 멈춘다.** 남기면 두 가지가 따라온다: 틱 타이머 때문에 러너가 끝나지 않고, 틱이
+ * 뒤늦게 던지는 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/warm-start-seam.test.ts

@@ -0,0 +1,140 @@
+/*
+ * ★ 웜스타트 이음매 검증 — 판정이 만든 씨앗이 **실제 커널에 심기는지**.
+ *
+ * ── 왜 따로 있나 ────────────────────────────────────────────────────────────
+ * `warm-start.test.ts` 는 순수 판정만 본다("무엇을 씨앗에 담기로 했나"). 그것만으로는 부족했다:
+ * 재기동 후 주문이 사라진 결함은 판정과 커널 **사이**에 있었기 때문이다. 판정은 오더를 버렸고,
+ * 커널은 받을 준비가 되어 있었다. 양쪽 테스트가 각각 초록이어도 이음매는 끊겨 있었다.
+ *
+ * 특히 이 테스트가 겨누는 것은 **`snap.orders` 경로**다. 커널은 오더를 두 가지로 받는다 —
+ * 두 번째 인자(`OrderStatusDelta[]`)와 스냅샷 안(`snap.orders`). 커널 테스트는 두 번째 인자를
+ * 쓰고, 호스트 웜스타트는 스냅샷 안을 쓴다. 즉 **호스트가 의존하는 쪽이 검증되지 않은 상태**였다.
+ *
+ * ── 무엇을 단언하나 ────────────────────────────────────────────────────────
+ * 스냅샷의 오더가 남은 데맨드(requested − fulfilled)로 커널에 서고, 이행이 끝난 오더는 서지 않고,
+ * 원값이 없는 오더는 조용히 서지 않는다는 것. 숫자를 지어내지 않는다는 규칙이 이음매 끝까지 지켜지는가.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { WmsKernel } from '@operato/twin-kernel'
+
+import { planWarmStart } from '../server/engine/warm-start.ts'
+import { withLiveAttentions } from '../server/engine/live-attentions.ts'
+
+const GTIN = 'urn:epc:idpat:sgtin:0614141.012345.*'
+
+/*
+ * 보드 — WMS 출고 흐름(피킹 → 스테이징 → 출하)이 실제로 굴러갈 최소 구성.
+ * `staging` 을 빼고 짜 봤더니 오더가 서기만 하고 진행이 0 이었다. 이음매가 아니라 픽스처 문제였다 —
+ * 이 테스트가 흐름 요건까지 시험하려는 것이 아니므로 커널 테스트와 같은 네 자리를 쓴다.
+ */
+const board = () => ({
+  locations: [
+    { id: 'dock-recv', type: 'dock', capacity: 100 },
+    { id: 'bin-1', type: 'storage', capacity: 200 },
+    { id: 'staging', type: 'staging', capacity: 100 },
+    { id: 'dock-ship', type: 'dock-ship', capacity: 100 }
+  ],
+  equipment: [
+    { id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv' },
+    { id: 'fk-2', kind: 'forklift', homeLocation: 'dock-recv' }
+  ]
+})
+
+/** 관측 스냅샷 흉내가 아니라, 스냅샷이 실제로 들고 오는 모양(일곱 축 중 필요한 것). */
+const observed = (orders: unknown[]) => ({
+  locations: board().locations.map(n => ({ ...n, occupancy: 0, status: 'idle' })),
+  items: Array.from({ length: 20 }, (_, i) => ({
+    epc: `urn:epc:id:sgtin:0614141.012345.${i}`,
+    location: 'bin-1',
+    gtin: GTIN,
+    qty: 1
+  })),
+  equipment: board().equipment.map(m => ({ ...m, location: 'dock-recv', status: 'idle' })),
+  tasks: [],
+  orders
+})
+
+/** 판정 → 주입. 호스트 `warmStart` 가 하는 일과 같은 순서로 잇는다. */
+function seedKernel(state: ReturnType<typeof observed>) {
+  const plan = planWarmStart(state, undefined, true)
+  assert.equal(plan.action, 'hydrate', '심기로 판정해야 한다')
+  if (plan.action !== 'hydrate') throw new Error('unreachable')
+  const k = new WmsKernel('t')
+  k.loadBoard(board() as any)
+  ;(k as any).hydrateObserved(plan.seed)
+  return { k, plan }
+}
+
+test('스냅샷 안의 오더가 커널에 선다 — 남은 데맨드로', () => {
+  const { k, plan } = seedKernel(
+    observed([{ id: 'SO-1', kind: 'outbound', status: 'in-progress', requested: 20, fulfilled: 5, lines: [{ gtin: GTIN, requested: 20, fulfilled: 5 }] }])
+  )
+  assert.equal(plan.orderCount, 1)
+  const o = (k as any).orders.get('SO-1')
+  assert.ok(o, '재기동 후 진행 중 주문이 커널에 있어야 한다 — 사라지던 결함의 회귀 방지')
+  assert.equal(o.requested, 15, '남은 데맨드 15(20−5)로 서야 한다 — 원값이 아니라 남은 양이다')
+})
+
+test('재고가 있으면 복원된 오더가 실제로 이행된다 — 서 있기만 하면 의미가 없다', () => {
+  const { k } = seedKernel(
+    observed([{ id: 'SO-1', kind: 'outbound', status: 'in-progress', requested: 8, fulfilled: 0, lines: [{ gtin: GTIN, requested: 8, fulfilled: 0 }] }])
+  )
+  const fc = (k as any).fork()
+  for (let t = 0; t < 1200; t++) fc.tick(1000)
+  const o = fc.getSnapshot().orders.find((x: any) => x.id === 'SO-1')
+  assert.ok(o, '예측에도 오더가 있어야 한다')
+  assert.ok(o.progress > 0, `복원된 오더가 진행돼야 한다(progress=${o.progress})`)
+})
+
+test('이미 이행된 오더는 서지 않는다 — 다 끝난 일을 다시 계획하지 않는다', () => {
+  const { k, plan } = seedKernel(
+    observed([{ id: 'SO-DONE', kind: 'outbound', status: 'completed', requested: 10, fulfilled: 10, lines: [{ gtin: GTIN, requested: 10, fulfilled: 10 }] }])
+  )
+  assert.equal(plan.orderCount, 1, '판정은 원값이 있으므로 넘긴다')
+  assert.equal((k as any).orders.get('SO-DONE'), undefined, '커널이 남은 양 0 으로 보고 세우지 않는다')
+})
+
+test('원값이 없는 오더는 커널에 서지 않고, 몇 건인지 남는다', () => {
+  const state = observed([{ id: 'SO-P', kind: 'outbound', status: 'in-progress', progress: 0.5 }])
+  const plan = planWarmStart(state, undefined, true)
+  assert.equal(plan.action, 'hydrate')
+  if (plan.action !== 'hydrate') return
+  assert.equal(plan.orderCount, 0)
+  assert.equal(plan.ordersWithoutDemand, 1, '뺀 사실이 숫자로 남아야 로그가 말할 수 있다')
+
+  const k = new WmsKernel('t')
+  k.loadBoard(board() as any)
+  ;(k as any).hydrateObserved(plan.seed)
+  assert.equal((k as any).orders.size, 0, 'progress 만으로는 남은 양을 알 수 없으므로 지어내지 않는다')
+})
+
+test('재고도 함께 살아난다 — 오더를 넣다가 기존 복원을 깨지 않았는지', () => {
+  const { k } = seedKernel(observed([{ id: 'SO-1', requested: 5, fulfilled: 0, kind: 'outbound', status: 'in-progress' }]))
+  const snap = (k as any).getSnapshot()
+  assert.equal(snap.items.length, 20, '재고 20건이 그대로 복원돼야 한다')
+  assert.equal(snap.equipment.length, 2)
+})
+
+test('라이브 상태의 확인 처리가 신호에 반영된다 — 라이브에서는 아예 안 먹던 것', () => {
+  /*
+   * `withLiveAttentions` 가 확인 목록을 넘기지 않아, 라이브(미러)에서는 사람이 확인해도 신호가
+   * 계속 활성으로 나갔다. 저널에서 되살린 확인 처리가 여기까지 닿는지 본다.
+   */
+  const state = {
+    locations: [{ id: 'bin-tight', type: 'storage', capacity: 1, occupancy: 1 }],
+    equipment: [],
+    orders: [],
+    tasks: [],
+    acked: [] as string[]
+  }
+  const before = withLiveAttentions(state).attentions ?? []
+  const signal = before[0]
+  assert.ok(signal, '픽스처 전제 — 병목 신호가 서야 한다')
+  /* 확인 전에는 `state` 를 채우지 않는다(확인된 것만 표시한다) — 없음과 'acknowledged' 를 가른다. */
+  assert.notEqual(signal.state, 'acknowledged', '확인하지 않았는데 확인된 것으로 나오면 안 된다')
+
+  const after = withLiveAttentions({ ...state, acked: [signal.id] }).attentions ?? []
+  assert.equal(after.find((a: any) => a.id === signal.id)?.state, 'acknowledged', '확인 처리가 라이브 신호에 반영돼야 한다')
+})