@things-factory/headless-twin 10.0.13 → 10.0.15

package/dist-server/engine/twin-engine.d.ts

@@ -174,6 +174,28 @@ export declare class TwinEngine {
      * 사건 집계가 없다 — 그 상태로 뒤를 접으면 0부터 접은 결과와 조용히 달라진다). 그래서 씨앗은 따로 든다.
      */
     private static readonly FOLD_NOTE;
+    /**
+     * 재기동에 쓸 **웜스타트 씨앗**을 만든다 — 상태 + 이어 접을 재개점.
+     *
+     * ── 왜 이 자리가 생겼나 (2026-08-24) ──────────────────────────────────────
+     * 두 호출부가 같은 일을 조금씩 다르게 하고 있었고(겹포장을 한쪽만 벗겼다), 둘 다 **재개점을 버리고**
+     * 상태만 들고 갔다. 그래서 저장된 재개점을 읽는 쪽이 다 있는데도 재기동은 매번 저널을 처음부터
+     * 접었다(실측: 저널 2,960만 줄).
+     *
+     * 여기서 하는 일 셋:
+     *  ① 겹포장을 벗긴다 — 옛 형식으로 저장된 값이 한 번은 반드시 나온다
+     *  ② **그 공장이 아직 그 공장인지** 심판한다 — 아니면 씨앗을 버린다(아래)
+     *  ③ 씨앗이 저널 끝보다 앞서 있으면 **그 꼬리만 접어** 끝까지 밀어 둔다
+     *
+     * ②가 필요한 이유: 재개점은 그때의 보드 위에서 만들어진 것이다. 그 뒤 구조가 바뀌었다면(자리가
+     * 빠졌다·설비가 옮겨졌다) 되세운 리듀서는 **지금 없는 자리와 설비를 든다** — 없는 냉장실이 화면에
+     * 나오고 그 자리의 판정이 계속 돌아간다. 오류 없이 틀리므로 눈에 띄지 않는다.
+     *
+     * ③이 필요한 이유: 스냅샷은 체크포인트 주기로 쓰이므로 마지막 주기 이후의 사실은 저널에만 있다.
+     * 그것을 빼고 되세우면 그만큼이 조용히 사라진다 — 「모름」을 「없음」으로 적는 것과 같은 부류다.
+     * 접는 구간은 **그 틈뿐**이고(저널 전체가 아니다), `recover` 가 그 자리에서 새 재개점을 남겨 준다.
+     */
+    private static warmSeedFor;
     /** 체크포인트된 최신 스냅샷 로드(없으면 null). getFromCache 는 CacheStore 엔티티를 반환 → 페이로드는 .value. */
     static loadSnapshot(domainId: string, instanceId: string): Promise<{
         revision: number;
@@ -1046,6 +1068,25 @@ export declare class TwinEngine {
      * 그 둘을 같게 두면 조용한 원본이 끊긴 원본으로 보인다.
      */
     static clearIngestReadFailure(domainId: string, instanceId: string): void;
+    /**
+     * **읽었는데 창을 넘길 수 없다**를 적는다 — 위와 **조치가 반대인** 사실이다(§`recordCursorStall`).
+     *
+     * 이 문이 없던 동안 이 사실이 `recordIngestReadFailure` 로 나갔다. 그래서 화면이 「원본에 닿지
+     * 못한다」고 말했는데 원본은 **답한** 상태였고, 그 답의 모양이 커서를 이긴 것이었다(한 시각에 한
+     * 페이지보다 많은 행). 사람은 원본을 의심하고 기다리는데 **기다림으로는 영원히 풀리지 않는다.**
+     *
+     * 조치가 반대인 두 사실을 한 이름으로 부르면 그 이름은 정보가 아니라 오해다.
+     */
+    static recordIngestCursorStall(domainId: string, instanceId: string, reason: string, nowMs?: number, stream?: string): void;
+    /**
+     * **원본에 있는데 세우지 않은 것을 적는다** — 이유와 수(§`IngestLedger.withheld`).
+     *
+     * 어댑터가 주기마다 불러도 된다: 장부가 이유로 묶어 **마지막 수로 덮는다**(누적하지 않는다).
+     * `count: 0` 은 「그 이유가 풀렸다」로 그 줄을 지운다 — 조용히 그치면 낡은 수가 남는다.
+     */
+    static recordIngestWithheld(domainId: string, instanceId: string, reason: string, count: number, nowMs?: number): void;
+    /** 창을 넘겼다 — 정체 기록을 지운다(풀린 정체가 화면에 남아 있으면 그것도 거짓이다). */
+    static clearIngestCursorStall(domainId: string, instanceId: string): void;
     /**
      * 저널에 **적은 것**을 같은 장부에 남긴다 — 유입과 같은 10분 창에.
      *

package/dist-server/engine/twin-engine.js

@@ -260,10 +260,61 @@ class TwinEngine {
         const state = (0, warm_start_js_1.unwrapState)(this.snapshot(domainId, instanceId));
         if (!state)
             return;
+        /*
+         * ── **아무것도 듣지 못한 것을 「비었다」로 적지 않는다** (2026-08-24 실측) ────
+         *
+         * 미러가 재기동하면 관측 축(재고·오더·작업)을 들고 오지 않는다(`startLive` 가 되찾은 상태를
+         * 버린다 — 「다음 계측이 정정한다」는 전제). 그런데 원본이 **커서 증분**으로 말하는 현장에서는 그
+         * 정정이 오지 않는다: 커서가 따라잡힌 뒤 원본이 변하지 않으면 미러는 영구히 빈 채다.
+         *
+         * 그 상태에서 이 함수가 돌면 **빈 상태를 좋은 스냅샷 위에 덮는다.** 그래서 손실이 영구화됐다:
+         *
+         *   저장돼 있던 것   rev 221,884 · nowTime 2026-04-15 · items 741 · orders 2,780 · tasks 6,353
+         *   덮으려던 것      같은 키 · nowTime 2026-01-01 · 전부 0
+         *
+         * 리비전으로는 막을 수 없다 — 저널 줄 번호는 관측이 없어도 계속 자란다. 막는 기준은 **「들은 것이
+         * 있나」**다. 유입이 한 건도 없었다면 이 빈 상태는 **원본이 「비었다」고 말한 것이 아니라 우리가
+         * 아무것도 못 들은 것**이고, 그 둘을 같은 값으로 적으면 「모름」이 「없음」이 된다.
+         *
+         * 원본이 실제로 「다 비었다」고 말한 경우는 막지 않는다 — 그때는 유입이 있었으므로 이 문을 지난다.
+         *
+         * 그리고 **거절을 말한다**: 조용히 거절하면 왜 체크포인트가 낡아 가는지 아무도 모른다.
+         */
+        if (!(inst.metrics?.ingestedTotal > 0)) {
+            const observed = (s) => (s?.items?.length ?? 0) + (s?.orders?.length ?? 0) + (s?.tasks?.length ?? 0);
+            if (observed(state) === 0) {
+                const prev = await this.loadSnapshot(domainId, instanceId).catch(() => null);
+                const had = observed(prev?.state);
+                if (had > 0) {
+                    (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": checkpoint refused — this twin has heard nothing since start and its live ` +
+                        `state is empty, while the stored snapshot holds ${had} observed fact(s) (revision ${prev?.revision}). ` +
+                        'Writing the empty state would destroy the only recoverable copy. The journal still holds the truth.');
+                    return;
+                }
+            }
+        }
         const revision = inst.revision ?? state.revision ?? 0;
         /* 구조 리비전도 함께 — 읽는 쪽이 "이 상태가 지금의 공장인가" 를 가릴 수 있어야 한다. */
         const { structureRev } = await this.tipOf(domainId, instanceId).catch(() => ({ structureRev: null }));
-        await cache_service_1.cacheService.setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, { revision, state, structureRev }, this.SNAPSHOT_TTL_S);
+        /*
+         * ── **이어 접을 씨앗을 함께 적는다** (2026-08-24) ──────────────────────────
+         *
+         * 이 함수는 오랫동안 `{revision, state, structureRev}` 만 적었다. 그래서 **재개점을 읽는 쪽은 다
+         * 있는데 쓰는 쪽이 없었다**: 조회 경로(`recover`)는 `fold` 가 있으면 꼬리만 접고, 없으면 저널을
+         * 0부터 접는다. 실측으로 저장된 스냅샷 34건 전부 `fold` 가 비어 있었고, 저널은 2,960만 줄이었다 —
+         * 그래서 재기동·조회마다 처음부터 다시 접었다. 규모 기준(엔티티 10만·품목 100만)에서 이것은
+         * 느린 것이 아니라 **못 하는 것**이다.
+         *
+         * 씨앗은 상태가 대신할 수 없다: 리듀서는 소비처가 보는 값 말고도 든다(부모를 기다리는 담김·집계
+         * 중인 수량·담을 줄 몰라 세어 둔 사건). 상태만 되돌리고 뒤를 접으면 0부터 접은 결과와 **조용히**
+         * 달라진다. 그 동치는 커널 시험이 증명한다(`observed-checkpoint.test.ts`).
+         *
+         * 관측 구동이 아니면 씨앗이 없다 — 시뮬은 리듀서를 갖지 않고, 그 상태의 권위는 커널 자신이다.
+         * 그때는 `fold` 를 **넣지 않는다**(빈 씨앗을 넣으면 읽는 쪽이 「이어 접을 수 있다」고 잘못 본다).
+         */
+        const reducer = inst.kernel?.observedCheckpoint?.();
+        const fold = reducer && inst.oee ? { reducer, oee: inst.oee.serialize() } : undefined;
+        await cache_service_1.cacheService.setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, { revision, state, structureRev, ...(fold ? { fold } : {}) }, this.SNAPSHOT_TTL_S);
     }
     /**
      * 접기의 **재개점** — 리듀서 내부 상태 전부 + 가동 누적기.
@@ -272,6 +323,55 @@ class TwinEngine {
      * 사건 집계가 없다 — 그 상태로 뒤를 접으면 0부터 접은 결과와 조용히 달라진다). 그래서 씨앗은 따로 든다.
      */
     static { this.FOLD_NOTE = 'reducer + oee checkpoint — the seed for folding only the tail'; }
+    /**
+     * 재기동에 쓸 **웜스타트 씨앗**을 만든다 — 상태 + 이어 접을 재개점.
+     *
+     * ── 왜 이 자리가 생겼나 (2026-08-24) ──────────────────────────────────────
+     * 두 호출부가 같은 일을 조금씩 다르게 하고 있었고(겹포장을 한쪽만 벗겼다), 둘 다 **재개점을 버리고**
+     * 상태만 들고 갔다. 그래서 저장된 재개점을 읽는 쪽이 다 있는데도 재기동은 매번 저널을 처음부터
+     * 접었다(실측: 저널 2,960만 줄).
+     *
+     * 여기서 하는 일 셋:
+     *  ① 겹포장을 벗긴다 — 옛 형식으로 저장된 값이 한 번은 반드시 나온다
+     *  ② **그 공장이 아직 그 공장인지** 심판한다 — 아니면 씨앗을 버린다(아래)
+     *  ③ 씨앗이 저널 끝보다 앞서 있으면 **그 꼬리만 접어** 끝까지 밀어 둔다
+     *
+     * ②가 필요한 이유: 재개점은 그때의 보드 위에서 만들어진 것이다. 그 뒤 구조가 바뀌었다면(자리가
+     * 빠졌다·설비가 옮겨졌다) 되세운 리듀서는 **지금 없는 자리와 설비를 든다** — 없는 냉장실이 화면에
+     * 나오고 그 자리의 판정이 계속 돌아간다. 오류 없이 틀리므로 눈에 띄지 않는다.
+     *
+     * ③이 필요한 이유: 스냅샷은 체크포인트 주기로 쓰이므로 마지막 주기 이후의 사실은 저널에만 있다.
+     * 그것을 빼고 되세우면 그만큼이 조용히 사라진다 — 「모름」을 「없음」으로 적는 것과 같은 부류다.
+     * 접는 구간은 **그 틈뿐**이고(저널 전체가 아니다), `recover` 가 그 자리에서 새 재개점을 남겨 준다.
+     */
+    static async warmSeedFor(domainId, instanceId) {
+        let cached = await this.loadSnapshot(domainId, instanceId).catch(() => null);
+        if (!cached?.state)
+            return null;
+        const seedOf = (c) => (c?.fold?.reducer ? { fold: c.fold } : {});
+        if (!cached.fold?.reducer)
+            return { revision: cached.revision, state: (0, warm_start_js_1.unwrapState)(cached.state) };
+        const tip = await this.tipOf(domainId, instanceId).catch(() => null);
+        if (tip && (cached.structureRev ?? null) !== tip.structureRev) {
+            (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": the stored fold seed is from structure ${cached.structureRev} but the factory is now ` +
+                `at ${tip.structureRev} — starting without it (the journal is folded from the beginning instead).`);
+            return { revision: cached.revision, state: (0, warm_start_js_1.unwrapState)(cached.state) };
+        }
+        if (tip && (cached.revision ?? 0) < tip.revision) {
+            /*
+             * 틈을 접는다 — `recover` 가 이 씨앗으로 **꼬리만** 접고, 끝 지점의 새 재개점을 남긴다.
+             * 아직 이 트윈의 런타임이 없으므로 `recover` 는 메모리 대신 저널 경로를 탄다(그것이 여기의 전제다).
+             */
+            const gap = tip.revision - (cached.revision ?? 0);
+            await this.recover(domainId, instanceId).catch(err => (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": could not fold the ${gap} event(s) after the checkpoint — ${err?.message ?? err}`));
+            const advanced = await this.loadSnapshot(domainId, instanceId).catch(() => null);
+            if (advanced?.state && (advanced.revision ?? 0) > (cached.revision ?? 0)) {
+                (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": folded ${gap} event(s) after the checkpoint → revision ${advanced.revision}.`);
+                cached = advanced;
+            }
+        }
+        return { revision: cached.revision, state: (0, warm_start_js_1.unwrapState)(cached.state), ...seedOf(cached) };
+    }
     /** 체크포인트된 최신 스냅샷 로드(없으면 null). getFromCache 는 CacheStore 엔티티를 반환 → 페이로드는 .value. */
     static async loadSnapshot(domainId, instanceId) {
         const entry = await cache_service_1.cacheService.getFromCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId });
@@ -488,10 +588,9 @@ class TwinEngine {
                     continue;
                 // 웜스타트: 캐시된 최신 스냅샷 우선(O(1) + attentions/OEE 등 라이브 파생상태 보존).
                 // 없으면 저널 fold-from-0 replay(진실 폴백 — replay 는 라이브 파생상태를 못 담으므로 캐시가 더 충실).
-                const cached = await this.loadSnapshot(row.domainId, row.instanceId).catch(() => null);
+                const cached = await this.warmSeedFor(row.domainId, row.instanceId).catch(() => null);
                 if (cached?.state) {
-                    /* 예전에 겹포장으로 저장된 값이 남아 있을 수 있다 — 읽는 쪽에서도 벗긴다(한 번은 반드시 만난다). */
-                    this.recovered[(0, runtime_key_js_1.runtimeKey)(row.domainId, row.instanceId)] = { revision: cached.revision, state: (0, warm_start_js_1.unwrapState)(cached.state) };
+                    this.recovered[(0, runtime_key_js_1.runtimeKey)(row.domainId, row.instanceId)] = cached;
                     /*
                      * **「웜스타트했다」고 말하지 않는다** — 여기서는 상태를 **찾아 둔 것**뿐이다.
                      *
@@ -1267,6 +1366,43 @@ class TwinEngine {
          * 관측 축(재고·위치·설비)은 **여전히 심지 않는다** — 다음 계측이 정정하고, 심으면 떠난 물건이
          * 되살아난다. 무엇을 넘길지는 `planLiveContinuity` 가 고르고, 어떻게 흡수할지는 커널이 정한다.
          */
+        /*
+         * ── **재개점에서 미러를 되세운다** (2026-08-24) ────────────────────────────
+         *
+         * 이 자리에서 미러는 오랫동안 되찾은 상태를 **버렸다**. 전제는 「진실은 원천에 있으니 다음 계측이
+         * 정정한다」였고 라이브 피드에서는 옳았다. 그런데 원본이 **커서 증분**으로 말하는 현장에서는 그
+         * 정정이 오지 않는다: 커서가 따라잡힌 뒤 원본이 변하지 않으면 미러는 영구히 빈 채로 남는다.
+         * 그리고 그 빈 채로 화면이 「이상 없음」을 보였다 — 사실이 사라지는 동안 화면이 안심시킨 것이다.
+         *
+         * 되돌리는 것은 **상태가 아니라 재개점**이다. 상태만 심으면 그 뒤를 이어 접은 결과가 0부터 접은
+         * 결과와 조용히 달라진다(리듀서는 보류된 담김·집계 중인 수량도 든다). 그 동치는 커널 시험이
+         * 증명한다(`observed-checkpoint.test.ts` — 재개점 + 꼬리 == 0부터 접기).
+         *
+         * 씨앗은 **그 공장이 아직 그 공장일 때만** 오고, 마지막 체크포인트 이후의 사실은 이미 접혀 들어
+         * 있다(`warmSeedFor`). 씨앗이 없으면 전과 같이 빈 채로 시작한다 — 지어내지 않는다.
+         */
+        const seed = this.recovered[key]?.fold?.reducer;
+        if (seed) {
+            if (typeof kernel.restoreObserved !== 'function') {
+                (0, log_js_1.twinWarn)(`[twin-engine] "${id}": a fold seed is stored but this kernel cannot take it (no restoreObserved) — ` +
+                    'the mirror starts empty and waits for the source to re-tell everything. Upgrade the kernel.');
+            }
+            else {
+                try {
+                    kernel.restoreObserved(seed);
+                    const st = kernel.getSnapshot?.();
+                    (0, log_js_1.twinLog)(`[twin-engine] mirror "${id}" resumed from the stored fold seed at revision ${this.recovered[key]?.revision} — ` +
+                        `items ${st?.items?.length ?? 0} · orders ${st?.orders?.length ?? 0} · tasks ${st?.tasks?.length ?? 0} ` +
+                        '(the journal is not folded from the beginning).');
+                    if (this.recovered[key]?.fold?.oee)
+                        inst.oee?.restore(this.recovered[key].fold.oee);
+                }
+                catch (err) {
+                    /* 되세우기가 실패해도 미러는 돌아야 한다 — 다만 무엇을 잃었는지 말한다. */
+                    (0, log_js_1.twinWarn)(`[twin-engine] "${id}": could not resume from the stored fold seed — starting empty: ${err?.message ?? err}`);
+                }
+            }
+        }
         this.seedLiveContinuity(domainId, id, kernel);
         delete this.recovered[key];
         /* 라이브 바인딩(data 채널) subdomain 필터용 Domain 1회 해석(sim 과 동일). */
@@ -2040,9 +2176,9 @@ class TwinEngine {
          * 체크포인트 캐시 우선(O(1) + 라이브 파생상태 보존), 없으면 저널 replay 폴백(부팅과 같은 순서).
          */
         if (!this.recovered[key] && reg.purpose !== 'bench') {
-            const cached = await this.loadSnapshot(domainId, instanceId).catch(() => null);
+            const cached = await this.warmSeedFor(domainId, instanceId).catch(() => null);
             if (cached?.state) {
-                this.recovered[key] = { revision: cached.revision, state: cached.state };
+                this.recovered[key] = cached;
             }
             else {
                 const state = await this.recover(domainId, instanceId).catch(() => null);
@@ -2085,6 +2221,24 @@ class TwinEngine {
             const reg = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
             if (!reg?.model)
                 throw new Error(`instance "${instanceId}" not provisioned (no model)`);
+            /*
+             * ── **미러도 씨앗을 여기서 확보한다** (2026-08-24) ────────────────────────
+             *
+             * 이 줄이 없어서 미러는 저장된 체크포인트를 **한 번도 읽지 않았다.** `startLive` 는 동기라 스스로
+             * 캐시를 읽을 수 없고 `recovered` 에 담겨 있기를 기대하는데, 그것을 담는 곳은 `bootstrap` 과
+             * `start` 뿐이었다 — 그리고 미러의 실제 기동 경로는 **여기**다. 그래서 「읽는 쪽·쓰는 쪽이 다
+             * 있는데 아무 일도 일어나지 않는」 상태가 됐다.
+             *
+             * 이것은 `start` 가 이미 배운 교훈과 같은 자리다: 부팅 순서에 기대면 어떤 날은 상태가 살아나고
+             * 어떤 날은 조용히 빈 채로 뜬다 — **재현되지 않는 결함이 가장 나쁘다.** 그래서 순서에 기대지 않고
+             * 이 자리에서 확보한다(이미 담겨 있으면 그것을 쓴다).
+             */
+            const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
+            if (!this.recovered[key]) {
+                const seed = await this.warmSeedFor(domainId, instanceId).catch(() => null);
+                if (seed?.state)
+                    this.recovered[key] = seed;
+            }
             return this.startLive(instanceId, domainId, reg.kind, reg.model);
         }
         if (mode === 'resume') {
@@ -3416,6 +3570,45 @@ class TwinEngine {
         if (ledger)
             (0, ingest_health_js_1.clearReadFailure)(ledger);
     }
+    /**
+     * **읽었는데 창을 넘길 수 없다**를 적는다 — 위와 **조치가 반대인** 사실이다(§`recordCursorStall`).
+     *
+     * 이 문이 없던 동안 이 사실이 `recordIngestReadFailure` 로 나갔다. 그래서 화면이 「원본에 닿지
+     * 못한다」고 말했는데 원본은 **답한** 상태였고, 그 답의 모양이 커서를 이긴 것이었다(한 시각에 한
+     * 페이지보다 많은 행). 사람은 원본을 의심하고 기다리는데 **기다림으로는 영원히 풀리지 않는다.**
+     *
+     * 조치가 반대인 두 사실을 한 이름으로 부르면 그 이름은 정보가 아니라 오해다.
+     */
+    static recordIngestCursorStall(domainId, instanceId, reason, nowMs = Date.now(), stream) {
+        const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
+        const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = (0, ingest_health_js_1.newIngestLedger)());
+        (0, ingest_health_js_1.recordCursorStall)(ledger, reason, nowMs, stream);
+    }
+    /**
+     * **원본에 있는데 세우지 않은 것을 적는다** — 이유와 수(§`IngestLedger.withheld`).
+     *
+     * 어댑터가 주기마다 불러도 된다: 장부가 이유로 묶어 **마지막 수로 덮는다**(누적하지 않는다).
+     * `count: 0` 은 「그 이유가 풀렸다」로 그 줄을 지운다 — 조용히 그치면 낡은 수가 남는다.
+     */
+    static recordIngestWithheld(domainId, instanceId, reason, count, nowMs = Date.now()) {
+        const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
+        const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = (0, ingest_health_js_1.newIngestLedger)());
+        if (!(count > 0)) {
+            if (ledger.withheld) {
+                ledger.withheld = ledger.withheld.filter(w => w.reason !== reason);
+                if (!ledger.withheld.length)
+                    delete ledger.withheld;
+            }
+            return;
+        }
+        (0, ingest_health_js_1.recordWithheld)(ledger, reason, count, nowMs);
+    }
+    /** 창을 넘겼다 — 정체 기록을 지운다(풀린 정체가 화면에 남아 있으면 그것도 거짓이다). */
+    static clearIngestCursorStall(domainId, instanceId) {
+        const ledger = this.ingestLedgers[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        if (ledger)
+            (0, ingest_health_js_1.clearCursorStall)(ledger);
+    }
     /**
      * 저널에 **적은 것**을 같은 장부에 남긴다 — 유입과 같은 10분 창에.
      *