@things-factory/headless-twin 10.0.13 → 10.0.15

package/server/engine/ingest-health.ts

@@ -148,6 +148,56 @@ export interface IngestLedger {
     /** 어느 흐름에서 났나(어댑터가 말해 주면). 원본마다 흐름이 다르므로 열려 있다. */
     stream?: string
   }
+  /**
+   * **읽었는데 창을 넘길 수 없다** (2026-08-24) — 위와 **다른 사실**이다.
+   *
+   * ── 왜 갈랐나 ───────────────────────────────────────────────────────────────
+   * 이 칸을 만들기 전에는 두 사실이 같은 이름으로 나갔다.
+   *
+   *   readFailure   원본에 닿지 못했다        → **기다리면 풀린다**
+   *   cursorStall   읽었는데 커서가 못 넘어간다 → **기다려도 안 풀린다**
+   *
+   * 둘째는 읽기가 성공한 실패다: 한 시각에 한 페이지보다 많은 행이 몰려 커서를 그 시각 밖으로 옮길 수
+   * 없다. 화면이 「원본에 닿지 못한다」고 말하면 사람은 원본을 의심하고 기다리는데, 필요한 조치는
+   * 페이지를 키우거나 같은 시각 안에서 순서를 정하는 것이다. **조치가 반대인 두 사실을 한 이름으로
+   * 부르면 그 이름은 정보가 아니라 오해다.**
+   *
+   * 모양은 위와 같게 둔다 — 「몇 번」과 「언제부터」가 여기서도 같은 값을 한다(한 번의 밀림과 사흘째
+   * 못 넘어가는 것은 다르다). 넘어가면 지운다.
+   */
+  /**
+   * **원본이 말했는데 트윈에 세우지 않은 것** — 이유별로 센다.
+   *
+   * ── 왜 이 자리가 필요한가 (2026-08-24) ─────────────────────────────────────
+   * 커넥터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**: 입자가 맞지 않거나, 받으면 상태가
+   * 거짓이 되거나, 커널 어휘로 옮길 수 없다. 그때 커넥터는 경고를 낸다 — **그런데 그 경고가 프로비저닝
+   * 화면에서 한 번 스쳐 지나갈 뿐이었다.** 그 뒤로는 어디에서도 볼 수 없었다.
+   *
+   * 그래서 사용자가 「원본보다 계획이 적다」를 물으면 **답이 어디에도 없다.** 그 사실은 한 번의
+   * 사건이 아니라 **상태의 성질**이다 — 세우지 않은 것은 지금도 트윈에 없다.
+   *
+   * ── `unhandled` 의 형제다 ──────────────────────────────────────────────────
+   *   `unhandled`   리듀서가 **받았는데** 담을 자리를 몰랐다
+   *   여기          커넥터가 **보지만 일부러 보내지 않았다** — 이유와 함께
+   *
+   * 둘 다 「사실이 조용히 사라지지 않게」 세는 것이고, 이유가 다르므로 자리도 다르다.
+   *
+   * 이유를 **문자열로 받는다**: 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 그 목록을 닫으면 새 원본을
+   * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율).
+   */
+  withheld?: { reason: string; count: number; lastAtMs: number }[]
+  cursorStall?: {
+    /** 연속 정체 수 — 넘어가면 0 으로 돌아간다. */
+    consecutive: number
+    /** 이 정체가 **처음** 시작된 시각(ms). */
+    sinceMs: number
+    /** 마지막 정체 시각(ms). */
+    lastAtMs: number
+    /** 사유 — 사람이 읽는 한 줄(어느 시각에서 막혔나까지 어댑터가 말해 주면 좋다). */
+    reason: string
+    /** 어느 흐름인가. 밀도가 높은 표는 원본마다 다르므로 이 이름이 조치의 절반이다. */
+    stream?: string
+  }
 }
 
 /**
@@ -182,6 +232,50 @@ export function clearReadFailure(ledger: IngestLedger): void {
   if (ledger.readFailure) delete ledger.readFailure
 }
 
+/**
+ * 커서 정체를 장부에 적는다 — **닿지 못한 것과 가른다.**
+ *
+ * `recordReadFailure` 와 같은 모양이지만 **다른 칸**이다. 한 주기가 두 이유로 실패할 수는 없으므로
+ * (먼저 닿아야 읽는다) 둘이 동시에 서지 않는다 — 그래서 화면은 둘 중 하나만 보게 되고, 그 하나가
+ * 조치를 정한다.
+ */
+export function recordCursorStall(ledger: IngestLedger, reason: string, nowMs: number, stream?: string): void {
+  const prev = ledger.cursorStall
+  ledger.cursorStall = {
+    consecutive: (prev?.consecutive ?? 0) + 1,
+    sinceMs: prev?.sinceMs ?? nowMs,
+    lastAtMs: nowMs,
+    reason,
+    ...(stream ? { stream } : {})
+  }
+}
+
+/**
+ * **세우지 않은 것을 적는다** — 이유별 누적.
+ *
+ * 주기마다 다시 알려도 시끄러워지지 않게 **이유로 묶어 센다**(줄이 늘지 않는다). 그리고 마지막 시각을
+ * 함께 든다 — 「지금도 그런가」와 「한때 그랬나」는 다른 사실이고, 시각 없이는 구별할 수 없다.
+ *
+ * 이유가 같고 수가 달라지면 **마지막 수로 덮는다**: 이것은 누적 사건이 아니라 **지금 세우지 않은 것의
+ * 수**다. 주기마다 8건이면 8이고, 더해서 800이 되면 거짓이다.
+ */
+export function recordWithheld(ledger: IngestLedger, reason: string, count: number, nowMs: number): void {
+  if (!reason || !(count > 0)) return
+  const list = (ledger.withheld ??= [])
+  const at = list.find(w => w.reason === reason)
+  if (at) {
+    at.count = count
+    at.lastAtMs = nowMs
+    return
+  }
+  list.push({ reason, count, lastAtMs: nowMs })
+}
+
+/** 창을 넘겼으면 지운다 — 풀린 정체가 화면에 남아 있으면 그것도 거짓이다. */
+export function clearCursorStall(ledger: IngestLedger): void {
+  if (ledger.cursorStall) delete ledger.cursorStall
+}
+
 /** 창 길이 — 10분. 부하 계기판(10초)과 다른 값이라 이름을 따로 둔다(같은 이름이면 섞인다). */
 export const INGEST_WINDOW_MS = 600_000
 
@@ -562,6 +656,8 @@ export interface IngestHealthView {
   /**
    * **원본에 닿지 못하고 있다** — 없으면 닿고 있다는 뜻이다(§`IngestLedger.readFailure`).
    *
+   * 커서 정체(`cursorStall`)와 **섞이지 않는다**: 이쪽은 기다리면 풀리고 그쪽은 기다려도 안 풀린다.
+   *
    * 「유입 없음」과 **다른 판정**이다: 유입 없음은 원본이 조용한 것일 수 있고, 이것은 우리가 묻지도
    * 못한 것이다. 화면은 두 문장을 다르게 말해야 한다 — 실 원본이 끊겼을 때 사용자가 원인을 찾을 수
    * 있는지가 그 차이다.
@@ -655,6 +751,32 @@ export function ingestHealth(
               ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {})
             }
           }
+        : {}),
+      /* 커서 정체도 **이 갈래에서** 내보낸다 — 유입이 없는 장부에서도 정체는 실재한다(읽었으나 못
+         넘겼으면 유입이 0이다). 여기서 떨어뜨리면 바로 그 상황에서 조용해진다. */
+      ...(ledger?.cursorStall
+        ? {
+            cursorStall: {
+              consecutive: ledger.cursorStall.consecutive,
+              since: new Date(ledger.cursorStall.sinceMs).toISOString(),
+              lastAt: new Date(ledger.cursorStall.lastAtMs).toISOString(),
+              reason: ledger.cursorStall.reason,
+              ...(ledger.cursorStall.stream ? { stream: ledger.cursorStall.stream } : {})
+            }
+          }
+        : {}),
+      /*
+       * **세우지 않은 것도 낸다 — 양쪽 갈래에서.** 유입이 한 건도 없는 장부에서도 이 사실은 실재한다
+       * (원본이 말하는데 전부 안 받는 경우가 있다). 여기서 떨어뜨리면 바로 그 상황에서 조용해진다.
+       */
+      ...(ledger?.withheld?.length
+        ? {
+            withheld: ledger.withheld.map(w => ({
+              reason: w.reason,
+              count: w.count,
+              lastAt: new Date(w.lastAtMs).toISOString()
+            }))
+          }
         : {})
     }
   }
@@ -667,6 +789,16 @@ export function ingestHealth(
     recent: recentRaw ? toWindowView(recentRaw, lastAnyMs) : null,
     trend: ledger.trend.map(w => toWindowView(w, lastAnyMs)),
     trendDropped: ledger.trendDropped,
+    /* 세우지 않은 것 — 양쪽 갈래에서 같은 모양으로 낸다(§`IngestLedger.withheld`). */
+    ...(ledger.withheld?.length
+      ? {
+          withheld: ledger.withheld.map(w => ({
+            reason: w.reason,
+            count: w.count,
+            lastAt: new Date(w.lastAtMs).toISOString()
+          }))
+        }
+      : {}),
     total: {
       offered: ledger.offered,
       accepted,
@@ -696,6 +828,17 @@ export function ingestHealth(
             ...(ledger.readFailure.stream ? { stream: ledger.readFailure.stream } : {})
           }
         }
+      : {}),
+    ...(ledger.cursorStall
+      ? {
+          cursorStall: {
+            consecutive: ledger.cursorStall.consecutive,
+            since: new Date(ledger.cursorStall.sinceMs).toISOString(),
+            lastAt: new Date(ledger.cursorStall.lastAtMs).toISOString(),
+            reason: ledger.cursorStall.reason,
+            ...(ledger.cursorStall.stream ? { stream: ledger.cursorStall.stream } : {})
+          }
+        }
       : {})
   }
 }

package/server/engine/twin-engine.ts

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

package/server/service/reference/reference-adapter.ts

@@ -154,6 +154,51 @@ export interface LiveFeedContinuity {
    * 로 알린다. 그 둘을 섞으면 조용한 원본이 끊긴 원본으로 보인다(고치려던 것의 반대 방향으로 틀린다).
    */
   onReadFailure?: (info: { reason: string; stream?: string }) => void
+  /**
+   * **읽었는데 창을 넘길 수 없다** — 어댑터가 커서 정체를 알린다 (2026-08-24).
+   *
+   * ── 왜 `onReadFailure` 와 갈라야 하나 ───────────────────────────────────────
+   * 이 문을 만들기 전에는 두 사실이 **같은 이름으로** 나갔다.
+   *
+   *   원본에 닿지 못했다        접속 실패·시간 초과·형식 오류 → 기다리면 풀린다
+   *   읽었는데 커서가 못 넘어간다  한 시각에 한 페이지보다 많은 행이 몰려 있다 → **기다려도 안 풀린다**
+   *
+   * 둘째는 **읽기가 성공한 실패**다. 원본은 답했고, 그 답의 모양이 커서를 이긴 것이다. 그런데 화면이
+   * 「원본에 닿지 못한다」고 말하면 사람을 반대 방향으로 보낸다 — 원본을 의심하고 기다린다. 실제로
+   * 필요한 조치는 **페이지를 키우거나 같은 시각 안에서 순서를 정하는 것**이고, 기다림으로는 영원히
+   * 풀리지 않는다.
+   *
+   * 조치가 반대인 두 사실을 한 이름으로 부르면, 그 이름은 정보가 아니라 오해다.
+   *
+   * ── 무엇을 알리나 ───────────────────────────────────────────────────────────
+   * 그 주기를 포기했을 때 부른다(`onReadFailure` 와 같은 규율). 어느 흐름인지 알면 함께 준다 —
+   * 밀도가 높은 표는 원본마다 다르므로 그 이름이 조치의 절반이다.
+   *
+   * **닿지 못한 것과 섞어 부르지 않는다.** 하나의 주기가 두 이유로 실패할 수는 없다(먼저 닿아야 읽는다).
+   */
+  onCursorStall?: (info: { reason: string; stream?: string }) => void
+  /**
+   * **원본에 있는데 세우지 않은 것을 알린다** — 이유와 수.
+   *
+   * ── 왜 이 통로가 필요한가 (2026-08-24) ─────────────────────────────────────
+   * 어댑터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**(입자가 안 맞는다 · 받으면 상태가
+   * 거짓이 된다 · 커널 어휘로 옮길 수 없다). 그때 어댑터는 경고를 냈는데, 그 경고가 **프로비저닝
+   * 화면에서 한 번 스쳐 지나갈 뿐**이었다 — 그 뒤로는 어디에서도 볼 수 없었다.
+   *
+   * 그래서 사용자가 「원본보다 이것이 적다」를 물으면 답이 어디에도 없었다. 그 사실은 한 번의 사건이
+   * 아니라 **상태의 성질**이다: 세우지 않은 것은 **지금도** 트윈에 없다.
+   *
+   * **주기마다 불러도 된다** — 장부가 이유로 묶어 세고 마지막 수로 덮는다(누적하지 않는다). 그래서
+   * 「지금 세우지 않은 것이 8건」이 8로 남고 800으로 부풀지 않는다.
+   *
+   * **풀리면 부르지 않는 것으로 끝나지 않는다** — 이유가 사라졌으면 `count: 0` 으로 부르는 것이 아니라
+   * 그 이유를 더 이상 보내지 않으면 된다… 가 **아니다.** 장부는 마지막 값을 들고 있으므로, 풀린 것을
+   * 알리려면 그 이유로 `count: 0` 을 한 번 보내라(그때 줄이 사라진다). 조용히 그치면 낡은 수가 남는다.
+   *
+   * 이유는 **자유 문자열**이다 — 무엇을 왜 안 받는지는 원본마다 다르고, 계약이 목록을 닫으면 새 원본을
+   * 붙일 때마다 계약을 고치게 된다(흐름 열쇠와 같은 규율). 사람이 읽을 문장으로 적어라.
+   */
+  onWithheld?: (info: { reason: string; count: number }) => void
 }
 
 export interface ReferenceAdapter {

package/server/service/reference/reference-assessment.ts

@@ -18,7 +18,7 @@ import type { IngestWarning, ReferenceMaster } from './reference-master.js'
  * 그래서 사실 층이 스스로 완결이다.
  *
  * ── 무엇을 지어내지 않는가 ──────────────────────────────────────────────────
- * 「없음」의 뜻을 셋으로 갈라 둔다. 뭉치면 조치가 달라지는 것들이 한 칸에 섞인다.
+ * 「없음」의 뜻을 셋으로 구분해 둔다. 뭉치면 조치가 달라지는 것들이 한 칸에 섞인다.
  *  · `gaps` — 원본에 있는데 우리가 옮기지 못했다. 고칠 대상이 있다(원본의 빈 칸이거나 우리 매핑).
  *  · `absent` — 이 원본에 그 **개념이 없다.** 빠진 것이 아니므로 고칠 것이 없다.
  *  · `grounding` — 값이 들어왔지만 **근거가 저장된 값이 아니다**(원본의 계산 규칙에서 왔다).
@@ -40,6 +40,16 @@ export interface AssessmentCounts {
   /** 공정을 말하는 투입 / 전체 투입 — 공정별 소요를 아는 정도. */
   taggedInputs?: number
   totalInputs?: number
+  /** 시험 명세(점검표)의 수 — 선언되지 않았으면 없다(0 과 구별한다). */
+  testSpecifications?: number
+  /** 그 명세들이 선언한 판정 기준의 수. */
+  criteria?: number
+  /**
+   * 그중 **아무 한계도 말하지 않는** 기준의 수 — 커널의 `criterionSaysNothing` 과 같은 판정이다.
+   *
+   * 이 수가 0 이 아니면 「관리점이 있다」가 「판정된다」를 뜻하지 않는다. 세지 않으면 그 구별이 사라진다.
+   */
+  criteriaWithoutLimit?: number
 }
 
 /** 옮기지 못한 것 한 갈래 — 건수 큰 것부터. */
@@ -65,7 +75,7 @@ export interface ImportAssessment {
    * 이름을 `origin` 이라 하지 않는다 — 화면에서 그 낱말이 이미 **트윈의 출처**(`summary.origin`:
    * 템플릿인가 원본인가)를 뜻한다. 같은 이름을 두 뜻으로 쓰면 읽는 사람이 헷갈린다.
    *
-   * `built` 와 견주어 「전부 옮겼는가」를 사람이 직접 셀 수 있게 한다. 커넥터가 말하지 않으면 이 자리는
+   * `built` 와 비교해 「전부 옮겼는가」를 사람이 직접 셀 수 있게 한다. 커넥터가 말하지 않으면 이 자리는
    * 비어 있고, 화면은 분모 없이 옮긴 수만 보인다 — **분모를 지어내지 않는다.**
    */
   originCounts?: Record<string, number>
@@ -84,7 +94,7 @@ export interface ImportAssessment {
   notes: IngestWarning[]
 }
 
-/** 이 마스터가 개념을 선언했나 — 「없다」와 「비어 있다」를 가른다. */
+/** 이 마스터가 개념을 선언했나 — 「없다」와 「비어 있다」를 구분한다. */
 const declared = (v: unknown): boolean => Array.isArray(v) ? v.length > 0 : v !== undefined && v !== null
 
 /**
@@ -105,6 +115,21 @@ export function assessMaster(master: ReferenceMaster, siteId: string): ImportAss
     equipment: (m.equipment ?? []).length,
     materialDefinitions: (m.materialDefinitions ?? []).length,
     operations: (m.operations ?? []).length,
+    ...(declared(m.testSpecifications)
+      ? {
+          testSpecifications: m.testSpecifications!.length,
+          criteria: m.testSpecifications!.reduce((n, t) => n + (t.criteria?.length ?? 0), 0),
+          /*
+           * **한계를 말하지 않는 기준** — 커널의 `criterionSaysNothing` 과 같은 판정이다. 기준이
+           * 선언됐다는 사실만 있고 판정할 재료가 없는 자리이고, 그것을 세지 않으면 「관리점이 있다」가
+           * 「판정된다」로 읽힌다.
+           */
+          criteriaWithoutLimit: m.testSpecifications!.reduce(
+            (n, t) => n + (t.criteria ?? []).filter(c => !c.expression && c.limit?.minimum === undefined && c.limit?.maximum === undefined).length,
+            0
+          )
+        }
+      : {}),
     ...(d
       ? {
           materials: (d.materials ?? []).length,
@@ -126,7 +151,7 @@ export function assessMaster(master: ReferenceMaster, siteId: string): ImportAss
   const notes: IngestWarning[] = []
   /*
    * 커넥터가 「대체」 수집기로 남기는 것 중 일부는 **빈 자리가 아니라 파생된 값**이다(산출량이 원본의
-   * 계산 규칙에서 온 경우처럼). 같은 통로로 오지만 뜻이 달라 갈라 담는다 — 이름에 그 사실이 적혀 있다.
+   * 계산 규칙에서 온 경우처럼). 같은 통로로 오지만 뜻이 달라 구분해 담는다 — 이름에 그 사실이 적혀 있다.
    */
   const isDerived = (field: string) => /derived|not a stored field/i.test(field)
   for (const w of m.warnings ?? []) {
@@ -209,6 +234,16 @@ export function formatAssessment(a: ImportAssessment): string {
     out.push('  파생된 값(저장된 값이 아니다):')
     for (const g of a.derived) out.push(`    ${g.what}${g.sample ? ` — ${g.sample}` : ''}`)
   }
+  if (c.testSpecifications) {
+    /*
+     * 관리 기준은 계측이 오는지와 무관하게 값이 있다 — 「관리점이 셋인데 둘은 아무 한계도 말하지
+     * 않는다」를 여기서 볼 수 있어야 판정에 근거가 있는지 사람이 안다.
+     */
+    out.push(
+      `  관리 기준: 점검표 ${n('testSpecifications', c.testSpecifications)} · 기준 ${c.criteria ?? 0}` +
+        (c.criteriaWithoutLimit ? ` (한계를 말하지 않는 것 ${c.criteriaWithoutLimit})` : '')
+    )
+  }
   if (a.absent.length) out.push(`  이 원본에 개념이 없는 자리: ${a.absent.join(', ')}`)
   for (const n of a.notes) out.push(`  참고 ${n.code}: ${n.message}`)
   return out.join('\n')

package/server/service/reference/reference-live.ts

@@ -164,6 +164,38 @@ async function loadLiveCursor(
         .update({ id: row.id }, { lastError: `live: ${reason}` } as any)
         .catch(err => twinWarn(`[twin-live] "${source}": read failure not recorded — ${err?.message ?? err}`))
     },
+    /**
+     * **읽었는데 창을 넘길 수 없다** — 위와 조치가 반대인 사실이다 (2026-08-24).
+     *
+     * 이 문을 만들기 전에는 이 사실이 `onReadFailure` 로 나갔다. 그래서 화면이 「원본에 닿지 못한다」고
+     * 말했는데 실제로는 원본이 **답한** 상태였고, 그 답의 모양이 커서를 이긴 것이었다. 사람은 원본을
+     * 의심하고 기다리는데 기다림으로는 영원히 풀리지 않는다 — **원인을 반대 방향으로 가리켰다.**
+     *
+     * `status` 를 건드리지 않는 규율은 위와 같다(재부착의 자격이다). `lastError` 에는 적는다 — 목록에서
+     * 이유를 볼 수 있어야 하고, 「닿지 못한다」와 다른 문장이어야 한다.
+     */
+    /*
+     * **세우지 않은 것을 장부에 적는다** — 원본에 있는데 트윈에 세우지 않은 것(이유와 수).
+     *
+     * 로그로도 남기지만 **로그는 사람이 볼 때만 값이 있다.** 이 사실은 상태의 성질이라(세우지 않은 것은
+     * 지금도 없다) 조회되는 자리에 있어야 한다 — 그러지 않으면 프로비저닝 화면에서 한 번 스쳐 지나간다.
+     *
+     * `status`·`lastError` 를 건드리지 않는다: 이것은 **실패가 아니다.** 어댑터가 옳은 판단으로 안 받은
+     * 것이고, 오류로 적으면 화면이 원본을 의심하게 만든다.
+     */
+    onWithheld: ({ reason, count }) => {
+      TwinEngine.recordIngestWithheld(domainId, instanceId, reason, count)
+    },
+    onCursorStall: ({ reason, stream }) => {
+      TwinEngine.recordIngestCursorStall(domainId, instanceId, reason, Date.now(), stream)
+      twinWarn(
+        `[twin-live] "${source}": read the source but the cursor cannot advance` +
+          `${stream ? ` (${stream})` : ''} — ${reason}. Waiting will not clear this.`
+      )
+      repo
+        .update({ id: row.id }, { lastError: `live cursor stalled: ${reason}` } as any)
+        .catch(err => twinWarn(`[twin-live] "${source}": cursor stall not recorded — ${err?.message ?? err}`))
+    },
     onCursor: next => {
       /* 어댑터가 준 모양을 그대로 적는다 — 이 층은 흐름의 뜻을 모른다(열쇠는 어댑터가 정한다). */
       repo