@things-factory/ingest 10.1.4

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

@@ -0,0 +1,550 @@
+/** 추이 창 하나 — 제시·통과·거부·미전달, 그리고 **적힌 것**을 함께 든다. */
+export interface IngestWindow {
+    /** 창이 열린 시각(ms). */
+    startMs: number;
+    /** 창이 닫힌 시각(ms). 아직 채우는 중이면 `-1`. */
+    endMs: number;
+    /** 이 창에 제시된 레코드 수(거부 여부 무관). */
+    offered: number;
+    /** 그중 **매핑이 거부한** 수 — 처방은 매핑을 고치는 것이다. */
+    rejected: number;
+    /**
+     * 매핑은 통과했지만 **트윈에 닿지 못한** 수 — 처방은 트윈을 세우는 것이다.
+     *
+     * ── 왜 거부와 따로 세나 (2026-08-20에 겪었다) ─────────────────────────────
+     * 트윈이 라이브로 돌지 않으면 커널이 레코드를 **알리지 않고 버린다**. 그런데 장부는 그것을 「통과」로 셌다.
+     * 화면이 「150 들어옴 · 150 통과 · 100%」라고 말하는 동안 150건은 바닥에 버려지고 있었다. 이 기능이
+     * 막으려던 바로 그것을 이 기능이 저지른 셈이다.
+     *
+     * 거부에 합치는 것도 답이 아니다 — 거부는 「매핑을 고쳐라」는 말이고, 여기서 필요한 말은 「트윈이 안
+     * 돌고 있다」다. **처방이 다르면 다른 수로 센다.**
+     */
+    undelivered: number;
+    /**
+     * 이 창에 **저널에 적힌 행** 수 — 「무엇이 남았나」.
+     *
+     * 유입과 다른 축이다: 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적는다(그래서 `offered` 는 0 이고
+     * `rows` 는 0 이 아니다). 이 칸이 없으면 그 트윈의 활동은 어느 추이에도 나타나지 않는다.
+     */
+    rows: number;
+    /**
+     * 그것을 적기 위해 **DB 를 두드린 횟수**(flush) — 「우리가 몇 번 갔나」.
+     *
+     * 행 수와 따로 세는 이유: 2026-08-20 에 고친 것이 바로 이 값이다(행마다 한 번 → 창당 한 번). 행만
+     * 세면 그 개선도, 되돌아가는 것도 보이지 않는다.
+     */
+    flushes: number;
+    /** 이 창에서 저널에 안 간 어휘 요소의 수 — 사라진 것이 아니라 저널로 가지 않는 것이다. */
+    vocabulary: number;
+}
+/** 거부 표본 하나 — 매핑을 고치려면 실제 모양을 봐야 한다. */
+export interface RejectSample {
+    atMs: number;
+    /** 커널이 낸 사유. 우리가 다시 쓰지 않고 그대로 옮긴다. */
+    errors: string[];
+    /** 막힌 레코드의 직렬화. 길면 자르고, 잘랐다고 표시한다. */
+    record: string;
+    recordTruncated?: boolean;
+}
+export interface IngestLedger {
+    /** 지금 채우는 중인 창. `startMs < 0` 이면 아직 아무것도 받지 않았다. */
+    window: IngestWindow;
+    /** 닫힌 창들 — 오래된 것이 앞. 상한을 넘으면 앞에서 밀려난다. */
+    trend: IngestWindow[];
+    /** 추이에서 밀려난 창 수. */
+    trendDropped: number;
+    /** 누적 제시·거부·미전달. */
+    offered: number;
+    rejected: number;
+    /**
+     * **저널에 안 가는 어휘 요소의 수** — 로트 번호·소비기한처럼 시각축이 없는 값.
+     *
+     * ── 왜 세나 (2026-09-05, 인티그레이션 레인이 셈으로 찾음) ─────────────────
+     * 어휘는 일부러 저널로 안 간다(§`canonical-ingest`) — 그것이 옳다. 그런데 **그 수를 빼 주는
+     * 자리가 없어서** 「보낸 것 − 앉은 것」이 안 맞고, 그 차이를 「사라졌다」로 읽게 된다.
+     *
+     * 실제로 그랬다: 커서 20 · 저널 17 · 어휘 1 → 사람이 손으로 세서 「둘이 빈다」를 찾았다. 그
+     * 뺄셈을 코드가 하려면 이 항이 있어야 한다.
+     */
+    vocabulary: number;
+    undelivered: number;
+    /** 누적 — 적힌 행과 두드린 횟수. */
+    rows: number;
+    flushes: number;
+    /**
+     * 마지막으로 **적은** 시각. 한 번도 없으면 `-1`.
+     *
+     * 유입 시각(`lastAtMs`)과 갈라 두는 이유는 위 `recordJournalWrite` 주석에 있다 — 섞으면 끊긴 피드가
+     * 초록으로 보인다.
+     */
+    lastWriteAtMs: number;
+    /**
+     * 마지막으로 **버려진** 시각(ms). 한 번도 없으면 `-1`.
+     *
+     * 창과 따로 둔다: 미전달은 창이 닫히기 전에 알아야 한다(그 사이에도 사실은 계속 사라지고 있다).
+     */
+    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` 가 답한다.
+     */
+    reasonsCapped: boolean;
+    /** 표본을 이미 뜬 사유들 — 같은 사유를 다시 직렬화하지 않기 위한 색인(O(1) 조회). */
+    sampledReasons: Set<string>;
+    /** 최근 거부 표본. */
+    samples: RejectSample[];
+    /** 표본에서 밀려난 거부 건수. */
+    sampleDropped: number;
+    /** 마지막으로 무엇이든 받은 시각(ms). **한 번도 없으면 `-1`** — 0 으로 두면 시각 0 과 구별되지 않는다. */
+    lastAtMs: number;
+    /**
+     * **원본에 닿지 못한 사실** (2026-08-23) — 「받은 것이 없다」와 **다른 사실**이다.
+     *
+     * ── 무엇이 아무 신호도 내지 않았나 ─────────────────────────────────────────────────────────
+     * 실 원본이 끊겼을 때(접속 시간 초과) 트윈의 **조회 가능한 상태 어디에도** 그 사실이 없었다.
+     * `recordIngest` 는 `onRecords` 가 불릴 때만 도달하고, 읽기가 실패하면 그 문에 오지 않는다.
+     * `TwinReference.lastError` 는 마스터 동기·접속 시험에만 적힌다.
+     *
+     * 그래서 화면이 볼 수 있는 것은 「새 사실이 없다」뿐이었고, 그것은 **「연결된 시스템에서 들어온 것이 없다」와 구별되지
+     * 않는다.** 실증 데모 중에 원본이 끊기면 사용자가 원인을 찾을 수 없다.
+     *
+     * ── 왜 「몇 번」과 「언제부터」를 함께 두나 ──────────────────────────────────
+     * 한 번 실패한 것과 20분째 못 읽는 것은 다른 사실이다. 그 구별이 없으면 화면이 순간의 실패에 놀라거나
+     * 계속된 단절을 대수롭지 않게 말한다. 그래서 **연속 실패 수**와 **처음 실패한 시각**을 함께 든다.
+     *
+     * 성공하면 지운다 — 고쳐진 단절이 화면에 남아 있으면 그것도 거짓이다.
+     */
+    /**
+     * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다.
+     *
+     * 실패 기록(`readFailure`)은 돌아오면 지워진다. 그것만 지우면 「끊긴 적이 있었다」가 화면에서
+     * 사라지므로, 돌아온 사실을 따로 남긴다.
+     */
+    lastRecovery?: {
+        atMs: number;
+        afterFailures: number;
+        downMs: number;
+    };
+    readFailure?: {
+        /** 연속 실패 수 — 성공 한 번에 0 으로 돌아간다. */
+        consecutive: number;
+        /** 이 단절이 **처음** 시작된 시각(ms). 연속이 끊기면 다시 정해진다. */
+        sinceMs: number;
+        /** 마지막 실패 시각(ms). */
+        lastAtMs: number;
+        /** 마지막 실패의 사유 — 사람이 읽는 한 줄(원본이 준 말 그대로). */
+        reason: string;
+        /** 어느 흐름에서 났나(어댑터가 말해 주면). 원본마다 흐름이 다르므로 열려 있다. */
+        stream?: string;
+        /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+        nextRetryMs?: number;
+    };
+    /**
+     * **읽었는데 창을 넘길 수 없다** (2026-08-24) — 위와 **다른 사실**이다.
+     *
+     * ── 왜 갈랐나 ───────────────────────────────────────────────────────────────
+     * 이 칸을 만들기 전에는 두 사실이 같은 이름으로 나갔다.
+     *
+     *   readFailure   원본에 닿지 못했다        → **기다리면 풀린다**
+     *   cursorStall   읽었는데 커서가 못 넘어간다 → **기다려도 안 풀린다**
+     *
+     * 둘째는 읽기가 성공한 실패다: 한 시각에 한 페이지보다 많은 행이 몰려 커서를 그 시각 밖으로 옮길 수
+     * 없다. 화면이 「원본에 닿지 못한다」고 말하면 사람은 원본을 의심하고 기다리는데, 필요한 조치는
+     * 페이지를 키우거나 같은 시각 안에서 순서를 정하는 것이다. **조치가 반대인 두 사실을 한 이름으로
+     * 부르면 그 이름은 정보가 아니라 오해다.**
+     *
+     * 모양은 위와 같게 둔다 — 「몇 번」과 「언제부터」가 여기서도 같은 값을 한다(한 번의 밀림과 사흘째
+     * 못 넘어가는 것은 다르다). 넘어가면 지운다.
+     */
+    /**
+     * **원본이 말했는데 트윈에 세우지 않은 것** — 이유별로 센다.
+     *
+     * ── 왜 이 자리가 필요한가 (2026-08-24) ─────────────────────────────────────
+     * 커넥터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**: 입자가 맞지 않거나, 받으면 상태가
+     * 거짓이 되거나, 커널 어휘로 옮길 수 없다. 그때 커넥터는 경고를 낸다 — **그런데 그 경고가 프로비저닝
+     * 화면에서 한 번 스쳐 지나갈 뿐이었다.** 그 뒤로는 어디에서도 볼 수 없었다.
+     *
+     * 그래서 사용자가 「원본보다 계획이 적다」를 물으면 **답이 어디에도 없다.** 그 사실은 한 번의
+     * 사건이 아니라 **상태의 성질**이다 — 세우지 않은 것은 지금도 트윈에 없다.
+     *
+     * ── `unhandled` 의 형제다 ──────────────────────────────────────────────────
+     *   `unhandled`   리듀서가 **받았는데** 담을 자리를 몰랐다
+     *   여기          커넥터가 **보지만 일부러 보내지 않았다** — 이유와 함께
+     *
+     * 둘 다 「사실이 오류 없이 사라지지 않게」 세는 것이고, 이유가 다르므로 자리도 다르다.
+     *
+     * 이유를 **문자열로 받는다**: 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 그 목록을 닫으면 새 원본을
+     * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율).
+     */
+    withheld?: {
+        reason: string;
+        count: number;
+        lastAtMs: number;
+    }[];
+    cursorStall?: {
+        /** 연속 정체 수 — 넘어가면 0 으로 돌아간다. */
+        consecutive: number;
+        /** 이 정체가 **처음** 시작된 시각(ms). */
+        sinceMs: number;
+        /** 마지막 정체 시각(ms). */
+        lastAtMs: number;
+        /** 사유 — 사람이 읽는 한 줄(어느 시각에서 막혔나까지 어댑터가 말해 주면 좋다). */
+        reason: string;
+        /** 어느 흐름인가. 밀도가 높은 표는 원본마다 다르므로 이 이름이 조치의 절반이다. */
+        stream?: string;
+    };
+}
+/**
+ * 읽기 실패를 장부에 적는다 — **받은 것이 없는 것과 가른다.**
+ *
+ * 연속 실패의 시작 시각을 지키는 것이 이 함수의 요점이다: 매번 새로 적으면 「20분째 못 읽는다」를
+ * 말할 수 없고, 화면은 늘 「방금 실패했다」만 보게 된다.
+ */
+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;
+/**
+ * 커서 정체를 장부에 적는다 — **닿지 못한 것과 가른다.**
+ *
+ * `recordReadFailure` 와 같은 모양이지만 **다른 칸**이다. 한 주기가 두 이유로 실패할 수는 없으므로
+ * (먼저 닿아야 읽는다) 둘이 동시에 서지 않는다 — 그래서 화면은 둘 중 하나만 보게 되고, 그 하나가
+ * 조치를 정한다.
+ */
+export declare function recordCursorStall(ledger: IngestLedger, reason: string, nowMs: number, stream?: string): void;
+/**
+ * **세우지 않은 것을 적는다** — 이유별 누적.
+ *
+ * 주기마다 다시 알려도 시끄러워지지 않게 **이유로 묶어 센다**(줄이 늘지 않는다). 그리고 마지막 시각을
+ * 함께 든다 — 「지금도 그런가」와 「한때 그랬나」는 다른 사실이고, 시각 없이는 구별할 수 없다.
+ *
+ * 이유가 같고 수가 달라지면 **마지막 수로 덮는다**: 이것은 누적 사건이 아니라 **지금 세우지 않은 것의
+ * 수**다. 주기마다 8건이면 8이고, 더해서 800이 되면 거짓이다.
+ */
+/**
+ * 어떤 길로 몇 건이 들어왔나 — 경로 이름은 부르는 쪽이 정한다.
+ *
+ * 이름을 자유 문자열로 두는 이유: 길이 늘어난다(지금은 물어보기·시나리오·부하 도구, 다음은 웹훅).
+ * 열거로 못 박으면 새 길이 생길 때 이 파일을 함께 고쳐야 하고, 잊으면 그 길이 통계에서 사라진다.
+ */
+export declare function recordIngestSource(ledger: IngestLedger, source: string, count: number, nowMs: number): void;
+/** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+/**
+ * **저널에 안 간 어휘 요소를 센다** — 없어진 것이 아니라 저널로 가지 않는 것이다.
+ *
+ * 어휘(로트 번호·소비기한 등)는 시각축이 없어 일부러 저널로 안 간다. 그런데 그 수를 빼 주는 자리가
+ * 없으면 「보낸 것 − 앉은 것」이 안 맞고, 그 차이를 **사라진 것으로 읽게 된다.**
+ *
+ * 창을 굴리지 않는다 — 부르는 쪽(`recordIngest`)이 이미 굴린 뒤에 부른다. 여기서 또 굴리면 한
+ * 유입이 두 창에 걸친다.
+ */
+export declare function recordVocabulary(ledger: IngestLedger, count: 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;
+/** 창 길이 — 10분. 부하 계기판(10초)과 다른 값이라 이름을 따로 둔다(같은 이름이면 섞인다). */
+export declare const INGEST_WINDOW_MS = 600000;
+/**
+ * 이만큼 아무것도 오지 않으면 「유입 없음」이라 말한다.
+ *
+ * 창 하나와 같게 둔다 — 한 창을 통째로 비운 것은 실제로 「그 구간에 아무것도 오지 않았다」이고, 추이의
+ * 그 자리도 비게 된다. 그림과 알약이 같은 말을 하게 하려면 같은 길이여야 한다.
+ */
+export declare const STALE_AFTER_MS = 600000;
+/** 추이 보관 창 수 — 36창 × 10분 = 6시간. 「고친 것이 먹혔나」를 보기에 충분하고 메모리는 숫자 넷×36 이다. */
+export declare const TREND_LIMIT = 36;
+/**
+ * 사유 종류 상한.
+ *
+ * **없으면 메모리가 끝없이 자란다.** 사유 문구에 레코드마다 다른 값이 섞이는 커넥터가 하나만 있어도
+ * (`unknown bizStep "PUTAWAY_X17"`, `…X18`, …) 키가 무한히 늘어난다. 초당 1만 건 규모에서 이것은
+ * 미미한 오버헤드가 아니라 누수다.
+ *
+ * 넘치면 `OTHER_REASON` 한 칸에 모으고 **몇 종을 모았는지 함께 낸다**(알리지 않고 자르지 않는다).
+ * 30종이면 고칠 곳을 찾기에 충분하다 — 목록을 훑는 일이 아니라 매핑 몇 줄을 고치는 일이다.
+ */
+export declare const REASON_LIMIT = 30;
+/** 상한을 넘긴 사유들이 모이는 칸. */
+export declare const OTHER_REASON = "(other reasons)";
+/**
+ * 표본 상한 — **사유마다 한 건**만 든다.
+ *
+ * 같은 사유 20건보다 **서로 다른 사유 1건씩**이 매핑을 고치는 데 유용하다. 그리고 이 규칙이 성능을
+ * 지킨다: 그 사유의 표본이 이미 있으면 `JSON.stringify` 를 **아예 하지 않는다.** 실측(레코드 241바이트)
+ * 으로 건당 0.24µs 인데, 초당 1만 건이 전부 거부되면 9,980건은 만들자마자 버려지는 문자열이었다 —
+ * CPU 는 감당되지만 GC 압박이 이벤트 루프로 돌아온다.
+ */
+export declare const SAMPLE_LIMIT = 30;
+/** 표본 하나의 직렬화 상한(문자). */
+export declare const RECORD_MAX = 2000;
+/**
+ * 매핑이 막고 있다고 볼 통과율 문턱.
+ *
+ * 값과 함께 내보낸다 — 화면이 「95% 미만이라 매핑 문제로 봤다」를 말할 수 있게. 숨긴 문턱은 사람이
+ * 판정을 믿지 못한다.
+ */
+export declare const HEALTHY_ACCEPTED_RATIO = 0.95;
+export declare function newIngestLedger(): IngestLedger;
+/**
+ * 창이 다 찼으면 닫아 추이에 넣고 새로 연다. **닫힌 창만 「최근」으로 읽는다.**
+ *
+ * ── 영속이 붙는 유일한 자리 ────────────────────────────────────────────────
+ * 닫힌 창 하나가 영속의 단위다(숫자 넷 + 구간). `onClosed` 를 받는 이유는 **이 함수가 창이 닫히는
+ * 유일한 지점**이기 때문이다 — 여기 한 곳에 붙이면 기록 경로가 갈리지 않는다.
+ *
+ * 왜 건마다가 아니라 창마다인가: 거부마다 행을 쓰면 초당 1만 행이고 그 부하가 이벤트 루프로 돌아온다.
+ * 창마다면 트윈 1,000개에 하루 14.4만 행(약 14MB)이다.
+ *
+ * `onClosed` 는 **오류를 내지 않아야 한다**(호출부가 감싼다) — 영속이 실패해도 장부는 계속 굴러야 한다.
+ * 영속을 지키는 것과 관측을 지키는 것은 다른 일이고, 뒤엣것이 앞엣것 때문에 멈추면 안 된다.
+ */
+export declare function rollIngestWindow(ledger: IngestLedger, nowMs: number, windowMs?: number, onClosed?: (closed: IngestWindow) => void): void;
+/** 사유 묶음의 키. 사유가 여럿이면 한 줄로 잇고, 없으면 지어내지 않고 `unknown`. */
+export declare function reasonKey(errors: string[] | undefined): string;
+/**
+ * 한 번의 인제스트 결과를 적는다.
+ *
+ * `offered` 를 함께 받는 이유: 통과율을 **서로 다른 두 계수기**에서 나눠 계산하면 분모와 분자가 다른
+ * 것을 세게 된다. 둘을 한자리에서 본 수를 그대로 적는다.
+ */
+export declare function recordIngest(ledger: IngestLedger, offered: number, rejected: {
+    record?: unknown;
+    errors?: string[];
+}[] | undefined, nowMs: number, onClosed?: (closed: IngestWindow) => void, 
+/** 매핑은 통과했지만 트윈에 닿지 못한 수 — 「통과」로 세면 화면이 거짓을 말한다. */
+undelivered?: number): void;
+/**
+ * 저널에 **적은 것**을 기록한다 — 창을 넘길 때가 되었으면 넘기고, 행·왕복을 더한다.
+ *
+ * ── 왜 유입과 같은 창인가 ───────────────────────────────────────────────────
+ * 새 장부를 만들지 않는다. 이 창은 「닫힌 창만 최근」·「0 과 없음을 가른다」·「잘린 것을 세어 드러낸다」를
+ * 이미 지키고, 닫힐 때 영속까지 된다. 같은 규율을 두 벌 만들면 한쪽만 고쳐진다.
+ *
+ * ── 유입이 없어도 창은 넘어간다 ────────────────────────────────────────────
+ * 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적는다. 창이 **유입에서만** 넘어간다면 그 트윈은 추이에
+ * 영원히 나타나지 않는다 — 그래서 쓰기도 창을 넘긴다.
+ */
+export declare function recordJournalWrite(ledger: IngestLedger, rows: number, nowMs: number, onClosed?: (closed: IngestWindow) => void): void;
+/**
+ * 한눈 판정.
+ *
+ * `not-applicable` 과 `not-connected` 를 섞지 않고, 재지 않은 것을 정상·비정상으로 채우지 않는다
+ * (`unknown`). 시뮬 트윈에 「동기화 안 됨」이라 말하면 거짓 경보이고, **거짓 경보는 참 경보를 죽인다.**
+ */
+export type SyncVerdict = 'syncing' /** 유입이 있고 통과율이 문턱 이상 */ | 'mapping-blocked' /** 유입은 있는데 거부가 문턱을 넘는다 — 사유를 보고 매핑을 고친다 */
+/**
+ * 들어오는데 **커널이 받지 않는다** — 사실이 사라지고 있다.
+ *
+ * ── 이름이 사실보다 좁다 (2026-08-20에 드러났다) ────────────────────────────
+ * 관측한 것은 「커널이 받지 않았다」(`ingestLive` 가 0)이고, **멈춘 것은 그 원인 중 하나일 뿐**이다.
+ * 다른 원인이 실제로 있었다: 미러로 선언된 트윈을 사람이 화면에서 시작하면 시뮬 구동으로 떴고, 그
+ * 트윈은 **돌고 있으면서** 유입을 한 건도 받지 못했다. 그때 화면은 한쪽에 「running」, 다른 쪽에
+ * 「멈춰」라고 적었고 사람은 「시작 버튼을 누르면 되겠네」라는 엉뚱한 처방으로 갔다.
+ *
+ * 그래서 **화면 문구는 관측 그대로** 적는다(「트윈에 닿지 않고 버려지는 중」). 이 키 이름은 서버·화면·
+ * 시험에 걸친 계약 문자열이라 그대로 두지만, 이름을 원인으로 읽지 않는다.
+ */
+ | 'twin-not-running' | 'no-traffic' /** 피드는 붙었는데 제시가 0 — 원천·망을 본다 */ | 'not-connected' /** 피드 자체가 없다 — 결선한다 */ | 'not-applicable' /** 원본이 먹이지 않는 트윈(시뮬)·멈춘 트윈 — 물을 대상이 아니다 */
+/**
+ * **지금은 조용한 것이 정상이다** — 원천이 지금 시각에 내놓지 않는다.
+ *
+ * ── 왜 초록도 빨강도 아닌가 (2026-09-04) ─────────────────────────────────
+ * 태양광은 밤에 발전하지 않고, 업무시간만 도는 원천은 저녁에 아무것도 내지 않는다. 그 침묵을
+ * `no-traffic` 으로 부르면 **정상인 밤마다 절반이 빨갛게 난다.** 거짓 빨강이 쌓이면 진짜 빨강도
+ * 같이 안 읽힌다 — 오늘 UX 레인이 「늘 참인 경고는 벽지가 된다」고 한 것과 같은 부류다.
+ *
+ * 그렇다고 `syncing` 도 아니다. 지금 받고 있는 것이 아니고, 초록으로 칠하면 **밤에 정말 끊긴
+ * 원천**을 아침까지 아무도 모른다.
+ *
+ * 그래서 셋째 값이다: 「지금은 안 오는 것이 맞다」. 화면은 이것을 회색으로 그리고, 다음에 올
+ * 시각을 함께 말할 수 있다.
+ */
+ | 'expected-quiet' | 'unknown'; /** 한 번도 받지 않았거나 창이 아직 닫히지 않았다 — 기다린다 */
+export declare function syncVerdictOf(args: {
+    /** `live-feed-registry.liveFeedStateOf` 의 답을 그대로 받는다 — 판정 어휘를 두 벌 만들지 않는다. */
+    feedState: 'attached' | 'detached' | 'not-applicable';
+    /** 마지막으로 **닫힌** 창. 없으면 `null`. */
+    recent: {
+        offered: number;
+        rejected: number;
+    } | null;
+    /** 마지막으로 무엇이든 받은 시각. 한 번도 없으면 `-1` — 0 이 아니다(0 은 1970년이다). */
+    lastAtMs?: number;
+    /** 지금. `lastAtMs` 를 견줄 때만 쓴다. */
+    nowMs?: number;
+    /** 마지막으로 **버려진** 시각. 한 번도 없으면 `-1`. */
+    lastUndeliveredAtMs?: number;
+    /**
+     * **이 원천은 이만큼 조용해도 정상이다** — 긷는 주기를 원천 쪽이 선언한 값.
+     *
+     * 없으면 창 하나(`STALE_AFTER_MS`)로 견준다(지금까지의 거동). 15분마다 긷는 원천은 그 값을
+     * 선언해야 하고, 안 하면 긷는 사이마다 「유입 없음」으로 보인다 — 이 파일이 아래에서 그 한계를
+     * 스스로 적어 두고 있었다.
+     *
+     * 장부는 원천의 주기를 알 수 없다. **선언만이 그것을 아는 유일한 길이다.**
+     */
+    expectedSilenceMs?: number;
+    /**
+     * **지금이 그 원천의 조용한 시간인가** — 근무 달력 판정의 결과만 받는다.
+     *
+     * 달력 자체를 여기서 보지 않는다: 이 함수는 순수하고, 달력·시간대·시각 해석은 계약이 이미
+     * 한 자리에서 한다(`inWorkCalendar`·`offCalendarAt`). 부르는 쪽이 그것을 불러 참·거짓만 준다 —
+     * `capabilityOf` 가 `requiredTests` 를 받는 것과 같은 규율이다.
+     *
+     * **모르면 주지 않는다.** `false` 로 채우면 「지금은 활동 시간이다」를 단언하는 것이 되고, 달력을
+     * 선언하지 않은 원천이 전부 그렇게 읽힌다.
+     */
+    quietNow?: boolean;
+    /**
+     * 지금까지 제시된 누적 수 — **「받고 있는 중」과 「오는 것이 없다」를 가르는 사실**이다.
+     *
+     * 닿은 시각(`lastAtMs`)으로는 가를 수 없다: 빈 읽기도 닿은 것이므로 그 시각이 선다. 창이 아직 닫히지
+     * 않았을 때 이 수가 0 이면 오는 것이 없는 것이고, 0 이 아니면 받고 있는 중이다.
+     */
+    offeredTotal?: number;
+    threshold?: number;
+}): SyncVerdict;
+export interface IngestWindowView {
+    from: string;
+    to: string;
+    offered: number;
+    /** **트윈에 닿은** 수. 제시 − 거부 − 미전달. */
+    accepted: number;
+    /** 매핑이 거부한 수 — 처방은 매핑을 고치는 것. */
+    rejected: number;
+    /** 매핑은 통과했으나 트윈에 닿지 못한 수 — 처방은 트윈을 세우는 것. */
+    undelivered: number;
+    /** 통과율(0~1). 제시가 없으면 `null` — **1 로 채우면 「전부 통과」로 읽힌다.** */
+    acceptedRatio: number | null;
+    /** 이 창에 적힌 행. */
+    rows: number;
+    /** 그것을 적기 위해 DB 를 두드린 횟수 — 행당 왕복이 줄었는지 보는 값. */
+    flushes: number;
+}
+export interface IngestHealthView {
+    verdict: SyncVerdict;
+    /** 판정에 쓴 문턱 — 화면이 왜 그 판정인지 말할 수 있게 함께 낸다. */
+    threshold: number;
+    /** 마지막으로 닫힌 창. 창이 한 번도 닫히지 않았으면 `null`. */
+    recent: IngestWindowView | null;
+    /** 닫힌 창들, 오래된 것부터. */
+    trend: IngestWindowView[];
+    /** 추이 상한에서 밀려난 창 수. */
+    trendDropped: number;
+    /** 누적(기동 이후). */
+    total: {
+        offered: number;
+        accepted: number;
+        rejected: number;
+        undelivered: number;
+        acceptedRatio: number | null;
+        /** 저널에 적힌 행과 그것을 위해 DB 를 두드린 횟수 — 기동 이후 누적. */
+        rows: number;
+        flushes: number;
+    };
+    /** 사유별 누적, 많은 것부터. `lastAt` 이 멈춘 사유는 이미 고쳐진 것이다. */
+    reasons: {
+        reason: string;
+        count: number;
+        lastAt: string;
+    }[];
+    /** 사유 종류가 상한에 닿아 일부가 `(other reasons)` 로 접혔나. */
+    reasonsCapped: boolean;
+    samples: RejectSample[];
+    sampleDropped: number;
+    /** 마지막으로 무엇이든 받은 시각. 한 번도 없으면 `null`. */
+    lastAt: string | null;
+    /** 마지막으로 저널에 적은 시각. 한 번도 없으면 `null` — 받은 적 없는 트윈도 이 값은 있을 수 있다. */
+    lastWriteAt: string | null;
+    /**
+     * **원본에 닿지 못하고 있다** — 없으면 닿고 있다는 뜻이다(§`IngestLedger.readFailure`).
+     *
+     * 커서 정체(`cursorStall`)와 **섞이지 않는다**: 이쪽은 기다리면 풀리고 그쪽은 기다려도 안 풀린다.
+     *
+     * 「유입 없음」과 **다른 판정**이다: 유입 없음은 연결된 시스템에서 들어온 것이 없는 것일 수 있고, 이것은 우리가 묻지도
+     * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
+     * 있는지가 그 차이다.
+     */
+    readFailure?: {
+        consecutive: number;
+        /** 이 단절이 시작된 시각 — 「20분째」를 말할 수 있게. */
+        since: string;
+        lastAt: string;
+        reason: string;
+        stream?: string;
+        /** 다음에 다시 물을 때까지 남은 시간(ms) — 커넥터가 물러섰을 때만 있다. */
+        nextRetryMs?: number;
+    };
+    /**
+     * 마지막으로 끊겼다가 돌아온 것 — 없으면 끊긴 적이 없거나 아직 돌아오지 않은 것이다 (2026-08-27).
+     *
+     * `readFailure` 는 돌아오면 사라진다. 이 칸이 없으면 밤새 끊겼던 연결과 한 번도 끊기지 않은 연결이
+     * 아침에 똑같이 보인다.
+     */
+    lastRecovery?: {
+        at: string;
+        afterFailures: number;
+        downMs: number;
+    };
+}
+/**
+ * 읽기용 요약.
+ *
+ * 장부가 없어도(한 번도 받지 않은 트윈) **판정은 낸다** — 피드 사실만으로 답할 수 있는 경우가 있다
+ * (`not-applicable`·`not-connected`). 그 경우 수치는 비운다: 없는 값을 0 으로 채우지 않는다.
+ *
+ * `nowMs` 를 받는 이유: 끊긴 피드를 가려내려면 「마지막 유입이 얼마나 전인가」를 봐야 하고, 그 판단을
+ * 화면이 아니라 여기서 한다(소비처마다 다시 판단하면 규칙이 갈라진다). 시험이 시각을 고정할 수 있도록
+ * 인자로 받는다.
+ */
+export declare function ingestHealth(ledger: IngestLedger | undefined, feedState: 'attached' | 'detached' | 'not-applicable', threshold?: number, nowMs?: number): IngestHealthView;