@things-factory/headless-twin 10.0.12 → 10.0.14

package/test/loop-lag.test.ts

@@ -0,0 +1,82 @@
+/*
+ * 루프 지체 계기 — **원인을 지어내지 않기 위한 값**이 정확한지 본다 (2026-08-21).
+ *
+ * 지키는 것:
+ *  ① 늦게 깨어난 만큼만 지체다 — 제때 깨어난 표본은 0 이고, 0 을 정체로 세지 않는다.
+ *  ② 창이 닫히기 전에는 `recent` 가 **null** 이다(채우는 중인 창을 「지금」으로 읽으면 과소 집계다).
+ *  ③ 가장 길게 막힌 **시각**을 든다 — 언제였는지가 원인을 가리는 근거다.
+ *  ④ 문턱 이하의 흔들림은 정체로 세지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { LoopLagSampler } from '../server/engine/loop-lag.ts'
+
+/** 시계를 손으로 밀어 넣는다 — 실제 타이머로 재면 기계 상태가 결과를 정한다. */
+function sampler(sampleMs = 500, stallMs = 200, windowMs = 10_000) {
+  let now = 1_000_000
+  const s = new LoopLagSampler(sampleMs, stallMs, windowMs, () => now)
+  return { s, advance: (ms: number) => (now += ms), at: () => now }
+}
+
+test('제때 깨어난 표본은 지체가 0 이고 정체로 세지 않는다', () => {
+  const { s, advance, at } = sampler()
+  for (let i = 0; i < 4; i++) {
+    advance(500)
+    assert.equal(s.sample(at()), 0)
+  }
+  assert.equal(s.view().total.stalls, 0)
+  assert.equal(s.view().total.maxMs, 0)
+  assert.equal(s.view().total.samples, 4)
+})
+
+test('늦게 깨어난 만큼이 지체다 — 그 초과분만', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(4_600) // 예정보다 4,100ms 늦게
+  assert.equal(s.sample(at()), 4_100)
+  assert.equal(s.view().total.maxMs, 4_100)
+  assert.equal(s.view().total.stalls, 1)
+})
+
+test('문턱 이하의 흔들림은 정체가 아니다 — 값은 남기고 세지는 않는다', () => {
+  const { s, advance, at } = sampler(500, 200)
+  advance(650) // 150ms 지체 — 문턱 200 미만
+  s.sample(at())
+  const v = s.view()
+  assert.equal(v.total.maxMs, 150)
+  assert.equal(v.total.stalls, 0, '문턱 이하를 세면 정상 상태가 정체로 보인다')
+})
+
+test('창이 닫히기 전에는 recent 가 null 이다 — 채우는 중인 창을 「지금」으로 읽지 않는다', () => {
+  const { s, advance, at } = sampler(500, 200, 2_000)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().recent, null)
+
+  /* 창 길이를 넘기면 그 창이 닫혀 `recent` 가 된다. */
+  advance(2_000)
+  s.sample(at())
+  const v = s.view()
+  assert.ok(v.recent, '창 길이를 넘겼으면 닫힌 창이 있어야 한다')
+  assert.equal(v.recent!.stalls, 1, '1,500ms 지체는 정체 한 번이다')
+})
+
+test('가장 길게 막힌 시각을 든다 — 언제였는지가 원인을 가린다', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(3_000)
+  const worst = at()
+  s.sample(worst)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().worstAtMs, worst)
+})
+
+test('한 번도 재지 않았으면 정체 시각은 null 이다 — 0 으로 적지 않는다', () => {
+  const { s } = sampler()
+  assert.equal(s.view().worstAtMs, null)
+  assert.equal(s.view().recent, null)
+})

package/test/mirror-resumes-from-checkpoint.test.ts

@@ -0,0 +1,192 @@
+/*
+ * ★ **재기동이 저널을 처음부터 다시 접지 않는다** — 미러가 저장된 재개점에서 이어 선다.
+ *
+ * ── 무엇이 오래 잘못돼 있었나 (2026-08-24 실측) ─────────────────────────────
+ * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 접고, 없으면 저널을 0부터
+ * 접는다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
+ * 적었다. 실측으로 저장된 스냅샷 34건 전부 `fold` 가 비어 있었고, 저널은 2,960만 줄이었다.
+ *
+ * 그래서 두 가지가 함께 일어났다.
+ *
+ *   ① 켤 때마다 처음부터 접었다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
+ *   ② 미러는 되찾은 상태를 **버렸다**(`startLive`). 「다음 계측이 정정한다」는 전제였는데, 원본이 커서
+ *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 조용했다
+ *
+ * ── 왜 커널 시험만으로 충분하지 않나 ────────────────────────────────────────
+ * 커널은 「재개점 + 꼬리 == 0부터 접기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
+ * 호스트가 재개점을 **적지 않거나 되세우지 않으면** 아무 일도 일어나지 않는다 — 이 저장소가 실제로
+ * 넉 달 동안 그 상태였다. 그래서 여기서 DB 를 물고 실제로 걷는다.
+ *
+ * ── 결정적인 단정 ───────────────────────────────────────────────────────────
+ * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 접어 온 것이 **아니다** —
+ * 저장된 재개점에서 온 것이다. 그리고 그 상황은 가정이 아니라 설계된 거동이다: 보존 정책이 체크포인트
+ * 리비전 이하의 행을 지운다(「그 앞은 스냅샷이 대신한다」).
+ */
+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')
+/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 조용히 실패한다(스냅샷도 씨앗도). */
+const { entities: cacheEntities } = req('@things-factory/cache-service/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 { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'resume-probe'
+
+/** 미러 하나 — 원본이 사실을 말해 주는 트윈이므로 시나리오도 레시피도 필요 없다. */
+const master = (): any => ({
+  source: INSTANCE,
+  system: 'wms',
+  siteName: '재개점 창고',
+  origin: { kind: 'reference' }, // 현실 출처 선언 — 이것이 미러로 뜨는 근거다
+  space: { width: 40, depth: 20, unit: 'm' },
+  locations: [
+    { id: 'dock', type: 'dock', role: 'location', capacity: 100 },
+    { id: 'bin-1', type: 'storage', role: 'location', capacity: 100 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
+})
+
+/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 접어 상태를 만든다. */
+function facts(n: number): any[] {
+  const out: any[] = []
+  for (let i = 1; i <= n; i++) {
+    out.push({
+      eventId: `o-${i}`,
+      eventType: 'order.status',
+      eventTime: '2026-08-24T01:00:00.000Z',
+      tenantId: domainId,
+      data: { orderId: `WO-${i}`, kind: 'workorder', status: 'in-progress', requested: 10, fulfilled: 3 }
+    })
+    out.push({
+      eventId: `t-${i}`,
+      eventType: 'task.status',
+      eventTime: '2026-08-24T01:00:01.000Z',
+      tenantId: domainId,
+      data: {
+        taskId: `TK-${i}`,
+        kind: 'putaway',
+        status: 'in-progress',
+        orderId: `WO-${i}`,
+        fromNode: 'dock',
+        toNode: 'bin-1',
+        intent: 'transport',
+        durationMs: 60000,
+        remainingMs: 30000
+      }
+    })
+  }
+  return out
+}
+
+const observed = (s: any): number => (s?.items?.length ?? 0) + (s?.orders?.length ?? 0) + (s?.tasks?.length ?? 0)
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities, ...cacheEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'resume-test', subdomain: 'resume-test' } as any)
+  domainId = d.id
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 접었다', async () => {
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
+  assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
+
+  const applied = TwinEngine.ingestLive(domainId, INSTANCE, facts(5))
+  assert.equal(applied, 10, '원본이 말한 사실이 커널에 들어갔다')
+  const before = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.ok(observed(before) > 0, `상태에 사실이 있어야 이 검사가 뜻이 있다 (실제 ${observed(before)})`)
+
+  await TwinEngine.persistSnapshot(domainId, INSTANCE)
+  const stored = await TwinEngine.loadSnapshot(domainId, INSTANCE)
+  assert.ok(stored, '스냅샷이 저장됐다')
+  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 접는다')
+  assert.ok(stored.fold?.oee, '가동 누적기도 함께 — 상태만 되돌리면 가동률이 부팅 이후로만 잡힌다')
+  /* 씨앗이 실제로 사실을 들었는지 — 빈 껍데기를 적어 두고 초록이 되지 않게. */
+  assert.ok((stored.fold.reducer as any).orders?.length, '씨앗에 오더가 담겨 있다')
+  assert.ok((stored.fold.reducer as any).tasks?.length, '씨앗에 작업이 담겨 있다')
+})
+
+test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 접은 것이 아니다', async () => {
+  /*
+   * 이 단정이 이 축의 전부다. 저널이 없는데 상태가 돌아오면 그 상태는 **저장된 재개점**에서 온 것이다.
+   * 그리고 이 상황은 가정이 아니다 — 보존 정책이 체크포인트 리비전 이하의 행을 실제로 지운다.
+   */
+  const before = observed(TwinEngine.snapshot(domainId, INSTANCE))
+  assert.ok(before > 0, '멈추기 전에 상태가 있어야 이 검사가 뜻이 있다')
+
+  await TwinEngine.stop(domainId, INSTANCE)
+  /* 이 인스턴스의 저널만 — 정확한 소유 표식으로 지운다. */
+  await ds.getRepository(TwinEvent).delete({ domain: { id: domainId } as any, instanceId: INSTANCE } as any)
+  assert.equal(
+    await ds.getRepository(TwinEvent).countBy({ domain: { id: domainId } as any, instanceId: INSTANCE } as any),
+    0,
+    '저널이 비었다 — 이제 접을 것이 없다'
+  )
+
+  await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
+  const after = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.equal(observed(after), before, '★ 사실이 그대로 돌아왔다 — 저널 없이')
+  assert.equal(after.orders.length, 5, '오더 다섯이 그대로다')
+  assert.equal(after.tasks.length, 5, '작업 다섯이 그대로다')
+})
+
+test('되세운 뒤 들어온 사실이 앞의 것을 덮지 않는다 — 더해진다', async () => {
+  /*
+   * 미러는 첫 봉투가 올 때 리듀서를 만든다. 되돌리기가 그보다 먼저 서지 않으면 첫 봉투가 **빈 리듀서**를
+   * 만들고 되세운 것을 덮는다 — 오류 없이 상태가 사라진다.
+   */
+  const before = observed(TwinEngine.snapshot(domainId, INSTANCE))
+  TwinEngine.ingestLive(domainId, INSTANCE, [
+    {
+      eventId: 'o-new',
+      eventType: 'order.status',
+      eventTime: '2026-08-24T02:00:00.000Z',
+      tenantId: domainId,
+      data: { orderId: 'WO-NEW', kind: 'workorder', status: 'in-progress', requested: 1, fulfilled: 0 }
+    } as any
+  ])
+  const after = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.equal(observed(after), before + 1, '앞의 것이 남고 새 것이 더해진다')
+  assert.ok(after.orders.some((o: any) => o.id === 'WO-1'), '되세운 오더가 남아 있다')
+  assert.ok(after.orders.some((o: any) => o.id === 'WO-NEW'), '새 오더도 있다')
+})
+
+test('씨앗이 없으면 지어내지 않는다 — 전과 같이 빈 채로 시작한다', async () => {
+  /*
+   * 처음 뜨는 트윈에는 씨앗이 없다. 여기서 무엇이든 심으면 없던 재고가 생긴다 — 그것은 이 작업이
+   * 고치려던 것보다 나쁘다.
+   */
+  const FRESH = 'resume-probe-fresh'
+  await TwinEngine.ingestMaster(domainId, { ...master(), source: FRESH }, 'reset')
+  try {
+    await TwinEngine.bootDeclared(domainId, FRESH, 'resync')
+    assert.equal(observed(TwinEngine.snapshot(domainId, FRESH)), 0, '아무것도 듣지 못했으므로 비어 있다')
+  } finally {
+    await TwinEngine.stop(domainId, FRESH).catch(() => {})
+  }
+})

package/test/model-gap.test.ts

@@ -0,0 +1,153 @@
+/*
+ * ★ 「원본이 말한 적 없는 것」을 세는 규율.
+ *
+ * ── 왜 이것이 필요한가 (2026-08-20 실측) ────────────────────────────────────
+ * 동기화 건강 기능을 만들 때 제가 전제를 이렇게 적었다: *「커넥터의 매핑이 한 글자 틀리면 트윈은
+ * 빈 공장이 된다」*. 사용자가 그 전제를 검증하게 해서 재 봤더니, 유입 문은 참조 오류를 **거부하지
+ * 않았다**:
+ *
+ *   모르는 로케이션 「오타-99」     → 통과
+ *   모르는 bizStep 「PUTAWAY_X17」 → 통과
+ *   모르는 계량기 「MMXU-오타-99」  → 통과
+ *
+ * 즉 그 기능이 잡겠다고 내세운 대표 사례가 `mapping-blocked` 로는 **뜰 수 없었다.** 거부되는 것은
+ * 형태 오류뿐이다(시각 형식·숫자 아닌 값·epc 없음).
+ *
+ * 거부하지 않는 것이 옳다 — 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고, 거부하면 그 선행
+ * 계측을 잃는다. 커널은 흡수하고 **표시한다**(`origin: 'observed'`). 빠져 있던 것은 그 표시를
+ * 「맞춰지고 있나」를 보는 사람에게 잇는 일이었다.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 마스터가 말한 것과 관측으로 알게 된 것을 섞지 않는다
+ * ② 트윈이 안 돌면 `null` — 「없다」와 「세어 보지 못했다」는 다르다
+ * ③ 조용히 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
+ * ④ 덮지 못하는 축을 밝힌다 — 계량기는 커널이 표시를 달지 않아 이 화면이 못 찾아 준다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { GAP_ID_LIMIT, modelGapOf } from '../server/engine/model-gap.ts'
+
+const loc = (id: string, origin: string) => ({ id, origin })
+
+test('마스터가 말한 로케이션은 갭이 아니다 — 선언된 것을 문제로 세지 않는다', () => {
+  const g = modelGapOf({
+    locations: [loc('dock-recv', 'master'), loc('bin-1', 'master')],
+    equipment: [loc('fk-1', 'master')]
+  })
+
+  assert.equal(g!.total, 0)
+  assert.deepEqual(g!.locations.ids, [])
+})
+
+test('관측으로만 알게 된 것을 축마다 센다 — 원천이 우리가 모르는 id 를 보내고 있다', () => {
+  const g = modelGapOf({
+    locations: [loc('dock-recv', 'master'), loc('오타-99', 'observed'), loc('A-77', 'observed')],
+    equipment: [loc('fk-1', 'master'), loc('없는-지게차', 'observed')],
+    persons: [loc('unknown-op', 'observed')]
+  })
+
+  assert.equal(g!.locations.count, 2)
+  assert.equal(g!.locations.unknown, 0, '표시가 다 있으면 모름은 0')
+  assert.deepEqual(g!.locations.ids, ['오타-99', 'A-77'], 'id 를 보여 준다 — 오타는 눈으로 찾는다')
+  assert.equal(g!.equipment.count, 1)
+  assert.equal(g!.persons.count, 1)
+  assert.equal(g!.total, 4, '세 축의 합')
+})
+
+test('트윈이 안 돌면 「없음」이다 — 0 이 아니다', () => {
+  /* 비교할 상대가 없다. 0 으로 답하면 「원천이 우리가 아는 것만 보낸다」는 없는 사실이 생긴다. */
+  assert.equal(modelGapOf(null), null)
+  assert.equal(modelGapOf(undefined), null)
+})
+
+test('돌지만 관측 갭이 없으면 0 이다 — 이건 「없음」과 다르다', () => {
+  const g = modelGapOf({ locations: [] })
+
+  assert.notEqual(g, null, '세어 봤다')
+  assert.equal(g!.total, 0, '세어 보니 없었다')
+})
+
+test('id 를 조용히 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
+  const many = Array.from({ length: GAP_ID_LIMIT + 7 }, (_, i) => loc(`ghost-${i}`, 'observed'))
+  const g = modelGapOf({ locations: many })
+
+  assert.equal(g!.locations.count, GAP_ID_LIMIT + 7, '전부 센다')
+  assert.equal(g!.locations.ids.length, GAP_ID_LIMIT, '보이는 것은 상한까지')
+  assert.equal(g!.locations.more, 7, '밀려난 수를 말한다')
+})
+
+test('커널이 담을 줄 모른 사건을 함께 낸다 — 참조 문제와 다른 사실이다', () => {
+  const at = Date.parse('2026-08-20T01:02:03.000Z')
+  const g = modelGapOf({
+    unhandled: [
+      { eventType: 'epcis.TransformationEvent', count: 12, lastAtMs: at },
+      { eventType: 'aggregation-mixed-classes', count: 3 }
+    ]
+  })
+
+  assert.equal(g!.unhandled.length, 2)
+  assert.equal(g!.unhandled[0].lastAt, '2026-08-20T01:02:03.000Z', '언제까지 났는지 — 멈춘 종류는 고쳐진 것이다')
+  assert.equal(g!.unhandled[1].lastAt, null, '시각이 없으면 지어내지 않는다')
+})
+
+test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다 — 경로가 `energy` 안이다', () => {
+  /*
+   * 이 값을 **루트에서 읽고 있었다**(2026-08-20에 잡음). 커널은 `EnergyState` 안에 담으므로 루트에서
+   * 읽으면 영원히 `null` 이고, 오류 없이 「에너지 트윈이 아니다」로 읽힌다. 나만 읽는 필드를 잘못된
+   * 경로에서 읽으면 이렇게 조용히 사라진다.
+   *
+   * 그리고 커널은 0 이면 그 칸을 만들지 않는다. 그래서 `energy` 자체가 있는지로 「세었고 0」과
+   * 「에너지 트윈이 아님」을 가른다.
+   */
+  assert.equal(modelGapOf({})!.unknownEquipmentReports, null, '에너지 트윈이 아니면 이 수가 없다')
+  assert.equal(modelGapOf({ energy: { points: [] } })!.unknownEquipmentReports, 0, '에너지 트윈이면 세었고 0 이다')
+  assert.equal(modelGapOf({ energy: { unknownEquipment: 41 } })!.unknownEquipmentReports, 41)
+  assert.equal(
+    modelGapOf({ unknownEquipment: 41 } as any)!.unknownEquipmentReports,
+    null,
+    '루트에 있는 값을 집지 않는다 — 그 경로는 커널의 것이 아니다'
+  )
+})
+
+test('계량기도 덮는다 — 이 축이 가장 무겁다', () => {
+  /*
+   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
+   * 로케이션 오타는 스키매틱이 비는 것으로 드러나지만, 이건 **그럴듯한 숫자**로 나온다.
+   * 커널 0.7.39 가 `MeterPointState.origin` 을 내면서 덮을 수 있게 됐다.
+   */
+  const g = modelGapOf({
+    energy: { points: [loc('main-incoming', 'master'), loc('MMXU-오타-99', 'observed')] }
+  })
+
+  assert.equal(g!.meters.count, 1)
+  assert.deepEqual(g!.meters.ids, ['MMXU-오타-99'])
+  assert.equal(g!.total, 1, '계량기도 합에 든다')
+  assert.deepEqual(g!.notCovered, [], '덮지 못하는 축이 없다')
+})
+
+test('표시가 없는 항목은 「선언됨」이 아니라 「모름」으로 센다', () => {
+  /*
+   * 계량기의 `origin` 은 늦게 생긴 칸이라, 옛 스냅샷에서 이어받은 지점에는 없다(`undefined`).
+   * 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다. 둘 다 틀리다.
+   */
+  const g = modelGapOf({
+    energy: { points: [{ id: 'carried-over' }, loc('main', 'master'), loc('ghost', 'observed')] }
+  })
+
+  assert.equal(g!.meters.unknown, 1, '표시 없는 것은 모름')
+  assert.equal(g!.meters.count, 1, '관측 갭에 섞이지 않는다')
+  assert.ok(!g!.meters.ids.includes('carried-over'), '모르는 것을 오타로 지목하지 않는다')
+})
+
+test('`origin` 은 「지금 모델에 있는가」의 답이다 — 채택되면 갭에서 빠진다', () => {
+  /*
+   * 커널이 표본마다 다시 맞춘다. 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다.
+   * 그래서 채택 뒤 스냅샷에서는 같은 id 가 `master` 로 오고, 이 도출은 그것을 그대로 따른다.
+   */
+  const before = modelGapOf({ energy: { points: [loc('new-meter', 'observed')] } })
+  const after = modelGapOf({ energy: { points: [loc('new-meter', 'master')] } })
+
+  assert.equal(before!.meters.count, 1)
+  assert.equal(after!.meters.count, 0, '모델에 들어오면 갭이 아니다')
+})

package/test/oee-accumulator.test.ts

@@ -18,6 +18,10 @@ const TICK = 1000
 function runSimCollect() {
   const m = {
     source: 'oee', system: 'wms' as const, siteName: 'O',
+  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
+     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
+     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
+    identity: { namespaces: ['https://twin.test/oee-accumulator'] },
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const },

package/test/operational-vocabulary.test.ts

@@ -37,7 +37,7 @@ test('운영 사실이 자기 봉투로 나온다 — EPCIS 로 감싸지지 않
 test('네 어휘가 한 배치에서 갈린다 — 실 피드는 섞여 온다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
     [
-      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
       { meterId: 'm-1', kW: 120 },
       { equipmentId: 'pv-1', generatedKW: 40 },
       { moverId: 'fk-1', kind: 'forklift', status: 'busy' }, // vocabulary-guard: allow 저널 와이어 필드
@@ -80,8 +80,8 @@ test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사
 test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한 배치에 섞여 와도 갈린다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
     [
-      { epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
-      { parentID: 'urn:epc:id:sscc:0614141.0000000001', childEPCs: ['urn:epc:id:sgtin:1.1.1'], action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:packing', readPoint: 'packing' }
+      { epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: 'dock-1' },
+      { parentID: 'urn:epc:id:sscc:0614141.0000000001', childEPCs: ['urn:epc:id:sgtin:9521321.012345.1'], action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:packing', readPoint: 'packing' }
     ] as any,
     'domain-1',
     AT
@@ -93,7 +93,7 @@ test('담김 레코드가 자기 봉투로 나온다 — 개체 관측과 한
 
 test('자리를 구조째 실으면 거부한다 — 예전에는 "[object Object]" 로 굳어 저널에 쌓였다', () => {
   const { accepted, rejected } = ingestCanonicalRecords(
-    [{ epc: 'urn:epc:id:sgtin:1.1.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: { id: 'dock-1' } }] as any,
+    [{ epc: 'urn:epc:id:sgtin:9521321.012345.1', action: 'ADD', bizStep: 'urn:epcglobal:cbv:bizstep:receiving', readPoint: { id: 'dock-1' } }] as any,
     'domain-1',
     AT
   )

package/test/read-failure-visible.test.ts

@@ -0,0 +1,145 @@
+/*
+ * ★ 「원본에 닿지 못한다」와 「원본이 조용하다」는 **다른 사실**이다 — 상태가 그것을 가려야 한다.
+ *
+ * ── 무엇이 조용했나 (2026-08-23 실측) ───────────────────────────────────────
+ * 실 원본이 끊겼다(`jejoup.hatiolab.com:4000` 접속 시간 초과, HTTP 000 / 8초). 그런데 트윈의
+ * **조회 가능한 상태 어디에도 그 사실이 없었다.**
+ *
+ *   recordIngest        `onRecords` 가 불릴 때만 도달한다 — 읽기 실패는 그 문에 오지 않는다
+ *   TwinReference.lastError  마스터 동기·접속 시험에만 적힌다 — 라이브 피드는 적지 않았다
+ *   계약                `openLiveFeed` 에 「읽지 못했다」를 말할 통로가 없었다
+ *
+ * 어댑터는 **로그로는 말하고 있었다**(재시도 경고). 그러나 로그는 사람이 볼 때만 값이 있다 — 화면이
+ * 말하려면 상태에 있어야 한다. 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ * ① 실패가 상태에 남는다  ② 「몇 번」과 「언제부터」를 함께 든다(한 번의 흔들림과 20분째 단절은 다르다)
+ * ③ **빈 읽기는 성공이다** — 조용한 원본을 끊긴 원본으로 만들지 않는다
+ * ④ 조회 뷰로 나간다 — 상태에만 있고 안 나가면 화면이 못 본다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  clearReadFailure,
+  ingestHealth,
+  newIngestLedger,
+  recordIngest,
+  recordReadFailure
+} from '../server/engine/ingest-health.ts'
+
+const T0 = Date.parse('2026-08-23T06:00:00.000Z')
+
+test('실패가 상태에 남는다 — 사유와 흐름까지', () => {
+  const l = newIngestLedger()
+  assert.equal(l.readFailure, undefined, '처음에는 없다(없음이 「닿는다」는 뜻이다)')
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'lot')
+  assert.equal(l.readFailure?.consecutive, 1)
+  assert.equal(l.readFailure?.reason, 'connect ETIMEDOUT')
+  assert.equal(l.readFailure?.stream, 'lot', '어느 표가 막혔나가 원인 찾기의 절반이다')
+})
+
+test('한 번의 흔들림과 20분째 단절을 가른다 — 시작 시각을 지킨다', () => {
+  /*
+   * 매번 새로 적으면 화면이 늘 「방금 실패했다」만 보게 되고, 계속된 단절을 대수롭지 않게 말한다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 600_000)
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 1_200_000)
+  assert.equal(l.readFailure?.consecutive, 3)
+  assert.equal(l.readFailure?.sinceMs, T0, '처음 실패한 시각을 지킨다')
+  assert.equal(l.readFailure?.lastAtMs, T0 + 1_200_000, '마지막 실패는 갱신된다')
+})
+
+test('빈 읽기는 성공이다 — 조용한 원본을 끊긴 원본으로 만들지 않는다', () => {
+  /*
+   * ★ 이 단정이 고치려던 것의 **반대 방향으로 틀리는 것**을 막는다. 원본이 「새 것이 없다」고 답한 것은
+   * 닿았다는 뜻이다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  clearReadFailure(l)
+  assert.equal(l.readFailure, undefined, '읽었으면 단절 기록이 사라진다')
+  /* 그리고 그 뒤 다시 실패하면 **새 단절**이다 — 옛 시작 시각을 물려받지 않는다. */
+  recordReadFailure(l, 'ETIMEDOUT', T0 + 3_600_000)
+  assert.equal(l.readFailure?.consecutive, 1, '연속이 끊겼으므로 1 부터')
+  assert.equal(l.readFailure?.sinceMs, T0 + 3_600_000, '새 단절의 시작이다')
+})
+
+test('조회 뷰로 나간다 — 상태에만 있으면 화면이 못 본다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'inventory')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 60_000)
+  assert.ok(v.readFailure, '뷰에 실려야 한다')
+  assert.equal(v.readFailure?.consecutive, 1)
+  assert.equal(v.readFailure?.since, new Date(T0).toISOString())
+  assert.equal(v.readFailure?.reason, 'connect ETIMEDOUT')
+  assert.equal(v.readFailure?.stream, 'inventory')
+})
+
+test('닿고 있으면 그 필드를 만들지 않는다 — 빈 값이 「닿는다」로 읽히지 않게', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 3, [], T0)
+  const v = ingestHealth(l, 'attached', undefined, T0 + 1000)
+  assert.equal(v.readFailure, undefined)
+  /* 가드가 스스로를 증명한다 — 이 장부가 실제로 무엇을 받았다. */
+  assert.equal(v.total.offered, 3, '빈 비교로 통과하지 않는다')
+})
+
+test('「유입 없음」과 「닿지 못함」은 다른 판정이다', () => {
+  /*
+   * 유입 없음은 원본이 조용한 것일 수 있고, 닿지 못함은 우리가 묻지도 못한 것이다. 두 상태가 같은
+   * 값으로 뭉개지면 화면이 두 문장을 다르게 말할 수 없다.
+   */
+  const quiet = newIngestLedger()
+  const dark = newIngestLedger()
+  recordReadFailure(dark, 'ETIMEDOUT', T0)
+
+  const vq = ingestHealth(quiet, 'attached', undefined, T0)
+  const vd = ingestHealth(dark, 'attached', undefined, T0)
+  assert.equal(vq.lastAt, null, '조용한 쪽도 받은 것이 없다')
+  assert.equal(vd.lastAt, null, '끊긴 쪽도 받은 것이 없다 — 그 값만으로는 갈리지 않는다')
+  assert.notEqual(Boolean(vq.readFailure), Boolean(vd.readFailure), '이 축이 그 둘을 가른다')
+})
+
+/*
+ * ── 읽기 실패가 **피드를 끄면 안 된다** (2026-08-23, 되돌린 자리) ────────────
+ *
+ * 처음 구현에서 읽기 실패가 레퍼런스 행의 `status` 를 `'error'` 로 적었다. 그것이 **피드를 영구히
+ * 껐다**: 부팅 재부착은 `status: 'connected'` 인 레퍼런스만 되살리므로, 원본이 **잠깐** 끊긴 것이
+ * 다음 재기동에서 그 트윈을 아예 굶겼다. 실측으로 그렇게 났다 — 그 판의 로그에 `[twin-live]` 줄이
+ * 한 줄도 없었다.
+ *
+ * 두 축을 한 칸에 섞은 것이 원인이다.
+ *
+ *   status      **연결 설정이 성립하나** — 접속 시험·마스터 동기가 정한다. 재부착의 **자격**이다
+ *   읽기 실패    **지금 닿나** — 오갈 수 있는 사실이고 유입 장부가 그 축을 갖는다
+ *
+ * 「사실을 말하게」 하려던 것이 「사실을 못 듣게」 만들었다. 그 방향의 실패는 조용하다 — 화면은
+ * 「원본에 닿지 못한다」를 정직하게 말하면서, 정작 다시 닿을 기회를 잃는다.
+ */
+test('읽기 실패가 레퍼런스의 status 를 건드리지 않는다 — 그것이 재부착의 자격이다', () => {
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+
+  const at = code.indexOf('onReadFailure:')
+  assert.ok(at > 0, 'onReadFailure 배선이 있어야 한다')
+  const body = code.slice(at, at + 600)
+
+  assert.doesNotMatch(body, /status:/, '읽기 실패는 status 를 적지 않는다 — 적으면 다음 부팅이 그 피드를 되살리지 않는다')
+  /* 대신 이유는 남긴다 — 사람이 목록에서 볼 수 있게. */
+  assert.match(body, /lastError/, '이유는 레퍼런스 행에 남긴다')
+  /* 그리고 「지금 닿나」는 장부가 답한다. */
+  assert.match(body, /recordIngestReadFailure/, '유입 장부가 그 축을 든다')
+})
+
+test('재부착의 자격은 connected 뿐이다 — 그래서 그 값을 함부로 바꾸면 안 된다', () => {
+  /*
+   * 이 단정이 위 가드의 **이유**를 못박는다. 재부착 조건이 넓어지면 위 규율의 근거가 약해지므로,
+   * 둘이 함께 움직여야 한다.
+   */
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  assert.match(src, /find\(\{ where: \{ status: 'connected' \}/, '부팅 재부착은 connected 만 되살린다')
+})