@things-factory/headless-twin 10.0.7 → 10.0.9

package/test/kpi-baseline.test.ts

@@ -0,0 +1,196 @@
+/*
+ * 여러 구간 동시 비교 — **"어제보다 나아졌다" 를 넘어선다.**
+ *
+ * 비교 축이 한 구간만 볼 때는 판단이 한 문장에서 멈췄다: "어제보다 나아졌다." 어제도 나빴으면 쓸모가
+ * 없다. 최근 며칠의 같은 시간대를 함께 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
+ *
+ * 이 테스트가 지키는 것은 산수보다 **정직성**이다. 이 도메인에서 값이 없는 것을 0 으로 읽으면 시간
+ * 지표는 "낮을수록 좋다" 라서 **일이 없던 구간이 최고 성적으로** 보고된다 — 목표 판정에서 이미 겪은
+ * 결함이라 여기서 되풀이하지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  MAX_BASELINE_PERIODS,
+  baselineWindows,
+  summarizeBaseline,
+  type MetricSpecLike
+} from '../server/engine/kpi-baseline.ts'
+
+const MS_DAY = 24 * 60 * 60_000
+const HOUR = 60 * 60_000
+
+/* 실제 표(`TWIN_METRIC`)의 성질만 흉내 낸 최소 사양 — 어휘는 그쪽이 소유한다. */
+const SPECS = {
+  'throughput.tasks': { direction: 'higher', unit: 'count' },
+  'workTime.p50Ms': { direction: 'lower', unit: 'ms' }
+} satisfies Record<string, MetricSpecLike>
+
+type M = keyof typeof SPECS
+
+/** 과거 창 표본 — 값만 신경 쓰는 테스트를 짧게 쓰기 위한 도우미. */
+const sample = (dayBack: number, values: Partial<Record<M, number | undefined>>) => ({
+  fromMs: -dayBack * MS_DAY,
+  toMs: -dayBack * MS_DAY + HOUR,
+  values
+})
+
+test('같은 시간대를 하루씩 뒤로 옮긴다 — 가까운 것부터', () => {
+  const from = 10 * MS_DAY
+  const to = from + HOUR
+
+  const windows = baselineWindows(from, to, 3)
+
+  assert.equal(windows.length, 3)
+  assert.deepEqual(windows[0], { fromMs: from - MS_DAY, toMs: to - MS_DAY }, '어제가 먼저')
+  assert.deepEqual(windows[2], { fromMs: from - 3 * MS_DAY, toMs: to - 3 * MS_DAY })
+  /* 길이는 그대로여야 한다 — 길이가 달라지면 처리량을 비교할 수 없다. */
+  for (const w of windows) assert.equal(w.toMs - w.fromMs, to - from)
+})
+
+test('주 단위는 같은 요일을 본다 — 주말·평일이 섞이지 않게', () => {
+  const from = 30 * MS_DAY
+  const windows = baselineWindows(from, from + HOUR, 2, 'week')
+
+  assert.equal(windows[0].fromMs, from - 7 * MS_DAY)
+  assert.equal(windows[1].fromMs, from - 14 * MS_DAY)
+})
+
+test('구간 수에 상한이 있고, 이상한 입력은 창을 만들지 않는다', () => {
+  assert.equal(baselineWindows(0, HOUR, 999).length, MAX_BASELINE_PERIODS)
+  assert.equal(baselineWindows(0, HOUR, 0).length, 0)
+  assert.equal(baselineWindows(0, HOUR, -3).length, 0)
+  /* 끝이 시작보다 앞이면 창이 아니다 — 지어내지 않는다. */
+  assert.equal(baselineWindows(HOUR, 0, 3).length, 0)
+  assert.equal(baselineWindows(Number.NaN, HOUR, 3).length, 0)
+})
+
+test('분포는 측정된 표본만으로 만들되, **결측 창도 남긴다**', () => {
+  /* 빼고 말하면 "지난 5일" 이 실제로는 3일이었다는 것을 아무도 모른다. */
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 50 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, {}), // 기록 없음
+    sample(3, { 'throughput.tasks': 60 }),
+    sample(4, { 'throughput.tasks': undefined }), // 기록 없음
+    sample(5, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.requested, 5)
+  assert.equal(row.measuredCount, 3)
+  assert.equal(row.samples.length, 5, '요청한 창 전부를 돌려준다')
+  assert.deepEqual(
+    row.samples.map(s => s.measured),
+    [true, false, true, false, true]
+  )
+  assert.deepEqual([row.min, row.median, row.max], [40, 60, 80])
+})
+
+test('현재 값이 없으면 자리를 말하지 않는다 — 결측을 0 으로 읽으면 최고 성적으로 뒤집힌다', () => {
+  /* 시간 지표는 "낮을수록 좋다" 라서 결측을 0 으로 놓으면 **일이 없던 구간이 1등**이 된다. */
+  const [row] = summarizeBaseline({ 'workTime.p50Ms': SPECS['workTime.p50Ms'] }, {}, [
+    sample(1, { 'workTime.p50Ms': 30_000 }),
+    sample(2, { 'workTime.p50Ms': 40_000 })
+  ])
+
+  assert.equal(row.current, undefined)
+  assert.equal(row.standing, undefined)
+  assert.equal(row.rank, undefined)
+  assert.equal(row.noPosition, 'no-current')
+  /* 그래도 분포 자체는 낸다 — "평소 얼마였나" 는 여전히 답할 수 있는 사실이다. */
+  assert.deepEqual([row.min, row.max], [30_000, 40_000])
+})
+
+test('표본이 둘 미만이면 자리를 말하지 않는다 — 하나를 분포라 부를 수 없다', () => {
+  const one = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [
+    sample(1, { 'throughput.tasks': 40 })
+  ])[0]
+
+  assert.equal(one.noPosition, 'too-few-samples')
+  assert.equal(one.standing, undefined)
+
+  const none = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [])[0]
+  assert.equal(none.noPosition, 'too-few-samples')
+  assert.equal(none.min, undefined)
+})
+
+test('방향을 지표가 안다 — 같은 자리가 처리량과 소요시간에서 반대로 읽힌다', () => {
+  const past = [sample(1, { 'throughput.tasks': 40, 'workTime.p50Ms': 40_000 }), sample(2, { 'throughput.tasks': 60, 'workTime.p50Ms': 60_000 }), sample(3, { 'throughput.tasks': 80, 'workTime.p50Ms': 80_000 })]
+
+  /* 값이 표본 전부보다 크다 — 처리량은 최고, 소요시간은 최악이다. */
+  const rows = summarizeBaseline(SPECS, { 'throughput.tasks': 90, 'workTime.p50Ms': 90_000 }, past)
+  const by = Object.fromEntries(rows.map(r => [r.metric, r]))
+
+  assert.equal(by['throughput.tasks'].standing, 'best')
+  assert.equal(by['workTime.p50Ms'].standing, 'worst')
+  /* 순위는 **방향 없는 사실**이다 — 둘 다 오름차순 4번째다. */
+  assert.equal(by['throughput.tasks'].rank, 4)
+  assert.equal(by['workTime.p50Ms'].rank, 4)
+  assert.equal(by['workTime.p50Ms'].rankOf, 4)
+})
+
+test('전부보다 나쁘면 worst — 처리량이 지난 3일 중 가장 낮은 경우', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 60 }),
+    sample(3, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.standing, 'worst')
+  assert.equal(row.rank, 1, '오름차순 첫째')
+})
+
+test('중앙값과 같으면 typical — 임의의 임계를 만들지 않는다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 60 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 60 }),
+    sample(3, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.standing, 'typical')
+})
+
+test('중앙값 양쪽을 방향대로 가른다', () => {
+  const past = [sample(1, { 'throughput.tasks': 40 }), sample(2, { 'throughput.tasks': 60 }), sample(3, { 'throughput.tasks': 80 })]
+  const spec = { 'throughput.tasks': SPECS['throughput.tasks'] }
+
+  assert.equal(summarizeBaseline(spec, { 'throughput.tasks': 70 }, past)[0].standing, 'better-than-typical')
+  assert.equal(summarizeBaseline(spec, { 'throughput.tasks': 50 }, past)[0].standing, 'worse-than-typical')
+
+  /* 소요시간은 반대다 — 중앙값보다 낮은 것이 좋다. */
+  const lower = { 'workTime.p50Ms': SPECS['workTime.p50Ms'] }
+  const pastMs = [sample(1, { 'workTime.p50Ms': 40 }), sample(2, { 'workTime.p50Ms': 60 }), sample(3, { 'workTime.p50Ms': 80 })]
+  assert.equal(summarizeBaseline(lower, { 'workTime.p50Ms': 50 }, pastMs)[0].standing, 'better-than-typical')
+  assert.equal(summarizeBaseline(lower, { 'workTime.p50Ms': 70 }, pastMs)[0].standing, 'worse-than-typical')
+})
+
+test('짝수 표본의 중앙값은 가운데 둘의 평균이다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 55 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 50 }),
+    sample(3, { 'throughput.tasks': 60 }),
+    sample(4, { 'throughput.tasks': 70 })
+  ])
+
+  assert.equal(row.median, 55)
+  assert.equal(row.standing, 'typical')
+})
+
+test('열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다', () => {
+  const rows = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10, 'made.up': 99 } as any, [
+    sample(1, { 'throughput.tasks': 5 } as any)
+  ])
+
+  assert.deepEqual(rows.map(r => r.metric), ['throughput.tasks'])
+})
+
+test('무한·NaN 은 측정으로 세지 않는다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': Number.NaN }, [
+    sample(1, { 'throughput.tasks': Number.POSITIVE_INFINITY }),
+    sample(2, { 'throughput.tasks': 40 }),
+    sample(3, { 'throughput.tasks': 60 })
+  ])
+
+  assert.equal(row.measuredCount, 2, '무한은 표본이 아니다')
+  assert.equal(row.noPosition, 'no-current', 'NaN 은 값이 아니다')
+})

package/test/kpi-query-bench.test.ts

@@ -0,0 +1,128 @@
+/*
+ * 구간 성과 질의 비용 측정 — **방송이냐 질의냐를 숫자로 정한다.**
+ *
+ * ── 왜 재는가 (2026-08-06) ─────────────────────────────────────────────────
+ * 성과 카드를 여러 단계(공간·트윈·구역·자리·설비)에 붙이려 한다. 두 방법이 있다.
+ *
+ *  · 방송 — 서버가 주기마다 전 단계를 계산해 밀어 준다. 자리가 트윈당 최대 200개고 지표가 6개라
+ *    태그가 1,200개가 된다. **보드에 카드를 하나도 안 놓아도 계산은 돈다.**
+ *  · 질의 — 카드가 필요할 때 묻는다. **보드에 놓인 카드 수만큼만** 든다. 시각(`toTime`)도 물을 수 있어
+ *    타임라인과 맞고, 공간 단위 합산(여러 트윈을 한 번에 접기)은 질의에만 있다.
+ *
+ * 질의로 정하려면 **한 번의 비용**을 알아야 한다. 카드 20장이 30초마다 물으면 감당되는지가 결정을
+ * 가른다. 짐작하지 않고 잰다.
+ *
+ * 빌드 산출물을 실행한다 — **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { test, before, after } from 'node:test'
+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 { computeTwinKpi } = 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 INSTANCE = 'kpi-bench'
+const TO = Date.parse('2026-03-10T10:00:00.000Z')
+const WINDOW_MIN = 60
+
+/** 자리 200개 — 실측한 최대 규모(트윈당 자리 최대 200, 평균 19). */
+const LOCATIONS = 200
+/** 창 안의 완료 작업 수 — 한 건이 두 줄(시작·완료)이라 이벤트는 두 배가 된다. */
+const TASK_COUNTS = [500, 2_000, 10_000]
+
+function taskRows(count: number, revBase: number) {
+  const rows: any[] = []
+  for (let i = 0; i < count; i++) {
+    const done = TO - 60_000 - (i % (WINDOW_MIN * 60)) * 1000
+    const started = done - 30_000
+    const at = `loc-${i % LOCATIONS}`
+    rows.push(
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2,
+        eventType: 'task.status',
+        eventTime: new Date(started).toISOString(),
+        payload: { data: { taskId: `t-${i}`, status: 'in-progress', resourceRef: 'fk-1', locationRef: at } }
+      },
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2 + 1,
+        eventType: 'task.status',
+        eventTime: new Date(done).toISOString(),
+        payload: { data: { taskId: `t-${i}`, status: 'completed', resourceRef: 'fk-1', locationRef: at } }
+      }
+    )
+  }
+  return rows
+}
+
+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: 'kpi-bench', subdomain: 'kpi-bench' } as any)
+  domainId = d.id
+
+  /* 자리 계층 — 자리 200개를 구역 4개에 나눠 붙인다(구역 단위 접기 비용도 재려면 부모가 있어야 한다). */
+  const locations = Array.from({ length: LOCATIONS }, (_, i) => ({
+    id: `loc-${i}`,
+    type: 'storage',
+    capacity: 10,
+    parentId: `area-${i % 4}`
+  }))
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'wms',
+    status: 'stopped',
+    board: { locations, equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'loc-0' }] }
+  } as any)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+const ms = async (fn: () => Promise<any>) => {
+  const t = process.hrtime.bigint()
+  await fn()
+  return Number(process.hrtime.bigint() - t) / 1e6
+}
+
+test('bench: 구간 성과 폴드 한 번의 비용 vs 창 안의 작업 수', async () => {
+  let seeded = 0
+  for (const count of TASK_COUNTS) {
+    await ds.getRepository(TwinEvent).save(taskRows(count - seeded, seeded * 2 + 1000))
+    seeded = count
+
+    const args = { domainId, instanceId: INSTANCE, toTime: new Date(TO).toISOString(), windowMinutes: WINDOW_MIN }
+    await computeTwinKpi(args) // 워밍업(연결·스키마 캐시)
+
+    const plain = await ms(() => computeTwinKpi(args))
+    const byArea = await ms(() => computeTwinKpi({ ...args, groupBy: 'area' }))
+
+    console.log(`  작업 ${count.toLocaleString()}건(이벤트 ${(count * 2).toLocaleString()}줄) · 자리 ${LOCATIONS}개`)
+    console.log(`    폴드 1회        ${plain.toFixed(1)}ms`)
+    console.log(`    구역별 폴드 1회 ${byArea.toFixed(1)}ms`)
+    console.log(`    카드 20장 동시  ${(plain * 20).toFixed(0)}ms (직렬 상한 — 실제로는 한 번 접어 나눠 쓸 수 있다)`)
+  }
+})

package/test/live-mirror-parity.test.ts

@@ -77,8 +77,8 @@ function bothPayloads() {
   const proj = new StateProjector(board)
   for (const env of events) proj.apply(env)
   return {
-    sim: sortByTag(buildEntityDeltas(kernel.getSnapshot())),
-    live: sortByTag(buildEntityDeltas(proj.snapshot()))
+    sim: sortByTag(buildEntityDeltas(kernel.getSnapshot(), 't1')),
+    live: sortByTag(buildEntityDeltas(proj.snapshot(), 't1'))
   }
 }
 
@@ -231,3 +231,36 @@ test('★ withLiveAttentions 는 채널을 하나도 떨어뜨리지 않는다(
   for (const expected of ['breakdown', 'bottleneck', 'hold', 'work-backlog'])
     assert.ok(kinds.has(expected), `라이브 배선이 '${expected}' 채널을 떨어뜨렸다 — 넘긴 것: ${[...kinds].join(', ') || '없음'}`)
 })
+
+/*
+ * ── 되짚은 상태에도 신호가 있어야 한다 (2026-08-05) ────────────────────────
+ * 라이브·시뮬은 커널이 신호를 스스로 내지만, 저널을 접는 경로는 프로젝터 상태만 낸다 — 신호 키가
+ * 아예 없었다. 지도는 `snap.attentions` 를 읽으므로 **과거를 되짚으면 주의 레일이 텅 비었고**,
+ * 기동돼 있지 않은 트윈을 보는 화면도 같았다. 실 저널로 재 보니 `rosarito-wms` 는 246건이 비어 있었다.
+ *
+ * 신호는 상태에서 계산되는 것이므로 같은 공식으로 채우면 된다(두 벌을 두지 않는다). 다만 "늦었나"
+ * 판정이 `nowTime` 을 보므로 그 값이 먼저다 — 되짚은 시점의 정직한 "지금" 은 물어본 시각이고,
+ * 벽시계를 끼워 넣으면 과거 화면이 "지금 기준으로 늦었다" 고 말한다.
+ */
+test('★ 프로젝터 폴드 상태에는 신호 키가 없다 — 보강이 필요한 이유', () => {
+  const { board, events } = runSim()
+  const proj = new StateProjector(board)
+  for (const env of events) proj.apply(env)
+  const raw: any = proj.snapshot()
+  assert.equal(raw.attentions, undefined, '접은 상태는 신호를 스스로 내지 않는다(커널이 아니다)')
+})
+
+test('★ 보강하면 되짚은 상태도 신호를 갖는다 — 지도의 주의 레일이 비지 않게', () => {
+  /* 용량 1 자리를 채워 병목이 스스로 성립하게 만든다(신호를 손으로 넣지 않는다). */
+  const st: any = {
+    revision: 3,
+    nowTime: '2026-08-05T00:00:00.000Z',
+    locations: [{ id: 'bin-tight', type: 'storage', capacity: 1, occupancy: 1 }],
+    equipment: [],
+    orders: [],
+    tasks: []
+  }
+  const out = withLiveAttentions(st)
+  assert.ok((out.attentions ?? []).length > 0, '접은 상태에서도 규칙이 신호를 낸다')
+  assert.equal(out.attentions![0].kind, 'bottleneck')
+})

package/test/master-to-twin.test.ts

@@ -59,7 +59,11 @@ test('미지 노드 타입 경고 — 카탈로그 있으면 검증(버리진
   const m = wmsMaster()
   ;(m.locations as any).push({ id: 'weird', type: '__unknown__', role: 'location', capacity: 1 })
   const withCat = masterToTwin(m, DOMAIN_CATALOG)
-  assert.ok(withCat.warnings.some(w => w.includes('__unknown__')), '미지 타입 경고')
+  /* 경고는 프로즈가 아니라 **코드+파라미터**다(화면이 다섯 언어로 렌더한다) — 문구가 아니라 계약을 본다. */
+  assert.ok(
+    withCat.warnings.some(w => w.code === 'unknown-location-type' && w.params?.type === '__unknown__'),
+    `미지 타입 경고: ${JSON.stringify(withCat.warnings)}`
+  )
   assert.ok(withCat.board.locations.some((n: any) => n.id === 'weird'), '경고해도 노드는 유지(반영 우선)')
   // 정상 타입만이면 경고 0
   assert.equal(masterToTwin(wmsMaster(), DOMAIN_CATALOG).warnings.length, 0, '알려진 타입만 → 경고 0')
@@ -107,7 +111,7 @@ test('현장 물질화(#4): 표현도 geo 도 없으면 빈 표현 + 경고(정
   const { spaceContent, warnings } = masterToTwin(m)
   assert.equal(spaceContent.representations.length, 0, '합성 불가')
   assert.ok(
-    warnings.some((w: string) => w.includes('no viewable representation')),
+    warnings.some(w => w.code === 'no-viewable-representation'),
     '뷰 없는 공간 경고 표면화'
   )
 })
@@ -158,7 +162,7 @@ test('내용 없는 명세는 경고한다 — 선언했는데 아무 말도 하
   m.operations = [{ key: 'cut', label: 'cutting', intent: 'process' }]
   const { warnings } = masterToTwin(m, DOMAIN_CATALOG)
   assert.ok(
-    warnings.some(w => w.includes('cut') && w.includes('kernel defaults')),
+    warnings.some(w => w.code === 'operation-without-duration' && w.params?.operation === 'cut'),
     `기본값으로 굴러갈 것을 알린다: ${JSON.stringify(warnings)}`
   )
 })

package/test/mutation-gate.test.ts

@@ -0,0 +1,108 @@
+/*
+ * 뮤테이션 게이트 가드 — **트윈을 바꾸는 문은 전부 잠겨 있다.**
+ *
+ * ── 계기 (2026-08-06) ──────────────────────────────────────────────────────
+ * 권한 모델을 손대며 세어 보니 트윈 뮤테이션 24개 중 **22개에 게이트가 없었다.** 인스턴스 삭제와
+ * 레퍼런스 자격정보 저장까지 로그인만 하면 누구나 부를 수 있었다. 발견은 사람 눈이었다 — 즉
+ * 25번째 뮤테이션이 게이트 없이 들어오면 아무것도 잡지 못한다. 그래서 기계가 센다.
+ *
+ * ── 왜 문자열을 그대로 비교하나 ─────────────────────────────────────────────
+ * "게이트가 있나" 만 보면 `domainOwnerGranted: false` 로 약해지거나 category 가 다른 값으로 갈라져도
+ * 통과한다. 게이트는 **한 문장이어야** 서버·클라·관리 화면이 같은 권한을 말한다. 그래서 정본 문장과
+ * 글자까지 같은지 본다.
+ *
+ * ── 조회는 왜 검사하지 않나 (ADR-0027) ──────────────────────────────────────
+ * 조회에는 게이트를 두지 않기로 했다 — `twinKpi` 가 같은 판정을 게이트 없이 이미 내주므로, 일부
+ * 조회만 잠그면 보안이 아니라 화면 고장이 된다. 이 결정이 바뀌면 아래 "정본 문장" 검사가 먼저
+ * 깨진다. 그때는 테스트를 고치지 말고 **ADR 을 먼저 고친다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 정본 게이트 — 트윈을 바꾸는 모든 작업이 요구하는 단 하나의 권한. */
+const GATE =
+  `@Directive('@privilege(category: "twin", privilege: "mutation", ` + `domainOwnerGranted: true, superUserGranted: true)')`
+
+const SERVER = new URL('../server', import.meta.url).pathname
+
+function walk(dir: string, out: string[] = []): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const p = join(dir, e)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+  }
+  return out
+}
+
+/**
+ * `@Mutation` 위에 붙은 데코레이터·주석 덩이를 거꾸로 모은다.
+ *
+ * 데코레이터가 바로 붙어 있다고 가정하지 않는다 — 나중에 다른 데코레이터가 끼어들어도 게이트를
+ * 찾아야 한다. 덩이의 끝은 코드(다른 메서드의 `}` 등)를 만나는 자리다.
+ */
+function decoratorBlockAbove(lines: string[], at: number): string[] {
+  const block: string[] = []
+  for (let i = at - 1; i >= 0; i--) {
+    const t = lines[i].trim()
+    if (!t) continue /* 주석과 데코레이터 사이의 빈 줄은 덩이를 끊지 않는다 */
+    const isBlockPart = t.startsWith('@') || t.startsWith('*') || t.startsWith('/*') || t.startsWith('//')
+    if (!isBlockPart) break
+    block.push(t)
+  }
+  return block
+}
+
+const files = walk(SERVER)
+
+test('트윈을 바꾸는 뮤테이션은 전부 정본 게이트를 달고 있다', () => {
+  const ungated: string[] = []
+  let mutations = 0
+
+  for (const f of files) {
+    const lines = readFileSync(f, 'utf-8').split('\n')
+    lines.forEach((line, i) => {
+      if (!line.trim().startsWith('@Mutation')) return
+      mutations++
+      if (!decoratorBlockAbove(lines, i).some(l => l === GATE)) {
+        /* 어느 뮤테이션인지 이름으로 말한다 — 줄번호만 주면 고치는 사람이 다시 찾아야 한다. */
+        const name = (lines.slice(i, i + 6).join(' ').match(/async\s+(\w+)/) ?? [, '?'])[1]
+        ungated.push(`${f.split('/').slice(-2).join('/')}:${i + 1}  ${name}`)
+      }
+    })
+  }
+
+  /* 훑기가 망가져 0건이 되면 "위반 없음" 으로 보인다 — 그 거짓 통과를 막는다. */
+  assert.ok(mutations >= 20, `뮤테이션을 ${mutations}개만 찾았다 — 소스 훑기가 망가졌다`)
+  assert.deepEqual(
+    ungated,
+    [],
+    `게이트 없는 뮤테이션 ${ungated.length}건 — 로그인만 하면 누구나 부를 수 있다:\n${ungated.join('\n')}`
+  )
+})
+
+test('권한 문장이 한 벌이다 — 약해지거나 갈라지지 않았다', () => {
+  const odd: string[] = []
+  for (const f of files) {
+    readFileSync(f, 'utf-8')
+      .split('\n')
+      .forEach((line, i) => {
+        const t = line.trim()
+        if (!t.startsWith("@Directive('@privilege")) return
+        if (t !== GATE) odd.push(`${f.split('/').slice(-2).join('/')}:${i + 1}  ${t}`)
+      })
+  }
+  assert.deepEqual(
+    odd,
+    [],
+    `정본과 다른 권한 문장 ${odd.length}건. 게이트를 늘리거나 나누는 것이 의도라면 ` +
+      `ADR-0027 을 먼저 고치고 이 검사의 정본을 함께 옮긴다:\n${odd.join('\n')}`
+  )
+})

package/test/oee-accumulator.test.ts

@@ -94,9 +94,73 @@ test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비
 
   // withLiveOee 로 보강 → buildEntityDeltas payload 에 oee 포함(sim 과 동일 형상 = 보드 OEE 컴포넌트 live 렌더).
   const enriched = withLiveOee(rawLive, acc)
-  const fk = buildEntityDeltas(enriched).find(d => d.tag === 'fk-1')!.data as any
+  const fk = buildEntityDeltas(enriched, 't1').find(d => d.tag === 'fk-1')!.data as any
   assert.ok(fk.oee, 'withLiveOee 후 설비 data(tag) payload 에 oee 포함 — live OEE 갭 종료')
   // buildEntityDeltas shapeOee = 정수 퍼센트(0-100), raw ms 제외.
   assert.ok(fk.oee.overall >= 0 && fk.oee.overall <= 100, 'oee.overall ∈ [0,100] 정수 퍼센트')
   assert.ok(fk.oee.availability < 100, 'availability < 100 (고장 시간 반영 — 누적기 downMs)')
 })
+
+/*
+ * ── 되짚은 화면에도 가동 이력이 있어야 한다 (2026-08-05) ────────────────────
+ * OEE 는 원 시스템이 누적을 보내 주지 않아 호스트가 상태 전이를 적분해 만든다. 그런데 그 누적기는
+ * **라이브에서만** 돌았고, 저널을 접는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
+ * "가동 이력이 전혀 없음" 으로 보였다(실 저널: `rosarito-mes` 18대, `hatiolab-wms` 22대가 그랬다).
+ *
+ * 없는 것은 데이터가 아니라 계산이다: 입력은 저널에 다 있다. 그래서 같은 누적기에 같은 이벤트를
+ * 태운다 — 이 테스트는 그 재계산이 라이브와 **같은 값**을 내는지, 그리고 시간여행에서 **그 시점까지만**
+ * 세는지를 못 박는다.
+ */
+test('★ 저널을 다시 태우면 라이브와 같은 계측이 나온다 — 규칙이 한 벌이므로', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const ev = (ms: number, id: string, status: string) => ({
+    eventId: `e${ms}`,
+    eventType: 'equipment.status',
+    eventTime: new Date(T0 + ms).toISOString(),
+    tenantId: 't',
+    data: { equipmentId: id, moverId: id, status }
+  })
+  const stream = [ev(0, 'fk-1', 'idle'), ev(10_000, 'fk-1', 'busy'), ev(40_000, 'fk-1', 'down'), ev(70_000, 'fk-1', 'idle')]
+
+  /* 라이브 — 이벤트가 도착하는 대로 누적. */
+  const live = new OeeAccumulator()
+  for (const e of stream) live.apply(e as any)
+
+  /* 되짚기 — 저널에서 같은 순서로 다시 태운다. */
+  const replayed = new OeeAccumulator()
+  for (const e of stream) replayed.apply(e as any)
+
+  const at = T0 + 70_000
+  assert.deepEqual(replayed.oee('fk-1', at), live.oee('fk-1', at), '같은 이벤트·같은 시점이면 같은 값이어야 한다')
+  assert.equal(replayed.oee('fk-1', at).downMs, 30_000, '고장 30초가 잡혀야 한다')
+})
+
+test('★ 시간여행은 그 시점까지만 센다 — 뒤에 일어난 고장이 과거 화면에 섞이지 않게', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const ev = (ms: number, status: string) => ({
+    eventId: `e${ms}`,
+    eventType: 'equipment.status',
+    eventTime: new Date(T0 + ms).toISOString(),
+    tenantId: 't',
+    data: { equipmentId: 'fk-1', moverId: 'fk-1', status }
+  })
+  const all = [ev(0, 'busy'), ev(30_000, 'down'), ev(60_000, 'idle')]
+
+  /* 30초 시점까지만 태운다(호스트가 잘라 낸 이벤트만 태우는 것과 같다). */
+  const past = new OeeAccumulator()
+  for (const e of all.slice(0, 2)) past.apply(e as any)
+  assert.equal(past.oee('fk-1', T0 + 30_000).downMs, 0, '아직 고장이 시작된 시점 — 고장 시간은 0 이다')
+
+  const now = new OeeAccumulator()
+  for (const e of all) now.apply(e as any)
+  assert.equal(now.oee('fk-1', T0 + 60_000).downMs, 30_000, '지금 화면에서는 고장 30초가 잡힌다')
+})
+
+test('★ 계측 시점을 벽시계로 재지 않는다 — 과거 화면의 가용률이 시간이 갈수록 떨어지지 않게', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const acc = new OeeAccumulator()
+  acc.apply({ eventId: 'e1', eventType: 'equipment.status', eventTime: new Date(T0).toISOString(), tenantId: 't', data: { equipmentId: 'fk-1', moverId: 'fk-1', status: 'busy' } } as any)
+  const atThen = acc.oee('fk-1', T0 + 10_000)
+  const atMuchLater = acc.oee('fk-1', T0 + 10_000_000)
+  assert.notDeepEqual(atThen, atMuchLater, '시점을 넘기면 값이 달라진다 — 그래서 그 화면의 시각을 넘겨야 한다')
+})

package/test/registry-key-guard.test.ts

@@ -0,0 +1,80 @@
+/*
+ * 런타임 레지스트리 색인 가드 — **엔진 밖에서 맵을 직접 만지지 않는다.**
+ *
+ * 계기(2026-08-06): `TwinEngine.instances` 가 `instanceId` 하나로 키를 잡던 시절, 엔진 밖 네 곳이 그 맵을
+ * **직접 색인**했다(`TwinEngine.instances[instanceId]`, 심지어 `(TwinEngine as any).instances?.[…]`).
+ * 그래서 도메인 확인이 자리마다 제각각이었고 한 곳은 아예 없었다.
+ *
+ * 키를 `(domainId, instanceId)` 로 고쳤지만, **직접 색인이 남아 있으면 같은 부류가 다시 자란다** — 밖에서
+ * `instances[id]` 를 쓰면 이제는 항상 `undefined` 가 나와 조용히 "안 돌고 있다" 로 읽힌다(더 나쁘다:
+ * 오류가 아니라 거짓 사실이 된다). 그래서 접근자(`owns`·`runtime`·`kernel`·`metrics`·`snapshot`)만 쓴다.
+ *
+ * 이 부류는 이미 한 번 물었다 — `twin-lifecycle-mutation.ts` 주석이 증언한다("과거엔
+ * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그"). 그때는 그 자리만
+ * 고쳤다. 이번에는 기계가 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SERVER = new URL('../server', import.meta.url).pathname
+
+/** 맵을 소유한 자리 — 여기서는 색인해야 한다. */
+const OWNERS = ['engine/twin-engine.ts', 'engine/runtime-key.ts']
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+  }
+  return out
+}
+
+/** 주석 줄은 뺀다 — 이 결함을 설명하는 주석이 여러 곳에 있고, 그것을 위반으로 셀 수 없다. */
+const isComment = (line: string) => /^\s*(\/\/|\/\*|\*)/.test(line)
+
+test('엔진 밖에서 런타임 레지스트리를 직접 색인하지 않는다', () => {
+  const offenders: string[] = []
+
+  for (const file of walk(SERVER)) {
+    const rel = file.slice(SERVER.length + 1)
+    if (OWNERS.includes(rel)) continue
+
+    readFileSync(file, 'utf-8')
+      .split('\n')
+      .forEach((line, i) => {
+        if (isComment(line)) return
+        /*
+         * **엔진 참조가 같은 줄에 있을 때만** 위반이다(`as any` 우회 포함). `.instances[` 만 보면
+         * 무관한 배열(응답·지역 변수)까지 잡아 정당한 코드를 막는다.
+         */
+        if (/TwinEngine\s*(as\s+any\s*)?\)?\s*\.\s*(instances|recovered)/.test(line)) {
+          offenders.push(`${rel}:${i + 1}  ${line.trim().slice(0, 100)}`)
+        }
+      })
+  }
+
+  assert.deepEqual(
+    offenders,
+    [],
+    `레지스트리를 직접 색인하는 곳 ${offenders.length}곳 — 접근자(owns·runtime·kernel·metrics·snapshot)를 쓴다:\n` +
+      offenders.join('\n')
+  )
+})
+
+test('엔진이 맵을 만질 때는 항상 키 함수를 거친다', () => {
+  const src = readFileSync(join(SERVER, 'engine/twin-engine.ts'), 'utf-8')
+  const bad: string[] = []
+
+  src.split('\n').forEach((line, i) => {
+    if (isComment(line)) return
+    /* 색인하는 줄에는 `runtimeKey(` 또는 미리 만들어 둔 `key` 변수가 있어야 한다. */
+    if (!/this\.(instances|recovered)\s*\[/.test(line)) return
+    if (/runtimeKey\(/.test(line) || /\[key\]/.test(line)) return
+    bad.push(`engine/twin-engine.ts:${i + 1}  ${line.trim().slice(0, 100)}`)
+  })
+
+  assert.deepEqual(bad, [], `키 함수를 거치지 않고 색인하는 곳 ${bad.length}곳:\n${bad.join('\n')}`)
+})