@things-factory/headless-twin 10.0.15 → 10.0.18

package/dist-server/engine/ingest-health.d.ts

@@ -12,7 +12,7 @@ export interface IngestWindow {
      * 매핑은 통과했지만 **트윈에 닿지 못한** 수 — 처방은 트윈을 세우는 것이다.
      *
      * ── 왜 거부와 따로 세나 (2026-08-20에 겪었다) ─────────────────────────────
-     * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **조용히 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
+     * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **알리지 않고 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
      * 화면이 「150 들어옴 · 150 통과 · 100%」라고 말하는 동안 150건은 바닥에 버려지고 있었다. 이 기능이
      * 막으려던 바로 그것을 이 기능이 저지른 셈이다.
      *
@@ -72,6 +72,26 @@ 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;
@@ -79,8 +99,8 @@ export interface IngestLedger {
     /**
      * 사유 종류가 상한에 닿았나.
      *
-     * **접힌 종류 수는 세지 않는다** — 그것을 세려면 이미 본 사유를 모두 기억해야 하고, 그 집합이
-     * 바로 이 상한으로 막으려던 무한한 집합이다. 접힌 **건수**는 `byReason[OTHER_REASON].count` 가 답한다.
+     * **모은 종류 수는 세지 않는다** — 그것을 세려면 이미 본 사유를 모두 기억해야 하고, 그 집합이
+     * 바로 이 상한으로 막으려던 무한한 집합이다. 모은 **건수**는 `byReason[OTHER_REASON].count` 가 답한다.
      */
     reasonsCapped: boolean;
     /** 표본을 이미 뜬 사유들 — 같은 사유를 다시 직렬화하지 않기 위한 색인(O(1) 조회). */
@@ -94,12 +114,12 @@ export interface IngestLedger {
     /**
      * **원본에 닿지 못한 사실** (2026-08-23) — 「받은 것이 없다」와 **다른 사실**이다.
      *
-     * ── 무엇이 조용했나 ─────────────────────────────────────────────────────────
+     * ── 무엇이 아무 신호도 내지 않았나 ─────────────────────────────────────────────────────────
      * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
      * `recordIngest` 는 `onRecords` 가 불릴 때만 도달하고, 읽기가 실패하면 그 문에 오지 않는다.
      * `TwinReference.lastError` 는 마스터 동기·접속 시험에만 적힌다.
      *
-     * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「원본이 조용하다」와 구별되지
+     * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「연결된 시스템에서 들어온 것이 없다」와 구별되지
      * 않는다.** 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
      *
      * ── 왜 「몇 번」과 「언제부터」를 함께 두나 ──────────────────────────────────
@@ -108,6 +128,17 @@ export interface IngestLedger {
      *
      * 성공하면 지운다 — 고쳐진 단절이 화면에 남아 있으면 그것도 거짓이다.
      */
+    /**
+     * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다.
+     *
+     * 실패 기록(`readFailure`)은 돌아오면 지워진다. 그것만 지우면 「끊긴 적이 있었다」가 화면에서
+     * 사라지므로, 돌아온 사실을 따로 남긴다.
+     */
+    lastRecovery?: {
+        atMs: number;
+        afterFailures: number;
+        downMs: number;
+    };
     readFailure?: {
         /** 연속 실패 수 — 성공 한 번에 0 으로 돌아간다. */
         consecutive: number;
@@ -119,6 +150,8 @@ export interface IngestLedger {
         reason: string;
         /** 어느 흐름에서 났나(어댑터가 말해 주면). 원본마다 흐름이 다르므로 열려 있다. */
         stream?: string;
+        /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+        nextRetryMs?: number;
     };
     /**
      * **읽었는데 창을 넘길 수 없다** (2026-08-24) — 위와 **다른 사실**이다.
@@ -152,7 +185,7 @@ export interface IngestLedger {
      *   `unhandled`   리듀서가 **받았는데** 담을 자리를 몰랐다
      *   여기          커넥터가 **보지만 일부러 보내지 않았다** — 이유와 함께
      *
-     * 둘 다 「사실이 조용히 사라지지 않게」 세는 것이고, 이유가 다르므로 자리도 다르다.
+     * 둘 다 「사실이 오류 없이 사라지지 않게」 세는 것이고, 이유가 다르므로 자리도 다르다.
      *
      * 이유를 **문자열로 받는다**: 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 그 목록을 닫으면 새 원본을
      * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율).
@@ -181,12 +214,30 @@ export interface IngestLedger {
  * 연속 실패의 시작 시각을 지키는 것이 이 함수의 요점이다: 매번 새로 적으면 「20분째 못 읽는다」를
  * 말할 수 없고, 화면은 늘 「방금 실패했다」만 보게 된다.
  */
-export declare function recordReadFailure(ledger: IngestLedger, reason: string, nowMs: number, stream?: string): void;
+export declare function recordReadFailure(ledger: IngestLedger, reason: string, nowMs: number, stream?: string, 
+/**
+ * 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰으면 그 값을 준다 (2026-08-27).
+ *
+ * 이것이 없으면 화면이 「닿지 못하고 있다」까지만 말하고, 사람은 **언제 다시 시도하는지** 알 수
+ * 없다. 그러면 기다려야 하는지 손을 써야 하는지 판단하지 못한다.
+ *
+ * **연달아 횟수와 시작 시각은 커넥터가 보내지 않는다** — 이 함수가 이미 센다. 두 곳에서 세면
+ * 갈라지고, 갈라지면 어느 쪽이 사실인지 알 수 없다.
+ */
+nextRetryMs?: number): void;
+/**
+ * **끊겼다가 돌아왔다** — 그 사실을 남긴다 (2026-08-27).
+ *
+ * 실패 기록만 지우면 「끊긴 적이 있었다」가 화면에서 사라진다. 그러면 밤새 두 시간 끊겼던 연결과 한
+ * 번도 끊기지 않은 연결이 아침에 똑같이 보인다. 몇 번 실패한 뒤에 돌아왔는지, 얼마나 끊겼는지를 함께
+ * 남긴다.
+ */
+export declare function recordRecovered(ledger: IngestLedger, afterFailures: number, downMs: number, nowMs: number): void;
 /**
  * 읽기가 성공했다 — 단절 기록을 지운다.
  *
  * **빈 읽기도 성공이다**: 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이다. 그 둘을 같게 두면
- * 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+ * 들어온 것이 없는 연결이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
  */
 export declare function clearReadFailure(ledger: IngestLedger): void;
 /**
@@ -206,6 +257,15 @@ export declare function recordCursorStall(ledger: IngestLedger, reason: string,
  * 이유가 같고 수가 달라지면 **마지막 수로 덮는다**: 이것은 누적 사건이 아니라 **지금 세우지 않은 것의
  * 수**다. 주기마다 8건이면 8이고, 더해서 800이 되면 거짓이다.
  */
+/**
+ * 어떤 길로 몇 건이 들어왔나 — 경로 이름은 부르는 쪽이 정한다.
+ *
+ * 이름을 자유 문자열로 두는 이유: 길이 늘어난다(지금은 물어보기·시나리오·부하 도구, 다음은 웹훅).
+ * 열거로 못 박으면 새 길이 생길 때 이 파일을 함께 고쳐야 하고, 잊으면 그 길이 통계에서 사라진다.
+ */
+export declare function recordIngestSource(ledger: IngestLedger, source: string, count: number, nowMs: number): void;
+/** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+export declare function recordDuplicates(ledger: IngestLedger, count: number, nowMs: number): void;
 export declare function recordWithheld(ledger: IngestLedger, reason: string, count: number, nowMs: number): void;
 /** 창을 넘겼으면 지운다 — 풀린 정체가 화면에 남아 있으면 그것도 거짓이다. */
 export declare function clearCursorStall(ledger: IngestLedger): void;
@@ -227,7 +287,7 @@ export declare const TREND_LIMIT = 36;
  * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
  * 미미한 오버헤드가 아니라 누수다.
  *
- * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 접었는지 함께 낸다**(조용히 자르지 않는다).
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 모았는지 함께 낸다**(알리지 않고 자르지 않는다).
  * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
  */
 export declare const REASON_LIMIT = 30;
@@ -326,6 +386,13 @@ export declare function syncVerdictOf(args: {
     nowMs?: number;
     /** 마지막으로 **버려진** 시각. 한 번도 없으면 `-1`. */
     lastUndeliveredAtMs?: number;
+    /**
+     * 지금까지 제시된 누적 수 — **「받고 있는 중」과 「오는 것이 없다」를 가르는 사실**이다.
+     *
+     * 닿은 시각(`lastAtMs`)으로는 가를 수 없다: 빈 읽기도 닿은 것이므로 그 시각이 선다. 창이 아직 닫히지
+     * 않았을 때 이 수가 0 이면 오는 것이 없는 것이고, 0 이 아니면 받고 있는 중이다.
+     */
+    offeredTotal?: number;
     threshold?: number;
 }): SyncVerdict;
 export interface IngestWindowView {
@@ -385,7 +452,7 @@ export interface IngestHealthView {
      *
      * 커서 정체(`cursorStall`)와 **섞이지 않는다**: 이쪽은 기다리면 풀리고 그쪽은 기다려도 안 풀린다.
      *
-     * 「유입 없음」과 **다른 판정**이다: 유입 없음은 원본이 조용한 것일 수 있고, 이것은 우리가 묻지도
+     * 「유입 없음」과 **다른 판정**이다: 유입 없음은 연결된 시스템에서 들어온 것이 없는 것일 수 있고, 이것은 우리가 묻지도
      * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
      * 있는지가 그 차이다.
      */
@@ -396,6 +463,19 @@ export interface IngestHealthView {
         lastAt: string;
         reason: string;
         stream?: string;
+        /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+        nextRetryMs?: number;
+    };
+    /**
+     * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다 (2026-08-27).
+     *
+     * `readFailure` 는 돌아오면 사라진다. 이 칸이 없으면 밤새 끊겼던 연결과 한 번도 끊기지 않은 연결이
+     * 아침에 똑같이 보인다.
+     */
+    lastRecovery?: {
+        at: string;
+        afterFailures: number;
+        downMs: number;
     };
 }
 /**

package/dist-server/engine/ingest-health.js

@@ -5,12 +5,12 @@
  * ── 한 질문 ─────────────────────────────────────────────────────────────────
  * 화면에서 값이 변하지 않을 때 원인이 넷인데, 지금까지 **넷이 똑같이 보였다.**
  *   ① 피드가 붙지 않았다  ② 붙었는데 아무것도 오지 않는다
- *   ③ 오는데 전부 거부된다  ④ 정상인데 현장이 조용하다
+ *   ③ 오는데 전부 거부된다  ④ 정상인데 현장이 들어온 것이 없다
  * ③은 특히 나쁘다 — 커넥터의 매핑이 한 글자 틀리면 트윈은 「빈 공장」이 되고, 그 사실이 서버 로그
  * 한 줄에만 남았다. 현장에 나간 사람은 로그를 뒤져야 했다.
  *
  * ── 왜 저널로는 답할 수 없나 ────────────────────────────────────────────────
- * **거부된 것은 저널에 없다** — 거부의 뜻이 그것이다. 저널을 접으면 통과한 쪽만 나온다. 거부의 추이는
+ * **거부된 것은 저널에 없다** — 거부의 뜻이 그것이다. 저널을 계산하면 통과한 쪽만 나온다. 거부의 추이는
  * 세는 자리를 따로 두어야 나온다. 이 장부가 그 자리다.
  *
  * ── 왜 건마다 저장하지 않나 ─────────────────────────────────────────────────
@@ -24,14 +24,17 @@
  * ── 지키는 규율 넷 ──────────────────────────────────────────────────────────
  *  ① **닫힌 창만 「최근」이다** — 채우는 중인 창은 과소 집계다(부하 계기판에서 겪었다).
  *  ② **0 과 「없음」을 가른다** — 안 받은 것은 `null`, 받았지만 거부 0 은 `0`.
- *  ③ **조용히 자르지 않는다** — 표본·추이 상한에서 밀려난 수를 함께 낸다.
+ *  ③ **알리지 않고 자르지 않는다** — 표본·추이 상한에서 밀려난 수를 함께 낸다.
  *  ④ **통과율에 1 을 함부로 쓰지 않는다** — 1,000건 중 1건 거부는 0.999 다.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HEALTHY_ACCEPTED_RATIO = exports.RECORD_MAX = exports.SAMPLE_LIMIT = exports.OTHER_REASON = exports.REASON_LIMIT = exports.TREND_LIMIT = exports.STALE_AFTER_MS = exports.INGEST_WINDOW_MS = void 0;
 exports.recordReadFailure = recordReadFailure;
+exports.recordRecovered = recordRecovered;
 exports.clearReadFailure = clearReadFailure;
 exports.recordCursorStall = recordCursorStall;
+exports.recordIngestSource = recordIngestSource;
+exports.recordDuplicates = recordDuplicates;
 exports.recordWithheld = recordWithheld;
 exports.clearCursorStall = clearCursorStall;
 exports.newIngestLedger = newIngestLedger;
@@ -47,21 +50,44 @@ exports.ingestHealth = ingestHealth;
  * 연속 실패의 시작 시각을 지키는 것이 이 함수의 요점이다: 매번 새로 적으면 「20분째 못 읽는다」를
  * 말할 수 없고, 화면은 늘 「방금 실패했다」만 보게 된다.
  */
-function recordReadFailure(ledger, reason, nowMs, stream) {
+function recordReadFailure(ledger, reason, nowMs, stream, 
+/**
+ * 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰으면 그 값을 준다 (2026-08-27).
+ *
+ * 이것이 없으면 화면이 「닿지 못하고 있다」까지만 말하고, 사람은 **언제 다시 시도하는지** 알 수
+ * 없다. 그러면 기다려야 하는지 손을 써야 하는지 판단하지 못한다.
+ *
+ * **연달아 횟수와 시작 시각은 커넥터가 보내지 않는다** — 이 함수가 이미 센다. 두 곳에서 세면
+ * 갈라지고, 갈라지면 어느 쪽이 사실인지 알 수 없다.
+ */
+nextRetryMs) {
     const prev = ledger.readFailure;
     ledger.readFailure = {
         consecutive: (prev?.consecutive ?? 0) + 1,
         sinceMs: prev?.sinceMs ?? nowMs,
         lastAtMs: nowMs,
         reason,
-        ...(stream ? { stream } : {})
+        ...(stream ? { stream } : {}),
+        ...(Number.isFinite(nextRetryMs) && nextRetryMs > 0 ? { nextRetryMs: nextRetryMs } : {})
     };
 }
+/**
+ * **끊겼다가 돌아왔다** — 그 사실을 남긴다 (2026-08-27).
+ *
+ * 실패 기록만 지우면 「끊긴 적이 있었다」가 화면에서 사라진다. 그러면 밤새 두 시간 끊겼던 연결과 한
+ * 번도 끊기지 않은 연결이 아침에 똑같이 보인다. 몇 번 실패한 뒤에 돌아왔는지, 얼마나 끊겼는지를 함께
+ * 남긴다.
+ */
+function recordRecovered(ledger, afterFailures, downMs, nowMs) {
+    if (ledger.readFailure)
+        delete ledger.readFailure;
+    ledger.lastRecovery = { atMs: nowMs, afterFailures, downMs };
+}
 /**
  * 읽기가 성공했다 — 단절 기록을 지운다.
  *
  * **빈 읽기도 성공이다**: 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이다. 그 둘을 같게 두면
- * 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+ * 들어온 것이 없는 연결이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
  */
 function clearReadFailure(ledger) {
     if (ledger.readFailure)
@@ -93,6 +119,27 @@ function recordCursorStall(ledger, reason, nowMs, stream) {
  * 이유가 같고 수가 달라지면 **마지막 수로 덮는다**: 이것은 누적 사건이 아니라 **지금 세우지 않은 것의
  * 수**다. 주기마다 8건이면 8이고, 더해서 800이 되면 거짓이다.
  */
+/**
+ * 어떤 길로 몇 건이 들어왔나 — 경로 이름은 부르는 쪽이 정한다.
+ *
+ * 이름을 자유 문자열로 두는 이유: 길이 늘어난다(지금은 물어보기·시나리오·부하 도구, 다음은 웹훅).
+ * 열거로 못 박으면 새 길이 생길 때 이 파일을 함께 고쳐야 하고, 잊으면 그 길이 통계에서 사라진다.
+ */
+function recordIngestSource(ledger, source, count, nowMs) {
+    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;
+}
+/** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+function recordDuplicates(ledger, count, nowMs) {
+    if (count <= 0)
+        return;
+    ledger.duplicates += count;
+    ledger.lastDuplicateAtMs = nowMs;
+}
 function recordWithheld(ledger, reason, count, nowMs) {
     if (!reason || !(count > 0))
         return;
@@ -128,7 +175,7 @@ exports.TREND_LIMIT = 36;
  * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
  * 미미한 오버헤드가 아니라 누수다.
  *
- * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 접었는지 함께 낸다**(조용히 자르지 않는다).
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 모았는지 함께 낸다**(알리지 않고 자르지 않는다).
  * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
  */
 exports.REASON_LIMIT = 30;
@@ -164,6 +211,9 @@ function newIngestLedger() {
         flushes: 0,
         lastWriteAtMs: -1,
         lastUndeliveredAtMs: -1,
+        bySource: {},
+        duplicates: 0,
+        lastDuplicateAtMs: -1,
         byReason: {},
         reasonsCapped: false,
         sampledReasons: new Set(),
@@ -252,7 +302,7 @@ undelivered = 0) {
     for (const it of items) {
         const raw = reasonKey(it?.errors);
         const known = raw in ledger.byReason;
-        /* 사유 종류 상한 — 넘치면 한 칸으로 접고, **닿았다는 사실**을 표시한다. */
+        /* 사유 종류 상한 — 넘치면 한 칸으로 모으고, **닿았다는 사실**을 표시한다. */
         let key = raw;
         if (!known && Object.keys(ledger.byReason).length >= exports.REASON_LIMIT) {
             key = exports.OTHER_REASON;
@@ -308,14 +358,14 @@ function recordJournalWrite(ledger, rows, nowMs, onClosed) {
     /*
      * **`lastAtMs` 는 건드리지 않는다.** 그 값은 「마지막 유입」이고, 끊긴 피드를 가려내는 근거다. 쓰기로
      * 갱신하면 라이브 트윈은 유입이 끊겨도 틱이 만든 델타를 계속 적으므로 **영원히 「방금 받았다」**가 되고,
-     * 「오래 끊긴 피드에 옛 창으로 초록을 내지 않는다」가 조용히 무력해진다. 축을 따로 든다.
+     * 「오래 끊긴 피드에 옛 창으로 초록을 내지 않는다」가 오류 하나 없이 무력해진다. 축을 따로 든다.
      */
     ledger.lastWriteAtMs = nowMs;
 }
 function syncVerdictOf(args) {
     /*
      * ── 버려지고 있는 것이 가장 먼저다 ────────────────────────────────────────
-     * 트윈이 멈추면 피드는 남아 계속 레코드를 나르고, 커널은 그것을 조용히 버린다. 그 상태를 「해당 없음」
+     * 트윈이 멈추면 피드는 남아 계속 레코드를 나르고, 커널은 그것을 알리지 않고 버린다. 그 상태를 「해당 없음」
      * 이라 부르면 **사실이 사라지는 동안 화면이 안심시킨다** — 실제로 그렇게 떴다(멈춘 트윈 옆에 「150
      * 통과 · 100%」). 그래서 시뮬·멈춤 판정보다 먼저 본다.
      *
@@ -353,8 +403,29 @@ function syncVerdictOf(args) {
         if (args.nowMs - args.lastAtMs > exports.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;
@@ -394,6 +465,8 @@ function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RA
         recent: recentRaw,
         lastAtMs: ledger?.lastAtMs ?? -1,
         lastUndeliveredAtMs: ledger?.lastUndeliveredAtMs ?? -1,
+        /* 창이 닫히지 않았을 때 「받는 중」과 「오는 것이 없다」를 가르는 사실. */
+        offeredTotal: ledger?.offered ?? 0,
         nowMs,
         threshold
     });
@@ -429,12 +502,22 @@ function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RA
                         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: {
@@ -448,7 +531,7 @@ function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RA
                 : {}),
             /*
              * **세우지 않은 것도 낸다 — 양쪽 갈래에서.** 유입이 한 건도 없는 장부에서도 이 사실은 실재한다
-             * (원본이 말하는데 전부 안 받는 경우가 있다). 여기서 떨어뜨리면 바로 그 상황에서 조용해진다.
+             * (원본이 말하는데 전부 안 받는 경우가 있다). 여기서 떨어뜨리면 바로 그 상황에서 들어온 것이 없어진다.
              */
             ...(ledger?.withheld?.length
                 ? {
@@ -479,6 +562,21 @@ function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RA
                 }))
             }
             : {}),
+        /*
+         * **어떤 길로 들어오고 있나** — 화면이 「이 트윈은 무엇을 통해 값을 받나」를 말할 수 있게.
+         * 비어 있으면 칸을 만들지 않는다: 아직 아무것도 안 받은 트윈과 「길이 없다」를 구별한다.
+         */
+        ...(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,
@@ -505,7 +603,18 @@ function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RA
                     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
                 }
             }
             : {}),