@things-factory/headless-twin 10.0.11 → 10.0.13

package/server/engine/twin-engine.ts

@@ -7,6 +7,7 @@
  * (설계 SoT: operato-twin/design/integration/things-factory-host.md)
  */
 
+import { twinLog, twinWarn, twinError } from './log.js'
 import { pubsub, getRepository, Domain } from '@things-factory/shell'
 /* 저널을 자를 조건은 SQL 이 안다 — 관용구만 쓴다(원시 SQL 은 5개 드라이버에서 갈라진다). */
 import { And, IsNull, LessThanOrEqual, MoreThan } from 'typeorm'
@@ -21,6 +22,8 @@ import { applyDeclarationLayers } from './local-declarations.js'
 import { isOfDomain, parseRuntimeKey, runtimeKey } from './runtime-key.js'
 import { routeCommand } from './command-routing.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
+/* 자극의 집은 원본이다(ADR-0029) — 그 행을 읽고 쓴다. */
+import { TwinReference } from '../service/reference/twin-reference.js'
 import { TwinStructure } from '../service/twin-structure/twin-structure.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
 import { utcOffsetOf } from '../service/reference/reference-master.js'
@@ -33,28 +36,83 @@ import { type IngestWarning, describeWarnings, unresolvedReference, projectionFa
 import { projectStructure } from '../service/twin-model/project-structure.js'
 import { buildTravelEstimator, chainEstimators } from './travel-estimator.js'
 import { buildMeasuredEstimator } from './measured-estimator.js'
+import { buildYieldEstimator } from './measured-yield.js'
+import { planStimulus, withStimulus } from './declared-stimulus.js'
+import { readRestartPolicy, type RestartPolicy } from './restart-policy.js'
 import { describeModelBasis, type ModelBasis } from './model-basis.js'
 import { computeTwinKpi } from './kpi-query.js'
 import { createHash } from 'node:crypto'
 
 import { buildEntityDeltas } from '@things-factory/headless-twin/dist-shared/entity-delta.js'
 import { fleetLoad, judgeCycle, loadSummary, newLoadMeter, recordFork, recordPhase, slowTickMessage, type LoadMeter, type LoadPhase } from './load-meter.js'
+import { loopLag } from './loop-lag.js'
+import { touchedItemKeys } from '@things-factory/headless-twin/dist-shared/touched-items.js'
 import { diffStructures, type StructureDiff } from './structure-diff.js'
 import { OeeAccumulator, withLiveOee } from './oee-accumulator.js'
 import { withLiveAttentions } from './live-attentions.js'
 import { digestAttentions, mergeLensAttentions } from './attention-digest.js'
 
 import { liveFeedStateOf } from './live-feed-registry.js'
+import {
+  ingestHealth,
+  newIngestLedger,
+  recordIngest,
+  recordReadFailure,
+  clearReadFailure,
+  rollIngestWindow,
+  /* 별칭 — 같은 이름의 정적 메서드와 헷갈리지 않게(그 메서드가 이것을 부른다). */
+  recordJournalWrite as recordLedgerWrite,
+  type IngestHealthView,
+  type IngestLedger,
+  type IngestWindow
+} from './ingest-health.js'
 import { EMS_PROPERTY } from '@operato/twin-kernel'
 import type { TwinKernel, TwinModelDef, StructureShift, SubscriptionMessage, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@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 } = require('@operato/twin-kernel')
+const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel')
 
 const KERNELS: Record<string, any> = { 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: unknown): number | null {
+  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`)
  * 이라 오타 하나·대소문자 하나로 야드/생산 트윈이 **조용히 창고 커널로 돌았다.** 오류가 없으니 화면에는
@@ -69,15 +127,57 @@ function kernelFor(kind: string): any {
   return K
 }
 
-/* 라이브 처리량 계측(모니터) — 유입/방송/저널률·백로그. 실 동기 인터페이스 부하를 읽는 일급 지표. */
+/** `observe()` 를 갖지 않은 커널을 만난 적이 있는가 — 경고를 한 번만 낸다(틱마다 쏟지 않는다). */
+let observeUnavailableWarned = false
+
+/**
+ * **이 커널의 진실이 원본에서 온다고 선언한다** — 그리고 선언이 닿지 않았으면 말한다.
+ *
+ * ── 무엇이 틀렸나 (2026-08-21) ──────────────────────────────────────────────
+ * 예전에는 `kernel.observe?.()` 였다. 옵셔널 호출이라 **메서드가 없으면 조용히 아무것도 하지 않는다.**
+ * 설치된 커널 0.7.39 에는 그 메서드가 없으므로, 지금 배포본에서는 미러가 관측 구동으로 선언되지
+ * 않는다 — 그런데 코드를 읽으면 선언한 것처럼 보인다.
+ *
+ * 그 차이가 실제 거동을 가른다: 관측 구동은 원본의 빈틈을 받아들이고 세지만, 시뮬로 오인된 미러는
+ * **멈춘다.** 즉 「관용이 켜진 줄 알았는데 안 켜져 있다」가 조용히 지나가고, 장애가 났을 때 원인이
+ * 커널에 있는 것처럼 보인다 — 원인은 버전이다.
+ *
+ * 그래서 옵셔널 호출을 없애고, 없으면 **한 번 경고한다.** 커널이 배포되면 이 경고는 사라진다.
+ */
+function declareObserved(kernel: any, what: string): void {
+  if (typeof kernel?.observe === 'function') {
+    kernel.observe()
+    return
+  }
+  if (observeUnavailableWarned) return
+  observeUnavailableWarned = true
+  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().'
+  )
+}
+
+/* 라이브 처리량 계측(모니터) — 유입/브로드캐스팅/저널률·백로그. 실 동기 인터페이스 부하를 읽는 일급 지표. */
 interface TwinMetrics {
   ingestedTotal: number // 누적 유입 이벤트
-  broadcastTotal: number // 누적 방송 횟수
+  broadcastTotal: number // 누적 브로드캐스팅 횟수
   journaledTotal: number // 누적 저널 기록 이벤트
   ingestRate: number // 최근 유입률(ev/s)
-  broadcastRate: number // 최근 방송률(회/s)
+  broadcastRate: number // 최근 브로드캐스팅률(회/s)
   journalRate: number // 최근 저널률(ev/s)
-  backlog: number // 마지막 flush 시 대기 저널 크기(백프레셔 신호)
+  /**
+   * **지금 대기 중인** 저널 건수 — 아직 DB 로 나가지 않은 것.
+   *
+   * ── 무엇이 틀렸었나 (2026-08-21) ──────────────────────────────────────────
+   * 예전에는 「마지막 flush 에서 쓴 건수」를 여기 넣었다. 그런데 200ms 마다 모아 한 문으로 넣는 것은
+   * **정상 동작**이다(그렇게 만든 것이 어제 고친 성능 작업이다). 그래서 정상적으로 10건을 쓴 직후
+   * 화면에 「밀림 10」 경고가 떴고, 다음 flush 까지 그 값이 남았다 — 큐는 이미 0 인데도.
+   *
+   * 운영자에게 그것은 「저장이 10건 밀려 있다」로 읽힌다. 거짓 경보는 참 경보를 죽인다.
+   *
+   * 이제 이 값은 **지금 남아 있는 것**이다: 다 나갔으면 0 이고, 정말로 쌓이는 중이면 그 수가 자란다.
+   */
+  backlog: number
   // 창(window) 집계용 내부 누적
   _accIngest: number
   _accBroadcast: number
@@ -86,19 +186,19 @@ interface TwinMetrics {
 }
 
 /*
- * realityMode — 이 트윈의 "현실이 어디서 오나"(runtime-state-model §0·§1 프레임의 ① 선언).
- * 부팅 거동을 결정하는 1급 선언: mirror=외부 실물 재동기 / sim-world=생성 타임라인 지속(resume) / sim-experiment=seed 재현(reset).
- * 미선언 = 'sim-experiment'(가장 보수적 — 기존 데모 거동 보존).
+ * 재기동 정책은 **선언이고 기본값이 없다** — 정의·판정은 `engine/restart-policy.ts` 가 든다(ADR-0029 §2).
+ *
+ * 예전에는 여기에 `DEFAULT_REALITY_MODE = 'sim-experiment'` 가 있었고, 미선언이 조용히 **저널 초기화**로
+ * 떨어졌다. 그 관용은 값이 하나 어긋나는 순간 이력을 지우는 길이 된다 — 그래서 없앴다.
  */
-export type RealityMode = 'mirror' | 'sim-world' | 'sim-experiment'
-export const DEFAULT_REALITY_MODE: RealityMode = 'sim-experiment'
+export type { RestartPolicy } from './restart-policy.js'
 
 /* 인메모리 라이브 런타임 홀더(영속 엔티티 TwinInstance 와 구분). */
 interface InstanceRuntime {
   /** 부하 계기판 — 작업별 소요. 시뮬·라이브 모두 붙는다(누가 루프를 점유하는지 보려면 둘 다 필요하다). */
   load?: LoadMeter
   /** 현실 출처 선언(§0 프레임 ①). 부팅 거동(reset/resume/resync)의 근거. */
-  realityMode?: RealityMode
+  restartPolicy?: RestartPolicy
   id: string
   domainId: string
   domain?: any // 라이브 바인딩(data 채널)용 Domain 객체(subdomain 필터). start 시 비동기 해석.
@@ -122,8 +222,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 대응 — 시간여행·히스토리 노브 앵커). */
@@ -164,13 +275,44 @@ export class TwinEngine {
    * 멈춘다 — HTTP·구독·다른 트윈의 틱까지. 실측으로 `order-check` 의 틱 하나가 34.9초였고, 그 사이
    * 구독자가 아무것도 빼내지 못해 pubsub 이 넘쳐 프로세스가 죽었다.
    *
-   * 방송 반복은 걷어냈지만(`flushLiveBroadcasts` 로 병합) **커널 틱 자체는 여전히 메인 루프에 있다.**
+   * 브로드캐스팅 반복은 걷어냈지만(`flushLiveBroadcasts` 로 병합) **커널 틱 자체는 여전히 메인 루프에 있다.**
    * 근본 해결은 분산이고 그것은 이연됐다 — 그때까지의 안전망이 이 셋이다.
    *
    * 판정을 예산(500ms)이 아니라 **굶김 문턱**으로 따로 둔다: 조금 느린 트윈은 계기판이 말하게 두고
    * (경고), 호스트를 굶기는 트윈만 멈춘다. 한 번으로 멈추지 않는다 — 웜스타트 직후의 첫 틱은 원래
    * 무겁다(복구한 상태를 처음 접는다). **연속**으로 이어질 때가 구조적으로 느린 것이다.
    */
+  /*
+   * ── 틱을 **한 순간에 몰지 않는다** (2026-08-21 실측) ────────────────────────
+   * 트윈마다 `setInterval(TICK_MS)` 를 부팅 때 나란히 세우면, 스무 개가 **같은 밀리초에** 깨어난다.
+   * 각자의 틱이 짧아도(실측: 물품 2,400 개에서 0.23ms) 그 순간에는 스무 개가 한 줄로 붙어 실행되고,
+   * 그 사이 도착한 HTTP 요청은 전부 뒤에서 기다린다. 초당 한 번의 정체가 「누를 때마다 걸린다」로
+   * 나타나는 자리다.
+   *
+   * 그래서 첫 발화만 간격 안에서 **고르게 흩는다** — 총 작업량은 같고 한 순간의 최대치만 낮아진다.
+   * 트윈이 간격보다 많아지면 다시 겹치므로, 그때는 이 흩기가 아니라 분산이 답이다(이연됨).
+   */
+  /** 부팅 때 트윈 하나를 되살린 뒤 루프를 비워 주는 시간(ms) — 그 사이 도착한 요청이 처리된다. */
+  static BOOT_YIELD_MS = 25
+  private static tickPhase = 0
+  /**
+   * 흩어진 첫 발화 뒤 주기 틱. **핸들은 항상 진짜 타이머**다 — 정지하는 쪽이 `clearInterval(inst.timer)`
+   * 하나로 끝내야 하므로, 첫 발화 전에는 그 `setTimeout` 을, 이후에는 `setInterval` 을 같은 자리에 둔다
+   * (감싼 객체를 주면 `clearInterval` 이 아무 일도 하지 않고 트윈이 멈추지 않는다 — 조용한 결함이 된다).
+   */
+  private static startTickTimer(fn: () => void, hold: (t: any) => void): any {
+    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 STARVE_FACTOR = 5
   /** 연속 몇 번이면 멈추나 — 3번이면 15초를 굶긴 셈이고, 그건 우연이 아니다. */
@@ -203,6 +345,44 @@ export class TwinEngine {
   static CHAIN_KEEP = 5 // 최근 몇 지점을 들고 있나(그보다 과거는 0부터 접는다)
   static SNAPSHOT_TTL_S = 7 * 24 * 3600 // 7일 — 정상 다운타임 생존, 만료 시 저널 replay 폴백
   static CHECKPOINT_MS = 20000 // 체크포인트 주기(핫 브로드캐스트 경로와 분리, O(state) 스로틀)
+  /**
+   * **저널 보존 — 지우는 것은 선언이 있을 때만 한다.**
+   *
+   * ── 왜 필요한가 (2026-08-22 실측) ─────────────────────────────────────────
+   * 개발 저널이 시간당 **581,794행 · 0.85GB** 로 자랐다(하루 20GB). 데모 MES 트윈 셋이 전체의 **97%**
+   * 를 만들고 지우는 것이 없었다. 오늘 고친 것들은 「그 크기에서도 질의가 빠르게」이고, **크기 자체를
+   * 줄이는 것은 아무것도 없었다.** 그러면 며칠마다 같은 자리로 돌아온다.
+   *
+   * ── 그런데 저널을 지우는 것은 사실을 잃는 일이다 ──────────────────────────
+   * 그래서 세 규율을 지킨다.
+   *
+   *  ① **선언이 없으면 아무것도 지우지 않는다.** 기본값은 없음이다 — 조용히 지우는 편이 조용히 쌓는
+   *     것보다 나쁘다. 지우는 것은 사람이 정한다.
+   *  ② **체크포인트가 대신할 수 있는 만큼만.** 스냅샷이 없거나 그 리비전을 넘는 자리는 건드리지 않는다.
+   *     주석이 「만료 시 저널 replay 폴백」이라고 적어 둔 그대로 — 스냅샷이 사라지면 저널이 **유일한**
+   *     복구 수단이므로, 둘을 함께 잃으면 그 트윈의 상태는 되돌릴 수 없다.
+   *  ③ **지운 것을 말한다.** 몇 건을 어느 시각까지 지웠는지 로그에 남긴다. 조용히 줄어든 저널은
+   *     「없었던 일」과 구별되지 않는다.
+   *
+   * 그리고 보존 기간은 **스냅샷 TTL(7일)보다 짧을 수 없다.** 더 짧으면 스냅샷이 살아 있는데 그것이
+   * 가리키는 앞쪽 저널이 없는 구간이 생기고, 시간여행·계보 추적이 그 구간에서 조용히 빈다.
+   */
+  static JOURNAL_RETENTION_DAYS?: number = undefined
+  /**
+   * **도메인마다 다른 보존 기간을 앱이 답한다** — 엔진은 그 값이 어디서 오는지 모른다.
+   *
+   * 보존 기간은 테넌트의 정책이다: 한 고객은 30일이 필요하고 다른 고객은 7일이면 된다. 그런데 엔진이
+   * `Setting` 을 읽게 만들면 **엔진이 화면 관심사를 알게 된다** — 방향이 거꾸로다(엔진은 커널의 호스트이고
+   * 그 위에 어떤 화면이 있는지 몰라야 한다).
+   *
+   * 그래서 시임을 둔다. 앱이 이 함수를 심고, 그 안에서 `Setting` 이든 다른 무엇이든 읽는다. 심지 않으면
+   * `JOURNAL_RETENTION_DAYS`(설정 파일에서 온 프로세스 기본값)가 답한다.
+   *
+   * `undefined` 를 돌려주면 **그 도메인은 지우지 않는다** — 「모른다」를 「지워도 된다」로 읽지 않는다.
+   */
+  static retentionDaysOf?: (domainId: string) => Promise<number | undefined>
+  static RETENTION_SWEEP_MS = 10 * 60 * 1000 // 10분마다 한 번 — 지우는 일은 급하지 않다
+  private static retentionTimer?: any
   private static checkpointTimer?: any
 
   /** 최신 스냅샷을 cache-service 에 체크포인트(도메인+instanceId 키). display-only·비차단·오류흡수. */
@@ -257,7 +437,7 @@ export class TwinEngine {
     if (!value?.state) return
     await cacheService
       .setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, value, this.SNAPSHOT_TTL_S)
-      .catch((err: any) => console.error(`[twin-engine] snapshot save fail "${instanceId}"`, err?.message ?? err))
+      .catch((err: any) => twinError(`[twin-engine] snapshot save fail "${instanceId}"`, err?.message ?? err))
   }
 
 
@@ -334,6 +514,113 @@ export 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: string): Promise<{ deleted: number; instances: number; skipped: string[] }> {
+    /* 도메인의 정책이 먼저다(§`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) {
+      twinWarn(
+        `[twin-engine] journal retention ${days}일은 스냅샷 TTL(${minDays}일)보다 짧다 — ${effectiveDays}일로 올린다 ` +
+          '(더 짧으면 스냅샷이 살아 있는데 그것이 가리키는 앞쪽 저널이 없는 구간이 생긴다)'
+      )
+    }
+    const cutoff = new Date(Date.now() - effectiveDays * 86400 * 1000)
+
+    const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId } } })
+    let deleted = 0
+    let instances = 0
+    const skipped: string[] = []
+
+    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 getRepository(TwinEvent)
+        .createQueryBuilder()
+        .delete()
+        .from(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++
+        /* **지운 것을 말한다** — 조용히 줄어든 저널은 「없었던 일」과 구별되지 않는다. */
+        twinLog(
+          `[twin-engine] journal pruned "${r.instanceId}" — ${n}건 (revision ≤ ${upTo} · ${cutoff.toISOString()} 이전). ` +
+            '그 앞은 체크포인트가 대신한다.'
+        )
+      }
+    }
+    if (skipped.length) {
+      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: string): void {
+    if (this.retentionTimer) return
+    /*
+     * 걸지 않는 조건: 프로세스 기본값도 없고 **도메인에 물을 길도 없을** 때다. 시임이 심겨 있으면
+     * 기본값이 없어도 걸어야 한다 — 그 도메인이 자기 값을 가질 수 있다.
+     */
+    if (!this.JOURNAL_RETENTION_DAYS && !this.retentionDaysOf) return
+    this.retentionTimer = setInterval(() => {
+      this.pruneJournal(domainId).catch(err => twinError('[twin-engine] journal prune failed', err?.message ?? err))
+    }, this.RETENTION_SWEEP_MS)
+    if (typeof this.retentionTimer?.unref === 'function') this.retentionTimer.unref()
+    twinLog(
+      `[twin-engine] journal retention on — ${this.JOURNAL_RETENTION_DAYS ?? '(도메인 정책)'}일 · ` +
+        `${this.RETENTION_SWEEP_MS / 60000}분마다`
+    )
+  }
+
   /** 체크포인트 루프 기동(1회) — 라이브 인스턴스들의 최신 스냅샷을 주기 영속. */
   static startCheckpointLoop(): void {
     if (this.checkpointTimer) return
@@ -341,7 +628,7 @@ export class TwinEngine {
       for (const [key, inst] of Object.entries(this.instances)) {
         const { instanceId } = parseRuntimeKey(key)
         this.persistSnapshot(inst.domainId, instanceId).catch(err =>
-          console.error(`[twin-engine] snapshot checkpoint fail "${instanceId}"`, err?.message ?? err)
+          twinError(`[twin-engine] snapshot checkpoint fail "${instanceId}"`, err?.message ?? err)
         )
       }
     }, this.CHECKPOINT_MS)
@@ -353,6 +640,8 @@ export class TwinEngine {
    * 라이브 tick 재개(sim 결정적 re-run / live 인제스트 지속)는 후속. 여기선 상태 복원 + 노출.
    */
   static async bootstrap(): Promise<void> {
+    /* 부팅부터 잰다 — 사람이 가장 답답한 구간이 여기이고, 그 구간을 재지 않으면 값으로 말할 수 없다. */
+    loopLag.start()
     try {
       const repo = getRepository(TwinInstance)
       const rows = await repo.find({ where: { status: 'running' } })
@@ -372,20 +661,38 @@ export class TwinEngine {
            * 로그만 읽으면 심긴 줄 알게 된다 — 실제로 그렇게 읽고 재기동 뒤 지속시간이 사라진 것을
            * 데이터 문제로 오진할 뻔했다.
            */
-          console.log(`[twin-engine] found cached state for "${row.instanceId}" → revision ${cached.revision} (seeded at start).`)
+          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[runtimeKey(row.domainId, row.instanceId)] = { revision: state.revision, state }
-          console.log(`[twin-engine] recovered "${row.instanceId}" from journal → revision ${state.revision}.`)
+          twinLog(`[twin-engine] recovered "${row.instanceId}" from journal → revision ${state.revision}.`)
         }
       }
-      /* 상태만 되찾는 것으로는 **도는 트윈이 되지 않는다** — 런타임까지 되살린다(아래). */
-      for (const row of rows) await this.resumeRow(row)
+      /*
+       * 상태만 되찾는 것으로는 **도는 트윈이 되지 않는다** — 런타임까지 되살린다(아래).
+       *
+       * 되살리기 사이에 **루프를 한 번 비워 준다** (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) as string[])) {
+        this.startRetentionLoop(domainId)
+      }
     } catch (err) {
-      console.error('[twin-engine] recovery scan failed', err)
+      twinError('[twin-engine] recovery scan failed', err)
     }
   }
 
@@ -400,7 +707,7 @@ export class TwinEngine {
    *
    * ── 모드를 지어내지 않는다 ──────────────────────────────────────────────────
    * 미러였던 트윈을 시뮬로 되살리면 **없던 움직임을 만들어 낸다**(관측 트윈이 스스로 물건을 옮긴다).
-   * 그래서 선언된 `realityMode` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
+   * 그래서 선언된 `restartPolicy` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
    *
    * ── 되살릴 수 없으면 그렇게 적는다 ──────────────────────────────────────────
    * 실패를 삼키면 등록부가 계속 `running` 이라 말한다 — 우리가 고치려던 그 거짓말이다. 그래서 실패한
@@ -422,16 +729,20 @@ export class TwinEngine {
     }
 
     try {
-      if (row.realityMode === 'mirror') {
-        if (!row.model) throw new Error('no model')
-        /* 시각 기준은 **공간**이 갖는다 — 교대의 HH:MM 을 어느 기준으로 읽나(라이브 기동과 같은 규칙). */
-        this.startLive(instanceId, domainId, row.kind, await this.withSpaceTimeBase(row.model as TwinModelDef, domainId))
+      /*
+       * **선언된 모드로 되살리는 판단은 한 곳에 있다**(`startFromRegistry`) — 2026-08-20.
+       *
+       * 예전에는 이 자리에서 `resync` 를 갈라 `startLive` 를 불렀다. 그래서 부팅으로 살아난 미러는
+       * 관측 구동이었지만 **사람이 화면에서 시작한 미러는 시뮬로 떴다**(그 문에는 갈림이 없었다).
+       * 같은 선언이 두 결과를 내지 않도록 갈림을 문 안으로 옮겼다.
+       */
+      await this.startFromRegistry(domainId, instanceId)
+      if (row.restartPolicy === 'resync') {
         /* 계측을 나르는 피드는 커넥터의 것이다 — 레퍼런스 계층이 부팅 훅에서 다시 붙인다
            (`resumeReferenceLiveFeeds`). 여기서 어댑터를 아는 것은 계층을 거꾸로 잇는 것이다. */
-        console.log(`[twin-engine] resumed mirror "${instanceId}" — feed reattach is the reference layer's job.`)
+        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.realityMode} "${instanceId}".`)
+        twinLog(`[twin-engine] resumed ${row.restartPolicy} "${instanceId}".`)
       }
     } catch (err: any) {
       await this.markStopped(row, err?.message ?? 'resume failed')
@@ -440,11 +751,11 @@ export class TwinEngine {
 
   /** 되살리지 못한 행을 정직하게 적는다 — 「도는 중」이라 말하는 채로 두지 않는다. */
   private static async markStopped(row: TwinInstance, why: string): Promise<void> {
-    console.warn(`[twin-engine] "${row.instanceId}" not resumed (${why}) — registry says stopped now.`)
+    twinWarn(`[twin-engine] "${row.instanceId}" not resumed (${why}) — registry says stopped now.`)
     try {
       await getRepository(TwinInstance).update({ id: row.id }, { status: 'stopped' })
     } catch (e: any) {
-      console.error(`[twin-engine] could not mark "${row.instanceId}" stopped — registry now lies about it.`, e?.message)
+      twinError(`[twin-engine] could not mark "${row.instanceId}" stopped — registry now lies about it.`, e?.message)
     }
   }
 
@@ -482,9 +793,9 @@ export class TwinEngine {
 
     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).`)
+        twinLog(`[twin-engine] "${id}" is a bench twin — starting empty on purpose (seeding would skew the measurement).`)
       } else if (plan.reason === 'unsupported') {
-        console.warn(
+        twinWarn(
           `[twin-engine] kernel for "${id}" cannot be warm-started (no hydrateObserved) — it starts with structure only, so held stock will read as zero.`
         )
       }
@@ -504,10 +815,10 @@ export class TwinEngine {
       /* 「언제부터인가」도 말한다 — 잃으면 지속된 조건이 모두 「방금」으로 보인다. */
       ...(plan.attentionSinceCount ? [`${plan.attentionSinceCount} attention start time(s)`] : [])
     ].join(', ')
-    console.log(`[twin-engine] warm-started "${id}" — restored ${restored}.`)
+    twinLog(`[twin-engine] warm-started "${id}" — restored ${restored}.`)
     /* 뺀 것은 조용히 넘기지 않는다 — 지어내지 않았다는 사실 자체를 말해야 화면의 빈칸이 읽힌다. */
     if (plan.ordersWithoutDemand > 0) {
-      console.warn(
+      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.'
       )
@@ -535,7 +846,7 @@ export class TwinEngine {
     const declared = model?.localDurations as Record<string, string> | undefined
     if (declared && Object.keys(declared).length) {
       if (typeof kernel?.declareDurations !== 'function') {
-        console.warn(
+        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".'
         )
@@ -544,14 +855,30 @@ export class TwinEngine {
           kernel.declareDurations(declared)
         } catch (err: any) {
           /* 커널이 거절한 값은 조용히 넘기지 않는다 — 화면은 「넣었습니다」라고 말한 값이다. */
-          console.warn(`[twin-engine] "${id}": declared operation duration rejected by the kernel — ${err?.message ?? err}`)
+          twinWarn(`[twin-engine] "${id}": declared operation duration rejected by the kernel — ${err?.message ?? err}`)
+        }
+      }
+    }
+    /* 공정 모수(수율·셋업)도 같은 규율로 싣는다 — 커널이 그 창구를 갖지 않으면 그 사실을 말한다. */
+    const params = model?.localParams as Record<string, Record<string, string>> | undefined
+    if (params && Object.keys(params).length) {
+      if (typeof kernel?.declareParameters !== 'function') {
+        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 {
+        try {
+          kernel.declareParameters(params)
+        } catch (err: any) {
+          twinWarn(`[twin-engine] "${id}": declared operation parameter rejected by the kernel — ${err?.message ?? err}`)
         }
       }
     }
     const ops = model?.operations
     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.`)
+      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)
@@ -576,13 +903,42 @@ export class TwinEngine {
     const chained = chainEstimators([measured?.estimator, travel.estimator])
     if (!chained) {
       /* 왜 못 넣었는지 한 번만 알린다 — 이동시간이 상수로 남은 이유를 모르고 지나가지 않게. */
-      if (travel.reasons.length) console.warn(`[twin-engine] "${instanceId}": no duration estimator installed — ${travel.reasons.join('; ')}`)
+      if (travel.reasons.length) twinWarn(`[twin-engine] "${instanceId}": no duration estimator installed — ${travel.reasons.join('; ')}`)
       return
     }
     kernel.durationEstimator = chained
+    /*
+     * **양품률도 이력에서 배운다** (2026-08-19) — 소요와 같은 자리에서 붙인다.
+     *
+     * 커널이 그 시임을 갖지 않은 버전이면(발행 이전) 조용히 넘어가지 않고 말한다: 수율이 상수로 남은
+     * 이유를 모르고 지나가면, 화면의 불량 판정이 그 현장의 사실이 아니라 우리 상수의 결과다.
+     */
+    const yields = await this.measuredYield(domainId, instanceId)
+    if (yields?.estimator) {
+      if (typeof kernel.yieldOf !== 'function') {
+        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
+        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) {
+      /* 배운 것이 없고 버린 것만 있으면 그 사실도 말한다 — 「이력이 없다」와 「표본이 모자라다」는 다르다. */
+      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(
+    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('; ')})`}`
@@ -596,7 +952,15 @@ export class TwinEngine {
    * 거기에 KPI 조회를 그대로 달면 요청당 저널 스캔이 하나씩 붙는다 — 실측은 분 단위로 바뀌지 않으므로
    * 짧은 TTL 로 재사용한다. 캐시는 인스턴스별이고, 만료 전에는 같은 값을 쓴다(예측 간 일관성도 얻는다).
    */
-  private static measuredCache = new Map<string, { at: number; value: ReturnType<typeof buildMeasuredEstimator> | undefined }>()
+  private static measuredCache = new Map<
+    string,
+    {
+      at: number
+      value: ReturnType<typeof buildMeasuredEstimator> | undefined
+      /** 같은 폴드에서 나온 양품률 — **저널을 두 번 접지 않는다**(소요와 수율은 같은 창의 같은 사실이다). */
+      yields?: ReturnType<typeof buildYieldEstimator>
+    }
+  >()
   private static readonly MEASURED_TTL_MS = 60_000
   /**
    * 캐시 항목 상한 — **라이프사이클이 놓친 것까지 막는 두 번째 방어.**
@@ -613,22 +977,31 @@ export class TwinEngine {
    */
   private static readonly MEASURED_MAX = 5_000
 
+  /** 이 트윈이 이력에서 배운 양품률 — 소요와 **같은 폴드·같은 캐시**에서 온다(저널을 두 번 접지 않는다). */
+  private static async measuredYield(domainId: string, instanceId: string) {
+    await this.measuredEstimator(domainId, instanceId)
+    return this.measuredCache.get(runtimeKey(domainId, instanceId))?.yields
+  }
+
   private static async measuredEstimator(domainId: string, instanceId: string) {
     /* 키는 `runtimeKey` 하나로 — 손으로 조립하면 지우는 쪽과 어긋나 못 지우는 항목이 생긴다. */
     const key = runtimeKey(domainId, instanceId)
     const hit = this.measuredCache.get(key)
     if (hit && Date.now() - hit.at < this.MEASURED_TTL_MS) return hit.value
     let value: ReturnType<typeof buildMeasuredEstimator> | undefined
+    let yields: ReturnType<typeof buildYieldEstimator> | undefined
     try {
       /* 작업 종류별 실측 — 창은 넉넉히(하루) 두고 표본이 모자란 종류는 추정기가 스스로 뺀다. */
       const kpi: any = await computeTwinKpi({ domainId, instanceId, windowMinutes: 24 * 60, groupBy: 'taskKind' })
       value = buildMeasuredEstimator(kpi?.groups?.items, {})
+      /* 같은 그룹에서 양품률도 배운다 — 한 번 접은 저널을 둘이 나눠 쓴다. */
+      yields = buildYieldEstimator(kpi?.groups?.items, {})
     } catch (err) {
-      console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, (err as any)?.message)
+      twinWarn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, (err as any)?.message)
     }
     /* 다시 넣어 **최근 쓴 것**으로 만든다 — 삽입 순서가 곧 버릴 순서이므로 이 한 줄이 LRU 를 만든다. */
     this.measuredCache.delete(key)
-    this.measuredCache.set(key, { at: Date.now(), value })
+    this.measuredCache.set(key, { at: Date.now(), value, yields })
     if (this.measuredCache.size > this.MEASURED_MAX) {
       const oldest = this.measuredCache.keys().next()
       if (!oldest.done) this.measuredCache.delete(oldest.value)
@@ -636,6 +1009,74 @@ export class TwinEngine {
     return value
   }
 
+  /**
+   * **원본이 선언한 자극을 싣는다** — 재기동해도 살아 있게 (2026-08-19).
+   *
+   * ── 무엇이 났나 ────────────────────────────────────────────────────────────
+   * 데모의 시나리오는 시드 코드가 메모리에만 실었다. 그래서 트윈을 재기동하면 자극이 사라지고 구조만
+   * 서 있는 트윈이 남았다(작업 0·오더 0) — 「살아 있는 데모」가 **첫 재기동까지만** 살았다.
+   *
+   * 자극의 집은 **원본**이다(`TwinReference.connectionConfig.scenario`, ADR-0029 ·
+   * `plans/simulator-as-source.md` §4): 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터가 정하는 사실이고
+   * 트윈은 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 걷어내야 할 표면이 하나 늘어난다.
+   *
+   * 판정은 순수 함수가 한다(`planStimulus`) — 미러에 싣지 않고, 검사를 통과하지 못한 선언은 태우지 않고
+   * (그 이력이 있다: 잘못된 선언 하나가 다음 틱에서 서버를 내렸다), 못 실은 이유는 **말한다.**
+   */
+  private static async installStimulus(domainId: string, instanceId: string, inst: InstanceRuntime): Promise<void> {
+    let config: any
+    try {
+      const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+      config = ref?.connectionConfig
+    } catch (err: any) {
+      twinWarn(`[twin-engine] "${instanceId}": could not read the declared stimulus — ${err?.message ?? err}`)
+      return
+    }
+    const plan = planStimulus(config, { hasScenarioEngine: !!inst.runtime?.scenario, mode: inst.mode }, validateScenario as any)
+    if (plan.action === 'skip') {
+      /* 선언이 없는 것은 정상이므로 조용히 지난다. 나머지 셋은 **말한다** — 선언했는데 안 실린 상태다. */
+      if (plan.reason !== 'none') {
+        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
+      recordPhase(inst.load ?? (inst.load = newLoadMeter()), 'stimulus', stimMs)
+      const kinds = (plan.scenario.generators ?? []).map((g: any) => g?.kind).filter(Boolean)
+      twinLog(
+        `[twin-engine] "${instanceId}": stimulus from its source started in ${Math.round(stimMs)}ms — ${kinds.length ? kinds.join(', ') : 'no generators'}.`
+      )
+    } catch (err: any) {
+      twinWarn(`[twin-engine] "${instanceId}": the declared stimulus was rejected at load — ${err?.message ?? err}`)
+    }
+  }
+
+  /**
+   * 자극을 **원본에 선언한다** — 프로비저닝·데모 시드가 부르는 문.
+   *
+   * 트윈이 아니라 원본에 적는 이유는 위와 같다(ADR-0029). 원본 행이 없으면 만들지 않는다 — 어떤 원본에서
+   * 온 트윈인지 모르는 채 자극을 지어 붙이면, 그 자극이 어디서 왔는지 아무도 되짚을 수 없다.
+   */
+  static async declareStimulus(domainId: string, instanceId: string, scenario: any): Promise<boolean> {
+    const repo = getRepository(TwinReference)
+    const ref = await repo.findOne({ where: { domain: { id: domainId }, source: instanceId } })
+    if (!ref) {
+      twinWarn(`[twin-engine] "${instanceId}": no source reference — a stimulus has nowhere to be declared.`)
+      return false
+    }
+    ref.connectionConfig = withStimulus(ref.connectionConfig, scenario)
+    await repo.save(ref)
+    return true
+  }
+
   /**
    * 이 트윈이 **이력에서 시간을 배운 작업 종류들** — 재기동에도 남는 근거.
    *
@@ -748,7 +1189,7 @@ export class TwinEngine {
     const plan = planLiveContinuity(cached)
     if (!plan.ackedCount && !plan.attentionSinceCount && !plan.energy) return
     if (typeof kernel.hydrateContinuity !== 'function') {
-      console.warn(
+      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.'
       )
@@ -758,7 +1199,7 @@ export class TwinEngine {
       kernel.hydrateContinuity(plan.seed)
     } catch (err: any) {
       /* 이어받기가 실패해도 미러는 돌아야 한다 — 다만 무엇을 잃었는지 말한다. */
-      console.warn(`[twin-engine] continuity seed failed for "${id}" — starting without it: ${err?.message ?? err}`)
+      twinWarn(`[twin-engine] continuity seed failed for "${id}" — starting without it: ${err?.message ?? err}`)
       return
     }
     const carried = [
@@ -766,10 +1207,10 @@ export 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.`)
+    twinLog(`[twin-engine] mirror "${id}" carried over ${carried} — observation axes come from the source.`)
   }
 
-  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 {
     const key = runtimeKey(domainId, id)
     if (this.instances[key]) return this.instances[key]
 
@@ -778,8 +1219,16 @@ export 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 => 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) twinLog(`[twin-engine] "${id}": warm start took ${Math.round(warmMs)}ms.`)
     /*
      * **번호를 이어 센다** — 저널에 이미 있는 번호와 겹치지 않게.
      *
@@ -808,48 +1257,95 @@ export class TwinEngine {
      * 실제로는 도는 커널이 옛 수를 그대로 쓰고 재기동 때 받는데, 그 사실이 답에서 사라진 것이다.
      * 규약에 기대는 대신 사실을 적는다: 「돌고 있나」를 묻는 쪽이 그 답을 받아야 한다.
      */
-    const inst: InstanceRuntime = { id, domainId, mode: 'sim', runtime, kernel, realityMode: realityMode ?? DEFAULT_REALITY_MODE, spaceId: (model as any)?.spaceId, unsub: () => {} }
+    const inst: InstanceRuntime = {
+      id,
+      domainId,
+      mode: 'sim',
+      runtime,
+      kernel,
+      /* 정책은 부르는 쪽이 선언한다 — 여기서 고르면 같은 트윈이 부르는 자리에 따라 다르게 재기동한다. */
+      restartPolicy: readRestartPolicy(restartPolicy, `start("${id}")`),
+      spaceId: (model as any)?.spaceId,
+      /*
+       * **시뮬도 계기를 든다** (2026-08-20).
+       *
+       * 예전에는 `startLive` 에서만 만들었다. 그래서 도는 트윈 22개가 시뮬인 서버에서 「초당 몇 행을
+       * 쓰나」·「밀린 게 있나」를 물을 자리가 **아예 없었다** — 저널 쓰기를 배치로 고친 뒤에도 그 효과와
+       * 회귀를 숫자로 볼 수 없다. 세지 않는 개선은 다음 사람이 되돌려도 아무도 모른다.
+       *
+       * 유입(`ingested`)은 시뮬에 뜻이 없다(원본에서 받는 것이 아니라 자기가 낸다) — 그 칸은 0 으로
+       * 남고, 그것이 사실이다(「받은 것이 없다」).
+       */
+      metrics: this.newMetrics(),
+      unsub: () => {}
+    }
     this.instances[key] = inst
     /* 다시 세웠으므로 지난 정지 이유는 사실이 아니다 — 남겨 두면 도는 트윈이 「굶겨서 멈췄다」고 말한다. */
     this.stopNotes.delete(key)
     delete this.recovered[key] // 웜스타트로 커널에 옮겨 심었다 — 이제 라이브가 진실이다.
+    /* 원본이 선언한 자극 — 기동을 막지 않는다(추정기와 같은 규율). 못 실었으면 그 사실을 말한다. */
+    this.installStimulus(domainId, id, inst).catch(err => twinWarn(`[twin-engine] "${id}": stimulus install failed — ${err?.message ?? err}`))
 
     /* 라이브 바인딩(P3): data 채널 필터가 subdomain 을 보므로 Domain 객체를 1회 해석해 둔다. */
     getRepository(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: SubscriptionMessage) => {
       this.publishGuarded(
         'twin-state',
         { twinState: { instanceId: id, kind: msg.kind, revision: (msg as any).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 as any).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()
 
-    /* 복구 앵커: 레지스트리에 model/kind/status/realityMode 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
-    this.register(domainId, id, kind, model, 'running', inst.realityMode).catch(err => console.error('twin register fail', err))
+    /* 위에서 잰 웜스타트 시간을 계기에 적는다 — 계기는 인스턴스가 생긴 뒤에야 있다. */
+    recordPhase(inst.load ?? (inst.load = newLoadMeter()), 'warmStart', warmMs)
+
+    /* 복구 앵커: 레지스트리에 model/kind/status/restartPolicy 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
+    this.register(domainId, id, kind, model, 'running', inst.restartPolicy).catch(err => 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
   }
 
@@ -913,7 +1409,7 @@ export class TwinEngine {
     const space = await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId: sid } }).catch(() => null)
     const offset = 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.`)
+      if (space?.timezone) 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 }
@@ -927,12 +1423,12 @@ export class TwinEngine {
     kernel.loadTwinModel(model)
     /* **세우는 쪽이 아는 사실은 세울 때 말한다.** 예전에는 첫 이벤트가 도착해야 커널이 스스로를
        관측 구동으로 여겼고, 그래서 아직 아무것도 못 받은 미러는 시뮬레이션 취급을 받았다. */
-    kernel.observe?.()
+    declareObserved(kernel, `live twin '${id}'`)
     this.applyOperations(kernel, model, id) // 명세는 라이브에도 실린다(예측 자격이 sim 과 같아진다)
     /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
      * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
     const projector = { apply: (e: CanonicalEnvelope) => kernel.apply(e), snapshot: () => kernel.getSnapshot() }
-    const inst: InstanceRuntime = { id, domainId, mode: 'live', realityMode: 'mirror', kernel, projector, oee: new OeeAccumulator(), spaceId: (model as any)?.spaceId, unsub: () => {} }
+    const inst: InstanceRuntime = { id, domainId, mode: 'live', restartPolicy: 'resync', kernel, projector, oee: new OeeAccumulator(), spaceId: (model as any)?.spaceId, unsub: () => {} }
     /*
      * ── 커널이 **판정으로 낸 사실**도 저널에 남는다 (2026-08-14 실측으로 잡음) ────
      *
@@ -952,14 +1448,17 @@ export class TwinEngine {
     inst.unsub = kernel.onEvent?.((e: CanonicalEnvelope) => {
       if (e && typeof e === 'object' && applying.has(e as object)) 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 => twinWarn('[twin-engine] estimator install failed', err?.message))
+    inst.metrics = this.newMetrics()
     this.instances[key] = inst
+    /* 미러에도 부른다 — 선언이 있으면 「미러에는 싣지 않는다」고 말해야 한다(조용한 무시 금지). */
+    this.installStimulus(domainId, id, inst).catch(err => twinWarn(`[twin-engine] "${id}": stimulus check failed — ${err?.message ?? err}`))
     /*
      * **원천이 되풀어 주지 않는 것만 잇는다** (2026-08-18 실측으로 붙임).
      *
@@ -975,23 +1474,62 @@ export class TwinEngine {
     delete this.recovered[key]
     /* 라이브 바인딩(data 채널) subdomain 필터용 Domain 1회 해석(sim 과 동일). */
     getRepository(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 부터 세는 것이 맞다. 그리고 이 조회는
+     * 비동기라 그 사이에 이벤트가 몇 건 들어와 있을 수 있는데, 그때 뒤로 되돌리는 것은 커널이 거절한다
+     * (겹치는 번호를 막는 그 판정이다). 거절은 삼키지 않고 남긴다.
+     */
     getRepository(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 as any).resumeRevision !== 'function') return
+        try {
+          ;(kernel as any).resumeRevision(head)
+        } catch (err: any) {
+          /* 뒤로 갈 수 없다는 거절 — 이 조회가 도착하기 전에 이미 그만큼 처리했다는 뜻이다. */
+          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', 'mirror').catch(err => console.error('twin register fail', err))
+    this.register(domainId, id, kind, model, 'running', 'resync').catch(err => 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: string, id: string, envelopes: CanonicalEnvelope[]): void {
+  static ingestLive(domainId: string, id: string, envelopes: CanonicalEnvelope[]): number {
     const inst = this.instances[runtimeKey(domainId, id)]
-    if (inst?.mode !== 'live' || !inst.projector) return
+    if (inst?.mode !== 'live' || !inst.projector) return 0
     const tIngest = performance.now()
     /* 인입 봉투를 표시해 두고 넣는다 — 커널이 그것을 재방출해도 저널에 두 번 적히지 않게(위 구독 주석). */
     for (const e of envelopes) {
@@ -1001,51 +1539,151 @@ export class TwinEngine {
     }
     recordPhase(inst.load ?? (inst.load = newLoadMeter()), 'ingest', performance.now() - tIngest)
     // 저널 결선(라이브도 sim 처럼 이벤트 영속) — 단 이벤트마다 DB write 하면 부하폭발이라 모아뒀다가
-    // coalescer tick 에서 배치 기록(방송과 동일 주기). 히스토리 노브·타임라인·비즈니스 원장이 이 저널을 읽는다.
+    // coalescer tick 에서 배치 기록(브로드캐스팅과 동일 주기). 히스토리 노브·타임라인·비즈니스 원장이 이 저널을 읽는다.
     ;(inst.pendingJournal ?? (inst.pendingJournal = [])).push(...envelopes)
     if (inst.metrics) { 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 FULL_BROADCAST_EVERY = 25
+  /** 전부 만든 횟수 — 범위를 좁히지 못한 창이 얼마나 되는지 값으로 남는다. */
+  static broadcastFullPasses = 0
+  /**
+   * 브로드캐스팅을 만든 횟수 전부 — **전부 만든 횟수의 분모.**
+   *
+   * 분자만 내면 「전부 만들기 1,200회」가 많은 것인지 적은 것인지 읽을 수 없다. 좁히기가 듣고 있으면
+   * 이 값의 `1/FULL_BROADCAST_EVERY` 쯤이 전부 만든 횟수이고, 두 값이 비슷하면 범위를 거의 못 좁힌
+   * 것이다(원인은 대개 「모른다」로 떨어지는 사건이다).
+   */
+  static broadcastPasses = 0
+
+  /**
+   * 이 창에 건드린 물품을 모은다 — **말할 수 없으면 범위를 버린다(전부 만든다).**
+   *
+   * `events` 를 주지 않으면 「무엇이 바뀌었는지 모른다」다(구조 전환처럼 상태 전반이 달라지는 자리).
+   * 한 창에서 한 번 「모른다」가 되면 그 창은 끝까지 모르는 채로 둔다 — 뒤에 온 사건으로 범위를
+   * 되살리면 앞 사건이 건드린 것을 빠뜨린다.
+   */
+  static markItemsDirty(inst: InstanceRuntime, events?: any[]): void {
+    if (inst.dirtyItems === undefined) return // 이 창은 이미 「모른다」
+    if (!events) {
+      inst.dirtyItems = undefined
+      return
+    }
+    for (const e of events) {
+      const touched = touchedItemKeys(e)
+      if (!touched) {
+        inst.dirtyItems = undefined
+        return
+      }
+      for (const epc of touched) inst.dirtyItems.add(epc)
+    }
+  }
+
+  /** 브로드캐스팅 병합 주기(ms) — 브로드캐스팅률 상한. 인제스트가 아무리 빨라도 이 주기로만 브로드캐스팅. */
   static BROADCAST_COALESCE_MS = 200
+  /**
+   * ── 브로드캐스팅 주기는 **재 본 비용에 맞춘다** (2026-08-21 실측) ────────────────────
+   * 한 번의 브로드캐스팅은 상태 크기에 비례한다(실측: 물품 2,400 개인 트윈 하나가 4.5ms — 상태 투영 1.7ms,
+   * payload 만들기 1.8ms, 시그니처 1.0ms). 트윈이 스무 개면 200ms 마다 90ms 가 브로드캐스팅에 들어가고,
+   * 그 시간에는 HTTP 도 구독도 서지 못한다.
+   *
+   * 그래서 한 창에서 브로드캐스팅에 쓴 시간이 주기의 일정 몫을 넘으면 **주기를 늘린다**. 화면은 조금 늦게
+   * 갱신되고(최신-상태 채널이라 값은 마지막 것 하나뿐이므로 내용은 같다), 늘렸다는 것은 계기판이
+   * 말한다(`broadcastCoalesceMs`). 여유가 생기면 원래 주기로 되돌린다.
+   *
+   * 이것은 브로드캐스팅 비용을 **줄이는 것이 아니다** — 비용을 줄이는 것은 변경분만 만드는 일이고 그것은 별
+   * 작업이다. 여기서는 그때까지 호스트가 굶지 않게 상한을 둔다.
+   */
+  static BROADCAST_MAX_COALESCE_MS = 1000
+  /** 주기의 몇 몫까지 브로드캐스팅에 써도 되는가 — 넘으면 주기를 늘린다(절반이면 나머지 절반은 남긴다). */
+  static BROADCAST_LOAD_RATIO = 0.3
+  /** 지금 쓰고 있는 주기(ms) — 계기판이 이 값을 읽는다. 늘어난 채로 있으면 그것이 사실이다. */
+  static broadcastPeriodMs = 200
+  /** 주기를 늘린 횟수 — 조용히 늦추지 않는다. */
+  static broadcastBackoffs = 0
   private static broadcastTimer?: any
 
-  /** live 방송 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 방송(entitySigs 로 변경 엔티티만). */
+  /** live 브로드캐스팅 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 브로드캐스팅(entitySigs 로 변경 엔티티만). */
   private static ensureBroadcastCoalescer(): void {
     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` 를 넘게 쓰면 주기를 두 배로(상한까지), 그 몫의
+   * 절반 아래로 내려오면 절반으로(원래 주기까지) 되돌린다. 문턱을 두 개 두는 이유는 하나면 경계에서
+   * 늘리고 줄이기를 반복하기 때문이다.
+   */
+  private static adjustBroadcastPeriod(flushMs: number): void {
+    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++
+      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(): void {
     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) {
@@ -1057,26 +1695,23 @@ export 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(() => recordPhase(inst.load ?? (inst.load = 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(
@@ -1085,12 +1720,16 @@ export class TwinEngine {
         `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)
   }
 
   /**
@@ -1130,22 +1769,134 @@ export class TwinEngine {
    * 없으면 `undefined` 다 — 0 이 아니다. 구조 리비전이 생기기 전에 만들어진 트윈은 아직 리비전이
    * 없고, 그 사실을 0 이라는 **유효해 보이는 번호**로 위장하면 안 된다.
    */
-  private static structureRevCache: Record<string, number> = {}
+  /** 구조 리비전 캐시 — `null` 은 **없다는 것을 알고 있다**는 뜻이다(모름과 구별한다, §7.1). */
+  private static structureRevCache: Record<string, number | null> = {}
   static async structureRevOf(domainId: string, instanceId: string): Promise<number | undefined> {
     const key = runtimeKey(domainId, instanceId)
     const cached = this.structureRevCache[key]
-    if (cached !== undefined) return cached
+    /*
+     * **없다는 것도 답이다** — 예전에는 찾지 못하면 캐시하지 않았다(`if (latest) …`). 그래서 구조 행이
+     * 없는 트윈은 **부를 때마다 SELECT** 했고, 그 경로가 델타마다 불리고 있었다(§7.1). `null` 로 기억한다.
+     */
+    if (cached !== undefined) return cached === null ? undefined : cached
     const latest = await getRepository(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
   }
 
+  /** 계기 한 벌 — **두 구동이 같은 것을 든다**(한쪽만 들면 그 구동은 물어도 답이 없다). */
+  private static newMetrics(): TwinMetrics {
+    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 }` 이면 시뮬이다.
+   */
+  private static flushJournal(inst: InstanceRuntime): Promise<void> {
+    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: any) => b && typeof b === 'object' && 'event' in b && typeof b.revision === 'number')
+    const plain = batch.filter((b: any) => !(b && typeof b === 'object' && 'event' in b && typeof b.revision === 'number'))
+
+    const tJournal = performance.now()
+    const done = () => recordPhase(inst.load ?? (inst.load = newLoadMeter()), 'journal', performance.now() - tJournal)
+    const jobs: Promise<void>[] = []
+
+    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 => twinError('twin journal flush fail', err))
+  }
+
+  /**
+   * 커널이 매긴 리비전을 그대로 들고 벌크 저장 — 시뮬 경로.
+   *
+   * 예전에는 이 경로가 **델타마다 한 행씩** 저장했다(그리고 행마다 구조 리비전을 물었다). 규모에서 그것이
+   * 호스트를 먹었다(§7.1 실측). 여기서 구조 리비전은 **한 번만** 묻는다.
+   */
+  static async persistCarried(domainId: string, instanceId: string, items: { event: any; revision: number }[]): Promise<void> {
+    const repo = getRepository(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행이면 어느 드라이버에서도 안전하다.
+   */
+  private static async insertRows(repo: any, rows: any[]): Promise<void> {
+    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: string, instanceId: string, envelopes: any[], startRevision: number): Promise<void> {
     const repo = getRepository(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) 공용. */
@@ -1155,7 +1906,7 @@ export class TwinEngine {
     kind: string,
     model: TwinModelDef,
     status: 'running' | 'stopped' = 'running',
-    realityMode?: RealityMode,
+    restartPolicy?: RestartPolicy,
     origin?: any,
     /*
      * 사람이 부르는 이름과 **누가 했나** — 업무키를 나눠 둔 대가로 이름을 함께 실어야 한다.
@@ -1176,10 +1927,15 @@ export class TwinEngine {
         // 인스턴스↔공간 1급 링크(space #3) — model.spaceId/areaId 를 컬럼으로 승격(dual-write). model JSON 도 유지(커널·복구용).
         spaceId: (model as any)?.spaceId ?? existing?.spaceId,
         areaId: (model as any)?.areaId ?? existing?.areaId,
-        /* 현실 출처 선언(§0 ①) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
-           둘 다 없으면 여기서 **각인한다**. 컬럼을 비워 두면 읽는 자리마다 기본값을 고르게 되고,
-           그러면 같은 트윈이 부르는 곳에 따라 다르게 재기동한다. 선언은 저장소에서 항상 명시적이다. */
-        realityMode: realityMode ?? existing?.realityMode ?? DEFAULT_REALITY_MODE,
+        /* 재기동 정책(ADR-0029 §2) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
+           **둘 다 없으면 오류를 낸다**: 예전에는 여기서 기본값을 각인했는데, 그 기본값이 「저널 초기화」라서
+           선언을 빠뜨린 프로비저닝이 조용히 이력을 지우는 트윈을 만들었다. 선언은 부르는 쪽의 몫이다. */
+        restartPolicy:
+          restartPolicy ??
+          readRestartPolicy(
+            existing?.restartPolicy,
+            `register("${instanceId}") did not declare a restart policy and the stored row has none`
+          ),
         /* 용도도 각인한다. 벤치로 뒤집는 것은 `setPurpose` 하나뿐이므로 기존값을 반드시 보존한다
            — 여기서 덮으면 재프로비전이 벤치 사본을 운영 트윈으로 되돌린다. */
         purpose: existing?.purpose ?? 'operational',
@@ -1237,7 +1993,7 @@ export class TwinEngine {
   private static assertNotRunning(domainId: string, instanceId: string): void {
     if (!this.instances[runtimeKey(domainId, instanceId)]) return
     /*
-     * **거절도 번역돼야 한다.** 이 문장은 던져져서 리졸버의 `catch` 를 지나 화면 토스트에 그대로
+     * **거절도 번역돼야 한다.** 이 문장은 전달되어 리졸버의 `catch` 를 지나 화면 토스트에 그대로
      * 떴다 — 다섯 언어 제품에서 영어 한 줄이 사용자에게 보였다(2026-08-14 실측).
      *
      * 그래서 코드와 파라미터를 예외에 실어 보낸다(`ImportSpaceRefusal` 과 같은 규약: 영어 문장은
@@ -1301,22 +2057,24 @@ export class TwinEngine {
      * 되돌리지 않는다 — 다만 조용히 넘기지 않고 말한다.
      */
     await projectStructure(domainId, instanceId, model, instanceId).catch((err: any) =>
-      console.warn(`[twin-engine] "${instanceId}" adopted a new structure but its projected rows were not refreshed — ${err?.message ?? err}`)
+      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 }
@@ -1327,6 +2085,14 @@ export class TwinEngine {
     instanceId: string,
     kind: string,
     model: TwinModelDef,
+    /**
+     * **재기동 정책은 생성 시점의 선언이다**(ADR-0029 §2) — 트윈은 정책 없이 존재할 수 없다.
+     *
+     * 예전에는 이 자리가 없었고 `register` 가 기본값(`sim-experiment` = 저널 초기화)을 각인했다. 그래서
+     * 선언을 빠뜨린 프로비저닝이 **재기동마다 이력을 지우는 트윈**을 조용히 만들었다. 이제 만드는 쪽이
+     * 말해야 한다: 이 트윈이 자기 과거를 어떻게 대하는지는 만드는 사람이 아는 사실이다.
+     */
+    restartPolicy: RestartPolicy,
     comment?: string,
     origin?: any,
     /** 이름·저자 — 업무키를 나눠 둔 대가로 이름을 함께 남긴다(`register` 의 `meta` 그대로). */
@@ -1351,7 +2117,7 @@ export class TwinEngine {
      * 달고 다닌다. 재생은 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다(`replaySegments`).
      */
     await this.recordStructure(domainId, instanceId, model, comment)
-    await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : (existing?.status as any) ?? 'stopped', undefined, origin, meta)
+    await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : (existing?.status as any) ?? 'stopped', restartPolicy, origin, meta)
   }
 
   /**
@@ -1464,12 +2230,49 @@ export class TwinEngine {
   }
 
   /** 레지스트리 model 로 기동(프로비전된 인스턴스 start). model 인자 없이 저장된 구조로 재기동. */
-  static async startFromRegistry(domainId: string, instanceId: string, realityMode?: RealityMode): Promise<InstanceRuntime> {
+  static async startFromRegistry(domainId: string, instanceId: string, restartPolicy?: RestartPolicy): Promise<InstanceRuntime> {
     const key = runtimeKey(domainId, instanceId)
     if (this.instances[key]) return this.instances[key]
     const reg = await getRepository(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 ?? readRestartPolicy(reg.restartPolicy, `twin "${instanceId}"`)
+    if (policy === 'resync') {
+      /* 미러는 **관측 구동**으로 세운다 — 시뮬로 세우면 없던 움직임을 스스로 만든다.
+         시각 기준은 공간이 갖는다(부팅 경로와 같은 규칙). */
+      return this.startLive(instanceId, domainId, reg.kind, await this.withSpaceTimeBase(reg.model as TwinModelDef, domainId))
+    }
+    if (policy === 'reset') {
+      /*
+       * 씨앗 재현 — 저널을 비우고 리비전 0 부터 다시 센다. 복구본도 함께 버린다(`resetJournal` 이 한다):
+       * 남겨 두면 백지로 시작한 트윈에 옛 상태가 되살아나 「씨앗 재현」이 아니게 된다.
+       *
+       * **벤치 사본은 예외다.** 그것은 누군가 지켜보는 실험이고, 그 실험의 기록을 기동이 지우면 실험이
+       * 사라진다(부팅은 벤치를 되살리지도 않는다 — `resumeRow`).
+       */
+      if (reg.purpose !== 'bench') await this.resetJournal(domainId, instanceId)
+    }
+
     /*
      * 웜스타트 재료를 **여기서 확실히 확보한다.**
      * `start()` 는 동기라 스스로 캐시를 읽을 수 없어서 `recovered` 에 미리 담겨 있기를 기대하는데,
@@ -1490,7 +2293,7 @@ export class TwinEngine {
     /*
      * 저널에 남아 있는 마지막 번호 — **모드와 무관하게** 이것을 이어 센다.
      *
-     * 저널을 초기화하고 기동하는 모드(sim-experiment)라면 이 값이 0이라 아무 영향이 없다. 규칙을
+     * 저널을 초기화하고 기동하는 정책(`reset`)이라면 이 값이 0이라 아무 영향이 없다. 규칙을
      * 모드별로 구분하지 않는 이유: "저널이 비어 있지 않으면 그 뒤부터" 하나면 어느 모드에서도
      * 겹칠 수 없고, 모드가 늘어도 이 자리를 다시 손볼 일이 없다.
      */
@@ -1508,29 +2311,30 @@ export class TwinEngine {
          메웠는데, 그건 YMS/MES 트윈을 **조용히 WMS 로 부팅**시키는 길이었다 — 오류 없이 다른 공장이 뜬다. */
       reg.kind,
       reg.model as TwinModelDef,
-      realityMode ?? (reg.realityMode as RealityMode),
+      /* 저장된 값은 위에서 **엄격히** 읽었다 — 모르는 값을 기본값으로 메우면 그 트윈이 조용히 다르게 재기동한다. */
+      policy,
       reg.purpose,
       Number(last?.max ?? 0) || 0
     )
   }
 
   /**
-   * 선언 기반 부팅(§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 async bootDeclared(domainId: string, instanceId: string, mode: RealityMode = DEFAULT_REALITY_MODE): Promise<InstanceRuntime> {
-    if (mode === 'mirror') {
+  static async bootDeclared(domainId: string, instanceId: string, mode: RestartPolicy): Promise<InstanceRuntime> {
+    if (mode === 'resync') {
       const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
       if (!reg?.model) throw new Error(`instance "${instanceId}" not provisioned (no model)`)
       return this.startLive(instanceId, domainId, reg.kind, reg.model as TwinModelDef)
     }
-    if (mode === 'sim-world') {
+    if (mode === 'resume') {
       /*
        * **이어지는 현실** — 저널을 지우지 않는다.
        *
@@ -1543,11 +2347,11 @@ export class TwinEngine {
        * 같은 씨앗에서 다시 시작하므로 자극의 패턴이 재기동 지점에서 한 번 끊긴다. 쌓인 사실과
        * 상태는 이어지고, 앞으로 일어날 일의 무작위 순서만 새로 시작한다.
        */
-      return this.startFromRegistry(domainId, instanceId, 'sim-world')
+      return this.startFromRegistry(domainId, instanceId, 'resume')
     }
-    // sim-experiment(기본): seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
+    // `reset`: seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
     await this.resetJournal(domainId, instanceId)
-    return this.startFromRegistry(domainId, instanceId, 'sim-experiment')
+    return this.startFromRegistry(domainId, instanceId, 'reset')
   }
 
   /**
@@ -1558,6 +2362,23 @@ export class TwinEngine {
   static async resetJournal(domainId: string, instanceId: string): Promise<void> {
     await getRepository(TwinEvent).delete({ domain: { id: domainId } as any, instanceId })
     delete this.recovered[runtimeKey(domainId, instanceId)]
+    /*
+     * ── **체크포인트도 함께 무효로 만든다** (2026-08-20) ──────────────────────
+     *
+     * 저널만 지우면 씨앗 재현이 되지 않는다: 웜스타트는 체크포인트를 **먼저** 보고, 그것이 남아 있으면
+     * 백지로 시작한 트윈에 옛 상태가 되살아난다(저널은 비었는데 재고가 있는 트윈이 된다).
+     * 시간여행이 딛는 사슬 캐시도 같은 이유로 무효다 — 지워진 리비전을 가리키게 된다.
+     *
+     * 공통 캐시 서비스에는 삭제가 없다(get/set/clearStale 뿐). 그래서 **「없음」을 적는다** — 값을
+     * 지어내는 것이 아니라 「체크포인트가 없다」는 사실을 적는 것이고, 읽는 쪽은 이미 `cached?.state` 로
+     * 그것을 가려낸다. 공통 모듈에 삭제를 새로 뚫는 것은 이 한 자리를 위해 하기에는 큰 변경이다.
+     */
+    await cacheService
+      .setInCache(this.SNAPSHOT_CACHE_ID, { domainId, instanceId }, { revision: 0, state: null }, this.SNAPSHOT_TTL_S)
+      .catch(err => twinWarn(`[twin-engine] "${instanceId}" checkpoint not invalidated — a seed run may inherit old state:`, err?.message ?? err))
+    await cacheService
+      .setInCache(this.CHAIN_INDEX_CACHE_ID, { domainId, instanceId }, { revisions: [] }, this.SNAPSHOT_TTL_S)
+      .catch(err => twinWarn(`[twin-engine] "${instanceId}" chain index not cleared — time travel may point at deleted revisions:`, err?.message ?? err))
   }
 
   /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
@@ -1598,27 +2419,60 @@ export class TwinEngine {
       (await getRepository(TwinSpace).find({ where: { domain: { id: domainId } } })).map(s => [s.spaceId, s.name])
     )
     /*
-     * **최신 리비전은 한 번에 묻는다.**
+     * **최신 리비전은 트윈마다 인덱스 끝에서 한 행씩 읽는다.**
+     *
+     * ── 그룹 질의로 바꾸었다가 되돌렸다 (2026-08-22 실측) ─────────────────────
+     * 예전 주석은 이랬다: 「트윈마다 `findOne(order revision DESC)` 을 돌고 있었다 — 13개면 질의
+     * 13번이고, 트윈이 늘면 그대로 자란다. 한 번의 그룹 질의로 바꾼다.」
+     *
+     * **질의 개수를 줄였지만 일의 양을 늘렸다.**
+     *
+     *   findOne × 13    `(domain, instance, revision)` 인덱스 **끝에서 한 행** — 각각 O(1)
+     *   GROUP BY 한 번  그 도메인의 저널을 **전수 집계** — O(전체)
      *
-     * 트윈마다 `findOne(order revision DESC)` 을 돌고 있었다 — 13개면 질의 13번이고, 트윈이 늘면
-     * 그대로 자란다. 이 목록은 트윈 관리·현장 구성·엔티티 패널이 모두 읽는 자리다.
-     * 한 번의 그룹 질의로 바꾼다(같은 모양의 선례가 이 파일에 이미 있다: structureRev 집계).
+     * 저널이 작을 때는 이득이었고, 커지면서 손해가 됐다. 실측(저널 1,134만 행): 이 그룹 질의가
+     * **44.7초**였다. 그리고 sqlite 드라이버는 연결이 하나이므로 그동안 앱의 모든 질의가 그 뒤에 섰다 —
+     * 같은 순간 29행짜리 `twin_instances` 조회도 44.7초로 찍혔다. 이 목록은 「트윈 관리·현장 구성·
+     * 엔티티 패널이 모두 읽는 자리」여서, 화면을 열 때마다 서버 전체가 그만큼 멈췄다.
+     *
+     * 트윈 수는 수십이고 저널은 천만이다. **작은 것을 여러 번 읽는 편이 큰 것을 한 번 훑는 것보다 싸다.**
+     * 질의 개수가 트윈 수에 비례해 자라는 것은 사실이지만, 각 질의가 인덱스 끝 한 행이므로 그 성장은
+     * 감당된다 — 그리고 병렬로 묻는다.
+     *
+     * **다시 그룹 질의로 바꾸지 말 것.** 바꾸려면 이 숫자를 먼저 다시 재라.
      */
     const tipOfInstance = new Map<string, number>()
-    try {
-      const tips = await getRepository(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: any) {
-      /* 집계가 실패하면 **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 getRepository(TwinEvent)
+            .createQueryBuilder('e')
+            .select('MAX(e.revision)', 'revision')
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId: r.instanceId })
+            .getRawOne<{ revision: unknown }>()
+          /* 행이 없으면 `null` 이다 — 그때는 비워 둔다(0 은 "아무 일도 없었다" 는 주장이다). */
+          if (row?.revision != null) tipOfInstance.set(String(r.instanceId), Number(row.revision) || 0)
+        } catch (err: any) {
+          /* 한 트윈의 조회가 실패해도 **0 으로 메우지 않는다** — 리비전 0 은 "아직 아무 일도 없었다" 는
+             사실 주장이다. 비워 두면 아래에서 undefined 로 남고, 화면은 그것을 "모름" 으로 그린다.
+             그리고 그 트윈만 모름이 된다 — 예전에는 집계 하나가 실패하면 전부 모름이었다. */
+          twinError(`[twin-engine] latest revision lookup failed "${r.instanceId}"`, err?.message ?? err)
+        }
+      })
+    )
 
     const out: any[] = []
     for (const r of rows) {
@@ -1637,7 +2491,7 @@ export class TwinEngine {
         spaceId: r.spaceId, // co-location: 같은 spaceId 인스턴스들이 한 현장 공유 — 현장뷰 집약 키(G7)
         /* 사람이 읽는 현장 이름 — 없으면 `undefined`(화면이 "이름 없음" 을 알아볼 수 있어야 한다). */
         spaceName: (r.spaceId ? spaceNameOf.get(r.spaceId) : undefined) || undefined,
-        realityMode: r.realityMode, // 현실 출처 선언(§0 ①) — mirror/sim-world/sim-experiment. 저장 시 각인되므로 비지 않는다.
+        restartPolicy: r.restartPolicy, // 재기동 정책(ADR-0029 §2) — resync/resume/reset. 선언이므로 비어 있을 수 없다.
         purpose: r.purpose, // 운영 vs 벤치 사본(1급 구별 — 이름 접두사 아님). 저장 시 각인되므로 비지 않는다.
         copyOf: r.copyOf ?? undefined,
         running: !!this.instances[runtimeKey(domainId, r.instanceId)],
@@ -1651,7 +2505,7 @@ export class TwinEngine {
         /* 스스로 멈춘 이유 — 있으면 낸다. 재기동 뒤에는 없다(그때는 「모른다」가 사실이다). */
         stopNote: this.stopNotes.get(runtimeKey(domainId, r.instanceId)) || undefined,
         liveFeed: liveFeedStateOf({
-          realityMode: r.realityMode,
+          restartPolicy: r.restartPolicy,
           running: !!this.instances[runtimeKey(domainId, r.instanceId)],
           instanceId: r.instanceId
         }),
@@ -1744,6 +2598,8 @@ export class TwinEngine {
   static async ingestMaster(
     domainId: string,
     master: ReferenceMaster,
+    /** 만들어지는 트윈의 재기동 정책 — 원본이 정하는 것이 아니라 **만드는 쪽의 선언**이다(ADR-0029 §2). */
+    restartPolicy: RestartPolicy,
     into?: { spaceId?: string },
     /** 누가 인제스트했나 — 사람이 없는 경로(부팅)는 주지 않는다(감사 기록을 지어내지 않는다). */
     actor?: { id: string }
@@ -1914,7 +2770,7 @@ export class TwinEngine {
       warnings.push(structureAdopted(shift.rev, shift))
     } else {
       /* 사이트 이름이 곧 트윈의 이름이다 — 마스터가 이미 말했으므로 지어내지 않고 그대로 싣는다. */
-      await this.provision(domainId, master.source, master.system, model, undefined, master.origin, {
+      await this.provision(domainId, master.source, master.system, model, restartPolicy, undefined, master.origin, {
         name: master.siteName,
         description: (master as any).description,
         actor
@@ -1943,11 +2799,11 @@ export class TwinEngine {
         }
       }
     } catch (err: any) {
-      console.error(`[twin-engine] structure projection failed for "${master.source}":`, err?.message)
+      twinError(`[twin-engine] structure projection failed for "${master.source}":`, err?.message)
       warnings.push(projectionFailed(err?.message ?? 'unknown'))
     }
 
-    if (warnings.length) console.warn(`[twin-engine] ingest "${master.source}" warnings: ${describeWarnings(warnings)}`)
+    if (warnings.length) twinWarn(`[twin-engine] ingest "${master.source}" warnings: ${describeWarnings(warnings)}`)
     return { instanceId: master.source, spaceId, warnings }
   }
 
@@ -1960,7 +2816,7 @@ export class TwinEngine {
       kind: r.kind,
       status: r.status,
       running: !!this.instances[runtimeKey(domainId, r.instanceId)],
-      realityMode: r.realityMode, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
+      restartPolicy: r.restartPolicy, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
       model: r.model
     }
   }
@@ -1970,15 +2826,15 @@ export class TwinEngine {
    * 보드 컴포넌트가 tag 로 구독(board-ui provider)해 `component.data` 로 라이브 갱신. delta 시에만(희소).
    * tag=엔티티 id(데모=단일 인스턴스). 멀티 인스턴스/보드 재사용 시 tag 네임스페이스는 후속.
    */
-  /** 방송 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
+  /** 브로드캐스팅 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
   private static publishDrops = new Map<string, { count: number; lastLogMs: number }>()
   private static readonly PUBLISH_DROP_LOG_MS = 10_000
 
   /**
-   * 한 번의 방송 — **구독자 하나가 호스트를 죽이지 못하게.**
+   * 한 번의 브로드캐스팅 — **구독자 하나가 호스트를 죽이지 못하게.**
    *
    * ── 무엇이 죽였나 (2026-08-14) ─────────────────────────────────────────────
-   * 밀린 push 가 1024를 넘으면 pubsub 이 던진다(`RepeaterOverflowError`). 그 방송은 타이머 콜백
+   * 밀린 push 가 1024를 넘으면 pubsub 이 오류를 낸다(`RepeaterOverflowError`). 그 브로드캐스팅은 타이머 콜백
    * 안에서 일어나므로 예외가 잡히는 곳 없이 올라가 **프로세스가 끝났다** — 트윈 14개가 도는 호스트가
    * 소비를 멈춘 구독자 하나 때문에 통째로.
    *
@@ -1995,7 +2851,7 @@ export 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}`)
+        twinWarn(`[twin-engine] broadcast dropped on "${what}" (${d.count} so far) — ${err?.message ?? err}`)
       }
       this.publishDrops.set(what, d)
       return false
@@ -2020,16 +2876,34 @@ export class TwinEngine {
     if (!st) return
     /*
      * 변화한 엔티티만 발행 — 이전엔 delta 마다 전 엔티티(노드+무버+오더)를 값 변화와 무관하게 전량 재발행해
-     * 같은 데이터를 매초 반복 push 하고 있었다(오용). 최신-상태 채널이므로 무변화 재방송은 무의미하다.
+     * 같은 데이터를 매초 반복 push 하고 있었다(오용). 최신-상태 채널이므로 무변화 재브로드캐스팅은 무의미하다.
      * 엔티티별 시그니처를 비교해 바뀐 것만 push.
      */
     const sigs = inst.entitySigs ?? (inst.entitySigs = new Map())
     const seen = new Set<string>()
     /* payload 매핑은 순수 함수(buildEntityDeltas)로 분리 — 여기선 시그니처 dedup + 발행만.
-     * 변화한 엔티티만 발행(최신-상태 채널이라 무변화 재방송 무의미). */
+     * 변화한 엔티티만 발행(최신-상태 채널이라 무변화 재브로드캐스팅 무의미). */
     /* ② payload 만들기 — 엔티티 수에 비례. ③ 시그니처 비교 + 발행 — 바뀐 것 수에 비례. */
     const tDelta = performance.now()
-    const deltas = 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 = buildEntityDeltas(st, inst.id, full ? undefined : { items: inst.dirtyItems! })
+    this.broadcastPasses++
+    if (full) this.broadcastFullPasses++
+    /* 이번 창의 범위는 여기서 닫는다 — 다음 창은 다시 모은다. */
+    inst.dirtyItems = new Set()
+    inst.fullBroadcastDue = false
     recordPhase(load, 'deltas', performance.now() - tDelta)
 
     const tPub = performance.now()
@@ -2045,14 +2919,21 @@ export class TwinEngine {
       if (!this.publishGuarded('data', { data: { domain, tag, data } }, `data:${inst.id}`)) sigs.delete(tag)
     }
     recordPhase(load, 'publish', performance.now() - tPub)
-    /* 사라진 엔티티의 시그니처 정리(맵 무한 성장 방지). */
-    if (sigs.size > seen.size) for (const tag of sigs.keys()) if (!seen.has(tag)) sigs.delete(tag)
+    /*
+     * 사라진 엔티티의 시그니처 정리(맵 무한 성장 방지) — **전부 만든 창에서만.**
+     * 범위를 좁힌 창의 `seen` 에는 만들지 않은 엔티티가 없으므로, 그때 정리하면 살아 있는 태그의
+     * 시그니처를 지운다. 낡은 값이 나가는 것은 아니지만(다음 창에 다시 만들어 보낸다) 같은 값을
+     * 되풀어 보내게 되어, 줄이려던 것을 되돌린다.
+     */
+    if (full && sigs.size > seen.size) for (const tag of sigs.keys()) if (!seen.has(tag)) sigs.delete(tag)
   }
 
-  static async persist(domainId: string, instanceId: string, msg: any): Promise<void> {
-    const repo = getRepository(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 해 상태 재구성.
@@ -2144,6 +3025,10 @@ export class TwinEngine {
     const baseWhere = { domain: { id: domainId }, instanceId }
     /* 이어 접을 때는 **그 뒤만** 읽는다 — 재개점까지의 사실은 이미 씨앗 안에 있다. */
     const from = resume ? (resume.revision ?? 0) : undefined
+    /*
+     * journal-fold: 재생은 사실을 하나씩 접는 것이므로 그 구간의 행이 필요하다. 커서(`from`)와 시각
+     * 상한이 구간을 자르고, 체크포인트가 앞쪽을 씨앗으로 대신한다 — 표 전체를 읽지 않는다.
+     */
     const rows = await getRepository(TwinEvent).find({
       where: useTime
         ? from
@@ -2324,22 +3209,71 @@ export 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: string, spaceId: string): Promise<{ minTime: string | null; maxTime: string | null }> {
     const regs = await getRepository(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)' } as const
+    const edge = async (instanceId: string, agg: 'MIN' | 'MAX'): Promise<number | null> => {
+      const row = await getRepository(TwinEvent)
+        .createQueryBuilder('e')
+        .select(AGG_SELECT[agg], 't')
+        .where('e.domain = :domainId', { domainId })
+        .andWhere('e.instanceId = :instanceId', { instanceId })
+        .getRawOne<{ t: unknown }>()
+      return parseTime(row?.t)
+    }
+
     let min = Infinity
     let max = -Infinity
-    for (const instanceId of ids) {
-      const rows = await getRepository(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) return { minTime: null, maxTime: null }
     return { minTime: new Date(min).toISOString(), maxTime: new Date(max).toISOString() }
   }
@@ -2360,14 +3294,20 @@ export class TwinEngine {
        * 체크포인트 루프가 20초마다 뜨지만 그 사이에 멈추면 그 구간이 통째로 다시 접힌다.
        */
       await this.persistSnapshot(domainId, id).catch(err =>
-        console.error(`[twin-engine] snapshot on stop fail "${id}"`, err?.message ?? err)
+        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[runtimeKey(domainId, id)]
       await getRepository(TwinInstance)
         .update({ domain: { id: i.domainId }, instanceId: id }, { status: 'stopped' })
-        .catch(err => console.error('twin deregister fail', err))
+        .catch(err => twinError('twin deregister fail', err))
     }
     for (const hook of this.stopHooks) { try { hook(id) } catch { /* 훅 격리 */ } }
   }
@@ -2426,7 +3366,7 @@ export class TwinEngine {
         const took = performance.now() - t0
         recordPhase(load, 'tick', took)
         const j = judgeCycle(load, took, this.TICK_MS, Date.now())
-        if (j.warn) console.warn(slowTickMessage(id, took, j.budgetMs, load))
+        if (j.warn) twinWarn(slowTickMessage(id, took, j.budgetMs, load))
         this.guardStarvation(domainId, id, took)
       }
     } catch (err: any) {
@@ -2476,9 +3416,9 @@ export class TwinEngine {
 
   /** 멈추고 **이유를 남긴다** — 이유 없는 「정지」는 사람이 자기가 멈춘 것으로 읽는다. */
   private static stopWithNote(domainId: string, id: string, note: StopNote, log: string): void {
-    console.error(log)
+    twinError(log)
     this.stopNotes.set(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 => twinError(`[twin-engine] stop after guard failed "${id}"`, err?.message ?? err))
   }
 
   /** 이 트윈이 스스로 멈춘 이유(있으면) — 화면이 옮겨 말한다. */
@@ -2540,7 +3480,7 @@ export 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' }
   }
@@ -2631,7 +3571,7 @@ export 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: loadSummary(this.instances[runtimeKey(domainId, id)]?.load, this.TICK_MS)
     }
@@ -2652,7 +3592,7 @@ export class TwinEngine {
       mode: inst.mode ?? 'sim',
       domainId: inst.domainId,
       domainLabel: inst.domain?.subdomain,
-      realityMode: inst.realityMode,
+      restartPolicy: inst.restartPolicy,
       tickMs: this.TICK_MS,
       running: !!inst.timer || inst.mode === 'live',
       ...(loadSummary(inst.load, this.TICK_MS) ?? { recent: null, total: null, forksCreated: 0, overBudget: 0, budgetMs: this.TICK_MS * 0.5, loadRatio: null })
@@ -2682,7 +3622,15 @@ export 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: loopLag.view(),
       ...fleetLoad(rows, this.TICK_MS),
       /* 줄마다 상세 — 화면이 펼쳐 볼 수 있게. 최근 부하 순서는 fleetLoad 가 정한다. */
       details: keys.map(key => { const at = parseRuntimeKey(key); return this.load(at.domainId, at.instanceId) }).filter(Boolean)
@@ -2701,7 +3649,183 @@ export class TwinEngine {
     if (inst) recordPhase(inst.load ?? (inst.load = newLoadMeter()), phase, tookMs)
   }
 
-  /** 전체 라이브 인스턴스 계측(모니터 대시보드용). */
+  /*
+   * ── 동기화 건강 장부 ───────────────────────────────────────────────────────
+   *
+   * **런타임이 아니라 엔진이 든다.** 인스턴스에 붙이면 트윈을 재기동할 때 사라지는데, 사람이 알고 싶은
+   * 것은 바로 그 순간이다 — 「고쳐서 다시 띄웠는데 이제 통과하나」. 프로세스가 사는 동안 이어진다.
+   *
+   * 지금은 메모리만이다. 창이 닫힐 때 한 행씩 영속하는 것은 `onWindowClosed` 한 자리에 붙는다.
+   */
+  private static ingestLedgers: Record<string, IngestLedger> = {}
+
+  /** 창이 닫힐 때 부를 곳 — 영속 계층이 부팅에서 한 번 등록한다(커널 층은 그 계층을 모른다). */
+  private static onWindowClosed?: (at: { domainId: string; instanceId: string }, closed: IngestWindow) => void
+
+  /**
+   * 닫힌 창을 받을 곳을 등록한다 — **영속(B)이 붙는 유일한 문.**
+   *
+   * 이 패키지는 저장 계층을 모른다. 등록하는 쪽이 자기 방식으로 쓴다. 훅이 오류를 내도 장부는 계속 굴러간다
+   * (`rollIngestWindow` 가 감싼다) — 영속을 지키려고 관측을 멈추지 않는다.
+   */
+  static onIngestWindowClosed(
+    fn: (at: { domainId: string; instanceId: string }, closed: IngestWindow) => void
+  ): void {
+    this.onWindowClosed = fn
+  }
+
+  /**
+   * 한 번의 인제스트 결과를 장부에 적는다.
+   *
+   * `offered` 는 **제시된 레코드 수**다(거부 여부 무관). 통과율을 서로 다른 두 계수기에서 나눠 계산하면
+   * 분모와 분자가 다른 것을 세게 되므로, 한자리에서 본 수를 그대로 넘긴다.
+   */
+  static recordIngestResult(
+    domainId: string,
+    instanceId: string,
+    offered: number,
+    rejected: { record?: unknown; errors?: string[] }[] | undefined,
+    nowMs = Date.now(),
+    /**
+     * 매핑은 통과했는데 **커널이 받지 않은** 수(`ingestLive` 의 반환과 견주어 얻는다).
+     *
+     * 「통과」로 세지 않는다 — 트윈이 멈춘 사이 사실이 사라지는데 화면이 100% 라고 말하게 된다.
+     */
+    undelivered = 0
+  ): void {
+    const key = runtimeKey(domainId, instanceId)
+    const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = newIngestLedger())
+    recordIngest(
+      ledger,
+      offered,
+      rejected,
+      nowMs,
+      closed => this.onWindowClosed?.({ domainId, instanceId }, closed),
+      undelivered
+    )
+  }
+
+  /**
+   * **원본에 닿지 못했다**를 적는다 — 「받은 것이 없다」와 가른다(§`recordReadFailure`).
+   *
+   * 이 문이 없던 동안 실 원본이 끊겨도 트윈의 조회 가능한 상태에 그 사실이 없었다. 화면이 볼 수 있는
+   * 것은 「새 사실이 없다」뿐이었고 그것은 「원본이 조용하다」와 구별되지 않는다 — 실증 중에 원본이
+   * 끊기면 사용자가 원인을 찾을 수 없다.
+   *
+   * 로그로는 말하고 있었다(어댑터가 재시도를 경고한다). 그러나 **로그는 사람이 볼 때만 값이 있다** —
+   * 화면이 말하려면 상태에 있어야 한다.
+   */
+  static recordIngestReadFailure(domainId: string, instanceId: string, reason: string, nowMs = Date.now(), stream?: string): void {
+    const key = runtimeKey(domainId, instanceId)
+    const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = newIngestLedger())
+    recordReadFailure(ledger, reason, nowMs, stream)
+  }
+
+  /**
+   * 읽기가 성공했다 — 단절 기록을 지운다.
+   *
+   * **빈 읽기도 성공이다.** 원본이 「새 것이 없다」고 답한 것은 닿았다는 뜻이므로, 그때도 부른다.
+   * 그 둘을 같게 두면 조용한 원본이 끊긴 원본으로 보인다.
+   */
+  static clearIngestReadFailure(domainId: string, instanceId: string): void {
+    const ledger = this.ingestLedgers[runtimeKey(domainId, instanceId)]
+    if (ledger) clearReadFailure(ledger)
+  }
+
+  /**
+   * 저널에 **적은 것**을 같은 장부에 남긴다 — 유입과 같은 10분 창에.
+   *
+   * ── 왜 유입 장부에 넣나 ────────────────────────────────────────────────────
+   * 새 장부를 만들면 「닫힌 창만 최근」·「0 과 없음을 가른다」·영속을 두 벌 지켜야 하고, 그중 한 벌만
+   * 고쳐지는 것이 보통이다. 유입 창은 그 규율이 이미 들어 있고 닫힐 때 행으로 남는다.
+   *
+   * ── 이 값이 없으면 무엇을 못 보나 ──────────────────────────────────────────
+   * 계기(`journalRate`)는 **지금**만 답한다. 프로세스를 다시 띄우면 0 에서 시작하므로 「어제 이 시각에도
+   * 이랬나」·「고친 뒤로 줄었나」를 물을 자리가 없다. 2026-08-20 에 고친 것이 바로 쓰기 경로이므로,
+   * 되돌아가는 것을 볼 수 있어야 한다.
+   */
+  static recordJournalWrite(domainId: string, instanceId: string, rows: number, nowMs = Date.now()): void {
+    const key = runtimeKey(domainId, instanceId)
+    const ledger = this.ingestLedgers[key] ?? (this.ingestLedgers[key] = newIngestLedger())
+    recordLedgerWrite(ledger, rows, nowMs, closed => this.onWindowClosed?.({ domainId, instanceId }, closed))
+  }
+
+  /**
+   * 「이 트윈이 현장과 맞춰지고 있나」 — 한눈 판정 + 추이 + 사유 + 표본.
+   *
+   * 조회할 때 창을 한 번 굴린다: 유입이 멈추면 다음 인제스트가 없어 창이 영원히 닫히지 않는데, 그러면
+   * 「최근」이 옛것으로 남는다. 타이머를 두지 않는 이유는 트윈마다 타이머를 걸면 그 타이머들이 다시
+   * 메인 루프에 얹히기 때문이다(오늘 확인한 그 부하를 이 기능이 다시 만들 이유가 없다).
+   */
+  /**
+   * 도메인의 트윈마다 **한 줄 요약** — 목록 화면과 미니 추이용.
+   *
+   * ── 왜 상세와 따로인가 ─────────────────────────────────────────────────────
+   * `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 }[] {
+    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: string, instanceId: string): IngestHealthView {
+    const key = runtimeKey(domainId, instanceId)
+    const nowMs = Date.now()
+    const ledger = this.ingestLedgers[key]
+    if (ledger) {
+      rollIngestWindow(ledger, nowMs, undefined, closed => this.onWindowClosed?.({ domainId, instanceId }, closed))
+    }
+
+    const inst = this.instances[key]
+    const feedState = liveFeedStateOf({
+      restartPolicy: inst?.restartPolicy,
+      running: !!inst,
+      instanceId
+    })
+    return ingestHealth(ledger, feedState, undefined, nowMs)
+  }
+
+  /**
+   * 도는 인스턴스 전체의 계측(모니터 대시보드용) — **시뮬과 미러를 함께**.
+   *
+   * 예전에는 시뮬에 계기가 없어 이 목록에서 조용히 빠졌다(계기가 `null` 이라 걸러졌다). 도는 트윈
+   * 대부분이 시뮬인 서버에서 그 목록은 「부하가 거의 없다」로 보였다.
+   */
   static async allMetrics(domainId?: string): Promise<any[]> {
     /* 도메인 없이 부르면 전 테넌트를 훑는다(내부 모니터용) — 키에서 도메인을 되돌려 각자에게 묻는다. */
     const rows = Object.keys(this.instances)
@@ -2754,6 +3878,14 @@ export class TwinEngine {
     const state = await this.recover(domainId, instanceId, undefined, untilTime).catch(() => null)
     if (!state) return null
     const cutoff = untilTime != null ? Date.parse(untilTime) : Infinity
+    /*
+     * journal-fold: 오더의 마지막 상태는 그 오더에 일어난 사실들을 접어야 나온다.
+     *
+     * **없어질 조건** — 지금 이 읽기에는 상한이 없고 `eventType` 에 인덱스도 없다. 그래서 저널이 큰
+     * 트윈에서는 이 한 번이 그 트윈의 저널 전체 주사다. 오더 상태를 따로 접어 둔 표(투영)를 두거나,
+     * `(domain, instanceId, eventType, revision)` 인덱스를 붙이고 커서를 넣으면 이 예외는 사라진다.
+     * 시각 상한(`cutoff`)을 SQL 로 내려도 절반은 준다.
+     */
     const rows = await getRepository(TwinEvent).find({ where: { domain: { id: domainId }, instanceId, eventType: OP_EVENT.order }, order: { revision: 'ASC' } })
     const latest = new Map<string, any>()
     for (const r of rows) {