@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -0,0 +1,335 @@
+/** 추이 창 하나 — 제시·통과·거부·미전달, 그리고 **적힌 것**을 함께 든다. */
+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;
+}
+/** 거부 표본 하나 — 매핑을 고치려면 실제 모양을 봐야 한다. */
+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;
+    undelivered: number;
+    /** 누적 — 적힌 행과 두드린 횟수. */
+    rows: number;
+    flushes: number;
+    /**
+     * 마지막으로 **적은** 시각. 한 번도 없으면 `-1`.
+     *
+     * 유입 시각(`lastAtMs`)과 갈라 두는 이유는 위 `recordJournalWrite` 주석에 있다 — 섞으면 끊긴 피드가
+     * 초록으로 보인다.
+     */
+    lastWriteAtMs: number;
+    /**
+     * 마지막으로 **버려진** 시각(ms). 한 번도 없으면 `-1`.
+     *
+     * 창과 따로 둔다: 미전달은 창이 닫히기 전에 알아야 한다(그 사이에도 사실은 계속 사라지고 있다).
+     */
+    lastUndeliveredAtMs: 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?: {
+        /** 연속 실패 수 — 성공 한 번에 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): void;
+/**
+ * 읽기가 성공했다 — 단절 기록을 지운다.
+ *
+ * **빈 읽기도 성공이다**: 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이다. 그 둘을 같게 두면
+ * 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
+ */
+export declare function clearReadFailure(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' /** 원본이 먹이지 않는 트윈(시뮬)·멈춘 트윈 — 물을 대상이 아니다 */ | '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;
+    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`).
+     *
+     * 「유입 없음」과 **다른 판정**이다: 유입 없음은 원본이 조용한 것일 수 있고, 이것은 우리가 묻지도
+     * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
+     * 있는지가 그 차이다.
+     */
+    readFailure?: {
+        consecutive: number;
+        /** 이 단절이 시작된 시각 — 「20분째」를 말할 수 있게. */
+        since: string;
+        lastAt: string;
+        reason: string;
+        stream?: string;
+    };
+}
+/**
+ * 읽기용 요약.
+ *
+ * 장부가 없어도(한 번도 받지 않은 트윈) **판정은 낸다** — 피드 사실만으로 답할 수 있는 경우가 있다
+ * (`not-applicable`·`not-connected`). 그 경우 수치는 비운다: 없는 값을 0 으로 채우지 않는다.
+ *
+ * `nowMs` 를 받는 이유: 끊긴 피드를 가려내려면 「마지막 유입이 얼마나 전인가」를 봐야 하고, 그 판단을
+ * 화면이 아니라 여기서 한다(소비처마다 다시 판단하면 규칙이 갈라진다). 시험이 시각을 고정할 수 있도록
+ * 인자로 받는다.
+ */
+export declare function ingestHealth(ledger: IngestLedger | undefined, feedState: 'attached' | 'detached' | 'not-applicable', threshold?: number, nowMs?: number): IngestHealthView;