@things-factory/headless-twin 10.0.9 → 10.0.11

package/test/entity-delta.test.ts

@@ -11,7 +11,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, itemsTag, ordersTag, personsTag, tasksTag } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas, ITEMS_AGGREGATE_LIMIT, itemsTag, ordersTag, personsTag, tasksTag, energyTag } from '../shared/entity-delta.ts'
 
 const byTag = (arr: any[], tag: string) => arr.find(x => x.tag === tag)
 
@@ -180,3 +180,173 @@ test('사람 집약 태그가 항상 나간다 — 선언하지 않은 트윈은
   const withTwo = buildEntityDeltas({ persons: [{ id: 'w1' }, { id: 'w2' }] }, 't1')
   assert.equal(withTwo.find(d => d.tag === personsTag('t1'))!.data.persons.length, 2)
 })
+
+/*
+ * ── 에너지 (EMS 6단계) ──────────────────────────────────────────────────────
+ *
+ * 계측은 `state.energy` 에 산다 — 자원 축이 아니다. 이 매핑이 없으면 보드에 놓은 계량기가 값을
+ * 받지 못하고 **영원히 빈 모습**이 된다(컴포넌트는 있는데 데이터가 없는, 눈에 안 보이는 결함).
+ */
+test('계량 지점의 마지막 관측이 그 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [
+          { id: 'meter-incoming', kW: 1200.5, kWh: 98_000, powerFactor: 0.95, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 3 },
+          { id: 'meter-quiet', samplesInWindow: 0 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+  const m = deltas.find(d => d.tag === 'meter-incoming')!
+  assert.equal(m.data.entity, 'meter')
+  assert.equal(m.data.kW, 1200.5)
+  assert.equal(m.data.measuredAt, '2026-08-14T09:01:00.000Z', '시각을 함께 낸다 — 화면이 계측 끊김을 스스로 안다')
+
+  /* 값이 없는 지점: 키를 넣지 않는다(0 으로 만들면 「전기를 안 썼다」가 된다). */
+  const q = deltas.find(d => d.tag === 'meter-quiet')!
+  assert.equal('kW' in q.data, false)
+  assert.equal(q.data.samplesInWindow, 0, '받은 표본 수는 사실이다')
+})
+
+test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의 사실이 아니다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [],
+      equipment: [],
+      energy: {
+        points: [],
+        contractKW: 4000,
+        open: { startMs: 1, endMs: 2, samples: 1, maxKW: 4200 },
+        peakSince: { kW: 4200, windowStartMs: 1 },
+        closed: Array.from({ length: 20 }, (_, i) => ({ startMs: i, endMs: i + 1, samples: 1, maxKW: 100 + i })),
+        closedTotal: 137
+      }
+    },
+    'ems-1'
+  )
+  const agg = deltas.find(d => d.tag === energyTag('ems-1'))!
+  assert.ok(agg, '집약 태그가 있어야 한다')
+  assert.equal(agg.data.contractKW, 4000)
+  assert.equal(agg.data.peakSince.kW, 4200)
+  /* 하루치를 매 방송에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
+  assert.equal(agg.data.recent.length, 8)
+  assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
+})
+
+test('에너지가 없는 트윈은 에너지 태그를 내지 않는다 — 없는 것을 만들지 않는다', () => {
+  const deltas = buildEntityDeltas({ locations: [], equipment: [] }, 'wms-1')
+  assert.equal(deltas.some(d => d.tag === energyTag('wms-1')), false)
+  assert.equal(deltas.some(d => d.data?.entity === 'meter'), false)
+})
+
+test('자리에도 에너지가 실린다 — 능력이 「잰다」고 말하는데 값이 없던 자리', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [
+        { id: 'incoming-1', type: 'incoming' },
+        { id: 'feeder-a', type: 'feeder' },
+        { id: 'feeder-b', type: 'feeder' }
+      ],
+      equipment: [
+        { id: 'm-main', kind: 'meter', homeLocation: 'incoming-1' },
+        { id: 'm-a1', kind: 'meter', homeLocation: 'feeder-a' },
+        { id: 'm-a2', kind: 'meter', homeLocation: 'feeder-a' }
+      ],
+      energy: {
+        points: [
+          { id: 'm-main', kW: 3800, kWh: 1000, atMs: Date.parse('2026-08-14T09:00:00.000Z'), samplesInWindow: 3 },
+          { id: 'm-a1', kW: 1000, atMs: Date.parse('2026-08-14T09:01:00.000Z'), samplesInWindow: 2 },
+          { id: 'm-a2', kW: 600, atMs: Date.parse('2026-08-14T09:02:00.000Z'), samplesInWindow: 1 }
+        ],
+        closed: [],
+        closedTotal: 0
+      }
+    },
+    'ems-1'
+  )
+
+  const incoming = deltas.find(d => d.tag === 'incoming-1')!.data
+  assert.equal(incoming.entity, 'location', '자리 payload 를 덮지 않고 합친다')
+  assert.equal(incoming.kW, 3800)
+  assert.deepEqual(incoming.meters, ['m-main'], '어느 계량기에서 온 수인지 되짚을 수 있어야 한다')
+
+  /* 자리에 계량기가 둘이면 그 자리의 수는 둘의 합이고, 나이는 **가장 최근**이다. */
+  const a = deltas.find(d => d.tag === 'feeder-a')!.data
+  assert.equal(a.kW, 1600)
+  assert.equal(a.samplesInWindow, 3)
+  assert.equal(a.measuredAt, '2026-08-14T09:02:00.000Z')
+  assert.deepEqual(a.meters, ['m-a1', 'm-a2'])
+
+  /* 계량기가 없는 자리는 예전 그대로 — 에너지 키를 만들지 않는다(0 은 「안 썼다」가 된다). */
+  const b = deltas.find(d => d.tag === 'feeder-b')!.data
+  assert.equal('kW' in b, false)
+  assert.equal('meters' in b, false)
+})
+
+test('자리를 모르는 계량기는 자리에 실리지 않는다 — 설비 태그로만 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [],
+      energy: { points: [{ id: 'm-orphan', kW: 500, samplesInWindow: 1 }], closed: [], closedTotal: 0 }
+    },
+    'ems-1'
+  )
+  assert.equal('kW' in deltas.find(d => d.tag === 'incoming-1')!.data, false)
+  assert.equal(deltas.find(d => d.tag === 'm-orphan')!.data.kW, 500, '설비 태그로는 나간다')
+})
+
+/*
+ * ── 능력 넷의 값이 컴포넌트까지 간다 (2026-08-15) ───────────────────────────
+ * 보드에 놓인 컴포넌트는 `data(tag)` 로만 값을 받는다. 커널이 값을 들고 있어도 이 페이로드에 실리지
+ * 않으면 화면은 영원히 「—」다 — 실제로 그 부류를 두 번 겪었다(스냅샷 투영이 필드를 빠뜨렸고,
+ * 값의 시각을 버렸다).
+ *
+ * 그래서 **설비 태그의 payload** 를 직접 못 박는다: 값과 그 값의 나이가 함께 실려야 한다.
+ */
+test('발전·저장·감축·개폐 값과 그 나이가 설비 태그로 나간다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [
+        { id: 'pv-1', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle', generatedKW: 210, exportKW: 40, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'ess-1', kind: 'battery', homeLocation: 'incoming-1', status: 'idle', soc: 62, chargeKW: 0, dischargeKW: 85, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'load-1', kind: 'curtailable-load', homeLocation: 'incoming-1', status: 'busy', curtailable: true, minKW: 30, measuredAt: '2026-08-15T09:00:00.000Z' },
+        { id: 'cb-1', kind: 'breaker', homeLocation: 'incoming-1', status: 'idle', position: 'closed', measuredAt: '2026-08-15T09:00:00.000Z' }
+      ]
+    },
+    'ems-1'
+  )
+  const by = Object.fromEntries(deltas.map(d => [d.tag, d.data as any]))
+
+  assert.equal(by['pv-1'].generatedKW, 210)
+  assert.equal(by['pv-1'].exportKW, 40)
+  assert.equal(by['ess-1'].soc, 62)
+  assert.equal(by['ess-1'].dischargeKW, 85)
+  assert.equal(by['load-1'].curtailable, true)
+  assert.equal(by['load-1'].minKW, 30)
+  assert.equal(by['cb-1'].position, 'closed')
+  /* 나이가 없으면 화면이 멈춘 값을 지금 값처럼 그린다 — 네 컴포넌트가 모두 이 키를 읽는다. */
+  for (const id of ['pv-1', 'ess-1', 'load-1', 'cb-1']) {
+    assert.equal(by[id].measuredAt, '2026-08-15T09:00:00.000Z', `${id}: 값의 나이가 함께 가야 한다`)
+  }
+})
+
+test('값이 없는 설비에는 그 키를 만들지 않는다 — 0 으로 그리면 「안 쓴다」가 된다', () => {
+  const deltas = buildEntityDeltas(
+    {
+      locations: [{ id: 'incoming-1', type: 'incoming' }],
+      equipment: [{ id: 'pv-2', kind: 'pv-array', homeLocation: 'incoming-1', status: 'idle' }]
+    },
+    'ems-1'
+  )
+  const pv = deltas.find(d => d.tag === 'pv-2')!.data as any
+  assert.equal('generatedKW' in pv, false)
+  assert.equal('measuredAt' in pv, false)
+})

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', '앞뒤 공백은 다듬어 낸다')
+})