@things-factory/headless-twin 10.0.14 → 10.0.17

package/server/engine/ingest-dedupe.ts

@@ -0,0 +1,149 @@
+/*
+ * 같은 사실을 두 번 받으면 한 번만 반영한다 — **유입 경계 한 곳에서.**
+ *
+ * ── 왜 필요한가 (2026-08-26) ────────────────────────────────────────────────
+ * 지금 중복을 막는 것은 커넥터마다 각자 하고 있다. 그래서 커넥터가 그것을 잊으면 트윈이 그대로 두 번
+ * 센다. 실제로 그랬다: 태양광 커넥터가 10초마다 물으면서 10분마다 바뀌는 값을 매번 다시 보냈고,
+ * 한 주기에 76건이 되풀이됐다(커넥터에서 고쳐서 2건이 됐다).
+ *
+ * 그리고 이것은 웹훅으로 받을 때 더 자주 난다. 밀어 주는 방식은 재전송이 정상이다 — 그쪽이 응답을
+ * 못 받으면 같은 것을 다시 보낸다.
+ *
+ * ── 무엇이 두 번 세어지나 ──────────────────────────────────────────────────
+ * 절대값으로 말하는 사실은 여러 번 반영해도 결과가 같다(잔량 · 상태 · 적산 · 순간 kW). 그런데 세는
+ * 값은 그렇지 않다.
+ *
+ *   구간의 표본 수 · 평균 부하(표본 수로 나눈다) · OEE 카운터 · 유입 계수
+ *   그리고 지난 기록에 같은 사실이 두 줄로 남는다 — 나중에 그 기록으로 다시 계산하면 또 두 번 센다
+ *
+ * ── 정체를 무엇으로 보나 ────────────────────────────────────────────────────
+ * 봉투의 `eventId` 로는 판단할 수 없다. 보낸 쪽이 매번 새로 만드는 순번이고(`…-energy-1` 처럼 호출마다
+ * 1부터 다시 시작한다), 같은 사실을 두 번 보내면 다른 번호가 붙는다. 다른 사실에 같은 번호가 붙는 일도
+ * 생긴다.
+ *
+ * 그래서 **사실 자체로** 판단한다.
+ *
+ *   무엇에 대한 것인가   설비 · 계량 지점 · 물품 · 작업 · 오더 · 자리
+ *   어떤 종류인가        사건 종류(eventType)
+ *   언제 잰 것인가       연결된 시스템이 준 시각
+ *
+ * 이 셋이 같으면 같은 사실이다. 태양광 커넥터가 `collectedAt` 으로 판단한 것과 같은 방식이고, 그것을
+ * 커넥터마다 하지 않도록 여기로 올린다.
+ *
+ * ── 정확히 같은 것만 버린다 ─────────────────────────────────────────────────
+ * 늦게 도착한 옛 사실은 버리지 않는다. 그것이 왔다는 것 자체가 사실이고, 상태에 반영되지 않는 것은
+ * 커널의 순서 판단이 이미 맡는다. 여기서 버리는 것은 **정체가 완전히 같은 것**뿐이다.
+ */
+
+/** 시각을 밀리초로 — 연결된 시스템이 준 시각이 먼저, 없으면 봉투의 시각. */
+function timeOf(envelope: any): number | undefined {
+  for (const v of [envelope?.data?.at, envelope?.data?.eventTime, envelope?.eventTime]) {
+    const t = Date.parse(String(v ?? ''))
+    if (Number.isFinite(t)) return t
+  }
+  return undefined
+}
+
+/**
+ * 이 봉투가 말하는 대상 — 어휘마다 이름이 다르므로 아는 이름을 모두 본다.
+ *
+ * 순서가 뜻을 갖는다: 주체를 먼저 본다. 설비 사실은 「지금 붙어 있는 작업」을 함께 싣고, 작업 사실은
+ * 「소속 오더」를 함께 싣는다. 아무 이름이나 먼저 보면 참조를 주체로 읽는다(승격 키에서 겪은 것과 같다).
+ */
+function targetOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? {}
+  const first = (...vals: unknown[]) => {
+    for (const v of vals) {
+      const s = String(v ?? '').trim()
+      if (s) return s
+    }
+    return undefined
+  }
+  return first(
+    d.meterId,
+    d.equipmentId,
+    d.moverId,
+    d.taskId,
+    d.orderId,
+    d.personId,
+    d.assetId,
+    d.locationId,
+    d.epcList?.[0],
+    d.parentID,
+    d.quantityList?.[0]?.epcClass,
+    d.transformationID
+  )
+}
+
+/**
+ * 이 봉투가 말하는 사실의 정체 — 같으면 같은 사실이다.
+ *
+ * 대상이나 시각을 알 수 없으면 **정체를 만들지 않는다**(`undefined`). 그때는 거르지 않고 통과시킨다 —
+ * 모르는 것을 같다고 판단하면 서로 다른 사실이 하나로 합쳐진다. 알리지 않고 잃는 것보다 두 번 세는 것이 낫다.
+ */
+export function factIdentity(envelope: any): string | undefined {
+  const type = String(envelope?.eventType ?? '').trim()
+  if (!type) return undefined
+  const target = targetOf(envelope)
+  if (!target) return undefined
+  const at = timeOf(envelope)
+  if (at === undefined) return undefined
+  return `${type}|${target}|${at}`
+}
+
+/**
+ * 최근에 본 정체를 기억한다 — **크기에 상한을 둔다.**
+ *
+ * 전부 기억할 수는 없다(트윈 하나가 수천만 사건을 갖는다). 창을 넘으면 오래된 것부터 잊는다. 창 밖의
+ * 재전송은 다시 통과하는데, 그것은 절대값 사실이라 상태에 해가 없고 지난 기록에 한 줄 더 남는다.
+ * 창을 크게 잡으면 그만큼 메모리를 쓴다 — 그 값을 여기서 이름으로 못 박는다.
+ *
+ * **재기동을 건너지 못한다.** 프로세스가 새로 뜨면 기억이 비어 있으므로, 재기동 직후 첫 주기가 같은
+ * 값을 다시 보내면 걸러지지 않는다. 그것을 막으려면 이 기억이 저장돼야 하고, 그것은 다음 걸음이다.
+ * 지금은 그 사실을 여기 적어 둔다 — 적어 두지 않으면 「중복은 이제 없다」로 읽힌다.
+ */
+export class FactDeduper {
+  /** 기억하는 정체의 수 — 창. */
+  static WINDOW = 20_000
+
+  private seen = new Set<string>()
+  private order: string[] = []
+
+  /** 이 사실을 본 적이 있나 — 없으면 기억하고 `false`. */
+  private known(identity: string): boolean {
+    if (this.seen.has(identity)) return true
+    this.seen.add(identity)
+    this.order.push(identity)
+    if (this.order.length > FactDeduper.WINDOW) {
+      const gone = this.order.splice(0, this.order.length - FactDeduper.WINDOW)
+      for (const g of gone) this.seen.delete(g)
+    }
+    return false
+  }
+
+  /**
+   * 처음 보는 것만 돌려준다 — 그리고 몇 개를 버렸는지 함께 낸다.
+   *
+   * 버린 수를 함께 내는 이유: 알리지 않고 버리면 「보낸 수」와 「반영된 수」가 어긋나는데 아무도 그
+   * 이유를 모른다. 그 수가 크면 보내는 쪽이 되풀이 보내고 있다는 뜻이고, 그것은 고칠 일이다.
+   */
+  filter<T>(envelopes: readonly T[]): { fresh: T[]; duplicates: number } {
+    const fresh: T[] = []
+    let duplicates = 0
+    for (const e of envelopes) {
+      const id = factIdentity(e)
+      if (id === undefined) {
+        fresh.push(e)
+        continue
+      }
+      if (this.known(id)) duplicates++
+      else fresh.push(e)
+    }
+    return { fresh, duplicates }
+  }
+
+  /** 기억하고 있는 정체의 수 — 계기가 읽는다. */
+  size(): number {
+    return this.seen.size
+  }
+}

package/server/engine/ingest-health.ts

@@ -4,12 +4,12 @@
  * ── 한 질문 ─────────────────────────────────────────────────────────────────
  * 화면에서 값이 변하지 않을 때 원인이 넷인데, 지금까지 **넷이 똑같이 보였다.**
  *   ① 피드가 붙지 않았다  ② 붙었는데 아무것도 오지 않는다
- *   ③ 오는데 전부 거부된다  ④ 정상인데 현장이 조용하다
+ *   ③ 오는데 전부 거부된다  ④ 정상인데 현장이 들어온 것이 없다
  * ③은 특히 나쁘다 — 커넥터의 매핑이 한 글자 틀리면 트윈은 「빈 공장」이 되고, 그 사실이 서버 로그
  * 한 줄에만 남았다. 현장에 나간 사람은 로그를 뒤져야 했다.
  *
  * ── 왜 저널로는 답할 수 없나 ────────────────────────────────────────────────
- * **거부된 것은 저널에 없다** — 거부의 뜻이 그것이다. 저널을 접으면 통과한 쪽만 나온다. 거부의 추이는
+ * **거부된 것은 저널에 없다** — 거부의 뜻이 그것이다. 저널을 계산하면 통과한 쪽만 나온다. 거부의 추이는
  * 세는 자리를 따로 두어야 나온다. 이 장부가 그 자리다.
  *
  * ── 왜 건마다 저장하지 않나 ─────────────────────────────────────────────────
@@ -23,7 +23,7 @@
  * ── 지키는 규율 넷 ──────────────────────────────────────────────────────────
  *  ① **닫힌 창만 「최근」이다** — 채우는 중인 창은 과소 집계다(부하 계기판에서 겪었다).
  *  ② **0 과 「없음」을 가른다** — 안 받은 것은 `null`, 받았지만 거부 0 은 `0`.
- *  ③ **조용히 자르지 않는다** — 표본·추이 상한에서 밀려난 수를 함께 낸다.
+ *  ③ **알리지 않고 자르지 않는다** — 표본·추이 상한에서 밀려난 수를 함께 낸다.
  *  ④ **통과율에 1 을 함부로 쓰지 않는다** — 1,000건 중 1건 거부는 0.999 다.
  */
 
@@ -41,7 +41,7 @@ export interface IngestWindow {
    * 매핑은 통과했지만 **트윈에 닿지 못한** 수 — 처방은 트윈을 세우는 것이다.
    *
    * ── 왜 거부와 따로 세나 (2026-08-20에 겪었다) ─────────────────────────────
-   * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **조용히 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
+   * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **알리지 않고 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
    * 화면이 「150 들어옴 · 150 통과 · 100%」라고 말하는 동안 150건은 바닥에 버려지고 있었다. 이 기능이
    * 막으려던 바로 그것을 이 기능이 저지른 셈이다.
    *
@@ -103,12 +103,29 @@ export interface IngestLedger {
    */
   lastUndeliveredAtMs: number
   /** 사유별 누적 건수와 **마지막으로 그 사유가 난 시각** — 고친 사유는 시각이 멈춘다. */
+  /**
+   * **어떤 길로 들어왔나** — 경로마다 건수와 마지막 시각.
+   *
+   * ── 왜 필요한가 (2026-08-26) ──────────────────────────────────────────────
+   * 트윈이 값을 받고 있다는 것은 계기가 말해 주는데, **무엇을 통해 받는지는 아무도 말하지 않았다.**
+   * 커넥터가 물어서 받는지, 연결된 시스템이 밀어 주는지, 시나리오가 넣는지, 부하 도구가 넣는지 —
+   * 화면에서 구별할 수 없었다. 그 구별이 없으면 「폴링을 웹훅으로 바꿨다」를 확인할 방법도 없다.
+   */
+  bySource: Record<string, { count: number; lastAtMs: number }>
+  /**
+   * **같은 사실이 두 번 와서 버린 수** — 알리지 않고 버리지 않는다.
+   *
+   * 이 수가 크면 보내는 쪽이 되풀이 보내고 있다는 뜻이고, 그것은 고칠 일이다(태양광 커넥터가 한 주기에
+   * 76건을 되풀이 보내던 것을 이 수로 볼 수 있었어야 했다).
+   */
+  duplicates: number
+  lastDuplicateAtMs: number
   byReason: Record<string, { count: number; lastAtMs: number }>
   /**
    * 사유 종류가 상한에 닿았나.
    *
-   * **접힌 종류 수는 세지 않는다** — 그것을 세려면 이미 본 사유를 모두 기억해야 하고, 그 집합이
-   * 바로 이 상한으로 막으려던 무한한 집합이다. 접힌 **건수**는 `byReason[OTHER_REASON].count` 가 답한다.
+   * **모은 종류 수는 세지 않는다** — 그것을 세려면 이미 본 사유를 모두 기억해야 하고, 그 집합이
+   * 바로 이 상한으로 막으려던 무한한 집합이다. 모은 **건수**는 `byReason[OTHER_REASON].count` 가 답한다.
    */
   reasonsCapped: boolean
   /** 표본을 이미 뜬 사유들 — 같은 사유를 다시 직렬화하지 않기 위한 색인(O(1) 조회). */
@@ -122,12 +139,12 @@ export interface IngestLedger {
   /**
    * **원본에 닿지 못한 사실** (2026-08-23) — 「받은 것이 없다」와 **다른 사실**이다.
    *
-   * ── 무엇이 조용했나 ─────────────────────────────────────────────────────────
+   * ── 무엇이 아무 신호도 내지 않았나 ─────────────────────────────────────────────────────────
    * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
    * `recordIngest` 는 `onRecords` 가 불릴 때만 도달하고, 읽기가 실패하면 그 문에 오지 않는다.
    * `TwinReference.lastError` 는 마스터 동기·접속 시험에만 적힌다.
    *
-   * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「원본이 조용하다」와 구별되지
+   * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「연결된 시스템에서 들어온 것이 없다」와 구별되지
    * 않는다.** 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
    *
    * ── 왜 「몇 번」과 「언제부터」를 함께 두나 ──────────────────────────────────
@@ -136,6 +153,13 @@ export interface IngestLedger {
    *
    * 성공하면 지운다 — 고쳐진 단절이 화면에 남아 있으면 그것도 거짓이다.
    */
+  /**
+   * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다.
+   *
+   * 실패 기록(`readFailure`)은 돌아오면 지워진다. 그것만 지우면 「끊긴 적이 있었다」가 화면에서
+   * 사라지므로, 돌아온 사실을 따로 남긴다.
+   */
+  lastRecovery?: { atMs: number; afterFailures: number; downMs: number }
   readFailure?: {
     /** 연속 실패 수 — 성공 한 번에 0 으로 돌아간다. */
     consecutive: number
@@ -147,6 +171,8 @@ export interface IngestLedger {
     reason: string
     /** 어느 흐름에서 났나(어댑터가 말해 주면). 원본마다 흐름이 다르므로 열려 있다. */
     stream?: string
+    /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+    nextRetryMs?: number
   }
   /**
    * **읽었는데 창을 넘길 수 없다** (2026-08-24) — 위와 **다른 사실**이다.
@@ -165,6 +191,27 @@ export interface IngestLedger {
    * 모양은 위와 같게 둔다 — 「몇 번」과 「언제부터」가 여기서도 같은 값을 한다(한 번의 밀림과 사흘째
    * 못 넘어가는 것은 다르다). 넘어가면 지운다.
    */
+  /**
+   * **원본이 말했는데 트윈에 세우지 않은 것** — 이유별로 센다.
+   *
+   * ── 왜 이 자리가 필요한가 (2026-08-24) ─────────────────────────────────────
+   * 커넥터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**: 입자가 맞지 않거나, 받으면 상태가
+   * 거짓이 되거나, 커널 어휘로 옮길 수 없다. 그때 커넥터는 경고를 낸다 — **그런데 그 경고가 프로비저닝
+   * 화면에서 한 번 스쳐 지나갈 뿐이었다.** 그 뒤로는 어디에서도 볼 수 없었다.
+   *
+   * 그래서 사용자가 「원본보다 계획이 적다」를 물으면 **답이 어디에도 없다.** 그 사실은 한 번의
+   * 사건이 아니라 **상태의 성질**이다 — 세우지 않은 것은 지금도 트윈에 없다.
+   *
+   * ── `unhandled` 의 형제다 ──────────────────────────────────────────────────
+   *   `unhandled`   리듀서가 **받았는데** 담을 자리를 몰랐다
+   *   여기          커넥터가 **보지만 일부러 보내지 않았다** — 이유와 함께
+   *
+   * 둘 다 「사실이 오류 없이 사라지지 않게」 세는 것이고, 이유가 다르므로 자리도 다르다.
+   *
+   * 이유를 **문자열로 받는다**: 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 그 목록을 닫으면 새 원본을
+   * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율).
+   */
+  withheld?: { reason: string; count: number; lastAtMs: number }[]
   cursorStall?: {
     /** 연속 정체 수 — 넘어가면 0 으로 돌아간다. */
     consecutive: number
@@ -189,7 +236,17 @@ export function recordReadFailure(
   ledger: IngestLedger,
   reason: string,
   nowMs: number,
-  stream?: string
+  stream?: string,
+  /**
+   * 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰으면 그 값을 준다 (2026-08-27).
+   *
+   * 이것이 없으면 화면이 「닿지 못하고 있다」까지만 말하고, 사람은 **언제 다시 시도하는지** 알 수
+   * 없다. 그러면 기다려야 하는지 손을 써야 하는지 판단하지 못한다.
+   *
+   * **연달아 횟수와 시작 시각은 커넥터가 보내지 않는다** — 이 함수가 이미 센다. 두 곳에서 세면
+   * 갈라지고, 갈라지면 어느 쪽이 사실인지 알 수 없다.
+   */
+  nextRetryMs?: number
 ): void {
   const prev = ledger.readFailure
   ledger.readFailure = {
@@ -197,15 +254,28 @@ export function recordReadFailure(
     sinceMs: prev?.sinceMs ?? nowMs,
     lastAtMs: nowMs,
     reason,
-    ...(stream ? { stream } : {})
+    ...(stream ? { stream } : {}),
+    ...(Number.isFinite(nextRetryMs) && (nextRetryMs as number) > 0 ? { nextRetryMs: nextRetryMs as number } : {})
   }
 }
 
+/**
+ * **끊겼다가 돌아왔다** — 그 사실을 남긴다 (2026-08-27).
+ *
+ * 실패 기록만 지우면 「끊긴 적이 있었다」가 화면에서 사라진다. 그러면 밤새 두 시간 끊겼던 연결과 한
+ * 번도 끊기지 않은 연결이 아침에 똑같이 보인다. 몇 번 실패한 뒤에 돌아왔는지, 얼마나 끊겼는지를 함께
+ * 남긴다.
+ */
+export function recordRecovered(ledger: IngestLedger, afterFailures: number, downMs: number, nowMs: number): void {
+  if (ledger.readFailure) delete ledger.readFailure
+  ledger.lastRecovery = { atMs: nowMs, afterFailures, downMs }
+}
+
 /**
  * 읽기가 성공했다 — 단절 기록을 지운다.
  *
  * **빈 읽기도 성공이다**: 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이다. 그 둘을 같게 두면
- * 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+ * 들어온 것이 없는 연결이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
  */
 export function clearReadFailure(ledger: IngestLedger): void {
   if (ledger.readFailure) delete ledger.readFailure
@@ -229,6 +299,48 @@ export function recordCursorStall(ledger: IngestLedger, reason: string, nowMs: n
   }
 }
 
+/**
+ * **세우지 않은 것을 적는다** — 이유별 누적.
+ *
+ * 주기마다 다시 알려도 시끄러워지지 않게 **이유로 묶어 센다**(줄이 늘지 않는다). 그리고 마지막 시각을
+ * 함께 든다 — 「지금도 그런가」와 「한때 그랬나」는 다른 사실이고, 시각 없이는 구별할 수 없다.
+ *
+ * 이유가 같고 수가 달라지면 **마지막 수로 덮는다**: 이것은 누적 사건이 아니라 **지금 세우지 않은 것의
+ * 수**다. 주기마다 8건이면 8이고, 더해서 800이 되면 거짓이다.
+ */
+/**
+ * 어떤 길로 몇 건이 들어왔나 — 경로 이름은 부르는 쪽이 정한다.
+ *
+ * 이름을 자유 문자열로 두는 이유: 길이 늘어난다(지금은 물어보기·시나리오·부하 도구, 다음은 웹훅).
+ * 열거로 못 박으면 새 길이 생길 때 이 파일을 함께 고쳐야 하고, 잊으면 그 길이 통계에서 사라진다.
+ */
+export function recordIngestSource(ledger: IngestLedger, source: string, count: number, nowMs: number): void {
+  const key = String(source ?? '').trim() || 'unknown'
+  if (count <= 0) return
+  const cur = (ledger.bySource[key] ??= { count: 0, lastAtMs: -1 })
+  cur.count += count
+  cur.lastAtMs = nowMs
+}
+
+/** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+export function recordDuplicates(ledger: IngestLedger, count: number, nowMs: number): void {
+  if (count <= 0) return
+  ledger.duplicates += count
+  ledger.lastDuplicateAtMs = nowMs
+}
+
+export function recordWithheld(ledger: IngestLedger, reason: string, count: number, nowMs: number): void {
+  if (!reason || !(count > 0)) return
+  const list = (ledger.withheld ??= [])
+  const at = list.find(w => w.reason === reason)
+  if (at) {
+    at.count = count
+    at.lastAtMs = nowMs
+    return
+  }
+  list.push({ reason, count, lastAtMs: nowMs })
+}
+
 /** 창을 넘겼으면 지운다 — 풀린 정체가 화면에 남아 있으면 그것도 거짓이다. */
 export function clearCursorStall(ledger: IngestLedger): void {
   if (ledger.cursorStall) delete ledger.cursorStall
@@ -255,7 +367,7 @@ export const TREND_LIMIT = 36
  * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
  * 미미한 오버헤드가 아니라 누수다.
  *
- * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 접었는지 함께 낸다**(조용히 자르지 않는다).
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 모았는지 함께 낸다**(알리지 않고 자르지 않는다).
  * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
  */
 export const REASON_LIMIT = 30
@@ -296,6 +408,9 @@ export function newIngestLedger(): IngestLedger {
     flushes: 0,
     lastWriteAtMs: -1,
     lastUndeliveredAtMs: -1,
+    bySource: {},
+    duplicates: 0,
+    lastDuplicateAtMs: -1,
     byReason: {},
     reasonsCapped: false,
     sampledReasons: new Set<string>(),
@@ -404,7 +519,7 @@ export function recordIngest(
     const raw = reasonKey(it?.errors)
     const known = raw in ledger.byReason
 
-    /* 사유 종류 상한 — 넘치면 한 칸으로 접고, **닿았다는 사실**을 표시한다. */
+    /* 사유 종류 상한 — 넘치면 한 칸으로 모으고, **닿았다는 사실**을 표시한다. */
     let key = raw
     if (!known && Object.keys(ledger.byReason).length >= REASON_LIMIT) {
       key = OTHER_REASON
@@ -469,7 +584,7 @@ export function recordJournalWrite(
   /*
    * **`lastAtMs` 는 건드리지 않는다.** 그 값은 「마지막 유입」이고, 끊긴 피드를 가려내는 근거다. 쓰기로
    * 갱신하면 라이브 트윈은 유입이 끊겨도 틱이 만든 델타를 계속 적으므로 **영원히 「방금 받았다」**가 되고,
-   * 「오래 끊긴 피드에 옛 창으로 초록을 내지 않는다」가 조용히 무력해진다. 축을 따로 든다.
+   * 「오래 끊긴 피드에 옛 창으로 초록을 내지 않는다」가 오류 하나 없이 무력해진다. 축을 따로 든다.
    */
   ledger.lastWriteAtMs = nowMs
 }
@@ -512,11 +627,18 @@ export function syncVerdictOf(args: {
   nowMs?: number
   /** 마지막으로 **버려진** 시각. 한 번도 없으면 `-1`. */
   lastUndeliveredAtMs?: number
+  /**
+   * 지금까지 제시된 누적 수 — **「받고 있는 중」과 「오는 것이 없다」를 가르는 사실**이다.
+   *
+   * 닿은 시각(`lastAtMs`)으로는 가를 수 없다: 빈 읽기도 닿은 것이므로 그 시각이 선다. 창이 아직 닫히지
+   * 않았을 때 이 수가 0 이면 오는 것이 없는 것이고, 0 이 아니면 받고 있는 중이다.
+   */
+  offeredTotal?: number
   threshold?: number
 }): SyncVerdict {
   /*
    * ── 버려지고 있는 것이 가장 먼저다 ────────────────────────────────────────
-   * 트윈이 멈추면 피드는 남아 계속 레코드를 나르고, 커널은 그것을 조용히 버린다. 그 상태를 「해당 없음」
+   * 트윈이 멈추면 피드는 남아 계속 레코드를 나르고, 커널은 그것을 알리지 않고 버린다. 그 상태를 「해당 없음」
    * 이라 부르면 **사실이 사라지는 동안 화면이 안심시킨다** — 실제로 그렇게 떴다(멈춘 트윈 옆에 「150
    * 통과 · 100%」). 그래서 시뮬·멈춤 판정보다 먼저 본다.
    *
@@ -555,7 +677,29 @@ export function syncVerdictOf(args: {
     if (args.nowMs - args.lastAtMs > STALE_AFTER_MS) return 'no-traffic'
   }
 
-  if (!args.recent) return 'unknown'
+  /*
+   * ── **닿았는데 오는 것이 없다** 를 「모른다」로 답하지 않는다 (2026-08-28) ────
+   *
+   * 창은 **다음 유입이 있을 때** 닫힌다. 그래서 오는 것이 하나도 없는 트윈은 창이 영원히 닫히지 않고,
+   * 이 자리가 `unknown` 을 냈다 — 붙어 있고 37초마다 성공적으로 읽는 트윈이 화면에서 「모른다」였다.
+   *
+   * 그것이 드러난 계기: 커넥터가 재기동마다 재고 2,665건을 다시 말하던 것을 없앴다. 그러자 정상 상태의
+   * 유입이 0 이 되었고, **건강 신호가 그 소음을 타고 있었다**는 것이 보였다.
+   *
+   * ── 가르는 사실은 **받은 것이 있나**다 (첫 판을 고침) ─────────────────────
+   * 처음에는 닿은 시각으로 갈랐다. 그것이 틀렸다 — **빈 읽기도 닿은 것**이라 그 시각은 언제나 선다.
+   * 그래서 창을 채우는 중인 트윈(제시 200건)까지 「오는 것이 없다」로 답하게 됐고, 시험이 그것을 잡았다.
+   * 받고 있는 중인데 오는 것이 없다고 말하는 것은 **없는 것과 못 본 것을 뒤집는 것**이다.
+   *
+   *   닿았고 · 제시가 0        오는 것이 없다        `no-traffic`
+   *   닿았고 · 제시가 있다      받는 중이고 판정할 창이 아직 없다   `unknown`
+   *   한 번도 닿지 않았다       `unknown`(위 `lastAtMs < 0` 갈래)
+   */
+  if (!args.recent) {
+    const touched = typeof args.lastAtMs === 'number' && args.lastAtMs >= 0
+    const nothingOffered = (args.offeredTotal ?? 0) <= 0
+    return touched && nothingOffered ? 'no-traffic' : 'unknown'
+  }
   if (args.recent.offered <= 0) return 'no-traffic'
 
   const ratio = (args.recent.offered - args.recent.rejected) / args.recent.offered
@@ -616,7 +760,7 @@ export interface IngestHealthView {
    *
    * 커서 정체(`cursorStall`)와 **섞이지 않는다**: 이쪽은 기다리면 풀리고 그쪽은 기다려도 안 풀린다.
    *
-   * 「유입 없음」과 **다른 판정**이다: 유입 없음은 원본이 조용한 것일 수 있고, 이것은 우리가 묻지도
+   * 「유입 없음」과 **다른 판정**이다: 유입 없음은 연결된 시스템에서 들어온 것이 없는 것일 수 있고, 이것은 우리가 묻지도
    * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
    * 있는지가 그 차이다.
    */
@@ -627,7 +771,16 @@ export interface IngestHealthView {
     lastAt: string
     reason: string
     stream?: string
+    /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+    nextRetryMs?: number
   }
+  /**
+   * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다 (2026-08-27).
+   *
+   * `readFailure` 는 돌아오면 사라진다. 이 칸이 없으면 밤새 끊겼던 연결과 한 번도 끊기지 않은 연결이
+   * 아침에 똑같이 보인다.
+   */
+  lastRecovery?: { at: string; afterFailures: number; downMs: number }
 }
 
 function toWindowView(w: IngestWindow, fallbackEndMs: number): IngestWindowView {
@@ -670,6 +823,8 @@ export function ingestHealth(
     recent: recentRaw,
     lastAtMs: ledger?.lastAtMs ?? -1,
     lastUndeliveredAtMs: ledger?.lastUndeliveredAtMs ?? -1,
+    /* 창이 닫히지 않았을 때 「받는 중」과 「오는 것이 없다」를 가르는 사실. */
+    offeredTotal: ledger?.offered ?? 0,
     nowMs,
     threshold
   })
@@ -706,12 +861,22 @@ export function ingestHealth(
               since: new Date(ledger.readFailure.sinceMs).toISOString(),
               lastAt: new Date(ledger.readFailure.lastAtMs).toISOString(),
               reason: ledger.readFailure.reason,
-              ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {})
+              ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {}),
+              ...(ledger.readFailure.nextRetryMs ? { nextRetryMs: ledger.readFailure.nextRetryMs } : {})
+            }
+          }
+        : {}),
+      ...(ledger?.lastRecovery
+        ? {
+            lastRecovery: {
+              at: new Date(ledger.lastRecovery.atMs).toISOString(),
+              afterFailures: ledger.lastRecovery.afterFailures,
+              downMs: ledger.lastRecovery.downMs
             }
           }
         : {}),
       /* 커서 정체도 **이 갈래에서** 내보낸다 — 유입이 없는 장부에서도 정체는 실재한다(읽었으나 못
-         넘겼으면 유입이 0이다). 여기서 떨어뜨리면 바로 그 상황에서 조용해진다. */
+         넘겼으면 유입이 0이다). 여기서 떨어뜨리면 바로 그 상황에서 들어온 것이 없어진다. */
       ...(ledger?.cursorStall
         ? {
             cursorStall: {
@@ -722,6 +887,19 @@ export function ingestHealth(
               ...(ledger.cursorStall.stream ? { stream: ledger.cursorStall.stream } : {})
             }
           }
+        : {}),
+      /*
+       * **세우지 않은 것도 낸다 — 양쪽 갈래에서.** 유입이 한 건도 없는 장부에서도 이 사실은 실재한다
+       * (원본이 말하는데 전부 안 받는 경우가 있다). 여기서 떨어뜨리면 바로 그 상황에서 들어온 것이 없어진다.
+       */
+      ...(ledger?.withheld?.length
+        ? {
+            withheld: ledger.withheld.map(w => ({
+              reason: w.reason,
+              count: w.count,
+              lastAt: new Date(w.lastAtMs).toISOString()
+            }))
+          }
         : {})
     }
   }
@@ -734,6 +912,31 @@ export function ingestHealth(
     recent: recentRaw ? toWindowView(recentRaw, lastAnyMs) : null,
     trend: ledger.trend.map(w => toWindowView(w, lastAnyMs)),
     trendDropped: ledger.trendDropped,
+    /* 세우지 않은 것 — 양쪽 갈래에서 같은 모양으로 낸다(§`IngestLedger.withheld`). */
+    ...(ledger.withheld?.length
+      ? {
+          withheld: ledger.withheld.map(w => ({
+            reason: w.reason,
+            count: w.count,
+            lastAt: new Date(w.lastAtMs).toISOString()
+          }))
+        }
+      : {}),
+    /*
+     * **어떤 길로 들어오고 있나** — 화면이 「이 트윈은 무엇을 통해 값을 받나」를 말할 수 있게.
+     * 비어 있으면 칸을 만들지 않는다: 아직 아무것도 안 받은 트윈과 「길이 없다」를 구별한다.
+     */
+    ...(Object.keys(ledger.bySource).length
+      ? {
+          sources: Object.entries(ledger.bySource)
+            .map(([source, v]) => ({ source, count: v.count, lastAt: new Date(v.lastAtMs).toISOString() }))
+            .sort((a, b) => b.count - a.count)
+        }
+      : {}),
+    /* 같은 사실이 두 번 와서 버린 수 — 0 이면 칸을 만들지 않는다(버린 적이 없다는 뜻이다). */
+    ...(ledger.duplicates
+      ? { duplicates: { count: ledger.duplicates, lastAt: new Date(ledger.lastDuplicateAtMs).toISOString() } }
+      : {}),
     total: {
       offered: ledger.offered,
       accepted,
@@ -760,7 +963,18 @@ export function ingestHealth(
             since: new Date(ledger.readFailure.sinceMs).toISOString(),
             lastAt: new Date(ledger.readFailure.lastAtMs).toISOString(),
             reason: ledger.readFailure.reason,
-            ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {})
+            ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {}),
+            ...(ledger.readFailure.nextRetryMs ? { nextRetryMs: ledger.readFailure.nextRetryMs } : {})
+          }
+        }
+      : {}),
+    /* 끊겼다가 돌아온 것 — 지금 닿고 있어도 남긴다(그것이 없으면 밤새의 단절이 사라진다). */
+    ...(ledger.lastRecovery
+      ? {
+          lastRecovery: {
+            at: new Date(ledger.lastRecovery.atMs).toISOString(),
+            afterFailures: ledger.lastRecovery.afterFailures,
+            downMs: ledger.lastRecovery.downMs
           }
         }
       : {}),

package/server/engine/integration-probes.ts

@@ -1,11 +1,11 @@
 /*
  * 연결 적합성 하네스 — **통합을 시험 스위트처럼 돌린다.**
  *
- * 선언 적합성 하네스 세 벌과 같은 규율을 **연결**에 적용한다: 사실이 조용히 사라지는 것을 막는다.
+ * 선언 적합성 하네스 세 벌과 같은 규율을 **연결**에 적용한다: 사실이 오류 없이 사라지는 것을 막는다.
  * 다른 점은 대상이 우리 선언이 아니라 **남의 시스템**이라는 것이고, 그래서 두 규칙이 더 붙는다.
  *
- *  ① **돌리지 않은 프로브는 「실패」가 아니라 「모른다」다.** 실패로 접으면 사람이 그 빨간 칸을
- *     없애려고 무엇이든 하게 되고, 모른다로 접으면 **무엇을 아직 모르는지**가 남는다. 판정
+ *  ① **돌리지 않은 프로브는 「실패」가 아니라 「모른다」다.** 실패로 처리하면 사람이 그 빨간 칸을
+ *     없애려고 무엇이든 하게 되고, 모른다로 처리하면 **무엇을 아직 모르는지**가 남는다. 판정
  *     (`assessStagePath`)이 「모른다」를 달성으로 바꾸지 않으므로 이 구분이 끝까지 살아 있다.
  *  ② **쓰기 프로브는 명시 동의 없이 돌지 않는다.** 이 스위트는 고객의 운영 시스템을 두드린다.
  *     읽기는 기본으로 돌리고, 남의 공장에 명령을 넣는 프로브는 사람이 켜야 돈다 — 켜지 않으면
@@ -71,7 +71,7 @@ export interface ProbeResult {
    *
    * 시뮬레이션 트윈에 라이브 프로브를 들이대면 빨간 칸이 생기는데 그건 결함이 아니다 — 시뮬은 원천에서
    * 받는 것이 없다. 레퍼런스 없이 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없으므로 「못 옮긴 값」도 없다.
-   * 이걸 통과로 접으면 없는 능력을 주장하고, 미측정으로 접으면 영원히 배선을 기다린다.
+   * 이걸 통과로 처리하면 없는 능력을 주장하고, 미측정으로 처리하면 영원히 배선을 기다린다.
    */
   applicable?: boolean
   /** 돌렸을 때의 판정. 돌리지 않았으면 무의미하다. */
@@ -87,7 +87,7 @@ export interface ProbeResult {
 const by = (rs: readonly ProbeResult[], id: ProbeId) => rs.find(r => r.id === id)
 /** 돌렸고 셌으면 그 수, 아니면 `null`(모른다). 실패한 프로브의 수를 0 으로 읽지 않는다. */
 /**
- * 센 값은 **판정과 무관한 사실**이다 — `passed` 를 요구하면 「세어서 0 을 얻었다」가 「모른다」로 접힌다.
+ * 센 값은 **판정과 무관한 사실**이다 — `passed` 를 요구하면 「세어서 0 을 얻었다」가 「모른다」와 구별되지 않는다.
  * 그 구분이 이 하네스의 전부이므로 여기서 잃으면 나머지가 무의미하다. 해당 없음만 `null` 이다.
  */
 const counted = (r: ProbeResult | undefined): number | null =>
@@ -96,9 +96,9 @@ const counted = (r: ProbeResult | undefined): number | null =>
 const countedOrZero = (r: ProbeResult | undefined): number => counted(r) ?? 0
 
 /**
- * 프로브 결과를 **증거**로 접는다.
+ * 프로브 결과를 **증거**로 처리한다.
  *
- * 접는 규칙의 정수: **돌리지 않은 프로브는 `null`** 로 간다. 그러면 판정이 그 단계를 달성으로
+ * 계산 규칙의 정수: **돌리지 않은 프로브는 `null`** 로 간다. 그러면 판정이 그 단계를 달성으로
  * 만들지 않고 `unmeasured` 로 말한다 — 스위트를 절반만 돌리고 초록을 주장할 길이 없다.
  */
 export function foldProbeResults(results: readonly ProbeResult[]): StageEvidence {