@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -2,10 +2,12 @@ import type { ReducerCheckpoint } from '@operato/twin-kernel';
 import type { OeeCheckpoint } from './oee-accumulator.js';
 import { type ReferenceMaster } from '../service/reference/reference-master.js';
 import { type IngestWarning } from '../service/reference/reference-master.js';
+import { type RestartPolicy } from './restart-policy.js';
 import { type ModelBasis } from './model-basis.js';
 import { type LoadMeter, type LoadPhase } from './load-meter.js';
 import { type StructureDiff } from './structure-diff.js';
 import { OeeAccumulator } from './oee-accumulator.js';
+import { type IngestHealthView, type IngestWindow } from './ingest-health.js';
 import type { TwinModelDef, StructureShift, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel';
 interface TwinMetrics {
     ingestedTotal: number;
@@ -14,19 +16,30 @@ interface TwinMetrics {
     ingestRate: number;
     broadcastRate: number;
     journalRate: number;
+    /**
+     * **지금 대기 중인** 저널 건수 — 아직 DB 로 나가지 않은 것.
+     *
+     * ── 무엇이 틀렸었나 (2026-08-21) ──────────────────────────────────────────
+     * 예전에는 「마지막 flush 에서 쓴 건수」를 여기 넣었다. 그런데 200ms 마다 모아 한 문으로 넣는 것은
+     * **정상 동작**이다(그렇게 만든 것이 어제 고친 성능 작업이다). 그래서 정상적으로 10건을 쓴 직후
+     * 화면에 「밀림 10」 경고가 떴고, 다음 flush 까지 그 값이 남았다 — 큐는 이미 0 인데도.
+     *
+     * 운영자에게 그것은 「저장이 10건 밀려 있다」로 읽힌다. 거짓 경보는 참 경보를 죽인다.
+     *
+     * 이제 이 값은 **지금 남아 있는 것**이다: 다 나갔으면 0 이고, 정말로 쌓이는 중이면 그 수가 자란다.
+     */
     backlog: number;
     _accIngest: number;
     _accBroadcast: number;
     _accJournal: number;
     _windowStartMs: number;
 }
-export type RealityMode = 'mirror' | 'sim-world' | 'sim-experiment';
-export declare const DEFAULT_REALITY_MODE: RealityMode;
+export type { RestartPolicy } from './restart-policy.js';
 interface InstanceRuntime {
     /** 부하 계기판 — 작업별 소요. 시뮬·라이브 모두 붙는다(누가 루프를 점유하는지 보려면 둘 다 필요하다). */
     load?: LoadMeter;
     /** 현실 출처 선언(§0 프레임 ①). 부팅 거동(reset/resume/resync)의 근거. */
-    realityMode?: RealityMode;
+    restartPolicy?: RestartPolicy;
     id: string;
     domainId: string;
     domain?: any;
@@ -50,8 +63,19 @@ interface InstanceRuntime {
     timer?: any;
     /** 엔티티별 마지막 발행 시그니처 — 값이 바뀐 엔티티만 재발행(무변화 반복 push 방지). */
     entitySigs?: Map<string, string>;
-    /** live 방송 병합(ingest-scale §4.4) — ingest 마다 방송하지 않고 dirty 표시 → coalescer tick 이 주기 방송. */
+    /** live 브로드캐스팅 병합(ingest-scale §4.4) — ingest 마다 브로드캐스팅하지 않고 dirty 표시 → coalescer tick 이 주기 브로드캐스팅. */
     dirty?: boolean;
+    /**
+     * 이 창에 **건드린 물품 태그** — 브로드캐스팅이 그것만 만든다.
+     *
+     * `undefined` 는 「말할 수 없다」다(낯선 사건이 하나라도 왔다) → 전부 만든다. 빈 집합은 「물품은
+     * 하나도 건드리지 않았다」이고, 그 둘은 다른 사실이다.
+     */
+    dirtyItems?: Set<string>;
+    /** 다음 브로드캐스팅에서 전부 만들어야 하나 — 주기마다 한 번은 그물로 전부 만든다. */
+    fullBroadcastDue?: boolean;
+    /** 전부 만들기까지 남은 창 수. */
+    fullBroadcastCountdown?: number;
     /** live 저널 결선 — ingest 이벤트를 모았다가 coalescer tick 에서 배치 기록(이벤트마다 DB write 금지). */
     pendingJournal?: any[];
     /** live 저널 revision 카운터(sim 의 delta revision 대응 — 시간여행·히스토리 노브 앵커). */
@@ -76,6 +100,15 @@ export declare class TwinEngine {
     /** 웜스타트 씨앗 — `instances` 와 **같은 키**(겹치면 남의 스냅샷으로 재고가 섞인다). */
     static recovered: Record<string, any>;
     static TICK_MS: number;
+    /** 부팅 때 트윈 하나를 되살린 뒤 루프를 비워 주는 시간(ms) — 그 사이 도착한 요청이 처리된다. */
+    static BOOT_YIELD_MS: number;
+    private static tickPhase;
+    /**
+     * 흩어진 첫 발화 뒤 주기 틱. **핸들은 항상 진짜 타이머**다 — 정지하는 쪽이 `clearInterval(inst.timer)`
+     * 하나로 끝내야 하므로, 첫 발화 전에는 그 `setTimeout` 을, 이후에는 `setInterval` 을 같은 자리에 둔다
+     * (감싼 객체를 주면 `clearInterval` 이 아무 일도 하지 않고 트윈이 멈추지 않는다 — 조용한 결함이 된다).
+     */
+    private static startTickTimer;
     /** 굶김 문턱 — 틱 간격의 배수(1초 간격이면 5초). 이 시간만큼 호스트가 멈춘다. */
     static STARVE_FACTOR: number;
     /** 연속 몇 번이면 멈추나 — 3번이면 15초를 굶긴 셈이고, 그건 우연이 아니다. */
@@ -93,6 +126,44 @@ export declare class TwinEngine {
     static CHAIN_KEEP: number;
     static SNAPSHOT_TTL_S: number;
     static CHECKPOINT_MS: number;
+    /**
+     * **저널 보존 — 지우는 것은 선언이 있을 때만 한다.**
+     *
+     * ── 왜 필요한가 (2026-08-22 실측) ─────────────────────────────────────────
+     * 개발 저널이 시간당 **581,794행 · 0.85GB** 로 자랐다(하루 20GB). 데모 MES 트윈 셋이 전체의 **97%**
+     * 를 만들고 지우는 것이 없었다. 오늘 고친 것들은 「그 크기에서도 질의가 빠르게」이고, **크기 자체를
+     * 줄이는 것은 아무것도 없었다.** 그러면 며칠마다 같은 자리로 돌아온다.
+     *
+     * ── 그런데 저널을 지우는 것은 사실을 잃는 일이다 ──────────────────────────
+     * 그래서 세 규율을 지킨다.
+     *
+     *  ① **선언이 없으면 아무것도 지우지 않는다.** 기본값은 없음이다 — 조용히 지우는 편이 조용히 쌓는
+     *     것보다 나쁘다. 지우는 것은 사람이 정한다.
+     *  ② **체크포인트가 대신할 수 있는 만큼만.** 스냅샷이 없거나 그 리비전을 넘는 자리는 건드리지 않는다.
+     *     주석이 「만료 시 저널 replay 폴백」이라고 적어 둔 그대로 — 스냅샷이 사라지면 저널이 **유일한**
+     *     복구 수단이므로, 둘을 함께 잃으면 그 트윈의 상태는 되돌릴 수 없다.
+     *  ③ **지운 것을 말한다.** 몇 건을 어느 시각까지 지웠는지 로그에 남긴다. 조용히 줄어든 저널은
+     *     「없었던 일」과 구별되지 않는다.
+     *
+     * 그리고 보존 기간은 **스냅샷 TTL(7일)보다 짧을 수 없다.** 더 짧으면 스냅샷이 살아 있는데 그것이
+     * 가리키는 앞쪽 저널이 없는 구간이 생기고, 시간여행·계보 추적이 그 구간에서 조용히 빈다.
+     */
+    static JOURNAL_RETENTION_DAYS?: number;
+    /**
+     * **도메인마다 다른 보존 기간을 앱이 답한다** — 엔진은 그 값이 어디서 오는지 모른다.
+     *
+     * 보존 기간은 테넌트의 정책이다: 한 고객은 30일이 필요하고 다른 고객은 7일이면 된다. 그런데 엔진이
+     * `Setting` 을 읽게 만들면 **엔진이 화면 관심사를 알게 된다** — 방향이 거꾸로다(엔진은 커널의 호스트이고
+     * 그 위에 어떤 화면이 있는지 몰라야 한다).
+     *
+     * 그래서 시임을 둔다. 앱이 이 함수를 심고, 그 안에서 `Setting` 이든 다른 무엇이든 읽는다. 심지 않으면
+     * `JOURNAL_RETENTION_DAYS`(설정 파일에서 온 프로세스 기본값)가 답한다.
+     *
+     * `undefined` 를 돌려주면 **그 도메인은 지우지 않는다** — 「모른다」를 「지워도 된다」로 읽지 않는다.
+     */
+    static retentionDaysOf?: (domainId: string) => Promise<number | undefined>;
+    static RETENTION_SWEEP_MS: number;
+    private static retentionTimer?;
     private static checkpointTimer?;
     /** 최신 스냅샷을 cache-service 에 체크포인트(도메인+instanceId 키). display-only·비차단·오류흡수. */
     static persistSnapshot(domainId: string, instanceId: string): Promise<void>;
@@ -146,6 +217,42 @@ export declare class TwinEngine {
     private static keepChainPoint;
     /** 이 트윈 저널의 끝 리비전 · 최신 구조 리비전 — 스냅샷이 지금의 사실인지 가리는 두 값. */
     private static tipOf;
+    /**
+     * **저널을 보존 기간까지만 둔다** — 체크포인트가 대신할 수 있는 만큼만 지운다.
+     *
+     * 한 인스턴스에서 지우는 조건은 **둘 다** 만족해야 한다.
+     *
+     *  · `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 pruneJournal(domainId: string): Promise<{
+        deleted: number;
+        instances: number;
+        skipped: string[];
+    }>;
+    /** 보존 정리 주기 기동(1회) — 선언이 없으면 아무것도 하지 않는다. */
+    static startRetentionLoop(domainId: string): void;
     /** 체크포인트 루프 기동(1회) — 라이브 인스턴스들의 최신 스냅샷을 주기 영속. */
     static startCheckpointLoop(): void;
     /**
@@ -164,7 +271,7 @@ export declare class TwinEngine {
      *
      * ── 모드를 지어내지 않는다 ──────────────────────────────────────────────────
      * 미러였던 트윈을 시뮬로 되살리면 **없던 움직임을 만들어 낸다**(관측 트윈이 스스로 물건을 옮긴다).
-     * 그래서 선언된 `realityMode` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
+     * 그래서 선언된 `restartPolicy` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
      *
      * ── 되살릴 수 없으면 그렇게 적는다 ──────────────────────────────────────────
      * 실패를 삼키면 등록부가 계속 `running` 이라 말한다 — 우리가 고치려던 그 거짓말이다. 그래서 실패한
@@ -249,7 +356,31 @@ export declare class TwinEngine {
      * 정상 규모에서 서로 밀어내며 캐시가 무의미해진다(그게 더 나쁘다: 조용히 느려진다).
      */
     private static readonly MEASURED_MAX;
+    /** 이 트윈이 이력에서 배운 양품률 — 소요와 **같은 폴드·같은 캐시**에서 온다(저널을 두 번 접지 않는다). */
+    private static measuredYield;
     private static measuredEstimator;
+    /**
+     * **원본이 선언한 자극을 싣는다** — 재기동해도 살아 있게 (2026-08-19).
+     *
+     * ── 무엇이 났나 ────────────────────────────────────────────────────────────
+     * 데모의 시나리오는 시드 코드가 메모리에만 실었다. 그래서 트윈을 재기동하면 자극이 사라지고 구조만
+     * 서 있는 트윈이 남았다(작업 0·오더 0) — 「살아 있는 데모」가 **첫 재기동까지만** 살았다.
+     *
+     * 자극의 집은 **원본**이다(`TwinReference.connectionConfig.scenario`, ADR-0029 ·
+     * `plans/simulator-as-source.md` §4): 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터가 정하는 사실이고
+     * 트윈은 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 걷어내야 할 표면이 하나 늘어난다.
+     *
+     * 판정은 순수 함수가 한다(`planStimulus`) — 미러에 싣지 않고, 검사를 통과하지 못한 선언은 태우지 않고
+     * (그 이력이 있다: 잘못된 선언 하나가 다음 틱에서 서버를 내렸다), 못 실은 이유는 **말한다.**
+     */
+    private static installStimulus;
+    /**
+     * 자극을 **원본에 선언한다** — 프로비저닝·데모 시드가 부르는 문.
+     *
+     * 트윈이 아니라 원본에 적는 이유는 위와 같다(ADR-0029). 원본 행이 없으면 만들지 않는다 — 어떤 원본에서
+     * 온 트윈인지 모르는 채 자극을 지어 붙이면, 그 자극이 어디서 왔는지 아무도 되짚을 수 없다.
+     */
+    static declareStimulus(domainId: string, instanceId: string, scenario: any): Promise<boolean>;
     /**
      * 이 트윈이 **이력에서 시간을 배운 작업 종류들** — 재기동에도 남는 근거.
      *
@@ -313,7 +444,7 @@ export declare class TwinEngine {
      * 커널이 그 문을 열어 두지 않았으면 그 사실도 말한다: 그 트윈은 재기동마다 열린 구간을 잃는다.
      */
     private static seedLiveContinuity;
-    static start(id: string, domainId: string, kind: string, model: TwinModelDef, realityMode?: RealityMode, purpose?: string, resumeFrom?: number): InstanceRuntime;
+    static start(id: string, domainId: string, kind: string, model: TwinModelDef, restartPolicy?: RestartPolicy, purpose?: string, resumeFrom?: number): InstanceRuntime;
     /**
      * live-모드 기동 — **관측 모드 커널**로 실 이벤트를 미러한다(통합 P2).
      *
@@ -361,33 +492,94 @@ export declare class TwinEngine {
     static withSpaceTimeBase(model: TwinModelDef, domainId: string, spaceId?: string): Promise<TwinModelDef>;
     static startLive(id: string, domainId: string, kind: string, model: TwinModelDef): InstanceRuntime;
     /**
-     * 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: string, id: string, envelopes: CanonicalEnvelope[]): void;
+    static ingestLive(domainId: string, id: string, envelopes: CanonicalEnvelope[]): number;
     /**
-     * 구간 성과 방송은 **없앴다**(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 FULL_BROADCAST_EVERY: number;
+    /** 전부 만든 횟수 — 범위를 좁히지 못한 창이 얼마나 되는지 값으로 남는다. */
+    static broadcastFullPasses: number;
+    /**
+     * 브로드캐스팅을 만든 횟수 전부 — **전부 만든 횟수의 분모.**
+     *
+     * 분자만 내면 「전부 만들기 1,200회」가 많은 것인지 적은 것인지 읽을 수 없다. 좁히기가 듣고 있으면
+     * 이 값의 `1/FULL_BROADCAST_EVERY` 쯤이 전부 만든 횟수이고, 두 값이 비슷하면 범위를 거의 못 좁힌
+     * 것이다(원인은 대개 「모른다」로 떨어지는 사건이다).
+     */
+    static broadcastPasses: number;
+    /**
+     * 이 창에 건드린 물품을 모은다 — **말할 수 없으면 범위를 버린다(전부 만든다).**
+     *
+     * `events` 를 주지 않으면 「무엇이 바뀌었는지 모른다」다(구조 전환처럼 상태 전반이 달라지는 자리).
+     * 한 창에서 한 번 「모른다」가 되면 그 창은 끝까지 모르는 채로 둔다 — 뒤에 온 사건으로 범위를
+     * 되살리면 앞 사건이 건드린 것을 빠뜨린다.
+     */
+    static markItemsDirty(inst: InstanceRuntime, events?: any[]): void;
+    /** 브로드캐스팅 병합 주기(ms) — 브로드캐스팅률 상한. 인제스트가 아무리 빨라도 이 주기로만 브로드캐스팅. */
     static BROADCAST_COALESCE_MS: number;
+    /**
+     * ── 브로드캐스팅 주기는 **재 본 비용에 맞춘다** (2026-08-21 실측) ────────────────────
+     * 한 번의 브로드캐스팅은 상태 크기에 비례한다(실측: 물품 2,400 개인 트윈 하나가 4.5ms — 상태 투영 1.7ms,
+     * payload 만들기 1.8ms, 시그니처 1.0ms). 트윈이 스무 개면 200ms 마다 90ms 가 브로드캐스팅에 들어가고,
+     * 그 시간에는 HTTP 도 구독도 서지 못한다.
+     *
+     * 그래서 한 창에서 브로드캐스팅에 쓴 시간이 주기의 일정 몫을 넘으면 **주기를 늘린다**. 화면은 조금 늦게
+     * 갱신되고(최신-상태 채널이라 값은 마지막 것 하나뿐이므로 내용은 같다), 늘렸다는 것은 계기판이
+     * 말한다(`broadcastCoalesceMs`). 여유가 생기면 원래 주기로 되돌린다.
+     *
+     * 이것은 브로드캐스팅 비용을 **줄이는 것이 아니다** — 비용을 줄이는 것은 변경분만 만드는 일이고 그것은 별
+     * 작업이다. 여기서는 그때까지 호스트가 굶지 않게 상한을 둔다.
+     */
+    static BROADCAST_MAX_COALESCE_MS: number;
+    /** 주기의 몇 몫까지 브로드캐스팅에 써도 되는가 — 넘으면 주기를 늘린다(절반이면 나머지 절반은 남긴다). */
+    static BROADCAST_LOAD_RATIO: number;
+    /** 지금 쓰고 있는 주기(ms) — 계기판이 이 값을 읽는다. 늘어난 채로 있으면 그것이 사실이다. */
+    static broadcastPeriodMs: number;
+    /** 주기를 늘린 횟수 — 조용히 늦추지 않는다. */
+    static broadcastBackoffs: number;
     private static broadcastTimer?;
-    /** live 방송 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 방송(entitySigs 로 변경 엔티티만). */
+    /** live 브로드캐스팅 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 브로드캐스팅(entitySigs 로 변경 엔티티만). */
     private static ensureBroadcastCoalescer;
     /**
-     * dirty 인스턴스 방송 flush(주기 tick 또는 명시 호출) — **시뮬과 라이브 둘 다.**
+     * 브로드캐스팅에 쓴 시간을 보고 주기를 정한다 — **늘리는 것도 줄이는 것도 값에 근거한다.**
      *
-     * 예전에는 라이브만 봤다(`mode !== 'live'` 면 건너뜀). 시뮬은 delta 마다 곧바로 방송했고, 그것이
-     * 한 tick 에서 수백 번 반복되며 이벤트 루프를 막았다(위 `start()` 주석의 35초 틱). 방송을 모으는
+     * 한 번의 flush 가 주기의 `BROADCAST_LOAD_RATIO` 를 넘게 쓰면 주기를 두 배로(상한까지), 그 몫의
+     * 절반 아래로 내려오면 절반으로(원래 주기까지) 되돌린다. 문턱을 두 개 두는 이유는 하나면 경계에서
+     * 늘리고 줄이기를 반복하기 때문이다.
+     */
+    private static adjustBroadcastPeriod;
+    /**
+     * dirty 인스턴스 브로드캐스팅 flush(주기 tick 또는 명시 호출) — **시뮬과 라이브 둘 다.**
+     *
+     * 예전에는 라이브만 봤다(`mode !== 'live'` 면 건너뜀). 시뮬은 delta 마다 곧바로 브로드캐스팅했고, 그것이
+     * 한 tick 에서 수백 번 반복되며 이벤트 루프를 막았다(위 `start()` 주석의 35초 틱). 브로드캐스팅을 모으는
      * 규율은 모드의 성질이 아니라 **채널의 성질**이다 — 최신-상태 채널이면 중간 상태는 보낼 값이 없다.
      */
     static flushLiveBroadcasts(): void;
@@ -405,12 +597,49 @@ export declare class TwinEngine {
      * 없으면 `undefined` 다 — 0 이 아니다. 구조 리비전이 생기기 전에 만들어진 트윈은 아직 리비전이
      * 없고, 그 사실을 0 이라는 **유효해 보이는 번호**로 위장하면 안 된다.
      */
+    /** 구조 리비전 캐시 — `null` 은 **없다는 것을 알고 있다**는 뜻이다(모름과 구별한다, §7.1). */
     private static structureRevCache;
     static structureRevOf(domainId: string, instanceId: string): Promise<number | undefined>;
+    /** 계기 한 벌 — **두 구동이 같은 것을 든다**(한쪽만 들면 그 구동은 물어도 답이 없다). */
+    private static newMetrics;
+    /**
+     * 모아 둔 저널을 **한 번에** 쓴다 — 두 구동이 같은 문을 쓴다 (§7.1).
+     *
+     * ── 왜 한 함수인가 ─────────────────────────────────────────────────────────
+     * 쓰는 자리가 둘이면(주기 flush · 정지) 한쪽만 고쳐지고, 그 어긋남은 **사실이 조용히 사라지는**
+     * 모양으로 나타난다. 그래서 흘리는 규칙을 여기 한 곳에 둔다.
+     *
+     * ── 리비전을 누가 매기나 ───────────────────────────────────────────────────
+     *  · 라이브 — 원천은 리비전을 주지 않으므로 **호스트가** 이어 붙인다(저널 high-water 에서 시드).
+     *  · 시뮬 — **커널의 리비전**이 실려 온다(저널이 그것으로 접히고 시간여행이 그것을 딛는다).
+     * 그래서 버퍼는 두 모양을 함께 든다: 봉투만 있으면 라이브, `{ event, revision }` 이면 시뮬이다.
+     */
+    private static flushJournal;
+    /**
+     * 커널이 매긴 리비전을 그대로 들고 벌크 저장 — 시뮬 경로.
+     *
+     * 예전에는 이 경로가 **델타마다 한 행씩** 저장했다(그리고 행마다 구조 리비전을 물었다). 규모에서 그것이
+     * 호스트를 먹었다(§7.1 실측). 여기서 구조 리비전은 **한 번만** 묻는다.
+     */
+    static persistCarried(domainId: string, instanceId: string, items: {
+        event: any;
+        revision: number;
+    }[]): Promise<void>;
+    /**
+     * 저널 행을 넣는다 — **넣기만 한다**(2026-08-20).
+     *
+     * 예전에는 `save()` 였다. 그런데 `save` 는 넣은 뒤 생성 컬럼을 읽으려고 **행마다 SELECT 를 한 번 더**
+     * 한다(시험 로그에서 그 질의가 그대로 보였다: `SELECT … FROM twin_events WHERE id = ?`). 저널은
+     * append-only 이고 부르는 쪽은 돌려받은 엔티티를 쓰지 않으므로 그 왕복이 순수 낭비다.
+     *
+     * 묶음은 **나눠서** 넣는다: 한 문에 열이 열다섯인 행을 수천 개 실으면 드라이버의 파라미터 한계에
+     * 걸린다(pg 는 65,535개). 500행이면 어느 드라이버에서도 안전하다.
+     */
+    private static insertRows;
     /** live 저널 배치 기록 — 모아둔 CanonicalEnvelope 들에 startRevision+1.. 을 부여해 벌크 저장(coalescer tick 당 1회). */
     static persistBatch(domainId: string, instanceId: string, envelopes: any[], startRevision: number): Promise<void>;
     /** 레지스트리 upsert(도메인+instanceId 유니크). status 인자로 provision(stopped)/start(running) 공용. */
-    static register(domainId: string, instanceId: string, kind: string, model: TwinModelDef, status?: 'running' | 'stopped', realityMode?: RealityMode, origin?: any, meta?: {
+    static register(domainId: string, instanceId: string, kind: string, model: TwinModelDef, status?: 'running' | 'stopped', restartPolicy?: RestartPolicy, origin?: any, meta?: {
         name?: string;
         description?: string;
         actor?: {
@@ -455,7 +684,15 @@ export declare class TwinEngine {
     static adoptStructure(domainId: string, instanceId: string, model: TwinModelDef, comment?: string, origin?: any): Promise<{
         rev: number;
     } & StructureShift>;
-    static provision(domainId: string, instanceId: string, kind: string, model: TwinModelDef, comment?: string, origin?: any, 
+    static provision(domainId: string, instanceId: string, kind: string, model: TwinModelDef, 
+    /**
+     * **재기동 정책은 생성 시점의 선언이다**(ADR-0029 §2) — 트윈은 정책 없이 존재할 수 없다.
+     *
+     * 예전에는 이 자리가 없었고 `register` 가 기본값(`sim-experiment` = 저널 초기화)을 각인했다. 그래서
+     * 선언을 빠뜨린 프로비저닝이 **재기동마다 이력을 지우는 트윈**을 조용히 만들었다. 이제 만드는 쪽이
+     * 말해야 한다: 이 트윈이 자기 과거를 어떻게 대하는지는 만드는 사람이 아는 사실이다.
+     */
+    restartPolicy: RestartPolicy, comment?: string, origin?: any, 
     /** 이름·저자 — 업무키를 나눠 둔 대가로 이름을 함께 남긴다(`register` 의 `meta` 그대로). */
     meta?: {
         name?: string;
@@ -497,18 +734,18 @@ export declare class TwinEngine {
     private static structureFingerprint;
     private static structureSignature;
     /** 레지스트리 model 로 기동(프로비전된 인스턴스 start). model 인자 없이 저장된 구조로 재기동. */
-    static startFromRegistry(domainId: string, instanceId: string, realityMode?: RealityMode): Promise<InstanceRuntime>;
+    static startFromRegistry(domainId: string, instanceId: string, restartPolicy?: RestartPolicy): Promise<InstanceRuntime>;
     /**
-     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 구분한다.
+     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 restartPolicy 에 따라 재기동 방식을 구분한다.
      * 부팅 경로를 한 곳에 모아 "런타임 ≠ 현실" 범주오류를 코드로 강제한다.
-     *   - 'mirror'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
-     *   - 'sim-world'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
+     *   - 'resync'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
+     *   - 'resume'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
      *                        ⚠ GATE(§8 ②③): 커널 상태 직렬화/재개가 아직 없어 진짜 resume 불가 → 실 필요·실부하 시 구현.
      *                        그때까지는 저널을 보존하되 revision 충돌을 피하려 fresh 로 기동하고, 선언과 구현의 간극을 크게 경고한다.
-     *   - 'sim-experiment' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
+     *   - 'reset' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
      * 반환: 기동된 InstanceRuntime.
      */
-    static bootDeclared(domainId: string, instanceId: string, mode?: RealityMode): Promise<InstanceRuntime>;
+    static bootDeclared(domainId: string, instanceId: string, mode: RestartPolicy): Promise<InstanceRuntime>;
     /**
      * 저널 초기화 — 인스턴스 이벤트 저널 purge(레지스트리·상태는 유지).
      * 데모 fresh-start 용: 매 부팅 seed 부터 새로 실행하는 데모에서, 복구본 폐기 후 revision 0 부터 재실행하면
@@ -571,7 +808,9 @@ export declare class TwinEngine {
      * 기존 공간으로 들어갈 수 있다. 아래 병합은 원래 그 경우를 위해 있었는데(N:1) 만드는 흐름에서
      * 공간을 고를 방법이 없었다 — 마스터가 파생한 id 만 쓰였다. 판정은 `resolveIngestSpace`(순수).
      */
-    static ingestMaster(domainId: string, master: ReferenceMaster, into?: {
+    static ingestMaster(domainId: string, master: ReferenceMaster, 
+    /** 만들어지는 트윈의 재기동 정책 — 원본이 정하는 것이 아니라 **만드는 쪽의 선언**이다(ADR-0029 §2). */
+    restartPolicy: RestartPolicy, into?: {
         spaceId?: string;
     }, 
     /** 누가 인제스트했나 — 사람이 없는 경로(부팅)는 주지 않는다(감사 기록을 지어내지 않는다). */
@@ -589,14 +828,14 @@ export declare class TwinEngine {
      * 보드 컴포넌트가 tag 로 구독(board-ui provider)해 `component.data` 로 라이브 갱신. delta 시에만(희소).
      * tag=엔티티 id(데모=단일 인스턴스). 멀티 인스턴스/보드 재사용 시 tag 네임스페이스는 후속.
      */
-    /** 방송 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
+    /** 브로드캐스팅 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
     private static publishDrops;
     private static readonly PUBLISH_DROP_LOG_MS;
     /**
-     * 한 번의 방송 — **구독자 하나가 호스트를 죽이지 못하게.**
+     * 한 번의 브로드캐스팅 — **구독자 하나가 호스트를 죽이지 못하게.**
      *
      * ── 무엇이 죽였나 (2026-08-14) ─────────────────────────────────────────────
-     * 밀린 push 가 1024를 넘으면 pubsub 이 던진다(`RepeaterOverflowError`). 그 방송은 타이머 콜백
+     * 밀린 push 가 1024를 넘으면 pubsub 이 오류를 낸다(`RepeaterOverflowError`). 그 브로드캐스팅은 타이머 콜백
      * 안에서 일어나므로 예외가 잡히는 곳 없이 올라가 **프로세스가 끝났다** — 트윈 14개가 도는 호스트가
      * 소비를 멈춘 구독자 하나 때문에 통째로.
      *
@@ -605,7 +844,6 @@ export declare class TwinEngine {
      */
     private static publishGuarded;
     static publishEntityData(inst: InstanceRuntime): void;
-    static persist(domainId: string, instanceId: string, msg: any): Promise<void>;
     /**
      * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
      * model 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서.
@@ -618,6 +856,29 @@ export declare 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 timeRange(domainId: string, spaceId: string): Promise<{
         minTime: string | null;
@@ -738,7 +999,116 @@ export declare class TwinEngine {
     static countForks(domainId: string, id: string, count: number): void;
     /** 엔진 밖(예측 질의 등)에서 무거운 작업을 잰다 — 같은 계기판에 모인다. */
     static recordLoad(domainId: string, id: string, phase: LoadPhase, tookMs: number): void;
-    /** 전체 라이브 인스턴스 계측(모니터 대시보드용). */
+    private static ingestLedgers;
+    /** 창이 닫힐 때 부를 곳 — 영속 계층이 부팅에서 한 번 등록한다(커널 층은 그 계층을 모른다). */
+    private static onWindowClosed?;
+    /**
+     * 닫힌 창을 받을 곳을 등록한다 — **영속(B)이 붙는 유일한 문.**
+     *
+     * 이 패키지는 저장 계층을 모른다. 등록하는 쪽이 자기 방식으로 쓴다. 훅이 오류를 내도 장부는 계속 굴러간다
+     * (`rollIngestWindow` 가 감싼다) — 영속을 지키려고 관측을 멈추지 않는다.
+     */
+    static onIngestWindowClosed(fn: (at: {
+        domainId: string;
+        instanceId: string;
+    }, closed: IngestWindow) => void): void;
+    /**
+     * 한 번의 인제스트 결과를 장부에 적는다.
+     *
+     * `offered` 는 **제시된 레코드 수**다(거부 여부 무관). 통과율을 서로 다른 두 계수기에서 나눠 계산하면
+     * 분모와 분자가 다른 것을 세게 되므로, 한자리에서 본 수를 그대로 넘긴다.
+     */
+    static recordIngestResult(domainId: string, instanceId: string, offered: number, rejected: {
+        record?: unknown;
+        errors?: string[];
+    }[] | undefined, nowMs?: number, 
+    /**
+     * 매핑은 통과했는데 **커널이 받지 않은** 수(`ingestLive` 의 반환과 견주어 얻는다).
+     *
+     * 「통과」로 세지 않는다 — 트윈이 멈춘 사이 사실이 사라지는데 화면이 100% 라고 말하게 된다.
+     */
+    undelivered?: number): void;
+    /**
+     * **원본에 닿지 못했다**를 적는다 — 「받은 것이 없다」와 가른다(§`recordReadFailure`).
+     *
+     * 이 문이 없던 동안 실 원본이 끊겨도 트윈의 조회 가능한 상태에 그 사실이 없었다. 화면이 볼 수 있는
+     * 것은 「새 사실이 없다」뿐이었고 그것은 「원본이 조용하다」와 구별되지 않는다 — 실증 중에 원본이
+     * 끊기면 사용자가 원인을 찾을 수 없다.
+     *
+     * 로그로는 말하고 있었다(어댑터가 재시도를 경고한다). 그러나 **로그는 사람이 볼 때만 값이 있다** —
+     * 화면이 말하려면 상태에 있어야 한다.
+     */
+    static recordIngestReadFailure(domainId: string, instanceId: string, reason: string, nowMs?: number, stream?: string): void;
+    /**
+     * 읽기가 성공했다 — 단절 기록을 지운다.
+     *
+     * **빈 읽기도 성공이다.** 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이므로, 그때도 부른다.
+     * 그 둘을 같게 두면 조용한 원본이 끊긴 원본으로 보인다.
+     */
+    static clearIngestReadFailure(domainId: string, instanceId: string): void;
+    /**
+     * 저널에 **적은 것**을 같은 장부에 남긴다 — 유입과 같은 10분 창에.
+     *
+     * ── 왜 유입 장부에 넣나 ────────────────────────────────────────────────────
+     * 새 장부를 만들면 「닫힌 창만 최근」·「0 과 없음을 가른다」·영속을 두 벌 지켜야 하고, 그중 한 벌만
+     * 고쳐지는 것이 보통이다. 유입 창은 그 규율이 이미 들어 있고 닫힐 때 행으로 남는다.
+     *
+     * ── 이 값이 없으면 무엇을 못 보나 ──────────────────────────────────────────
+     * 계기(`journalRate`)는 **지금**만 답한다. 프로세스를 다시 띄우면 0 에서 시작하므로 「어제 이 시각에도
+     * 이랬나」·「고친 뒤로 줄었나」를 물을 자리가 없다. 2026-08-20 에 고친 것이 바로 쓰기 경로이므로,
+     * 되돌아가는 것을 볼 수 있어야 한다.
+     */
+    static recordJournalWrite(domainId: string, instanceId: string, rows: number, nowMs?: number): void;
+    /**
+     * 「이 트윈이 현장과 맞춰지고 있나」 — 한눈 판정 + 추이 + 사유 + 표본.
+     *
+     * 조회할 때 창을 한 번 굴린다: 유입이 멈추면 다음 인제스트가 없어 창이 영원히 닫히지 않는데, 그러면
+     * 「최근」이 옛것으로 남는다. 타이머를 두지 않는 이유는 트윈마다 타이머를 걸면 그 타이머들이 다시
+     * 메인 루프에 얹히기 때문이다(오늘 확인한 그 부하를 이 기능이 다시 만들 이유가 없다).
+     */
+    /**
+     * 도메인의 트윈마다 **한 줄 요약** — 목록 화면과 미니 추이용.
+     *
+     * ── 왜 상세와 따로인가 ─────────────────────────────────────────────────────
+     * `ingestHealthOf` 는 사유 문구와 **레코드 원문 표본**까지 낸다. 목록에 트윈이 스무 개면 그 원문이
+     * 스무 벌 실려 조회가 무거워지고, 화면은 어차피 그것을 그리지 않는다. 그래서 여기서는 **숫자만** 낸다.
+     *
+     * 추이는 창당 숫자 넷이라 스파크라인 하나에 충분하고 가볍다.
+     *
+     * ── 등록된 트윈을 기준으로 훑는다 ──────────────────────────────────────────
+     * 도는 트윈만 훑으면 「고치려고 멈춰 둔 트윈」이 목록에서 사라진다 — 사람이 방금 멈춘 그것을 보려고
+     * 목록을 여는데 없으면 결함으로 읽는다. 그래서 호출부(목록 화면)가 아는 instanceId 들을 받는다.
+     */
+    static ingestHealthBrief(domainId: string, instanceIds: string[]): {
+        instanceId: string;
+        verdict: string;
+        acceptedRatio: number | null;
+        trend: {
+            offered: number;
+            rejected: number;
+            undelivered: number;
+            rows: number;
+        }[];
+        lastAt: string | null;
+    }[];
+    /**
+     * 한 트윈의 동기화 건강.
+     *
+     * ── 조회가 장부를 전진시킨다(의도) ─────────────────────────────────────────
+     * 창은 **다음 유입이 있을 때** 닫힌다. 그래서 피드가 죽으면 마지막 창이 열린 채로 남아 영원히 영속되지
+     * 않고, 추이에도 들어가지 않는다. 조회 시점에 한 번 굴려 주면 그 마지막 창이 닫히면서 영속 훅도 불린다
+     * — 즉 **죽은 피드의 마지막 구간을 잃지 않기 위해** 읽기가 굴린다. 부수효과지만 필요한 부수효과다.
+     *
+     * 시각은 **한 번만 읽어** 굴리기와 판정에 같은 값을 쓴다. 두 번 읽으면 그 사이에 창이 닫혀 판정이
+     * 굴리기 전 상태를 보는 일이 생긴다.
+     */
+    static ingestHealthOf(domainId: string, instanceId: string): IngestHealthView;
+    /**
+     * 도는 인스턴스 전체의 계측(모니터 대시보드용) — **시뮬과 미러를 함께**.
+     *
+     * 예전에는 시뮬에 계기가 없어 이 목록에서 조용히 빠졌다(계기가 `null` 이라 걸러졌다). 도는 트윈
+     * 대부분이 시뮬인 서버에서 그 목록은 「부하가 거의 없다」로 보였다.
+     */
     static allMetrics(domainId?: string): Promise<any[]>;
     /**
      * 예측용 커널을 **임의 시각 T 기준**으로 재구성 — 과거-vantage 예측(백테스트)·"그때 서서 본 미래".
@@ -749,4 +1119,3 @@ export declare class TwinEngine {
     /** 현재 전체 스냅샷 — 라이브 우선, 없으면 저널 복구 캐시. */
     static snapshot(domainId: string, id: string): any;
 }
-export {};