@things-factory/headless-twin 10.0.9 → 10.0.10

package/{server/engine → shared}/entity-delta.ts

@@ -45,6 +45,8 @@ export const TASKS_TAG_PREFIX = '__tasks__'
 export const ITEMS_TAG_PREFIX = '__items__'
 export const PERSONS_TAG_PREFIX = '__persons__'
 export const ASSETS_TAG_PREFIX = '__assets__'
+/** 에너지 집약 — 수요 구간·피크·계약은 **트윈 하나의 사실**이라 개체 태그가 없다. */
+export const ENERGY_TAG_PREFIX = '__energy__'
 
 /** 이 트윈의 집약 채널 태그. 트윈 식별자가 없으면 만들지 않는다 — 덮어쓰기의 원인이었다. */
 export function aggregateTag(prefix: string, instanceId: string): string {
@@ -58,6 +60,7 @@ export const tasksTag = (instanceId: string) => aggregateTag(TASKS_TAG_PREFIX, i
 export const itemsTag = (instanceId: string) => aggregateTag(ITEMS_TAG_PREFIX, instanceId)
 export const personsTag = (instanceId: string) => aggregateTag(PERSONS_TAG_PREFIX, instanceId)
 export const assetsTag = (instanceId: string) => aggregateTag(ASSETS_TAG_PREFIX, instanceId)
+export const energyTag = (instanceId: string) => aggregateTag(ENERGY_TAG_PREFIX, instanceId)
 
 /**
  * 통과시키지 않는 필드 — **빼는 데는 이유가 필요하다.**
@@ -124,11 +127,58 @@ function aggregateItem(entity: any, idKey: 'id' | 'epc'): any {
  */
 export const ITEMS_AGGREGATE_LIMIT = 500
 
+/**
+ * 자리별 에너지 — **그 자리의 계량기들이 잰 것**을 그 자리 태그에 실을 수 있게 모은다.
+ *
+ * ── 왜 자리에도 필요한가 (2026-08-14) ───────────────────────────────────────
+ * 카탈로그는 자리에도 `metered` 를 준다(수전·분기·구역 계량은 재는 자리다). 그런데 값은 계량기
+ * **설비** 태그로만 나갔다. 그래서 계통도의 분기 자리에 계량 컴포넌트를 놓으면 **영원히 「—」** 였다 —
+ * 능력은 「잰다」고 말하는데 값이 오지 않는 자리.
+ *
+ * 「이 구간이 얼마를 먹나」는 자리의 사실이고, 사람은 계통도의 자리에 붙여 본다.
+ *
+ * ── 계층은 여기서 문제가 되지 않는다 ────────────────────────────────────────
+ * 각 자리에는 **그 자리에 붙은 계량기만** 더한다(수전 자리에는 수전 계량기, 분기 자리에는 그 분기의
+ * 것). 커널이 부하를 뿌리로만 세는 것과 다른 층의 계산이다 — 여기서는 자리마다 자기 것을 말한다.
+ *
+ * 근거를 함께 낸다(`meters`) — 그 자리의 수가 어느 계량기에서 왔는지 되짚을 수 있어야 한다.
+ */
+function energyByLocation(state: any): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>()
+  const points = state?.energy?.points
+  if (!Array.isArray(points) || !points.length) return out
+
+  /* 계량기 → 자리. 자리를 모르는 계량기는 자리 payload 에 실을 데가 없다(설비 태그로만 나간다). */
+  const locOf = new Map<string, string>()
+  for (const e of state?.equipment ?? []) if (e?.id && e?.homeLocation) locOf.set(e.id, e.homeLocation)
+
+  for (const pt of points) {
+    const loc = pt?.id ? locOf.get(pt.id) : undefined
+    if (!loc) continue
+    const acc = out.get(loc) ?? { meters: [] as string[], samplesInWindow: 0 }
+    ;(acc.meters as string[]).push(pt.id)
+    acc.samplesInWindow = Number(acc.samplesInWindow ?? 0) + (Number(pt.samplesInWindow) || 0)
+    /* 값은 **있는 것만** 더한다 — 하나도 없으면 키를 만들지 않는다(0 은 「안 썼다」가 된다). */
+    if (Number.isFinite(Number(pt.kW))) acc.kW = Number(acc.kW ?? 0) + Number(pt.kW)
+    if (Number.isFinite(Number(pt.kWh))) acc.kWh = Number(acc.kWh ?? 0) + Number(pt.kWh)
+    /* 나이는 **가장 최근**을 쓴다 — 자리에 계량기가 여럿이면 그중 마지막 관측이 그 자리의 나이다. */
+    if (pt.atMs !== undefined) {
+      const iso = new Date(Number(pt.atMs)).toISOString()
+      if (!acc.measuredAt || String(acc.measuredAt) < iso) acc.measuredAt = iso
+    }
+    out.set(loc, acc)
+  }
+  return out
+}
+
 export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[] {
   const out: EntityDelta[] = []
+  const locEnergy = energyByLocation(state)
 
   for (const n of state?.locations ?? []) {
-    out.push({ tag: n.id, data: payloadOf('location', n) })
+    /* 에너지는 자리 payload 에 **합친다** — 같은 태그로 두 번 보내면 뒤엣것이 앞을 덮는다. */
+    const energy = locEnergy.get(n.id)
+    out.push({ tag: n.id, data: energy ? { ...payloadOf('location', n), ...energy } : payloadOf('location', n) })
   }
   for (const m of state?.equipment ?? []) {
     /* Mobile(location/motion) + Operable(status/held) + Processable(oee) — 한 payload 로.
@@ -187,5 +237,50 @@ export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[]
     }
   })
 
+  /*
+   * ── 에너지 (EMS) ─────────────────────────────────────────────────────────
+   *
+   * 계측은 `state.energy` 에 산다 — 자원 축(`equipment`·`locations`)이 아니다. 그래서 이 매핑이 없으면
+   * 보드에 놓은 계량기가 **아무 값도 받지 못한다**(컴포넌트는 있는데 영원히 빈 모습).
+   *
+   * 두 갈래로 낸다:
+   *  · **개체별** — 계량 지점 하나하나의 마지막 관측(kW·kWh·역률·시각). 태그는 그 설비 id 다.
+   *  · **집약** — 수요 구간·피크·계약전력. 이것은 트윈 하나의 사실이라 개체에 실을 수 없다.
+   *
+   * 값이 없으면 **키를 넣지 않는다**(0 으로 만들지 않는다) — 「못 읽었다」와 「0 이었다」는 다른 사실이고,
+   * 그 구별이 이 트윈의 값어치다.
+   */
+  const energy = state?.energy
+  if (energy) {
+    for (const pt of energy.points ?? []) {
+      if (!pt?.id) continue
+      out.push({
+        tag: pt.id,
+        data: {
+          entity: 'meter',
+          ...(pt.kW !== undefined ? { kW: pt.kW } : {}),
+          ...(pt.kWh !== undefined ? { kWh: pt.kWh } : {}),
+          ...(pt.powerFactor !== undefined ? { powerFactor: pt.powerFactor } : {}),
+          /* 마지막 표본 시각 — 계측이 끊긴 것을 화면이 스스로 알 수 있게(우리가 판정하지 않는다). */
+          ...(pt.atMs !== undefined ? { measuredAt: new Date(pt.atMs).toISOString() } : {}),
+          samplesInWindow: pt.samplesInWindow ?? 0
+        }
+      })
+    }
+    out.push({
+      tag: energyTag(instanceId),
+      data: {
+        entity: 'energy',
+        ...(energy.contractKW !== undefined ? { contractKW: energy.contractKW } : {}),
+        ...(energy.open ? { open: energy.open } : {}),
+        ...(energy.peakSince ? { peakSince: energy.peakSince } : {}),
+        /* 마감된 구간은 **최근 것만** 낸다 — 하루치를 매 방송에 실으면 채널이 그것으로 찬다.
+           전체 수는 함께 낸다(조용히 자르지 않는다). */
+        recent: (energy.closed ?? []).slice(-8),
+        closedTotal: energy.closedTotal ?? 0
+      }
+    })
+  }
+
   return out
 }

package/test/adopt-structure-live.test.ts

@@ -0,0 +1,133 @@
+/*
+ * ★ 돌고 있는 미러에 새 구조를 넣는다 — **미러는 멈출 수 없다.**
+ *
+ * 미러가 비추는 현실은 24시간 돈다. 설비 한 대가 늘었다고 트윈을 멈췄다 세우면 그 사이의
+ * 사실을 잃고, 라이브에서 유실은 곧 거짓이다. 그래서 미러는 **돌면서** 갈아탄다.
+ *
+ * 갈아타기가 옳으려면 **세 층이 함께** 움직여야 한다. 하나라도 빠지면 조용히 어긋난다:
+ *  ① 리비전 — 이후의 이벤트가 새 번호를 달고 다닌다(재생이 마디를 나눌 수 있게)
+ *  ② 저장 model·구조 행 — 조회가 새 구조를 본다
+ *  ③ 커널 — 지금 접히는 이벤트가 새 구조 위에서 접힌다
+ *
+ * 커널 단위 거동(무엇을 지키고 무엇을 버리나)은 커널 쪽 `adopt-structure.test.ts` 가 지킨다.
+ * 여기서 지키는 것은 **호스트 배선** — 세 층이 같은 인제스트에서 함께 움직이는가.
+ *
+ * 실 DataSource 로 돈다. 부분 적용은 정의상 "여러 표에 걸쳐 무엇이 남았나" 이므로.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { TwinStructure } = req('../dist-server/service/twin-structure/twin-structure.js')
+const { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { TwinEquipment } = req('../dist-server/service/twin-model/twin-equipment.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const MIRROR = 'mirror-probe'
+const SIM = 'sim-probe'
+
+const master = (source: string, bins: number, forklifts: number): any => ({
+  source,
+  system: 'wms',
+  siteName: '미러 창고',
+  space: { width: 60, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    ...Array.from({ length: bins }, (_, i) => ({ id: `bin-${i + 1}`, type: 'storage', role: 'location', name: `빈${i + 1}`, capacity: 20 }))
+  ],
+  equipment: Array.from({ length: forklifts }, (_, i) => ({ id: `fk-${i + 1}`, kind: 'forklift', homeLocationId: 'dock-recv' }))
+})
+
+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: 'adopt-test', subdomain: 'adopt-test' } as any)
+  domainId = d.id
+
+  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2))
+  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2))
+})
+
+after(async () => {
+  for (const id of [MIRROR, SIM]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함께 움직인다', async () => {
+  /* 미러 기동은 선언 기반 부팅이 가른다 — `startFromRegistry` 는 시뮬 경로다(같은 함수가 아니다). */
+  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'mirror')
+  assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
+
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2))
+
+  /* ① 리비전 — 이후 이벤트가 달고 다닐 번호가 올라간다 */
+  const revs = await ds.getRepository(TwinStructure).find({ where: { instanceId: MIRROR }, order: { rev: 'ASC' } })
+  assert.deepEqual(revs.map((r: any) => r.rev), [1, 2], '구조가 달라졌으니 새 리비전이 남는다')
+
+  /* ② 저장 model·구조 행 — 조회가 새 구조를 본다 */
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: MIRROR } })
+  assert.equal(inst.model.locations.length, 8, '저장 model 가 새 구조다(도크 1 + 빈 7)')
+  assert.equal(await ds.getRepository(TwinLocation).countBy({ instance: { id: inst.id } } as any), 8, '구조 행도 함께 다시 그려진다')
+
+  /* ③ 커널 — 멈추지 않은 채로 새 구조를 들고 있다 */
+  assert.equal(TwinEngine.instances[`${domainId}:${MIRROR}`]?.mode, 'live', '갈아타기가 미러를 멈추지 않는다')
+  const snap = TwinEngine.snapshot(domainId, MIRROR)
+  assert.equal(snap.locations.filter((n: any) => n.type === 'storage').length, 7, '커널도 새 자리를 들고 있다')
+
+  /* 무엇이 달라졌는지 **말한다** — 멈췄다 세우는 마디가 없으므로 말하지 않으면 조용히 지나간다 */
+  const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
+  assert.ok(adopted, '갈아타기는 말없이 성공하지 않는다')
+  assert.equal(adopted.params.locationsAdded, 4, '자리 4개가 늘었다(빈 3→7)')
+  assert.equal(adopted.params.rev, 2)
+})
+
+test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서 직접 세어 보게 하지 않는다', async () => {
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1)) // 지게차 2 → 1
+  const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
+  assert.equal(adopted.params.equipmentDropped, 1)
+
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: MIRROR } })
+  assert.equal(await ds.getRepository(TwinEquipment).countBy({ instance: { id: inst.id } } as any), 1, '표에서도 사라진다')
+  assert.equal(TwinEngine.snapshot(domainId, MIRROR).equipment.length, 1, '커널에서도 사라진다')
+})
+
+test('돌고 있는 시뮬레이션은 여전히 거절한다 — 조건이 바뀐 실험은 다른 실험이다', async () => {
+  await TwinEngine.bootDeclared(domainId, SIM, 'sim-experiment')
+  const before = (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length
+
+  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2)), /is running/)
+
+  assert.equal(
+    (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length,
+    before,
+    '거절된 인제스트는 흔적을 남기지 않는다'
+  )
+})
+
+test('멈춘 미러는 구조를 전환하지 않는다 — 정지한 대상을 전환하려 하지 않는다', async () => {
+  await TwinEngine.stop(domainId, MIRROR)
+  await assert.rejects(
+    () => TwinEngine.adoptStructure(domainId, MIRROR, { locations: [], equipment: [] } as any),
+    /is not running/,
+    '멈춘 트윈은 프로비저닝으로 세우는 것이지 갈아타는 것이 아니다'
+  )
+})

package/test/attention-digest.test.ts

@@ -46,7 +46,7 @@ test('순서는 화면과 같다 — 확인된 것은 아래로, 그다음 심
   assert.equal(d.attentionTotal, 3)
 })
 
-test('한도를 말하지 않으면 자르지 않는다 — 이 값을 모르는 소비처가 일부만 받으면 안 된다', () => {
+test('한도를 지정하지 않으면 자르지 않는다 — 이 값을 모르는 소비처가 일부만 받으면 안 된다', () => {
   const all = Array.from({ length: 30 }, (_, i) => attn(`a${i}`, 'low'))
   assert.equal(digestAttentions(all).attentions.length, 30)
   assert.equal(digestAttentions(all, 0).attentions.length, 30)
@@ -103,7 +103,7 @@ test('★ 순서는 렌즈 순서가 아니라 급한 순서다 — 뒤 렌즈
   assert.equal(d.attentionTotal, 3)
 })
 
-test('★ 두 렌즈가 같은 자리를 가리키면 더 급한 쪽이 색을 정한다 — 하나의 현실이므로', () => {
+test('★ 두 렌즈가 같은 대상을 지목하면 더 급한 쪽이 색을 정한다 — 하나의 현실이므로', () => {
   const d = mergeLensAttentions([
     { instanceId: 'wms', attentions: [attn('a', 'low', 'dock-1')] },
     { instanceId: 'yms', attentions: [attn('b', 'critical', 'dock-1')] }
@@ -127,7 +127,7 @@ test('★ 신호가 없는 렌즈는 아무것도 보태지 않는다 — 빈
   assert.deepEqual(d.attentions.map(a => a.id), ['a'])
 })
 
-test('★ 렌즈가 하나도 없으면 빈 요약 — 공간에 떠 있는 트윈이 없을 때', () => {
+test('★ 렌즈가 하나도 없으면 빈 요약 — 공간에 배치된 트윈이 없을 때', () => {
   const d = mergeLensAttentions([], 20)
   assert.deepEqual(d.attentions, [])
   assert.equal(d.attentionTotal, 0)

package/test/axis-read.test.ts

@@ -0,0 +1,87 @@
+/*
+ * 축의 값을 어디서 읽나 — **선언이 말한 자리에서** (§10 6.5단계)
+ *
+ * ── 왜 있나 ────────────────────────────────────────────────────────────────
+ * 개념 지도는 상태 축을 `state[축이름]` 으로 읽었다. 에너지의 수요 구간은 `state.energy.closed` 에
+ * 살아서 그 규칙으로는 **언제나 `undefined`** 다 — 카드가 「관측 없음」으로 굳는다. 축은 선언돼 있고
+ * 상태에도 값이 있는데 이름이 안 맞을 뿐이라, 화면도 서버도 그 원인을 말해 주지 않는다.
+ *
+ * 이 시험이 지키는 것은 **모름과 없음의 구별**이다: 경로 중간이 비면 `undefined`(모른다)이고, 배열이
+ * 비면 빈 배열(없다)이다. 그 둘을 섞으면 「아직 안 온 것」과 「하나도 없는 것」이 같아진다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { atPath, axisValueOf } from '../shared/axis-read.ts'
+
+test('경로가 없는 축은 이름으로 읽는다 — 지금까지의 거동', () => {
+  const state = { orders: [{ id: 'o1' }], tasks: [] }
+  assert.deepEqual(axisValueOf(state, { axis: 'orders' }), [{ id: 'o1' }])
+  assert.deepEqual(axisValueOf(state, { axis: 'tasks' }), [], '빈 배열은 「없다」다 — 모른다가 아니다')
+})
+
+test('경로가 있으면 그 경로로 읽는다 — 중첩된 축이 조용히 사라지지 않게', () => {
+  const state = { energy: { closed: [{ startMs: 1 }, { startMs: 2 }] } }
+  const value = axisValueOf(state, { axis: 'demandWindows', path: 'energy.closed' })
+  assert.equal(Array.isArray(value), true)
+  assert.equal(value.length, 2)
+  /* 축 이름으로 읽으면 없다 — 그것이 이 함수가 생긴 이유다. */
+  assert.equal((state as any).demandWindows, undefined)
+})
+
+test('경로 중간이 비면 모른다 — 빈 배열로 메우지 않는다', () => {
+  assert.equal(axisValueOf({}, { axis: 'demandWindows', path: 'energy.closed' }), undefined)
+  assert.equal(axisValueOf({ energy: {} }, { axis: 'demandWindows', path: 'energy.closed' }), undefined)
+  /* 에너지 트윈이 아직 표본을 못 받았을 때가 이 경우다 — 「구간 0」이 아니라 「모름」이다. */
+})
+
+test('상태가 없으면 모른다 — 커널이 멈춰 있으면 0 이 아니다', () => {
+  assert.equal(axisValueOf(null, { axis: 'orders' }), undefined)
+  assert.equal(axisValueOf(undefined, { axis: 'demandWindows', path: 'energy.closed' }), undefined)
+})
+
+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)
+})
+
+test('커널 선언과 상태의 모양이 맞는다 — 선언한 경로에 정말 값이 있다', async () => {
+  /*
+   * 선언(`path`)과 실제 상태의 모양이 어긋나면 이 배선은 조용히 빈 카드를 만든다. 그래서 **커널이 낸
+   * 상태로** 확인한다 — 선언을 읽는 쪽과 값을 만드는 쪽이 같은 모양을 쓰는지 보는 것이 요점이다.
+   */
+  const { EmsKernel, axisInfo, ENERGY_EVENT, DEMAND_WINDOW_MS } = await import('@operato/twin-kernel')
+  const info = axisInfo('demandWindows')!
+  assert.ok(info, '커널이 그 축을 선언해야 한다')
+  assert.equal(info.path, 'energy.closed')
+
+  const k = new EmsKernel('t')
+  k.loadTwinModel({ locations: [{ id: 'i', type: 'incoming', capacity: 0 }], equipment: [] })
+  const at = Date.parse('2026-08-14T05:00:00.000Z')
+  const sample = (whenMs: number, kW: number) => ({
+    eventId: `e${whenMs}`,
+    eventType: ENERGY_EVENT.measured,
+    eventTime: new Date(whenMs).toISOString(),
+    tenantId: 't',
+    data: { meterId: 'm', kW, at: new Date(whenMs).toISOString() }
+  })
+
+  /*
+   * 표본이 오기 전에는 **빈 목록**이다 — 그리고 그것이 맞다.
+   *
+   * 처음에는 `undefined`(모름)를 기대했다가 이 시험에 걸렸다. 판단해 보면 빈 목록이 옳다: 커널은
+   * 관측 중이고, 수요 구간은 15분이 지나야 닫힌다. 「아직 하나도 마감되지 않았다」는 **참인 사실**이고
+   * 개념 지도가 그것을 `none-yet` 으로 그린다.
+   *
+   * 「모른다」는 다른 경우다 — 커널이 멈춰 있어 상태 자체가 없을 때(위 시험). 그 둘을 섞지 않는 것이
+   * 이 배선의 요점이다.
+   */
+  assert.deepEqual(axisValueOf(k.getSnapshot(), info), [], '관측 중인데 아직 마감이 없으면 빈 목록이다')
+
+  k.apply(sample(at + 60_000, 100) as any)
+  k.apply(sample(at + DEMAND_WINDOW_MS + 60_000, 120) as any) // 앞 구간 마감
+  const windows = axisValueOf(k.getSnapshot(), info)
+  assert.equal(Array.isArray(windows), true, '선언한 경로에 목록이 있어야 한다')
+  assert.equal(windows.length, 1, '마감된 구간 하나')
+})

package/test/boot-resume.test.ts

@@ -0,0 +1,205 @@
+/*
+ * 재기동을 넘어 **도는 트윈이 계속 돈다** — 그리고 되살리지 못하면 그렇게 말한다.
+ *
+ * ── 실측 (2026-08-14) ───────────────────────────────────────────────────────
+ * 서버를 한 번 재기동하면 등록부는 `running` 이라 말하는데 **아무 커널도 돌지 않았다**.
+ * `bootstrap()` 은 상태만 되찾아 `recovered` 에 담았고, 커널을 세우는 것은 명시 mutation 뿐이었다.
+ * 미러 트윈에서는 계측까지 끊겼다 — `startReferenceLiveFeed` 를 부르는 곳이 `importTwinReference`
+ * 하나뿐이어서, 붙어 있던 커넥터가 조용히 떨어졌다(오류도 로그도 없이).
+ *
+ * 이 시험이 지키는 것 넷:
+ *  ① 부팅이 런타임까지 되살린다(상태 복구만으로는 도는 트윈이 아니다)
+ *  ② 모드를 지어내지 않는다 — 미러였던 것은 미러로(시뮬로 되살리면 없던 움직임을 만든다)
+ *  ③ 되살리지 못한 행은 `stopped` 로 적는다(우리가 고치려던 거짓말이 남지 않게)
+ *  ④ 부팅 훅이 **엔진 다음에** 피드를 다시 붙인다
+ *
+ * 엔진과 레퍼런스 계층은 DB·shell 을 물고 있어 단위 시험이 불러올 수 없다. 그래서 **배선의 모양**을
+ * 소스로 지킨다 — 이 부류의 결함은 「부르는 곳이 없다」는 모양이고, 그건 소스에서 보인다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const engine = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+const live = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-live.ts', import.meta.url)), 'utf-8')
+const boot = readFileSync(fileURLToPath(new URL('../server/index.ts', import.meta.url)), 'utf-8')
+
+/** 그 정적 메서드의 본문만 — 다음 메서드 선언까지. */
+function methodOf(src: string, name: string): string {
+  const at = [`static ${name}(`, `static async ${name}(`].map(sig => src.indexOf(sig)).filter(i => i >= 0).sort((a, b) => a - b)[0]
+  assert.ok(at !== undefined, `${name} 가 없다 — 이름이 바뀌었으면 이 검사도 함께 고친다`)
+  const ends = ['\n  static ', '\n  private static ', '\n  /**'].map(m => src.indexOf(m, at + 10)).filter(i => i >= 0)
+  const end = ends.sort((a, b) => a - b)[0]
+  return src.slice(at, end === undefined ? undefined : end)
+}
+
+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\)/, '복구 뒤 재개 루프가 있어야 한다')
+})
+
+test('모드를 지어내지 않는다 — 미러였던 것은 미러로 되살린다', () => {
+  const body = methodOf(engine, 'resumeRow')
+  assert.match(body, /realityMode === 'mirror'/, '선언된 모드를 보고 갈라야 한다')
+  assert.match(body, /this\.startLive\(/, '미러는 관측 구동으로 세운다')
+  assert.match(body, /this\.startFromRegistry\(/, '시뮬은 등록부의 모드 그대로 세운다')
+  /*
+   * 미러 가지 안을 그대로 떠서 본다 — 미러를 시뮬로 세우면 관측 트윈이 **스스로 물건을 옮긴다**
+   * (없던 움직임을 만드는 것이다). 단어의 거리로 재면 로그·주석에 걸려 헛돈다.
+   */
+  const at = body.indexOf("realityMode === 'mirror'")
+  const mirrorBranch = body.slice(at, body.indexOf('} else {', at))
+  assert.match(mirrorBranch, /startLive\(/, '미러 가지는 관측 구동으로 세워야 한다')
+  assert.equal(mirrorBranch.includes('startFromRegistry'), false, '미러 가지에서 시뮬 기동을 부른다 — 없던 움직임을 만든다')
+})
+
+test('되살리지 못한 행은 stopped 로 적는다 — 「도는 중」이라 말하는 채로 두지 않는다', () => {
+  const resume = methodOf(engine, 'resumeRow')
+  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)/, '되살리지 못한 사실은 로그에도 남아야 한다')
+})
+
+test('벤치 사본은 무인으로 되살아나지 않는다 — 실험은 재기동을 넘기지 못한다', () => {
+  const body = methodOf(engine, 'resumeRow')
+  assert.match(body, /purpose === 'bench'/, '격리 사본을 갈라야 한다')
+  assert.match(body, /bench[\s\S]{0,200}markStopped/, '되살리지 않았으면 등록부도 그렇게 적어야 한다')
+})
+
+test('피드 재개는 등록부가 「도는 미러」라고 말하는 것만 — 멈춘 것을 다시 켜지 않는다', () => {
+  assert.match(live, /export async function resumeReferenceLiveFeeds/, '재개 함수가 있어야 한다')
+  assert.match(live, /r\.status === 'running' && r\.realityMode === 'mirror'/, '도는 미러만 골라야 한다')
+  assert.match(live, /discoverSites/, '사이트 서술자는 다시 찾아서 얻는다(hint 를 남기지 않았다)')
+  /* 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다 — 조용히 넘기지 않는다. */
+  assert.match(live, /NOT reattached/, '못 붙인 것은 이유와 함께 남겨야 한다')
+})
+
+test('부팅 훅이 엔진 다음에 피드를 붙인다 — 순서가 뒤집히면 없는 커널에 계측을 붓는다', () => {
+  assert.match(boot, /resumeReferenceLiveFeeds/, '부팅 훅이 재개를 불러야 한다(부르는 곳이 없으면 없는 기능이다)')
+  const engineAt = boot.indexOf('TwinEngine.bootstrap()')
+  const feedAt = boot.indexOf('resumeReferenceLiveFeeds()')
+  assert.ok(engineAt >= 0 && feedAt > engineAt, '엔진 복구가 피드 재개보다 앞이어야 한다')
+})
+
+/*
+ * ── 부팅 재개가 드러낸 것 (2026-08-14 실측) ─────────────────────────────────
+ * 트윈 14개가 실제로 돌기 시작하자 호스트가 죽었다. 원인은 재개가 아니라 **방송 두 가지**였다:
+ *  ① 시뮬은 delta 마다 곧바로 전 상태를 투영해 방송했다 — 한 tick 이 사실을 수백 개 내면 그 반복이
+ *     이벤트 루프를 35초 막았고(단계 합은 32ms 였다), 그 사이 구독자는 아무것도 빼내지 못했다.
+ *  ② 밀린 push 가 1024를 넘자 pubsub 이 던졌고, 타이머 콜백을 타고 올라온 그 예외가 프로세스를 끝냈다.
+ * 둘 다 재개 없이도 있던 결함이다 — 재개가 그것을 매일 아침 만나게 만들었을 뿐이다.
+ */
+test('시뮬 방송도 모아서 한 번 — delta 마다 전 상태를 투영하지 않는다', () => {
+  const at = engine.indexOf("if (msg.kind === 'delta')")
+  assert.ok(at >= 0, 'sim delta 처리 자리가 없다')
+  const body = engine.slice(at, at + 1400)
+  assert.match(body, /inst\.dirty = true/, 'dirty 로 표시하고')
+  assert.match(body, /ensureBroadcastCoalescer\(\)/, '주기 flush 에 맡겨야 한다')
+  assert.equal(/this\.publishEntityData\(inst\)/.test(body), false, 'delta 마다 곧바로 방송하는 모양으로 되돌아갔다')
+})
+
+test('flush 가 시뮬도 본다 — 라이브만 보면 시뮬 방송이 멈춘 채 남는다', () => {
+  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/, '시뮬은 엔티티 방송까지만')
+})
+
+test('구독자 하나가 호스트를 죽이지 못한다 — 그리고 못 보낸 것을 보낸 것으로 적지 않는다', () => {
+  /* 직접 방송은 **가드 안에 하나**여야 한다 — 그 밖의 호출은 예외가 그대로 올라가는 길이다. */
+  const guardBody = methodOf(engine, 'publishGuarded')
+  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(engine, /if \(!this\.publishGuarded\('data'[\s\S]{0,80}sigs\.delete\(tag\)/, '실패한 태그의 시그니처를 되돌려야 한다')
+})
+
+/*
+ * ── 굶김 안전망 (2026-08-14) ─────────────────────────────────────────────────
+ * 시뮬 틱은 메인 이벤트 루프에서 돈다 — 한 트윈의 틱이 길어지면 그 시간만큼 호스트 전체가 멈춘다
+ * (실측 34.9초). 방송 반복은 걷어냈지만 커널 틱 자체는 여전히 메인 루프에 있고, 근본 해결(분산)은
+ * 이연됐다. 그 사이의 안전망이 이것이다: **호스트를 굶기는 트윈은 멈춘다.**
+ */
+test('굶김은 예산과 다른 문턱으로 판정한다 — 조금 느린 트윈을 내리지 않는다', () => {
+  const body = methodOf(engine, 'guardStarvation')
+  assert.match(body, /this\.TICK_MS \* this\.STARVE_FACTOR/, '굶김 문턱은 틱 간격의 배수다')
+  /* 예산(500ms)으로 내리면 계기판이 말해야 할 「조금 느림」에 트윈이 죽는다. */
+  assert.equal(/budgetMs/.test(body), false, '예산으로 내리는 모양 — 경고와 정지를 섞지 않는다')
+  assert.ok(/STARVE_FACTOR = \d+/.test(engine) && /STARVE_STREAK = \d+/.test(engine), '문턱과 연속 횟수가 상수로 서 있어야 한다')
+})
+
+test('한 번으로 내리지 않고, 한 번 내려오면 연속이 끊긴다', () => {
+  const body = methodOf(engine, 'guardStarvation')
+  assert.match(body, /streak < this\.STARVE_STREAK\) return/, '연속이 차기 전에는 멈추지 않는다')
+  /* 웜스타트 직후 첫 틱은 원래 무겁다(복구한 상태를 처음 접는다) — 그것으로 내리면 재개가 무의미해진다. */
+  assert.match(body, /this\.starveStreak\.delete\(key\)[\s\S]{0,40}return/, '문턱 아래면 연속을 끊어야 한다')
+})
+
+test('멈추는 길은 하나 — 타이머만 끄면 등록부가 계속 「도는 중」이라 말한다', () => {
+  const guard = methodOf(engine, 'stopWithNote')
+  assert.match(guard, /this\.stop\(domainId, id\)/, '공용 stop 을 써야 한다(스냅샷·피드 정리·등록부가 그 안에 있다)')
+  /* 예전 tick 실패 경로는 `clearInterval` 만 했다 — 그 모양으로 되돌아가지 않게. */
+  const tick = methodOf(engine, 'tickGuarded')
+  assert.equal(/clearInterval\(inst\.timer\)/.test(tick), false, '타이머만 끄는 모양으로 되돌아갔다')
+  assert.match(tick, /stopWithNote\(/, '실패도 이유와 함께 멈춰야 한다')
+})
+
+test('왜 멈췄는지 코드로 남고, 다시 세우면 지운다', () => {
+  assert.match(engine, /export interface StopNote/, '이유는 문장이 아니라 코드다(화면이 옮긴다)')
+  assert.match(engine, /code: 'starved', params: \{ streak/, '굶김은 근거 수치와 함께')
+  assert.match(engine, /code: 'tick-failed', params: \{ reason/, '틱 실패는 원문 그대로(옮길 어휘가 아니다)')
+  assert.match(methodOf(engine, 'list'), /stopNote: this\.stopNotes\.get\(/, '목록이 그 사실을 함께 내야 한다')
+  /* 남겨 두면 다시 돌고 있는 트윈이 「굶겨서 멈췄다」고 말한다. */
+  assert.match(engine, /this\.stopNotes\.delete\(key\)/, '다시 세울 때 지워야 한다')
+})
+
+/*
+ * ── 같은 현장 이웃 설비 상태 전달 (2026-08-14) ──────────────────────────────
+ * 시뮬 에너지 트윈은 계측이 없으므로 스스로 부하를 만든다. 그 재료 하나가 「무엇이 돌고 있나」인데,
+ * 그것은 같은 현장 공장 트윈이 아는 사실이다. 호스트는 **누가 이웃인지**만 알려 주고, 무엇을 읽어
+ * 어떻게 부하로 바꿀지는 커널이 정한다 — 호스트가 kW 를 계산해 주면 규칙이 어디에도 안 적힌 채
+ * 트윈마다 갈라진다.
+ */
+test('이웃 상태는 커널이 요청할 때만, 같은 현장에서만 전달한다', () => {
+  const body = methodOf(engine, 'feedPeerEquipment')
+  assert.match(body, /observePeerEquipment !== 'function'\) return/, '이웃을 읽지 않는 커널에는 넘기지 않는다')
+  assert.match(body, /other\.spaceId !== inst\.spaceId\) continue/, '같은 현장만 이웃이다')
+  assert.match(body, /other === inst/, '자기 자신은 이웃이 아니다')
+  /* 상태만 넘긴다 — 스냅샷을 통째로 넘기면 매 tick 상태 크기에 비례한 비용을 치른다. */
+  assert.equal(/snapshot\(\)/.test(body), false, '스냅샷을 넘기는 모양으로 되돌아갔다')
+  assert.match(body, /status: String/, '상태만 실어 보낸다')
+})
+
+test('현장이 없으면 이웃 목록을 비운다 — 옛 상태가 남아 부하를 만들지 않게', () => {
+  const body = methodOf(engine, 'feedPeerEquipment')
+  assert.match(body, /!inst\.spaceId[\s\S]{0,120}observePeerEquipment\(\[\]\)/, '빈 목록으로 덮어야 한다')
+})
+
+test('tick 이 이웃 상태를 먼저 싣는다 — 커널이 그것을 읽어 부하를 만든다', () => {
+  const tick = methodOf(engine, 'tickGuarded')
+  const feedAt = tick.indexOf('feedPeerEquipment')
+  const tickAt = tick.indexOf('runtime.tick(')
+  assert.ok(feedAt >= 0 && tickAt > feedAt, '이웃 상태를 실은 뒤에 tick 해야 한다')
+})
+
+/*
+ * ── 시뮬 트윈의 시각축 (2026-08-15) ─────────────────────────────────────────
+ * 커널의 기본 기준점은 상수(2026-01-01)다. 호스트가 그것을 실제 시각으로 옮기지 않으면 시뮬 트윈의
+ * 저널 시각이 **재기동마다 되감긴다** — 며칠 치 사건이 전부 같은 분에 몰리고, 실 시각으로 창을 자르는
+ * 성과·이력 질의에는 그 트윈이 보이지 않는다. 수요 구간(15분)도 가짜 시각 위에 서게 된다.
+ */
+test('시뮬 기동이 커널의 시각 기준점을 지금으로 맞춘다', () => {
+  const body = methodOf(engine, 'start')
+  assert.match(body, /setClockOrigin\?\.\(Date\.now\(\)\)/, '기동 순간의 실제 시각을 줘야 한다')
+  /* 커널을 세운 **직후**여야 한다 — 시계가 흐른 뒤에 옮기면 그전 사실과 시간축이 어긋난다. */
+  const at = body.indexOf('setClockOrigin')
+  const runtimeAt = body.indexOf('new TwinRuntime(')
+  assert.ok(at >= 0 && runtimeAt > at, '런타임을 세우기 전에 기준점을 맞춘다')
+})