@things-factory/ingest 10.1.4

package/dist-server/ingest-health.js

@@ -0,0 +1,671 @@
+"use strict";
+/*
+ * 동기화 건강 — **이 트윈이 현장과 맞춰지고 있나.** 순수(import 없음).
+ *
+ * ── 한 질문 ─────────────────────────────────────────────────────────────────
+ * 화면에서 값이 변하지 않을 때 원인이 넷인데, 지금까지 **넷이 똑같이 보였다.**
+ *   ① 피드가 붙지 않았다  ② 붙었는데 아무것도 오지 않는다
+ *   ③ 오는데 전부 거부된다  ④ 정상인데 현장이 들어온 것이 없다
+ * ③은 특히 나쁘다 — 커넥터의 매핑이 한 글자 틀리면 트윈은 「빈 공장」이 되고, 그 사실이 서버 로그
+ * 한 줄에만 남았다. 현장에 나간 사람은 로그를 뒤져야 했다.
+ *
+ * ── 왜 저널로는 답할 수 없나 ────────────────────────────────────────────────
+ * **거부된 것은 저널에 없다** — 거부의 뜻이 그것이다. 저널을 계산하면 통과한 쪽만 나온다. 거부의 추이는
+ * 세는 자리를 따로 두어야 나온다. 이 장부가 그 자리다.
+ *
+ * ── 왜 건마다 저장하지 않나 ─────────────────────────────────────────────────
+ * 라이브 계측은 초당 여러 건이다. 거부마다 행을 쓰면 그 자체가 부하가 된다(`reference-live.ts` 가
+ * 이미 그렇게 적어 두었다). 그리고 이 패키지는 **`integration-base` 를 알지 않는다**(이식성 규약) —
+ * 시나리오 경로가 쓰는 dead-letter 를 여기서 부를 수 없다. 그래서 **집계한다.**
+ *
+ * ── 통과와 거부를 함께 센다 ─────────────────────────────────────────────────
+ * 거부만 그리면 「유입 없음」과 「정상」이 **둘 다 거부 0** 으로 같아 보인다. 제시 수가 있어야 갈린다.
+ *
+ * ── 지키는 규율 넷 ──────────────────────────────────────────────────────────
+ *  ① **닫힌 창만 「최근」이다** — 채우는 중인 창은 과소 집계다(부하 계기판에서 겪었다).
+ *  ② **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.recordVocabulary = recordVocabulary;
+exports.recordDuplicates = recordDuplicates;
+exports.recordWithheld = recordWithheld;
+exports.clearCursorStall = clearCursorStall;
+exports.newIngestLedger = newIngestLedger;
+exports.rollIngestWindow = rollIngestWindow;
+exports.reasonKey = reasonKey;
+exports.recordIngest = recordIngest;
+exports.recordJournalWrite = recordJournalWrite;
+exports.syncVerdictOf = syncVerdictOf;
+exports.ingestHealth = ingestHealth;
+/**
+ * 읽기 실패를 장부에 적는다 — **받은 것이 없는 것과 가른다.**
+ *
+ * 연속 실패의 시작 시각을 지키는 것이 이 함수의 요점이다: 매번 새로 적으면 「20분째 못 읽는다」를
+ * 말할 수 없고, 화면은 늘 「방금 실패했다」만 보게 된다.
+ */
+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 } : {}),
+        ...(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)
+        delete ledger.readFailure;
+}
+/**
+ * 커서 정체를 장부에 적는다 — **닿지 못한 것과 가른다.**
+ *
+ * `recordReadFailure` 와 같은 모양이지만 **다른 칸**이다. 한 주기가 두 이유로 실패할 수는 없으므로
+ * (먼저 닿아야 읽는다) 둘이 동시에 서지 않는다 — 그래서 화면은 둘 중 하나만 보게 되고, 그 하나가
+ * 조치를 정한다.
+ */
+function recordCursorStall(ledger, reason, nowMs, stream) {
+    const prev = ledger.cursorStall;
+    ledger.cursorStall = {
+        consecutive: (prev?.consecutive ?? 0) + 1,
+        sinceMs: prev?.sinceMs ?? nowMs,
+        lastAtMs: nowMs,
+        reason,
+        ...(stream ? { 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;
+}
+/** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+/**
+ * **저널에 안 간 어휘 요소를 센다** — 없어진 것이 아니라 저널로 가지 않는 것이다.
+ *
+ * 어휘(로트 번호·소비기한 등)는 시각축이 없어 일부러 저널로 안 간다. 그런데 그 수를 빼 주는 자리가
+ * 없으면 「보낸 것 − 앉은 것」이 안 맞고, 그 차이를 **사라진 것으로 읽게 된다.**
+ *
+ * 창을 굴리지 않는다 — 부르는 쪽(`recordIngest`)이 이미 굴린 뒤에 부른다. 여기서 또 굴리면 한
+ * 유입이 두 창에 걸친다.
+ */
+function recordVocabulary(ledger, count) {
+    if (!Number.isFinite(count) || count <= 0)
+        return;
+    ledger.vocabulary += count;
+    ledger.window.vocabulary += count;
+}
+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;
+    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 });
+}
+/** 창을 넘겼으면 지운다 — 풀린 정체가 화면에 남아 있으면 그것도 거짓이다. */
+function clearCursorStall(ledger) {
+    if (ledger.cursorStall)
+        delete ledger.cursorStall;
+}
+/** 창 길이 — 10분. 부하 계기판(10초)과 다른 값이라 이름을 따로 둔다(같은 이름이면 섞인다). */
+exports.INGEST_WINDOW_MS = 600_000;
+/**
+ * 이만큼 아무것도 오지 않으면 「유입 없음」이라 말한다.
+ *
+ * 창 하나와 같게 둔다 — 한 창을 통째로 비운 것은 실제로 「그 구간에 아무것도 오지 않았다」이고, 추이의
+ * 그 자리도 비게 된다. 그림과 알약이 같은 말을 하게 하려면 같은 길이여야 한다.
+ */
+exports.STALE_AFTER_MS = exports.INGEST_WINDOW_MS;
+/** 추이 보관 창 수 — 36창 × 10분 = 6시간. 「고친 것이 먹혔나」를 보기에 충분하고 메모리는 숫자 넷×36 이다. */
+exports.TREND_LIMIT = 36;
+/**
+ * 사유 종류 상한.
+ *
+ * **없으면 메모리가 끝없이 자란다.** 사유 문구에 레코드마다 다른 값이 섞이는 커넥터가 하나만 있어도
+ * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
+ * 미미한 오버헤드가 아니라 누수다.
+ *
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 모았는지 함께 낸다**(알리지 않고 자르지 않는다).
+ * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
+ */
+exports.REASON_LIMIT = 30;
+/** 상한을 넘긴 사유들이 모이는 칸. */
+exports.OTHER_REASON = '(other reasons)';
+/**
+ * 표본 상한 — **사유마다 한 건**만 든다.
+ *
+ * 같은 사유 20건보다 **서로 다른 사유 1건씩**이 매핑을 고치는 데 유용하다. 그리고 이 규칙이 성능을
+ * 지킨다: 그 사유의 표본이 이미 있으면 `JSON.stringify` 를 **아예 하지 않는다.** 실측(레코드 241바이트)
+ * 으로 건당 0.24µs 인데, 초당 1만 건이 전부 거부되면 9,980건은 만들자마자 버려지는 문자열이었다 —
+ * CPU 는 감당되지만 GC 압박이 이벤트 루프로 돌아온다.
+ */
+exports.SAMPLE_LIMIT = exports.REASON_LIMIT;
+/** 표본 하나의 직렬화 상한(문자). */
+exports.RECORD_MAX = 2000;
+/**
+ * 매핑이 막고 있다고 볼 통과율 문턱.
+ *
+ * 값과 함께 내보낸다 — 화면이 「95% 미만이라 매핑 문제로 봤다」를 말할 수 있게. 숨긴 문턱은 사람이
+ * 판정을 믿지 못한다.
+ */
+exports.HEALTHY_ACCEPTED_RATIO = 0.95;
+function newIngestLedger() {
+    return {
+        window: { startMs: -1, endMs: -1, offered: 0, rejected: 0, vocabulary: 0, undelivered: 0, rows: 0, flushes: 0 },
+        trend: [],
+        trendDropped: 0,
+        offered: 0,
+        rejected: 0,
+        undelivered: 0,
+        rows: 0,
+        flushes: 0,
+        lastWriteAtMs: -1,
+        lastUndeliveredAtMs: -1,
+        bySource: {},
+        duplicates: 0,
+        vocabulary: 0,
+        lastDuplicateAtMs: -1,
+        byReason: {},
+        reasonsCapped: false,
+        sampledReasons: new Set(),
+        samples: [],
+        sampleDropped: 0,
+        lastAtMs: -1
+    };
+}
+/**
+ * 창이 다 찼으면 닫아 추이에 넣고 새로 연다. **닫힌 창만 「최근」으로 읽는다.**
+ *
+ * ── 영속이 붙는 유일한 자리 ────────────────────────────────────────────────
+ * 닫힌 창 하나가 영속의 단위다(숫자 넷 + 구간). `onClosed` 를 받는 이유는 **이 함수가 창이 닫히는
+ * 유일한 지점**이기 때문이다 — 여기 한 곳에 붙이면 기록 경로가 갈리지 않는다.
+ *
+ * 왜 건마다가 아니라 창마다인가: 거부마다 행을 쓰면 초당 1만 행이고 그 부하가 이벤트 루프로 돌아온다.
+ * 창마다면 트윈 1,000개에 하루 14.4만 행(약 14MB)이다.
+ *
+ * `onClosed` 는 **오류를 내지 않아야 한다**(호출부가 감싼다) — 영속이 실패해도 장부는 계속 굴러야 한다.
+ * 영속을 지키는 것과 관측을 지키는 것은 다른 일이고, 뒤엣것이 앞엣것 때문에 멈추면 안 된다.
+ */
+function rollIngestWindow(ledger, nowMs, windowMs = exports.INGEST_WINDOW_MS, onClosed) {
+    if (ledger.window.startMs < 0) {
+        ledger.window.startMs = nowMs;
+        return;
+    }
+    if (nowMs - ledger.window.startMs < windowMs)
+        return;
+    const closed = { ...ledger.window, endMs: nowMs };
+    ledger.trend.push(closed);
+    ledger.window = { startMs: nowMs, endMs: -1, offered: 0, rejected: 0, vocabulary: 0, undelivered: 0, rows: 0, flushes: 0 };
+    if (ledger.trend.length > exports.TREND_LIMIT) {
+        const drop = ledger.trend.length - exports.TREND_LIMIT;
+        ledger.trend.splice(0, drop);
+        ledger.trendDropped += drop;
+    }
+    /* 영속은 관측을 막지 않는다 — 터져도 장부는 이미 갱신됐다. */
+    if (onClosed) {
+        try {
+            onClosed(closed);
+        }
+        catch {
+            /* 호출부가 알린다. 여기서 삼키는 것은 **장부의 진행**을 지키기 위해서다. */
+        }
+    }
+}
+/** 사유 묶음의 키. 사유가 여럿이면 한 줄로 잇고, 없으면 지어내지 않고 `unknown`. */
+function reasonKey(errors) {
+    const list = (errors ?? []).map(e => String(e).trim()).filter(Boolean);
+    return list.length ? list.join(' · ') : 'unknown';
+}
+function safeJson(v) {
+    try {
+        const s = JSON.stringify(v);
+        return s === undefined ? String(v) : s;
+    }
+    catch {
+        return '(serialization failed)'; /* 순환 참조 등 — 모양을 못 보여 주는 것도 사실이다 */
+    }
+}
+/**
+ * 한 번의 인제스트 결과를 적는다.
+ *
+ * `offered` 를 함께 받는 이유: 통과율을 **서로 다른 두 계수기**에서 나눠 계산하면 분모와 분자가 다른
+ * 것을 세게 된다. 둘을 한자리에서 본 수를 그대로 적는다.
+ */
+function recordIngest(ledger, offered, rejected, nowMs, onClosed, 
+/** 매핑은 통과했지만 트윈에 닿지 못한 수 — 「통과」로 세면 화면이 거짓을 말한다. */
+undelivered = 0) {
+    if (!Number.isFinite(offered) || offered < 0)
+        return;
+    rollIngestWindow(ledger, nowMs, exports.INGEST_WINDOW_MS, onClosed);
+    ledger.offered += offered;
+    ledger.window.offered += offered;
+    ledger.lastAtMs = nowMs;
+    if (Number.isFinite(undelivered) && undelivered > 0) {
+        ledger.undelivered += undelivered;
+        ledger.window.undelivered += undelivered;
+        ledger.lastUndeliveredAtMs = nowMs;
+    }
+    const items = rejected ?? [];
+    if (!items.length)
+        return;
+    ledger.rejected += items.length;
+    ledger.window.rejected += items.length;
+    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;
+            ledger.reasonsCapped = true;
+        }
+        const seen = ledger.byReason[key];
+        ledger.byReason[key] = { count: (seen?.count ?? 0) + 1, lastAtMs: nowMs };
+        /*
+         * **표본은 사유마다 하나.** 이미 그 사유의 표본이 있으면 직렬화를 아예 하지 않는다 — 초당 1만 건이
+         * 전부 거부될 때 만들자마자 버려지는 문자열을 만들지 않기 위해서다(실측: 건당 0.24µs, GC 압박).
+         */
+        if (ledger.sampledReasons.has(key)) {
+            ledger.sampleDropped += 1;
+            continue;
+        }
+        const text = safeJson(it?.record);
+        const truncated = text.length > exports.RECORD_MAX;
+        ledger.samples.push({
+            atMs: nowMs,
+            errors: key === exports.OTHER_REASON ? [exports.OTHER_REASON] : it?.errors?.length ? [...it.errors] : ['unknown'],
+            record: truncated ? text.slice(0, exports.RECORD_MAX) : text,
+            ...(truncated ? { recordTruncated: true } : {})
+        });
+        ledger.sampledReasons.add(key);
+        if (ledger.samples.length > exports.SAMPLE_LIMIT) {
+            const gone = ledger.samples.splice(0, ledger.samples.length - exports.SAMPLE_LIMIT);
+            /* 밀려난 표본의 사유는 색인에서도 빼야 다음에 다시 뜰 수 있다(안 빼면 그 사유는 영원히 표본 없음). */
+            for (const g of gone)
+                ledger.sampledReasons.delete(reasonKey(g.errors));
+            ledger.sampleDropped += gone.length;
+        }
+    }
+}
+/**
+ * 저널에 **적은 것**을 기록한다 — 창을 넘길 때가 되었으면 넘기고, 행·왕복을 더한다.
+ *
+ * ── 왜 유입과 같은 창인가 ───────────────────────────────────────────────────
+ * 새 장부를 만들지 않는다. 이 창은 「닫힌 창만 최근」·「0 과 없음을 가른다」·「잘린 것을 세어 드러낸다」를
+ * 이미 지키고, 닫힐 때 영속까지 된다. 같은 규율을 두 벌 만들면 한쪽만 고쳐진다.
+ *
+ * ── 유입이 없어도 창은 넘어간다 ────────────────────────────────────────────
+ * 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적는다. 창이 **유입에서만** 넘어간다면 그 트윈은 추이에
+ * 영원히 나타나지 않는다 — 그래서 쓰기도 창을 넘긴다.
+ */
+function recordJournalWrite(ledger, rows, nowMs, onClosed) {
+    if (!Number.isFinite(rows) || rows <= 0)
+        return;
+    rollIngestWindow(ledger, nowMs, exports.INGEST_WINDOW_MS, onClosed);
+    ledger.rows += rows;
+    ledger.flushes += 1;
+    ledger.window.rows += rows;
+    ledger.window.flushes += 1;
+    /*
+     * **`lastAtMs` 는 건드리지 않는다.** 그 값은 「마지막 유입」이고, 끊긴 피드를 가려내는 근거다. 쓰기로
+     * 갱신하면 라이브 트윈은 유입이 끊겨도 틱이 만든 델타를 계속 적으므로 **영원히 「방금 받았다」**가 되고,
+     * 「오래 끊긴 피드에 옛 창으로 초록을 내지 않는다」가 오류 하나 없이 무력해진다. 축을 따로 든다.
+     */
+    ledger.lastWriteAtMs = nowMs;
+}
+function syncVerdictOf(args) {
+    /*
+     * ── 버려지고 있는 것이 가장 먼저다 ────────────────────────────────────────
+     * 트윈이 멈추면 피드는 남아 계속 레코드를 나르고, 커널은 그것을 알리지 않고 버린다. 그 상태를 「해당 없음」
+     * 이라 부르면 **사실이 사라지는 동안 화면이 안심시킨다** — 실제로 그렇게 떴다(멈춘 트윈 옆에 「150
+     * 통과 · 100%」). 그래서 시뮬·멈춤 판정보다 먼저 본다.
+     *
+     * 시뮬 트윈에는 이 값이 서지 않는다(먹이는 피드가 없으므로 미전달도 없다). 그래서 이 순서가 시뮬에
+     * 거짓 경보를 주지 않는다.
+     */
+    if (typeof args.lastUndeliveredAtMs === 'number' &&
+        args.lastUndeliveredAtMs >= 0 &&
+        typeof args.nowMs === 'number' &&
+        args.nowMs - args.lastUndeliveredAtMs <= exports.STALE_AFTER_MS) {
+        return 'twin-not-running';
+    }
+    if (args.feedState === 'not-applicable')
+        return 'not-applicable';
+    if (args.feedState === 'detached')
+        return 'not-connected';
+    /*
+     * ── 끊긴 피드가 초록으로 남지 않게 ────────────────────────────────────────
+     * 창은 **다음 유입이 있을 때** 닫힌다. 그래서 유입이 멈추면 창도 멈추고, 「최근 창」은 멈추기 직전의
+     * 건강했던 창으로 남는다. 그 창만 보고 판정하면 **어제 죽은 피드가 오늘도 「동기화 중」**이다. 이
+     * 기능이 있는 이유가 바로 그 상태를 드러내는 것이므로, 그때 초록을 내면 목적을 놓친다.
+     *
+     * 그래서 창과 별개로 **지금까지의 침묵**을 먼저 본다. 한 창을 통째로 아무것도 받지 않았으면 그것은
+     * 「유입 없음」이다 — 실제로 그 구간의 창은 비어 있게 된다.
+     *
+     * 이 판단을 서버에 두는 이유: 소비처가 여럿(목록·연결 상세·앞으로 생길 것)이고, 화면마다 다시
+     * 판단하면 규칙이 갈라져 어떤 화면은 초록, 어떤 화면은 경고를 말한다.
+     *
+     * 한계 — 한 창(10분)보다 **느리게 긷는 원천**은 긷는 사이에 「유입 없음」으로 보인다. 장부는 원천의
+     * 주기를 모르므로 이보다 정확히 답할 수 없다. 주기를 알게 되면 그 값으로 견주는 것이 맞다.
+     */
+    /*
+     * 견줄 길이는 **원천이 선언한 값이 있으면 그것**이다(§`expectedSilenceMs`). 없으면 창 하나 —
+     * 위 한계 문단이 말하는 그대로다.
+     */
+    const silenceLimitMs = typeof args.expectedSilenceMs === 'number' && args.expectedSilenceMs > 0
+        ? args.expectedSilenceMs
+        : exports.STALE_AFTER_MS;
+    if (typeof args.lastAtMs === 'number' && typeof args.nowMs === 'number') {
+        if (args.lastAtMs < 0) {
+            /* 한 번도 받지 않았는데 지금이 조용한 시간이면 「기다린다」가 아니라 「지금은 맞다」다. */
+            return args.quietNow === true ? 'expected-quiet' : 'unknown';
+        }
+        if (args.nowMs - args.lastAtMs > silenceLimitMs) {
+            /*
+             * 오래 조용하다. **지금이 그 원천의 조용한 시간이면 그것이 정상이다.**
+             *
+             * 이 갈래를 위쪽(버려지는 중·피드 없음)보다 뒤에 두는 이유: 사실이 사라지고 있거나 결선이
+             * 없는 것은 **몇 시든 문제**다. 밤이라고 덮으면 밤새 새는 것을 아침에 안다.
+             */
+            return args.quietNow === true ? 'expected-quiet' : 'no-traffic';
+        }
+    }
+    /*
+     * ── **닿았는데 오는 것이 없다** 를 「모른다」로 답하지 않는다 (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;
+        if (touched && nothingOffered)
+            return args.quietNow === true ? 'expected-quiet' : 'no-traffic';
+        return 'unknown';
+    }
+    if (args.recent.offered <= 0)
+        return args.quietNow === true ? 'expected-quiet' : 'no-traffic';
+    const ratio = (args.recent.offered - args.recent.rejected) / args.recent.offered;
+    return ratio >= (args.threshold ?? exports.HEALTHY_ACCEPTED_RATIO) ? 'syncing' : 'mapping-blocked';
+}
+function toWindowView(w, fallbackEndMs) {
+    /* 「통과」는 **트윈에 닿은** 것만이다. 버려진 것을 통과로 세면 화면이 안심시킨다. */
+    const accepted = w.offered - w.rejected - w.undelivered;
+    return {
+        from: new Date(w.startMs).toISOString(),
+        to: new Date(w.endMs >= 0 ? w.endMs : fallbackEndMs).toISOString(),
+        offered: w.offered,
+        accepted,
+        rejected: w.rejected,
+        undelivered: w.undelivered,
+        acceptedRatio: w.offered > 0 ? round4(accepted / w.offered) : null,
+        rows: w.rows,
+        flushes: w.flushes
+    };
+}
+/**
+ * 읽기용 요약.
+ *
+ * 장부가 없어도(한 번도 받지 않은 트윈) **판정은 낸다** — 피드 사실만으로 답할 수 있는 경우가 있다
+ * (`not-applicable`·`not-connected`). 그 경우 수치는 비운다: 없는 값을 0 으로 채우지 않는다.
+ *
+ * `nowMs` 를 받는 이유: 끊긴 피드를 가려내려면 「마지막 유입이 얼마나 전인가」를 봐야 하고, 그 판단을
+ * 화면이 아니라 여기서 한다(소비처마다 다시 판단하면 규칙이 갈라진다). 시험이 시각을 고정할 수 있도록
+ * 인자로 받는다.
+ */
+function ingestHealth(ledger, feedState, threshold = exports.HEALTHY_ACCEPTED_RATIO, nowMs = Date.now()) {
+    const recentRaw = ledger?.trend.length ? ledger.trend[ledger.trend.length - 1] : null;
+    /* 열린 창의 끝 시각 대체값 — 유입이 없는 장부에서 `-1` 을 시각으로 읽으면 1969년이 화면에 뜬다. */
+    const lastAnyMs = Math.max(ledger?.lastAtMs ?? -1, ledger?.lastWriteAtMs ?? -1);
+    const verdict = syncVerdictOf({
+        feedState,
+        recent: recentRaw,
+        lastAtMs: ledger?.lastAtMs ?? -1,
+        lastUndeliveredAtMs: ledger?.lastUndeliveredAtMs ?? -1,
+        /* 창이 닫히지 않았을 때 「받는 중」과 「오는 것이 없다」를 가르는 사실. */
+        offeredTotal: ledger?.offered ?? 0,
+        nowMs,
+        threshold
+    });
+    /*
+     * **유입이 없어도 「빈 장부」가 아니다.** 시뮬 트윈은 받는 것 없이 적는다. 유입 시각만 보고 비었다고
+     * 판단하면 그 트윈의 창은 만들어져 있는데 화면에는 아무 추이도 나오지 않는다(이 축을 넣은 이유가 그것이다).
+     */
+    if (!ledger || (ledger.lastAtMs < 0 && ledger.lastWriteAtMs < 0)) {
+        return {
+            verdict,
+            threshold,
+            recent: null,
+            trend: [],
+            trendDropped: 0,
+            total: { offered: 0, accepted: 0, rejected: 0, undelivered: 0, acceptedRatio: null, rows: 0, flushes: 0 },
+            reasons: [],
+            reasonsCapped: false,
+            samples: [],
+            sampleDropped: 0,
+            lastAt: null,
+            lastWriteAt: null,
+            /*
+             * **이 짧은 답에도 단절은 실어야 한다** — 이 자리가 바로 그 트윈의 모습이다.
+             *
+             * 받은 것도 적은 것도 없는 장부는 「아직 아무 일도 없다」로 읽히는데, 원본에 닿지 못하는 트윈이
+             * 정확히 그 모습이다(읽지 못하면 받은 것도 적은 것도 없다). 여기서 떨어뜨리면 **가장 필요한
+             * 순간에** 그 사실이 사라진다 — 실측으로 원본이 끊긴 트윈이 이 경로로 답하고 있었다.
+             */
+            ...(ledger?.readFailure
+                ? {
+                    readFailure: {
+                        consecutive: ledger.readFailure.consecutive,
+                        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.nextRetryMs ? { nextRetryMs: ledger.readFailure.nextRetryMs } : {})
+                    }
+                }
+                : {}),
+            ...(ledger?.lastRecovery
+                ? {
+                    lastRecovery: {
+                        at: new Date(ledger.lastRecovery.atMs).toISOString(),
+                        afterFailures: ledger.lastRecovery.afterFailures,
+                        downMs: ledger.lastRecovery.downMs
+                    }
+                }
+                : {}),
+            /* 커서 정체도 **이 갈래에서** 내보낸다 — 유입이 없는 장부에서도 정체는 실재한다(읽었으나 못
+               넘겼으면 유입이 0이다). 여기서 떨어뜨리면 바로 그 상황에서 들어온 것이 없어진다. */
+            ...(ledger?.cursorStall
+                ? {
+                    cursorStall: {
+                        consecutive: ledger.cursorStall.consecutive,
+                        since: new Date(ledger.cursorStall.sinceMs).toISOString(),
+                        lastAt: new Date(ledger.cursorStall.lastAtMs).toISOString(),
+                        reason: ledger.cursorStall.reason,
+                        ...(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()
+                    }))
+                }
+                : {})
+        };
+    }
+    /* 「통과」는 트윈에 닿은 것만이다 — 창 뷰와 같은 규칙. */
+    const accepted = ledger.offered - ledger.rejected - ledger.undelivered;
+    return {
+        verdict,
+        threshold,
+        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,
+            rejected: ledger.rejected,
+            undelivered: ledger.undelivered,
+            acceptedRatio: ledger.offered > 0 ? round4(accepted / ledger.offered) : null,
+            rows: ledger.rows,
+            flushes: ledger.flushes
+        },
+        reasons: Object.entries(ledger.byReason)
+            .map(([reason, v]) => ({ reason, count: v.count, lastAt: new Date(v.lastAtMs).toISOString() }))
+            .sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason)),
+        reasonsCapped: ledger.reasonsCapped,
+        samples: [...ledger.samples],
+        sampleDropped: ledger.sampleDropped,
+        /* 「받은 적 없음」과 「방금 받음」을 가른다 — 적기만 하는 트윈의 유입 시각은 **없다**. */
+        lastAt: ledger.lastAtMs >= 0 ? new Date(ledger.lastAtMs).toISOString() : null,
+        lastWriteAt: ledger.lastWriteAtMs >= 0 ? new Date(ledger.lastWriteAtMs).toISOString() : null,
+        /* 닿지 못하고 있으면 그 사실을 낸다 — 없으면 필드를 만들지 않는다(빈 값이 「닿는다」로 읽히지 않게). */
+        ...(ledger.readFailure
+            ? {
+                readFailure: {
+                    consecutive: ledger.readFailure.consecutive,
+                    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.nextRetryMs ? { nextRetryMs: ledger.readFailure.nextRetryMs } : {})
+                }
+            }
+            : {}),
+        /* 끊겼다가 돌아온 것 — 지금 닿고 있어도 남긴다(그것이 없으면 밤새의 단절이 사라진다). */
+        ...(ledger.lastRecovery
+            ? {
+                lastRecovery: {
+                    at: new Date(ledger.lastRecovery.atMs).toISOString(),
+                    afterFailures: ledger.lastRecovery.afterFailures,
+                    downMs: ledger.lastRecovery.downMs
+                }
+            }
+            : {}),
+        ...(ledger.cursorStall
+            ? {
+                cursorStall: {
+                    consecutive: ledger.cursorStall.consecutive,
+                    since: new Date(ledger.cursorStall.sinceMs).toISOString(),
+                    lastAt: new Date(ledger.cursorStall.lastAtMs).toISOString(),
+                    reason: ledger.cursorStall.reason,
+                    ...(ledger.cursorStall.stream ? { stream: ledger.cursorStall.stream } : {})
+                }
+            }
+            : {})
+    };
+}
+/** 비율은 자릿수를 넉넉히 준다 — 0.999 가 1 로 반올림되면 「전부 통과」로 읽힌다. */
+const round4 = (v) => Math.round(v * 10000) / 10000;
+//# sourceMappingURL=ingest-health.js.map