@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -0,0 +1,78 @@
+/*
+ * 인제스트 공간 판정 — "이 현장에 더한다" 가 조용히 빗나가지 않게.
+ *
+ * 엔진 본체는 DB·TypeORM 을 물고 있어 단위테스트로 부를 수 없다. 그래서 **결정만** 순수 모듈로
+ * 떼어 놓고 여기서 본다(엔진은 공간 존재 여부를 조회해 넘기는 일만 한다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolveIngestSpace, refuseImportSpace, collidingIds, INGEST_SPACE_NOT_FOUND } from '../server/service/reference/ingest-space.ts'
+
+test('고르지 않으면 마스터가 파생한 공간으로 — 지금까지의 거동을 바꾸지 않는다', () => {
+  for (const req of [undefined, null, '', '   ']) {
+    const c = resolveIngestSpace('hatiolab-wms-site', req as any, false)
+    assert.deepEqual(c, { spaceId: 'hatiolab-wms-site', joined: false }, `요청=${JSON.stringify(req)}`)
+  }
+})
+
+test('기존 현장을 고르면 그 공간으로 들어가고 합치기로 표시된다', () => {
+  const c = resolveIngestSpace('trailer-yard-new-site', 'rosarito-site', true)
+  assert.deepEqual(c, { spaceId: 'rosarito-site', joined: true })
+})
+
+test('마스터가 이미 그 공간이면 합치기가 아니다 — 같은 공간의 재인제스트다', () => {
+  const c = resolveIngestSpace('rosarito-site', 'rosarito-site', true)
+  assert.deepEqual(c, { spaceId: 'rosarito-site', joined: false })
+})
+
+test('없는 현장은 거절한다 — 조용히 새 공간을 만들지 않는다', () => {
+  /* 여기서 새 공간을 만들어 주면 사용자는 합쳤다고 믿고 화면은 따로 논다. 그때는 이미 양쪽에
+     이벤트가 쌓여 있어 손으로 합치는 것이 훨씬 비싸다. */
+  assert.throws(
+    () => resolveIngestSpace('a-site', 'typo-site', false),
+    (e: any) => e.code === INGEST_SPACE_NOT_FOUND && /typo-site/.test(e.message)
+  )
+})
+
+test('앞뒤 공백은 다듬는다 — 사용자가 붙여 넣은 id 로 거절당하지 않게', () => {
+  const c = resolveIngestSpace('a-site', '  rosarito-site  ', true)
+  assert.equal(c.spaceId, 'rosarito-site')
+})
+
+test('같은 id 를 쓰는 것들을 찾아낸다 — 합쳐지는 것을 모르고 지나가지 않게', () => {
+  const existing = [{ id: 'a-yard' }, { id: 'a-dock' }]
+  const incoming = [{ id: 'a-yard' }, { id: 'a-line' }, { id: 'a-dock' }]
+  assert.deepEqual(collidingIds(existing, incoming), ['a-dock', 'a-yard'], '정렬된 교집합')
+  assert.deepEqual(collidingIds(existing, [{ id: 'a-line' }]), [], '겹치지 않으면 빈 배열')
+  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, [], '종류 폴백이 다시 생겼다 — 선언이 없으면 메우지 말고 던질 것')
+})

package/test/knob-defaults.test.ts

@@ -0,0 +1,72 @@
+/*
+ * 노브 기본값 — **조용히 아무것도 안 하는 트윈**이 만들어지지 않게.
+ *
+ * 기본값을 아는 곳은 노브 스키마(계약)인데 그것을 적용하는 곳이 위자드뿐이었다. 그래서 화면을 거치지
+ * 않는 호출자가 파라미터를 일부만 주면 템플릿 안에서 발생률이 0 이 되고, 이벤트를 하나도 만들지 않는
+ * 트윈이 아무 말 없이 생겼다(실제로 밟았고 템플릿이 깨진 것으로 오진했다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { applyKnobDefaults, filledKnobKeys } from '../server/service/reference/knob-defaults.ts'
+
+const KNOBS = [
+  { key: 'id', default: 'wms-new' },
+  { key: 'inboundRate', default: 40 },
+  { key: 'outboundRate', default: 30 },
+  { key: 'geo', default: { lat: 37.5, lon: 127.0 } },
+  { key: 'noDefault' } // 기본값을 선언하지 않은 노브
+]
+
+test('빠진 노브를 기본값으로 채운다 — 부분 파라미터 호출이 죽은 트윈을 만들지 않게', () => {
+  const out = applyKnobDefaults(KNOBS, { id: 'mine' })
+  assert.equal(out.id, 'mine', '준 값은 그대로')
+  assert.equal(out.inboundRate, 40)
+  assert.equal(out.outboundRate, 30)
+  assert.deepEqual(out.geo, { lat: 37.5, lon: 127.0 })
+  assert.ok(!('noDefault' in out), '기본값 없는 노브는 만들어 내지 않는다')
+})
+
+test('0 은 덮지 않는다 — "자극 없이 구조만" 이라는 선언을 뒤집지 않게', () => {
+  /* falsy 로 판정해 덮으면 발생률 0(도착 없음)이 40 으로 바뀐다. 없는 것과 0 은 다르다. */
+  const out = applyKnobDefaults(KNOBS, { inboundRate: 0, outboundRate: 0 })
+  assert.equal(out.inboundRate, 0)
+  assert.equal(out.outboundRate, 0)
+})
+
+test('빈 문자열·false 도 뜻 있는 값이라 덮지 않는다', () => {
+  const out = applyKnobDefaults([{ key: 'name', default: 'New site' }, { key: 'flag', default: true }], { name: '', flag: false })
+  assert.equal(out.name, '')
+  assert.equal(out.flag, false)
+})
+
+test('null 은 "주지 않음" 으로 본다 — JSON·GraphQL 경로가 그렇게 보낸다', () => {
+  const out = applyKnobDefaults(KNOBS, { inboundRate: null as any })
+  assert.equal(out.inboundRate, 40)
+})
+
+test('선언 밖 파라미터는 손대지 않는다 — 템플릿의 폴백 경로를 끊지 않게', () => {
+  /* 템플릿은 `geo` 대신 `lat`/`lon` 을 읽는 폴백을 가진다. 모르는 키를 걷어내면 그 경로가 끊긴다. */
+  const out = applyKnobDefaults(KNOBS, { lat: 1, lon: 2 })
+  assert.equal(out.lat, 1)
+  assert.equal(out.lon, 2)
+})
+
+test('입력을 바꾸지 않는다 — 호출자의 객체가 몰래 변하면 추적이 어렵다', () => {
+  const given = { id: 'mine' }
+  applyKnobDefaults(KNOBS, given)
+  assert.deepEqual(given, { id: 'mine' })
+})
+
+test('노브가 없거나 파라미터가 없어도 무너지지 않는다', () => {
+  assert.deepEqual(applyKnobDefaults(null, { a: 1 }), { a: 1 })
+  assert.deepEqual(applyKnobDefaults(KNOBS, null).inboundRate, 40)
+  assert.deepEqual(applyKnobDefaults(undefined, undefined), {})
+})
+
+test('무엇을 채웠는지 알린다 — 준 적 없는 값으로 만들어진 것을 밝히게', () => {
+  assert.deepEqual(filledKnobKeys(KNOBS, { id: 'mine', inboundRate: 0 }), ['outboundRate', 'geo'],
+    '준 것과 0 은 채운 목록에 없다')
+  assert.deepEqual(filledKnobKeys(KNOBS, null), ['id', 'inboundRate', 'outboundRate', 'geo'])
+  assert.deepEqual(filledKnobKeys(KNOBS, { id: 'a', inboundRate: 1, outboundRate: 2, geo: {} }), [], '다 주면 빈 목록')
+})