@things-factory/headless-twin 10.0.9 → 10.0.10

package/test/event-time-column.test.ts

@@ -0,0 +1,67 @@
+/*
+ * eventTime 이 **날짜 컬럼**이라는 사실을 지킨다.
+ *
+ * ── 왜 있나 (2026-08-08) ────────────────────────────────────────────────────
+ * 예전에는 문자열 컬럼이었고, "UTC ISO 만 들어오니 사전식 비교가 맞는다" 는 전제 위에서 정렬·범위
+ * 질의가 돌았다. 그 전제는 컬럼 어디에도 적혀 있지 않았다.
+ *
+ * 날짜 컬럼으로 바꾸면서 **조용한 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
+ * (`2026-08-07 11:00:00.000`)으로 저장하는데, 화면은 ISO 문자열(`…T11:00:00.000Z`)을 보낸다.
+ * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 조용히
+ * 비어 버리고, 사용자는 "그 시간에 아무 일도 없었다" 로 읽는다.
+ *
+ * 그래서 두 가지를 못 박는다: 저장 형식이 실제로 그렇다는 것과, 경계에서 날짜로 옮기면 걸린다는 것.
+ * 이 검사가 깨지면 typeorm/드라이버의 거동이 바뀐 것이므로 변환 지점을 다시 봐야 한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { DataSource, EntitySchema, Between } = req('typeorm')
+
+const Ev = new EntitySchema({
+  name: 'ev',
+  tableName: 'ev',
+  columns: {
+    id: { primary: true, type: 'int', generated: true },
+    eventTime: { type: 'datetime', nullable: true }
+  }
+})
+
+async function seeded() {
+  const ds = new DataSource({ type: 'sqlite', database: ':memory:', entities: [Ev], synchronize: true })
+  await ds.initialize()
+  const repo = ds.getRepository('ev')
+  await repo.save([
+    { eventTime: new Date('2026-08-07T11:00:00.000Z') },
+    { eventTime: new Date('2026-08-07T13:00:00.000Z') }
+  ])
+  return { ds, repo }
+}
+
+test('sqlite 는 datetime 을 공백 구분 형식으로 저장한다 — ISO 문자열과 사전식으로 어긋난다', async () => {
+  const { ds } = await seeded()
+  const raw = await ds.query('select eventTime from ev order by id')
+  assert.match(raw[0].eventTime, /^\d{4}-\d{2}-\d{2} /, '공백 구분이 아니면 이 검사의 전제가 바뀐 것이다')
+  assert.ok(!String(raw[0].eventTime).includes('T'), 'T 가 들어가면 ISO 와 같은 형식이므로 함정이 사라진 것이다')
+  await ds.destroy()
+})
+
+test('ISO 문자열을 그대로 넘기면 **조용히 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
+  const { ds, repo } = await seeded()
+  const rows = await repo.find({
+    where: { eventTime: Between('2026-08-07T10:00:00.000Z', '2026-08-07T12:00:00.000Z') }
+  })
+  assert.equal(rows.length, 0, '이 검사가 깨졌다면 드라이버가 문자열을 받아 주게 된 것 — 변환 지점을 재검토할 것')
+  await ds.destroy()
+})
+
+test('경계에서 날짜로 옮기면 제대로 걸린다 — 질의 전에 반드시 변환한다', async () => {
+  const { ds, repo } = await seeded()
+  const rows = await repo.find({
+    where: { eventTime: Between(new Date('2026-08-07T10:00:00.000Z'), new Date('2026-08-07T12:00:00.000Z')) }
+  })
+  assert.equal(rows.length, 1)
+  await ds.destroy()
+})

package/test/forecast-metrics.test.ts

@@ -0,0 +1,71 @@
+/*
+ * 예측 지표 — **스냅샷에서 무엇을 세는가.**
+ *
+ * 여기서 틀리면 예측 그래프가 조용히 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
+ * 「없음」과 「0」이 같은 그림이 되기 쉬워서, 그 경계를 명시로 잡아 둔다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { FORECAST_METRICS, metricsForKind } from '../dist-server/service/twin-forecast/forecast-metrics.js'
+
+test('물류 지표 — 기존 여섯은 그대로 센다', () => {
+  const s = {
+    items: [1, 2, 3],
+    locations: [{ occupancy: 2 }, { occupancy: 5 }],
+    tasks: [{}, {}],
+    orders: [{ status: 'shipped' }, { status: 'picking' }, { status: 'cancelled' }]
+  }
+  assert.equal(FORECAST_METRICS.items(s), 3)
+  assert.equal(FORECAST_METRICS.occupancy(s), 7)
+  assert.equal(FORECAST_METRICS.tasks(s), 2)
+  assert.equal(FORECAST_METRICS.orders(s), 3)
+  assert.equal(FORECAST_METRICS.shipped(s), 1)
+  /* 취소는 백로그가 아니다 — 대기와 취소를 같이 세면 「안 빠지는 일감」이 부풀려진다. */
+  assert.equal(FORECAST_METRICS.backlog(s), 1)
+})
+
+test('에너지 지표 — 커널이 낸 값을 그대로 읽는다(다시 계산하지 않는다)', () => {
+  const s = {
+    energy: {
+      peakSince: { kW: 812 },
+      open: { meanKW: 300, projectedKW: 455, projectionBasis: 'mean-so-far' },
+      closed: [{ overContract: true }, { overContract: false }, { overContract: true }]
+    }
+  }
+  assert.equal(FORECAST_METRICS.peakKW(s), 812)
+  assert.equal(FORECAST_METRICS.projectedKW(s), 455)
+  assert.equal(FORECAST_METRICS.overWindows(s), 2)
+})
+
+test('투영이 아직 없으면 지금까지의 평균으로 — 0 으로 떨어뜨리지 않는다', () => {
+  assert.equal(FORECAST_METRICS.projectedKW({ energy: { open: { meanKW: 120 } } }), 120)
+})
+
+test('에너지가 없는 스냅샷 — 세 지표 모두 0(그리지 않을 값이지, 관측한 0 이 아니다)', () => {
+  assert.equal(FORECAST_METRICS.peakKW({ items: [] }), 0)
+  assert.equal(FORECAST_METRICS.projectedKW({ items: [] }), 0)
+  assert.equal(FORECAST_METRICS.overWindows({ items: [] }), 0)
+})
+
+test('계약을 모르면 초과 구간은 0 — overContract 가 없는 구간을 초과로 세지 않는다', () => {
+  const s = { energy: { closed: [{ maxKW: 900 }, { maxKW: 1200 }] } }
+  assert.equal(FORECAST_METRICS.overWindows(s), 0)
+})
+
+test('종류별 지표 목록 — 에너지 트윈에는 물류 지표가 섞이지 않는다', () => {
+  const ems = metricsForKind('ems')
+  assert.deepEqual(ems, ['projectedKW', 'peakKW', 'overWindows'])
+  assert.equal(ems.includes('items' as any), false)
+  assert.equal(metricsForKind('wms').includes('items'), true)
+  /* 종류를 모르면 물류로 — 기존 트윈(kind 미선언)이 지표를 잃지 않는다. */
+  assert.equal(metricsForKind(undefined).includes('items'), true)
+})
+
+test('목록의 모든 키가 실제로 계산 가능하다 — 화면에 뜨는데 서버가 모르는 지표는 없다', () => {
+  for (const kind of ['ems', 'wms', 'mes', 'yms']) {
+    for (const key of metricsForKind(kind)) {
+      assert.equal(typeof (FORECAST_METRICS as any)[key], 'function', `${kind}:${key}`)
+    }
+  }
+})

package/test/forecast-tuning.test.ts

@@ -0,0 +1,42 @@
+/*
+ * 예측 틱 크기 — **지평선이 정하고, 양끝은 묶인다.**
+ *
+ * 이 규칙이 틀리면 예측이 조용히 비싸지거나(1초 고정 시절 9,000틱·28.5초) 조용히 성글어진다
+ * (짧은 작업이 한 틱에 삼켜진다). 둘 다 화면에는 그럴듯한 숫자로 나오므로 시험이 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { forecastStepMs, TARGET_TICKS_PER_RUN, MAX_STEP_MS, MIN_STEP_MS } from '../dist-server/service/twin-forecast/forecast-tuning.js'
+
+test('기본 지평선(5분)은 5초 단위 — 실측으로 1초와 답이 같고 5배 싸다', () => {
+  assert.equal(forecastStepMs(300_000), 5_000)
+})
+
+test('짧은 지평선은 더 잘게 — 1분이면 1초', () => {
+  assert.equal(forecastStepMs(60_000), 1_000)
+})
+
+test('아주 짧아도 커널 시각 단위 아래로 내려가지 않는다', () => {
+  assert.equal(forecastStepMs(5_000), MIN_STEP_MS)
+  assert.equal(forecastStepMs(0), MIN_STEP_MS)
+  assert.equal(forecastStepMs(Number.NaN), MIN_STEP_MS)
+})
+
+test('아무리 길어도 상한을 넘지 않는다 — 짧은 작업이 한 틱에 삼켜진다', () => {
+  assert.equal(forecastStepMs(2 * 60 * 60_000), MAX_STEP_MS)
+  assert.equal(forecastStepMs(24 * 60 * 60_000), MAX_STEP_MS)
+})
+
+test('틱 크기는 초 단위로 떨어진다 — 3,333ms 는 사람도 화면도 설명할 수 없다', () => {
+  for (const h of [100_000, 200_000, 333_000, 777_000]) {
+    assert.equal(forecastStepMs(h) % 1000, 0, `${h}ms`)
+  }
+})
+
+test('상한에 걸리지 않는 구간에서는 목표 틱 수 근처로 돈다', () => {
+  for (const h of [60_000, 120_000, 300_000, 600_000]) {
+    const ticks = h / forecastStepMs(h)
+    assert.ok(ticks >= TARGET_TICKS_PER_RUN * 0.8 && ticks <= TARGET_TICKS_PER_RUN * 1.25, `${h}ms → ${ticks}틱`)
+  }
+})

package/test/gap-analytics.test.ts

@@ -52,11 +52,38 @@ test('learnedCalibration — biasShift=평균오차, 편향 제거로 정확도
   assert.equal(learn.accAfter, 100, '일정 편향을 완전 제거 → 잔차 0 → 100%')
 })
 
-test('aggregatePoints — 공동배치 인덱스별 합산(공장 총량)', () => {
-  const a = [pt(2, 30), pt(4, 30)]
-  const b = [pt(1, 20), pt(2, 20)]
-  const agg = aggregatePoints([a, b])
-  assert.equal(agg.length, 2)
-  assert.equal(agg[0].actual, 50, '실제 30+20')
-  assert.equal(agg[0].error, agg[0].actual - agg[0].p50, 'error = 실제−예측(합산 후 재계산)')
+/* 같은 격자 위의 점 — vantage 를 명시한다(예전 헬퍼는 t 를 늘 0 으로 두어 시간축을 전혀 시험하지 않았다). */
+const at = (t: number, error: number, actual = 100) => ({ ...pt(error, actual), t })
+
+test('aggregatePoints — 공동배치 합산(공장 총량)', () => {
+  const a = [at(10, 2, 30), at(20, 4, 30)]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a, b])
+  assert.equal(points.length, 2)
+  assert.equal(droppedVantages, 0)
+  assert.equal(points[0].actual, 50, '실제 30+20')
+  assert.equal(points[0].t, 10, '합산점의 시각은 그 vantage 다')
+  assert.equal(points[0].error, points[0].actual - points[0].p50, 'error = 실제−예측(합산 후 재계산)')
+})
+
+test('한 트윈이 못 잰 vantage 는 통째로 뺀다 — 빠진 트윈을 0 으로 세지 않는다', () => {
+  /*
+   * 예전에는 `max` 길이로 돌며 있는 것만 더했다. 그래서 이 경우 t=20 의 공장 총량이 20(b 뿐)으로
+   * 나왔다 — a 가 그 시각에 아무것도 안 했다는 뜻이 아니라, **못 쟀다**는 뜻인데도.
+   * 공장 합계 곡선이 꼬리에서 아래로 꺾이고, 그 곡선으로 예측 정확도를 판정했다.
+   */
+  const a = [at(10, 2, 30), null]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a as any, b])
+  assert.equal(points.length, 1, '모두가 값을 가진 vantage 만 남는다')
+  assert.equal(points[0].t, 10)
+  assert.equal(droppedVantages, 1, '뺀 개수를 돌려줘야 화면이 "2점 중 1점" 이라고 말할 수 있다')
+})
+
+test('길이가 다르면 뒤쪽은 뺀다 — 남은 트윈만의 합을 공장 총량이라 부르지 않는다', () => {
+  const a = [at(10, 2, 30)]
+  const b = [at(10, 1, 20), at(20, 2, 20)]
+  const { points, droppedVantages } = aggregatePoints([a, b])
+  assert.equal(points.length, 1)
+  assert.equal(droppedVantages, 1)
 })

package/test/ingest-bench.test.ts

@@ -8,10 +8,10 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { StateProjector, objectEvent, BIZSTEP, DISP } from '@operato/twin-kernel'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const T0 = '2026-07-19T00:00:00.000Z'
-const board = (nNodes: number) => ({
+const model = (nNodes: number) => ({
   locations: Array.from({ length: nNodes }, (_, i) => ({ id: `bin-${i}`, type: 'storage', capacity: 100000 })),
   equipment: []
 })
@@ -23,7 +23,7 @@ function envelope(epc: string, location: string): any {
 test('bench: apply 처리량(이벤트 흡수)', () => {
   const nNodes = 200
   const M = 200_000
-  const proj = new StateProjector(board(nNodes))
+  const proj = new StateProjector(model(nNodes))
   const t0 = performance.now()
   for (let i = 0; i < M; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % nNodes}`))
   const dt = performance.now() - t0
@@ -33,7 +33,7 @@ test('bench: apply 처리량(이벤트 흡수)', () => {
 
 test('bench: snapshot 비용 vs item 수 (전체 O(N) 재구성)', () => {
   for (const N of [1000, 10000, 50000]) {
-    const proj = new StateProjector(board(200))
+    const proj = new StateProjector(model(200))
     for (let i = 0; i < N; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % 200}`))
     const iters = 200
     const t0 = performance.now()
@@ -45,7 +45,7 @@ test('bench: snapshot 비용 vs item 수 (전체 O(N) 재구성)', () => {
 
 test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방출)', () => {
   for (const N of [100, 1000, 5000]) {
-    const proj = new StateProjector(board(N))
+    const proj = new StateProjector(model(N))
     for (let i = 0; i < N * 5; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % N}`))
     const snap = proj.snapshot()
     const iters = 200
@@ -58,7 +58,7 @@ test('bench: buildEntityDeltas 비용 vs 엔티티 수 (전 엔티티 매번 방
 
 test('bench: 방송 1회 총비용(snapshot + buildEntityDeltas) vs 상태 규모', () => {
   for (const [locations, items] of [[200, 5000], [1000, 50000], [2000, 100000]]) {
-    const proj = new StateProjector(board(locations))
+    const proj = new StateProjector(model(locations))
     for (let i = 0; i < items; i++) proj.apply(envelope(`urn:epc:id:sscc:0614141.${i}`, `bin-${i % locations}`))
     const iters = 100
     const t0 = performance.now()

package/test/ingest-running-guard.test.ts

@@ -0,0 +1,136 @@
+/*
+ * ★ 가동 중 인제스트 — **거절할 것이면 아무것도 쓰기 전에 거절한다.**
+ *
+ * 가동 중 재프로비저닝은 `provision` 이 막는다. 그런데 그 호출은 `ingestMaster` 의 **맨 끝**이었고,
+ * 그때까지 공간·표현·구역(TwinArea)은 이미 저장된 뒤였다. 사용자 화면에는 "인제스트 실패" 가
+ * 뜨는데 실제로는 절반이 적용된 상태다 — **실패라고 말하면서 데이터를 바꾸는 것**이 가장 나쁘다.
+ *
+ * 이 검사는 그 경계 하나를 지킨다: 거절된 인제스트는 **흔적을 남기지 않는다.**
+ *
+ * 순수 함수로는 확인되지 않는다. 부분 쓰기는 정의상 "여러 표에 걸쳐 무엇이 남았나" 이므로 실
+ * DataSource 가 있어야 한다(멀티DB 규약상 sqlite 가 5개 드라이버 공통의 최소선이다).
+ *
+ * 이 제약 자체는 최종형이 아니다 — 커널에는 가동 중 구조 교체(`adoptStructure`)가 이미 있고
+ * 재생은 리비전 경계마다 그것을 쓴다. 라이브에 배선되면 이 거절은 사라지고 이 검사도 함께 간다.
+ */
+import { test, before, after } 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 { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { TwinStructure } = req('../dist-server/service/twin-structure/twin-structure.js')
+const { TwinArea } = req('../dist-server/service/twin-space/twin-area.js')
+const { TwinSpace } = req('../dist-server/service/twin-space/twin-space.js')
+const { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'guard-probe'
+
+/** WMS 마스터 — `bins` 로 규모를, `siteName`·구역 이름으로 "무엇이 바뀌려 했나" 를 다이얼한다. */
+const master = (bins: number, siteName: string, areaName: string): any => ({
+  source: INSTANCE,
+  system: 'wms',
+  siteName,
+  space: { width: 60, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'a-dc', type: 'warehouse', role: 'area', name: areaName },
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    ...Array.from({ length: bins }, (_, i) => ({
+      id: `bin-${i + 1}`,
+      type: 'storage',
+      role: 'location',
+      name: `빈${i + 1}`,
+      parentId: 'a-dc',
+      capacity: 20
+    }))
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }]
+})
+
+/** 지금 DB 에 남아 있는 모든 흔적 — 인제스트가 건드리는 표를 한 줌으로 뜬다. */
+async function trace() {
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: INSTANCE } })
+  const space = await ds.getRepository(TwinSpace).findOne({ where: { spaceId: `${INSTANCE}-site` } })
+  const areas = await ds.getRepository(TwinArea).find({ order: { areaId: 'ASC' } })
+  const revs = await ds.getRepository(TwinStructure).find({ order: { rev: 'ASC' } })
+  return {
+    boardLocations: (inst?.model?.locations ?? []).length,
+    spaceName: space?.name,
+    areaNames: areas.map((a: any) => a.name),
+    revs: revs.map((r: any) => r.rev),
+    rows: await ds.getRepository(TwinLocation).count()
+  }
+}
+
+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: 'guard-test', subdomain: 'guard-test' } as any)
+  domainId = d.id
+
+  await TwinEngine.ingestMaster(domainId, master(3, '서울 창고', '보관 구역'))
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('멈춰 있으면 재인제스트가 통한다 — 막는 것은 가동 중일 때뿐이다', async () => {
+  await TwinEngine.ingestMaster(domainId, master(5, '서울 창고', '보관 구역'))
+  const t = await trace()
+  assert.equal(t.boardLocations, 6, '자리 6개(도크 1 + 빈 5)로 갱신된다')
+  assert.deepEqual(t.revs, [1, 2], '구조가 달라졌으니 리비전이 하나 늘어난다')
+  assert.equal(t.rows, 6, '표도 함께 다시 그려진다')
+})
+
+test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', async () => {
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-experiment')
+  const before = await trace()
+
+  /*
+   * 바뀔 것을 **일부러 전부** 흔든다. 구조(빈 5→9)뿐 아니라 공간 이름·구역 이름까지 —
+   * 부분 쓰기는 앞쪽(공간·구역)에서 일어났으므로, 구조만 확인하면 예전 결함을 못 잡는다.
+   */
+  await assert.rejects(
+    () => TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역')),
+    /is running/,
+    '가동 중에는 거절해야 한다'
+  )
+
+  assert.deepEqual(await trace(), before, '거절된 인제스트는 어느 표에도 흔적을 남기지 않는다')
+})
+
+test('멈추면 다시 통한다 — 거절은 잠금이 아니라 순서다', async () => {
+  await TwinEngine.stop(domainId, INSTANCE)
+  await TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'))
+
+  const t = await trace()
+  assert.equal(t.boardLocations, 10, '아까 거절당한 그 구조가 이제 들어간다')
+  assert.deepEqual(t.revs, [1, 2, 3])
+  assert.equal(t.rows, 10)
+  /*
+   * 공간 이름은 **안 바뀐다** — 이미 있는 공간의 이름은 인제스트가 덮지 않는다(공유 공간에서
+   * 먼저 쓴 값이 이긴다). 거절 검사가 "안 바뀌었다" 를 확인할 때 이 성질에 기대지 않도록,
+   * 여기서 그것이 별개의 규칙임을 못 박아 둔다.
+   */
+  assert.equal(t.spaceName, '서울 창고', '기존 공간 이름은 재인제스트가 덮지 않는다(별개 규칙)')
+})

package/test/ingest-space.test.ts

@@ -7,7 +7,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { resolveIngestSpace, collidingIds, INGEST_SPACE_NOT_FOUND } from '../server/service/reference/ingest-space.ts'
+import { resolveIngestSpace, refuseImportSpace, collidingIds, INGEST_SPACE_NOT_FOUND } from '../server/service/reference/ingest-space.ts'
 
 test('고르지 않으면 마스터가 파생한 공간으로 — 지금까지의 거동을 바꾸지 않는다', () => {
   for (const req of [undefined, null, '', '   ']) {
@@ -48,3 +48,31 @@ test('같은 id 를 쓰는 것들을 찾아낸다 — 합쳐지는 것을 모르
   assert.deepEqual(collidingIds(undefined, undefined), [], '없는 쪽은 빈 것으로 본다')
   assert.deepEqual(collidingIds([{}, { id: '' }], [{ id: '' }]), [], 'id 없는 항목은 세지 않는다')
 })
+
+/* ── 실 시스템 import 의 현장 선택 (2026-08-13) ───────────────────────────── */
+
+test('현장을 고르지 않으면 사이트가 몇이든 진행한다 — 지금까지의 거동', () => {
+  for (const n of [0, 1, 5, 40]) {
+    assert.equal(refuseImportSpace(n, undefined), undefined)
+    assert.equal(refuseImportSpace(n, ''), undefined)
+  }
+})
+
+test('사이트 하나면 그 현장에 넣는다 — 렌즈를 더하는 정상 경로', () => {
+  assert.equal(refuseImportSpace(1, 'rosarito-site'), undefined)
+})
+
+test('사이트 여럿을 한 현장에 넣는 것은 거절한다 — 서로 다른 현장이 조용히 합쳐진다', () => {
+  const r = refuseImportSpace(3, 'rosarito-site')
+  assert.ok(r, '거절해야 한다')
+  assert.equal(r.code, 'space-with-multiple-sites')
+  assert.equal(r.params?.count, 3)
+  assert.equal(r.params?.spaceId, 'rosarito-site')
+  assert.match(r.message, /pick one site/)
+})
+
+test('거절 사유는 코드로 낸다 — 화면이 다섯 언어로 번역할 수 있게', () => {
+  const r = refuseImportSpace(2, '  rosarito-site  ')
+  assert.equal(r?.code, 'space-with-multiple-sites')
+  assert.equal(r?.params?.spaceId, 'rosarito-site', '앞뒤 공백은 다듬어 낸다')
+})

package/test/instance-cache-lifecycle.test.ts

@@ -0,0 +1,110 @@
+/*
+ * ★ 인스턴스별 캐시는 **트윈과 함께 사라진다.**
+ *
+ * ── 왜 이 검사가 필요한가 ─────────────────────────────────────────────────────
+ * 엔진은 트윈마다 메모리에 몇 가지를 들고 있다(실측 추정기·구조 리비전·복구 표식). 지움은 저널과
+ * 등록부까지 갔는데 **캐시는 남았다** — 삭제된 트윈의 항목이 서버 재기동까지 살아 있었다. 항목 하나가
+ * 하루치 KPI 그룹을 물고 있으므로, 트윈을 만들고 지우는 일이 반복되는 현장에서는 그것이 곧 누수다.
+ *
+ * TTL 은 이것을 막지 못한다: TTL 은 **값이 낡는 것**을 막을 뿐 **없어진 주인**을 지우지 않는다.
+ *
+ * 그래서 규율은 둘이다.
+ *  ① 트윈이 사라지면 그 트윈에 대한 메모리를 **전부** 잊는다(정확한 쪽).
+ *  ② 우리 API 를 지나지 않고 사라지는 길(도메인째 삭제·DB 직접 조작)에는 **상한**이 막는다(방어).
+ *
+ * 사설(private) 필드를 들여다보는 검사인 것을 안다. 그런데 여기서 지켜야 하는 것은 겉으로 드러나는
+ * 값이 아니라 **메모리가 자라지 않는다**는 사실이고, 그것은 안을 봐야 볼 수 있다.
+ */
+import { test, before, after } 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 domainId: string
+
+const INSTANCE = 'cache-probe'
+
+const master = (): any => ({
+  source: INSTANCE,
+  system: 'wms',
+  siteName: '캐시 창고',
+  space: { spaceId: 'cache-site', width: 40, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'dock', type: 'dock', role: 'location', name: '도크', capacity: 50 },
+    { id: 'bin-1', type: 'storage', role: 'location', name: '빈1', capacity: 20 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
+})
+
+/** 캐시 안을 본다 — 겉으로는 안 보이는 사실을 지키는 검사이므로. */
+const caches = () => ({
+  measured: (TwinEngine as any).measuredCache as Map<string, unknown>,
+  structureRev: (TwinEngine as any).structureRevCache as Record<string, number>,
+  recovered: (TwinEngine as any).recovered as Record<string, unknown>
+})
+const keyOf = (id: string) => `${domainId}:${id}`
+
+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: 'cache-test', subdomain: 'cache-test' } as any)
+  domainId = d.id
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('지운 트윈의 캐시는 남지 않는다 — TTL 은 없어진 주인을 지우지 않는다', async () => {
+  await TwinEngine.ingestMaster(domainId, master())
+  /* 캐시를 실제로 채운다 — 손으로 넣으면 "채우는 경로" 가 바뀌어도 검사가 통과한다. */
+  await TwinEngine.structureRevOf(domainId, INSTANCE)
+  const { measured, structureRev } = caches()
+  assert.ok(keyOf(INSTANCE) in structureRev, '구조 리비전이 캐시에 올라와야 이 검사가 뜻이 있다')
+
+  await TwinEngine.remove(domainId, INSTANCE)
+
+  const after = caches()
+  assert.equal(keyOf(INSTANCE) in after.structureRev, false, '지운 트윈의 구조 리비전이 남았다')
+  assert.equal(after.measured.has(keyOf(INSTANCE)), false, '지운 트윈의 실측 캐시가 남았다')
+  assert.equal(keyOf(INSTANCE) in after.recovered, false, '지운 트윈의 복구 표식이 남았다')
+  assert.equal(measured, after.measured, '캐시 객체를 갈아치우는 것이 아니라 항목을 지운다')
+})
+
+test('상한을 넘으면 가장 오래 손대지 않은 것부터 버린다 — 주인 없이 사라진 트윈까지 막는다', async () => {
+  const { measured } = caches()
+  measured.clear()
+  const MAX = (TwinEngine as any).MEASURED_MAX as number
+  assert.ok(MAX > 0, '상한이 선언되어 있어야 방어가 성립한다')
+
+  /*
+   * 상한 + 2 개를 넣고, 넣는 경로(`measuredEstimator`)를 그대로 쓴다. 트윈이 등록되어 있지 않으면
+   * KPI 조회가 빈 값을 내고 캐시에는 `undefined` 가 들어간다 — **그 자체도 캐시할 값이다**(없다는
+   * 사실을 알고 있는 것과 매번 다시 묻는 것은 다르다).
+   */
+  const call = (TwinEngine as any).measuredEstimator.bind(TwinEngine)
+  for (let i = 0; i < MAX + 2; i++) await call(domainId, `ghost-${i}`)
+
+  assert.ok(measured.size <= MAX, `상한을 넘어 자랐다(${measured.size} > ${MAX})`)
+  assert.equal(measured.has(`${domainId}:ghost-0`), false, '가장 오래된 항목이 남아 있다 — 버릴 순서가 어긋났다')
+  assert.ok(measured.has(`${domainId}:ghost-${MAX + 1}`), '가장 최근 항목은 남아야 한다')
+  measured.clear()
+})

package/test/kernel-kind-guard.test.ts

@@ -0,0 +1,96 @@
+/*
+ * 커널 선택 가드 — **모르는 종류로는 뜨지 않는다.**
+ *
+ * ── 무엇이 있었나 (2026-08-08) ───────────────────────────────────────────────
+ * 커널을 고르는 자리 셋이 모두 이랬다:
+ *
+ *     const Kernel = KERNELS[reg.kind ?? 'wms'] ?? WmsKernel
+ *
+ * 폴백이 둘 겹쳐 있었다. ①은 컬럼이 비었을 때, ②는 표에 없는 값일 때. 그리고 `kind` 는
+ * 검증 없는 자유 문자열이다(`@Arg('kind') kind: string` — enum 도 화이트리스트도 없다).
+ * 그래서 오타 하나·대소문자 하나로 **야드/생산 트윈이 조용히 창고 커널로 돌았다.**
+ * 오류가 없으니 화면에는 트윈이 정상으로 보이고, 안에서 도는 규칙만 다른 도메인의 것이다.
+ * 예측 경로가 가장 나빴다 — 야드의 미래를 창고 규칙으로 굴려 놓고 숫자만 뜬다.
+ *
+ * ── 왜 검사로 남기나 ────────────────────────────────────────────────────────
+ * 자리를 고치는 것만으로는 부족하다. 커널 종류가 늘 때(다음은 TMS 든 무엇이든) 새 자리가
+ * 생기고, `?? WmsKernel` 은 "안전한 기본값" 처럼 보여서 다시 자란다. 실제로 세 자리에
+ * 똑같이 자라 있었다. 틀린 공장을 조용히 띄우는 것보다 뜨지 않는 편이 낫다.
+ *
+ * 이 검사가 막는 것은 **표를 밖에서 직접 색인하는 것**이다. 종류→커널 해소는 `kernelFor`
+ * 하나만 한다. 새 자리를 쓸 때 이 검사가 걸리면, 폴백을 붙이지 말고 `kernelFor` 를 부를 것.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENGINE = new URL('../server/engine/twin-engine.ts', import.meta.url).pathname
+const MUTATION = new URL('../server/service/twin-lifecycle/twin-lifecycle-mutation.ts', import.meta.url).pathname
+
+/*
+ * 종류 폴백은 **한 패키지에 갇혀 있지 않다.** 처음에 twin-engine 두 자리만 고쳤더니, 라이브 미러를
+ * 띄우는 호출자 넷(operato-twin 의 벤치·부하시험·프리셋 프로비저닝, headless 의 reference-live)이
+ * `det.kind ?? 'wms'` 로 **엔진이 던지기 전에 먼저 이기고** 있었다. 커넥터 spec 도 마찬가지였다.
+ * 그래서 두 패키지의 서버 코드를 함께 훑는다.
+ */
+const ROOTS = [new URL('../server', import.meta.url).pathname, new URL('../../operato-twin/server', import.meta.url).pathname]
+
+/**
+ * 코드만 본다 — 주석은 **과거를 설명하느라 옛 코드를 그대로 인용한다**(바로 위 머리말이 그렇다).
+ * 줄 단위로 `*`·`//` 만 걸러내면 여러 줄 주석의 둘째 줄부터 새어 나오므로 블록을 통째로 지운다.
+ */
+function codeOf(path: string): string[] {
+  return readFileSync(path, 'utf-8')
+    .replace(/\/\*[\s\S]*?\*\//g, '') // 블록 주석
+    .split('\n')
+    .map(l => l.replace(/\/\/.*$/, '')) // 줄 주석
+    .filter(l => l.trim())
+}
+
+test('커널 폴백이 없다 — 모르는 종류는 창고로 떨어지지 않는다', () => {
+  const offenders = codeOf(ENGINE).filter(l => /\?\?\s*WmsKernel|\|\|\s*WmsKernel/.test(l))
+  assert.deepEqual(offenders, [], '커널 선택에 폴백이 다시 생겼다 — kernelFor 로 던지게 할 것')
+})
+
+test('종류→커널 해소는 kernelFor 한 곳만 한다', () => {
+  /* 표를 직접 색인하는 줄. 정의부(`const KERNELS: Record…`)와 kernelFor 내부는 제외. */
+  const indexing = codeOf(ENGINE).filter(l => /KERNELS\[/.test(l) && !/const K = KERNELS\[kind\]/.test(l))
+  assert.deepEqual(indexing, [], 'KERNELS 를 밖에서 색인하고 있다 — kernelFor(kind) 를 쓸 것')
+})
+
+test('kernelFor 는 모르는 종류에 던진다 — 조용히 고르지 않는다', () => {
+  const src = readFileSync(ENGINE, 'utf-8')
+  const fn = src.slice(src.indexOf('function kernelFor'))
+  assert.match(fn.slice(0, 300), /throw new Error/, 'kernelFor 가 던지지 않으면 이 계약이 무너진다')
+})
+
+test("board 를 주는 기동은 kind 를 요구한다 — `kind ?? 'wms'` 로 메우지 않는다", () => {
+  const offenders = codeOf(MUTATION).filter(l => /kind\s*\?\?\s*['"]/.test(l))
+  assert.deepEqual(offenders, [], '종류를 빠뜨린 프로비저닝이 다시 창고로 기동한다')
+})
+
+/** 두 패키지의 서버 .ts 전부. */
+function serverFiles(): string[] {
+  const out: string[] = []
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e)
+      if (statSync(p).isDirectory()) walk(p)
+      else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+    }
+  }
+  for (const r of ROOTS) walk(r)
+  return out
+}
+
+test('어느 서버 코드도 커널 종류를 리터럴로 메우지 않는다 — 호출자가 엔진의 검증을 앞질렀다', () => {
+  /* 예시 JSON 안의 `system: 'wms'` 는 필드를 보여 주는 것이라 대상이 아니다 — 폴백 연산자만 본다. */
+  const offenders: string[] = []
+  for (const f of serverFiles()) {
+    codeOf(f).forEach(l => {
+      if (/(\?\?|\|\|)\s*['"](wms|yms|mes)['"]/.test(l)) offenders.push(`${f.split('/packages/')[1]}: ${l.trim().slice(0, 90)}`)
+    })
+  }
+  assert.deepEqual(offenders, [], '종류 폴백이 다시 생겼다 — 선언이 없으면 메우지 말고 던질 것')
+})