@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/lineage-survives-restart.test.ts

@@ -0,0 +1,203 @@
+/*
+ * ★ 재기동을 건너도 **계보에 입력이 남는다** — 호스트의 웜스타트 경로로 확인한다.
+ *
+ * ── 무엇이 잘못돼 있었나 ──────────────────────────────────────────────────────
+ * 오더의 진행 중 할당(`allocated`)과 거래번호(`bizTransaction`)가 상태 계약에 없어서, 웜스타트가
+ * 오더를 되살릴 때 둘 다 비운 채로 세웠다. 그 오더의 진행 중 작업이 완료되면
+ * `TransformationEvent` 가 **입력 없이** 나간다 — "무엇이 무엇으로 바뀌었나" 에서 "무엇이" 가
+ * 통째로 빠지고, 계보를 거슬러 올라갈 수 없다.
+ *
+ * 실 앱에서 변환 36건 중 35건이 입력 0 이었고 모든 이벤트의 거래번호가 빈값이었다.
+ *
+ * ── 왜 커널 검사만으로 충분하지 않나 ──────────────────────────────────────────
+ * 커널 검사는 `hydrateObserved` 로 직접 심어 확인한다. 호스트는 **저널을 재생해서** 그 씨앗을
+ * 만든다(`recover` → `replay`). 그 경로에서 한 번 더 떨어질 수 있으므로 여기서 실제로 걷는다.
+ */
+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 { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { TwinLineageQuery } = req('../dist-server/service/twin-model/twin-lineage-query.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'lineage-probe'
+const CP = '0614141'
+const pat = (ref: string) => `urn:epc:idpat:sgtin:${CP}.${ref}.*`
+
+/** 원자재 하나로 완제품 하나를 만드는 2단 라인 — 실제 트레일러 템플릿의 축소판. */
+const master = (): any => ({
+  source: INSTANCE,
+  system: 'mes',
+  siteName: '계보 공장',
+  space: { width: 60, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'raw-store', type: 'raw-store', role: 'location', capacity: 500 },
+    { id: 'cut-station', type: 'cut-station', role: 'location', capacity: 50 },
+    { id: 'weld-station', type: 'weld-station', role: 'location', capacity: 50 },
+    { id: 'fg-store', type: 'fg-store', role: 'location', capacity: 500 }
+  ],
+  equipment: [
+    { id: 'cutter-1', kind: 'cutter', homeLocationId: 'cut-station' },
+    { id: 'welder-1', kind: 'welder', homeLocationId: 'weld-station' }
+  ],
+  productionSpec: {
+    companyPrefix: CP,
+    binding: { steel: '077101', frame: '078101' },
+    definition: {
+      materials: [{ id: 'steel' }, { id: 'frame' }],
+      routes: [{ key: 'frame-route', steps: ['cut', 'weld'] }],
+      recipes: [{ key: 'frame-recipe', label: 'f', route: 'frame-route', inputs: [{ material: 'steel', qty: 2 }], outputs: [{ material: 'frame', qty: 1 }] }],
+      operations: [
+        { key: 'cut', label: '절단', intent: 'process', locationType: 'cut-station', resourceType: 'cutter', duration: 'PT1M' },
+        { key: 'weld', label: '용접', intent: 'process', locationType: 'weld-station', resourceType: 'welder', duration: 'PT1M' }
+      ]
+    }
+  }
+})
+
+const SCENARIO = {
+  seed: 9,
+  generators: [
+    { kind: 'inbound-arrival', stimulus: 'arrival', rate: { distribution: 'constant', meanPerHour: 3600 },
+      content: { skuMix: [{ gtin: pat('077101'), weight: 1 }], qtyPerLine: { min: 1, max: 1 } } },
+    { kind: 'production-order', stimulus: 'order', rate: { distribution: 'constant', meanPerHour: 120 },
+      content: { skuMix: [{ gtin: pat('078101'), weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }
+  ]
+}
+
+/** 저널에 남은 변환 이벤트들 — 계보가 실제로 무엇을 기록했나. */
+async function transforms(): Promise<{ inputs: number; outputs: number; tx: string }[]> {
+  const rows: any[] = await ds.getRepository(TwinEvent).find({ where: { domain: { id: domainId } as any, instanceId: INSTANCE } as any })
+  return rows
+    .filter(r => r.eventType === 'epcis.TransformationEvent')
+    .map(r => ({
+      inputs: (r.payload?.data?.inputEPCList ?? []).length,
+      outputs: (r.payload?.data?.outputEPCList ?? []).length,
+      tx: r.payload?.data?.bizTransactionList?.[0]?.bizTransaction ?? ''
+    }))
+}
+
+/**
+ * 틱과 자극은 **런타임**에 있다 — `startFromRegistry` 가 돌려주는 것은 호스트의 인스턴스 기록이고
+ * 커널 런타임은 그 안에 있다(둘을 같은 것으로 보면 `scenario` 가 없다고 나온다).
+ */
+const runtime = () => TwinEngine.runtime(domainId, INSTANCE)
+
+function tick(n: number): void {
+  const rt = runtime()
+  for (let i = 0; i < n; i++) rt.tick(1000)
+}
+
+/**
+ * 상태는 런타임의 `resync()` 로 얻는다 — `{ revision, state }` 를 돌려주므로 축은 그 **안에** 있다.
+ * (`TwinEngine.snapshot` 도 이것을 그대로 넘겨 주므로 축이 한 겹 안에 들어 있다.)
+ */
+const orders = () => ((runtime().resync().state?.orders ?? []) as any[])
+
+function drive(): void {
+  const rt = runtime()
+  rt.scenario.load(SCENARIO)
+  rt.scenario.start()
+}
+
+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: 'lineage-test', subdomain: 'lineage-test' } as any)
+  domainId = d.id
+  await TwinEngine.ingestMaster(domainId, master())
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('재기동을 건너도 계보에 입력이 실린다 — 웜스타트가 확보분을 잃지 않는다', async () => {
+  /* ① 한 번 굴려 진행 중 할당을 만든다. */
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-world')
+  drive()
+  tick(200)
+  const workingBefore = orders().filter(o => (o.allocated ?? []).length)
+  assert.ok(workingBefore.length, '진행 중 확보분이 있어야 이 검사가 뜻이 있다')
+
+  /* ② 멈추고 **저널을 재생해** 다시 세운다 — 호스트의 웜스타트 경로 그대로. */
+  await TwinEngine.stop(domainId, INSTANCE)
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-world')
+
+  const revived = orders().filter(o => (o.allocated ?? []).length)
+  assert.ok(revived.length, '되살아난 오더가 확보분을 들고 있어야 한다 — 잃으면 계보의 입력이 빈다')
+
+  /* ③ 되살아난 작업이 끝날 만큼 더 굴린다. */
+  drive()
+  tick(300)
+
+  const all = await transforms()
+  assert.ok(all.length, '변환이 저널에 남아야 이 검사가 뜻이 있다')
+  const withInputs = all.filter(t => t.inputs > 0)
+  assert.ok(withInputs.length, '입력이 실린 변환이 하나도 없다 — 계보의 "어디서 왔나" 가 통째로 빈다')
+
+  /* 거래번호도 함께 — 계보가 **무슨 거래로** 일어났는지 잇는 축이다. */
+  assert.ok(all.some(t => t.tx), '거래번호가 전부 빈값이다 — 계보를 거래로 이을 수 없다')
+})
+
+test('계보를 거슬러 올라가 선언과 나란히 놓는다 — 그 차이가 진단이다', async () => {
+  const q = new TwinLineageQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+
+  /* 완제품 하나를 고른다 — 저널이 그것을 산출로 실은 변환이 있어야 계보가 있다. */
+  const rows: any[] = await ds.getRepository(TwinEvent).find({ where: { domain: { id: domainId } as any, instanceId: INSTANCE } as any })
+  /* **완제품**을 고른다. 변환에는 중간 산물(WIP)을 내는 것도 있어서 아무거나 집으면 WIP 이 잡히고,
+     WIP 은 선언된 자재가 아니라 라우트의 내부 산물이므로 견줄 대상이 아니다. */
+  const made = rows
+    .filter(r => r.eventType === 'epcis.TransformationEvent' && (r.payload?.data?.inputEPCList ?? []).length)
+    .flatMap(r => r.payload.data.outputEPCList ?? [])
+    .filter((e: string) => e.includes(`.078101.`))
+  assert.ok(made.length, '완제품을 낸 변환이 있어야 이 검사가 뜻이 있다')
+
+  const lin = await q.twinItemLineage(INSTANCE, made[0], ctx)
+  assert.ok(lin, '계보가 나와야 한다')
+  assert.equal(lin.epc, made[0])
+  assert.ok(lin.items.length > 1, '거슬러 올라간 것이 있어야 한다 — 하나면 아무것도 안 찾은 것이다')
+  assert.ok(lin.edges.some((e: any) => e.from === made[0]), '이 개체를 만든 직접 투입이 보여야 한다')
+
+  /* 근거를 밝힌다 — 창을 넘겨 끊겼으면 계보가 실제보다 얕게 보인다. */
+  assert.equal(lin.basis.source, 'journal')
+  assert.equal(typeof lin.basis.transformationsRead, 'number')
+
+  /* **겹쳐 보기** — 선언(레시피)과 관측(실제 투입)을 자재별로 나란히. */
+  assert.equal(lin.conformance.comparable, true, `견줄 수 없으면 이유를 말한다: ${lin.conformance?.reason}`)
+  const steel = lin.conformance.lines.find((l: any) => l.material === 'steel')
+  assert.ok(steel, '레시피가 선언한 자재가 줄로 나와야 한다')
+  assert.equal(steel.declared, 2, '레시피는 강재 2개를 요구한다')
+  assert.equal(steel.observed, 2, '실제로도 2개를 먹었다 — 설계대로다')
+  assert.equal(steel.matches, true)
+})
+
+test('바인딩이 없으면 비교하지 않고 이유를 알린다 — 짐작으로 이으면 거짓 진단이 된다', async () => {
+  const q = new TwinLineageQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+  /* 개체이긴 하지만 바인딩에 없는 품목 — 짐작으로 자재에 붙이면 "설계와 다르다" 는 거짓이 나온다. */
+  const lin = await q.twinItemLineage(INSTANCE, `urn:epc:id:sgtin:${CP}.099999.1`, ctx)
+  assert.equal(lin.conformance.comparable, false)
+  assert.equal(lin.conformance.reason, 'item-not-bound')
+})

package/test/live-feed-registry.test.ts

@@ -0,0 +1,67 @@
+/*
+ * 「계측이 들어오고 있나」 — **도는 것과 받는 것을 가른다.**
+ *
+ * ── 무엇이 보이지 않았나 (2026-08-14) ───────────────────────────────────────
+ * 미러 트윈은 커널이 돌기만 하면 「도는 중」이었다. 피드가 떨어져 있으면 그 트윈은 아무것도 받지
+ * 않으면서 도는 중인데, 화면에서 두 상태가 똑같이 보였다 — 재기동 뒤 실제로 그랬고 사람은
+ * 「값이 안 변하네」로 뒤늦게 알았다.
+ *
+ * 이 모듈은 DB 를 물지 않는다 — 그래서 배선의 모양이 아니라 **거동**을 시험한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { registerLiveFeedProbe, liveFeedAttached, liveFeedStateOf } from '../server/engine/live-feed-registry.ts'
+
+/* 두 계층의 장부를 흉내낸다 — 커넥터 기반과 프리셋 기반. */
+const connectorFeeds = new Set<string>()
+const presetFeeds = new Set<string>()
+registerLiveFeedProbe(() => [...connectorFeeds])
+registerLiveFeedProbe(() => [...presetFeeds])
+
+test('어느 장부든 붙어 있다고 하면 붙어 있다 — 한쪽만 보면 흐르는 트윈을 끊겼다고 부른다', () => {
+  connectorFeeds.add('ems-plant-1')
+  presetFeeds.add('sap-wh-1')
+
+  assert.equal(liveFeedAttached('ems-plant-1'), true, '커넥터 기반 피드')
+  assert.equal(liveFeedAttached('sap-wh-1'), true, '프리셋 기반 피드 — 이걸 놓치면 거짓 경보가 된다')
+  assert.equal(liveFeedAttached('nobody'), false)
+})
+
+test('답하지 못하는 장부가 다른 계층의 사실을 죽이지 않는다', () => {
+  registerLiveFeedProbe(() => {
+    throw new Error('registry down')
+  })
+  /* 터진 장부 뒤에 등록된 장부의 사실도 그대로 읽혀야 한다. */
+  const late = new Set<string>(['late-twin'])
+  registerLiveFeedProbe(() => [...late])
+  assert.equal(liveFeedAttached('late-twin'), true)
+  assert.equal(liveFeedAttached('ems-plant-1'), true)
+})
+
+test('「없음」과 「해당 없음」을 섞지 않는다', () => {
+  /* 도는 미러 — 이 둘이 우리가 보이려던 구별이다. */
+  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: true, instanceId: 'ems-plant-1' }), 'attached')
+  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: true, instanceId: 'ems-plant-2' }), 'detached')
+
+  /* 시뮬 트윈에는 나를 피드가 **없어야 한다** — 결함이 아니라 그 트윈의 성질이다. */
+  assert.equal(liveFeedStateOf({ realityMode: 'sim-world', running: true, instanceId: 'hatio-us' }), 'not-applicable')
+  assert.equal(liveFeedStateOf({ realityMode: 'sim-experiment', running: true, instanceId: 'trailer-new' }), 'not-applicable')
+
+  /* 사람이 멈춰 둔 트윈에게 피드를 묻는 것은 뜻이 없다. */
+  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: false, instanceId: 'ems-plant-1' }), 'not-applicable')
+
+  /* 선언이 없으면 미러라고 짐작하지 않는다(짐작으로 경보를 울리지 않는다). */
+  assert.equal(liveFeedStateOf({ running: true, instanceId: 'ems-plant-1' }), 'not-applicable')
+})
+
+test('목록이 그 사실을 함께 낸다 — 화면이 따로 물어야 하면 언젠가 묻지 않는다', async () => {
+  const src = await import('node:fs').then(fs =>
+    fs.readFileSync(new URL('../server/engine/twin-engine.ts', import.meta.url), 'utf-8')
+  )
+  const at = src.indexOf('static async list(')
+  assert.ok(at >= 0, 'list() 가 없다 — 이름이 바뀌었으면 이 검사도 함께 고친다')
+  const body = src.slice(at, src.indexOf('\n  /** 운영 공간 목록', at))
+  assert.match(body, /liveFeed: liveFeedStateOf\(/, '관리 목록 행에 피드 사실이 실려야 한다')
+  assert.match(body, /realityMode: r\.realityMode/, '선언된 모드를 넘겨야 한다(짐작하지 않는다)')
+})

package/test/live-kernel-facts.test.ts

@@ -0,0 +1,161 @@
+/*
+ * 라이브에서 **커널이 낸 사실**이 사라지지 않는다 — 저널에 남고, 인입은 두 번 적히지 않는다.
+ *
+ * ── 실측 (2026-08-14) ───────────────────────────────────────────────────────
+ * 에너지 트윈에 커넥터를 붙여 표본을 흘렸다. 저널에 `energy.measured` 48건이 쌓였는데 **구간 마감은
+ * 0건**이었다. 커널은 15분 경계에서 마감 사실을 내고 있었지만(`emitOp`) 라이브 경로에 그것을 구독하는
+ * 곳이 없어서 **커널 안에서 사라졌다.** 저널을 읽는 성과 화면의 전력 타일은 영원히 나오지 않는다.
+ *
+ * sim 은 `runtime.subscribe` 로 같은 일을 한다 — 라이브에만 그 배선이 없었다.
+ *
+ * 이 시험이 지키는 것 둘:
+ *  ① 라이브 기동은 커널 사건을 구독한다(그 사실이 저널로 간다)
+ *  ② 인입 봉투는 **한 번만** 적힌다 — `apply()` 가 그것을 구독자에게 되흘리기 때문이다
+ *
+ * 엔진은 DB·shell 을 물고 있어 단위 시험이 불러올 수 없다. 그래서 **배선의 모양**을 소스로 지킨다 —
+ * 실제 거동은 실서버에서 확인했고(그때 이 결함이 드러났다), 여기서는 그 배선이 사라지지 않게 한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+
+/** 그 정적 메서드의 본문만 — 다음 메서드 선언까지. `async` 도 찾는다(빠뜨리면 있는 메서드를 없다고 한다). */
+function methodOf(name: string): string {
+  const at = [`static ${name}(`, `static async ${name}(`].map(sig => src.indexOf(sig)).find(i => i >= 0) ?? -1
+  assert.ok(at >= 0, `${name} 가 없다 — 이름이 바뀌었으면 이 검사도 함께 고친다`)
+  const next = src.indexOf('\n  static ', at + 10)
+  return src.slice(at, next < 0 ? undefined : next)
+}
+
+test('라이브 기동이 커널 사건을 구독한다 — 판정이 저널로 가는 유일한 길', () => {
+  const body = methodOf('startLive')
+  assert.match(body, /kernel\.onEvent\?\.\(/, '구독이 없으면 커널의 마감·피크·제안이 사라진다')
+  assert.match(body, /pendingJournal/, '구독한 사실은 저널 배치로 가야 한다')
+  /* 예전에는 `unsub: () => {}` 로 아무것도 구독하지 않았다 — 그 모양으로 되돌아가지 않게 못 박는다. */
+  assert.equal(
+    /unsub: \(\) => \{\}[\s\S]{0,80}$/.test(body.trim()),
+    false,
+    'startLive 가 아무것도 구독하지 않는 모양으로 되돌아갔다'
+  )
+})
+
+test('인입 봉투는 저널에 한 번만 적힌다 — apply 가 그것을 되흘린다', () => {
+  const start = methodOf('startLive')
+  const ingest = methodOf('ingestLive')
+  /* 표시하고(ingest) 걸러낸다(구독). 둘 중 하나만 있으면 인입이 두 번 적히거나 표시가 무의미해진다. */
+  assert.match(ingest, /applying\?\.add\(/, '인입 봉투를 표시해야 한다')
+  assert.match(start, /applying\.has\(/, '표시된 봉투는 구독에서 건너뛰어야 한다')
+})
+
+test('식별자가 아니라 **객체 동일성**으로 가른다 — 어댑터의 id 규칙에 기대지 않게', () => {
+  const start = methodOf('startLive')
+  assert.match(start, /WeakSet<object>/, '약한 참조로 표시한다(따로 비울 것이 없다)')
+  /* eventId 비교는 어댑터가 id 를 어떻게 만드는지에 기대게 되어 약하다 — 그 방식으로 되돌아가지 않게. */
+  assert.equal(/applying\.has\(e\.eventId\)/.test(start), false, 'id 비교로 되돌아갔다')
+})
+
+test('커널이 낸 사실도 방송을 예약한다 — 피크·마감은 상태를 바꾼다', () => {
+  const body = methodOf('startLive')
+  assert.match(body, /inst\.dirty = true/, '상태가 바뀌었으므로 다음 주기에 방송해야 한다')
+  assert.match(body, /ensureBroadcastCoalescer\(\)/, '방송은 주기로 합친다(사건마다 방송하면 폭발한다)')
+})
+
+/*
+ * ── 구조 전환도 방송한다 (2026-08-18) ───────────────────────────────────────
+ * 화면이 보는 것 상당수가 구조에서 파생된다(계약 대비 판정·주목 신호·자리 색). 구조 전환이 조용히
+ * 끝나면 지도 레일은 다음 계측 표본이 올 때까지 옛 화면을 들고 있고, 헤더 배지는 폴링으로 먼저 알아
+ * 「배지엔 있고 목록엔 없는」 어긋난 화면이 된다(실화면에서 봤다).
+ */
+test('구조 전환은 상태 방송을 예약한다 — 다음 표본까지 화면이 옛것을 들고 있지 않게', () => {
+  const body = methodOf('adoptStructure')
+  assert.match(body, /inst\.dirty = true/, '구조가 바뀐 순간이 상태가 바뀐 순간이다')
+  assert.match(body, /ensureBroadcastCoalescer\(\)/, '새 경로가 아니라 있는 병합 규율에 얹는다')
+  /* 커널 전환보다 먼저 방송하면 구독자가 옛 스냅샷을 되물어 간다 — 순서가 규율이다. */
+  assert.ok(
+    body.indexOf('inst.kernel.adoptStructure(model)') < body.indexOf('inst.dirty = true'),
+    '커널을 갈고 나서 방송한다'
+  )
+})
+
+/*
+ * ── 자를 것을 알면서 다 읽어 오지 않는다 (2026-08-18 실측) ───────────────────
+ * 저널을 전량 읽어 온 뒤 JS 에서 걸렀다. 27만 건짜리 트윈에서 한 시간 전 상태를 물으면 7.4초가 걸렸고,
+ * 그 대부분이 「필요 없는 행을 읽어 오는 시간」이었다. 시각·리비전 상한은 SQL 이 아는 조건이다.
+ *
+ * 시간 측정은 도는 서버에서 크게 흔들리므로(같은 질의 596~1547ms) **배선**을 지킨다.
+ */
+test('저널 상한은 SQL 에서 자른다 — 읽고 나서 버리지 않는다', () => {
+  const body = methodOf('recover')
+  assert.match(body, /eventTime: LessThanOrEqual\(new Date\(cutoffMs\)\)/, '시각 상한은 질의 조건이다')
+  assert.match(body, /revision: LessThanOrEqual\(untilRevision\)/, '리비전 상한도 질의 조건이다')
+  /* 시각이 비어 있는 옛 행은 함께 가져온다 — SQL 로 자르면 그 행들이 빠져 예전과 다른 결과가 된다. */
+  assert.match(body, /eventTime: IsNull\(\)/, '시각 없는 레거시 행을 잃지 않는다')
+  /* 읽어 온 뒤 다시 거르지 않는다 — 두 벌이 되면 어느 쪽이 진짜 조건인지 흐려진다. */
+  assert.equal(/rows\.filter\(/.test(body), false, '읽고 나서 또 거르지 않는다')
+})
+
+test('과거 화면의 「지금」은 잘라 낸 뒤의 마지막 사실이다 — 미래 이벤트를 쓰지 않는다', () => {
+  const body = methodOf('recover')
+  /* 예전에는 전량(rows)의 마지막 시각을 썼다 — 물어본 시점보다 뒤의 이벤트라 과거 화면이 미래를
+     기준으로 「늦었다」를 판정할 수 있었다. 이제 rows 는 이미 잘린 것이다. */
+  assert.match(body, /const wanted = rows/, '자른 것과 접는 것이 같아야 한다')
+})
+
+/*
+ * ── 재개점에서 이어 접는다 (2026-08-18) ──────────────────────────────────────
+ * 접은 결과는 이미 남기고 있었지만, 그 지점의 **재개점**(리듀서 내부 상태 전부 + 가동 누적기)이 없어서
+ * 이벤트가 하나만 늘어도 0부터 다시 접어야 했다. 동치는 커널 시험이 증명한다(0부터 == 재개점 + 꼬리).
+ * 여기서는 **호스트가 그 씨앗을 실제로 쓰는지**를 지킨다 — 배선이 사라지면 지름길은 조용히 사라진다.
+ */
+test('폴드가 재개점을 쓰고, 새 재개점을 함께 남긴다', () => {
+  const body = methodOf('recover')
+  assert.match(body, /replayFrom\(model, resume\.fold\.reducer/, '씨앗이 있으면 꼬리만 접는다')
+  assert.match(body, /revision: MoreThan\(from\)/, '읽는 것도 그 뒤만')
+  assert.match(body, /oee\.restore\(resume\.fold\.oee\)/, '가동 누적기도 이어받는다(없으면 가용률이 작아진다)')
+  assert.match(body, /replayWithCheckpoint\(/, '씨앗이 없을 때도 새 재개점을 만든다')
+  assert.match(body, /keep\(withNow\(out\.state\), \{ reducer: out\.checkpoint, oee: oee\.serialize\(\) \}\)/, '재개점을 함께 저장한다')
+})
+
+test('씨앗을 좁게 쓴다 — 캐시가 사실을 이기지 않는다', () => {
+  const body = methodOf('recover')
+  /* 지금을 물었을 때만·구조가 그대로일 때만. 시간여행은 목표 이전 재개점이 필요하고(사슬은 다음 단계),
+     구조가 바뀌면 그 경계에서 갈라 접어야 한다. */
+  assert.match(body, /asOfNowRead && tip && cachedForResume && cachedForResume\.fold/, '지금 읽기에만 쓴다')
+  assert.match(body, /\(cachedForResume\.structureRev \?\? null\) === tip\.structureRev/, '구조가 같을 때만 쓴다')
+  assert.match(body, /segments\.length <= 1/, '구조가 갈린 폴드에는 쓰지 않는다')
+})
+
+/*
+ * ── 재개점 **사슬** (2026-08-18) ─────────────────────────────────────────────
+ * 최신 재개점 하나로는 과거를 도울 수 없다 — 그것은 언제나 목표보다 뒤에 있다. 그래서 지점을 여러 개
+ * 남기고, 과거를 물으면 **목표 직전** 지점에서 접는다. 지점은 각각 상태 전체를 들고 있어 무겁기 때문에
+ * 눈금(리비전 간격)을 넘을 때만 남기고 최근 몇 개만 든다 — 더 과거는 0부터 접는다(알려진 한계).
+ */
+test('과거 읽기는 목표 직전 지점에서 접는다 — 사슬을 쓴다', () => {
+  const body = methodOf('recover')
+  assert.match(body, /this\.chainSeedFor\(domainId, instanceId, \{/, '과거 씨앗을 사슬에서 고른다')
+  assert.match(body, /structureCount <= 1/, '구조가 갈린 트윈에서는 쓰지 않는다')
+  assert.match(body, /revision: And\(MoreThan\(from\), LessThanOrEqual\(untilRevision\)\)/, '씨앗 뒤 · 목표 이내만 읽는다')
+  assert.match(body, /this\.keepChainPoint\(domainId, instanceId, \{/, '지점을 남긴다')
+})
+
+test('시각으로 물으면 지점의 시각도 목표 이내여야 한다 — 짐작하지 않는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const at = src.indexOf('private static async chainSeedFor(')
+  const body = src.slice(at, src.indexOf('\n  private static async keepChainPoint(', at))
+  assert.match(body, /if \(!Number\.isFinite\(t\) \|\| t > target\.timeMs\) continue/, '시각을 모르는 지점은 쓰지 않는다')
+  assert.match(body, /if \(!value\?\.fold\?\.reducer\) continue/, '재개점 없는 지점은 씨앗이 아니다')
+})
+
+test('사슬은 눈금을 넘을 때만 자라고, 최근 몇 개만 든다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const at = src.indexOf('private static async keepChainPoint(')
+  const body = src.slice(at, src.indexOf('\n  /** 이 트윈 저널의 끝 리비전', at))
+  assert.match(body, /value\.revision - newest < this\.CHAIN_STRIDE\) return/, '눈금을 넘지 않으면 남기지 않는다')
+  assert.match(body, /slice\(-this\.CHAIN_KEEP\)/, '최근 몇 개만 든다')
+  /* 공용 캐시에 삭제 API 가 없다는 사실을 숨기지 않는다 — 버린 지점은 TTL 까지 남는다. */
+  assert.match(body, /values expire with the cache TTL/, '버린 지점의 운명을 말한다')
+})

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

@@ -13,7 +13,7 @@ import assert from 'node:assert/strict'
 
 import { WmsKernel, StateProjector, deriveAttentions, computeOee } from '@operato/twin-kernel'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 import { withLiveAttentions } from '../server/engine/live-attentions.ts'
 
 const GTIN = 'urn:epc:idpat:sgtin:0614141.099999.*'
@@ -36,17 +36,17 @@ const master = () => ({
 
 /** 커널 sim 구동 + 방출 이벤트 수집(커널 face2 테스트 패턴). */
 function runSim() {
-  const board = masterToTwin(master()).board
+  const model = masterToTwin(master()).model
   const kernel = new WmsKernel('t')
   const events: any[] = []
   kernel.onEvent((e: any) => events.push(e))
-  kernel.loadBoard(board)
+  kernel.loadTwinModel(model)
   kernel.scenario.load({ seed: 42, generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 120 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }] })
   kernel.scenario.start()
   for (let i = 0; i < 300; i++) kernel.tick(1000)
   kernel.scenario.pause()
   for (let i = 0; i < 60; i++) kernel.tick(1000)
-  return { board, kernel, events }
+  return { model, kernel, events }
 }
 
 const sortByTag = (arr: any[]) => [...arr].sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0))
@@ -72,13 +72,13 @@ const coreOnly = (d: any) => {
 
 /** sim(커널) · live(projector 재투영) payload 를 태그로 정렬해 나란히. */
 function bothPayloads() {
-  const { board, kernel, events } = runSim()
+  const { model, kernel, events } = runSim()
   assert.ok(events.length > 0, 'sim 이벤트 생성됨')
-  const proj = new StateProjector(board)
+  const proj = new StateProjector(model)
   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'))
   }
 }
 
@@ -91,7 +91,7 @@ test('★ 라이브 미러: 핵심 관측 상태(점유·용량·위치·아이
   const { sim, live } = bothPayloads()
   const simCore = sim.map(d => ({ tag: d.tag, data: coreOnly(d.data) }))
   const liveCore = live.map(d => ({ tag: d.tag, data: coreOnly(d.data) }))
-  // 통로(라우팅)는 온전 — 이벤트로 재구성되는 관측 상태는 두 드라이버가 동일 → 보드가 동일 렌더.
+  // 통로(라우팅)는 온전 — 이벤트로 재구성되는 관측 상태는 두 드라이버가 동일 → 모델이 동일 렌더.
   assert.deepEqual(liveCore, simCore, 'occupancy/capacity/location/item 등 핵심 관측 상태 일치')
 })
 
@@ -112,15 +112,15 @@ function runSimRich() {
       { id: 'fk-2', kind: 'forklift', homeLocationId: 'dock-recv' }
     ]
   }
-  const board = masterToTwin(m).board
+  const model = masterToTwin(m).model
   const kernel = new WmsKernel('t')
   const events: any[] = []
   kernel.onEvent((e: any) => events.push(e))
-  kernel.loadBoard(board)
+  kernel.loadTwinModel(model)
   kernel.scenario.load({ seed: 7, generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 600 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }] })
   kernel.scenario.start()
   for (let i = 0; i < 120; i++) kernel.tick(1000) // 이동중·고장·병목이 살아있는 시점
-  const proj = new StateProjector(board)
+  const proj = new StateProjector(model)
   for (const env of events) proj.apply(env)
   return { sim: kernel.getSnapshot() as any, live: proj.snapshot() as any }
 }
@@ -195,10 +195,17 @@ test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE
   assert.ok(m?.oee, 'sim 무버 oee 존재')
   const o = m.oee
 
-  // live 텔레메트리/누적기가 공급할 카운터 + 재구성 nowMs(planned) 로 공식 재적용.
+  /*
+   * live 텔레메트리/누적기가 공급할 카운터 + **계측 창** 으로 공식 재적용.
+   *
+   * 창을 명시한다(`metricsSinceMs: 0` 부터 `planned` 까지). 예전 이 검사는 창을 넘기지 않고 공식이
+   * 그것을 epoch(0)로 메우는 것에 **기대고** 있었다 — 그 메움이 화면에 56,000년 유휴를 세운 결함이라
+   * 없앴다. 이제 창을 모르면 잰 시간이 없으므로, 재생산에는 창이 함께 와야 한다. 라이브 공급자가
+   * 실제로 하는 일이 그것이다(누적기는 첫 이벤트 시각을 창으로 낸다).
+   */
   const planned = o.runMs + o.setupMs + o.downMs + o.idleMs
   const derived = computeOee(
-    { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, scrapCount: o.scrapCount },
+    { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, scrapCount: o.scrapCount, metricsSinceMs: 0 },
     planned
   )
   const near = (a: number, b: number) => Math.abs(a - b) < 1e-6
@@ -231,3 +238,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 { model, events } = runSim()
+  const proj = new StateProjector(model)
+  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')
+})