@things-factory/headless-twin 10.0.11 → 10.0.13

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 },
@@ -95,9 +99,9 @@ beforeEach(async () => {
 
 test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는다 — 부팅마다 늘면 이력이 잘게 쪼개진다', async () => {
   const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)), 'reset')
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1)
@@ -105,12 +109,12 @@ test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는
 })
 
 test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다**', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   assert.ok(first.length > 0, '이벤트가 있어야 "살아남는지" 를 물을 수 있다')
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(kept, first.length, '구조가 바뀌었다고 이력을 지우면 안 된다 — 그것이 이 작업의 전부다')
@@ -121,9 +125,9 @@ test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다
 })
 
 test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면 나중에 어느 공장인지 알 길이 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(2, 1), 200), 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   const before = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 200), before)
 
@@ -135,11 +139,11 @@ test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면
 })
 
 test('★ 재생이 경계를 넘는다 — 앞선 사실은 남고, 새 구조의 설비가 들어온다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 300), first.length)
 
   const state = await TwinEngine.recover(domainId, INSTANCE)
@@ -153,20 +157,20 @@ test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는
    * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 접으면 그때 없던
    * 설비에서 일이 있었던 것처럼 보인다 — 이 규칙이 그 행들을 제자리에 붙인다.
    */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const legacy = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
   /* 컬럼이 없던 시절을 흉내 낸다 — 번호를 지운다. */
   await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   const state = await TwinEngine.recover(domainId, INSTANCE)
   assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 조용히 버리지 않는다')
   assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
 })
 
 test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전환이 결과를 바꾸지 않는다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2), 'reset')
   const events = realEvents(boardWith(3, 2), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, events, 0)
 
@@ -177,7 +181,7 @@ test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전
 })
 
 test('꺼진 트윈의 이력도 읽을 수 있다 — 저널은 트윈이 꺼져 있을 때 가장 필요하다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   assert.equal(TwinEngine.owns(domainId, INSTANCE), false, '떠 있지 않다')
   assert.equal(await TwinEngine.ownsRegistered(domainId, INSTANCE), true, '그래도 이 테넌트 것이다')
   assert.equal(await TwinEngine.ownsRegistered(domainId, 'someone-elses-twin'), false)
@@ -189,11 +193,11 @@ test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신
    * 그런데 그 규칙을 과거 조회에도 적용하면, 그 시점에 존재하지도 않던 설비가 화면에 선다 —
    * 이 작업이 막으려던 바로 그 거짓말이다. 규칙이 "지금" 에만 걸리는지 못박는다.
    */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const now = await TwinEngine.recover(domainId, INSTANCE)
   assert.equal(now.equipment.length, 3, '"지금" 은 늘린 설비를 보여준다')
@@ -204,10 +208,10 @@ test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신
 })
 
 test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두 개를 눈으로 비교할 수는 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 200)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), '도장 능력 보강')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset', '도장 능력 보강')
   await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 100), first.length)
 
   const history = await TwinEngine.structureHistory(domainId, INSTANCE)
@@ -232,11 +236,11 @@ test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두
 })
 
 test('번호 없는 옛 행도 가장 오래된 리비전의 몫으로 센다 — 재생과 같은 규칙', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const legacy = realEvents(boardWith(2, 1), 200)
   await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
   await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const history = await TwinEngine.structureHistory(domainId, INSTANCE)
   assert.equal(history[0].events, legacy.length, '재생이 rev 1 로 접는 행들을 세는 쪽만 빠뜨리면 두 화면이 다른 말을 한다')
@@ -250,11 +254,11 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
    * 그런 일이 없다.
    */
   const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
   const table = ds.getMetadata(TwinStructure).tableName
   await ds.query(`UPDATE "${table}" SET signature = 'old-style-signature-from-a-previous-algorithm'`)
 
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model)
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
 
   const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
   assert.equal(revs.length, 1, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')
@@ -269,11 +273,11 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
  * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 조용히 재생 순서를 뒤섞는다.
  */
 test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지키는 약속', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
     assert.equal(kept, first.length, 'sim-world 는 이어지는 현실이다 — 지우면 선언이 거짓이 된다')
@@ -283,11 +287,11 @@ test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지
 })
 
 test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹치면 재생 순서가 뒤섞인다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
   const first = realEvents(boardWith(2, 1), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
 
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     const kernel: any = rt.kernel
     assert.ok(kernel, '커널이 떠야 이어 세기를 물을 수 있다')
@@ -301,8 +305,8 @@ test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹
 })
 
 test('저널이 비어 있으면 이어 셀 것이 없다 — 새로 시작하는 트윈에 영향 없음', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1))
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'sim-world')
+  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
   try {
     assert.equal((rt.kernel as any).getSnapshot().revision, 0)
   } finally {

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

@@ -61,13 +61,13 @@ before(async () => {
   beta = b.id
 
   /* 두 테넌트가 **같은 id** 로 각자 프로비저닝한다 — DB 유일성이 `[domain, instanceId]` 라 허용된다. */
-  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model())
-  await TwinEngine.provision(beta, SHARED_ID, 'wms', model())
+  await TwinEngine.provision(alpha, SHARED_ID, 'wms', model(), 'reset')
+  await TwinEngine.provision(beta, SHARED_ID, 'wms', model(), 'reset')
 })
 
 /**
  * **스펙마다 반드시 멈춘다.** 남기면 두 가지가 따라온다: 틱 타이머 때문에 러너가 끝나지 않고, 틱이
- * 뒤늦게 던지는 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

@@ -85,7 +85,7 @@ before(async () => {
   q = new TwinModelItemQuery()
   ctx = { state: { domain: { id: domainId } } }
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {
@@ -213,7 +213,7 @@ test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴
   const bad = master()
   bad.equipment.push({ id: 'ghost-1', kind: 'welder', homeLocationId: 'no-such-station' }) // 끊어진 참조
   bad.equipment.push({ id: 'floater-1', kind: 'welder' })                                   // 기준 자리 없음
-  await TwinEngine.ingestMaster(domainId, bad)
+  await TwinEngine.ingestMaster(domainId, bad, 'reset')
 
   const sum = await new TwinModelQuery().twinModelSummary(INSTANCE, ctx)
   const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'twin.rel.home')
@@ -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 }
@@ -263,7 +265,7 @@ test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한
   for (let i = 0; i < 200; i++) k.tick(1000)
 
   const INST = 'journal-probe'
-  await TwinEngine.provision(domainId, INST, 'wms', model)
+  await TwinEngine.provision(domainId, INST, 'wms', model, 'reset')
   await TwinEngine.persistBatch(domainId, INST, journal.all(), 0)
   await TwinEngine.stop(domainId, INST).catch(() => {})
   delete (TwinEngine as any).recovered[`${domainId}:${INST}`]

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

@@ -76,7 +76,7 @@ before(async () => {
   domainId = d.id
   q = new TwinModelTreeQuery()
   ctx = { state: { domain: { id: domainId } } }
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {
@@ -108,13 +108,13 @@ test('수량을 곱해 내려간다 — 그리고 모르면 곱하지 않는다'
       { key: 'frame-line', label: 'f', inputs: [{ material: 'steel', qty: 4 }], outputs: [{ material: 'frame', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, noQty)
+  await TwinEngine.ingestMaster(domainId, noQty, 'reset')
   const t2 = await explode('trailer')
   assert.equal(t2.items.find((n: any) => n.id === 'frame').qty, null, '모르는 수량을 1 로 메우지 않는다')
   assert.equal(t2.items.find((n: any) => n.id === 'steel').qty, null, '모르는 값 아래는 전부 모르는 값이다')
   assert.equal(t2.qtyIncomplete, true, '합계가 성립하지 않는다는 사실을 낸다')
 
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 test('역전개도 같은 선언으로 — 방향만 뒤집는다', async () => {
@@ -146,11 +146,11 @@ test('사이클은 다시 탐색하지 않고 알린다', async () => {
       { key: 'frame-line', label: 'f', inputs: [{ material: 'trailer', qty: 1 }], outputs: [{ material: 'frame', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, loop)
+  await TwinEngine.ingestMaster(domainId, loop, 'reset')
   const t = await explode('trailer')
   assert.ok(t.items.length < 10, '무한히 자라지 않는다')
   assert.ok(t.cycles.length > 0, '사이클을 만났다는 사실을 말한다')
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 test('상한에서 끊기면 끊겼다고 알린다 — 조용히 자르지 않는다', async () => {
@@ -167,10 +167,10 @@ test('선언에 없는 자재를 참조하면 그 사실이 드러난다', async
       { key: 'trailer-line', label: 't', inputs: [{ material: 'no-such-part', qty: 1 }], outputs: [{ material: 'trailer', qty: 1 }] }
     ]
   })
-  await TwinEngine.ingestMaster(domainId, ghost)
+  await TwinEngine.ingestMaster(domainId, ghost, 'reset')
   const t = await explode('trailer')
   const child = t.items.find((n: any) => n.id === 'no-such-part')
   assert.ok(child, '가리켜진 것은 그리되')
   assert.equal(child.known, false, '선언에 없다는 사실을 함께 낸다(있는 척하지 않는다)')
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })

package/test/twin-origin-resync.test.ts

@@ -68,7 +68,7 @@ after(async () => {
 })
 
 test('인제스트가 원천을 각인한다 — 원천이 무엇이든 한 자리에', async () => {
-  await TwinEngine.ingestMaster(domainId, master(BORN, 3, { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } }))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 3, { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } }), 'reset')
   assert.deepEqual(await originOf(BORN), { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } })
 })
 
@@ -78,7 +78,7 @@ test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않
    * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **조용히 다시 읽을 수 없게 된다.**
    * 그런 종류의 손상은 다음번에 다시 읽으려 할 때까지 아무도 모른다.
    */
-  await TwinEngine.ingestMaster(domainId, master(BORN, 5))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5), 'reset')
   assert.deepEqual(
     await originOf(BORN),
     { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } },
@@ -90,12 +90,12 @@ test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않
 })
 
 test('새 원천을 말하면 갱신된다 — 보존은 침묵에만 적용된다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(BORN, 5, { kind: 'reference', source: 'oracle-wms' }))
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5, { kind: 'reference', source: 'oracle-wms' }), 'reset')
   assert.deepEqual(await originOf(BORN), { kind: 'reference', source: 'oracle-wms' })
 })
 
 test('원천 없이 태어난 트윈은 원천이 없다 — 짐작해 채우지 않는다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(ORPHAN, 2))
+  await TwinEngine.ingestMaster(domainId, master(ORPHAN, 2), 'reset')
   assert.equal(await originOf(ORPHAN), null, '모르는 것을 아는 척하면 엉뚱한 원본으로 현장을 덮는다')
 })
 

package/test/warm-start-seam.test.ts

@@ -30,6 +30,10 @@ const GTIN = 'urn:epc:idpat:sgtin:0614141.012345.*'
  * 이 테스트가 흐름 요건까지 시험하려는 것이 아니므로 커널 테스트와 같은 네 자리를 쓴다.
  */
 const model = () => ({
+  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
+     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
+     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
+  identity: { namespaces: ['https://twin.test/warm-start-seam'] },
   locations: [
     { id: 'dock-recv', type: 'dock', capacity: 100 },
     { id: 'bin-1', type: 'storage', capacity: 200 },