@things-factory/headless-twin 10.0.12 → 10.0.13

package/test/restart-policy.test.ts

@@ -8,7 +8,7 @@
  * 이름이 바뀌었다.
  *
  * ── 지키는 규율 둘 (계획서 §6) ──────────────────────────────────────────────
- * ① **모르는 값은 던진다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
+ * ① **모르는 값은 오류를 낸다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
  *    하나 어긋나는 순간 이력을 지우는 길이다. 기본값을 없앴다.
  * ② **옛 어휘를 번역하지 않는다.** 번역을 두면 옛 값이 살아남고 다시 저장된다. 저장된 값은 한 번
  *    옮기고(데이터 이관), 코드는 새 어휘만 안다 — 다만 무엇으로 옮겨야 하는지는 오류 문장이 말한다.
@@ -27,21 +27,21 @@ test('셋뿐이다 — 그리고 그 셋을 읽는다', () => {
   assert.equal(readRestartPolicy('  resume  ', 'test'), 'resume', '공백은 다듬는다')
 })
 
-test('미선언은 던진다 — 기본값으로 메우면 저널이 지워지는 길이 열린다', () => {
+test('미선언은 오류를 낸다 — 기본값으로 메우면 저널이 지워지는 길이 열린다', () => {
   for (const raw of [undefined, null, '', '   ', 42, {}]) {
     assert.throws(() => readRestartPolicy(raw, 'twin "x"'), /twin "x": restart policy/)
   }
-  /* 무엇을 해야 하는지 문장이 말한다 — 코드를 그대로 던지지 않는다. */
+  /* 무엇을 해야 하는지 문장이 말한다 — 코드를 그대로 오류를 내지 않는다. */
   try {
     readRestartPolicy(undefined, 'twin "x"')
-    assert.fail('던져야 한다')
+    assert.fail('오류를 내어야 한다')
   } catch (e: any) {
     assert.match(e.message, /resync \| resume \| reset/)
     assert.match(e.message, /no default/)
   }
 })
 
-test('옛 어휘도 던진다 — 다만 무엇으로 옮길지 말한다(번역해 주지 않는다)', () => {
+test('옛 어휘도 오류를 낸다 — 다만 무엇으로 옮길지 말한다(번역해 주지 않는다)', () => {
   const cases: [string, string][] = [
     ['mirror', 'resync'],
     ['sim-world', 'resume'],
@@ -50,7 +50,7 @@ test('옛 어휘도 던진다 — 다만 무엇으로 옮길지 말한다(번역
   for (const [old, next] of cases) {
     try {
       readRestartPolicy(old, 'twin "x"')
-      assert.fail(`${old} 은 던져야 한다`)
+      assert.fail(`${old} 은 오류를 내어야 한다`)
     } catch (e: any) {
       assert.match(e.message, /old vocabulary/)
       assert.match(e.message, new RegExp(`"${next}"`), '옮길 값을 말한다')
@@ -58,7 +58,7 @@ test('옛 어휘도 던진다 — 다만 무엇으로 옮길지 말한다(번역
   }
 })
 
-test('묻는 자리도 있다 — 화면·검사는 던지지 않고 판별한다', () => {
+test('묻는 자리도 있다 — 화면·검사는 오류를 내지 않고 판별한다', () => {
   assert.equal(isRestartPolicy('resume'), true)
   assert.equal(isRestartPolicy('sim-world'), false)
   assert.equal(isRestartPolicy(undefined), false)

package/test/revision-axis.test.ts

@@ -0,0 +1,93 @@
+/*
+ * ★ 리비전은 **두 셈**이고, 둘이 같은 것을 세지 않는다 — 그 사실을 코드가 지키는지 본다.
+ *
+ * ── 무엇이 어긋나 있었나 (2026-08-23 실측) ──────────────────────────────────
+ * 포천 미러의 체크포인트가 뜻이 다른 두 수를 나란히 적었다.
+ *
+ *   바깥 revision   12,972   저널에 적힌 줄 번호
+ *   state.revision   6,478   커널이 처리한 봉투 수
+ *
+ * 차이 6,494 는 그 트윈을 **다시 세운 시각**(09:11)에 저널이 이미 갖고 있던 줄 수와 정확히 같았다
+ * (줄 6494 = 08:23:59 · 줄 6495 = 09:11:13). 산수가 맞았으니 결함은 「수가 틀렸다」가 아니다.
+ *
+ * 결함은 **비대칭**이었다. 재기동 경로(`start` → `resumeRevision`)는 커널에 저널 머리를 알려 주는데
+ * 미러를 세우는 경로(`startLive`)는 알려 주지 않았다. 그래서 같은 저장물을 읽는 사람이 같은 이름의 두
+ * 수를 같은 축으로 견주게 되고, 실제로 그렇게 읽혔다(반나절이 그 오독에서 나갔다).
+ *
+ * ── 왜 알려 주어야 하나 ─────────────────────────────────────────────────────
+ * 커널의 계약이 그 이유를 적어 두었다(`resumeRevision`): 「저널이 비어 있지 않은데 0부터 다시 세면 같은
+ * 트윈에 같은 리비전이 둘 생기고, 재생 순서가 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다 — 오류는 안 난다.」
+ * 조용히 깨지는 종류이므로 시험이 지킨다.
+ *
+ * ── 이 시험이 무엇을 재는가 ─────────────────────────────────────────────────
+ * DB 도 커널도 띄우지 않는다. 이 규율은 **어느 경로가 무엇을 부르나**에 있고 그것은 소스에서 확인된다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENGINE = join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts')
+const src = readFileSync(ENGINE, 'utf8')
+
+/**
+ * 그 함수 본문만 — 다른 경로의 호출이 섞여 판정이 흐려지지 않게.
+ *
+ * 끝은 **다음 멤버 선언**으로 자른다. 글자 수로 자르면 주석이 늘어난 날 조용히 짧아져서, 있는 것을
+ * 없다고 말한다(거짓 빨강을 내는 가드는 없는 것보다 나쁘다).
+ */
+function bodyOf(signature: string): string {
+  const at = src.indexOf(signature)
+  assert.ok(at > 0, `${signature} 이 있어야 한다`)
+  const rest = src.slice(at + signature.length)
+  const end = rest.search(/\n  (?:static|private static|\/\*\*)/)
+  const body = end === -1 ? rest : rest.slice(0, end)
+  /* 잘라낸 본문이 비면 판정이 성립하지 않는다 — 그것을 통과로 읽지 않는다. */
+  assert.ok(body.length > 200, `${signature} 본문을 잘라내지 못했다(${body.length}자)`)
+  return body
+}
+
+test('미러를 세우는 경로도 커널에 저널 머리를 알려 준다', () => {
+  const body = bodyOf('static startLive(')
+  /* 저널 머리를 읽는다 — 이 조회는 예전부터 있었다(inst.revision 시드용). */
+  assert.match(body, /order: \{ revision: 'DESC' \}/, '저널 머리를 읽어야 한다')
+  /* 그리고 **커널에도** 알려 준다 — 이 한 줄이 없어서 두 수가 갈렸다. */
+  assert.match(body, /resumeRevision\(head\)/, '커널에도 그 번호를 알려 준다')
+})
+
+test('재기동 경로는 예전부터 알려 주고 있었다 — 두 경로가 같아졌는지 본다', () => {
+  /*
+   * 이 단정은 「고쳤다」가 아니라 **두 경로가 대칭인지**를 지킨다. 한쪽만 남으면 같은 결함이 다른
+   * 문으로 되살아난다.
+   */
+  const body = bodyOf('static start(')
+  assert.match(body, /resumeRevision\(resumeFrom\)/, '재기동 경로도 알려 준다')
+})
+
+test('저널이 비어 있으면 알려 주지 않는다 — 새 트윈은 0 부터 세는 것이 맞다', () => {
+  const body = bodyOf('static startLive(')
+  assert.match(body, /if \(!head \|\| typeof/, '머리가 0 이면 아무 일도 하지 않는다')
+})
+
+test('뒤로 되돌리려는 거절을 삼키지 않는다', () => {
+  /*
+   * 조회가 비동기라 그 사이에 이벤트가 들어와 있을 수 있다. 그때 커널은 뒤로 가기를 거절한다(겹치는
+   * 번호를 막는 그 판정이다). 그 거절을 조용히 버리면 「왜 두 수가 아직 다르지」를 답할 계기가 없다.
+   */
+  const body = bodyOf('static startLive(')
+  assert.match(body, /catch \(err[^)]*\)[\s\S]{0,200}twinWarn/, '거절을 로그에 남긴다')
+  assert.match(body, /is behind the kernel/, '무엇이 어긋났는지 말한다')
+})
+
+test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는 옳다', () => {
+  /*
+   * 바깥은 저널 줄 번호(이어 쓸 자리), 안쪽은 커널이 접은 봉투 수다. **둘을 하나로 합치지 않는다** —
+   * 합치면 「어디까지 적었나」와 「어디까지 반영했나」를 구별할 수 없고, 그 구별이 미러의 정직성이다.
+   * 두 경로가 대칭이면 값이 같아지지만, **자리는 둘이어야 한다.**
+   */
+  const at = src.indexOf('static async persistSnapshot')
+  assert.ok(at > 0, 'persistSnapshot 이 있어야 한다')
+  const body = src.slice(at, at + 1200)
+  assert.match(body, /inst\.revision \?\? state\.revision/, '바깥은 저널 줄 번호를 먼저 쓴다')
+  assert.match(body, /\{ revision, state/, '두 수를 나란히 싣는다')
+})

package/test/runtime-key.test.ts

@@ -39,7 +39,7 @@ test('인스턴스 id 안의 구분자를 보존한다 — 첫 구분자에서
   assert.equal(instanceId, weird)
 })
 
-test('도메인 id 에 구분자가 있으면 던진다 — 조용히 모호한 키를 만들지 않는다', () => {
+test('도메인 id 에 구분자가 있으면 오류를 낸다 — 조용히 모호한 키를 만들지 않는다', () => {
   /* 조용히 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
   assert.throws(() => runtimeKey(`a${RUNTIME_KEY_SEP}b`, 'x'), /ambiguous/)
 })
@@ -49,7 +49,7 @@ test('빈 값은 키가 될 수 없다 — 테넌트 없는 런타임은 없다'
   assert.throws(() => runtimeKey(D1, ''), /instanceId is required/)
 })
 
-test('키가 아닌 것을 되돌리려 하면 던진다', () => {
+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}"`)
   }

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(방송, 't1')·heap.
+ * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(브로드캐스팅, 't1')·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
 import { test } from 'node:test'
@@ -87,7 +87,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     const tSnap = (performance.now() - t) / iters
     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)
+    // 4) 브로드캐스팅 payload(buildEntityDeltas)
     t = performance.now()
     for (let k = 0; k < iters; k++) buildEntityDeltas(s, 't1')
     const tDelta = (performance.now() - t) / iters

package/test/spec-coverage.test.ts

@@ -61,7 +61,7 @@ test('커널이 보고 API 를 갖지 않으면 undefined — "전부 기본값"
   assert.equal(readSpecCoverage(undefined), undefined)
 })
 
-test('커널 보고가 던져도 예측을 깨지 않는다', () => {
+test('커널 보고가 오류를 내어도 예측을 깨지 않는다', () => {
   assert.equal(readSpecCoverage({ specCoverage: () => { throw new Error('boom') } }), undefined)
 })
 

package/test/stage-path.test.ts

@@ -0,0 +1,95 @@
+/*
+ * ★ 단계 판정 — **체크리스트가 아니라 증거로 센다.**
+ *
+ * 이 테스트가 지키는 것:
+ *  ① **「모른다」는 달성이 아니다.** 계측되지 않은 신호(`null`)를 0 으로 대체하면 「반출 0건」과
+ *     「반출을 세지 않았다」가 같아진다. 배선하지 않은 계측으로 단계를 주장할 길을 남기지 않는다.
+ *  ② **반출을 세었는데 없으면 라이브가 아니다.** 되풀어 읽는 스냅샷은 원리적으로 반출을 못 낸다 —
+ *     이 판별식이 폴링을 「실시간」이라 부르는 것을 막는다.
+ *  ③ **선언이 비면 예측이 아니다.** 커널 기본값 위에 선 숫자도 화면에서는 예측처럼 보인다.
+ *  ④ **앞을 건너뛸 수 없다.** 뒤 단계는 자기 조건을 따지지 않고 `prerequisite` 으로 막는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assessStagePath, forbiddenClaims, type StageEvidence } from '../server/engine/stage-path.ts'
+
+/** 전부 달성한 증거 — 각 시험은 여기서 한 축만 무너뜨린다(무엇이 판정을 바꿨는지 분명해진다). */
+const full = (): StageEvidence => ({
+  locationCount: 12,
+  itemCount: 340,
+  masterWarnings: 3,
+  liveIngestTotal: 1200,
+  removalsObserved: 17,
+  forecastRan: true,
+  specCoverage: { declared: 6, total: 8 },
+  actuateCapability: true,
+  correlatedEffectObserved: 2
+})
+
+test('전부 증거가 있으면 폐루프까지 도달하고 금지 표현이 없다', () => {
+  const p = assessStagePath(full())
+  assert.deepEqual(p.stages.map(s => s.achieved), [true, true, true, true])
+  assert.equal(p.reached, 'closed-loop')
+  assert.equal(p.next, null)
+  assert.deepEqual(forbiddenClaims(p), [])
+})
+
+test('못 옮긴 값을 세지 않았으면 구조도 달성이 아니다 — 0 이라고 우기지 않는다', () => {
+  const p = assessStagePath({ ...full(), masterWarnings: null })
+  const s1 = p.stages[0]
+  assert.equal(s1.achieved, false)
+  assert.deepEqual(s1.unmeasured, ['master-warnings'])
+  assert.deepEqual(s1.blockedBy, [], '자리와 물품은 있으므로 막힌 것이 아니라 모르는 것이다')
+  assert.equal(p.reached, null, '첫 칸을 못 밟았으면 서 있는 칸이 없다')
+})
+
+test('못 옮긴 값이 3건이어도 구조는 달성이다 — 요구는 「없다」가 아니라 「말할 수 있다」', () => {
+  assert.equal(assessStagePath({ ...full(), masterWarnings: 3 }).stages[0].achieved, true)
+  assert.equal(assessStagePath({ ...full(), masterWarnings: 0 }).stages[0].achieved, true)
+})
+
+test('반출을 세었는데 0 이면 라이브가 아니다 — 스냅샷 되풀어 읽기의 징표', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: 0 })
+  assert.equal(p.stages[1].achieved, false)
+  assert.deepEqual(p.stages[1].blockedBy, ['no-removal-observed'])
+  assert.equal(p.reached, 'structure')
+  assert.ok(forbiddenClaims(p).includes('claim.realtime'), '실시간이라고 말할 수 없다')
+})
+
+test('반출이 계측되지 않으면 「없다」가 아니라 「모른다」로 막힌다', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: null })
+  assert.deepEqual(p.stages[1].unmeasured, ['removals'])
+  assert.deepEqual(p.stages[1].blockedBy, [], '인제스트는 있으므로 막힌 것이 아니다')
+})
+
+test('선언이 비면 예측이 아니다 — 기본값 위에 선 숫자도 숫자로 보인다', () => {
+  const p = assessStagePath({ ...full(), specCoverage: { declared: 0, total: 8 } })
+  assert.equal(p.stages[2].achieved, false)
+  assert.deepEqual(p.stages[2].blockedBy, ['declarations-empty'])
+  assert.equal(p.reached, 'live')
+  assert.ok(forbiddenClaims(p).includes('claim.prediction'))
+})
+
+test('접수만으로는 폐루프가 아니다 — 효과가 관측으로 돌아와야 닫힌다', () => {
+  const p = assessStagePath({ ...full(), correlatedEffectObserved: 0 })
+  assert.deepEqual(p.stages[3].blockedBy, ['effect-not-observed'])
+  assert.equal(p.reached, 'forecast')
+})
+
+test('앞이 막히면 뒤는 자기 조건을 따지지 않는다 — 순서를 건너뛸 수 없다', () => {
+  const p = assessStagePath({ ...full(), locationCount: 0, itemCount: 0 })
+  assert.deepEqual(p.stages[0].blockedBy, ['no-locations', 'no-items'])
+  for (const later of p.stages.slice(1)) assert.deepEqual(later.blockedBy, ['prerequisite'])
+  assert.deepEqual(p.next, { stage: 'structure', blockedBy: ['no-locations', 'no-items'], unmeasured: [] })
+})
+
+test('다음 걸음은 목록이 아니라 하나다', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: 0, specCoverage: null, actuateCapability: false })
+  assert.equal(p.next?.stage, 'live', '뒤쪽 결손을 함께 들이밀지 않는다')
+})
+
+test('비직렬 수량 물품만 있어도 구조는 달성이다 — 식품·화학은 개수로 오지 않는다', () => {
+  /* itemCount 는 「자리에 놓인 물품 수」이고, 비직렬 수량 물품(subLot)도 한 줄로 센다. */
+  assert.equal(assessStagePath({ ...full(), itemCount: 1 }).stages[0].achieved, true)
+})

package/test/standard-coverage.test.ts

@@ -11,9 +11,21 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { standardsForKind } from '../server/service/twin-model/standard-coverage.ts'
-import { iec61850Coverage } from '../server/service/twin-model/iec61850-coverage.ts'
-import { epcisCoverage } from '../server/service/twin-model/epcis-coverage.ts'
+/*
+ * **빌드 산출물을 부른다** — 소스를 직접 실행하지 않는다.
+ *
+ * 이 모듈들은 서로를 값으로 참조한다(축 어긋남 판정을 한 곳에 두었다). 그 참조는 계약대로 `.js` 로
+ * 적히고, 타입만 지우고 소스를 실행하는 방식은 그 경로를 `.ts` 로 바꿔 주지 않는다. 그래서 소스를
+ * 부르면 「모듈을 찾을 수 없다」로 선다.
+ *
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { standardsForKind } = req('../dist-server/service/twin-model/standard-coverage.js')
+const { iec61850Coverage } = req('../dist-server/service/twin-model/iec61850-coverage.js')
+const { epcisCoverage } = req('../dist-server/service/twin-model/epcis-coverage.js')
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 

package/test/status-tally.test.ts

@@ -0,0 +1,55 @@
+/*
+ * 상태별 내림 — **수 하나가 뜻을 바꾸지 않게** (2026-08-23).
+ *
+ * 커널이 관측 흡수에서 완료된 작업을 떨어뜨리지 않게 고쳐진 뒤, 개념 지도의 작업 카드가 0 에서 2,820 이
+ * 되었다. 카드는 상태의 인구조사이므로 그 수가 맞지만, 사람은 「지금 할 일 2,820건」으로 읽는다.
+ * 수를 줄여 맞는 척하게 만들지 않고, 무엇으로 이루어진 수인지 함께 낸다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 상태별로 갈라 세고, **많은 것부터** 낸다(카드가 한 줄로 보이므로 순서가 뜻을 만든다).
+ *  ② 낱말은 커널의 것 그대로 — 여기서 묶거나 고쳐 부르지 않는다.
+ *  ③ 상태를 말하지 않는 축은 **필드를 만들지 않는다**(빈 표는 「상태 없음」과 「못 읽음」을 뭉갠다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { statusTally } from '../server/service/twin-model/status-tally.ts'
+
+test('상태별로 갈라 세고 많은 것부터 낸다', () => {
+  const r = statusTally([
+    { id: 'a', status: 'completed' },
+    { id: 'b', status: 'in-progress' },
+    { id: 'c', status: 'completed' },
+    { id: 'd', status: 'completed' }
+  ])
+  assert.deepEqual(r.statusCounts, [
+    { status: 'completed', count: 3 },
+    { status: 'in-progress', count: 1 }
+  ])
+})
+
+test('낱말은 커널의 것 그대로 — 묶거나 고쳐 부르지 않는다', () => {
+  const r = statusTally([{ status: 'assigned' }, { status: 'created' }])
+  assert.deepEqual(
+    r.statusCounts?.map(s => s.status).sort(),
+    ['assigned', 'created'],
+    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 조용히 잘못 부른다'
+  )
+})
+
+test('상태를 말하지 않는 축은 필드를 만들지 않는다', () => {
+  assert.deepEqual(statusTally([{ id: 'loc-1' }, { id: 'loc-2' }]), {}, '빈 표를 내지 않는다')
+  assert.deepEqual(statusTally([]), {})
+  assert.deepEqual(statusTally(null), {})
+  assert.deepEqual(statusTally({ id: 'not-a-list' }), {}, '목록이 아니면 셀 것이 없다')
+})
+
+test('상태를 말하는 것만 센다 — 없는 것을 「모름」이라는 갈래로 만들지 않는다', () => {
+  const r = statusTally([{ status: 'completed' }, { id: 'x' }, { status: '' }, { status: 7 }])
+  assert.deepEqual(r.statusCounts, [{ status: 'completed', count: 1 }])
+})
+
+test('한 갈래뿐이면 그대로 한 갈래다 — 화면이 그때는 내림을 감춘다', () => {
+  const r = statusTally([{ status: 'completed' }, { status: 'completed' }])
+  assert.deepEqual(r.statusCounts, [{ status: 'completed', count: 2 }], '판단은 화면이 하고, 사실은 그대로 낸다')
+})

package/test/structure-revision-db.test.ts

@@ -41,6 +41,10 @@ const GTIN = 'urn:epc:idpat:sgtin:0614141.012345.*'
 /** 저장 자리 `bins` 개 + 지게차 `forklifts` 대 — 구조를 다이얼한다. */
 const boardWith = (bins: number, forklifts: number): any => ({
   spaceId: 'struct-space',
+  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
+     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
+     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
+  identity: { namespaces: ['https://twin.test/structure-revision'] },
   utcOffsetMinutes: 0,
   locations: [
     { id: 'dock-recv', type: 'dock', capacity: 100 },

package/test/tenant-registry-db.test.ts

@@ -67,7 +67,7 @@ before(async () => {
 
 /**
  * **스펙마다 반드시 멈춘다.** 남기면 두 가지가 따라온다: 틱 타이머 때문에 러너가 끝나지 않고, 틱이
- * 뒤늦게 던지는 DB 쓰기가 teardown 이후에 도착해 `SQLITE_MISUSE` 로 스위트를 오염시킨다.
+ * 뒤늦게 오류를 내는 DB 쓰기가 teardown 이후에 도착해 `SQLITE_MISUSE` 로 스위트를 오염시킨다.
  */
 afterEach(async () => {
   await TwinEngine.stop(alpha, SHARED_ID).catch(() => {})

package/test/time-range.test.ts

@@ -0,0 +1,152 @@
+/*
+ * ★ 시각축은 **두 수만 묻는다** — 저널을 다 읽어 오지 않는다.
+ *
+ * ── 무엇을 겪었나 (2026-08-20 실측) ─────────────────────────────────────────
+ * `TwinEngine.timeRange` 는 공간의 인스턴스마다 `find()` 로 **행을 전부 엔티티로 하이드레이션**한 뒤
+ * JS 에서 min/max 를 골랐다. 그런데 이 함수는 화면 상단의 컨텍스트 띠가 **4초마다** 부른다. 개발
+ * 서버에서 `order-check` 한 트윈이 275,882행 · `payload` 131MB 였다 — 4초마다 그 JSON 을 전부 파싱했다.
+ *
+ * 결과: 프로세스 CPU 81~152%, 아무 일도 하지 않는 질의가 8~14초. JS 프로파일 상위가 TypeORM 의
+ * `RelationIdLoader`·`RawSqlResultsToEntityTransformer`·`stringToSimpleJson` 이고 GC 가 16.7% 였다.
+ * 트윈 틱(계기가 16%)도 저널 쓰기도 아니라 **이 읽기**였다.
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ * ① 답이 맞다(공간의 모든 트윈에 걸친 min/max, 남의 공간은 안 섞인다)
+ * ② 「없음」을 0 으로 떨어뜨리지 않는다(시각축이 1970년에서 시작하면 스크러버가 못 쓰게 된다)
+ * ③ **행을 실어 오지 않는다** — 고친 방식이 되돌아가면(다시 `find()`) 답은 그대로 맞고 느려지기만
+ *    하므로, 결과만 보는 시험으로는 회귀를 잡을 수 없다. 그래서 소스를 함께 본다.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+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 { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const SPACE = 'space-yard'
+const OTHER_SPACE = 'space-elsewhere'
+
+/** 저널 행 하나 — 시각축이 보는 것은 `eventTime` 뿐이다. */
+async function event(instanceId: string, eventTime: string | null, revision: number): Promise<void> {
+  await ds.getRepository(TwinEvent).save(
+    ds.getRepository(TwinEvent).create({
+      domain: { id: domainId } as any,
+      instanceId,
+      eventType: 'test.event',
+      revision,
+      eventTime: eventTime === null ? null : new Date(eventTime),
+      payload: { note: 'x' }
+    } as any)
+  )
+}
+
+async function instance(instanceId: string, spaceId: string): Promise<void> {
+  await ds.getRepository(TwinInstance).save(
+    ds.getRepository(TwinInstance).create({
+      domain: { id: domainId } as any,
+      instanceId,
+      spaceId,
+      kind: 'yms',
+      status: 'stopped',
+      restartPolicy: 'reset',
+      purpose: 'operational'
+    } 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: 'range-test', subdomain: 'range-test' } as any)
+  domainId = d.id
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+test('공간의 여러 트윈에 걸쳐 가장 이른 것과 가장 늦은 것을 낸다', async () => {
+  await instance('yard-a', SPACE)
+  await instance('yard-b', SPACE)
+
+  /* 가장 이른 것은 b 에, 가장 늦은 것은 a 에 있다 — 한 트윈만 보면 답이 틀린다. */
+  await event('yard-a', '2026-03-01T00:00:00.000Z', 1)
+  await event('yard-a', '2026-06-30T12:00:00.000Z', 2)
+  await event('yard-b', '2026-01-15T09:00:00.000Z', 1)
+
+  const r = await TwinEngine.timeRange(domainId, SPACE)
+  assert.equal(r.minTime, '2026-01-15T09:00:00.000Z')
+  assert.equal(r.maxTime, '2026-06-30T12:00:00.000Z')
+})
+
+test('다른 공간의 저널은 섞이지 않는다 — 시각축은 그 현장의 것이다', async () => {
+  await instance('far-c', OTHER_SPACE)
+  await event('far-c', '2020-01-01T00:00:00.000Z', 1)
+  await event('far-c', '2030-01-01T00:00:00.000Z', 2)
+
+  const r = await TwinEngine.timeRange(domainId, SPACE)
+  assert.equal(r.minTime, '2026-01-15T09:00:00.000Z', '2020년이 새어 들어오지 않는다')
+  assert.equal(r.maxTime, '2026-06-30T12:00:00.000Z', '2030년도 그렇다')
+})
+
+test('시각이 빈 행이 시각축을 1970년으로 끌어내리지 않는다', async () => {
+  /* 옛 행에는 `eventTime` 이 없을 수 있다. 그것을 0 으로 읽으면 스크러버가 56년을 그린다. */
+  await event('yard-a', null, 3)
+
+  const r = await TwinEngine.timeRange(domainId, SPACE)
+  assert.equal(r.minTime, '2026-01-15T09:00:00.000Z', '빈 시각은 「없음」이고 0 이 아니다')
+})
+
+test('이벤트가 없으면 「없음」이다 — 0 이나 지금이 아니다', async () => {
+  await instance('empty-d', 'space-empty')
+
+  const r = await TwinEngine.timeRange(domainId, 'space-empty')
+  assert.equal(r.minTime, null)
+  assert.equal(r.maxTime, null)
+})
+
+test('그 공간에 트윈이 없으면 「없음」이다', async () => {
+  const r = await TwinEngine.timeRange(domainId, 'space-nobody')
+  assert.equal(r.minTime, null)
+  assert.equal(r.maxTime, null)
+})
+
+test('두 수를 구하려고 행을 실어 오지 않는다 — 되돌아가면 답은 맞고 느려지기만 한다', () => {
+  /*
+   * 결과만 보는 시험으로는 이 회귀를 잡을 수 없다(`find()` 로 돌려도 min/max 는 맞다). 그래서 함수의
+   * 소스를 본다: 집계(MIN/MAX)를 쓰고, 저널을 `find()` 로 긁지 않는다.
+   */
+  const src = readFileSync(new URL('../server/engine/twin-engine.ts', import.meta.url).pathname, 'utf-8')
+  const at = src.indexOf('static async timeRange(')
+  assert.ok(at > 0, 'timeRange 를 찾지 못했다 — 이름이 바뀌면 이 검사도 함께 옮긴다')
+
+  /* 함수 본문만 떼어 본다 — 다음 멤버 선언까지. */
+  const body = src.slice(at, src.indexOf('\n  /** 정지 훅', at) > 0 ? src.indexOf('\n  /** 정지 훅', at) : at + 4000)
+
+  assert.ok(body.includes("MIN(e.eventTime)") && body.includes("MAX(e.eventTime)"), '집계는 DB 가 한다')
+  assert.ok(
+    !/getRepository\(TwinEvent\)\s*\.?\s*\n?\s*\.find\(/.test(body),
+    '저널을 행 단위로 실어 오면 안 된다 — 275,882행 · payload 131MB 를 4초마다 파싱했던 자리다'
+  )
+})

package/test/touched-items.test.ts

@@ -0,0 +1,61 @@
+/*
+ * 사건이 **어느 물품을 건드렸나** — 브로드캐스팅이 바뀐 것만 만들 수 있게 (2026-08-21).
+ *
+ * 이 판정이 틀리면 **화면이 낡는다.** 그래서 지키는 것을 값으로 못 박는다:
+ *  ① 개체를 말한 자리를 전부 읽는다 — 관측·집약(부모/자식)·변환(입력/출력).
+ *  ② 부류 수량만 말한 사건은 「모른다」다 — 그 부류의 어느 개체인지 말하지 않았다.
+ *  ③ 물품을 만지지 않는다고 **선언된** 사건은 빈 범위다(작업·설비·인원·자산·오더·품질·확인·에너지).
+ *  ④ 낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다.
+ *
+ * 「모른다」(`null`)와 「하나도 없다」(빈 집합)는 **다른 사실**이다. 앞은 전부 다시 만들게 하고 뒤는
+ * 물품을 건너뛰게 한다 — 둘을 같게 두면 둘 중 하나가 반드시 틀린다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { touchedItemKeys } from '../shared/touched-items.ts'
+
+const epcis = (data: any) => ({ eventType: 'epcis.object', data })
+
+test('관측 사건은 말한 개체를 모두 낸다', () => {
+  const got = touchedItemKeys(epcis({ epcList: ['urn:epc:id:sgtin:952.1.A', 'urn:epc:id:sgtin:952.1.B'] }))
+  assert.deepEqual([...got!].sort(), ['urn:epc:id:sgtin:952.1.A', 'urn:epc:id:sgtin:952.1.B'])
+})
+
+test('집약은 부모와 자식을 함께 낸다 — 부모만 내면 팔레트에 담긴 것이 낡는다', () => {
+  const got = touchedItemKeys({
+    eventType: 'epcis.aggregation',
+    data: { parentID: 'urn:epc:id:sscc:952.P1', childEPCs: ['urn:epc:id:sgtin:952.1.A'] }
+  })
+  assert.deepEqual([...got!].sort(), ['urn:epc:id:sgtin:952.1.A', 'urn:epc:id:sscc:952.P1'])
+})
+
+test('변환은 입력과 출력을 함께 낸다 — 소비된 것도 값이 바뀐다', () => {
+  const got = touchedItemKeys({
+    eventType: 'epcis.transformation',
+    data: { inputEPCList: ['in-1', 'in-2'], outputEPCList: ['out-1'] }
+  })
+  assert.deepEqual([...got!].sort(), ['in-1', 'in-2', 'out-1'])
+})
+
+test('부류 수량만 말한 사건은 「모른다」다 — 그 부류의 어느 개체인지 말하지 않았다', () => {
+  const got = touchedItemKeys(epcis({ quantityList: [{ epcClass: 'urn:epc:idpat:sgtin:952.1.*', quantity: 3 }] }))
+  assert.equal(got, null, '개체를 특정하지 못하면 전부 다시 만들어야 한다')
+})
+
+test('물품을 만지지 않는다고 선언된 사건은 빈 범위다 — 전부 다시 만들 이유가 없다', () => {
+  for (const eventType of ['task.status', 'equipment.status', 'person.status', 'asset.status', 'order.status', 'quality.output', 'attention.acked']) {
+    const got = touchedItemKeys({ eventType, data: { taskId: 't1', moverId: 'fk-1' } })
+    assert.ok(got, `${eventType} 은 「모른다」가 아니다`)
+    assert.equal(got!.size, 0, `${eventType} 은 물품을 건드리지 않는다`)
+  }
+  const energy = touchedItemKeys({ eventType: 'energy.measured', data: { id: 'm-1', kW: 12 } })
+  assert.equal(energy!.size, 0)
+})
+
+test('낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다', () => {
+  assert.equal(touchedItemKeys({ eventType: 'something.new', data: { epcList: ['x'] } }), null)
+  assert.equal(touchedItemKeys({ data: { epcList: ['x'] } }), null, '낱말이 없으면 판정할 수 없다')
+  assert.equal(touchedItemKeys(undefined), null)
+  assert.equal(touchedItemKeys({ eventType: 'epcis.object' }), null, '내용이 없으면 판정할 수 없다')
+})

package/test/twin-event-keys.test.ts

@@ -7,7 +7,15 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { bizStepOf, epcOf, orderOf, locationOf, equipmentIdOf, twinEventKeys } from '../server/service/twin-event/twin-event-keys.ts'
+/*
+ * **빌드 산출물을 부른다** — 이 모듈은 로그 문(`engine/log.js`)을 값으로 참조하고, 타입만 지우고 소스를
+ * 실행하는 방식은 그 `.js` 경로를 `.ts` 로 바꿔 주지 않는다. 소스를 부르면 「모듈을 찾을 수 없다」로 선다.
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { bizStepOf, epcOf, orderOf, locationOf, equipmentIdOf, twinEventKeys } = req('../dist-server/service/twin-event/twin-event-keys.js')
 
 /** EPCIS ObjectEvent 한 건(입고) — 실제 인제스트가 싣는 모양. */
 const EPCIS_OBJECT = {
@@ -102,7 +110,7 @@ test('상한을 넘는 값은 조용히 사라지지 않는다 — 잘리되 경
 })
 
 test('빈 봉투에도 터지지 않는다', () => {
-  const empty = { bizStep: undefined, epc: undefined, orderId: undefined, locationId: undefined, moverId: undefined }
+  const empty = { action: undefined, bizStep: undefined, epc: undefined, orderId: undefined, locationId: undefined, moverId: undefined }
   assert.deepEqual(twinEventKeys(undefined), empty)
   assert.deepEqual(twinEventKeys({}), empty)
 })

package/test/twin-model-item-db.test.ts

@@ -238,6 +238,8 @@ test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한
   const model = {
     spaceId: 'journal-space',
     utcOffsetMinutes: 0,
+    /* 커널은 선언 없이 팔레트·문서를 만들지 않는다 — 픽스처 자기 이름공간을 준다. */
+    identity: { namespaces: ['https://twin.test/twin-model-item/journal'] },
     locations: [
       { id: 'dock-recv', type: 'dock', capacity: 100 },
       { id: 'bin-1', type: 'storage', capacity: 20 }