@things-factory/headless-twin 10.0.12 → 10.0.13

package/server/engine/kpi-query.ts

@@ -14,11 +14,12 @@
  * 상수를 앱에서 재현하지 않고(무방언), 라이브 트윈에서도 자연스럽다(마지막 기록 ≈ 지금).
  * 어떤 기준을 썼는지는 결과의 `window.basis` 로 밝힌다 — 숨기면 사용자가 숫자를 오해한다.
  */
+import { twinWarn } from './log.js'
 import { Between, In } from 'typeorm'
 
 import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY, type TariffDeclaration } from '@operato/twin-kernel'
 
-import { getRepository } from '@things-factory/shell'
+import { getReadRepository, getRepository } from '@things-factory/shell'
 
 import { TwinEvent } from '../service/twin-event/twin-event.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
@@ -283,7 +284,7 @@ async function locationAreaMap(
     for (const row of rows) {
       const locations = (((row.model as any)?.locations ?? []) as any[]).filter(n => n?.id)
       if (!locations.length) continue
-      /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
+      /* 순환은 hierarchyOf 가 오류를 낸다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
       let h
       try {
         /*
@@ -293,7 +294,7 @@ async function locationAreaMap(
          */
         h = hierarchyOf({ locations }, t => levelOfLocationType(t, row.kind))
       } catch (e: any) {
-        console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
+        twinWarn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
         continue
       }
       for (const n of locations) {
@@ -483,22 +484,110 @@ async function latestEventTime(domainId: string, instanceIds: string[]): Promise
  */
 async function fetchEvents(domainId: string, instanceIds: string[], fromMs: number, toMs: number, lookbackMs: number) {
   if (instanceIds.length === 0) return { events: [] as KpiEvent[], capped: false }
-  const rows = await getRepository(TwinEvent).find({
-    where: {
-      domain: { id: domainId },
-      instanceId: In(instanceIds),
-      eventType: In(BUSINESS_EVENTS),
-      eventTime: Between(new Date(fromMs - lookbackMs), new Date(toMs))
-    },
-    order: { revision: 'ASC' },
-    take: MAX_EVENTS
-  })
+  /*
+   * ── 필요한 세 컬럼만, 그리고 **읽기 연결로** (2026-08-22 실측) ─────────────
+   * 이 읽기가 서버를 붙잡고 있었다. 실측(개발 DB 16.3GB · 저널 1,134만 행): 2만 행을 실어 오는 동안
+   * 다른 가벼운 읽기가 **47.6초** 기다렸다. 로그에서 이 자리 뒤로 사용자·도메인 조회까지 30.9초로
+   * 찍혔다 — TypeORM sqlite 드라이버는 연결을 하나만 들기 때문이다.
+   *
+   * **행 단위로 읽는 것 자체는 정당하다**: 이 폴드는 `p10·p50·p90` 을 낸다(§`kpi-fold`). 분위수는
+   * 카운터로 만들 수 없고 트윈별 사전집계로도 만들 수 없다(p90 의 평균은 p90 이 아니다). 개별 값이
+   * 있어야 한다.
+   *
+   * 정당하지 않은 것은 **읽는 방식**이었다. 세 가지를 고친다.
+   *
+   *  ① **엔티티를 만들지 않는다.** 폴드가 쓰는 것은 `eventType`·`eventTime`·`payload` 뿐인데
+   *     `find()` 는 열여섯 컬럼을 실어 엔티티로 만들고 관계 로더를 지난다. CPU 프로파일에서
+   *     `RawSqlResultsToEntityTransformer` 와 `stringToSimpleJson` 이 상위였다.
+   *  ② **읽기 연결로 보낸다**(`getReadRepository`). 순수 읽기이므로 쓰기와 순서를 다툴 것이 없다.
+   *     실측: 같은 2만 행 읽기에서 다른 읽기의 대기가 47.6초 → 2.8초.
+   *  ③ **정렬 축을 거르는 축과 맞춘다.** 여기가 이 자리의 진짜 비용이었다.
+   *
+   * ── `ORDER BY revision` 이 `LIMIT` 을 무력화했다 (실측) ────────────────────
+   * 거르는 축은 `event_time`(창)이고 정렬 축은 `revision` 이었다. 그러면 sqlite 는 창에 맞는 행을
+   * **전부** 찾아 `revision` 으로 **전부 정렬한 뒤** 상한을 적용한다 — 상한이 정렬 뒤에 걸리므로
+   * 아무것도 줄여 주지 않는다. 실측이 그것을 그대로 보였다(인스턴스 하나가 375만 행):
+   *
+   *   ORDER BY revision            LIMIT 20000 → 32.2초 · LIMIT 5000 → 28.3초 · LIMIT 2000 → 28.2초
+   *   ORDER BY eventTime, revision LIMIT 20000 →  0.41초                                     (78배)
+   *
+   * 계획도 그렇게 말한다: 앞은 `USE TEMP B-TREE FOR ORDER BY`(전체 정렬), 뒤는
+   * `USE TEMP B-TREE FOR LAST TERM OF ORDER BY` — 시각은 인덱스(`ix_twin_event_1`)에서 순서대로
+   * 나오고 **동시각만** 임시 정렬한다. 즉 범위를 훑다가 상한에서 멈춘다.
+   *
+   * ── 순서의 뜻은 **완전히 같지는 않다** (측정해서 고친 문장) ────────────────
+   * 처음에 「순서의 뜻은 같다」고 적었다. 재 보니 아니었다 — `revision` 순서와 `eventTime` 순서가
+   * 어긋나는 자리가 실재한다(hatio-mx2: 426만 행 중 **7건** · rosarito-mes: 11만 중 8건). 미러는
+   * 원본의 시각을 싣고 도착 순서로 리비전을 받으므로, 늦게 도착한 사건이 그 어긋남을 만든다.
+   *
+   * **그러나 폴드의 수치는 같다.** `foldTaskRecords`(커널 `task-fold.ts`)가 스트림 위치가 아니라
+   * **시각으로** 판정한다:
+   *
+   *   startedMs   = Math.min(startedMs, at)
+   *   completedMs = Math.max(completedMs, at)
+   *
+   * `min`·`max` 이므로 행이 어떤 순서로 와도 답이 같다. 소요시간·분위수·처리량은 순서와 무관하다.
+   *
+   * 순서에 민감한 자리는 **하나**다: 그 폴드의 `location` 이 「마지막에 본 것」이다. 같은 밀리초에 같은
+   * 작업의 자리가 두 번 바뀌면 어느 것이 남는지가 순서로 갈린다(라이브 미러가 같은 밀리초에 여러 행을
+   * 보내는 경우다). 수치가 아니라 **표시되는 자리 하나**이고, 그래서 이 바꿈의 값이 그 위험보다 크다.
+   *
+   * `revision` 을 둘째 축으로 남기는 이유도 그것이다 — 동시각의 순서가 실행마다 달라지지 않게 한다.
+   *
+   * **상한을 낮추는 것으로는 고쳐지지 않는다**(위 숫자가 그것을 말한다). 정렬 축이 원인이다.
+   *
+   * 남는 비용을 감추지 않는다: `payload` 파싱은 여전히 메인 스레드 일이고 연결을 나눠도 나뉘지 않는다
+   * (실측 평균 1.5초). 그것을 더 줄이려면 폴드가 payload 에서 무엇을 쓰는지 좁혀야 한다 — 별 건이다.
+   */
+  const raw = await getReadRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.payload AS "payload"'])
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
+    .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
+    .andWhere('e.eventTime BETWEEN :from AND :to', { from: new Date(fromMs - lookbackMs), to: new Date(toMs) })
+    .orderBy('e.eventTime', 'ASC')
+    .addOrderBy('e.revision', 'ASC')
+    .limit(MAX_EVENTS)
+    .getRawMany<{ eventType: string; eventTime: unknown; payload: unknown }>()
+
   /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
    * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
   return {
     /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
-    events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime?.toISOString(), payload: r.payload })),
-    capped: rows.length >= MAX_EVENTS
+    events: raw.map(r => ({ eventType: r.eventType, eventTime: isoOf(r.eventTime), payload: jsonOf(r.payload) })),
+    capped: raw.length >= MAX_EVENTS
+  }
+}
+
+/**
+ * 원시 결과의 시각을 ISO 로 — **드라이버마다 모양이 다르다.**
+ *
+ * 엔티티 경로에서는 TypeORM 이 `Date` 로 바꿔 주지만, 원시 결과는 드라이버가 준 그대로다(sqlite 는
+ * `'2026-08-07 11:00:00.000'`, pg 는 `Date`). 경계에서 한 번 정규화한다 — 폴드는 ISO 문자열만 안다.
+ */
+function isoOf(v: unknown): string | undefined {
+  if (v == null) return undefined
+  if (v instanceof Date) return v.toISOString()
+  const s = String(v)
+  /* sqlite 의 공백 구분 형식을 ISO 로 — 그대로 `Date` 에 주면 시간대 해석이 갈린다. */
+  const d = new Date(s.includes('T') ? s : s.replace(' ', 'T') + (s.endsWith('Z') ? '' : 'Z'))
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString()
+}
+
+/**
+ * 원시 결과의 `payload` 를 객체로 — **엔티티 경로의 `simple-json` 변환을 여기서 한다.**
+ *
+ * 깨진 JSON 은 **버리지 않고 비운다**: 그 사건이 있었다는 사실은 남고, 안을 읽을 수 없다는 것만
+ * 폴드에 전해진다(폴드는 없는 필드를 건너뛴다). 던지면 창 하나가 통째로 사라진다.
+ */
+function jsonOf(v: unknown): any {
+  if (v == null) return undefined
+  if (typeof v !== 'string') return v
+  try {
+    return JSON.parse(v)
+  } catch {
+    return undefined
   }
 }
 
@@ -597,6 +686,31 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...shiftCtx,
     groupLimit: input.groupLimit
   })
+  /*
+   * **완료로 세지 않은 오더 상태 낱말을 말한다** (2026-08-23).
+   *
+   * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
+   * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
+   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+   *
+   * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
+   * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
+   * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
+   *
+   * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
+   * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+   *
+   * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
+   * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
+   */
+  const notCounted = Object.entries(kpi.orderStatusNotCounted ?? {})
+  if (notCounted.length && kpi.throughput.orders === 0) {
+    twinWarn(
+      `[twin-kpi] no order counted as completed in this window, but these order status words were seen: ` +
+        `${notCounted.map(([w, n]) => `${w}×${n}`).join(' · ')} — the connector may not be translating them ` +
+        `to the kernel's vocabulary (see its own status table).`
+    )
+  }
   /*
    * 목표를 **폴드 뒤, 그룹 조립 앞**에 읽는다 — 전체 판정과 축별 판정이 같은 목록에서 나와야
    * 두 곳의 임계가 갈라지지 않는다. 폴드 자체는 목표를 모른다(사실 층과 판정 층의 분리).

package/server/engine/live-feed-registry.ts

@@ -1,3 +1,4 @@
+import { twinWarn } from './log.js'
 /*
  * 「이 트윈에 계측이 들어오고 있나」 — **그 사실을 한 자리에서 묻는다.**
  *
@@ -35,7 +36,7 @@ export function liveFeedAttached(instanceId: string): boolean {
     try {
       if (probe().includes(instanceId)) return true
     } catch (e: any) {
-      console.warn('[twin-live] a feed registry could not answer —', e?.message ?? e)
+      twinWarn('[twin-live] a feed registry could not answer —', e?.message ?? e)
     }
   }
   return false

package/server/engine/load-meter.ts

@@ -8,11 +8,11 @@
  *
  * 실제로 그런 상태를 만났다: 포트는 LISTEN 이고 webpack 은 `compiled successfully` 인데 요청이 하나도
  * 처리되지 않고 CPU 만 99% 였다. **터지면 알지만 느려지면 몰랐다** — `tickGuarded` 는 예외만 잡고
- * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·방송·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
+ * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·브로드캐스팅·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
  *
  * ── 총량만으로는 부족하다 ─────────────────────────────────────────────────
  * "틱이 800ms 걸렸다" 는 어디를 고칠지 알려 주지 않는다. 한 주기는 여러 작업으로 이뤄진다 —
- * 커널 틱 · 상태 투영(snapshot) · 방송 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
+ * 커널 틱 · 상태 투영(snapshot) · 브로드캐스팅 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
  * **작업마다 따로** 잰다. 어느 작업이 총 시간의 몇 %인지 보이면 손댈 곳이 정해진다.
  *
  * 재고 말하는 것이 먼저다. 워커 스레드로 옮기는 것은 그다음이다 — 무엇이 느린지 모른 채 옮기면
@@ -20,7 +20,16 @@
  */
 
 /** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
-export const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick'] as const
+/*
+ * ── 부팅 구간을 재는 두 이름 (2026-08-22) ───────────────────────────────────
+ * 실측으로 부팅이 620~717초였고 트윈 하나를 세우는 데 15~93초였다. 그런데 **어느 작업이 그 시간을
+ * 쓰는지 아무 계기도 답하지 못했다** — 재는 이름이 도는 중의 작업(틱·브로드캐스팅·저널)뿐이었다.
+ * 짐작으로 원인을 적으면 그것이 사실로 읽히므로, 그 자리에 이름을 둔다.
+ *
+ *  · `warmStart` — 저장된 상태를 커널에 심는다(물품·오더·작업·주목 시각).
+ *  · `stimulus`  — 선언된 자극을 싣고 시작한다(실측: 큰 트윈에서 이 뒤가 29~72초였다).
+ */
+export const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick', 'warmStart', 'stimulus'] as const
 export type LoadPhase = (typeof LOAD_PHASES)[number]
 
 export interface PhaseStats {

package/server/engine/log.ts

@@ -0,0 +1,72 @@
+/*
+ * 트윈 로그의 문 — **모든 줄에 시각을 찍는다.** 순수(프레임워크 의존 없음).
+ *
+ * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────
+ * 「서버가 왜 느린가」를 조사하면서 루프가 55초 막힌 것을 계기로 알아냈는데(`loop-lag.ts`),
+ * **그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.** 트윈의 로그가 `console.log` 로 나가
+ * 시각이 없었기 때문이다. 프레임워크 로그(`2026-08-22T05:54:12+09:00 info: …`)와 섞여 있어서, 어느
+ * 줄이 언제 찍혔는지 앞뒤 프레임워크 줄로 짐작해야 했다.
+ *
+ * ── 왜 프레임워크 로거를 그대로 쓰지 않나 ──────────────────────────────────
+ * 재발명을 피하려고 `@things-factory/env` 의 `logger` 를 쓰려 했는데, 실측으로 막혔다: 앱 **밖**에서는
+ * 그 로거에 전송지가 하나도 없다(설정이 앱에서 주입된다). 그래서 시험·도구에서 부르면
+ *
+ *   [winston] Attempt to write logs with no transports … {"message":"…","level":"info"}
+ *
+ * 가 나오고 **메시지 자체가 사라진다.** 트윈 엔진은 시험과 CLI 도구에서도 불려 다니므로, 그 조건에서
+ * 로그가 없어지는 것은 바꿔선 안 되는 거동이다(로그가 사라지는 것이 지금 문제의 원인이었다).
+ *
+ * 그래서 **싱크는 그대로 두고**(console) 빠진 사실 하나만 채운다 — 시각. 형식은 프레임워크와 같은
+ * 모양으로 맞춰 한 파일에서 섞여 읽히게 하고, **밀리초까지** 남긴다(계기의 값이 epoch ms 라
+ * 초 단위로는 같은 초 안의 순서를 가릴 수 없다).
+ */
+
+/** 두 자리·세 자리 0 채우기 — 형식이 흔들리면 정렬해 읽을 수 없다. */
+const p2 = (n: number) => String(n).padStart(2, '0')
+const p3 = (n: number) => String(n).padStart(3, '0')
+
+/**
+ * 지역 시각 + 오프셋 — `2026-08-22T05:54:12.345+09:00`.
+ *
+ * UTC 로 찍지 않는다: 이 로그를 읽는 사람은 현장의 시각으로 이야기하고, 프레임워크의 다른 줄도
+ * 지역 시각이다. 두 줄이 다른 기준이면 나란히 놓고 읽을 수 없다.
+ */
+export function stamp(at: Date = new Date()): string {
+  const off = -at.getTimezoneOffset()
+  const sign = off >= 0 ? '+' : '-'
+  const abs = Math.abs(off)
+  return (
+    `${at.getFullYear()}-${p2(at.getMonth() + 1)}-${p2(at.getDate())}` +
+    `T${p2(at.getHours())}:${p2(at.getMinutes())}:${p2(at.getSeconds())}.${p3(at.getMilliseconds())}` +
+    `${sign}${p2(Math.floor(abs / 60))}:${p2(abs % 60)}`
+  )
+}
+
+/**
+ * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**
+ *
+ * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는
+ * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.
+ * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
+ */
+export function line(args: unknown[]): string {
+  return args
+    .map(a => {
+      if (typeof a === 'string') return a
+      if (a instanceof Error) return a.stack ?? a.message
+      if (a === undefined) return 'undefined'
+      if (a === null) return 'null'
+      try {
+        return typeof a === 'object' ? JSON.stringify(a) : String(a)
+      } catch {
+        /* 순환 참조 등 — 값을 못 적어도 **무엇이 있었다는 사실**은 남긴다. */
+        return String(a)
+      }
+    })
+    .join(' ')
+}
+
+/* 수준 표기는 프레임워크와 같은 낱말을 쓴다(`info`·`warn`·`error`) — 같은 파일에서 걸러 읽는다. */
+export const twinLog = (...args: unknown[]): void => console.log(`${stamp()} info: ${line(args)}`)
+export const twinWarn = (...args: unknown[]): void => console.warn(`${stamp()} warn: ${line(args)}`)
+export const twinError = (...args: unknown[]): void => console.error(`${stamp()} error: ${line(args)}`)

package/server/engine/loop-lag.ts

@@ -0,0 +1,120 @@
+/*
+ * 이벤트 루프 지체 — **화면이 느린 이유를 지어내지 않기 위해.** 순수(import 없음).
+ *
+ * ── 왜 필요한가 (2026-08-21) ────────────────────────────────────────────────
+ * 「UI 반응성이 느리다」를 진단하려 했는데, 있는 계기판으로는 답이 나오지 않았다. `twinLoad` 는 **트윈의
+ * 계측된 작업**만 재고, `processCpuRatio` 는 프로세스 전체를 재지만 **언제 얼마나 멈췄나**를 말하지
+ * 못한다. 밖에서 HTTP 지연을 재 보니 같은 요청이 44ms 와 5.8초로 갈라졌는데, 그 5.8초가 트윈 때문인지
+ * webpack 재빌드 때문인지 남의 재기동 때문인지 **가릴 근거가 없었다.**
+ *
+ * 근거 없이 원인을 고르면 엉뚱한 곳을 고친다. 그래서 루프가 실제로 얼마나 막혔는지를 잰다.
+ *
+ * ── 어떻게 재나 ─────────────────────────────────────────────────────────────
+ * 일정 간격으로 깨어나는 타이머를 두고, **예정 시각과 실제 시각의 차이**를 본다. 루프가 막혀 있었으면
+ * 그만큼 늦게 깨어난다. 재는 비용은 그 차이 계산 하나뿐이다(창마다 값 다섯).
+ *
+ * 이 값은 **원인을 말하지 않는다** — 「200ms 이상 막힌 일이 이 창에서 세 번, 가장 긴 것은 4.6초」까지가
+ * 사실이다. 원인은 그 시각의 트윈 부하(`twinLoad`)와 프로세스 CPU 와 나란히 놓고 사람이 가린다.
+ * 재지 않은 것을 0 으로 적지 않는다 — 한 번도 깨어나지 않았으면 `null` 이다.
+ */
+
+/** 표본 간격(ms) — 촘촘할 필요가 없다. 긴 정체를 놓치지 않는 정도면 된다. */
+export const LAG_SAMPLE_MS = 500
+/** 이 값을 넘는 지체만 「정체」로 센다(ms). 사람이 화면에서 느끼기 시작하는 크기. */
+export const LAG_STALL_MS = 200
+/** 창 길이(ms) — `twinLoad` 의 창과 같은 크기로 두어 나란히 읽는다. */
+export const LAG_WINDOW_MS = 10_000
+
+export interface LoopLagWindow {
+  /** 이 창에서 가장 길게 막힌 시간(ms). */
+  maxMs: number
+  /** 정체(문턱 초과) 횟수. */
+  stalls: number
+  /** 표본 수 — 분모다. */
+  samples: number
+  /** 지체 합(ms) — 평균은 읽는 쪽에서 낸다. */
+  totalMs: number
+  /** 창이 열린 시각. */
+  startMs: number
+}
+
+export interface LoopLagView {
+  /** 마지막으로 닫힌 창 — 「지금 어떤가」. 아직 한 창도 안 지났으면 null. */
+  recent: (LoopLagWindow & { endMs: number }) | null
+  /** 기동 이후 누적. */
+  total: LoopLagWindow
+  /** 기동 이후 가장 길게 막힌 시각(ms, epoch) — 언제였는지가 원인을 가리는 데 쓰인다. */
+  worstAtMs: number | null
+  /** 표본 간격 — 읽는 쪽이 이 값보다 짧은 정체는 못 본다는 것을 알아야 한다. */
+  sampleMs: number
+  /** 정체로 세는 문턱. */
+  stallMs: number
+}
+
+const emptyWindow = (startMs: number): LoopLagWindow => ({ maxMs: 0, stalls: 0, samples: 0, totalMs: 0, startMs })
+
+export class LoopLagSampler {
+  private window: LoopLagWindow
+  private closed: (LoopLagWindow & { endMs: number }) | null = null
+  private total: LoopLagWindow
+  private worstAtMs: number | null = null
+  private timer: any
+  private expectedMs: number
+
+  private sampleMs: number
+  private stallMs: number
+  private windowMs: number
+  private now: () => number
+
+  /* 생성자 파라미터 프로퍼티(`private x = …`)는 쓰지 않는다 — 시험이 소스를 그대로 실행하는데
+     (타입 제거 실행 방식) 그 문법은 지원되지 않아 파일 전체가 열리지 않는다. */
+  constructor(sampleMs = LAG_SAMPLE_MS, stallMs = LAG_STALL_MS, windowMs = LAG_WINDOW_MS, now: () => number = Date.now) {
+    this.sampleMs = sampleMs
+    this.stallMs = stallMs
+    this.windowMs = windowMs
+    this.now = now
+    const t = this.now()
+    this.window = emptyWindow(t)
+    this.total = emptyWindow(t)
+    this.expectedMs = t + sampleMs
+  }
+
+  /** 표본을 하나 넣는다 — 타이머가 부르고, 시험은 직접 부른다(시계를 밀어 넣어 잰다). */
+  sample(atMs = this.now()): number {
+    const lag = Math.max(0, atMs - this.expectedMs)
+    this.expectedMs = atMs + this.sampleMs
+    for (const w of [this.window, this.total]) {
+      w.samples += 1
+      w.totalMs += lag
+      if (lag > this.stallMs) w.stalls += 1
+      if (lag > w.maxMs) w.maxMs = lag
+    }
+    if (lag >= this.total.maxMs && lag > this.stallMs) this.worstAtMs = atMs
+    if (atMs - this.window.startMs >= this.windowMs) {
+      this.closed = { ...this.window, endMs: atMs }
+      this.window = emptyWindow(atMs)
+    }
+    return lag
+  }
+
+  /** 계기판이 읽는 값. **한 창도 닫히지 않았으면 `recent` 는 null** — 채우는 중인 창은 과소 집계다. */
+  view(): LoopLagView {
+    return { recent: this.closed, total: this.total, worstAtMs: this.worstAtMs, sampleMs: this.sampleMs, stallMs: this.stallMs }
+  }
+
+  /** 표본 타이머 기동(1회) — 프로세스 종료를 막지 않는다. */
+  start(): void {
+    if (this.timer) return
+    this.timer = setInterval(() => this.sample(), this.sampleMs)
+    if (typeof this.timer?.unref === 'function') this.timer.unref()
+  }
+
+  stop(): void {
+    if (!this.timer) return
+    clearInterval(this.timer)
+    this.timer = undefined
+  }
+}
+
+/** 프로세스 하나의 루프를 재는 것이므로 표본기도 하나다. */
+export const loopLag = new LoopLagSampler()

package/server/engine/model-gap.ts

@@ -0,0 +1,168 @@
+/*
+ * **원본이 말한 적 없는 것** — 미해결 참조를 세는 한 자리. 순수(import 없음).
+ *
+ * ── 무엇을 답하나 ───────────────────────────────────────────────────────────
+ * 원천이 우리 모델에 없는 id 를 보내면 어떻게 되나. 유입 문(`ingestCanonicalRecords`)은 **거부하지
+ * 않는다** — 실측으로 확인했다(2026-08-20):
+ *
+ *   모르는 로케이션 「오타-99」        → 통과
+ *   모르는 bizStep 「PUTAWAY_X17」   → 통과
+ *   모르는 계량기 「MMXU-오타-99」    → 통과
+ *
+ * 거부하지 않는 것이 옳다. 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고(구조 갱신은 늦게 온다),
+ * 거부하면 그 선행 계측을 잃는다. 그래서 커널은 **흡수하고 표시한다** — 마스터에 없던 로케이션은
+ * `origin: 'observed'` 로 승격되어 스냅샷에 실린다(`ObservedReducer.touchLocation`).
+ *
+ * ── 왜 이 파일이 있나 ───────────────────────────────────────────────────────
+ * 그 표시를 읽는 곳이 **모델 인스펙션 화면 하나**였다. 그런데 이 사실을 필요로 하는 사람은 「이 트윈이
+ * 현장과 맞춰지고 있나」를 보는 사람이다 — 원천이 우리가 모르는 로케이션만 보내고 있으면 트윈은 도는데
+ * 스키매틱은 비어 있고, 그것이 우리가 「빈 공장」이라 불러 온 상태다.
+ *
+ * 도출을 두 곳에 적으면 두 화면이 다른 수를 말하게 된다. 그래서 여기 한 벌만 둔다.
+ *
+ * ── 판정을 바꾸지 않는다 ────────────────────────────────────────────────────
+ * 동기화 판정(`syncVerdictOf`)은 **피드**를 말한다: 오고 있나, 통과하나. 이 갭은 **모델**을 말한다:
+ * 원천이 아는 것을 우리가 선언했나. 둘을 한 판정에 섞으면 「유입은 정상인데 모델이 뒤처졌다」와
+ * 「유입이 막혔다」가 같은 색으로 보이고, 처방이 완전히 다르다.
+ */
+
+/** 커널 스냅샷에서 우리가 읽는 것만. 나머지 필드는 알 필요가 없다. */
+export interface ModelGapSource {
+  locations?: { id?: string; origin?: string }[]
+  equipment?: { id?: string; origin?: string }[]
+  persons?: { id?: string; origin?: string }[]
+  /** 커널이 담을 줄 몰라 세어 둔 사건 — 종류별 개수와 처음·마지막 시각. */
+  unhandled?: { eventType: string; count: number; firstAtMs?: number; lastAtMs?: number }[]
+  /**
+   * EMS 상태 — **`energy` 안에 있다.**
+   *
+   * `unknownEquipment` 를 루트에서 읽고 있었다(2026-08-20에 잡음). 커널은 그것을 `EnergyState` 안에
+   * 담으므로, 루트에서 읽으면 **영원히 `null`** 이다 — 오류도 없이 「에너지 트윈이 아니다」로 읽힌다.
+   * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 조용히 사라진다.
+   *
+   * 계량 지점의 `origin` 은 **없을 수 있다**(옛 스냅샷에서 이어받은 지점). 그때는 「선언되었다」가
+   * 아니라 **모른다**다.
+   */
+  energy?: {
+    points?: { id?: string; origin?: string }[]
+    /** 모델이 모르는 설비가 에너지 상태를 보내 온 횟수. 0 이면 커널이 이 칸을 만들지 않는다. */
+    unknownEquipment?: number
+  }
+}
+
+/**
+ * 화면에 내는 id 수 상한.
+ *
+ * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에
+ * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 조용히 자르지 않는다.
+ */
+export const GAP_ID_LIMIT = 20
+
+export interface ModelGapAxis {
+  /** 관측으로만 알게 된 id 수. */
+  count: number
+  /** 그중 화면에 싣는 것(최대 `GAP_ID_LIMIT`). */
+  ids: string[]
+  /** 상한에서 밀려난 수. 0 이면 전부 실었다. */
+  more: number
+  /**
+   * 출처를 **모르는** 수 — 표시가 없는 항목.
+   *
+   * 「선언되었다」로 세지 않는다. 계량기는 이 표시가 늦게 생겼으므로 옛 스냅샷에서 이어받은 지점에는
+   * 칸이 없다(`undefined`). 그것을 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다.
+   * 둘 다 틀리므로 **모른다고 센다.**
+   */
+  unknown: number
+}
+
+export interface ModelGapView {
+  locations: ModelGapAxis
+  equipment: ModelGapAxis
+  persons: ModelGapAxis
+  /**
+   * EMS 계량 지점.
+   *
+   * ── 이 축이 가장 무겁다 ────────────────────────────────────────────────────
+   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에
+   * 더해진다. 오타 하나면 진짜 계량기는 멈추고 유령이 누적된다 — 숫자는 그럴듯하고 틀린다. 자리 오타는
+   * 스키매틱이 비는 것으로 드러나지만, 이건 그럴듯한 숫자로 나온다.
+   *
+   * 커널이 `origin` 을 **표본마다 다시 맞춘다** — 선언의 정본은 모델이고 모델은 채택으로 늘어나므로,
+   * 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다. 그래서 이 값은 「지금 모델에
+   * 있는가」의 답이고, 「한 번 오타였다」의 답이 아니다.
+   */
+  meters: ModelGapAxis
+  /** 세 축의 합 — 화면이 「있나 없나」를 한 번에 묻기 위한 값. */
+  total: number
+  /** 커널이 담을 줄 모른 사건들(종류별). 참조 문제와 다른 사실이므로 따로 낸다. */
+  unhandled: { eventType: string; count: number; lastAt: string | null }[]
+  /** EMS: 모델이 모르는 설비의 에너지 보고 횟수. 없으면 `null`(0 과 구별한다). */
+  unknownEquipmentReports: number | null
+  /**
+   * 아직 덮지 못하는 축 — **모르는 것을 모른다고 말한다.**
+   *
+   * 계량기는 커널 0.7.39 부터 덮인다(그 전에는 `origin` 표시가 없어 오타를 찾아 줄 수 없었다).
+   * 비어 있는 것이 정상이고, 새 축이 표시 없이 들어오면 여기에 이름을 넣는다 — 화면이 「다 찾아
+   * 준다」고 말하지 않게.
+   */
+  notCovered: string[]
+}
+
+/** 계량기 축이 아직 덮이지 않는 이유 — 화면이 그대로 말할 수 있게 이름을 여기 둔다. */
+export const NOT_COVERED_METERS = 'meters'
+
+function axisOf(rows: { id?: string; origin?: string }[] | undefined): ModelGapAxis {
+  const ids: string[] = []
+  let count = 0
+  let unknown = 0
+  for (const r of rows ?? []) {
+    if (r?.origin === 'observed') {
+      count++
+      if (ids.length < GAP_ID_LIMIT) ids.push(String(r.id ?? ''))
+    } else if (r?.origin !== 'master') {
+      /* 표시가 없다 — 마스터로도 관측으로도 세지 않는다. 모르는 것은 모른다고 센다. */
+      unknown++
+    }
+  }
+  return { count, ids, more: Math.max(0, count - ids.length), unknown }
+}
+
+/**
+ * 스냅샷 → 모델 갭.
+ *
+ * 스냅샷이 없으면 `null` 이다 — **0 이 아니다.** 트윈이 돌지 않으면 비교할 상대가 없고, 「없다」와
+ * 「세어 보지 못했다」는 다른 사실이다(모델 인스펙션이 같은 규율을 쓴다).
+ */
+export function modelGapOf(snapshot: ModelGapSource | null | undefined): ModelGapView | null {
+  if (!snapshot) return null
+
+  const locations = axisOf(snapshot.locations)
+  const equipment = axisOf(snapshot.equipment)
+  const persons = axisOf(snapshot.persons)
+  const meters = axisOf(snapshot.energy?.points)
+
+  return {
+    locations,
+    equipment,
+    persons,
+    meters,
+    total: locations.count + equipment.count + persons.count + meters.count,
+    unhandled: (snapshot.unhandled ?? []).map(u => ({
+      eventType: u.eventType,
+      count: u.count,
+      /* 마지막 시각이 멈춘 종류는 이미 고쳐진 것이다. 없으면 지어내지 않는다. */
+      lastAt: Number.isFinite(u.lastAtMs) ? new Date(u.lastAtMs as number).toISOString() : null
+    })),
+    /*
+     * 커널은 0 이면 이 칸을 만들지 않는다. 그래서 「없음」은 두 뜻이다 — 에너지 트윈이 아니거나, 세었고
+     * 0 이었다. 둘을 가르려면 `energy` 자체가 있는지를 본다: 있으면 세었고 0 이다.
+     */
+    unknownEquipmentReports:
+      typeof snapshot.energy?.unknownEquipment === 'number' ? snapshot.energy.unknownEquipment : snapshot.energy ? 0 : null,
+    /*
+     * 이제 계량기도 덮는다(커널 0.7.39 가 `MeterPointState.origin` 을 낸다). 덮지 못하는 축이 생기면
+     * 다시 여기에 이름을 넣는다 — 화면이 「다 찾아 준다」고 말하지 않게.
+     */
+    notCovered: []
+  }
+}

package/server/engine/restart-policy.ts

@@ -18,7 +18,7 @@
  * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────
  * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
  * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에
- * 이력이 사라진다. 그래서 모르는 값은 **던진다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
+ * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
  */
 
 /** 재기동 정책 — 셋뿐이다. */
@@ -27,11 +27,11 @@ export type RestartPolicy = 'resync' | 'resume' | 'reset'
 export const RESTART_POLICIES: readonly RestartPolicy[] = ['resync', 'resume', 'reset'] as const
 
 /**
- * 저장된 값을 정책으로 읽는다 — **모르면 던진다**(기본값으로 메우지 않는다).
+ * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).
  *
  * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,
  * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.
- * 그래서 이 함수는 옛 값에 대해서도 던지며, 무엇으로 옮겨야 하는지 문장으로 말한다.
+ * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.
  */
 export function readRestartPolicy(raw: unknown, where: string): RestartPolicy {
   const value = typeof raw === 'string' ? raw.trim() : ''
@@ -49,7 +49,7 @@ export function readRestartPolicy(raw: unknown, where: string): RestartPolicy {
   )
 }
 
-/** 이 값이 정책인가 — 던지지 않고 묻는 자리(화면·검사)를 위해. */
+/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */
 export function isRestartPolicy(raw: unknown): raw is RestartPolicy {
   return typeof raw === 'string' && (RESTART_POLICIES as readonly string[]).includes(raw)
 }

package/server/engine/runtime-key.ts

@@ -25,7 +25,7 @@
  * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
  * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
  * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
- * **그때는 던진다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
+ * **그때는 오류를 낸다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
  */
 
 /** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */