@things-factory/headless-twin 10.0.12 → 10.0.14

package/test/ingest-health-engine.test.ts

@@ -0,0 +1,248 @@
+/*
+ * ★ 동기화 판정이 **실제 트윈 위에서** 옳게 나온다 — 엔진 이음새.
+ *
+ * 순수 모듈 시험(`ingest-health.test.ts`)은 「이런 장부가 주어지면 이런 판정」을 지킨다. 그런데 화면이
+ * 실제로 받는 판정은 그 앞에 한 층이 더 있다: **피드 사실을 어디서 얻는가**(`liveFeedStateOf` — 이 트윈이
+ * 미러인가 시뮬인가, 지금 도는가) 그리고 **장부를 어느 트윈의 것으로 찾는가**(도메인+인스턴스 키).
+ *
+ * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 조용히 틀릴 수 있다:
+ *  ① 시뮬 트윈이 「연결 안 됨」으로 보인다 — 거짓 경보이고, 거짓 경보는 참 경보를 죽인다
+ *  ② 남의 도메인 장부를 집는다 — 키를 도메인 없이 만들면 그렇게 된다
+ *
+ * 그래서 실 DataSource 로 트윈을 세우고, 미러 하나·시뮬 하나로 판정 여섯을 이 자리에서 확인한다.
+ * 목 HTTP 게이트웨이는 쓰지 않는다(그것은 데모 환경변수에 딸린 것이고, 여기서 볼 것은 장부와 판정이다).
+ */
+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 { INGEST_WINDOW_MS, STALE_AFTER_MS } = req('../dist-server/engine/ingest-health.js')
+const { registerLiveFeedProbe } = req('../dist-server/engine/live-feed-registry.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+/*
+ * 피드 사실을 이 시험이 쥔다.
+ *
+ * 실제 커넥터 피드는 원천에 붙어야 서고, 붙지 못하면 비동기로 떨어진다 — 그 타이밍에 판정이 흔들리면
+ * 이 시험은 **판정을 재는 게 아니라 커넥터를 재는 것**이 된다(실제로 그렇게 깨졌다: 세 번째 검사까지는
+ * 붙어 있다가 네 번째에서 떨어져 「연결 안 됨」이 나왔다). 그래서 `registerLiveFeedProbe` — 계층이 자기
+ * 장부를 등록하도록 만들어 둔 그 확장점 — 으로 시험의 장부를 하나 더 얹는다. 커넥터 거동은 커넥터
+ * 시험이 지킨다.
+ */
+let feedUp = new Set<string>()
+
+let ds: DataSource
+let domainId: string
+let otherDomainId: string
+
+/*
+ * 시나리오마다 트윈을 따로 둔다.
+ *
+ * 장부는 트윈마다 하나이고 **창은 이어진다.** 트윈 하나로 여러 시나리오를 돌리면 앞 검사가 남긴 창에
+ * 뒤 검사의 건수가 섞여 「최근 창」이 엉뚱한 것을 가리킨다(실제로 그렇게 깨졌다: 200건을 기대한 자리에
+ * 50건이 나왔다). 트윈을 나누면 각 검사가 자기 창만 본다.
+ */
+const MIRROR = 'sync-mirror' /* 붙었는데 아직 안 받음 → 창이 닫히면 동기화 중 */
+const BLOCKED = 'sync-blocked' /* 거부가 문턱을 넘음 */
+const STALE = 'sync-stale' /* 오래 끊김 */
+const SIM = 'sync-sim'
+const MIRRORS = [MIRROR, BLOCKED, STALE]
+
+/**
+ * 이 검사가 쓰는 창의 시작점.
+ *
+ * 창 하나를 닫고도 **읽는 시점이 다음 창 안에** 있어야 한다. `1.4창` 전에서 시작해 `창+1` 에서 닫으면
+ * 읽을 때까지 `0.4창`밖에 지나지 않아 두 번째 창이 닫히지 않는다 — 정확히 `2창` 전으로 잡았을 때
+ * 밀리초 몇 개 때문에 한 창이 더 닫혀 깨졌다.
+ */
+const windowStart = () => Date.now() - Math.floor(INGEST_WINDOW_MS * 1.4)
+
+const master = (source: string): any => ({
+  source,
+  system: 'wms',
+  siteName: '동기화 검사 창고',
+  space: { width: 40, depth: 20, unit: 'm' },
+  locations: [
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    { id: 'bin-1', type: 'storage', role: 'location', name: '빈1', capacity: 20 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }]
+})
+
+/** 거부 하나 — 사유는 커널이 주는 모양을 그대로 흉내낸다(레코드 원문 포함). */
+const reject = (why: string) => ({ errors: [why], record: { epc: 'urn:epc:id:sgtin:0614141.107346.2018', bizStep: '?' } })
+
+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)
+  registerLiveFeedProbe(() => [...feedUp])
+
+  const d = await ds.getRepository(Domain).save({ name: 'sync-test', subdomain: 'sync-test' } as any)
+  domainId = d.id
+  const o = await ds.getRepository(Domain).save({ name: 'sync-other', subdomain: 'sync-other' } as any)
+  otherDomainId = o.id
+
+  for (const id of [...MIRRORS, SIM]) await TwinEngine.ingestMaster(domainId, master(id), 'reset')
+})
+
+after(async () => {
+  for (const id of [...MIRRORS, SIM]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+/** 미러로 세우고 피드를 붙인 상태로 만든다 — 각 검사가 자기 트윈을 자기 손으로 세운다. */
+async function bootMirror(instanceId: string): Promise<void> {
+  const rt = await TwinEngine.bootDeclared(domainId, instanceId, 'resync')
+  assert.equal(rt.mode, 'live', `${instanceId} 는 미러로 떠야 이 검사가 뜻이 있다`)
+  feedUp.add(instanceId)
+}
+
+test('시뮬 트윈은 「해당 없음」이다 — 물을 대상이 아닌 것에 경고색을 주지 않는다', async () => {
+  const rt = await TwinEngine.bootDeclared(domainId, SIM, 'reset')
+  assert.equal(rt.mode, 'sim', '시뮬로 떠야 이 검사가 뜻이 있다')
+
+  assert.equal(TwinEngine.ingestHealthOf(domainId, SIM).verdict, 'not-applicable')
+})
+
+test('미러가 붙었지만 아직 아무것도 안 받았으면 「모름」이다 — 정상도 비정상도 아니다', async () => {
+  await bootMirror(MIRROR)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'unknown')
+  assert.equal(v.lastAt, null, '받은 적이 없다 — 0 이 아니다')
+  assert.equal(v.total.acceptedRatio, null, '비율이 없다 — 1 이 아니다')
+})
+
+test('창이 닫히면 「동기화 중」이 되고, 통과와 거부를 함께 낸다', () => {
+  const t0 = windowStart()
+
+  TwinEngine.recordIngestResult(domainId, MIRROR, 200, [reject('unknown bizStep "?"')], t0)
+  /* 창을 닫는다 — 창은 **다음 유입이 있을 때** 닫힌다. */
+  TwinEngine.recordIngestResult(domainId, MIRROR, 50, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'syncing')
+  assert.equal(v.recent.offered, 200)
+  assert.equal(v.recent.rejected, 1)
+  assert.equal(v.recent.accepted, 199)
+  assert.equal(v.recent.acceptedRatio, 0.995)
+  assert.equal(v.total.offered, 250, '누적은 두 창을 합한다')
+})
+
+test('거부가 문턱을 넘으면 「매핑이 막고 있음」이고, 사유와 레코드 원문이 함께 나온다', async () => {
+  await bootMirror(BLOCKED)
+  const t0 = windowStart()
+
+  TwinEngine.recordIngestResult(
+    domainId,
+    BLOCKED,
+    100,
+    Array.from({ length: 40 }, () => reject('unknown location "A-99"')),
+    t0
+  )
+  TwinEngine.recordIngestResult(domainId, BLOCKED, 1, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const v = TwinEngine.ingestHealthOf(domainId, BLOCKED)
+  assert.equal(v.verdict, 'mapping-blocked')
+  assert.equal(v.recent.acceptedRatio, 0.6, '100건 중 40건이 거부됐다')
+
+  const reason = v.reasons.find((r: any) => r.reason === 'unknown location "A-99"')
+  assert.ok(reason, '사유를 묶어서 낸다')
+  assert.equal(reason.count, 40)
+
+  /* 표본은 커널이 낸 사유를 그대로 들고 있다(`errors`) — 우리가 다시 쓰지 않는다. */
+  const sample = v.samples.find((s: any) => s.errors.includes('unknown location "A-99"'))
+  assert.ok(sample, '사유만으로는 원천이 무엇을 보냈는지 알 수 없다 — 원문이 있어야 고친다')
+  assert.match(sample.record, /urn:epc:id:sgtin/, '레코드 원문이 그대로 들어 있다')
+})
+
+test('오래 끊긴 미러는 「유입 없음」이다 — 건강했던 옛 창으로 초록을 내지 않는다', async () => {
+  /*
+   * 이것이 이 기능이 있는 이유다. 창은 다음 유입이 있을 때 닫히므로, 유입이 멈추면 「최근 창」은 멈추기
+   * 직전의 건강했던 창으로 남는다. 그 창만 보면 어제 죽은 피드가 오늘도 「동기화 중」이다.
+   */
+  await bootMirror(STALE)
+  const long = Date.now() - STALE_AFTER_MS * 5
+
+  TwinEngine.recordIngestResult(domainId, STALE, 1000, [], long)
+  TwinEngine.recordIngestResult(domainId, STALE, 1000, [], long + INGEST_WINDOW_MS + 1) // 건강한 창을 닫는다
+
+  const v = TwinEngine.ingestHealthOf(domainId, STALE)
+  assert.equal(v.verdict, 'no-traffic', '마지막 유입이 한 창보다 오래 전이다')
+  assert.equal(v.recent.acceptedRatio, 1, '(옛 창 자체는 건강했다 — 그래서 창만 보면 속는다)')
+})
+
+test('피드가 떨어진 미러는 「연결 안 됨」이다 — 「유입 없음」과 처방이 다르다', () => {
+  /* 「유입 없음」은 원천·망을 보라는 말이고, 「연결 안 됨」은 결선하라는 말이다. 섞으면 엉뚱한 곳을 본다. */
+  feedUp.delete(MIRROR)
+
+  assert.equal(TwinEngine.ingestHealthOf(domainId, MIRROR).verdict, 'not-connected')
+
+  feedUp.add(MIRROR)
+})
+
+test('멈춘 미러는 「해당 없음」이다 — 고치려고 멈춰 둔 트윈에 「연결 안 됨」이라 하지 않는다', async () => {
+  await TwinEngine.stop(domainId, MIRROR)
+
+  const v = TwinEngine.ingestHealthOf(domainId, MIRROR)
+  assert.equal(v.verdict, 'not-applicable')
+  assert.ok(v.total.offered > 0, '멈춰도 장부는 남는다 — 마지막에 무엇이 거부됐는지 볼 수 있어야 한다')
+})
+
+test('멈춘 트윈에 계속 들어오면 「버려지는 중」이라 말한다 — 실제로 겪은 거짓 안심', async () => {
+  /*
+   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 조용히 버렸다. 화면은 「해당 없음 ·
+   * 150 통과 · 100%」였다. 여기서는 그 상황을 그대로 만들어 판정과 수치를 확인한다.
+   */
+  /* 사람이 트윈을 멈춘다 — 그런데 피드는 남는다. 그 조합이 사실을 잃게 만든다. */
+  await TwinEngine.stop(domainId, STALE)
+  assert.equal(TwinEngine.instances[`${domainId}:${STALE}`], undefined, '멈췄다')
+
+  /* 커널이 받지 않는다 — `ingestLive` 가 0 을 돌려준다. */
+  const applied = TwinEngine.ingestLive(domainId, STALE, [{ any: 'envelope' } as any])
+  assert.equal(applied, 0, '멈춘 트윈은 봉투를 받지 않는다')
+
+  TwinEngine.recordIngestResult(domainId, STALE, 10, [], Date.now(), 10)
+
+  const v = TwinEngine.ingestHealthOf(domainId, STALE)
+  assert.equal(v.verdict, 'twin-not-running', '「해당 없음」으로 덮지 않는다')
+  assert.equal(v.total.undelivered >= 10, true, '버려진 수를 센다')
+})
+
+test('장부는 도메인으로 갈린다 — 같은 instanceId 라도 남의 것을 집지 않는다', () => {
+  const v = TwinEngine.ingestHealthOf(otherDomainId, MIRROR)
+
+  assert.equal(v.total.offered, 0, '다른 도메인에는 이 트윈의 장부가 없다')
+  assert.equal(v.total.acceptedRatio, null)
+  assert.equal(v.samples.length, 0, '남의 레코드 원문이 새지 않는다')
+})
+
+test('목록 요약은 숫자만 낸다 — 원문을 스무 벌 실어 조회를 무겁게 하지 않는다', () => {
+  const brief = TwinEngine.ingestHealthBrief(domainId, [MIRROR, SIM])
+
+  assert.equal(brief.length, 2)
+  const m = brief.find((b: any) => b.instanceId === MIRROR)
+  assert.ok(m, '멈춘 트윈도 목록에 남는다')
+  assert.equal((m as any).samples, undefined, '표본은 목록에 없다')
+  assert.equal((m as any).reasons, undefined, '사유도 목록에 없다')
+  assert.ok(Array.isArray((m as any).trend), '스파크라인용 추이는 있다')
+
+  const s = brief.find((b: any) => b.instanceId === SIM)
+  assert.equal((s as any).verdict, 'not-applicable')
+  assert.equal((s as any).acceptedRatio, null, '시뮬은 비율이 없다 — 0 이 아니다')
+})

package/test/ingest-health-wiring.test.ts

@@ -0,0 +1,119 @@
+/*
+ * 유입 경로가 **모두 같은 장부**에 적는다 — 소스 규율 검사.
+ *
+ * ── 왜 기계가 지켜야 하나 ───────────────────────────────────────────────────
+ * 피드를 여는 경로가 둘이다(커넥터 `openLiveFeed` · 시나리오 `twin-ingest` 태스크). 한쪽만 장부에
+ * 적으면 그 경로로 먹이는 트윈이 **「한 번도 받지 않은 것」**으로 보인다. 그 판정은 `unknown` 이고,
+ * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **조용히 틀린 답**이 된다.
+ *
+ * 세 번째 경로가 생길 때 사람이 이 사실을 기억할 것이라고 믿지 않는다. 인제스트를 부르는 자리를
+ * 소스에서 찾아 장부 기록이 함께 있는지 본다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 훑는 곳 — 이 저장소에서 인제스트를 부를 수 있는 층 둘. */
+const ROOTS = [
+  new URL('../server', import.meta.url).pathname,
+  new URL('../../operato-twin/server', import.meta.url).pathname
+]
+
+/** 인제스트를 여는 함수 이름. 이 이름이 나오는 자리가 곧 유입 경로다. */
+const INGEST_CALL = 'ingestCanonicalRecords('
+
+/** 장부에 적는 창구. */
+const LEDGER_CALL = 'recordIngestResult('
+
+/**
+ * 예외 — 인제스트를 **부르지 않고 다시 내보내기만** 하는 자리.
+ *
+ * 늘리려면 이유를 함께 적는다. 「부르는데 안 적는다」는 예외가 될 수 없다 — 그게 이 검사가 막는 것이다.
+ */
+const REEXPORT_ONLY = ['board/tasks/twin-ingest-core.ts', 'engine/index.ts', 'engine/canonical-ingest.ts']
+
+function sources(dir: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return []
+  }
+  return entries.flatMap(f => {
+    const p = join(dir, f)
+    return statSync(p).isDirectory() ? sources(p) : p.endsWith('.ts') && !p.endsWith('.d.ts') ? [p] : []
+  })
+}
+
+function ingestCallSites(): { file: string; src: string }[] {
+  const out: { file: string; src: string }[] = []
+  for (const root of ROOTS) {
+    for (const f of sources(root)) {
+      const src = readFileSync(f, 'utf-8')
+      if (!src.includes(INGEST_CALL)) continue
+      const rel = f.slice(root.length + 1)
+      if (REEXPORT_ONLY.some(x => rel.endsWith(x))) continue
+      out.push({ file: rel, src })
+    }
+  }
+  return out
+}
+
+test('인제스트를 부르는 곳은 모두 장부에 적는다 — 한 경로만 빠지면 그 트윈은 「모름」으로 보인다', () => {
+  const missing = ingestCallSites()
+    .filter(s => !s.src.includes(LEDGER_CALL))
+    .map(s => s.file)
+
+  assert.deepEqual(
+    missing,
+    [],
+    `장부에 적지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
+      `그 경로로 먹이는 트윈은 twinIngestHealth 에서 「한 번도 받지 않음」(unknown)으로 보이고, ` +
+      `화면에서 정상과 구별되지 않는다. TwinEngine.recordIngestResult(도메인, 인스턴스, 제시수, 거부) 를 부른다.`
+  )
+})
+
+test('검사가 실제로 경로를 보고 있다 — 대상이 사라지면 초록이 거짓이 된다', () => {
+  const sites = ingestCallSites().map(s => s.file)
+
+  assert.ok(
+    sites.length >= 2,
+    `유입 경로를 ${sites.length}곳 찾았다 — 둘(커넥터·시나리오)보다 적으면 호출 형태가 바뀐 것이다. ` +
+      `이 검사의 패턴을 함께 옮긴다. 찾은 것: ${sites.join(', ') || '없음'}`
+  )
+})
+
+test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진 것을 통과로 세지 않게', () => {
+  /*
+   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 조용히 버렸는데, 장부는 그것을 「통과」로
+   * 셌다. 화면은 멈춘 트윈 옆에 「150 통과 · 100%」라고 적었다 — 사실이 사라지는 동안 안심시킨 것이다.
+   *
+   * 고친 방법은 `ingestLive` 가 **넣은 수를 돌려주는** 것이다. 새 경로가 그 반환을 안 쓰고 0 을 넘기면
+   * 같은 침묵이 돌아온다. 그래서 경로마다 미전달을 세는지 소스에서 본다.
+   */
+  const missing = ingestCallSites()
+    .filter(s => !s.src.includes('undelivered'))
+    .map(s => s.file)
+
+  assert.deepEqual(
+    missing,
+    [],
+    `커널이 받은 수를 견주지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
+      `TwinEngine.ingestLive(...) 의 반환(넣은 수)을 받아 accepted.length 와의 차이를 ` +
+      `recordIngestResult(..., nowMs, undelivered) 로 넘긴다. 그러지 않으면 트윈이 멈춘 사이 ` +
+      `버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.`
+  )
+})
+
+test('제시 수를 거부 수로 대신하지 않는다 — 통과율의 분모가 뒤바뀌지 않게', () => {
+  /*
+   * 실수하기 쉬운 자리다: `recordIngestResult(..., rejected.length, rejected)` 처럼 적으면 분모가
+   * 거부 수가 되어 **통과율이 언제나 0** 이 된다. 오류 없이 「전부 거부」로 읽힌다.
+   */
+  const bad = ingestCallSites()
+    .filter(s => /recordIngestResult\([^)]*rejected\.length\s*,/.test(s.src))
+    .map(s => s.file)
+
+  assert.deepEqual(bad, [], `제시 수 자리에 거부 수를 넘긴 곳:\n  ${bad.join('\n  ')}`)
+})

package/test/ingest-health.test.ts

@@ -0,0 +1,306 @@
+/*
+ * 동기화 건강 — **「이 트윈이 현장과 맞춰지고 있나」에 정직하게 답한다.**
+ *
+ * 지키는 것: ① 판정 일곱이 서로 섞이지 않고, **끊긴 피드가 옛 창으로 초록을 내지 않으며, 버려지고 있는
+ * 것을 「해당 없음」으로 덮지 않는다** ② 닫힌 창만 「최근」이다 ③ 0 과 「없음」이 다르다 ④ 상한에서
+ * 밀려난 것을 함께 낸다 ⑤ 사유 종류가 무한히 자라지 않는다 ⑥ 같은 사유를 두 번 직렬화하지 않는다
+ * ⑦ 영속 훅이 장부의 진행을 막지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  HEALTHY_ACCEPTED_RATIO,
+  INGEST_WINDOW_MS,
+  OTHER_REASON,
+  REASON_LIMIT,
+  STALE_AFTER_MS,
+  TREND_LIMIT,
+  ingestHealth,
+  newIngestLedger,
+  recordIngest,
+  rollIngestWindow,
+  syncVerdictOf
+} from '../server/engine/ingest-health.ts'
+
+/* ── ① 판정 ─────────────────────────────────────────────────────────────── */
+
+test('시뮬 트윈에는 「동기화 안 됨」이라 말하지 않는다 — 거짓 경보는 참 경보를 죽인다', () => {
+  assert.equal(syncVerdictOf({ feedState: 'not-applicable', recent: null }), 'not-applicable')
+  assert.equal(syncVerdictOf({ feedState: 'not-applicable', recent: { offered: 0, rejected: 0 } }), 'not-applicable')
+})
+
+test('피드가 없는 것과 붙었는데 안 오는 것을 가른다', () => {
+  assert.equal(syncVerdictOf({ feedState: 'detached', recent: null }), 'not-connected')
+  assert.equal(syncVerdictOf({ feedState: 'attached', recent: { offered: 0, rejected: 0 } }), 'no-traffic')
+})
+
+test('재지 않은 것을 정상·비정상으로 채우지 않는다', () => {
+  assert.equal(syncVerdictOf({ feedState: 'attached', recent: null }), 'unknown')
+})
+
+test('오래 끊긴 피드는 건강했던 옛 창으로 초록을 내지 않는다 — 이 기능이 있는 이유', () => {
+  /*
+   * 창은 다음 유입이 있을 때 닫힌다. 유입이 멈추면 「최근 창」은 멈추기 직전의 건강했던 창으로 남는다.
+   * 그 창만 보면 어제 죽은 피드가 오늘도 「동기화 중」이다.
+   */
+  const healthy = { offered: 1000, rejected: 0 }
+
+  assert.equal(
+    syncVerdictOf({ feedState: 'attached', recent: healthy, lastAtMs: 0, nowMs: STALE_AFTER_MS + 1 }),
+    'no-traffic'
+  )
+  assert.equal(
+    syncVerdictOf({ feedState: 'attached', recent: healthy, lastAtMs: 0, nowMs: STALE_AFTER_MS }),
+    'syncing',
+    '경계까지는 아직 조용하다고 하지 않는다'
+  )
+})
+
+test('침묵이 거부보다 앞선다 — 끊긴 피드에 「매핑이 막고 있음」이라 말하지 않는다', () => {
+  /* 매핑을 고치라는 말은 유입이 있을 때만 맞는 처방이다. 오지 않는 것은 매핑 문제가 아니다. */
+  assert.equal(
+    syncVerdictOf({ feedState: 'attached', recent: { offered: 100, rejected: 90 }, lastAtMs: 0, nowMs: STALE_AFTER_MS + 1 }),
+    'no-traffic'
+  )
+})
+
+test('붙었지만 한 번도 받지 않은 것을 「유입 없음」이라 단정하지 않는다', () => {
+  /* `-1` 은 「없음」이다. 0(1970년)으로 읽으면 방금 띄운 트윈이 곧바로 「끊겼다」가 된다. */
+  assert.equal(
+    syncVerdictOf({ feedState: 'attached', recent: null, lastAtMs: -1, nowMs: STALE_AFTER_MS * 100 }),
+    'unknown'
+  )
+})
+
+test('시뮬 트윈은 오래 조용해도 「유입 없음」이 아니다', () => {
+  assert.equal(
+    syncVerdictOf({ feedState: 'not-applicable', recent: null, lastAtMs: -1, nowMs: STALE_AFTER_MS * 100 }),
+    'not-applicable'
+  )
+})
+
+test('들어오는데 트윈이 안 돌면 「버려지는 중」이다 — 「해당 없음」으로 안심시키지 않는다', () => {
+  /*
+   * 실제로 겪었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 커널은 그것을 조용히 버렸다.
+   * 그런데 화면은 「해당 없음 · 150 통과 · 100%」였다 — 사실이 사라지는 동안 화면이 안심시킨 것이다.
+   *
+   * 멈춘 트윈의 피드 사실은 `not-applicable` 이므로, 미전달을 **그보다 먼저** 봐야 이 상태가 드러난다.
+   */
+  assert.equal(
+    syncVerdictOf({ feedState: 'not-applicable', recent: null, lastUndeliveredAtMs: 0, nowMs: 1000 }),
+    'twin-not-running'
+  )
+  assert.equal(
+    syncVerdictOf({ feedState: 'attached', recent: { offered: 100, rejected: 0 }, lastUndeliveredAtMs: 0, nowMs: 1000 }),
+    'twin-not-running',
+    '통과율이 좋아 보여도 버려지고 있으면 그것을 말한다'
+  )
+})
+
+test('버려진 지 오래됐으면 더는 「버려지는 중」이라 하지 않는다 — 지난 일을 현재로 말하지 않는다', () => {
+  assert.equal(
+    syncVerdictOf({ feedState: 'not-applicable', recent: null, lastUndeliveredAtMs: 0, nowMs: STALE_AFTER_MS + 1 }),
+    'not-applicable'
+  )
+})
+
+test('버려진 적이 없으면 미전달 판정이 서지 않는다 — `-1` 을 시각 0 으로 읽지 않는다', () => {
+  assert.equal(
+    syncVerdictOf({ feedState: 'not-applicable', recent: null, lastUndeliveredAtMs: -1, nowMs: 1000 }),
+    'not-applicable'
+  )
+})
+
+test('버려진 것을 「통과」로 세지 않는다 — 통과율이 그만큼 내려간다', () => {
+  const l = newIngestLedger()
+  /* 100건 제시 · 매핑 거부 0 · 그런데 40건이 트윈에 닿지 못했다 */
+  recordIngest(l, 100, [], 0, undefined, 40)
+  recordIngest(l, 1, [], INGEST_WINDOW_MS + 1) // 창을 닫는다
+
+  const v = ingestHealth(l, 'attached', undefined, INGEST_WINDOW_MS + 1)
+  assert.equal(v.recent!.offered, 100)
+  assert.equal(v.recent!.rejected, 0, '매핑은 아무것도 거부하지 않았다')
+  assert.equal(v.recent!.undelivered, 40)
+  assert.equal(v.recent!.accepted, 60, '트윈에 닿은 것만 통과다')
+  assert.equal(v.recent!.acceptedRatio, 0.6, '100% 가 아니다')
+  assert.equal(v.total.undelivered, 40)
+})
+
+test('거부가 문턱을 넘으면 매핑을 지목한다 — 문턱 경계를 정확히 지킨다', () => {
+  /* 문턱은 「이상이면 정상」이다. 통과율이 정확히 문턱이면 정상으로 본다. */
+  assert.equal(syncVerdictOf({ feedState: 'attached', recent: { offered: 100, rejected: 5 } }), 'syncing')
+  assert.equal(syncVerdictOf({ feedState: 'attached', recent: { offered: 100, rejected: 6 } }), 'mapping-blocked')
+  assert.equal(HEALTHY_ACCEPTED_RATIO, 0.95)
+})
+
+/* ── ② 창 ───────────────────────────────────────────────────────────────── */
+
+test('채우는 중인 창을 「최근」이라 부르지 않는다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 100, [], 0)
+  recordIngest(l, 100, [], 1000)
+
+  /* 읽는 시각을 넘긴다 — 넘기지 않으면 벽시계와 견주어 「오래 조용함」으로 읽힌다(1970년 장부이므로). */
+  const v = ingestHealth(l, 'attached', undefined, 1000)
+  assert.equal(v.recent, null, '창이 아직 닫히지 않았다')
+  assert.equal(v.verdict, 'unknown', '그래서 판정도 모름이다')
+  assert.equal(v.total.offered, 200, '누적은 이미 센다')
+})
+
+test('창이 닫히면 최근이 되고, 통과와 거부를 함께 낸다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 200, [{ errors: ['epc is required'] }, { errors: ['epc is required'] }], 0)
+  recordIngest(l, 5, [], INGEST_WINDOW_MS + 1) // 창을 닫는다
+
+  const v = ingestHealth(l, 'attached', undefined, INGEST_WINDOW_MS + 1)
+  assert.equal(v.recent!.offered, 200)
+  assert.equal(v.recent!.rejected, 2)
+  assert.equal(v.recent!.accepted, 198)
+  assert.equal(v.recent!.acceptedRatio, 0.99)
+  assert.equal(v.verdict, 'syncing')
+})
+
+test('추이 상한을 넘으면 오래된 창이 밀려나고, 밀려난 수를 낸다', () => {
+  const l = newIngestLedger()
+  for (let i = 0; i <= TREND_LIMIT + 3; i++) recordIngest(l, 1, [], i * (INGEST_WINDOW_MS + 1))
+
+  const v = ingestHealth(l, 'attached')
+  assert.equal(v.trend.length, TREND_LIMIT)
+  assert.ok(v.trendDropped > 0, `밀려난 창을 조용히 버리지 않는다 — 실제 ${v.trendDropped}`)
+})
+
+/* ── ③ 0 과 없음 ────────────────────────────────────────────────────────── */
+
+test('한 번도 받지 않은 트윈은 수치를 0 으로 채우지 않는다', () => {
+  const v = ingestHealth(newIngestLedger(), 'attached')
+
+  assert.equal(v.lastAt, null, '받은 적이 없다')
+  assert.equal(v.total.acceptedRatio, null, '비율이 없다 — 1 이 아니다')
+  assert.equal(v.recent, null)
+  assert.equal(v.verdict, 'unknown')
+})
+
+test('장부가 없어도 피드 사실만으로 답할 수 있는 판정은 낸다', () => {
+  const v = ingestHealth(undefined, 'not-applicable')
+
+  assert.equal(v.verdict, 'not-applicable')
+  assert.equal(v.total.acceptedRatio, null, '없는 값을 지어내지 않는다')
+})
+
+test('제시는 있고 거부가 0 이면 비율은 1 이다 — 이건 「없음」이 아니다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 50, [], 0)
+
+  assert.equal(ingestHealth(l, 'attached').total.acceptedRatio, 1)
+})
+
+test('1,000건 중 1건 거부가 「전부 통과」로 읽히지 않는다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 1000, [{ errors: ['bad'] }], 0)
+
+  assert.equal(ingestHealth(l, 'attached').total.acceptedRatio, 0.999)
+})
+
+/* ── ④⑤⑥ 상한과 비용 ───────────────────────────────────────────────────── */
+
+test('사유 종류가 무한히 자라지 않는다 — 문구에 변수가 섞여도', () => {
+  const l = newIngestLedger()
+  for (let i = 0; i < REASON_LIMIT * 5; i++) recordIngest(l, 1, [{ errors: [`unknown bizStep "S${i}"`] }], 1)
+
+  const v = ingestHealth(l, 'attached')
+  assert.ok(v.reasons.length <= REASON_LIMIT + 1, `사유 칸이 ${v.reasons.length}개 — 상한 + 기타 한 칸`)
+  assert.equal(v.reasonsCapped, true, '접혔다는 사실을 말한다')
+  assert.ok(
+    v.reasons.some(r => r.reason === OTHER_REASON),
+    '접힌 것들이 갈 칸이 있다'
+  )
+  assert.equal(v.total.rejected, REASON_LIMIT * 5, '건수는 하나도 잃지 않는다')
+})
+
+test('같은 사유는 한 번만 표본을 뜬다 — 나머지는 직렬화하지 않는다', () => {
+  const l = newIngestLedger()
+  let serialized = 0
+  const record = () => {
+    serialized++
+    return { epc: 'x' }
+  }
+  for (let i = 0; i < 500; i++) recordIngest(l, 1, [{ errors: ['epc is required'], record: record() }], 1)
+
+  const v = ingestHealth(l, 'attached')
+  assert.equal(v.samples.length, 1, '사유 하나 → 표본 하나')
+  assert.equal(v.sampleDropped, 499, '나머지는 세어서 밝힌다')
+  assert.equal(v.total.rejected, 500, '건수는 그대로')
+  assert.equal(serialized, 500, '(레코드를 만든 횟수 — 장부가 직렬화한 횟수는 아래에서 본다)')
+})
+
+test('사유가 여럿이면 사유마다 표본이 하나씩 생긴다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 3, [{ errors: ['a'] }, { errors: ['b'] }, { errors: ['a'] }], 1)
+
+  const v = ingestHealth(l, 'attached')
+  assert.equal(v.samples.length, 2, 'a·b 하나씩')
+  assert.equal(v.sampleDropped, 1, '두 번째 a 는 안 뜬다')
+})
+
+test('긴 레코드는 자르고, 잘랐다고 표시한다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 1, [{ errors: ['big'], record: { blob: 'x'.repeat(5000) } }], 1)
+
+  const s = ingestHealth(l, 'attached').samples[0]
+  assert.equal(s.recordTruncated, true)
+  assert.ok(s.record.length <= 2000)
+})
+
+test('직렬화할 수 없는 레코드가 장부를 멈추지 않는다', () => {
+  const l = newIngestLedger()
+  const cyclic: any = {}
+  cyclic.self = cyclic
+  recordIngest(l, 1, [{ errors: ['cyclic'], record: cyclic }], 1)
+
+  assert.equal(ingestHealth(l, 'attached').total.rejected, 1, '건수는 센다')
+})
+
+/* ── ⑦ 영속 훅 ──────────────────────────────────────────────────────────── */
+
+test('창이 닫힐 때만 영속 훅이 불린다 — 건마다가 아니다', () => {
+  const l = newIngestLedger()
+  const closed: { offered: number; rejected: number }[] = []
+
+  for (let i = 0; i < 50; i++) recordIngest(l, 10, [], i * 1000, w => closed.push(w))
+  assert.equal(closed.length, 0, '10분이 안 지났으면 한 번도 안 부른다')
+
+  recordIngest(l, 10, [], INGEST_WINDOW_MS + 1, w => closed.push(w))
+  assert.equal(closed.length, 1, '창이 닫힐 때 한 번')
+  assert.equal(closed[0].offered, 500, '닫힌 창의 값을 그대로 넘긴다')
+})
+
+test('영속이 실패해도 장부는 계속 굴러간다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 10, [], 0)
+
+  assert.doesNotThrow(() =>
+    recordIngest(l, 10, [], INGEST_WINDOW_MS + 1, () => {
+      throw new Error('DB down')
+    })
+  )
+  assert.equal(l.trend.length, 1, '창은 닫혔다')
+  assert.equal(ingestHealth(l, 'attached').total.offered, 20, '집계도 이어진다')
+})
+
+/* ── 입력 방어 ──────────────────────────────────────────────────────────── */
+
+test('망가진 제시 수는 기록하지 않는다 — 통과율이 거짓이 되지 않게', () => {
+  const l = newIngestLedger()
+  recordIngest(l, -5, [], 1)
+  recordIngest(l, NaN, [], 1)
+
+  assert.equal(ingestHealth(l, 'attached').lastAt, null, '아무것도 안 쌓였다')
+})
+
+test('사유가 비어 있으면 지어내지 않고 unknown 으로 둔다', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 1, [{ errors: [] }], 1)
+
+  assert.equal(ingestHealth(l, 'attached').reasons[0].reason, 'unknown')
+})