@things-factory/headless-twin 10.0.12 → 10.0.13

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

package/test/integration-probes.test.ts

@@ -0,0 +1,103 @@
+/*
+ * ★ 연결 적합성 하네스 — **절반만 돌린 스위트가 초록을 주장하지 못하게.**
+ *
+ * 지키는 것:
+ *  ① 돌리지 않은 프로브는 **「모른다」**로 접힌다 → 판정이 그 단계를 달성으로 만들지 않는다.
+ *  ② **실패한 프로브의 수를 0 으로 읽지 않는다.** 「0건이었다」와 「세지 못했다」는 다른 사실이다.
+ *  ③ **쓰기 프로브는 동의 없이 계획에 들어오지 않는다** — 남의 운영 시스템에 명령을 넣는 일이다.
+ *  ④ **게이팅 실패 뒤는 돌리지 않는다** — 빨간 칸을 늘리는 것은 원인을 알려 주지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { PROBE_SEQUENCE, foldProbeResults, plannedProbes, type ProbeResult } from '../server/engine/integration-probes.ts'
+import { assessStagePath, forbiddenClaims } from '../server/engine/stage-path.ts'
+
+const pass = (id: any, count?: number, coverage?: { declared: number; total: number }): ProbeResult =>
+  ({ id, ran: true, passed: true, ...(count !== undefined ? { count } : {}), ...(coverage ? { coverage } : {}) })
+
+/** 읽기 프로브 전부 통과 — 반출까지 관측된 상태. */
+const readOnlyAllPass = (): ProbeResult[] => [
+  pass('connect'), pass('discover', 1), pass('master', 12), pass('master-warnings', 3), pass('items', 340),
+  pass('live-ingest', 1200), pass('live-removal', 17),
+  pass('declarations', undefined, { declared: 6, total: 8 }), pass('forecast'),
+  pass('actuate-declared')
+]
+
+test('시퀀스는 읽기부터 시작하고 쓰기 프로브는 하나뿐이다', () => {
+  assert.equal(PROBE_SEQUENCE[0].id, 'connect')
+  assert.deepEqual(PROBE_SEQUENCE.filter(p => p.writes).map(p => p.id), ['actuate-effect'])
+})
+
+test('아무것도 돌리지 않았으면 첫 칸부터 「모른다」다 — 실패로 접지 않는다', () => {
+  const p = assessStagePath(foldProbeResults([]))
+  assert.equal(p.reached, null)
+  assert.deepEqual(p.next?.stage, 'structure')
+  assert.ok(p.stages[0].blockedBy.includes('no-locations'))
+  assert.ok(p.stages[0].unmeasured.includes('master-warnings'), '세지 않은 것은 모르는 것이다')
+})
+
+test('읽기만 전부 통과하면 예측까지 도달하고 폐루프는 「검증되지 않음」으로 남는다', () => {
+  const p = assessStagePath(foldProbeResults(readOnlyAllPass()))
+  assert.equal(p.reached, 'forecast')
+  assert.deepEqual(p.stages[3].unmeasured, ['correlated-effect'])
+  assert.deepEqual(p.stages[3].blockedBy, [], '능력은 선언∩구현이므로 막힌 것이 아니라 안 돌린 것이다')
+  assert.deepEqual(forbiddenClaims(p), ['claim.automatic-control'])
+})
+
+test('쓰기 프로브를 돌려 효과가 관측되면 폐루프가 닫힌다', () => {
+  const p = assessStagePath(foldProbeResults([...readOnlyAllPass(), pass('actuate-effect', 2)]))
+  assert.equal(p.reached, 'closed-loop')
+  assert.deepEqual(forbiddenClaims(p), [])
+})
+
+test('측정하지 못한 프로브는 수를 들지 않는다 — 0 을 지어내지 않는다', () => {
+  /*
+   * 규칙은 「실패면 모른다」가 아니다 — **센 값은 판정과 무관한 사실**이다(0건도 사실이다).
+   * 측정 자체를 못 한 프로브(타임아웃 등)는 `count` 를 **비운다**. 0 을 채우면 「세어 보니 없었다」로
+   * 읽히고, 그건 스냅샷 피드를 delta 로 오인하게 만드는 정반대의 결론을 낳는다.
+   */
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
+    { id: 'live-removal', ran: true, passed: false, detail: 'timeout' }]
+  const e = foldProbeResults(rs)
+  assert.equal(e.removalsObserved, null, '측정하지 못했으면 모른다')
+  assert.deepEqual(assessStagePath(e).stages[1].unmeasured, ['removals'])
+})
+
+test('세어서 0 을 얻은 것은 사실이다 — 모른다로 접지 않는다', () => {
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
+    { id: 'live-removal', ran: true, passed: false, count: 0 }]
+  const e = foldProbeResults(rs)
+  assert.equal(e.removalsObserved, 0)
+  assert.deepEqual(assessStagePath(e).stages[1].blockedBy, ['no-removal-observed'])
+})
+
+test('반출을 세었는데 0 이면 라이브가 막힌다 — 스냅샷 되풀어 읽기', () => {
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'), pass('live-removal', 0)]
+  const p = assessStagePath(foldProbeResults(rs))
+  assert.deepEqual(p.stages[1].blockedBy, ['no-removal-observed'])
+  assert.equal(p.reached, 'structure')
+  assert.ok(forbiddenClaims(p).includes('claim.realtime'))
+})
+
+test('쓰기 프로브는 동의 없이 계획에 들어오지 않는다', () => {
+  assert.ok(!plannedProbes([]).includes('actuate-effect'))
+  assert.ok(plannedProbes([], { allowWrites: true }).includes('actuate-effect'))
+})
+
+test('게이팅 프로브가 실패하면 그 뒤는 계획하지 않는다', () => {
+  const planned = plannedProbes([{ id: 'connect', ran: true, passed: false, detail: '401' }])
+  assert.deepEqual(planned, [], '붙지 못했으면 뒤를 두드릴 이유가 없다')
+})
+
+test('통과한 프로브는 다시 계획하지 않고, 남은 것만 계획한다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1)])
+  assert.equal(planned[0], 'master')
+  assert.ok(!planned.includes('connect'))
+})
+
+test('게이팅이 아닌 프로브의 실패는 뒤를 멈추지 않는다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1), pass('master', 12),
+    { id: 'master-warnings', ran: true, passed: false, detail: 'not-counted' }])
+  assert.ok(planned.includes('items'), '못 옮긴 값을 세지 못한 것이 구조 확인을 멈추지는 않는다')
+})