@things-factory/headless-twin 10.0.12 → 10.0.14

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

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TwinEngine = void 0;
+const log_js_1 = require("./log.js");
 const shell_1 = require("@things-factory/shell");
 /* 저널을 자를 조건은 SQL 이 안다 — 관용구만 쓴다(원시 SQL 은 5개 드라이버에서 갈라진다). */
 const typeorm_1 = require("typeorm");
@@ -41,17 +42,57 @@ const kpi_query_js_1 = require("./kpi-query.js");
 const node_crypto_1 = require("node:crypto");
 const entity_delta_js_1 = require("@things-factory/headless-twin/dist-shared/entity-delta.js");
 const load_meter_js_1 = require("./load-meter.js");
+const loop_lag_js_1 = require("./loop-lag.js");
+const touched_items_js_1 = require("@things-factory/headless-twin/dist-shared/touched-items.js");
 const structure_diff_js_1 = require("./structure-diff.js");
 const oee_accumulator_js_1 = require("./oee-accumulator.js");
 const live_attentions_js_1 = require("./live-attentions.js");
 const attention_digest_js_1 = require("./attention-digest.js");
 const live_feed_registry_js_1 = require("./live-feed-registry.js");
+const ingest_health_js_1 = require("./ingest-health.js");
 const twin_kernel_1 = require("@operato/twin-kernel");
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
 const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel');
 const KERNELS = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel };
 /**
- * 종류 문자열 → 커널. **모르는 값이면 던진다.**
+ * 시각축을 구할 때 한 번에 띄우는 트윈 수.
+ *
+ * 트윈마다 왕복이 둘이라, 공간에 트윈이 수백이면 동시 왕복도 수백이 된다 — 커넥션 풀이 마르면 이
+ * 함수 하나 때문에 다른 질의가 줄을 선다. 20이면 왕복 40개로 지연은 감추면서 풀은 남는다.
+ */
+const TIME_RANGE_FANOUT = 20;
+/**
+ * DB 가 준 시각을 epoch ms 로 — **모양이 드라이버마다 다르다.**
+ *
+ * 집계(MIN/MAX)의 반환은 드라이버가 정한다: sqlite 는 문자열, pg·mysql·mssql 은 `Date`. 엔티티
+ * 하이드레이션을 건너뛰면 TypeORM 의 날짜 변환도 함께 건너뛰므로 받는 쪽에서 한 번 정규화한다.
+ *
+ * ── 시간대를 잃지 않는다 (시험이 잡았다) ────────────────────────────────────
+ * 처음에 `Date.parse(String(v))` 로 두었더니 **9시간이 밀렸다.** sqlite 는 UTC 로 저장한 값을
+ * `2026-01-15 09:00:00.000` 처럼 **시간대 표시 없이** 돌려주는데, 그 형태를 `Date.parse` 는 **로컬
+ * 시각**으로 읽는다(여기가 KST 라 UTC 00:00 이 됐다). 원래 코드가 이 함정을 피한 것은 TypeORM 이
+ * 하이드레이션에서 먼저 `Date` 로 바꿔 줬기 때문이다 — 그 단계를 건너뛴 대가를 여기서 치른다.
+ *
+ * 그래서 시간대 표시가 **없는 문자열은 UTC 로 읽는다**(TypeORM 이 UTC 로 적으므로). 표시가 있으면
+ * 그대로 믿고, `Date` 는 손대지 않는다.
+ *
+ * 읽을 수 없는 값은 **없음(`null`)** 이다 — 0 으로 떨어뜨리면 1970년이 시각축의 시작이 된다.
+ */
+function parseTime(v) {
+    if (v == null)
+        return null;
+    if (v instanceof Date)
+        return Number.isFinite(v.getTime()) ? v.getTime() : null;
+    const s = String(v).trim();
+    if (!s)
+        return null;
+    /* 끝에 `Z` 나 `±hh:mm` 이 붙어 있으면 시간대를 아는 문자열이다 — 그대로 믿는다. */
+    const zoned = /(?:Z|[+-]\d{2}:?\d{2})$/.test(s);
+    const t = Date.parse(zoned ? s : `${s.replace(' ', 'T')}Z`);
+    return Number.isFinite(t) ? t : null;
+}
+/**
+ * 종류 문자열 → 커널. **모르는 값이면 오류를 낸다.**
  *
  * 예전에는 표를 찾고 없으면 WmsKernel 로 떨어졌다. `kind` 는 검증 없는 자유 문자열(`@Arg('kind') kind: string`)
  * 이라 오타 하나·대소문자 하나로 야드/생산 트윈이 **조용히 창고 커널로 돌았다.** 오류가 없으니 화면에는
@@ -66,6 +107,33 @@ function kernelFor(kind) {
         throw new Error(`unknown twin kind "${kind}" — expected one of ${Object.keys(KERNELS).join(' | ')}`);
     return K;
 }
+/** `observe()` 를 갖지 않은 커널을 만난 적이 있는가 — 경고를 한 번만 낸다(틱마다 쏟지 않는다). */
+let observeUnavailableWarned = false;
+/**
+ * **이 커널의 진실이 원본에서 온다고 선언한다** — 그리고 선언이 닿지 않았으면 말한다.
+ *
+ * ── 무엇이 틀렸나 (2026-08-21) ──────────────────────────────────────────────
+ * 예전에는 `kernel.observe?.()` 였다. 옵셔널 호출이라 **메서드가 없으면 조용히 아무것도 하지 않는다.**
+ * 설치된 커널 0.7.39 에는 그 메서드가 없으므로, 지금 배포본에서는 미러가 관측 구동으로 선언되지
+ * 않는다 — 그런데 코드를 읽으면 선언한 것처럼 보인다.
+ *
+ * 그 차이가 실제 거동을 가른다: 관측 구동은 원본의 빈틈을 받아들이고 세지만, 시뮬로 오인된 미러는
+ * **멈춘다.** 즉 「관용이 켜진 줄 알았는데 안 켜져 있다」가 조용히 지나가고, 장애가 났을 때 원인이
+ * 커널에 있는 것처럼 보인다 — 원인은 버전이다.
+ *
+ * 그래서 옵셔널 호출을 없애고, 없으면 **한 번 경고한다.** 커널이 배포되면 이 경고는 사라진다.
+ */
+function declareObserved(kernel, what) {
+    if (typeof kernel?.observe === 'function') {
+        kernel.observe();
+        return;
+    }
+    if (observeUnavailableWarned)
+        return;
+    observeUnavailableWarned = true;
+    (0, log_js_1.twinWarn)(`[twin-engine] ${what}: kernel has no observe() — this mirror is not declared observation-driven. ` +
+        'Source gaps will stop it instead of being tolerated and counted. Deploy a kernel that provides observe().');
+}
 class TwinEngine {
     /*
      * 기동 중인 런타임 — **키는 `runtimeKey(domainId, instanceId)`** 다(`runtime-key.ts` 에 이유).
@@ -85,13 +153,45 @@ class TwinEngine {
      * 멈춘다 — HTTP·구독·다른 트윈의 틱까지. 실측으로 `order-check` 의 틱 하나가 34.9초였고, 그 사이
      * 구독자가 아무것도 빼내지 못해 pubsub 이 넘쳐 프로세스가 죽었다.
      *
-     * 방송 반복은 걷어냈지만(`flushLiveBroadcasts` 로 병합) **커널 틱 자체는 여전히 메인 루프에 있다.**
+     * 브로드캐스팅 반복은 걷어냈지만(`flushLiveBroadcasts` 로 병합) **커널 틱 자체는 여전히 메인 루프에 있다.**
      * 근본 해결은 분산이고 그것은 이연됐다 — 그때까지의 안전망이 이 셋이다.
      *
      * 판정을 예산(500ms)이 아니라 **굶김 문턱**으로 따로 둔다: 조금 느린 트윈은 계기판이 말하게 두고
      * (경고), 호스트를 굶기는 트윈만 멈춘다. 한 번으로 멈추지 않는다 — 웜스타트 직후의 첫 틱은 원래
      * 무겁다(복구한 상태를 처음 접는다). **연속**으로 이어질 때가 구조적으로 느린 것이다.
      */
+    /*
+     * ── 틱을 **한 순간에 몰지 않는다** (2026-08-21 실측) ────────────────────────
+     * 트윈마다 `setInterval(TICK_MS)` 를 부팅 때 나란히 세우면, 스무 개가 **같은 밀리초에** 깨어난다.
+     * 각자의 틱이 짧아도(실측: 물품 2,400 개에서 0.23ms) 그 순간에는 스무 개가 한 줄로 붙어 실행되고,
+     * 그 사이 도착한 HTTP 요청은 전부 뒤에서 기다린다. 초당 한 번의 정체가 「누를 때마다 걸린다」로
+     * 나타나는 자리다.
+     *
+     * 그래서 첫 발화만 간격 안에서 **고르게 흩는다** — 총 작업량은 같고 한 순간의 최대치만 낮아진다.
+     * 트윈이 간격보다 많아지면 다시 겹치므로, 그때는 이 흩기가 아니라 분산이 답이다(이연됨).
+     */
+    /** 부팅 때 트윈 하나를 되살린 뒤 루프를 비워 주는 시간(ms) — 그 사이 도착한 요청이 처리된다. */
+    static { this.BOOT_YIELD_MS = 25; }
+    static { this.tickPhase = 0; }
+    /**
+     * 흩어진 첫 발화 뒤 주기 틱. **핸들은 항상 진짜 타이머**다 — 정지하는 쪽이 `clearInterval(inst.timer)`
+     * 하나로 끝내야 하므로, 첫 발화 전에는 그 `setTimeout` 을, 이후에는 `setInterval` 을 같은 자리에 둔다
+     * (감싼 객체를 주면 `clearInterval` 이 아무 일도 하지 않고 트윈이 멈추지 않는다 — 조용한 결함이 된다).
+     */
+    static startTickTimer(fn, hold) {
+        const spread = Math.max(1, Math.round(this.TICK_MS / 20));
+        const offset = (this.tickPhase = (this.tickPhase + spread) % this.TICK_MS);
+        const first = setTimeout(() => {
+            const interval = setInterval(fn, this.TICK_MS);
+            if (typeof interval?.unref === 'function')
+                interval.unref();
+            hold(interval); // 정지 경로가 지울 대상을 바꿔 준다
+            fn();
+        }, offset);
+        if (typeof first?.unref === 'function')
+            first.unref();
+        return first;
+    }
     /** 굶김 문턱 — 틱 간격의 배수(1초 간격이면 5초). 이 시간만큼 호스트가 멈춘다. */
     static { this.STARVE_FACTOR = 5; }
     /** 연속 몇 번이면 멈추나 — 3번이면 15초를 굶긴 셈이고, 그건 우연이 아니다. */
@@ -123,6 +223,30 @@ class TwinEngine {
     static { this.CHAIN_KEEP = 5; } // 최근 몇 지점을 들고 있나(그보다 과거는 0부터 접는다)
     static { this.SNAPSHOT_TTL_S = 7 * 24 * 3600; } // 7일 — 정상 다운타임 생존, 만료 시 저널 replay 폴백
     static { this.CHECKPOINT_MS = 20000; } // 체크포인트 주기(핫 브로드캐스트 경로와 분리, O(state) 스로틀)
+    /**
+     * **저널 보존 — 지우는 것은 선언이 있을 때만 한다.**
+     *
+     * ── 왜 필요한가 (2026-08-22 실측) ─────────────────────────────────────────
+     * 개발 저널이 시간당 **581,794행 · 0.85GB** 로 자랐다(하루 20GB). 데모 MES 트윈 셋이 전체의 **97%**
+     * 를 만들고 지우는 것이 없었다. 오늘 고친 것들은 「그 크기에서도 질의가 빠르게」이고, **크기 자체를
+     * 줄이는 것은 아무것도 없었다.** 그러면 며칠마다 같은 자리로 돌아온다.
+     *
+     * ── 그런데 저널을 지우는 것은 사실을 잃는 일이다 ──────────────────────────
+     * 그래서 세 규율을 지킨다.
+     *
+     *  ① **선언이 없으면 아무것도 지우지 않는다.** 기본값은 없음이다 — 조용히 지우는 편이 조용히 쌓는
+     *     것보다 나쁘다. 지우는 것은 사람이 정한다.
+     *  ② **체크포인트가 대신할 수 있는 만큼만.** 스냅샷이 없거나 그 리비전을 넘는 자리는 건드리지 않는다.
+     *     주석이 「만료 시 저널 replay 폴백」이라고 적어 둔 그대로 — 스냅샷이 사라지면 저널이 **유일한**
+     *     복구 수단이므로, 둘을 함께 잃으면 그 트윈의 상태는 되돌릴 수 없다.
+     *  ③ **지운 것을 말한다.** 몇 건을 어느 시각까지 지웠는지 로그에 남긴다. 조용히 줄어든 저널은
+     *     「없었던 일」과 구별되지 않는다.
+     *
+     * 그리고 보존 기간은 **스냅샷 TTL(7일)보다 짧을 수 없다.** 더 짧으면 스냅샷이 살아 있는데 그것이
+     * 가리키는 앞쪽 저널이 없는 구간이 생기고, 시간여행·계보 추적이 그 구간에서 조용히 빈다.
+     */
+    static { this.JOURNAL_RETENTION_DAYS = undefined; }
+    static { this.RETENTION_SWEEP_MS = 10 * 60 * 1000; } // 10분마다 한 번 — 지우는 일은 급하지 않다
     /** 최신 스냅샷을 cache-service 에 체크포인트(도메인+instanceId 키). display-only·비차단·오류흡수. */
     static async persistSnapshot(domainId, instanceId) {
         const inst = this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
@@ -136,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);
     }
     /**
      * 접기의 **재개점** — 리듀서 내부 상태 전부 + 가동 누적기.
@@ -148,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 });
@@ -168,7 +392,7 @@ class TwinEngine {
             return;
         await cache_service_1.cacheService
             .setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, value, this.SNAPSHOT_TTL_S)
-            .catch((err) => console.error(`[twin-engine] snapshot save fail "${instanceId}"`, err?.message ?? err));
+            .catch((err) => (0, log_js_1.twinError)(`[twin-engine] snapshot save fail "${instanceId}"`, err?.message ?? err));
     }
     /** 사슬 색인 — 어떤 리비전 지점을 들고 있나(최신순 아님, 오름차순). */
     static async chainIndex(domainId, instanceId) {
@@ -238,6 +462,104 @@ class TwinEngine {
         ]);
         return { revision: tip?.revision ?? 0, structureRev: newest?.rev ?? null };
     }
+    /**
+     * **저널을 보존 기간까지만 둔다** — 체크포인트가 대신할 수 있는 만큼만 지운다.
+     *
+     * 한 인스턴스에서 지우는 조건은 **둘 다** 만족해야 한다.
+     *
+     *  · `createdAt` 이 보존 기간보다 오래됐다 — **행이 쓰인 실제 시각**이 기준이다
+     *  · `revision` 이 **체크포인트 리비전 이하**다 — 그 앞은 스냅샷이 대신한다
+     *
+     * ── 왜 `eventTime` 이 아니라 `createdAt` 인가 (2026-08-22 실측으로 고침) ────
+     * 처음에 `eventTime` 으로 적었다. 그것은 **트윈의 시계**다 — 시뮬레이션은 자기 시계로 사건을 찍고,
+     * 그 시계는 실제 시각과 무관하게 앞서거나 뒤선다. 실측:
+     *
+     *   order-check   가장 늦은 eventTime = 2027-06-08   ← 실제 시각보다 10개월 앞
+     *   hatio-mx2     2026-01-01 ~ 지금                  ← 7개월치를 한 번에 지우게 된다
+     *
+     * 즉 「7일」이 트윈마다 다른 뜻이 된다: 시계가 앞선 트윈은 영원히 지워지지 않고, 과거부터 찍은 트윈은
+     * 거의 전부가 한 번에 지워진다. **보존은 저장 나이의 문제**이고 저장 나이는 실제 시계다.
+     *
+     * `createdAt` 은 그 행이 DB 에 쓰인 시각이고 1,599만 행 전부 채워져 있다(확인함). 도메인 시각을
+     * 정책에 쓰지 않는다 — 그 둘을 섞으면 시뮬과 미러에서 같은 설정이 다르게 동작한다.
+     *
+     * 스냅샷이 없으면 **그 인스턴스는 건드리지 않는다.** 저널이 유일한 복구 수단인 상태이므로, 지우면
+     * 그 트윈의 상태를 되돌릴 수 없다. 「지울 수 없었다」는 사실도 함께 센다 — 조용히 넘기면 「보존이
+     * 도는데 왜 안 줄어드나」가 된다.
+     *
+     * `createdAt` 이 빈 옛 행은 **지우지 않는다**(시각을 모르는 것을 「오래됐다」로 읽지 않는다).
+     *
+     * 드라이버 다섯을 다 지나야 하므로 raw SQL 을 쓰지 않는다 — 조건 삭제는 쿼리빌더가 이식한다.
+     */
+    static async pruneJournal(domainId) {
+        /* 도메인의 정책이 먼저다(§`retentionDaysOf`). 없으면 프로세스 기본값. 둘 다 없으면 지우지 않는다. */
+        const perDomain = this.retentionDaysOf ? await this.retentionDaysOf(domainId).catch(() => undefined) : undefined;
+        const days = perDomain ?? this.JOURNAL_RETENTION_DAYS;
+        if (!days || days <= 0)
+            return { deleted: 0, instances: 0, skipped: [] };
+        /* 보존 기간은 스냅샷 TTL 보다 짧을 수 없다 — 짧으면 스냅샷이 가리키는 앞쪽이 비는 구간이 생긴다. */
+        const minDays = this.SNAPSHOT_TTL_S / 86400;
+        const effectiveDays = Math.max(days, minDays);
+        if (effectiveDays !== days) {
+            (0, log_js_1.twinWarn)(`[twin-engine] journal retention ${days}일은 스냅샷 TTL(${minDays}일)보다 짧다 — ${effectiveDays}일로 올린다 ` +
+                '(더 짧으면 스냅샷이 살아 있는데 그것이 가리키는 앞쪽 저널이 없는 구간이 생긴다)');
+        }
+        const cutoff = new Date(Date.now() - effectiveDays * 86400 * 1000);
+        const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId } } });
+        let deleted = 0;
+        let instances = 0;
+        const skipped = [];
+        for (const r of rows) {
+            const snap = await this.loadSnapshot(domainId, r.instanceId).catch(() => null);
+            const upTo = Number(snap?.revision ?? 0);
+            if (!upTo) {
+                /* 스냅샷이 없다 — 저널이 유일한 복구 수단이므로 손대지 않는다. */
+                skipped.push(r.instanceId);
+                continue;
+            }
+            const res = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+                .createQueryBuilder()
+                .delete()
+                .from(twin_event_js_1.TwinEvent)
+                .where('domain_id = :domainId', { domainId })
+                .andWhere('instance_id = :instanceId', { instanceId: r.instanceId })
+                .andWhere('revision <= :upTo', { upTo })
+                .andWhere('created_at IS NOT NULL')
+                .andWhere('created_at < :cutoff', { cutoff })
+                .execute();
+            const n = res.affected ?? 0;
+            if (n > 0) {
+                deleted += n;
+                instances++;
+                /* **지운 것을 말한다** — 조용히 줄어든 저널은 「없었던 일」과 구별되지 않는다. */
+                (0, log_js_1.twinLog)(`[twin-engine] journal pruned "${r.instanceId}" — ${n}건 (revision ≤ ${upTo} · ${cutoff.toISOString()} 이전). ` +
+                    '그 앞은 체크포인트가 대신한다.');
+            }
+        }
+        if (skipped.length) {
+            (0, log_js_1.twinLog)(`[twin-engine] journal prune skipped ${skipped.length} instance(s) with no checkpoint — ` +
+                `저널이 유일한 복구 수단이라 손대지 않았다: ${skipped.slice(0, 5).join(', ')}${skipped.length > 5 ? ' …' : ''}`);
+        }
+        return { deleted, instances, skipped };
+    }
+    /** 보존 정리 주기 기동(1회) — 선언이 없으면 아무것도 하지 않는다. */
+    static startRetentionLoop(domainId) {
+        if (this.retentionTimer)
+            return;
+        /*
+         * 걸지 않는 조건: 프로세스 기본값도 없고 **도메인에 물을 길도 없을** 때다. 시임이 심겨 있으면
+         * 기본값이 없어도 걸어야 한다 — 그 도메인이 자기 값을 가질 수 있다.
+         */
+        if (!this.JOURNAL_RETENTION_DAYS && !this.retentionDaysOf)
+            return;
+        this.retentionTimer = setInterval(() => {
+            this.pruneJournal(domainId).catch(err => (0, log_js_1.twinError)('[twin-engine] journal prune failed', err?.message ?? err));
+        }, this.RETENTION_SWEEP_MS);
+        if (typeof this.retentionTimer?.unref === 'function')
+            this.retentionTimer.unref();
+        (0, log_js_1.twinLog)(`[twin-engine] journal retention on — ${this.JOURNAL_RETENTION_DAYS ?? '(도메인 정책)'}일 · ` +
+            `${this.RETENTION_SWEEP_MS / 60000}분마다`);
+    }
     /** 체크포인트 루프 기동(1회) — 라이브 인스턴스들의 최신 스냅샷을 주기 영속. */
     static startCheckpointLoop() {
         if (this.checkpointTimer)
@@ -245,7 +567,7 @@ class TwinEngine {
         this.checkpointTimer = setInterval(() => {
             for (const [key, inst] of Object.entries(this.instances)) {
                 const { instanceId } = (0, runtime_key_js_1.parseRuntimeKey)(key);
-                this.persistSnapshot(inst.domainId, instanceId).catch(err => console.error(`[twin-engine] snapshot checkpoint fail "${instanceId}"`, err?.message ?? err));
+                this.persistSnapshot(inst.domainId, instanceId).catch(err => (0, log_js_1.twinError)(`[twin-engine] snapshot checkpoint fail "${instanceId}"`, err?.message ?? err));
             }
         }, this.CHECKPOINT_MS);
         if (typeof this.checkpointTimer?.unref === 'function')
@@ -256,6 +578,8 @@ class TwinEngine {
      * 라이브 tick 재개(sim 결정적 re-run / live 인제스트 지속)는 후속. 여기선 상태 복원 + 노출.
      */
     static async bootstrap() {
+        /* 부팅부터 잰다 — 사람이 가장 답답한 구간이 여기이고, 그 구간을 재지 않으면 값으로 말할 수 없다. */
+        loop_lag_js_1.loopLag.start();
         try {
             const repo = (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance);
             const rows = await repo.find({ where: { status: 'running' } });
@@ -264,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;
                     /*
                      * **「웜스타트했다」고 말하지 않는다** — 여기서는 상태를 **찾아 둔 것**뿐이다.
                      *
@@ -276,22 +599,39 @@ class TwinEngine {
                      * 로그만 읽으면 심긴 줄 알게 된다 — 실제로 그렇게 읽고 재기동 뒤 지속시간이 사라진 것을
                      * 데이터 문제로 오진할 뻔했다.
                      */
-                    console.log(`[twin-engine] found cached state for "${row.instanceId}" → revision ${cached.revision} (seeded at start).`);
+                    (0, log_js_1.twinLog)(`[twin-engine] found cached state for "${row.instanceId}" → revision ${cached.revision} (seeded at start).`);
                     continue;
                 }
                 const state = await this.recover(row.domainId, row.instanceId).catch(() => null);
                 if (state) {
                     this.recovered[(0, runtime_key_js_1.runtimeKey)(row.domainId, row.instanceId)] = { revision: state.revision, state };
-                    console.log(`[twin-engine] recovered "${row.instanceId}" from journal → revision ${state.revision}.`);
+                    (0, log_js_1.twinLog)(`[twin-engine] recovered "${row.instanceId}" from journal → revision ${state.revision}.`);
                 }
             }
-            /* 상태만 되찾는 것으로는 **도는 트윈이 되지 않는다** — 런타임까지 되살린다(아래). */
-            for (const row of rows)
+            /*
+             * 상태만 되찾는 것으로는 **도는 트윈이 되지 않는다** — 런타임까지 되살린다(아래).
+             *
+             * 되살리기 사이에 **루프를 한 번 비워 준다** (2026-08-21). 웜스타트 하나가 물품 수천 개를 접으므로
+             * 스무 개를 연달아 하면 그 시간 내내 HTTP 가 서지 않는다 — 서버는 이미 `Server ready` 를 찍은
+             * 뒤라서, 사람에게는 「열렸는데 아무 반응이 없는 화면」으로 보인다. 총 시간은 같고, 그 사이에
+             * 도착한 요청이 처리될 틈만 생긴다.
+             */
+            for (const row of rows) {
                 await this.resumeRow(row);
+                await new Promise(resolve => setTimeout(resolve, this.BOOT_YIELD_MS));
+            }
             this.startCheckpointLoop(); // 이후 기동되는 라이브 인스턴스의 최신 스냅샷을 주기 영속
+            /*
+             * 보존 정리 — **선언이 있을 때만** 돈다(§`JOURNAL_RETENTION_DAYS`). 도메인마다 한 번 건다.
+             * 체크포인트 루프 뒤에 두는 이유: 지울 수 있는 경계가 스냅샷이므로, 스냅샷을 남기는 쪽이 먼저
+             * 돌아야 첫 정리가 실제로 지울 것을 갖는다.
+             */
+            for (const domainId of new Set(rows.map(r => r.domainId).filter(Boolean))) {
+                this.startRetentionLoop(domainId);
+            }
         }
         catch (err) {
-            console.error('[twin-engine] recovery scan failed', err);
+            (0, log_js_1.twinError)('[twin-engine] recovery scan failed', err);
         }
     }
     /**
@@ -327,18 +667,21 @@ class TwinEngine {
             return;
         }
         try {
+            /*
+             * **선언된 모드로 되살리는 판단은 한 곳에 있다**(`startFromRegistry`) — 2026-08-20.
+             *
+             * 예전에는 이 자리에서 `resync` 를 갈라 `startLive` 를 불렀다. 그래서 부팅으로 살아난 미러는
+             * 관측 구동이었지만 **사람이 화면에서 시작한 미러는 시뮬로 떴다**(그 문에는 갈림이 없었다).
+             * 같은 선언이 두 결과를 내지 않도록 갈림을 문 안으로 옮겼다.
+             */
+            await this.startFromRegistry(domainId, instanceId);
             if (row.restartPolicy === 'resync') {
-                if (!row.model)
-                    throw new Error('no model');
-                /* 시각 기준은 **공간**이 갖는다 — 교대의 HH:MM 을 어느 기준으로 읽나(라이브 기동과 같은 규칙). */
-                this.startLive(instanceId, domainId, row.kind, await this.withSpaceTimeBase(row.model, domainId));
                 /* 계측을 나르는 피드는 커넥터의 것이다 — 레퍼런스 계층이 부팅 훅에서 다시 붙인다
                    (`resumeReferenceLiveFeeds`). 여기서 어댑터를 아는 것은 계층을 거꾸로 잇는 것이다. */
-                console.log(`[twin-engine] resumed mirror "${instanceId}" — feed reattach is the reference layer's job.`);
+                (0, log_js_1.twinLog)(`[twin-engine] resumed mirror "${instanceId}" — feed reattach is the reference layer's job.`);
             }
             else {
-                await this.startFromRegistry(domainId, instanceId);
-                console.log(`[twin-engine] resumed ${row.restartPolicy} "${instanceId}".`);
+                (0, log_js_1.twinLog)(`[twin-engine] resumed ${row.restartPolicy} "${instanceId}".`);
             }
         }
         catch (err) {
@@ -347,12 +690,12 @@ class TwinEngine {
     }
     /** 되살리지 못한 행을 정직하게 적는다 — 「도는 중」이라 말하는 채로 두지 않는다. */
     static async markStopped(row, why) {
-        console.warn(`[twin-engine] "${row.instanceId}" not resumed (${why}) — registry says stopped now.`);
+        (0, log_js_1.twinWarn)(`[twin-engine] "${row.instanceId}" not resumed (${why}) — registry says stopped now.`);
         try {
             await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).update({ id: row.id }, { status: 'stopped' });
         }
         catch (e) {
-            console.error(`[twin-engine] could not mark "${row.instanceId}" stopped — registry now lies about it.`, e?.message);
+            (0, log_js_1.twinError)(`[twin-engine] could not mark "${row.instanceId}" stopped — registry now lies about it.`, e?.message);
         }
     }
     /**
@@ -388,10 +731,10 @@ class TwinEngine {
         const plan = (0, warm_start_js_1.planWarmStart)(this.recovered[(0, runtime_key_js_1.runtimeKey)(domainId, id)]?.state, purpose, typeof hydrate === 'function');
         if (plan.action === 'skip') {
             if (plan.reason === 'bench') {
-                console.log(`[twin-engine] "${id}" is a bench twin — starting empty on purpose (seeding would skew the measurement).`);
+                (0, log_js_1.twinLog)(`[twin-engine] "${id}" is a bench twin — starting empty on purpose (seeding would skew the measurement).`);
             }
             else if (plan.reason === 'unsupported') {
-                console.warn(`[twin-engine] kernel for "${id}" cannot be warm-started (no hydrateObserved) — it starts with structure only, so held stock will read as zero.`);
+                (0, log_js_1.twinWarn)(`[twin-engine] kernel for "${id}" cannot be warm-started (no hydrateObserved) — it starts with structure only, so held stock will read as zero.`);
             }
             return;
         }
@@ -408,10 +751,10 @@ class TwinEngine {
             /* 「언제부터인가」도 말한다 — 잃으면 지속된 조건이 모두 「방금」으로 보인다. */
             ...(plan.attentionSinceCount ? [`${plan.attentionSinceCount} attention start time(s)`] : [])
         ].join(', ');
-        console.log(`[twin-engine] warm-started "${id}" — restored ${restored}.`);
+        (0, log_js_1.twinLog)(`[twin-engine] warm-started "${id}" — restored ${restored}.`);
         /* 뺀 것은 조용히 넘기지 않는다 — 지어내지 않았다는 사실 자체를 말해야 화면의 빈칸이 읽힌다. */
         if (plan.ordersWithoutDemand > 0) {
-            console.warn(`[twin-engine] "${id}": ${plan.ordersWithoutDemand} order(s) could not be restored — they carry progress only, ` +
+            (0, log_js_1.twinWarn)(`[twin-engine] "${id}": ${plan.ordersWithoutDemand} order(s) could not be restored — they carry progress only, ` +
                 'with no requested/fulfilled counts, so the remaining demand is unknown. They are left out rather than guessed.');
         }
     }
@@ -436,7 +779,7 @@ class TwinEngine {
         const declared = model?.localDurations;
         if (declared && Object.keys(declared).length) {
             if (typeof kernel?.declareDurations !== 'function') {
-                console.warn(`[twin-engine] "${id}": this facility declared ${Object.keys(declared).length} operation duration(s) but the kernel cannot consume them ` +
+                (0, log_js_1.twinWarn)(`[twin-engine] "${id}": this facility declared ${Object.keys(declared).length} operation duration(s) but the kernel cannot consume them ` +
                     '(declareDurations missing — kernel needs publishing). The simulation keeps running on built-in constants, and specCoverage() will keep reporting "default".');
             }
             else {
@@ -445,7 +788,7 @@ class TwinEngine {
                 }
                 catch (err) {
                     /* 커널이 거절한 값은 조용히 넘기지 않는다 — 화면은 「넣었습니다」라고 말한 값이다. */
-                    console.warn(`[twin-engine] "${id}": declared operation duration rejected by the kernel — ${err?.message ?? err}`);
+                    (0, log_js_1.twinWarn)(`[twin-engine] "${id}": declared operation duration rejected by the kernel — ${err?.message ?? err}`);
                 }
             }
         }
@@ -453,7 +796,7 @@ class TwinEngine {
         const params = model?.localParams;
         if (params && Object.keys(params).length) {
             if (typeof kernel?.declareParameters !== 'function') {
-                console.warn(`[twin-engine] "${id}": this facility declared operation parameters for ${Object.keys(params).length} operation(s) but the kernel cannot consume them ` +
+                (0, log_js_1.twinWarn)(`[twin-engine] "${id}": this facility declared operation parameters for ${Object.keys(params).length} operation(s) but the kernel cannot consume them ` +
                     '(declareParameters missing — kernel needs publishing). Yield and setup keep running on built-in constants.');
             }
             else {
@@ -461,7 +804,7 @@ class TwinEngine {
                     kernel.declareParameters(params);
                 }
                 catch (err) {
-                    console.warn(`[twin-engine] "${id}": declared operation parameter rejected by the kernel — ${err?.message ?? err}`);
+                    (0, log_js_1.twinWarn)(`[twin-engine] "${id}": declared operation parameter rejected by the kernel — ${err?.message ?? err}`);
                 }
             }
         }
@@ -469,7 +812,7 @@ class TwinEngine {
         if (!ops?.length)
             return;
         if (typeof kernel?.loadOperations !== 'function') {
-            console.warn(`[twin-engine] "${id}": model declares ${ops.length} operation spec(s) but the kernel cannot consume them (loadOperations missing — kernel needs publishing). Simulation will use built-in default durations.`);
+            (0, log_js_1.twinWarn)(`[twin-engine] "${id}": model declares ${ops.length} operation spec(s) but the kernel cannot consume them (loadOperations missing — kernel needs publishing). Simulation will use built-in default durations.`);
             return;
         }
         kernel.loadOperations(ops);
@@ -495,7 +838,7 @@ class TwinEngine {
         if (!chained) {
             /* 왜 못 넣었는지 한 번만 알린다 — 이동시간이 상수로 남은 이유를 모르고 지나가지 않게. */
             if (travel.reasons.length)
-                console.warn(`[twin-engine] "${instanceId}": no duration estimator installed — ${travel.reasons.join('; ')}`);
+                (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": no duration estimator installed — ${travel.reasons.join('; ')}`);
             return;
         }
         kernel.durationEstimator = chained;
@@ -508,25 +851,25 @@ class TwinEngine {
         const yields = await this.measuredYield(domainId, instanceId);
         if (yields?.estimator) {
             if (typeof kernel.yieldOf !== 'function') {
-                console.warn(`[twin-engine] "${instanceId}": learned yield for ${Object.keys(yields.learned).length} operation kind(s) but the kernel cannot consume it ` +
+                (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": learned yield for ${Object.keys(yields.learned).length} operation kind(s) but the kernel cannot consume it ` +
                     '(yieldOf missing — kernel needs publishing). Yield keeps running on the declared value or the built-in constant.');
             }
             else {
                 kernel.yieldEstimator = yields.estimator;
-                console.log(`[twin-engine] "${instanceId}": measured yield installed — ${Object.entries(yields.learned)
+                (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": measured yield installed — ${Object.entries(yields.learned)
                     .map(([k, v]) => `${k}=${Math.round(v * 1000) / 10}%(${yields.samples[k].good + yields.samples[k].scrap}건)`)
                     .join(', ')}${yields.skipped.length ? ` · 표본 부족으로 뺀 종류: ${yields.skipped.map(s => `${s.kind}(${s.judged})`).join(', ')}` : ''}`);
             }
         }
         else if (yields?.skipped.length) {
             /* 배운 것이 없고 버린 것만 있으면 그 사실도 말한다 — 「이력이 없다」와 「표본이 모자라다」는 다르다. */
-            console.log(`[twin-engine] "${instanceId}": no measured yield yet — samples below ${yields.minSamples}: ${yields.skipped
+            (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": no measured yield yet — samples below ${yields.minSamples}: ${yields.skipped
                 .map(s => `${s.kind}(${s.judged})`)
                 .join(', ')}`);
         }
         const learned = Object.keys(measured?.learned ?? {});
         const spread = Object.keys(measured?.spreads ?? {});
-        console.log(`[twin-engine] "${instanceId}": duration estimator installed — measured kinds: ${learned.length ? learned.join(',') : 'none'}` +
+        (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": duration estimator installed — measured kinds: ${learned.length ? learned.join(',') : 'none'}` +
             ` (with observed spread: ${spread.length ? spread.join(',') : 'none'})` +
             `${travel.estimator ? `, travel from distance (speeds: ${Object.keys(travel.speedsByKind).join(',')})` : `, travel not derived (${travel.reasons.join('; ')})`}`);
     }
@@ -574,7 +917,7 @@ class TwinEngine {
             yields = (0, measured_yield_js_1.buildYieldEstimator)(kpi?.groups?.items, {});
         }
         catch (err) {
-            console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, err?.message);
+            (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, err?.message);
         }
         /* 다시 넣어 **최근 쓴 것**으로 만든다 — 삽입 순서가 곧 버릴 순서이므로 이 한 줄이 LRU 를 만든다. */
         this.measuredCache.delete(key);
@@ -607,26 +950,30 @@ class TwinEngine {
             config = ref?.connectionConfig;
         }
         catch (err) {
-            console.warn(`[twin-engine] "${instanceId}": could not read the declared stimulus — ${err?.message ?? err}`);
+            (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": could not read the declared stimulus — ${err?.message ?? err}`);
             return;
         }
         const plan = (0, declared_stimulus_js_1.planStimulus)(config, { hasScenarioEngine: !!inst.runtime?.scenario, mode: inst.mode }, validateScenario);
         if (plan.action === 'skip') {
             /* 선언이 없는 것은 정상이므로 조용히 지난다. 나머지 셋은 **말한다** — 선언했는데 안 실린 상태다. */
             if (plan.reason !== 'none') {
-                console.warn(`[twin-engine] "${instanceId}": a stimulus is declared on its source but was not loaded (${plan.reason}${plan.detail ? `: ${plan.detail}` : ''}).` +
+                (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": a stimulus is declared on its source but was not loaded (${plan.reason}${plan.detail ? `: ${plan.detail}` : ''}).` +
                     (plan.reason === 'observed' ? ' This twin runs on observation — we do not manufacture arrivals for it.' : ''));
             }
             return;
         }
         try {
+            /* 자극을 싣고 시작하는 데 든 시간 — 실측에서 큰 트윈은 이 구간이 29~72초였다. */
+            const tStim = performance.now();
             inst.runtime.scenario.load(plan.scenario);
             inst.runtime.scenario.start();
+            const stimMs = performance.now() - tStim;
+            (0, load_meter_js_1.recordPhase)(inst.load ?? (inst.load = (0, load_meter_js_1.newLoadMeter)()), 'stimulus', stimMs);
             const kinds = (plan.scenario.generators ?? []).map((g) => g?.kind).filter(Boolean);
-            console.log(`[twin-engine] "${instanceId}": stimulus from its source started — ${kinds.length ? kinds.join(', ') : 'no generators'}.`);
+            (0, log_js_1.twinLog)(`[twin-engine] "${instanceId}": stimulus from its source started in ${Math.round(stimMs)}ms — ${kinds.length ? kinds.join(', ') : 'no generators'}.`);
         }
         catch (err) {
-            console.warn(`[twin-engine] "${instanceId}": the declared stimulus was rejected at load — ${err?.message ?? err}`);
+            (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": the declared stimulus was rejected at load — ${err?.message ?? err}`);
         }
     }
     /**
@@ -639,7 +986,7 @@ class TwinEngine {
         const repo = (0, shell_1.getRepository)(twin_reference_js_1.TwinReference);
         const ref = await repo.findOne({ where: { domain: { id: domainId }, source: instanceId } });
         if (!ref) {
-            console.warn(`[twin-engine] "${instanceId}": no source reference — a stimulus has nowhere to be declared.`);
+            (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}": no source reference — a stimulus has nowhere to be declared.`);
             return false;
         }
         ref.connectionConfig = (0, declared_stimulus_js_1.withStimulus)(ref.connectionConfig, scenario);
@@ -750,7 +1097,7 @@ class TwinEngine {
         if (!plan.ackedCount && !plan.attentionSinceCount && !plan.energy)
             return;
         if (typeof kernel.hydrateContinuity !== 'function') {
-            console.warn(`[twin-engine] kernel for "${id}" cannot carry continuity (no hydrateContinuity) — the open demand window, ` +
+            (0, log_js_1.twinWarn)(`[twin-engine] kernel for "${id}" cannot carry continuity (no hydrateContinuity) — the open demand window, ` +
                 'its peak and the attention start times are lost on every restart.');
             return;
         }
@@ -759,7 +1106,7 @@ class TwinEngine {
         }
         catch (err) {
             /* 이어받기가 실패해도 미러는 돌아야 한다 — 다만 무엇을 잃었는지 말한다. */
-            console.warn(`[twin-engine] continuity seed failed for "${id}" — starting without it: ${err?.message ?? err}`);
+            (0, log_js_1.twinWarn)(`[twin-engine] continuity seed failed for "${id}" — starting without it: ${err?.message ?? err}`);
             return;
         }
         const carried = [
@@ -767,7 +1114,7 @@ class TwinEngine {
             ...(plan.ackedCount ? [`${plan.ackedCount} acknowledged attention(s)`] : []),
             ...(plan.attentionSinceCount ? [`${plan.attentionSinceCount} attention start time(s)`] : [])
         ].join(', ');
-        console.log(`[twin-engine] mirror "${id}" carried over ${carried} — observation axes come from the source.`);
+        (0, log_js_1.twinLog)(`[twin-engine] mirror "${id}" carried over ${carried} — observation axes come from the source.`);
     }
     static start(id, domainId, kind, model, restartPolicy, purpose, resumeFrom) {
         const key = (0, runtime_key_js_1.runtimeKey)(domainId, id);
@@ -778,8 +1125,17 @@ class TwinEngine {
         kernel.loadTwinModel(model); // 구조만. 상태는 아래 웜스타트가 주입한다.
         this.applyOperations(kernel, model, id); // 시간·수율 명세(있으면) — 없으면 커널 기본값
         /* 추정기는 DB 조회를 포함해 비동기 — 기동을 막지 않고 붙는다(붙기 전 작업은 명세·상수로 산출). */
-        this.installEstimators(kernel, domainId, id, model).catch(err => console.warn('[twin-engine] estimator install failed', err?.message));
+        this.installEstimators(kernel, domainId, id, model).catch(err => (0, log_js_1.twinWarn)('[twin-engine] estimator install failed', err?.message));
+        /*
+         * **웜스타트에 든 시간을 값으로 남긴다** (2026-08-22). 실측으로 부팅이 620~717초였고 트윈 하나에
+         * 15~93초였는데, 어느 작업이 그 시간을 쓰는지 답할 계기가 없었다. 로그에도 밀리초까지 적어
+         * 부팅 로그만으로 구간을 읽을 수 있게 한다.
+         */
+        const tWarm = performance.now();
         this.warmStart(domainId, id, kernel, purpose);
+        const warmMs = performance.now() - tWarm;
+        if (warmMs >= 1000)
+            (0, log_js_1.twinLog)(`[twin-engine] "${id}": warm start took ${Math.round(warmMs)}ms.`);
         /*
          * **번호를 이어 센다** — 저널에 이미 있는 번호와 겹치지 않게.
          *
@@ -817,6 +1173,17 @@ class TwinEngine {
             /* 정책은 부르는 쪽이 선언한다 — 여기서 고르면 같은 트윈이 부르는 자리에 따라 다르게 재기동한다. */
             restartPolicy: (0, restart_policy_js_1.readRestartPolicy)(restartPolicy, `start("${id}")`),
             spaceId: model?.spaceId,
+            /*
+             * **시뮬도 계기를 든다** (2026-08-20).
+             *
+             * 예전에는 `startLive` 에서만 만들었다. 그래서 도는 트윈 22개가 시뮬인 서버에서 「초당 몇 행을
+             * 쓰나」·「밀린 게 있나」를 물을 자리가 **아예 없었다** — 저널 쓰기를 배치로 고친 뒤에도 그 효과와
+             * 회귀를 숫자로 볼 수 없다. 세지 않는 개선은 다음 사람이 되돌려도 아무도 모른다.
+             *
+             * 유입(`ingested`)은 시뮬에 뜻이 없다(원본에서 받는 것이 아니라 자기가 낸다) — 그 칸은 0 으로
+             * 남고, 그것이 사실이다(「받은 것이 없다」).
+             */
+            metrics: this.newMetrics(),
             unsub: () => { }
         };
         this.instances[key] = inst;
@@ -824,36 +1191,57 @@ class TwinEngine {
         this.stopNotes.delete(key);
         delete this.recovered[key]; // 웜스타트로 커널에 옮겨 심었다 — 이제 라이브가 진실이다.
         /* 원본이 선언한 자극 — 기동을 막지 않는다(추정기와 같은 규율). 못 실었으면 그 사실을 말한다. */
-        this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus install failed — ${err?.message ?? err}`));
+        this.installStimulus(domainId, id, inst).catch(err => (0, log_js_1.twinWarn)(`[twin-engine] "${id}": stimulus install failed — ${err?.message ?? err}`));
         /* 라이브 바인딩(P3): data 채널 필터가 subdomain 을 보므로 Domain 객체를 1회 해석해 둔다. */
         (0, shell_1.getRepository)(shell_1.Domain).findOne({ where: { id: domainId } }).then(d => (inst.domain = d)).catch(() => { });
-        /* State 채널: runtime.subscribe(snapshot→delta→clock) → pubsub 방송(구독 리졸버가 instanceId 필터). */
+        /* State 채널: runtime.subscribe(snapshot→delta→clock) → pubsub 브로드캐스팅(구독 리졸버가 instanceId 필터). */
         const sub = runtime.subscribe((msg) => {
             this.publishGuarded('twin-state', { twinState: { instanceId: id, kind: msg.kind, revision: msg.revision, payload: msg } }, `twin-state:${id}`);
-            /* 영속 + 라이브 바인딩 브리지: delta 마다 저널 저장 + 엔티티별 data(tag:) publish → 보드 컴포넌트 라이브. */
+            /* 영속 + 라이브 바인딩 브리지: delta 를 저널 버퍼에 담고 + 엔티티별 data(tag:) publish → 보드 컴포넌트 라이브. */
             if (msg.kind === 'delta') {
-                this.persist(domainId, id, msg).catch(err => console.error('twin persist fail', err));
                 /*
-                 * ── 방송은 **모아서** 한 번 (2026-08-14 실측으로 잡음) ────────────────────
-                 * 여기서 곧바로 방송하고 있었다. 그런데 커널은 한 번의 tick 에서 사실을 **여러 개** 낸다
+                 * ── 쓰기도 **모아서** 한 번 (2026-08-20 실측으로 잡음) ────────────────────
+                 *
+                 * 여기서 델타마다 `persist()` 를 불렀다 — 행 하나당 `save()` 하나, 그리고 그 안에서
+                 * `structureRevOf` 를 await(구조 행이 없는 트윈은 캐시 미스가 기억되지 않아 **델타마다
+                 * SELECT** 였다). 데모 자극을 켠 트윈 23개에서 그 결과가 이랬다: 프로세스 CPU 81~112%,
+                 * 아무 일도 하지 않는 질의가 8~14초. 프로파일은 `JSON.parse`·대형 GC·스레드풀을 가리키고
+                 * 계기는 틱의 몫이 16% 라고 말했다 — **틱이 아니라 쓰기였다.**
+                 *
+                 * 바로 위 주석이 **브로드캐스팅**에서 같은 함정을 적어 두었다(틱 하나가 35초). 브로드캐스팅은 모으도록
+                 * 고쳤고 쓰기는 단건으로 남아 있었다. 같은 규율로 들인다 — ADR-0030 이 *"기록 경로가 둘인
+                 * 것은 시뮬만 옆문으로 들어오기 때문"* 이라 예고한 그 자리다.
+                 *
+                 * **리비전은 커널의 것을 그대로 든다**(라이브는 flush 때 호스트가 부여한다). 시뮬의 저널은
+                 * 커널 리비전으로 접히므로 여기서 다시 번호를 매기면 시간여행이 어긋난다.
+                 */
+                ;
+                (inst.pendingJournal ?? (inst.pendingJournal = [])).push({ event: msg.event, revision: msg.revision });
+                /*
+                 * ── 브로드캐스팅은 **모아서** 한 번 (2026-08-14 실측으로 잡음) ────────────────────
+                 * 여기서 곧바로 브로드캐스팅하고 있었다. 그런데 커널은 한 번의 tick 에서 사실을 **여러 개** 낸다
                  * (예약·배치·완료…). 그래서 tick 하나가 전 상태 투영을 수백 번 반복했다 — `order-check`
                  * 트윈에서 **틱 하나가 35초**를 먹고(단계 합은 32ms 였다: 시간은 반복 횟수에 있었다) 그
                  * 35초 동안 이벤트 루프가 막혀 구독자가 아무것도 빼내지 못했다. 밀린 push 가 1024를 넘는
-                 * 순간 pubsub 이 던지고, 그 예외가 타이머 콜백을 타고 올라와 **호스트가 죽었다.**
+                 * 순간 pubsub 이 오류를 내고, 그 예외가 타이머 콜백을 타고 올라와 **호스트가 죽었다.**
                  *
                  * 라이브는 이미 dirty 표시 + 주기 flush 로 이 문제를 풀어 두었다(BROADCAST_COALESCE_MS).
                  * 시뮬만 그 규율 밖에 있었다 — 같은 규율로 들인다(최신-상태 채널이라 중간 상태를 모두
                  * 보낼 이유가 없다: 200ms 마다 마지막 것 하나면 화면은 같다).
                  */
                 inst.dirty = true;
+                /* 이 사실이 건드린 물품만 다음 브로드캐스팅에서 만든다(모르면 전부). */
+                this.markItemsDirty(inst, [msg.event]);
                 this.ensureBroadcastCoalescer();
             }
         });
         inst.unsub = () => sub.unsubscribe();
+        /* 위에서 잰 웜스타트 시간을 계기에 적는다 — 계기는 인스턴스가 생긴 뒤에야 있다. */
+        (0, load_meter_js_1.recordPhase)(inst.load ?? (inst.load = (0, load_meter_js_1.newLoadMeter)()), 'warmStart', warmMs);
         /* 복구 앵커: 레지스트리에 model/kind/status/restartPolicy 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
-        this.register(domainId, id, kind, model, 'running', inst.restartPolicy).catch(err => console.error('twin register fail', err));
+        this.register(domainId, id, kind, model, 'running', inst.restartPolicy).catch(err => (0, log_js_1.twinError)('twin register fail', err));
         /* 워커 tick — 스켈레톤은 setInterval(메인 루프). 긴 시뮬 오프-루프(worker thread)는 스케일 하드닝(향후, §host 경계). */
-        inst.timer = setInterval(() => this.tickGuarded(domainId, id, runtime), this.TICK_MS);
+        inst.timer = this.startTickTimer(() => this.tickGuarded(domainId, id, runtime), t => (inst.timer = t));
         return inst;
     }
     /**
@@ -915,7 +1303,7 @@ class TwinEngine {
         const offset = (0, reference_master_js_1.utcOffsetOf)(space?.timezone);
         if (offset === undefined) {
             if (space?.timezone)
-                console.warn(`[twin-engine] space "${sid}" declares time zone "${space.timezone}" but it is not a known IANA zone — times will be read as UTC.`);
+                (0, log_js_1.twinWarn)(`[twin-engine] space "${sid}" declares time zone "${space.timezone}" but it is not a known IANA zone — times will be read as UTC.`);
             return model;
         }
         return { ...model, utcOffsetMinutes: offset };
@@ -929,7 +1317,7 @@ class TwinEngine {
         kernel.loadTwinModel(model);
         /* **세우는 쪽이 아는 사실은 세울 때 말한다.** 예전에는 첫 이벤트가 도착해야 커널이 스스로를
            관측 구동으로 여겼고, 그래서 아직 아무것도 못 받은 미러는 시뮬레이션 취급을 받았다. */
-        kernel.observe?.();
+        declareObserved(kernel, `live twin '${id}'`);
         this.applyOperations(kernel, model, id); // 명세는 라이브에도 실린다(예측 자격이 sim 과 같아진다)
         /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
          * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
@@ -956,16 +1344,17 @@ class TwinEngine {
                 return // 인입의 재방출 — 저널은 인입에서 한 번만
                 ;
             (inst.pendingJournal ?? (inst.pendingJournal = [])).push(e);
-            /* 커널이 낸 사실도 상태를 바꾼다(피크·마감) — 다음 방송 주기에 실린다. */
+            /* 커널이 낸 사실도 상태를 바꾼다(피크·마감) — 다음 브로드캐스팅 주기에 실린다. */
             inst.dirty = true;
+            this.markItemsDirty(inst, [e]);
             this.ensureBroadcastCoalescer();
         }) ?? (() => { });
         /* 추정기(실측·거리)도 라이브에 붙인다 — 예측이 상수로 계산되지 않게. 기동을 막지 않는다. */
-        this.installEstimators(kernel, domainId, id, model).catch(err => console.warn('[twin-engine] estimator install failed', err?.message));
-        inst.metrics = { ingestedTotal: 0, broadcastTotal: 0, journaledTotal: 0, ingestRate: 0, broadcastRate: 0, journalRate: 0, backlog: 0, _accIngest: 0, _accBroadcast: 0, _accJournal: 0, _windowStartMs: Date.now() };
+        this.installEstimators(kernel, domainId, id, model).catch(err => (0, log_js_1.twinWarn)('[twin-engine] estimator install failed', err?.message));
+        inst.metrics = this.newMetrics();
         this.instances[key] = inst;
         /* 미러에도 부른다 — 선언이 있으면 「미러에는 싣지 않는다」고 말해야 한다(조용한 무시 금지). */
-        this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus check failed — ${err?.message ?? err}`));
+        this.installStimulus(domainId, id, inst).catch(err => (0, log_js_1.twinWarn)(`[twin-engine] "${id}": stimulus check failed — ${err?.message ?? err}`));
         /*
          * **원천이 되풀어 주지 않는 것만 잇는다** (2026-08-18 실측으로 붙임).
          *
@@ -977,27 +1366,106 @@ 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 과 동일). */
         (0, shell_1.getRepository)(shell_1.Domain).findOne({ where: { id: domainId } }).then(d => (inst.domain = d)).catch(() => { });
-        /* 저널 revision 카운터 시드 — 기존 저널 최대치에서 이어붙임(재기동 시 revision 충돌 방지). 이후 인메모리 증가. */
+        /*
+         * 저널 revision 카운터 시드 — 기존 저널 최대치에서 이어붙임(재기동 시 revision 충돌 방지).
+         *
+         * ── **커널에도 같은 번호를 알려 준다** (2026-08-23 실측) ────────────────────
+         * 예전에는 이 자리에서 `inst.revision`(저널 줄 번호)만 이어받고 **커널은 0 부터 세게 두었다.**
+         * 그래서 체크포인트가 뜻이 다른 두 수를 나란히 적었다.
+         *
+         *   바깥 revision  12,972   저널에 적힌 줄 번호 (이 자리에서 이어받는다)
+         *   state.revision  6,478   커널이 처리한 봉투 수 (0 부터 셌다)
+         *
+         * 포천 미러에서 확정했다: 차이 6,494 는 그 트윈을 **다시 세운 시각**(09:11)에 저널이 이미 갖고
+         * 있던 줄 수와 정확히 같았다(줄 6494 = 08:23:59, 줄 6495 = 09:11:13). 산수가 맞았다.
+         *
+         * 결함은 두 수가 다르다는 것 자체가 아니라 **비대칭**이다: 재기동 경로(`start` → `resumeRevision`)는
+         * 커널에 번호를 알려 주는데 **이 경로(미러)는 알려 주지 않았다.** 그래서 같은 저장물을 읽는 소비처가
+         * 같은 이름의 두 수를 같은 축으로 견주게 되고, 실제로 그렇게 읽혔다.
+         *
+         * 저널이 비어 있으면(0) 아무 일도 하지 않는다 — 새 트윈은 0 부터 세는 것이 맞다. 그리고 이 조회는
+         * 비동기라 그 사이에 이벤트가 몇 건 들어와 있을 수 있는데, 그때 뒤로 되돌리는 것은 커널이 거절한다
+         * (겹치는 번호를 막는 그 판정이다). 거절은 삼키지 않고 남긴다.
+         */
         (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
             .findOne({ where: { domain: { id: domainId }, instanceId: id }, order: { revision: 'DESC' } })
-            .then(top => (inst.revision = top?.revision ?? 0))
+            .then(top => {
+            const head = top?.revision ?? 0;
+            inst.revision = head;
+            if (!head || typeof kernel.resumeRevision !== 'function')
+                return;
+            try {
+                ;
+                kernel.resumeRevision(head);
+            }
+            catch (err) {
+                /* 뒤로 갈 수 없다는 거절 — 이 조회가 도착하기 전에 이미 그만큼 처리했다는 뜻이다. */
+                (0, log_js_1.twinWarn)(`[twin-engine] "${id}": journal head ${head} is behind the kernel — ${err?.message ?? err}`);
+            }
+        })
             .catch(() => (inst.revision = 0));
-        this.register(domainId, id, kind, model, 'running', 'resync').catch(err => console.error('twin register fail', err));
+        this.register(domainId, id, kind, model, 'running', 'resync').catch(err => (0, log_js_1.twinError)('twin register fail', err));
         return inst;
     }
     /**
-     * live 이벤트 인제스트 — projector 구동 + data(tag) 방송(폐루프의 인바운드 도착 지점, command-routing §8.2).
+     * live 이벤트 인제스트 — projector 구동 + data(tag) 브로드캐스팅(폐루프의 인바운드 도착 지점, command-routing §8.2).
      * reference 어댑터가 낸 records → 커널 face2-adapter.ingest → CanonicalEnvelope 를 여기로 밀어넣는다.
      * (State 채널 델타/저널 결선은 후속 — 스켈레톤은 data(tag) 미러 중심.)
+     *
+     * ── 넣은 수를 **답한다** (2026-08-20) ────────────────────────────────────────
+     * 트윈이 라이브로 돌지 않으면 여기서 봉투를 버린다. 그것 자체는 맞다(넣을 커널이 없다). 문제는
+     * **조용히** 버린 것이었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 유입 장부는 그것을
+     * 「통과」로 셌다. 화면은 멈춘 트윈 옆에 「150 통과 · 100%」라고 적었다 — 사실이 사라지는 동안
+     * 화면이 안심시킨 것이다.
+     *
+     * 그래서 **넣은 수를 돌려준다.** 부르는 쪽이 제시 수와 견주어 버려진 수를 장부에 적는다. 반환을
+     * 무시하는 호출부는 그대로 동작한다(전과 같다).
      */
     static ingestLive(domainId, id, envelopes) {
         const inst = this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, id)];
         if (inst?.mode !== 'live' || !inst.projector)
-            return;
+            return 0;
         const tIngest = performance.now();
         /* 인입 봉투를 표시해 두고 넣는다 — 커널이 그것을 재방출해도 저널에 두 번 적히지 않게(위 구독 주석). */
         for (const e of envelopes) {
@@ -1012,46 +1480,146 @@ class TwinEngine {
             inst.metrics.ingestedTotal += envelopes.length;
             inst.metrics._accIngest += envelopes.length;
         } // 계측(④-1)
-        // 방송 병합(ingest-scale §1.1/§4.4) — apply 는 O(1)·싸다. 그러나 방송(snapshot O(state))은 비싸(대규모 5ms+)
-        // 이벤트마다 방송하면 폭발 → dirty 만 찍고 coalescer tick 이 주기 방송(방송률 ≠ 인제스트률).
+        // 브로드캐스팅 병합(ingest-scale §1.1/§4.4) — apply 는 O(1)·싸다. 그러나 브로드캐스팅(snapshot O(state))은 비싸(대규모 5ms+)
+        // 이벤트마다 브로드캐스팅하면 폭발 → dirty 만 찍고 coalescer tick 이 주기 브로드캐스팅(브로드캐스팅률 ≠ 인제스트률).
         inst.dirty = true;
+        this.markItemsDirty(inst, envelopes);
         this.ensureBroadcastCoalescer();
+        return envelopes.length;
     }
     /**
-     * 구간 성과 방송은 **없앴다**(2026-08-06). 카드가 `twinKpi` 를 직접 묻는다.
+     * 구간 성과 브로드캐스팅은 **없앴다**(2026-08-06). 카드가 `twinKpi` 를 직접 묻는다.
      *
-     * 왜: 카드를 여러 단계(공간·트윈·구역·자리·설비)에 붙이려면 방송으로는 태그가 트윈당 1,200개가 되고,
+     * 왜: 카드를 여러 단계(공간·트윈·구역·자리·설비)에 붙이려면 브로드캐스팅으로는 태그가 트윈당 1,200개가 되고,
      * **모델에 카드를 하나도 안 놓아도** 30초마다 트윈마다 저널을 접었다. 질의로 바꾸니 보고 있는 카드
      * 수만큼만 들고, 같은 (대상·창·축) 은 클라이언트가 하나로 합친다.
      *
      * 덤으로 질의만 할 수 있는 것이 둘 생겼다 — **과거 시각**(`toTime`)과 **공간 단위 합산**(여러 트윈을
-     * 한 번에 접기). 방송 루프는 트윈별이라 둘 다 못 했다.
+     * 한 번에 접기). 브로드캐스팅 루프는 트윈별이라 둘 다 못 했다.
      *
      * 축을 나눠도 폴드 비용이 같다는 실측이 근거다(`test/kpi-query-bench.test.ts`).
      */
-    /** 방송 병합 주기(ms) — 방송률 상한. 인제스트가 아무리 빨라도 이 주기로만 방송. */
+    /**
+     * 몇 창마다 한 번은 **전부** 만드나 — 사건 없이 값이 바뀌는 자리에 대한 그물.
+     *
+     * 25 창이면 기본 주기에서 5초다. 보장이 아니라 그물이다(위 `publishEntityData` 주석).
+     */
+    static { this.FULL_BROADCAST_EVERY = 25; }
+    /** 전부 만든 횟수 — 범위를 좁히지 못한 창이 얼마나 되는지 값으로 남는다. */
+    static { this.broadcastFullPasses = 0; }
+    /**
+     * 브로드캐스팅을 만든 횟수 전부 — **전부 만든 횟수의 분모.**
+     *
+     * 분자만 내면 「전부 만들기 1,200회」가 많은 것인지 적은 것인지 읽을 수 없다. 좁히기가 듣고 있으면
+     * 이 값의 `1/FULL_BROADCAST_EVERY` 쯤이 전부 만든 횟수이고, 두 값이 비슷하면 범위를 거의 못 좁힌
+     * 것이다(원인은 대개 「모른다」로 떨어지는 사건이다).
+     */
+    static { this.broadcastPasses = 0; }
+    /**
+     * 이 창에 건드린 물품을 모은다 — **말할 수 없으면 범위를 버린다(전부 만든다).**
+     *
+     * `events` 를 주지 않으면 「무엇이 바뀌었는지 모른다」다(구조 전환처럼 상태 전반이 달라지는 자리).
+     * 한 창에서 한 번 「모른다」가 되면 그 창은 끝까지 모르는 채로 둔다 — 뒤에 온 사건으로 범위를
+     * 되살리면 앞 사건이 건드린 것을 빠뜨린다.
+     */
+    static markItemsDirty(inst, events) {
+        if (inst.dirtyItems === undefined)
+            return; // 이 창은 이미 「모른다」
+        if (!events) {
+            inst.dirtyItems = undefined;
+            return;
+        }
+        for (const e of events) {
+            const touched = (0, touched_items_js_1.touchedItemKeys)(e);
+            if (!touched) {
+                inst.dirtyItems = undefined;
+                return;
+            }
+            for (const epc of touched)
+                inst.dirtyItems.add(epc);
+        }
+    }
+    /** 브로드캐스팅 병합 주기(ms) — 브로드캐스팅률 상한. 인제스트가 아무리 빨라도 이 주기로만 브로드캐스팅. */
     static { this.BROADCAST_COALESCE_MS = 200; }
-    /** live 방송 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 방송(entitySigs 로 변경 엔티티만). */
+    /**
+     * ── 브로드캐스팅 주기는 **재 본 비용에 맞춘다** (2026-08-21 실측) ────────────────────
+     * 한 번의 브로드캐스팅은 상태 크기에 비례한다(실측: 물품 2,400 개인 트윈 하나가 4.5ms — 상태 투영 1.7ms,
+     * payload 만들기 1.8ms, 시그니처 1.0ms). 트윈이 스무 개면 200ms 마다 90ms 가 브로드캐스팅에 들어가고,
+     * 그 시간에는 HTTP 도 구독도 서지 못한다.
+     *
+     * 그래서 한 창에서 브로드캐스팅에 쓴 시간이 주기의 일정 몫을 넘으면 **주기를 늘린다**. 화면은 조금 늦게
+     * 갱신되고(최신-상태 채널이라 값은 마지막 것 하나뿐이므로 내용은 같다), 늘렸다는 것은 계기판이
+     * 말한다(`broadcastCoalesceMs`). 여유가 생기면 원래 주기로 되돌린다.
+     *
+     * 이것은 브로드캐스팅 비용을 **줄이는 것이 아니다** — 비용을 줄이는 것은 변경분만 만드는 일이고 그것은 별
+     * 작업이다. 여기서는 그때까지 호스트가 굶지 않게 상한을 둔다.
+     */
+    static { this.BROADCAST_MAX_COALESCE_MS = 1000; }
+    /** 주기의 몇 몫까지 브로드캐스팅에 써도 되는가 — 넘으면 주기를 늘린다(절반이면 나머지 절반은 남긴다). */
+    static { this.BROADCAST_LOAD_RATIO = 0.3; }
+    /** 지금 쓰고 있는 주기(ms) — 계기판이 이 값을 읽는다. 늘어난 채로 있으면 그것이 사실이다. */
+    static { this.broadcastPeriodMs = 200; }
+    /** 주기를 늘린 횟수 — 조용히 늦추지 않는다. */
+    static { this.broadcastBackoffs = 0; }
+    /** live 브로드캐스팅 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 브로드캐스팅(entitySigs 로 변경 엔티티만). */
     static ensureBroadcastCoalescer() {
         if (this.broadcastTimer)
             return;
-        this.broadcastTimer = setInterval(() => this.flushLiveBroadcasts(), this.BROADCAST_COALESCE_MS);
+        this.broadcastPeriodMs = this.BROADCAST_COALESCE_MS;
+        this.broadcastTimer = setInterval(() => this.flushLiveBroadcasts(), this.broadcastPeriodMs);
         if (typeof this.broadcastTimer.unref === 'function')
             this.broadcastTimer.unref(); // 종료 비차단
     }
     /**
-     * dirty 인스턴스 방송 flush(주기 tick 또는 명시 호출) — **시뮬과 라이브 둘 다.**
+     * 브로드캐스팅에 쓴 시간을 보고 주기를 정한다 — **늘리는 것도 줄이는 것도 값에 근거한다.**
      *
-     * 예전에는 라이브만 봤다(`mode !== 'live'` 면 건너뜀). 시뮬은 delta 마다 곧바로 방송했고, 그것이
-     * 한 tick 에서 수백 번 반복되며 이벤트 루프를 막았다(위 `start()` 주석의 35초 틱). 방송을 모으는
+     * 한 번의 flush 가 주기의 `BROADCAST_LOAD_RATIO` 를 넘게 쓰면 주기를 두 배로(상한까지), 그 몫의
+     * 절반 아래로 내려오면 절반으로(원래 주기까지) 되돌린다. 문턱을 두 개 두는 이유는 하나면 경계에서
+     * 늘리고 줄이기를 반복하기 때문이다.
+     */
+    static adjustBroadcastPeriod(flushMs) {
+        const period = this.broadcastPeriodMs;
+        const high = period * this.BROADCAST_LOAD_RATIO;
+        const low = high / 2;
+        let next = period;
+        if (flushMs > high && period < this.BROADCAST_MAX_COALESCE_MS) {
+            next = Math.min(this.BROADCAST_MAX_COALESCE_MS, period * 2);
+            this.broadcastBackoffs++;
+            (0, log_js_1.twinWarn)(`[twin-engine] broadcast period ${period}ms → ${next}ms — one flush took ${Math.round(flushMs)}ms across ${Object.keys(this.instances).length} twin(s)`);
+        }
+        else if (flushMs < low && period > this.BROADCAST_COALESCE_MS) {
+            next = Math.max(this.BROADCAST_COALESCE_MS, Math.round(period / 2));
+        }
+        if (next === period)
+            return;
+        this.broadcastPeriodMs = next;
+        if (this.broadcastTimer)
+            clearInterval(this.broadcastTimer);
+        this.broadcastTimer = setInterval(() => this.flushLiveBroadcasts(), next);
+        if (typeof this.broadcastTimer.unref === 'function')
+            this.broadcastTimer.unref();
+    }
+    /**
+     * dirty 인스턴스 브로드캐스팅 flush(주기 tick 또는 명시 호출) — **시뮬과 라이브 둘 다.**
+     *
+     * 예전에는 라이브만 봤다(`mode !== 'live'` 면 건너뜀). 시뮬은 delta 마다 곧바로 브로드캐스팅했고, 그것이
+     * 한 tick 에서 수백 번 반복되며 이벤트 루프를 막았다(위 `start()` 주석의 35초 틱). 브로드캐스팅을 모으는
      * 규율은 모드의 성질이 아니라 **채널의 성질**이다 — 최신-상태 채널이면 중간 상태는 보낼 값이 없다.
      */
     static flushLiveBroadcasts() {
         const now = Date.now();
+        const flushStart = performance.now();
         for (const inst of Object.values(this.instances)) {
             const isLive = inst.mode === 'live';
-            // 처리량 계측(④-1) — 창(≥1s)마다 유입/방송/저널률 갱신. dirty 무관(유휴면 0으로 수렴). 부하를 읽는 신호.
-            const m = isLive ? inst.metrics : undefined;
+            /*
+             * 처리량 계측(④-1) — 창(≥1s)마다 유입·브로드캐스팅·저널률 갱신. dirty 무관(유휴면 0으로 수렴).
+             *
+             * **두 구동을 함께 센다** (2026-08-20). 예전에는 `isLive ? … : undefined` 로 시뮬을 잘라 냈다.
+             * 그래서 도는 트윈 대부분이 시뮬인 서버에서 「초당 몇 행을 쓰나」에 답할 자리가 없었다 — 저널 쓰기를
+             * 배치로 고친 뒤에도 그 효과를 숫자로 볼 수 없었다. 유입(`ingestRate`)은 시뮬에서 0 으로 수렴하고,
+             * 그것이 사실이다(원본에서 받는 것이 없다).
+             */
+            const m = inst.metrics;
             if (m) {
                 const dt = (now - m._windowStartMs) / 1000;
                 if (dt >= 1) {
@@ -1067,44 +1635,42 @@ class TwinEngine {
             if (!inst.dirty)
                 continue;
             inst.dirty = false;
-            // ① 엔티티 data(tag) 방송 — 보드 컴포넌트 라이브 렌더.
+            /* 주기마다 한 번은 범위를 버리고 전부 만든다 — 사건 없이 값이 바뀌는 자리에 대한 그물. */
+            const left = (inst.fullBroadcastCountdown ?? 0) - 1;
+            if (left <= 0) {
+                inst.fullBroadcastDue = true;
+                inst.fullBroadcastCountdown = this.FULL_BROADCAST_EVERY;
+            }
+            else {
+                inst.fullBroadcastCountdown = left;
+            }
+            // ① 엔티티 data(tag) 브로드캐스팅 — 보드 컴포넌트 라이브 렌더.
             this.publishEntityData(inst);
             if (m) {
                 m.broadcastTotal++;
                 m._accBroadcast++;
             }
-            /* 시뮬의 저널·state 채널은 자기 콜백이 delta 마다 처리한다(사실은 하나도 빠뜨리지 않는다).
-               여기서 모으는 것은 **엔티티 방송**뿐이다 — 화면이 읽는 최신-상태 채널. */
+            /* ③ 저널 배치 기록 — **두 구동이 같은 문을 쓴다**(시뮬도 여기서 흘린다, §7.1). */
+            this.flushJournal(inst);
+            /* 여기서부터는 **라이브만**이다: 시뮬의 state 채널은 자기 콜백이 델타마다 보내므로(리비전이 커널의
+               것이다) 여기서 또 보내면 같은 신호가 두 번 간다. 저널은 위에서 이미 두 구동 몫을 흘렸다. */
             if (!isLive)
                 continue;
-            // ③ 저널 배치 기록 — 모아둔 이벤트에 revision 부여해 벌크 저장(이벤트마다 write 아님).
-            //    revision 카운터는 인메모리(startLive 에서 저널 high-water 로 1회 시드) → tick 마다 DB 질의 없음.
-            const batch = inst.pendingJournal;
-            if (batch?.length && inst.revision != null) {
-                inst.pendingJournal = [];
-                const start = inst.revision;
-                inst.revision = start + batch.length;
-                if (m) {
-                    m.journaledTotal += batch.length;
-                    m._accJournal += batch.length;
-                    m.backlog = batch.length;
-                }
-                const tJournal = performance.now();
-                this.persistBatch(inst.domainId, inst.id, batch, start)
-                    .then(() => (0, load_meter_js_1.recordPhase)(inst.load ?? (inst.load = (0, load_meter_js_1.newLoadMeter)()), 'journal', performance.now() - tJournal))
-                    .catch(err => console.error('twin live journal fail', err));
-            }
-            // ② State 채널 방송 — "바뀌었다"는 가벼운 신호만(kind+revision). 맵 구독(subscribeTwinState)은 이 신호에
+            // ② State 채널 브로드캐스팅 — "바뀌었다"는 가벼운 신호만(kind+revision). 맵 구독(subscribeTwinState)은 이 신호에
             //    scheduleRefresh(250ms 디바운스)→pollLive 로 되물어봄. 스냅샷(O(state))은 보는 사람이 물을 때만 1회 계산.
             //    (여기서 payload 로 스냅샷을 실으면 아무도 안 읽는데 tick 마다 통째로 떠서 순수 낭비 — 신호만 보낸다.)
             this.publishGuarded('twin-state', { twinState: { instanceId: inst.id, kind: 'delta', revision: inst.revision ?? 0 } }, `twin-state:${inst.id}`);
         }
-        /* 돌고 있는 인스턴스가 하나도 없으면 tick 을 멈춘다(예전엔 「라이브가 없으면」이었는데, 이제
-           시뮬도 이 flush 에 기대므로 그 조건이면 시뮬 방송이 멈춘 채 남는다). */
+        /* 가동 중인 인스턴스가 하나도 없으면 tick 을 멈춘다(예전엔 「라이브가 없으면」이었는데, 이제
+           시뮬도 이 flush 에 기대므로 그 조건이면 시뮬 브로드캐스팅이 멈춘 채 남는다). */
         if (!Object.keys(this.instances).length && this.broadcastTimer) {
             clearInterval(this.broadcastTimer);
             this.broadcastTimer = undefined;
+            this.broadcastPeriodMs = this.BROADCAST_COALESCE_MS;
+            return;
         }
+        /* 이번 flush 가 얼마를 썼는지로 다음 주기를 정한다 — 브로드캐스팅이 루프를 다 쓰지 못하게. */
+        this.adjustBroadcastPeriod(performance.now() - flushStart);
     }
     /**
      * 저널 행 한 줄 — **기록 경로가 둘이라(라이브 벌크·심 단건) 행 모양은 반드시 한 곳에서 만든다.**
@@ -1142,23 +1708,135 @@ class TwinEngine {
      * 없으면 `undefined` 다 — 0 이 아니다. 구조 리비전이 생기기 전에 만들어진 트윈은 아직 리비전이
      * 없고, 그 사실을 0 이라는 **유효해 보이는 번호**로 위장하면 안 된다.
      */
+    /** 구조 리비전 캐시 — `null` 은 **없다는 것을 알고 있다**는 뜻이다(모름과 구별한다, §7.1). */
     static { this.structureRevCache = {}; }
     static async structureRevOf(domainId, instanceId) {
         const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
         const cached = this.structureRevCache[key];
+        /*
+         * **없다는 것도 답이다** — 예전에는 찾지 못하면 캐시하지 않았다(`if (latest) …`). 그래서 구조 행이
+         * 없는 트윈은 **부를 때마다 SELECT** 했고, 그 경로가 델타마다 불리고 있었다(§7.1). `null` 로 기억한다.
+         */
         if (cached !== undefined)
-            return cached;
+            return cached === null ? undefined : cached;
         const latest = await (0, shell_1.getRepository)(twin_structure_js_1.TwinStructure).findOne({ where: { domain: { id: domainId }, instanceId }, order: { rev: 'DESC' } });
-        if (latest)
-            this.structureRevCache[key] = latest.rev;
+        this.structureRevCache[key] = latest ? latest.rev : null;
         return latest?.rev;
     }
+    /** 계기 한 벌 — **두 구동이 같은 것을 든다**(한쪽만 들면 그 구동은 물어도 답이 없다). */
+    static newMetrics() {
+        return { ingestedTotal: 0, broadcastTotal: 0, journaledTotal: 0, ingestRate: 0, broadcastRate: 0, journalRate: 0, backlog: 0, _accIngest: 0, _accBroadcast: 0, _accJournal: 0, _windowStartMs: Date.now() };
+    }
+    /**
+     * 모아 둔 저널을 **한 번에** 쓴다 — 두 구동이 같은 문을 쓴다 (§7.1).
+     *
+     * ── 왜 한 함수인가 ─────────────────────────────────────────────────────────
+     * 쓰는 자리가 둘이면(주기 flush · 정지) 한쪽만 고쳐지고, 그 어긋남은 **사실이 조용히 사라지는**
+     * 모양으로 나타난다. 그래서 흘리는 규칙을 여기 한 곳에 둔다.
+     *
+     * ── 리비전을 누가 매기나 ───────────────────────────────────────────────────
+     *  · 라이브 — 원천은 리비전을 주지 않으므로 **호스트가** 이어 붙인다(저널 high-water 에서 시드).
+     *  · 시뮬 — **커널의 리비전**이 실려 온다(저널이 그것으로 접히고 시간여행이 그것을 딛는다).
+     * 그래서 버퍼는 두 모양을 함께 든다: 봉투만 있으면 라이브, `{ event, revision }` 이면 시뮬이다.
+     */
+    static flushJournal(inst) {
+        const batch = inst.pendingJournal;
+        if (!batch?.length)
+            return Promise.resolve();
+        inst.pendingJournal = [];
+        const m = inst.metrics;
+        /* 쓴 건수는 누적에, **지금 남은 것**은 backlog 에. 이 자리에서 배치 크기를 backlog 로 적으면
+           정상적인 배치 저장이 화면에서 경고로 보인다(2026-08-21 교정). */
+        if (m) {
+            m.journaledTotal += batch.length;
+            m._accJournal += batch.length;
+            m.backlog = inst.pendingJournal?.length ?? 0;
+        }
+        /* 시뮬은 자기 리비전을 들고 온다 — 그대로 쓴다. 라이브는 여기서 이어 붙인다. */
+        const carried = batch.filter((b) => b && typeof b === 'object' && 'event' in b && typeof b.revision === 'number');
+        const plain = batch.filter((b) => !(b && typeof b === 'object' && 'event' in b && typeof b.revision === 'number'));
+        const tJournal = performance.now();
+        const done = () => (0, load_meter_js_1.recordPhase)(inst.load ?? (inst.load = (0, load_meter_js_1.newLoadMeter)()), 'journal', performance.now() - tJournal);
+        const jobs = [];
+        if (carried.length)
+            jobs.push(this.persistCarried(inst.domainId, inst.id, carried));
+        if (plain.length && inst.revision != null) {
+            const start = inst.revision;
+            inst.revision = start + plain.length;
+            jobs.push(this.persistBatch(inst.domainId, inst.id, plain, start));
+        }
+        if (!jobs.length)
+            return Promise.resolve();
+        /*
+         * **약속을 돌려준다** — 주기 flush 는 기다리지 않지만(핫 경로) **정지는 기다려야 한다.** 기다리지
+         * 않으면 곧바로 이어지는 저널 재생이 아직 안 쓰인 구간을 못 보고, 웜스타트가 「없던 일」로 시작한다
+         * (실제로 그렇게 깨졌다: 확보분을 든 오더가 되살아나지 못했다).
+         */
+        const written = carried.length + plain.length;
+        return Promise.all(jobs)
+            .then(() => {
+            done();
+            /*
+             * **적힌 뒤에 적는다** — 실패한 배치를 「남았다」고 세면 추이가 없는 사실을 있다고 말한다.
+             * 창(10분)에 쌓이므로 재기동 뒤에도 「지난 여섯 시간 얼마나 적었나」를 답할 수 있다.
+             */
+            this.recordJournalWrite(inst.domainId, inst.id, written);
+        })
+            .catch(err => (0, log_js_1.twinError)('twin journal flush fail', err));
+    }
+    /**
+     * 커널이 매긴 리비전을 그대로 들고 벌크 저장 — 시뮬 경로.
+     *
+     * 예전에는 이 경로가 **델타마다 한 행씩** 저장했다(그리고 행마다 구조 리비전을 물었다). 규모에서 그것이
+     * 호스트를 먹었다(§7.1 실측). 여기서 구조 리비전은 **한 번만** 묻는다.
+     */
+    static async persistCarried(domainId, instanceId, items) {
+        const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
+        const structureRev = await this.structureRevOf(domainId, instanceId);
+        const rows = items.map(it => this.journalRow(repo, domainId, instanceId, it.event, it.revision, structureRev));
+        await this.insertRows(repo, rows);
+    }
+    /**
+     * 저널 행을 넣는다 — **넣기만 한다**(2026-08-20).
+     *
+     * 예전에는 `save()` 였다. 그런데 `save` 는 넣은 뒤 생성 컬럼을 읽으려고 **행마다 SELECT 를 한 번 더**
+     * 한다(시험 로그에서 그 질의가 그대로 보였다: `SELECT … FROM twin_events WHERE id = ?`). 저널은
+     * append-only 이고 부르는 쪽은 돌려받은 엔티티를 쓰지 않으므로 그 왕복이 순수 낭비다.
+     *
+     * 묶음은 **나눠서** 넣는다: 한 문에 열이 열다섯인 행을 수천 개 실으면 드라이버의 파라미터 한계에
+     * 걸린다(pg 는 65,535개). 500행이면 어느 드라이버에서도 안전하다.
+     */
+    static async insertRows(repo, rows) {
+        const CHUNK = 500;
+        /*
+         * ── 한 트랜잭션으로 감싸 보았고, **되돌렸다** (2026-08-22 실측) ─────────────
+         * 「청크마다 커밋하면 fsync 가 그만큼 늘어난다」는 이유로 전체를 한 트랜잭션에 감쌌다. 쓰기 자체는
+         * 실제로 빨라졌다 — 느린 질의 목록에서 이 INSERT 가 사라졌다. **그런데 서버가 더 느려졌다.**
+         *
+         *   감싸기 전   느린 질의 최대 32.3초 · ROLLBACK 없음
+         *   감싼 뒤     느린 질의 최대 50.2초 · ROLLBACK 36.3초 등장
+         *
+         * 기전은 드라이버다. TypeORM 의 sqlite 드라이버는 연결을 **하나**만 든다(풀 없음). 트랜잭션이
+         * 열려 있는 동안 그 유일한 연결은 이 묶음의 것이므로, **묶음이 끝날 때까지 앱의 모든 질의가
+         * 기다린다.** 청크마다 커밋하면 그 사이에 다른 질의가 끼어들 자리가 생긴다 — fsync 를 더 치르는
+         * 대신 **머리 막힘이 짧아진다.**
+         *
+         * 즉 여기서는 「커밋 수를 줄이는 것」이 목적이 아니다. 목적은 **한 번에 오래 붙잡지 않는 것**이다.
+         * 저널 묶음의 원자성은 그 대가를 치를 만큼의 값이 아니다: 저널은 append-only 이고 리비전이
+         * 이어지므로, 절반만 들어간 묶음은 다음 기동의 replay 가 그 지점부터 이어받는다.
+         *
+         * 연결 풀이 있는 드라이버(postgres·mysql)에서는 판단이 달라질 수 있다 — 그때는 이 주석을 근거로
+         * 다시 재고 정하라. **드라이버마다 다른 결론이 나는 자리다.**
+         */
+        for (let i = 0; i < rows.length; i += CHUNK)
+            await repo.insert(rows.slice(i, i + CHUNK));
+    }
     /** live 저널 배치 기록 — 모아둔 CanonicalEnvelope 들에 startRevision+1.. 을 부여해 벌크 저장(coalescer tick 당 1회). */
     static async persistBatch(domainId, instanceId, envelopes, startRevision) {
         const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
         const structureRev = await this.structureRevOf(domainId, instanceId);
         const rows = envelopes.map((e, i) => this.journalRow(repo, domainId, instanceId, e, startRevision + i + 1, structureRev));
-        await repo.save(rows, { chunk: 500 });
+        await this.insertRows(repo, rows);
     }
     /** 레지스트리 upsert(도메인+instanceId 유니크). status 인자로 provision(stopped)/start(running) 공용. */
     static async register(domainId, instanceId, kind, model, status = 'running', restartPolicy, origin, 
@@ -1180,7 +1858,7 @@ class TwinEngine {
             spaceId: model?.spaceId ?? existing?.spaceId,
             areaId: model?.areaId ?? existing?.areaId,
             /* 재기동 정책(ADR-0029 §2) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
-               **둘 다 없으면 던진다**: 예전에는 여기서 기본값을 각인했는데, 그 기본값이 「저널 초기화」라서
+               **둘 다 없으면 오류를 낸다**: 예전에는 여기서 기본값을 각인했는데, 그 기본값이 「저널 초기화」라서
                선언을 빠뜨린 프로비저닝이 조용히 이력을 지우는 트윈을 만들었다. 선언은 부르는 쪽의 몫이다. */
             restartPolicy: restartPolicy ??
                 (0, restart_policy_js_1.readRestartPolicy)(existing?.restartPolicy, `register("${instanceId}") did not declare a restart policy and the stored row has none`),
@@ -1242,7 +1920,7 @@ class TwinEngine {
         if (!this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)])
             return;
         /*
-         * **거절도 번역돼야 한다.** 이 문장은 던져져서 리졸버의 `catch` 를 지나 화면 토스트에 그대로
+         * **거절도 번역돼야 한다.** 이 문장은 전달되어 리졸버의 `catch` 를 지나 화면 토스트에 그대로
          * 떴다 — 다섯 언어 제품에서 영어 한 줄이 사용자에게 보였다(2026-08-14 실측).
          *
          * 그래서 코드와 파라미터를 예외에 실어 보낸다(`ImportSpaceRefusal` 과 같은 규약: 영어 문장은
@@ -1297,20 +1975,22 @@ class TwinEngine {
          * 실패는 흡수한다: 투영이 막혀도(예: 모델에 중복 id) 커널은 이미 새 구조로 돌고 있으므로 그 사실을
          * 되돌리지 않는다 — 다만 조용히 넘기지 않고 말한다.
          */
-        await (0, project_structure_js_1.projectStructure)(domainId, instanceId, model, instanceId).catch((err) => console.warn(`[twin-engine] "${instanceId}" adopted a new structure but its projected rows were not refreshed — ${err?.message ?? err}`));
+        await (0, project_structure_js_1.projectStructure)(domainId, instanceId, model, instanceId).catch((err) => (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}" adopted a new structure but its projected rows were not refreshed — ${err?.message ?? err}`));
         /*
-         * **구조가 바뀐 순간이 상태가 바뀐 순간이다** — 그러니 방송한다.
+         * **구조가 바뀐 순간이 상태가 바뀐 순간이다** — 그러니 브로드캐스팅한다.
          *
          * ── 무엇이 났나 (2026-08-18) ────────────────────────────────────────────
          * 구조 전환은 커널만 갈고 조용히 끝났다. 그런데 화면이 보는 것 상당수가 구조에서 파생된다 —
          * 계약 대비 판정, 주목 신호, 자리 색. 현장이 계약을 고쳐 선언한 순간 조건이 성립하는데도, 상태
-         * 방송이 없어서 지도 레일은 **다음 계측 표본이 올 때까지** 옛 화면을 들고 있었다(그 사이 헤더
+         * 브로드캐스팅이 없어서 지도 레일은 **다음 계측 표본이 올 때까지** 옛 화면을 들고 있었다(그 사이 헤더
          * 배지는 4초 폴링으로 먼저 알아, 「배지엔 있고 목록엔 없는」 어긋난 화면이 실제로 보였다).
          *
-         * 새 방송 경로를 만들지 않는다: dirty 를 세워 **이미 있는 병합 규율**(200ms)에 얹는다. 구조 전환은
-         * 드물지만, 여러 트윈에 잇달아 들어올 수 있고(현장 일괄 선언) 그때도 방송률 상한은 지켜야 한다.
+         * 새 브로드캐스팅 경로를 만들지 않는다: dirty 를 세워 **이미 있는 병합 규율**(200ms)에 얹는다. 구조 전환은
+         * 드물지만, 여러 트윈에 잇달아 들어올 수 있고(현장 일괄 선언) 그때도 브로드캐스팅률 상한은 지켜야 한다.
          */
         inst.dirty = true;
+        /* 구조가 갈렸으면 무엇이 달라졌는지 사건으로 말할 수 없다 — 전부 다시 만든다. */
+        this.markItemsDirty(inst);
         this.ensureBroadcastCoalescer();
         return { rev, ...shift };
     }
@@ -1451,6 +2131,43 @@ 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)`);
+        /*
+         * ── 선언된 `restartPolicy` 가 **기동 방식을 정한다** (2026-08-20) ──────────
+         *
+         * 예전에는 이 함수가 정책을 **읽어서 넘기기만** 했고, 기동은 언제나 시뮬 경로였다. 그래서 미러로
+         * 선언한 트윈을 화면에서 시작하면 **시뮬로 떴다** — 그 트윈은 유입을 받지 못한다(`ingestLive` 는
+         * 라이브가 아니면 0 을 돌려준다). 오류는 나지 않고, 화면에는 「running」이라 적힌다.
+         *
+         * 부팅 경로(`resumeRow`)에는 그 갈림이 있었는데 여기에는 없었다. 즉 **부팅으로 살아난 미러는
+         * 받고, 사람이 시작한 미러는 받지 못했다.** 같은 선언이 두 결과를 내는 것은 결함이다.
+         *
+         * 갈림을 여기 한 곳에 둔다 — 부팅도 이 문을 지난다.
+         *
+         * ── `reset` 은 선언대로 **저널을 비운다** (2026-08-20) ───────────────────
+         * 「seed 재현」은 백지에서 다시 시작한다는 뜻이다. 예전에는 그 선언이 구현되지 않아 `reset` 트윈이
+         * 사실상 이어졌고, 그래서 「이 트윈의 이력은 왜 재기동을 넘겨 남아 있나」를 아무도 설명할 수 없었다.
+         *
+         * 이것은 **사실을 지우는 동작**이라 순서를 지켜 켰다: 먼저 사람이 각 트윈의 정책을 다시 선언할 문을
+         * 만들고(`setTwinRestartPolicy`), 이력을 두고 볼 트윈을 `resume` 으로 옮긴 뒤에 켠다. 그 순서를
+         * 뒤집으면 선언을 지킨 대가로 남의 이력을 지운다.
+         */
+        const policy = restartPolicy ?? (0, restart_policy_js_1.readRestartPolicy)(reg.restartPolicy, `twin "${instanceId}"`);
+        if (policy === 'resync') {
+            /* 미러는 **관측 구동**으로 세운다 — 시뮬로 세우면 없던 움직임을 스스로 만든다.
+               시각 기준은 공간이 갖는다(부팅 경로와 같은 규칙). */
+            return this.startLive(instanceId, domainId, reg.kind, await this.withSpaceTimeBase(reg.model, domainId));
+        }
+        if (policy === 'reset') {
+            /*
+             * 씨앗 재현 — 저널을 비우고 리비전 0 부터 다시 센다. 복구본도 함께 버린다(`resetJournal` 이 한다):
+             * 남겨 두면 백지로 시작한 트윈에 옛 상태가 되살아나 「씨앗 재현」이 아니게 된다.
+             *
+             * **벤치 사본은 예외다.** 그것은 누군가 지켜보는 실험이고, 그 실험의 기록을 기동이 지우면 실험이
+             * 사라진다(부팅은 벤치를 되살리지도 않는다 — `resumeRow`).
+             */
+            if (reg.purpose !== 'bench')
+                await this.resetJournal(domainId, instanceId);
+        }
         /*
          * 웜스타트 재료를 **여기서 확실히 확보한다.**
          * `start()` 는 동기라 스스로 캐시를 읽을 수 없어서 `recovered` 에 미리 담겨 있기를 기대하는데,
@@ -1459,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);
@@ -1486,8 +2203,8 @@ class TwinEngine {
         /* 커널 종류·현실 선언은 레지스트리에 반드시 있다(둘 다 NOT NULL). 예전에는 `?? 'wms'` 로
            메웠는데, 그건 YMS/MES 트윈을 **조용히 WMS 로 부팅**시키는 길이었다 — 오류 없이 다른 공장이 뜬다. */
         reg.kind, reg.model, 
-        /* 저장된 값은 **엄격히** 읽는다 — 모르는 값을 기본값으로 메우면 그 트윈이 조용히 다르게 재기동한다. */
-        restartPolicy ?? (0, restart_policy_js_1.readRestartPolicy)(reg.restartPolicy, `twin "${instanceId}"`), reg.purpose, Number(last?.max ?? 0) || 0);
+        /* 저장된 값은 위에서 **엄격히** 읽었다 — 모르는 값을 기본값으로 메우면 그 트윈이 조용히 다르게 재기동한다. */
+        policy, reg.purpose, Number(last?.max ?? 0) || 0);
     }
     /**
      * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 restartPolicy 에 따라 재기동 방식을 구분한다.
@@ -1504,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') {
@@ -1533,6 +2268,23 @@ class TwinEngine {
     static async resetJournal(domainId, instanceId) {
         await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).delete({ domain: { id: domainId }, instanceId });
         delete this.recovered[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        /*
+         * ── **체크포인트도 함께 무효로 만든다** (2026-08-20) ──────────────────────
+         *
+         * 저널만 지우면 씨앗 재현이 되지 않는다: 웜스타트는 체크포인트를 **먼저** 보고, 그것이 남아 있으면
+         * 백지로 시작한 트윈에 옛 상태가 되살아난다(저널은 비었는데 재고가 있는 트윈이 된다).
+         * 시간여행이 딛는 사슬 캐시도 같은 이유로 무효다 — 지워진 리비전을 가리키게 된다.
+         *
+         * 공통 캐시 서비스에는 삭제가 없다(get/set/clearStale 뿐). 그래서 **「없음」을 적는다** — 값을
+         * 지어내는 것이 아니라 「체크포인트가 없다」는 사실을 적는 것이고, 읽는 쪽은 이미 `cached?.state` 로
+         * 그것을 가려낸다. 공통 모듈에 삭제를 새로 뚫는 것은 이 한 자리를 위해 하기에는 큰 변경이다.
+         */
+        await cache_service_1.cacheService
+            .setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, { revision: 0, state: null }, this.SNAPSHOT_TTL_S)
+            .catch(err => (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}" checkpoint not invalidated — a seed run may inherit old state:`, err?.message ?? err));
+        await cache_service_1.cacheService
+            .setInCache(this.CHAIN_INDEX_CACHE_ID, { domainId, instanceId }, { revisions: [] }, this.SNAPSHOT_TTL_S)
+            .catch(err => (0, log_js_1.twinWarn)(`[twin-engine] "${instanceId}" chain index not cleared — time travel may point at deleted revisions:`, err?.message ?? err));
     }
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     static async remove(domainId, instanceId) {
@@ -1568,30 +2320,60 @@ class TwinEngine {
          */
         const spaceNameOf = new Map((await (0, shell_1.getRepository)(twin_space_js_1.TwinSpace).find({ where: { domain: { id: domainId } } })).map(s => [s.spaceId, s.name]));
         /*
-         * **최신 리비전은 한 번에 묻는다.**
+         * **최신 리비전은 트윈마다 인덱스 끝에서 한 행씩 읽는다.**
+         *
+         * ── 그룹 질의로 바꾸었다가 되돌렸다 (2026-08-22 실측) ─────────────────────
+         * 예전 주석은 이랬다: 「트윈마다 `findOne(order revision DESC)` 을 돌고 있었다 — 13개면 질의
+         * 13번이고, 트윈이 늘면 그대로 자란다. 한 번의 그룹 질의로 바꾼다.」
+         *
+         * **질의 개수를 줄였지만 일의 양을 늘렸다.**
          *
-         * 트윈마다 `findOne(order revision DESC)` 을 돌고 있었다 — 13개면 질의 13번이고, 트윈이 늘면
-         * 그대로 자란다. 이 목록은 트윈 관리·현장 구성·엔티티 패널이 모두 읽는 자리다.
-         * 한 번의 그룹 질의로 바꾼다(같은 모양의 선례가 이 파일에 이미 있다: structureRev 집계).
+         *   findOne × 13    `(domain, instance, revision)` 인덱스 **끝에서 한 행** — 각각 O(1)
+         *   GROUP BY 한 번  그 도메인의 저널을 **전수 집계** — O(전체)
+         *
+         * 저널이 작을 때는 이득이었고, 커지면서 손해가 됐다. 실측(저널 1,134만 행): 이 그룹 질의가
+         * **44.7초**였다. 그리고 sqlite 드라이버는 연결이 하나이므로 그동안 앱의 모든 질의가 그 뒤에 섰다 —
+         * 같은 순간 29행짜리 `twin_instances` 조회도 44.7초로 찍혔다. 이 목록은 「트윈 관리·현장 구성·
+         * 엔티티 패널이 모두 읽는 자리」여서, 화면을 열 때마다 서버 전체가 그만큼 멈췄다.
+         *
+         * 트윈 수는 수십이고 저널은 천만이다. **작은 것을 여러 번 읽는 편이 큰 것을 한 번 훑는 것보다 싸다.**
+         * 질의 개수가 트윈 수에 비례해 자라는 것은 사실이지만, 각 질의가 인덱스 끝 한 행이므로 그 성장은
+         * 감당된다 — 그리고 병렬로 묻는다.
+         *
+         * **다시 그룹 질의로 바꾸지 말 것.** 바꾸려면 이 숫자를 먼저 다시 재라.
          */
         const tipOfInstance = new Map();
-        try {
-            const tips = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
-                .createQueryBuilder('e')
-                .select('e.instanceId', 'instanceId')
-                .addSelect('MAX(e.revision)', 'revision')
-                .where('e.domain = :domainId', { domainId })
-                .groupBy('e.instanceId')
-                .getRawMany();
-            for (const t of tips)
-                if (t?.instanceId != null)
-                    tipOfInstance.set(String(t.instanceId), Number(t.revision) || 0);
-        }
-        catch (err) {
-            /* 집계가 실패하면 **0 으로 메우지 않는다** — 리비전 0 은 "아직 아무 일도 없었다" 는 사실 주장이다.
-               비워 두면 아래에서 `?? 0` 이 아니라 undefined 로 남고, 화면은 그것을 "모름" 으로 그린다. */
-            console.error('[twin-engine] latest revision aggregate failed', err?.message ?? err);
-        }
+        await Promise.all(rows.map(async (r) => {
+            try {
+                /*
+                 * **집계 하나로 묻는다 — 행을 실어 오지 않는다.**
+                 *
+                 * `findOne(order revision DESC)` 로 두었더니 두 가지가 틀렸다. ① 관계를 가진 엔티티의 정렬
+                 * 조회는 TypeORM 이 `DISTINCT` 로 감싸므로 `select` 로 컬럼을 좁히면 `distinctAlias.
+                 * TwinEvent_id` 가 없다고 터진다(실측: 모든 트윈에서 SQLITE_ERROR). ② `select` 를 떼면
+                 * **`payload` 까지 실어 온다** — 이 값 하나를 알려고 큰 TEXT 를 읽는다.
+                 *
+                 * 그래서 단일 집계를 쓴다. `(domain, instance, revision)` 인덱스에서 instance 가 정해지면
+                 * `MAX` 는 그 구간의 끝이므로 sqlite 가 끝을 집는다(실측 0.007초 · 도메인 전체 GROUP BY 는
+                 * 14.5초). 이 파일의 다른 자리도 같은 규율이다(§`timeRange` · 기동 시 최종 리비전).
+                 */
+                const row = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+                    .createQueryBuilder('e')
+                    .select('MAX(e.revision)', 'revision')
+                    .where('e.domain = :domainId', { domainId })
+                    .andWhere('e.instanceId = :instanceId', { instanceId: r.instanceId })
+                    .getRawOne();
+                /* 행이 없으면 `null` 이다 — 그때는 비워 둔다(0 은 "아무 일도 없었다" 는 주장이다). */
+                if (row?.revision != null)
+                    tipOfInstance.set(String(r.instanceId), Number(row.revision) || 0);
+            }
+            catch (err) {
+                /* 한 트윈의 조회가 실패해도 **0 으로 메우지 않는다** — 리비전 0 은 "아직 아무 일도 없었다" 는
+                   사실 주장이다. 비워 두면 아래에서 undefined 로 남고, 화면은 그것을 "모름" 으로 그린다.
+                   그리고 그 트윈만 모름이 된다 — 예전에는 집계 하나가 실패하면 전부 모름이었다. */
+                (0, log_js_1.twinError)(`[twin-engine] latest revision lookup failed "${r.instanceId}"`, err?.message ?? err);
+            }
+        }));
         const out = [];
         for (const r of rows) {
             const model = r.model ?? { locations: [], equipment: [] };
@@ -1906,11 +2688,11 @@ class TwinEngine {
             }
         }
         catch (err) {
-            console.error(`[twin-engine] structure projection failed for "${master.source}":`, err?.message);
+            (0, log_js_1.twinError)(`[twin-engine] structure projection failed for "${master.source}":`, err?.message);
             warnings.push((0, reference_master_js_3.projectionFailed)(err?.message ?? 'unknown'));
         }
         if (warnings.length)
-            console.warn(`[twin-engine] ingest "${master.source}" warnings: ${(0, reference_master_js_3.describeWarnings)(warnings)}`);
+            (0, log_js_1.twinWarn)(`[twin-engine] ingest "${master.source}" warnings: ${(0, reference_master_js_3.describeWarnings)(warnings)}`);
         return { instanceId: master.source, spaceId, warnings };
     }
     /** 단건 상세 — 프로비저닝 에디터가 편집할 model(구조+layout) 포함. */
@@ -1932,14 +2714,14 @@ class TwinEngine {
      * 보드 컴포넌트가 tag 로 구독(board-ui provider)해 `component.data` 로 라이브 갱신. delta 시에만(희소).
      * tag=엔티티 id(데모=단일 인스턴스). 멀티 인스턴스/보드 재사용 시 tag 네임스페이스는 후속.
      */
-    /** 방송 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
+    /** 브로드캐스팅 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
     static { this.publishDrops = new Map(); }
     static { this.PUBLISH_DROP_LOG_MS = 10_000; }
     /**
-     * 한 번의 방송 — **구독자 하나가 호스트를 죽이지 못하게.**
+     * 한 번의 브로드캐스팅 — **구독자 하나가 호스트를 죽이지 못하게.**
      *
      * ── 무엇이 죽였나 (2026-08-14) ─────────────────────────────────────────────
-     * 밀린 push 가 1024를 넘으면 pubsub 이 던진다(`RepeaterOverflowError`). 그 방송은 타이머 콜백
+     * 밀린 push 가 1024를 넘으면 pubsub 이 오류를 낸다(`RepeaterOverflowError`). 그 브로드캐스팅은 타이머 콜백
      * 안에서 일어나므로 예외가 잡히는 곳 없이 올라가 **프로세스가 끝났다** — 트윈 14개가 도는 호스트가
      * 소비를 멈춘 구독자 하나 때문에 통째로.
      *
@@ -1957,7 +2739,7 @@ class TwinEngine {
             const now = Date.now();
             if (now - d.lastLogMs >= this.PUBLISH_DROP_LOG_MS) {
                 d.lastLogMs = now;
-                console.warn(`[twin-engine] broadcast dropped on "${what}" (${d.count} so far) — ${err?.message ?? err}`);
+                (0, log_js_1.twinWarn)(`[twin-engine] broadcast dropped on "${what}" (${d.count} so far) — ${err?.message ?? err}`);
             }
             this.publishDrops.set(what, d);
             return false;
@@ -1981,16 +2763,35 @@ class TwinEngine {
             return;
         /*
          * 변화한 엔티티만 발행 — 이전엔 delta 마다 전 엔티티(노드+무버+오더)를 값 변화와 무관하게 전량 재발행해
-         * 같은 데이터를 매초 반복 push 하고 있었다(오용). 최신-상태 채널이므로 무변화 재방송은 무의미하다.
+         * 같은 데이터를 매초 반복 push 하고 있었다(오용). 최신-상태 채널이므로 무변화 재브로드캐스팅은 무의미하다.
          * 엔티티별 시그니처를 비교해 바뀐 것만 push.
          */
         const sigs = inst.entitySigs ?? (inst.entitySigs = new Map());
         const seen = new Set();
         /* payload 매핑은 순수 함수(buildEntityDeltas)로 분리 — 여기선 시그니처 dedup + 발행만.
-         * 변화한 엔티티만 발행(최신-상태 채널이라 무변화 재방송 무의미). */
+         * 변화한 엔티티만 발행(최신-상태 채널이라 무변화 재브로드캐스팅 무의미). */
         /* ② payload 만들기 — 엔티티 수에 비례. ③ 시그니처 비교 + 발행 — 바뀐 것 수에 비례. */
         const tDelta = performance.now();
-        const deltas = (0, entity_delta_js_1.buildEntityDeltas)(st, inst.id);
+        /*
+         * ── 물품은 **건드린 것만** 만든다 (2026-08-21 실측) ──────────────────────
+         * 만드는 payload 의 대부분이 물품이다(엔티티 3,611 중 2,400). 바뀐 것이 하나여도 전부 만들어
+         * 문자열로 바꾼 뒤 「같다」를 확인하고 버렸다.
+         *
+         * 범위는 이 창에 들어온 사건에서 모았다(`touchedItemKeys`). **말할 수 없는 사건이 하나라도 있으면
+         * 범위는 없고 전부 만든다** — 낯선 어휘가 오면 조용히 빠뜨리는 대신 비싸게 안전한 쪽으로 떨어진다.
+         *
+         * 그리고 주기마다 한 번은 **무조건 전부** 만든다(`FULL_BROADCAST_EVERY`). 커널이 사건 없이 물품을
+         * 바꾸는 자리가 생기면 그 값이 화면에 남을 수 있는데, 그 창을 몇 초로 묶는 그물이다. **보장이 아니라
+         * 그물이다** — 사건 없이 바뀌는 자리를 찾으면 그것을 고치는 것이 답이고 이 그물은 시간을 벌 뿐이다.
+         */
+        const full = inst.fullBroadcastDue === true || !inst.dirtyItems;
+        const deltas = (0, entity_delta_js_1.buildEntityDeltas)(st, inst.id, full ? undefined : { items: inst.dirtyItems });
+        this.broadcastPasses++;
+        if (full)
+            this.broadcastFullPasses++;
+        /* 이번 창의 범위는 여기서 닫는다 — 다음 창은 다시 모은다. */
+        inst.dirtyItems = new Set();
+        inst.fullBroadcastDue = false;
         (0, load_meter_js_1.recordPhase)(load, 'deltas', performance.now() - tDelta);
         const tPub = performance.now();
         for (const { tag, data } of deltas) {
@@ -2007,16 +2808,23 @@ class TwinEngine {
                 sigs.delete(tag);
         }
         (0, load_meter_js_1.recordPhase)(load, 'publish', performance.now() - tPub);
-        /* 사라진 엔티티의 시그니처 정리(맵 무한 성장 방지). */
-        if (sigs.size > seen.size)
+        /*
+         * 사라진 엔티티의 시그니처 정리(맵 무한 성장 방지) — **전부 만든 창에서만.**
+         * 범위를 좁힌 창의 `seen` 에는 만들지 않은 엔티티가 없으므로, 그때 정리하면 살아 있는 태그의
+         * 시그니처를 지운다. 낡은 값이 나가는 것은 아니지만(다음 창에 다시 만들어 보낸다) 같은 값을
+         * 되풀어 보내게 되어, 줄이려던 것을 되돌린다.
+         */
+        if (full && sigs.size > seen.size)
             for (const tag of sigs.keys())
                 if (!seen.has(tag))
                     sigs.delete(tag);
     }
-    static async persist(domainId, instanceId, msg) {
-        const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
-        await repo.save(this.journalRow(repo, domainId, instanceId, msg.event, msg.revision, await this.structureRevOf(domainId, instanceId)));
-    }
+    /*
+     * 단건 저장(`persist`)은 **없앴다** (2026-08-20, §7.1).
+     *
+     * 시뮬이 델타마다 이것을 불러 행 하나씩 썼고, 그것이 규모에서 호스트를 먹었다. 남겨 두면 다음 사람이
+     * 다시 부를 자리가 되므로 지운다 — 쓰는 문은 `flushJournal` 하나다(`persistBatch`·`persistCarried`).
+     */
     /**
      * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
      * model 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서.
@@ -2105,6 +2913,10 @@ class TwinEngine {
         const baseWhere = { domain: { id: domainId }, instanceId };
         /* 이어 접을 때는 **그 뒤만** 읽는다 — 재개점까지의 사실은 이미 씨앗 안에 있다. */
         const from = resume ? (resume.revision ?? 0) : undefined;
+        /*
+         * journal-fold: 재생은 사실을 하나씩 접는 것이므로 그 구간의 행이 필요하다. 커서(`from`)와 시각
+         * 상한이 구간을 자르고, 체크포인트가 앞쪽을 씨앗으로 대신한다 — 표 전체를 읽지 않는다.
+         */
         const rows = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({
             where: useTime
                 ? from
@@ -2281,24 +3093,68 @@ class TwinEngine {
     /**
      * 공간(공동배치) 시각 범위 — 스크러버 앵커(runtime-state-model §4·§6). 그 공간 전 인스턴스 저널의 min/max eventTime.
      * 반환 {minTime, maxTime}(ISO) — 이벤트/시각 없으면 null. 클라 히스토리 스크러버가 이 범위를 시각축으로 그린다.
+     *
+     * ── 두 수를 구하려고 저널을 다 읽지 않는다 (2026-08-20 실측으로 잡음) ────────
+     * 여기서 인스턴스마다 `find()` 로 **행을 전부 엔티티로 하이드레이션**한 다음 JS 에서 min/max 를
+     * 골랐다. 그런데 이 함수는 화면 상단의 컨텍스트 띠가 **4초마다** 부른다. 실측한 개발 서버에서
+     * `order-check` 한 트윈이 275,882행 · `payload` 131MB 였다 — 4초마다 그 JSON 을 전부 파싱한 것이다.
+     *
+     * 그 결과가 이랬다: 프로세스 CPU 81~152%, 아무 일도 하지 않는 질의가 8~14초. JS 프로파일의 상위가
+     * TypeORM 의 `RelationIdLoader`·`RawSqlResultsToEntityTransformer`·`stringToSimpleJson`(= `payload`
+     * 파싱)이고 GC 가 16.7% 였다. **트윈 틱도 저널 쓰기도 아니라 이 읽기였다.**
+     *
+     * 집계는 DB 가 한다. `(domain, instanceId, eventTime)` 인덱스가 이미 있어(`ix_twin_event_1`)
+     * 인덱스의 **양 끝을 집는다** — 행을 하나도 실어 오지 않는다.
+     *
+     * ── 왜 MIN 과 MAX 를 한 문장에 넣지 않나 (실측) ─────────────────────────────
+     * 처음에 `SELECT MIN(...), MAX(...) ... WHERE instanceId IN (...)` 한 방으로 두었더니 **21ms** 였다.
+     * 집계가 **둘이면** 옵티마이저의 「인덱스 끝을 집는」 최적화가 걸리지 않아 인덱스 구간을 훑는다 —
+     * 즉 비용이 여전히 **행 수에 비례**한다. 트윈마다 단일 집계로 나눠 물으면 **0.32ms**(트윈 3개 · 6왕복)
+     * 이고, 비용이 **트윈 수에 비례**한다. 규모 기준(엔티티 10만)에서는 이 차이가 본질이다.
+     *
+     * 왕복은 트윈당 둘이지만 **함께 띄운다** — 원격 DB 에서 직렬로 돌면 왕복 지연이 그대로 쌓인다.
+     *
+     * 드라이버 다섯을 다 지나가야 하므로 raw SQL 을 쓰지 않는다(쿼리빌더의 MIN/MAX 는 이식된다).
+     * 돌려주는 값의 **모양은 드라이버마다 다르다**(문자열·Date) — 받은 뒤에 한 번 정규화한다(`parseTime`).
      */
     static async timeRange(domainId, spaceId) {
         const regs = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, spaceId } });
         const ids = regs.map(r => r.instanceId);
         if (!ids.length)
             return { minTime: null, maxTime: null };
+        /**
+         * 한 트윈 저널의 시각 양 끝 하나 — 단일 집계라 인덱스 끝을 집는다.
+         *
+         * 집계식을 **조립하지 않고 표에 리터럴로 적는다.** `` `${agg}(e.eventTime)` `` 로 만들면 이 자리가
+         * 집계를 쓰는지 훑는 검사(`journal-read-discipline`)가 찾지 못한다 — 실제로 그렇게 빨개졌다.
+         * 번역 키에서 겪은 것과 같은 규율이다: 검사가 일하게 두는 편이 낫다.
+         */
+        const AGG_SELECT = { MIN: 'MIN(e.eventTime)', MAX: 'MAX(e.eventTime)' };
+        const edge = async (instanceId, agg) => {
+            const row = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+                .createQueryBuilder('e')
+                .select(AGG_SELECT[agg], 't')
+                .where('e.domain = :domainId', { domainId })
+                .andWhere('e.instanceId = :instanceId', { instanceId })
+                .getRawOne();
+            return parseTime(row?.t);
+        };
         let min = Infinity;
         let max = -Infinity;
-        for (const instanceId of ids) {
-            const rows = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where: { domain: { id: domainId }, instanceId } });
-            for (const r of rows) {
-                const t = r.eventTime != null ? Date.parse(String(r.eventTime)) : NaN;
-                if (Number.isNaN(t))
-                    continue;
-                if (t < min)
-                    min = t;
-                if (t > max)
-                    max = t;
+        /*
+         * 한 번에 띄우는 수를 묶는다 — 공간에 트윈이 수백이면 왕복 수백 개를 동시에 보내 커넥션 풀을
+         * 말려 버린다(이 함수 하나 때문에 다른 질의가 기다리게 된다).
+         */
+        for (let i = 0; i < ids.length; i += TIME_RANGE_FANOUT) {
+            const batch = ids.slice(i, i + TIME_RANGE_FANOUT);
+            const edges = await Promise.all(batch.flatMap(id => [edge(id, 'MIN'), edge(id, 'MAX')]));
+            for (let k = 0; k < edges.length; k += 2) {
+                const lo = edges[k];
+                const hi = edges[k + 1];
+                if (lo !== null && lo < min)
+                    min = lo;
+                if (hi !== null && hi > max)
+                    max = hi;
             }
         }
         if (min === Infinity)
@@ -2319,13 +3175,19 @@ class TwinEngine {
              * 남기지 않으면 다음 조회가 저널을 전량 다시 접는다(그 값은 어차피 방금 메모리에 있던 것이다).
              * 체크포인트 루프가 20초마다 뜨지만 그 사이에 멈추면 그 구간이 통째로 다시 접힌다.
              */
-            await this.persistSnapshot(domainId, id).catch(err => console.error(`[twin-engine] snapshot on stop fail "${id}"`, err?.message ?? err));
+            await this.persistSnapshot(domainId, id).catch(err => (0, log_js_1.twinError)(`[twin-engine] snapshot on stop fail "${id}"`, err?.message ?? err));
+            /*
+             * **모아 둔 저널도 지금 흘린다** — 주기 flush 사이(최대 `BROADCAST_COALESCE_MS`)에 멈추면 그 구간의
+             * 사실이 사라진다. 스냅샷만 남기면 상태는 살아도 **왜 그렇게 됐는지**가 빈다(저널이 답하는 것이다).
+             * 쓰기는 이 함수를 기다리지 않지만(비차단) 버퍼는 여기서 비워지므로 다음 기동이 두 번 적지 않는다.
+             */
+            await this.flushJournal(i);
             clearInterval(i.timer);
             i.unsub();
             delete this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, id)];
             await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance)
                 .update({ domain: { id: i.domainId }, instanceId: id }, { status: 'stopped' })
-                .catch(err => console.error('twin deregister fail', err));
+                .catch(err => (0, log_js_1.twinError)('twin deregister fail', err));
         }
         for (const hook of this.stopHooks) {
             try {
@@ -2391,7 +3253,7 @@ class TwinEngine {
                 (0, load_meter_js_1.recordPhase)(load, 'tick', took);
                 const j = (0, load_meter_js_1.judgeCycle)(load, took, this.TICK_MS, Date.now());
                 if (j.warn)
-                    console.warn((0, load_meter_js_1.slowTickMessage)(id, took, j.budgetMs, load));
+                    (0, log_js_1.twinWarn)((0, load_meter_js_1.slowTickMessage)(id, took, j.budgetMs, load));
                 this.guardStarvation(domainId, id, took);
             }
         }
@@ -2430,9 +3292,9 @@ class TwinEngine {
     }
     /** 멈추고 **이유를 남긴다** — 이유 없는 「정지」는 사람이 자기가 멈춘 것으로 읽는다. */
     static stopWithNote(domainId, id, note, log) {
-        console.error(log);
+        (0, log_js_1.twinError)(log);
         this.stopNotes.set((0, runtime_key_js_1.runtimeKey)(domainId, id), note);
-        this.stop(domainId, id).catch(err => console.error(`[twin-engine] stop after guard failed "${id}"`, err?.message ?? err));
+        this.stop(domainId, id).catch(err => (0, log_js_1.twinError)(`[twin-engine] stop after guard failed "${id}"`, err?.message ?? err));
     }
     /** 이 트윈이 스스로 멈춘 이유(있으면) — 화면이 옮겨 말한다. */
     static stopNoteOf(domainId, id) {
@@ -2486,7 +3348,7 @@ class TwinEngine {
         }
         if (ack?.accepted && emitted.length) {
             inst.pendingJournal = [...(inst.pendingJournal ?? []), ...emitted];
-            inst.dirty = true; // 코얼레서가 이번 주기에 비우고 방송까지 하게 한다
+            inst.dirty = true; // 코얼레서가 이번 주기에 비우고 브로드캐스팅까지 하게 한다
         }
         return ack ?? { accepted: false, errorCode: 'unknown-command', error: 'unknown-command' };
     }
@@ -2573,7 +3435,7 @@ class TwinEngine {
             instanceId: id,
             ingestedTotal: m.ingestedTotal, broadcastTotal: m.broadcastTotal, journaledTotal: m.journaledTotal,
             ingestRate: m.ingestRate, broadcastRate: m.broadcastRate, journalRate: m.journalRate,
-            backlog: m.backlog, broadcastCoalesceMs: this.BROADCAST_COALESCE_MS,
+            backlog: m.backlog, broadcastCoalesceMs: this.broadcastPeriodMs,
             /* 작업별 부하 — 무거운 것부터. 잰 적이 없으면 null(0 으로 채우면 "빠르다" 로 읽힌다). */
             load: (0, load_meter_js_1.loadSummary)(this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, id)]?.load, this.TICK_MS)
         };
@@ -2621,7 +3483,15 @@ class TwinEngine {
         });
         return {
             tickMs: this.TICK_MS,
-            broadcastCoalesceMs: this.BROADCAST_COALESCE_MS,
+            broadcastCoalesceMs: this.broadcastPeriodMs,
+            /* 브로드캐스팅 주기를 늘린 횟수 — 늘어난 주기만 보면 「원래 그런 값」으로 읽힌다. */
+            broadcastBackoffs: this.broadcastBackoffs,
+            /* 물품 범위를 좁히지 못해 전부 만든 횟수 — 좁히기가 실제로 듣고 있는지를 이 값으로 본다. */
+            broadcastPasses: this.broadcastPasses,
+            broadcastFullPasses: this.broadcastFullPasses,
+            broadcastFullEvery: this.FULL_BROADCAST_EVERY,
+            /* **루프가 실제로 얼마나 막혔나** — 트윈 부하와 나란히 놓고 원인을 가린다(loop-lag.ts 주석). */
+            loopLag: loop_lag_js_1.loopLag.view(),
             ...(0, load_meter_js_1.fleetLoad)(rows, this.TICK_MS),
             /* 줄마다 상세 — 화면이 펼쳐 볼 수 있게. 최근 부하 순서는 fleetLoad 가 정한다. */
             details: keys.map(key => { const at = (0, runtime_key_js_1.parseRuntimeKey)(key); return this.load(at.domainId, at.instanceId); }).filter(Boolean)
@@ -2639,7 +3509,174 @@ class TwinEngine {
         if (inst)
             (0, load_meter_js_1.recordPhase)(inst.load ?? (inst.load = (0, load_meter_js_1.newLoadMeter)()), phase, tookMs);
     }
-    /** 전체 라이브 인스턴스 계측(모니터 대시보드용). */
+    /*
+     * ── 동기화 건강 장부 ───────────────────────────────────────────────────────
+     *
+     * **런타임이 아니라 엔진이 든다.** 인스턴스에 붙이면 트윈을 재기동할 때 사라지는데, 사람이 알고 싶은
+     * 것은 바로 그 순간이다 — 「고쳐서 다시 띄웠는데 이제 통과하나」. 프로세스가 사는 동안 이어진다.
+     *
+     * 지금은 메모리만이다. 창이 닫힐 때 한 행씩 영속하는 것은 `onWindowClosed` 한 자리에 붙는다.
+     */
+    static { this.ingestLedgers = {}; }
+    /**
+     * 닫힌 창을 받을 곳을 등록한다 — **영속(B)이 붙는 유일한 문.**
+     *
+     * 이 패키지는 저장 계층을 모른다. 등록하는 쪽이 자기 방식으로 쓴다. 훅이 오류를 내도 장부는 계속 굴러간다
+     * (`rollIngestWindow` 가 감싼다) — 영속을 지키려고 관측을 멈추지 않는다.
+     */
+    static onIngestWindowClosed(fn) {
+        this.onWindowClosed = fn;
+    }
+    /**
+     * 한 번의 인제스트 결과를 장부에 적는다.
+     *
+     * `offered` 는 **제시된 레코드 수**다(거부 여부 무관). 통과율을 서로 다른 두 계수기에서 나눠 계산하면
+     * 분모와 분자가 다른 것을 세게 되므로, 한자리에서 본 수를 그대로 넘긴다.
+     */
+    static recordIngestResult(domainId, instanceId, offered, rejected, nowMs = Date.now(), 
+    /**
+     * 매핑은 통과했는데 **커널이 받지 않은** 수(`ingestLive` 의 반환과 견주어 얻는다).
+     *
+     * 「통과」로 세지 않는다 — 트윈이 멈춘 사이 사실이 사라지는데 화면이 100% 라고 말하게 된다.
+     */
+    undelivered = 0) {
+        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.recordIngest)(ledger, offered, rejected, nowMs, closed => this.onWindowClosed?.({ domainId, instanceId }, closed), undelivered);
+    }
+    /**
+     * **원본에 닿지 못했다**를 적는다 — 「받은 것이 없다」와 가른다(§`recordReadFailure`).
+     *
+     * 이 문이 없던 동안 실 원본이 끊겨도 트윈의 조회 가능한 상태에 그 사실이 없었다. 화면이 볼 수 있는
+     * 것은 「새 사실이 없다」뿐이었고 그것은 「원본이 조용하다」와 구별되지 않는다 — 실증 중에 원본이
+     * 끊기면 사용자가 원인을 찾을 수 없다.
+     *
+     * 로그로는 말하고 있었다(어댑터가 재시도를 경고한다). 그러나 **로그는 사람이 볼 때만 값이 있다** —
+     * 화면이 말하려면 상태에 있어야 한다.
+     */
+    static recordIngestReadFailure(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.recordReadFailure)(ledger, reason, nowMs, stream);
+    }
+    /**
+     * 읽기가 성공했다 — 단절 기록을 지운다.
+     *
+     * **빈 읽기도 성공이다.** 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이므로, 그때도 부른다.
+     * 그 둘을 같게 두면 조용한 원본이 끊긴 원본으로 보인다.
+     */
+    static clearIngestReadFailure(domainId, instanceId) {
+        const ledger = this.ingestLedgers[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        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);
+    }
+    /** 창을 넘겼다 — 정체 기록을 지운다(풀린 정체가 화면에 남아 있으면 그것도 거짓이다). */
+    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분 창에.
+     *
+     * ── 왜 유입 장부에 넣나 ────────────────────────────────────────────────────
+     * 새 장부를 만들면 「닫힌 창만 최근」·「0 과 없음을 가른다」·영속을 두 벌 지켜야 하고, 그중 한 벌만
+     * 고쳐지는 것이 보통이다. 유입 창은 그 규율이 이미 들어 있고 닫힐 때 행으로 남는다.
+     *
+     * ── 이 값이 없으면 무엇을 못 보나 ──────────────────────────────────────────
+     * 계기(`journalRate`)는 **지금**만 답한다. 프로세스를 다시 띄우면 0 에서 시작하므로 「어제 이 시각에도
+     * 이랬나」·「고친 뒤로 줄었나」를 물을 자리가 없다. 2026-08-20 에 고친 것이 바로 쓰기 경로이므로,
+     * 되돌아가는 것을 볼 수 있어야 한다.
+     */
+    static recordJournalWrite(domainId, instanceId, rows, 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)());
+        (0, ingest_health_js_1.recordJournalWrite)(ledger, rows, nowMs, closed => this.onWindowClosed?.({ domainId, instanceId }, closed));
+    }
+    /**
+     * 「이 트윈이 현장과 맞춰지고 있나」 — 한눈 판정 + 추이 + 사유 + 표본.
+     *
+     * 조회할 때 창을 한 번 굴린다: 유입이 멈추면 다음 인제스트가 없어 창이 영원히 닫히지 않는데, 그러면
+     * 「최근」이 옛것으로 남는다. 타이머를 두지 않는 이유는 트윈마다 타이머를 걸면 그 타이머들이 다시
+     * 메인 루프에 얹히기 때문이다(오늘 확인한 그 부하를 이 기능이 다시 만들 이유가 없다).
+     */
+    /**
+     * 도메인의 트윈마다 **한 줄 요약** — 목록 화면과 미니 추이용.
+     *
+     * ── 왜 상세와 따로인가 ─────────────────────────────────────────────────────
+     * `ingestHealthOf` 는 사유 문구와 **레코드 원문 표본**까지 낸다. 목록에 트윈이 스무 개면 그 원문이
+     * 스무 벌 실려 조회가 무거워지고, 화면은 어차피 그것을 그리지 않는다. 그래서 여기서는 **숫자만** 낸다.
+     *
+     * 추이는 창당 숫자 넷이라 스파크라인 하나에 충분하고 가볍다.
+     *
+     * ── 등록된 트윈을 기준으로 훑는다 ──────────────────────────────────────────
+     * 도는 트윈만 훑으면 「고치려고 멈춰 둔 트윈」이 목록에서 사라진다 — 사람이 방금 멈춘 그것을 보려고
+     * 목록을 여는데 없으면 결함으로 읽는다. 그래서 호출부(목록 화면)가 아는 instanceId 들을 받는다.
+     */
+    static ingestHealthBrief(domainId, instanceIds) {
+        return instanceIds.map(instanceId => {
+            const full = this.ingestHealthOf(domainId, instanceId);
+            return {
+                instanceId,
+                verdict: full.verdict,
+                /* 최근 **닫힌** 창의 통과율. 창이 안 닫혔으면 비운다 — 0 이나 1 로 채우지 않는다. */
+                acceptedRatio: full.recent?.acceptedRatio ?? null,
+                /*
+                 * 스파크라인용 — 창마다 셋. **미전달을 빼놓으면 스파크라인이 거짓을 그린다**: 버려진 것을
+                 * 통과로 세면 트윈이 멈춘 구간에서도 선이 100% 에 붙는다.
+                 */
+                /* 적힌 행도 함께 — 시뮬 트윈은 유입이 0 이라 이 값 없이는 추이가 빈 선으로 보인다. */
+                trend: full.trend.map(w => ({ offered: w.offered, rejected: w.rejected, undelivered: w.undelivered, rows: w.rows })),
+                lastAt: full.lastAt
+            };
+        });
+    }
+    /**
+     * 한 트윈의 동기화 건강.
+     *
+     * ── 조회가 장부를 전진시킨다(의도) ─────────────────────────────────────────
+     * 창은 **다음 유입이 있을 때** 닫힌다. 그래서 피드가 죽으면 마지막 창이 열린 채로 남아 영원히 영속되지
+     * 않고, 추이에도 들어가지 않는다. 조회 시점에 한 번 굴려 주면 그 마지막 창이 닫히면서 영속 훅도 불린다
+     * — 즉 **죽은 피드의 마지막 구간을 잃지 않기 위해** 읽기가 굴린다. 부수효과지만 필요한 부수효과다.
+     *
+     * 시각은 **한 번만 읽어** 굴리기와 판정에 같은 값을 쓴다. 두 번 읽으면 그 사이에 창이 닫혀 판정이
+     * 굴리기 전 상태를 보는 일이 생긴다.
+     */
+    static ingestHealthOf(domainId, instanceId) {
+        const key = (0, runtime_key_js_1.runtimeKey)(domainId, instanceId);
+        const nowMs = Date.now();
+        const ledger = this.ingestLedgers[key];
+        if (ledger) {
+            (0, ingest_health_js_1.rollIngestWindow)(ledger, nowMs, undefined, closed => this.onWindowClosed?.({ domainId, instanceId }, closed));
+        }
+        const inst = this.instances[key];
+        const feedState = (0, live_feed_registry_js_1.liveFeedStateOf)({
+            restartPolicy: inst?.restartPolicy,
+            running: !!inst,
+            instanceId
+        });
+        return (0, ingest_health_js_1.ingestHealth)(ledger, feedState, undefined, nowMs);
+    }
+    /**
+     * 도는 인스턴스 전체의 계측(모니터 대시보드용) — **시뮬과 미러를 함께**.
+     *
+     * 예전에는 시뮬에 계기가 없어 이 목록에서 조용히 빠졌다(계기가 `null` 이라 걸러졌다). 도는 트윈
+     * 대부분이 시뮬인 서버에서 그 목록은 「부하가 거의 없다」로 보였다.
+     */
     static async allMetrics(domainId) {
         /* 도메인 없이 부르면 전 테넌트를 훑는다(내부 모니터용) — 키에서 도메인을 되돌려 각자에게 묻는다. */
         const rows = Object.keys(this.instances)
@@ -2693,6 +3730,14 @@ class TwinEngine {
         if (!state)
             return null;
         const cutoff = untilTime != null ? Date.parse(untilTime) : Infinity;
+        /*
+         * journal-fold: 오더의 마지막 상태는 그 오더에 일어난 사실들을 접어야 나온다.
+         *
+         * **없어질 조건** — 지금 이 읽기에는 상한이 없고 `eventType` 에 인덱스도 없다. 그래서 저널이 큰
+         * 트윈에서는 이 한 번이 그 트윈의 저널 전체 주사다. 오더 상태를 따로 접어 둔 표(투영)를 두거나,
+         * `(domain, instanceId, eventType, revision)` 인덱스를 붙이고 커서를 넣으면 이 예외는 사라진다.
+         * 시각 상한(`cutoff`)을 SQL 로 내려도 절반은 준다.
+         */
         const rows = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({ where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order }, order: { revision: 'ASC' } });
         const latest = new Map();
         for (const r of rows) {