@things-factory/headless-twin 10.0.12 → 10.0.13

package/test/axis-read.test.ts

@@ -40,7 +40,7 @@ test('상태가 없으면 모른다 — 커널이 멈춰 있으면 0 이 아니
   assert.equal(axisValueOf(undefined, { axis: 'demandWindows', path: 'energy.closed' }), undefined)
 })
 
-test('경로 따라가기는 중간 부재에서 멈춘다 — 던지지 않는다', () => {
+test('경로 따라가기는 중간 부재에서 멈춘다 — 오류를 내지 않는다', () => {
   assert.equal(atPath({ a: { b: 1 } }, 'a.b'), 1)
   assert.equal(atPath({ a: null }, 'a.b'), undefined)
   assert.equal(atPath(undefined, 'a.b'), undefined)
@@ -85,3 +85,103 @@ test('커널 선언과 상태의 모양이 맞는다 — 선언한 경로에 정
   assert.equal(Array.isArray(windows), true, '선언한 경로에 목록이 있어야 한다')
   assert.equal(windows.length, 1, '마감된 구간 하나')
 })
+
+/*
+ * ── 규칙의 집이 하나인지 **기계가 지킨다** (2026-08-21) ──────────────────────
+ *
+ * 위 단위 시험은 처음부터 초록이었다. 함수는 옳았고, **호출부 하나가 그 함수를 지나지 않았다** —
+ * `twin-model-item-query.ts` 가 `(snap as any)[axis]` 로 축 이름을 직접 읽었다. 그래서 개념 지도의
+ * 카드는 수요 구간을 **42** 로 세는데 그 개념을 열면 **0건**이 나왔다. 사용자에게는 「트윈이 비어
+ * 있다」로 읽힌다.
+ *
+ * 그 함정은 형제 파일 주석에 이미 적혀 있었다(「축 이름으로만 읽으면 중첩된 축이 언제나 관측 없음이
+ * 된다 — 에너지의 수요 구간이 그렇다」). **적어 두는 것으로는 막히지 않았다.** 그래서 센다.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SVC = fileURLToPath(new URL('../server/service/twin-model', import.meta.url))
+
+/**
+ * 상태에서 축을 **이름으로** 읽는 모양 — `snap[axis]` · `(state as any)[axis]` 류.
+ *
+ * 앞에 `\b` 를 둔다: 처음에는 없어서 `const` 안의 `st` 를 잡아 `ROW_BACKED[axis]`(조회표이지 상태
+ * 읽기가 아니다)를 위반으로 냈다. **거짓 빨강을 내는 가드는 없는 것보다 나쁘다** — 이름이 근거다.
+ */
+const BY_NAME = /\(?\s*\b(?:snap|state)\b[^)\n]*\)?\s*\[\s*axis\s*\]/g
+
+test('축을 이름으로 읽는 자리가 없다 — 선언된 경로를 지나야 중첩된 축이 보인다', () => {
+  const offenders: string[] = []
+  for (const f of readdirSync(SVC).filter(n => n.endsWith('.ts'))) {
+    const src = readFileSync(join(SVC, f), 'utf8')
+    for (const line of src.split('\n')) {
+      /* 주석은 규칙이 아니라 설명이다 — 함정을 적어 둔 줄이 스스로 위반으로 잡히면 신호가 묻힌다. */
+      const code = line.replace(/\/\*.*?\*\//g, '').replace(/\/\/.*$/, '')
+      if (code.trimStart().startsWith('*')) continue
+      if (BY_NAME.test(code)) offenders.push(`${f}: ${line.trim()}`)
+      BY_NAME.lastIndex = 0
+    }
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `축을 이름으로 읽는 자리가 있다 — \`axisValueOf(state, 축선언)\` 을 쓰십시오.\n${offenders.join('\n')}`
+  )
+})
+
+test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는 대상이 있다', () => {
+  /* 가드가 지킬 것이 없으면 그 가드는 초록으로 거짓을 말한다. 대상이 실재하는지 함께 본다. */
+  const req = createRequire(import.meta.url)
+  const { TWIN_AXES } = req('@operato/twin-kernel')
+  const nested = (TWIN_AXES as any[]).filter(a => a.path)
+
+  assert.ok(nested.length > 0, '경로를 가진 축이 하나도 없으면 이 가드는 의미가 없다')
+  assert.ok(
+    nested.some(a => a.axis === 'demandWindows'),
+    `수요 구간이 경로 축이어야 한다 — 실제 경로 축: ${nested.map(a => a.axis).join(', ')}`
+  )
+})
+
+/*
+ * ── 무엇이 항목을 가리키는지도 **선언이 말한다** (2026-08-21) ─────────────────
+ *
+ * 개념 지도의 수요 구간을 열면 여섯 구간이 모두 「식별자 없음 — 참조할 수 없는 항목입니다」로 보였다.
+ * 값(구간 시작·종료·최대수요)은 실재하는데 **가리킬 수 없다고 말한 것**이다.
+ *
+ * 원인은 축이 사는 자리를 짐작했던 것과 **같은 부류**다: 소비처가 `id`·`key`·`gtin` 을 순서대로
+ * 짐작했고, 수요 구간에는 그 셋이 없다. 그것은 결함이 아니다 — 구간의 정체성은 **언제 시작했나**이고
+ * 커널도 그것으로 키를 만든다(`contract-projected-over:<startMs>`).
+ */
+test('id 가 없는 상태 축은 무엇이 항목을 가리키는지 선언한다', () => {
+  const req2 = createRequire(import.meta.url)
+  const { TWIN_AXES } = req2('@operato/twin-kernel')
+  const dw = (TWIN_AXES as any[]).find(a => a.axis === 'demandWindows')
+
+  assert.ok(dw, '수요 구간 축이 있어야 한다')
+  assert.equal(dw.idField, 'startMs', '구간의 정체성은 시작 시각이다')
+})
+
+test('항목 질의가 짐작하지 않는다 — 선언된 자리를 읽는다', () => {
+  /*
+   * 기계가 지킨다. 주석에 적어 두는 것으로는 막히지 않는 것을 오늘 이미 겪었다(축이 사는 자리를
+   * 짐작한 자리 셋이 형제 파일 주석의 경고에도 남아 있었다).
+   */
+  /*
+   * ── **파일 이름에 묶지 않는다** (2026-08-22) ────────────────────────────────
+   * 예전에는 `twin-model-item-query.ts` 하나만 읽었다. 다른 레인이 `idOf` 를 `name-index.ts` 로
+   * 옮기자(기능은 배열 차례까지 온전했다) 이 가드가 **거짓 빨강**을 냈다. 가드가 지켜야 하는 것은
+   * 「그 파일에 그 낱말이 있나」가 아니라 「**이 서비스 어딘가에서 선언된 식별 자리를 읽나**」다.
+   *
+   * 그래서 서비스 폴더를 훑는다 — 옮겨도 따라간다. 옮길 자유를 막는 가드는 사람을 가드와 싸우게 만든다.
+   */
+  const sources = readdirSync(SVC, { recursive: true } as any)
+    .filter((f: any) => String(f).endsWith('.ts'))
+    .map((f: any) => readFileSync(join(SVC, String(f)), 'utf8'))
+  const all = sources.join('\n')
+
+  assert.match(all, /idField/, '선언된 식별 자리를 읽어야 한다(이 서비스 어딘가에서)')
+  /* `x?.id === itemId` 로 찾던 자리가 남아 있으면 그 축의 항목은 열 수 없다. */
+  assert.doesNotMatch(all, /find\(\(x: any\) => x\?\.id === itemId\)/, 'id 로만 찾는 자리가 남지 않았다')
+})

package/test/boot-resume.test.ts

@@ -37,23 +37,79 @@ function methodOf(src: string, name: string): string {
 test('부팅이 런타임까지 되살린다 — 상태 복구만으로는 도는 트윈이 아니다', () => {
   const body = methodOf(engine, 'bootstrap')
   assert.match(body, /resumeRow\(row\)/, 'bootstrap 이 행마다 재개를 시도해야 한다')
-  /* 예전 모양: 스냅샷을 `recovered` 에 담고 `continue` 로 끝났다 — 그것으로 되돌아가지 않게. */
-  assert.match(body, /for \(const row of rows\) await this\.resumeRow\(row\)/, '복구 뒤 재개 루프가 있어야 한다')
+  /* 예전 모양: 스냅샷을 `recovered` 에 담고 `continue` 로 끝났다 — 그것으로 되돌아가지 않게.
+     한 줄로 못 박지 않는다(2026-08-21 에 되살리기 사이 양보가 들어와 줄 모양이 바뀌었다) —
+     **행 전부를 돌며 재개한다**는 사실만 본다. */
+  assert.match(body, /for \(const row of rows\)[\s\S]{0,400}?await this\.resumeRow\(row\)/, '복구 뒤 재개 루프가 있어야 한다')
+  /* 되살리기 사이에 루프를 비워 준다 — 없으면 부팅 내내 HTTP 가 서지 않는다. */
+  assert.match(body, /BOOT_YIELD_MS/, '되살리기 사이에 양보가 있어야 한다')
 })
 
 test('모드를 지어내지 않는다 — 미러였던 것은 미러로 되살린다', () => {
-  const body = methodOf(engine, 'resumeRow')
-  assert.match(body, /restartPolicy === 'resync'/, '선언된 모드를 보고 갈라야 한다')
-  assert.match(body, /this\.startLive\(/, '미러는 관측 구동으로 세운다')
-  assert.match(body, /this\.startFromRegistry\(/, '시뮬은 등록부의 모드 그대로 세운다')
+  /*
+   * ── 갈림은 **문 안**에 있다 (2026-08-20) ──────────────────────────────────
+   * 예전에는 이 판단이 `resumeRow` 에 있었다. 그래서 부팅으로 살아난 미러는 관측 구동이었지만, 사람이
+   * 화면에서 시작한 미러는 **시뮬로 떴다** — 그 문(`startFromRegistry`)에는 갈림이 없었기 때문이다.
+   * 시뮬로 뜬 미러는 유입을 한 건도 받지 못하고(`ingestLive` 가 0 을 돌려준다), 화면에는 「running」이라
+   * 적힌다. 같은 선언이 두 결과를 내지 않도록 갈림을 문 안으로 옮겼고, 이 시험이 그 자리를 지킨다.
+   */
+  const resumeRow = methodOf(engine, 'resumeRow')
+  assert.match(resumeRow, /await this\.startFromRegistry\(domainId, instanceId\)/, '부팅도 같은 문을 지난다')
+
+  const door = methodOf(engine, 'startFromRegistry')
+  assert.match(door, /const policy = restartPolicy \?\? readRestartPolicy\(/, '선언된 값을 엄격히 읽는다')
+  assert.match(door, /if \(policy === 'resync'\)/, '문이 선언된 모드를 보고 갈라야 한다')
   /*
    * 미러 가지 안을 그대로 떠서 본다 — 미러를 시뮬로 세우면 관측 트윈이 **스스로 물건을 옮긴다**
    * (없던 움직임을 만드는 것이다). 단어의 거리로 재면 로그·주석에 걸려 헛돈다.
    */
-  const at = body.indexOf("restartPolicy === 'resync'")
-  const mirrorBranch = body.slice(at, body.indexOf('} else {', at))
-  assert.match(mirrorBranch, /startLive\(/, '미러 가지는 관측 구동으로 세워야 한다')
-  assert.equal(mirrorBranch.includes('startFromRegistry'), false, '미러 가지에서 시뮬 기동을 부른다 — 없던 움직임을 만든다')
+  const at = door.indexOf("if (policy === 'resync')")
+  const mirrorBranch = door.slice(at, door.indexOf('\n    }', at))
+  assert.match(mirrorBranch, /return this\.startLive\(/, '미러 가지는 관측 구동으로 세우고 거기서 끝난다')
+  assert.equal(mirrorBranch.includes('this.start('), false, '미러 가지에서 시뮬 기동을 부른다 — 없던 움직임을 만든다')
+  /* 미러도 공간의 시각 기준을 받는다 — 교대의 HH:MM 을 어느 기준으로 읽나(부팅과 같은 규칙). */
+  assert.match(mirrorBranch, /withSpaceTimeBase\(/)
+})
+
+test('reset 은 선언대로 저널을 비운다 — 씨앗 재현은 백지에서 시작한다', () => {
+  /*
+   * 「seed 재현」은 백지에서 다시 시작한다는 뜻인데, 예전에는 그 선언이 구현되지 않아 `reset` 트윈이
+   * 사실상 이어졌다. 사실을 지우는 동작이라 순서를 지켜 켰다: 먼저 사람이 정책을 다시 선언할 문을 만들고
+   * (`setTwinRestartPolicy`), 이력을 두고 볼 트윈을 `resume` 으로 옮긴 뒤에 켰다.
+   */
+  const door = methodOf(engine, 'startFromRegistry')
+  const at = door.indexOf("if (policy === 'reset')")
+  assert.ok(at > 0, '문이 reset 을 갈라야 한다')
+  const branch = door.slice(at, door.indexOf('\n    }', at))
+  assert.match(branch, /resetJournal\(domainId, instanceId\)/, '저널을 비운다')
+  /* 벤치 사본은 예외다 — 누군가 지켜보는 실험의 기록을 기동이 지우면 실험이 사라진다. */
+  assert.match(branch, /purpose !== 'bench'/, '벤치 실험의 기록은 지우지 않는다')
+  /* 웜스타트보다 **먼저** 지워야 한다 — 뒤에 지우면 이미 옛 상태를 읽어 실은 뒤다. */
+  assert.ok(at < door.indexOf('this.recovered[key]'), '지우기가 웜스타트보다 앞에 있어야 한다')
+})
+
+test('저널만 지우면 씨앗 재현이 아니다 — 체크포인트·사슬도 무효로 만든다', () => {
+  /*
+   * 웜스타트는 체크포인트를 **먼저** 본다. 저널만 지우면 백지로 시작한 트윈에 옛 상태가 되살아나
+   * 「저널은 비었는데 재고가 있는」 트윈이 된다. 시간여행이 딛는 사슬 캐시도 지워진 리비전을 가리킨다.
+   */
+  const body = methodOf(engine, 'resetJournal')
+  assert.match(body, /SNAPSHOT_CACHE_ID[\s\S]{0,120}state: null/, '체크포인트를 「없음」으로 덮는다')
+  assert.match(body, /CHAIN_INDEX_CACHE_ID[\s\S]{0,80}revisions: \[\]/, '사슬 색인도 비운다')
+  /* 실패를 삼키지 않는다 — 무효화가 실패하면 다음 기동이 옛 상태를 물려받는다. */
+  assert.match(body, /catch[\s\S]{0,120}twinWarn/)
+})
+
+test('정책을 다시 선언하는 문이 있다 — 없으면 선언과 쓰임이 영원히 어긋난다', () => {
+  const src = readFileSync(
+    fileURLToPath(new URL('../server/service/twin-lifecycle/twin-lifecycle-mutation.ts', import.meta.url)),
+    'utf-8'
+  )
+  assert.match(src, /async setTwinRestartPolicy\(/, '만든 뒤에 고칠 길이 있어야 한다')
+  /* 값은 엄격히 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 조용히 결정된다. */
+  assert.match(src, /readRestartPolicy\(restartPolicy, /)
+  /* 도는 런타임을 조용히 갈아 끼우지 않는다 — 다르다는 사실을 답에 담는다. */
+  assert.match(src, /appliesAtNextStart/)
 })
 
 test('되살리지 못한 행은 stopped 로 적는다 — 「도는 중」이라 말하는 채로 두지 않는다', () => {
@@ -61,7 +117,7 @@ test('되살리지 못한 행은 stopped 로 적는다 — 「도는 중」이
   assert.match(resume, /catch[\s\S]{0,80}markStopped/, '실패를 삼키면 등록부가 계속 거짓을 말한다')
   const mark = methodOf(engine, 'markStopped')
   assert.match(mark, /status: 'stopped'/, '등록부에 실제로 적어야 한다')
-  assert.match(mark, /console\.(warn|error)/, '되살리지 못한 사실은 로그에도 남아야 한다')
+  assert.match(mark, /twin(Warn|Error)/, '되살리지 못한 사실은 로그에도 남아야 한다')
 })
 
 test('벤치 사본은 무인으로 되살아나지 않는다 — 실험은 재기동을 넘기지 못한다', () => {
@@ -87,36 +143,46 @@ test('부팅 훅이 엔진 다음에 피드를 붙인다 — 순서가 뒤집히
 
 /*
  * ── 부팅 재개가 드러낸 것 (2026-08-14 실측) ─────────────────────────────────
- * 트윈 14개가 실제로 돌기 시작하자 호스트가 죽었다. 원인은 재개가 아니라 **방송 두 가지**였다:
- *  ① 시뮬은 delta 마다 곧바로 전 상태를 투영해 방송했다 — 한 tick 이 사실을 수백 개 내면 그 반복이
+ * 트윈 14개가 실제로 돌기 시작하자 호스트가 죽었다. 원인은 재개가 아니라 **브로드캐스팅 두 가지**였다:
+ *  ① 시뮬은 delta 마다 곧바로 전 상태를 투영해 브로드캐스팅했다 — 한 tick 이 사실을 수백 개 내면 그 반복이
  *     이벤트 루프를 35초 막았고(단계 합은 32ms 였다), 그 사이 구독자는 아무것도 빼내지 못했다.
- *  ② 밀린 push 가 1024를 넘자 pubsub 이 던졌고, 타이머 콜백을 타고 올라온 그 예외가 프로세스를 끝냈다.
+ *  ② 밀린 push 가 1024를 넘자 pubsub 이 오류를 냈고, 타이머 콜백을 타고 올라온 그 예외가 프로세스를 끝냈다.
  * 둘 다 재개 없이도 있던 결함이다 — 재개가 그것을 매일 아침 만나게 만들었을 뿐이다.
  */
-test('시뮬 방송도 모아서 한 번 — delta 마다 전 상태를 투영하지 않는다', () => {
+test('시뮬 브로드캐스팅도 모아서 한 번 — delta 마다 전 상태를 투영하지 않는다', () => {
   const at = engine.indexOf("if (msg.kind === 'delta')")
   assert.ok(at >= 0, 'sim delta 처리 자리가 없다')
-  const body = engine.slice(at, at + 1400)
+  const body = engine.slice(at, at + 2600)
   assert.match(body, /inst\.dirty = true/, 'dirty 로 표시하고')
   assert.match(body, /ensureBroadcastCoalescer\(\)/, '주기 flush 에 맡겨야 한다')
-  assert.equal(/this\.publishEntityData\(inst\)/.test(body), false, 'delta 마다 곧바로 방송하는 모양으로 되돌아갔다')
+  assert.equal(/this\.publishEntityData\(inst\)/.test(body), false, 'delta 마다 곧바로 브로드캐스팅하는 모양으로 되돌아갔다')
 })
 
-test('flush 가 시뮬도 본다 — 라이브만 보면 시뮬 방송이 멈춘 채 남는다', () => {
+test('flush 가 시뮬도 본다 — 브로드캐스팅과 저널은 둘 다, state 채널은 라이브만', () => {
   const body = methodOf(engine, 'flushLiveBroadcasts')
   assert.equal(/mode !== 'live'\) continue/.test(body), false, '시뮬을 건너뛰는 모양으로 되돌아갔다')
-  assert.match(body, /const isLive = inst\.mode === 'live'/, '모드는 가르되 둘 다 방송해야 한다')
-  /* 저널·state 채널은 시뮬이 자기 콜백에서 이미 처리한다 — 여기서 또 하면 두 번 적힌다. */
-  assert.match(body, /if \(!isLive\) continue/, '시뮬은 엔티티 방송까지만')
+  assert.match(body, /const isLive = inst\.mode === 'live'/, '모드는 가르되 둘 다 브로드캐스팅해야 한다')
+  /*
+   * **저널은 두 구동이 같은 문을 쓴다** (2026-08-20, ingest-scale §7.1). 예전에는 시뮬이 델타마다 단건
+   * 저장을 했고 그것이 규모에서 호스트를 먹었다(CPU 100%·질의 8~14초). 그래서 flush 가 시뮬의 저널도
+   * 흘린다 — 그 호출이 `if (!isLive) continue` **앞**에 있어야 시뮬 몫이 빠지지 않는다.
+   */
+  const flushAt = body.indexOf('this.flushJournal(inst)')
+  const liveOnlyAt = body.indexOf('if (!isLive) continue')
+  assert.ok(flushAt >= 0, '저널을 흘리는 자리가 없다')
+  assert.ok(liveOnlyAt >= 0, 'state 채널을 라이브로 가르는 자리가 없다')
+  assert.ok(flushAt < liveOnlyAt, '저널 flush 가 라이브 전용 구간 뒤로 밀리면 시뮬의 사실이 쌓인 채 남는다')
+  /* state 채널은 시뮬이 자기 콜백에서 이미 보낸다 — 여기서 또 보내면 같은 신호가 두 번 간다. */
+  assert.ok(body.indexOf("twinState: { instanceId: inst.id") > liveOnlyAt, 'state 채널 브로드캐스팅은 라이브 구간에 있어야 한다')
 })
 
 test('구독자 하나가 호스트를 죽이지 못한다 — 그리고 못 보낸 것을 보낸 것으로 적지 않는다', () => {
-  /* 직접 방송은 **가드 안에 하나**여야 한다 — 그 밖의 호출은 예외가 그대로 올라가는 길이다. */
+  /* 직접 브로드캐스팅은 **가드 안에 하나**여야 한다 — 그 밖의 호출은 예외가 그대로 올라가는 길이다. */
   const guardBody = methodOf(engine, 'publishGuarded')
-  assert.equal((engine.match(/pubsub\.publish\(/g) ?? []).length, 1, '가드를 거치지 않는 직접 방송이 남아 있다')
+  assert.equal((engine.match(/pubsub\.publish\(/g) ?? []).length, 1, '가드를 거치지 않는 직접 브로드캐스팅이 남아 있다')
   assert.match(guardBody, /pubsub\.publish\(/, '그 하나는 가드 안에 있어야 한다')
-  assert.match(guardBody, /catch/, '방송 실패를 잡아야 한다(타이머 콜백에서 던지면 프로세스가 끝난다)')
-  assert.match(guardBody, /console\.warn/, '못 보낸 사실은 남아야 한다(삼키면 「보냈는데 낡았다」가 된다)')
+  assert.match(guardBody, /catch/, '브로드캐스팅 실패를 잡아야 한다(타이머 콜백에서 오류가 나면 프로세스가 끝난다)')
+  assert.match(guardBody, /twinWarn/, '못 보낸 사실은 남아야 한다(삼키면 「보냈는데 낡았다」가 된다)')
   /* 시그니처를 남겨 두면 다음 주기에 「무변화」로 건너뛰고 그 태그는 영원히 낡는다. */
   assert.match(engine, /if \(!this\.publishGuarded\('data'[\s\S]{0,80}sigs\.delete\(tag\)/, '실패한 태그의 시그니처를 되돌려야 한다')
 })
@@ -124,7 +190,7 @@ test('구독자 하나가 호스트를 죽이지 못한다 — 그리고 못 보
 /*
  * ── 굶김 안전망 (2026-08-14) ─────────────────────────────────────────────────
  * 시뮬 틱은 메인 이벤트 루프에서 돈다 — 한 트윈의 틱이 길어지면 그 시간만큼 호스트 전체가 멈춘다
- * (실측 34.9초). 방송 반복은 걷어냈지만 커널 틱 자체는 여전히 메인 루프에 있고, 근본 해결(분산)은
+ * (실측 34.9초). 브로드캐스팅 반복은 걷어냈지만 커널 틱 자체는 여전히 메인 루프에 있고, 근본 해결(분산)은
  * 이연됐다. 그 사이의 안전망이 이것이다: **호스트를 굶기는 트윈은 멈춘다.**
  */
 test('굶김은 예산과 다른 문턱으로 판정한다 — 조금 느린 트윈을 내리지 않는다', () => {

package/test/broadcast-cost-baseline.test.ts

@@ -0,0 +1,200 @@
+/*
+ * **브로드캐스팅 한 번의 비용** — 200ms 마다 무엇을 만드는지 값으로 남긴다 (2026-08-21).
+ *
+ * ── 왜 재는가 ───────────────────────────────────────────────────────────────
+ * `publishEntityData` 는 브로드캐스팅 주기마다 ① 상태를 통째로 투영하고(`getSnapshot`) ② 엔티티마다 payload 를
+ * 만들고(`buildEntityDeltas`) ③ 그 payload 를 문자열로 만들어 이전 것과 비교한다. ③ 의 비교가 없던
+ * 시절에는 바뀌지 않은 것까지 전송했고, 그 낭비는 2026-08-14 에 없앴다 — 그런데 없앤 것은 **전송**이고
+ * ①②③ 의 **계산은 그대로** 남았다. 물품이 수천 개인 트윈에서는 하나만 움직여도 수천 개를 만들어
+ * 문자열로 바꾼 뒤 「같다」를 확인하고 버린다.
+ *
+ * 고치기 전에 세 축의 몫을 값으로 남긴다. 짐작으로 고치면 무엇이 나아졌는지 말할 수 없다.
+ *
+ * ── 고친 뒤 (2026-08-21) ────────────────────────────────────────────────────
+ * 이제 브로드캐스팅은 **건드린 물품만** 만든다(`buildEntityDeltas` 의 `scope.items`). 그래서 이 시험은 두
+ * 창을 나란히 잰다: 범위를 모를 때(전부) 와 물품 하나를 건드렸을 때(좁힘).
+ *
+ * ── 게이트는 시간이 아니다 ──────────────────────────────────────────────────
+ * 기계마다·스위트 병렬 실행마다 시간은 달라진다(같은 코드에서 3.2배와 14.8배가 나온 적이 있다). 그래서
+ * 단정은 **시간과 무관한 사실**로 한다: 좁힌 창이 만든 물품 payload 가 말한 것 하나뿐인가. 시간은
+ * 기준선으로 출력만 하고, 여러 번 재 그중 **가장 짧은 값**을 적는다(GC·JIT 잡음을 덜 타는 값).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { MesKernel, type CanonicalEnvelope, type ProductionSpec, type ScenarioDef, type TwinModelDef } from '@operato/twin-kernel'
+
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
+
+const COMMISSIONING = 'urn:epcglobal:cbv:bizstep:commissioning'
+/* GS1 이 예제로 지정한 `952` 대역 — 실 배정 대역을 픽스처에 두지 않는다(CBV 2.0). */
+const PREFIX = '9521321'
+const RAW_GTIN = `urn:epc:idpat:sgtin:${PREFIX}.0001.*`
+
+const DEFINITION: any = {
+  materials: [
+    { key: 'raw', label: '원자재', locationType: 'raw-store' },
+    { key: 'product', label: '완제품', locationType: 'fg-store' }
+  ],
+  locationTypes: [
+    { key: 'raw-store', label: '자재 보관' },
+    { key: 'cut-st', label: '절단' },
+    { key: 'fg-store', label: '완제품 보관' }
+  ],
+  resourceTypes: [{ key: 'cutter', label: '절단기' }],
+  operations: [{ key: 'cut', label: '절단', intent: 'process', locationType: 'cut-st', resourceType: 'cutter', bizStep: COMMISSIONING }],
+  routes: [{ key: 'line', label: '라인', steps: ['cut'] }],
+  recipes: [{ key: 'prod', label: '완제품', inputs: [{ material: 'raw', qty: 1 }], outputs: [{ material: 'product', qty: 1 }], route: 'line' }]
+}
+const SPEC: ProductionSpec = {
+  definition: DEFINITION,
+  binding: { raw: '0001', product: '0002' },
+  identity: { documentTypes: { workorder: '403' }, namespaces: [`urn:epc:idpat:sgtin:${PREFIX}.`] },
+  companyPrefix: PREFIX
+}
+
+function board(): TwinModelDef {
+  return {
+    locations: [
+      { id: 'raw-store', type: 'raw-store', capacity: 1_000_000 },
+      { id: 'cut-st', type: 'cut-st', capacity: 1_000_000 },
+      { id: 'fg-store', type: 'fg-store', capacity: 1_000_000 }
+    ],
+    equipment: Array.from({ length: 8 }, (_, i) => ({ id: `cutter-${i}`, kind: 'cutter', homeLocation: 'cut-st' }))
+  } as TwinModelDef
+}
+
+function scenario(ordersPerHour: number): ScenarioDef {
+  return {
+    seed: 9,
+    generators: [
+      {
+        kind: 'inbound-arrival',
+        stimulus: 'arrival',
+        rate: { distribution: 'constant', meanPerHour: ordersPerHour * 4 },
+        content: { skuMix: [{ gtin: RAW_GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } }
+      },
+      {
+        kind: 'workorder',
+        stimulus: 'order',
+        rate: { distribution: 'constant', meanPerHour: ordersPerHour },
+        content: { skuMix: [{ gtin: 'wo', weight: 1 }], qtyPerLine: { min: 1, max: 1 } }
+      }
+    ]
+  } as ScenarioDef
+}
+
+interface Row {
+  items: number
+  entities: number
+  payloads: number
+  /** 물품 하나만 건드렸다고 말했을 때 만드는 payload 수 — 좁히기가 듣는지. */
+  scopedPayloads: number
+  snapshotMs: number
+  /** 매핑 + 시그니처(다섯 번 중 가장 짧은 값). */
+  buildMs: number
+  broadcastMs: number
+  /** 좁힌 창의 매핑 + 시그니처 시간 — 투영은 그대로 남는다(커널 몫). */
+  scopedMs: number
+  /** 만든 payload 목록 — 단정이 「무엇을 만들었나」를 직접 본다(수만으로는 축을 구별하지 못한다). */
+  fullDeltas: any[]
+  scopedDeltas: any[]
+}
+
+/** 한 규모에서 **브로드캐스팅 한 번**의 세 축을 잰다. 상태는 미리 쌓아 두고, 재는 것은 브로드캐스팅뿐이다. */
+function measure(ticks: number, ordersPerHour: number): Row {
+  const k: any = new MesKernel('bench', undefined, SPEC)
+  k.onEvent((_e: CanonicalEnvelope) => {})
+  k.loadTwinModel(board())
+  k.scenario.load(scenario(ordersPerHour))
+  k.scenario.start()
+  for (let i = 0; i < ticks; i++) k.tick(1000)
+
+  /* ① 상태 투영 — 자리·물품·자원·작업·오더를 새 객체로 만든다. */
+  const t0 = performance.now()
+  const st = k.getSnapshot()
+  const t1 = performance.now()
+  /*
+   * ②③ payload 만들기 + 시그니처 — **다섯 번 재 가장 짧은 값을 쓴다.** 한 번만 재면 그 순간의 GC 가
+   * 값에 들어가, 좁힌 창이 전부 만든 창보다 오래 걸린 것처럼 보이는 일이 실제로 있었다.
+   */
+  const pass = (scope?: { items: ReadonlySet<string> }) => {
+    let best = Infinity
+    let built: any[] = []
+    let chars = 0
+    for (let i = 0; i < 5; i++) {
+      const a = performance.now()
+      built = buildEntityDeltas(st, 'bench', scope)
+      chars = 0
+      for (const d of built) chars += JSON.stringify(d.data).length
+      best = Math.min(best, performance.now() - a)
+    }
+    return { built, chars, ms: Math.round(best * 10) / 10 }
+  }
+
+  const fullPass = pass()
+  const deltas = fullPass.built
+  const chars = fullPass.chars
+
+  const entities =
+    st.locations.length + st.items.length + st.equipment.length + (st.assets?.length ?? 0) + (st.persons?.length ?? 0) + st.tasks.length + st.orders.length
+
+  /* ④ 좁힌 창 — 물품 하나만 건드렸다고 말한 경우. 같은 상태로 재야 비교가 성립한다. */
+  const one = new Set<string>([st.items[0]?.epc].filter(Boolean) as string[])
+  const scopedPass = pass({ items: one })
+  const scoped = scopedPass.built
+
+  assert.ok(chars > 0 && scopedPass.chars > 0, '문자열을 만들지 않았다면 측정이 성립하지 않는다')
+  const ms = (a: number, b: number) => Math.round((b - a) * 10) / 10
+  return {
+    items: st.items.length,
+    entities,
+    payloads: deltas.length,
+    scopedPayloads: scoped.length,
+    snapshotMs: ms(t0, t1),
+    buildMs: fullPass.ms,
+    broadcastMs: Math.round((ms(t0, t1) + fullPass.ms) * 10) / 10,
+    scopedMs: scopedPass.ms,
+    fullDeltas: deltas,
+    scopedDeltas: scoped
+  }
+}
+
+test('브로드캐스팅 한 번의 비용 — 좁힌 창은 건드린 물품만 만든다', () => {
+  /* 예열은 가장 큰 규모로 한 번 버린다 — 작은 규모부터 재면 뒤 측정이 앞의 JIT 이득을 본다. */
+  measure(600, 3600)
+
+  const rows = [measure(600, 60), measure(600, 480), measure(600, 3600)]
+
+  console.log('[브로드캐스팅 한 번의 비용 · MES 선언본]')
+  for (const r of rows) {
+    console.log(
+      `  물품 ${String(r.items).padStart(5)} · 엔티티 ${String(r.entities).padStart(5)} — payload ${String(r.payloads).padStart(5)}개 · ` +
+        `투영 ${String(r.snapshotMs).padStart(6)}ms · 만들기 ${String(r.buildMs).padStart(6)}ms · 합 ${r.broadcastMs}ms` +
+        `  ▸ 좁힌 창: payload ${String(r.scopedPayloads).padStart(4)}개 · ${r.scopedMs}ms`
+    )
+  }
+
+  /* 측정이 성립했는지 — 규모가 실제로 커져야 비교에 뜻이 있다. */
+  assert.ok(rows[0].items > 0, '물품이 쌓여야 한다')
+  assert.ok(rows[rows.length - 1].items > rows[0].items * 3, '규모가 실제로 커져야 한다')
+
+  /*
+   * ── 고친 뒤의 단정 (2026-08-21) ──────────────────────────────────────────
+   * 전부 만드는 창은 여전히 엔티티 수에 비례한다 — 그 창은 그물이고 주기마다 한 번뿐이다(§그물).
+   *
+   * **좁힌 창이 만드는 물품 payload 는 말한 것 하나뿐이다.** 이것이 시간과 무관한 단정이다. 기울기로
+   * 재지 않는 이유는 이 픽스처가 물품과 함께 오더·작업도 늘리기 때문이다 — 그 축은 좁히지 않으므로
+   * (자리 점유·집약과 같은 이유) 기울기에는 남의 몫이 섞인다.
+   *
+   * 실 현장의 비율은 물품 쪽이 훨씬 무겁다(hatio-us: 물품 2,805 · 오더 192 · 작업 221). 이 픽스처는
+   * 오더를 과하게 실은 쪽이므로, 여기서 보이는 절감은 **실 현장보다 작다.**
+   */
+  const last = rows[rows.length - 1]
+  const itemPayloads = (ds: any[]) => ds.filter(d => d?.data?.entity === 'item').length
+  assert.equal(itemPayloads(last.fullDeltas), last.items, '전부 만드는 창은 물품 전부를 만든다')
+  assert.equal(itemPayloads(last.scopedDeltas), 1, '좁힌 창은 건드린 물품 하나만 만들어야 한다')
+  /* 집약은 좁히지 않는다 — 목록 전체가 한 payload 라서 한 물품이 바뀌면 통째로 새로 만든다. */
+  const aggregates = (ds: any[]) => ds.filter(d => String(d.tag).startsWith('__')).length
+  assert.equal(aggregates(last.scopedDeltas), aggregates(last.fullDeltas), '집약 뷰는 좁힌 창에서도 그대로 나간다')
+})

package/test/broadcast-period.test.ts

@@ -0,0 +1,58 @@
+/*
+ * 브로드캐스팅 주기는 **재 본 비용에 맞춘다** (2026-08-21).
+ *
+ * 한 번의 브로드캐스팅은 상태 크기에 비례한다(실측: 물품 2,400 개 트윈 하나가 4.5ms). 트윈이 스무 개면
+ * 200ms 주기에서 90ms 가 브로드캐스팅이고, 그 시간에는 HTTP 도 구독도 서지 못한다. 그래서 브로드캐스팅이 주기의
+ * 일정 몫을 넘게 쓰면 주기를 늘리고, 여유가 생기면 되돌린다.
+ *
+ * 지키는 것:
+ *  ① 무거우면 늘린다 — 상한까지만.
+ *  ② 가벼워지면 되돌린다 — 원래 주기 아래로는 내려가지 않는다.
+ *  ③ 경계에서 늘리고 줄이기를 반복하지 않는다(문턱이 둘이다).
+ *  ④ **늘렸다는 사실을 센다** — 조용히 늦추면 사람은 화면이 낡은 이유를 알 수 없다.
+ */
+import { test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { TwinEngine } = req('../dist-server/engine/twin-engine.js')
+
+/** 주기 조정만 부른다 — 실제 브로드캐스팅(pubsub·DB)은 이 판정과 무관하다. */
+const adjust = (flushMs: number) => (TwinEngine as any).adjustBroadcastPeriod(flushMs)
+
+beforeEach(() => {
+  TwinEngine.broadcastPeriodMs = TwinEngine.BROADCAST_COALESCE_MS
+  TwinEngine.broadcastBackoffs = 0
+})
+
+test('브로드캐스팅이 주기의 몫을 넘게 쓰면 주기를 늘린다 — 상한까지만', () => {
+  const base = TwinEngine.BROADCAST_COALESCE_MS
+  adjust(base) // 주기를 통째로 쓴 셈
+  assert.equal(TwinEngine.broadcastPeriodMs, base * 2)
+
+  for (let i = 0; i < 10; i++) adjust(TwinEngine.broadcastPeriodMs)
+  assert.equal(TwinEngine.broadcastPeriodMs, TwinEngine.BROADCAST_MAX_COALESCE_MS, '상한 위로는 올라가지 않는다')
+})
+
+test('늘렸다는 사실을 센다 — 조용히 늦추지 않는다', () => {
+  adjust(TwinEngine.BROADCAST_COALESCE_MS)
+  assert.equal(TwinEngine.broadcastBackoffs, 1)
+})
+
+test('가벼워지면 되돌린다 — 원래 주기 아래로는 내려가지 않는다', () => {
+  adjust(TwinEngine.BROADCAST_COALESCE_MS) // 200 → 400
+  assert.ok(TwinEngine.broadcastPeriodMs > TwinEngine.BROADCAST_COALESCE_MS)
+
+  for (let i = 0; i < 10; i++) adjust(0.5)
+  assert.equal(TwinEngine.broadcastPeriodMs, TwinEngine.BROADCAST_COALESCE_MS)
+})
+
+test('경계에서 늘리고 줄이기를 반복하지 않는다 — 문턱이 둘이다', () => {
+  const base = TwinEngine.BROADCAST_COALESCE_MS
+  /* 늘리는 문턱(몫)과 되돌리는 문턱(몫의 절반) 사이의 값 — 어느 쪽도 아니어야 한다. */
+  const between = base * TwinEngine.BROADCAST_LOAD_RATIO * 0.75
+  for (let i = 0; i < 5; i++) adjust(between)
+  assert.equal(TwinEngine.broadcastPeriodMs, base, '문턱 사이의 값은 주기를 바꾸지 않는다')
+  assert.equal(TwinEngine.broadcastBackoffs, 0)
+})

package/test/canonical-ingest-vocabularies.test.ts

@@ -79,7 +79,7 @@ test('설비 에너지 상태는 EPCIS 도 계량도 아닌 자기 어휘로 들
     [
       { equipmentId: 'pv-1', at: '2026-08-15T09:00:00.000Z', generatedKW: 210 },
       { meterId: 'm-1', kW: 800, at: '2026-08-15T09:00:00.000Z' },
-      { epc: 'urn:epc:id:sgtin:1.2.3', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing' }
+      { epc: 'urn:epc:id:sgtin:9521321.012345.3', action: 'OBSERVE', bizStep: 'urn:epcglobal:cbv:bizstep:storing' }
     ] as any,
     'tenant-1',
     '2026-08-15T09:00:00.000Z'
@@ -116,3 +116,38 @@ test('개폐 위치는 표준의 네 값만 받는다 — 과도·불량을 열
   assert.equal(bad.rejected.length, 1)
   assert.match(bad.rejected[0].errors.join(' '), /position/)
 })
+
+/*
+ * ── 레코드가 말한 시각이 봉투의 시각이 된다 (2026-08-23) ────────────────────
+ *
+ * 이 경로는 `eventTimePath` 를 주지 않아 **언제나 폴링 시각**을 썼다. 그래서 커넥터가 이미 싣고 있던
+ * `eventTime` 이 조용히 무시됐다 — 어디에도 오류가 나지 않고, 커넥터를 붙인 쪽은 그것이 먹는다고
+ * 믿고 있었다.
+ *
+ * 무엇이 걸렸나: **계보의 시각**이다. 4월에 만든 로트가 8월에 만들어진 것으로 저널에 남았다. 그리고
+ * 실측 소요를 재는 폴드가 봉투 시각을 쓰므로(`kpi-fold`: `workMs = 완료 − 첫 착수`), 폴링 간격을
+ * 작업시간으로 배울 수 있었다 — 못 배우는 것보다 나쁘다.
+ */
+test('레코드가 시각을 말하면 그것이 봉투의 시각이다 — 폴링 시각으로 덮지 않는다', () => {
+  const POLLED = '2026-08-23T00:00:00.000Z'
+  const SAID = '2026-04-15T07:35:53.000Z'
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ ...epcisRecord, eventTime: SAID }] as any,
+    't',
+    POLLED
+  )
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted[0].eventTime, SAID, '원본이 말한 시각이어야 한다')
+  assert.notEqual(accepted[0].eventTime, POLLED, '폴링 시각이 아니어야 한다')
+})
+
+test('레코드가 시각을 말하지 않으면 폴링 시각으로 떨어진다 — 이 한 줄이 기존 경로를 막지 않는다', () => {
+  /*
+   * 커널의 경로 해석은 없는 값을 **오류로 만들지 않는다**(§`resolve`). 그래서 시각을 말하지 않는
+   * 레코드는 예전처럼 기본값을 쓴다. 이 단정이 없으면 위 한 줄이 조용히 대량 거부를 낼 수 있다.
+   */
+  const POLLED = '2026-08-23T00:00:00.000Z'
+  const { accepted, rejected } = ingestCanonicalRecords([epcisRecord] as any, 't', POLLED)
+  assert.deepEqual(rejected, [])
+  assert.equal(accepted[0].eventTime, POLLED)
+})