@things-factory/headless-twin 10.0.11 → 10.0.13

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')
+})

package/test/ingest-history.test.ts

@@ -0,0 +1,247 @@
+/*
+ * ★ 인제스트 이력 — **재기동 뒤에도 추이가 이어진다.**
+ *
+ * ── 무엇이 미완이었나 (2026-08-20) ──────────────────────────────────────────
+ * 닫힌 창을 표로 남기기 시작했는데 **읽는 코드가 없었다.** 21행이 쌓여 있고 아무도 보지 않았다 —
+ * 이 프로젝트가 결함으로 보는 상태다(「필드만 만들고 아무도 읽지 않는다」). 표를 만든 이유가
+ * 「메모리 장부는 재기동에 사라지고 6시간까지인데 추이는 그보다 오래 봐야 한다」였으니 목적이
+ * 절반만 서 있었다.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 표와 메모리를 이어 붙이되 **겹친 창을 두 번 내지 않는다** — 같은 구간이 두 번 그려지면 추이가
+ *    거짓이 된다. 겹치면 메모리 쪽을 쓴다(같은 사실의 원본이다).
+ * ② 어디서부터 메모리인지 밝힌다(`liveFrom`) — 화면이 근거를 말할 수 있게. 재기동 직후에는 `null`
+ *    이고, 그때 보이는 것은 전부 표에서 온 것이다.
+ * ③ **조용히 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
+ * ④ 남의 도메인·남의 트윈의 창을 집지 않는다.
+ * ⑤ 제시가 0 인 창의 통과율은 `null` 이다 — 빈 창은 완벽한 창이 아니다.
+ */
+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 } = req('../dist-server/engine/ingest-health.js')
+const { TwinIngestWindow } = req('../dist-server/service/twin-ingest-window/twin-ingest-window.js')
+const { TwinIngestWindowQuery, HISTORY_WINDOW_LIMIT, HISTORY_HOURS_MAX } = req(
+  '../dist-server/service/twin-ingest-window/twin-ingest-window-query.js'
+)
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let otherDomainId: string
+
+const TWIN = 'hist-twin'
+const HOUR = 3_600_000
+
+const resolver = new TwinIngestWindowQuery()
+const ask = (instanceId: string, hours?: number, domain = domainId) =>
+  resolver.twinIngestHistory(instanceId, hours, { state: { domain: { id: domain } } } as any)
+
+/** 표에 닫힌 창 하나 — 시각은 「몇 시간 전」으로 준다. */
+async function storedWindow(instanceId: string, hoursAgo: number, offered: number, rejected = 0, domain = domainId) {
+  const closed = new Date(Date.now() - hoursAgo * HOUR)
+  const opened = new Date(closed.getTime() - 600_000)
+  const repo = ds.getRepository(TwinIngestWindow)
+  await repo.save(
+    repo.create({
+      domain: { id: domain } as any,
+      instanceId,
+      openedAt: opened,
+      closedAt: closed,
+      offered,
+      rejected,
+      undelivered: 0,
+      journaledRows: 0,
+      journalFlushes: 0,
+      ...(offered > 0 ? { acceptedRatio: (offered - rejected) / offered } : {})
+    } as any)
+  )
+  return opened.toISOString()
+}
+
+async function instance(instanceId: string, domain = domainId) {
+  const repo = ds.getRepository(TwinInstance)
+  await repo.save(
+    repo.create({
+      domain: { id: domain } as any,
+      instanceId,
+      spaceId: 'hist-space',
+      kind: 'wms',
+      status: 'stopped',
+      restartPolicy: 'reset',
+      purpose: 'operational'
+    } as any)
+  )
+}
+
+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)
+
+  domainId = (await ds.getRepository(Domain).save({ name: 'hist', subdomain: 'hist' } as any)).id
+  otherDomainId = (await ds.getRepository(Domain).save({ name: 'hist-other', subdomain: 'hist-other' } as any)).id
+  await instance(TWIN)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+test('표에 남은 창을 읽어 온다 — 재기동으로 메모리가 비어도 추이가 있다', async () => {
+  await storedWindow(TWIN, 5, 100, 4)
+  await storedWindow(TWIN, 3, 200, 0)
+
+  const r = await ask(TWIN)
+  assert.equal(r.windows.length, 2)
+  assert.equal(r.storedCount, 2)
+  assert.equal(r.liveCount, 0, '메모리에는 닫힌 창이 없다(이 트윈은 이 프로세스에서 받은 적이 없다)')
+  assert.equal(r.liveFrom, null, '그래서 「여기서부터 메모리」가 없다 — 0 이나 지금으로 채우지 않는다')
+})
+
+test('오래된 것이 앞, 최신이 뒤 — 추이는 시간순이어야 그림이 된다', async () => {
+  const r = await ask(TWIN)
+  const times = r.windows.map((w: any) => Date.parse(w.from))
+  assert.deepEqual(times, [...times].sort((a, b) => a - b), '오름차순')
+})
+
+test('통과는 트윈에 닿은 것만 — 표의 통과율을 그대로 쓴다', async () => {
+  const r = await ask(TWIN)
+  const w = r.windows.find((x: any) => x.offered === 100)
+  assert.equal(w.rejected, 4)
+  assert.equal(w.accepted, 96)
+  assert.equal(w.acceptedRatio, 0.96)
+})
+
+test('제시가 0 인 창의 통과율은 「없음」이다 — 빈 창은 완벽한 창이 아니다', async () => {
+  await storedWindow(TWIN, 2, 0, 0)
+
+  const r = await ask(TWIN)
+  const empty = r.windows.find((x: any) => x.offered === 0)
+  assert.equal(empty.acceptedRatio, null)
+})
+
+test('물은 기간 밖의 창은 오지 않는다', async () => {
+  await storedWindow(TWIN, 40, 999, 0) // 40시간 전
+
+  const r = await ask(TWIN, 24)
+  assert.ok(
+    !r.windows.some((w: any) => w.offered === 999),
+    '24시간을 물었으면 40시간 전 창은 안 온다'
+  )
+
+  const wide = await ask(TWIN, 48)
+  assert.ok(
+    wide.windows.some((w: any) => w.offered === 999),
+    '48시간을 물으면 온다'
+  )
+})
+
+test('기간 상한을 넘겨 물으면 자르고, 자른 사실을 낸다', async () => {
+  const r = await ask(TWIN, HISTORY_HOURS_MAX + 100)
+
+  assert.equal(r.hours, HISTORY_HOURS_MAX, '상한까지만 본다')
+  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 조용히 자르지 않는다')
+})
+
+test('상한 안에서는 잘렸다고 말하지 않는다 — 없는 문제를 만들지 않는다', async () => {
+  const r = await ask(TWIN, 24)
+  assert.equal(r.hoursClamped, undefined)
+  assert.equal(r.storedDropped, 0)
+})
+
+test('창 수 상한에서 밀려난 수를 센다', async () => {
+  const many = 'hist-many'
+  await instance(many)
+  /* 상한 + 5개를 심는다. 10분 간격이므로 상한을 넘기려면 그만큼의 창이 필요하다. */
+  for (let i = 0; i < HISTORY_WINDOW_LIMIT + 5; i++) await storedWindow(many, 1 + i * 0.01, 10, 0)
+
+  const r = await ask(many, HISTORY_HOURS_MAX)
+  assert.equal(r.windows.length, HISTORY_WINDOW_LIMIT, '상한까지만 낸다')
+  assert.equal(r.storedDropped, 5, '밀려난 수를 말한다')
+})
+
+test('남의 도메인 창을 집지 않는다', async () => {
+  await instance('hist-shared', otherDomainId)
+  await storedWindow('hist-shared', 1, 777, 0, otherDomainId)
+
+  /* 같은 instanceId 를 내 도메인에서 물어도 남의 창이 오면 안 된다. */
+  await instance('hist-shared')
+  const mine = await ask('hist-shared')
+  assert.ok(
+    !mine.windows.some((w: any) => w.offered === 777),
+    '남의 도메인 창이 새지 않는다'
+  )
+})
+
+test('내 도메인에 없는 트윈은 「없음」이다 — 남의 것이라 말하지 않는다', async () => {
+  assert.equal(await ask('does-not-exist'), null)
+})
+
+test('겹친 창을 두 번 내지 않는다 — 같은 구간이 두 번 그려지면 추이가 거짓이 된다', async () => {
+  /*
+   * 프로세스가 살아 있는 동안 닫힌 창은 **표와 메모리에 둘 다** 있다(영속 훅이 창이 닫힐 때 쓴다).
+   * 정리하지 않으면 그 구간이 추이에 두 번 들어가 유입이 두 배로 보인다.
+   */
+  const twin = 'hist-overlap'
+  await instance(twin)
+
+  /* 메모리에 닫힌 창 하나를 만든다 — 창은 다음 유입이 있을 때 닫힌다. */
+  const t0 = Date.now() - Math.floor(INGEST_WINDOW_MS * 1.4)
+  TwinEngine.recordIngestResult(domainId, twin, 50, [], t0)
+  TwinEngine.recordIngestResult(domainId, twin, 1, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const live = TwinEngine.ingestHealthOf(domainId, twin).trend
+  assert.equal(live.length, 1, '메모리에 닫힌 창 하나')
+
+  /* 같은 창을 표에도 심는다(영속 훅이 했을 일). 값은 일부러 다르게 두어 어느 쪽이 이겼는지 본다. */
+  const repo = ds.getRepository(TwinIngestWindow)
+  await repo.save(
+    repo.create({
+      domain: { id: domainId } as any,
+      instanceId: twin,
+      openedAt: new Date(Date.parse(live[0].from)),
+      closedAt: new Date(Date.parse(live[0].to)),
+      offered: 999,
+      rejected: 0,
+      undelivered: 0,
+      journaledRows: 0,
+      journalFlushes: 0,
+      acceptedRatio: 1
+    } as any)
+  )
+
+  const r = await ask(twin)
+  const sameStart = r.windows.filter((w: any) => Date.parse(w.from) === Date.parse(live[0].from))
+  assert.equal(sameStart.length, 1, '한 번만 낸다')
+  assert.equal(sameStart[0].source, 'live', '겹치면 메모리 쪽 — 같은 사실의 원본이다')
+  assert.equal(sameStart[0].offered, 50, '표의 999 가 아니라 메모리의 50')
+  assert.equal(r.liveFrom, live[0].from, '어디서부터 메모리인지 밝힌다')
+})
+
+test('겹치지 않는 표의 창은 메모리 앞에 이어 붙는다', async () => {
+  const twin = 'hist-overlap'
+  /* 메모리 창보다 오래된 것 — 이건 표에서만 온다. */
+  await storedWindow(twin, 6, 30, 1)
+
+  const r = await ask(twin)
+  assert.equal(r.windows.length, 2, '표 하나 + 메모리 하나')
+  assert.equal(r.windows[0].source, 'stored', '오래된 것이 앞')
+  assert.equal(r.windows[1].source, 'live')
+})