@things-factory/headless-twin 10.0.12 → 10.0.13

package/server/service/twin-ingest-window/twin-ingest-window-query.ts

@@ -0,0 +1,125 @@
+import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
+import { Between } from 'typeorm'
+
+import { ScalarObject, getRepository } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+import { TwinIngestWindow } from './twin-ingest-window.js'
+
+/*
+ * 인제스트 창 **이력** — 재기동 뒤에도 추이를 이어 본다.
+ *
+ * ── 왜 따로 있나 (2026-08-20) ───────────────────────────────────────────────
+ * 창을 표로 남기기 시작했는데 **읽는 코드가 없었다.** 21행이 쌓여 있고 아무도 보지 않았다 — 이
+ * 프로젝트가 결함으로 보는 상태다(「필드만 만들고 아무도 읽지 않는다」). 표를 만든 이유가 「메모리
+ * 장부는 재기동에 사라지고 6시간까지인데 추이는 그보다 오래 봐야 한다」였으니, 목적이 미완이었다.
+ *
+ * ── 왜 `twinIngestHealth` 에 합치지 않나 ────────────────────────────────────
+ * 그 조회는 **화면이 자주 묻는다**(상세를 열 때마다, 목록은 응답에 요약이 함께 온다). 거기에 DB 주사를
+ * 얹으면 이 세션에서 없앤 것과 같은 종류의 비용이 돌아온다 — 자주 묻는 조회가 자라는 표를 읽는 것.
+ * 이력은 **다른 질문**이고 덜 자주 묻는다: 「더 뒤까지 보여 달라」.
+ *
+ * ── 이어 붙이기는 서버가 한다 ───────────────────────────────────────────────
+ * 표와 메모리는 겹친다(프로세스가 살아 있는 동안 닫힌 창은 둘 다에 있다). 겹침을 화면이 정리하게 두면
+ * 화면마다 규칙이 갈리고, 같은 구간이 두 번 그려지거나 사라진다. 그래서 여기서 한 벌로 이어 붙이고
+ * **어디서부터 메모리인지**(`liveFrom`)를 함께 낸다 — 화면이 근거를 말할 수 있게.
+ */
+
+/**
+ * 한 번에 돌려주는 창 수 상한 — 144창 × 10분 = 24시간.
+ *
+ * 상한이 필요한 이유는 이 표가 **자란다**는 것이다(트윈 1,000개에 하루 14.4만 행). 상한에서 밀려난
+ * 수는 **세어서 낸다** — 조용히 자르면 화면이 「그 앞에는 아무 일도 없었다」로 읽는다.
+ */
+export const HISTORY_WINDOW_LIMIT = 144
+
+/** 물을 수 있는 기간의 상한(시간). 넘겨도 여기서 자르고, 자른 사실을 낸다. */
+export const HISTORY_HOURS_MAX = 168
+
+@Resolver()
+export class TwinIngestWindowQuery {
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description:
+      'Ingest windows for one twin over a past span, stitched from two sources so the trend survives a restart: closed windows persisted in the table (older) and the in-memory ledger (recent, roughly the last 6 hours). Overlap is resolved here rather than on screen — a window present in both is reported once, from memory, and `liveFrom` says where memory takes over so a screen can state its basis. Each window carries offered / accepted / rejected / undelivered plus the journal rows written and the write round-trips behind them; `acceptedRatio` is null when nothing was offered, because an empty window is not a perfect one. Deliberately separate from twinIngestHealth: that query is polled whenever a screen opens, and making it scan a growing table would reintroduce the cost this codebase just removed elsewhere. Counts that could not be returned are reported rather than dropped — `storedDropped` when the row cap was hit and `hoursClamped` when the requested span was longer than allowed. Null if the instance is not in the current domain.'
+  })
+  async twinIngestHistory(
+    @Arg('instanceId') instanceId: string,
+    @Arg('hours', type => Int, { nullable: true, description: 'How far back to read, in hours. Defaults to 24 and is clamped to 168.' })
+    hours: number | undefined,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    /* 테넌트 격리 — 멈춘 트윈의 이력도 볼 수 있어야 한다(그때가 가장 보고 싶은 때다). */
+    if (!TwinEngine.owns(domainId, instanceId) && !(await TwinEngine.ownsRegistered(domainId, instanceId))) return null
+
+    const asked = Number.isFinite(Number(hours)) && Number(hours) > 0 ? Math.floor(Number(hours)) : 24
+    const span = Math.min(asked, HISTORY_HOURS_MAX)
+    const now = Date.now()
+    const fromMs = now - span * 3_600_000
+
+    /*
+     * 표에서 그 구간의 닫힌 창을 읽는다. **상한을 둔다** — 자라는 표이고, 이 조회가 화면에서 열린다.
+     * 최신 쪽이 중요하므로 내려서 정렬해 가져오고, 낼 때 다시 올린다.
+     */
+    const repo = getRepository(TwinIngestWindow)
+    const where = {
+      domain: { id: domainId } as any,
+      instanceId,
+      closedAt: Between(new Date(fromMs), new Date(now))
+    }
+    const rows = await repo.find({ where, order: { closedAt: 'DESC' }, take: HISTORY_WINDOW_LIMIT })
+
+    /*
+     * 상한에 닿았으면 **몇 개가 밀렸는지 센다.** 「더 있음」만 말하면 화면이 그 앞을 짐작하게 된다.
+     * 상한에 닿지 않았으면 셀 필요가 없다(왕복을 아낀다).
+     */
+    const storedDropped = rows.length === HISTORY_WINDOW_LIMIT ? Math.max(0, (await repo.count({ where })) - rows.length) : 0
+
+    const stored = rows.reverse().map(r => ({
+      from: r.openedAt?.toISOString?.() ?? new Date(r.openedAt as any).toISOString(),
+      to: r.closedAt?.toISOString?.() ?? new Date(r.closedAt as any).toISOString(),
+      offered: r.offered,
+      /* 통과는 **트윈에 닿은** 것만. 표의 값을 그대로 쓴다 — 읽는 쪽에서 다시 나누면 반올림이 갈린다. */
+      accepted: r.offered - r.rejected - (r.undelivered ?? 0),
+      rejected: r.rejected,
+      undelivered: r.undelivered ?? 0,
+      acceptedRatio: typeof r.acceptedRatio === 'number' ? r.acceptedRatio : null,
+      rows: r.journaledRows ?? 0,
+      flushes: r.journalFlushes ?? 0,
+      source: 'stored' as const
+    }))
+
+    /* 메모리 장부의 닫힌 창 — 이쪽이 최신이고, 겹치는 구간은 이쪽을 쓴다(같은 사실의 원본이다). */
+    const live = (TwinEngine.ingestHealthOf(domainId, instanceId).trend ?? []).map((w: any) => ({
+      ...w,
+      source: 'live' as const
+    }))
+
+    /*
+     * 겹침 정리 — 창의 **여는 시각**이 키다. 같은 창이 표와 메모리에 둘 다 있으면 하나만 낸다.
+     * 시각 문자열을 그대로 키로 쓰지 않는다: 드라이버가 밀리초를 자르거나 형식을 바꿀 수 있어
+     * 같은 창이 다른 키가 된다. epoch 로 견준다.
+     */
+    const liveStarts = new Set(live.map((w: any) => Date.parse(w.from)))
+    const windows = [...stored.filter(w => !liveStarts.has(Date.parse(w.from))), ...live]
+
+    return {
+      windows,
+      hours: span,
+      /* 물은 것보다 짧게 잘렸으면 밝힌다. */
+      ...(span < asked ? { hoursClamped: asked } : {}),
+      from: new Date(fromMs).toISOString(),
+      to: new Date(now).toISOString(),
+      /** 표에서 읽은 창 수 · 상한에서 밀려난 수. */
+      storedCount: stored.length,
+      storedDropped,
+      /**
+       * 어디서부터 메모리인가 — 화면이 근거를 말할 수 있게. 메모리에 닫힌 창이 없으면 `null` 이다
+       * (재기동 직후가 그렇다: 그때 보이는 것은 전부 표에서 온 것이다).
+       */
+      liveFrom: live.length ? live[0].from : null,
+      liveCount: live.length
+    }
+  }
+}

package/server/service/twin-ingest-window/twin-ingest-window-writer.ts

@@ -0,0 +1,57 @@
+import { twinWarn } from '../../engine/log.js'
+import { getRepository } from '@things-factory/shell'
+
+import { TwinEngine } from '../../engine/index.js'
+import { TwinIngestWindow } from './twin-ingest-window.js'
+
+/*
+ * 닫힌 창을 표로 옮긴다 — **영속이 붙는 유일한 자리.**
+ *
+ * 커널 층(`engine/ingest-health.ts`)은 저장 계층을 모른다. 창이 닫힐 때 부를 곳을 엔진이 문으로 열어
+ * 두었고(`onIngestWindowClosed`), 이 파일이 부팅에서 한 번 등록한다. 그래서 기록 경로가 갈리지 않는다.
+ *
+ * ── 실패를 삼키지 않는다 ────────────────────────────────────────────────────
+ * 쓰기가 터져도 메모리 장부는 계속 굴러간다(`rollIngestWindow` 가 훅을 감싼다). 다만 **조용히 넘기지는
+ * 않는다** — 실패를 로그로 남긴다. 그러지 않으면 추이 표에 구멍이 생긴 이유를 나중에 알 수 없다.
+ *
+ * ── 왜 await 하지 않나 ──────────────────────────────────────────────────────
+ * 이 훅은 인제스트 경로에서 불린다(라이브 피드의 콜백 안). 여기서 DB 를 기다리면 **유입이 DB 속도에
+ * 묶인다** — 이 기능이 막으려던 부하가 그 모양으로 돌아온다. 그래서 띄워 보내고 결과만 로그로 받는다.
+ */
+export function installIngestWindowWriter(): void {
+  TwinEngine.onIngestWindowClosed((at, closed) => {
+    const repo = getRepository(TwinIngestWindow)
+    const offered = closed.offered
+    repo
+      .save(
+        repo.create({
+          domain: { id: at.domainId } as any,
+          instanceId: at.instanceId,
+          openedAt: new Date(closed.startMs),
+          closedAt: new Date(closed.endMs),
+          offered,
+          rejected: closed.rejected,
+          undelivered: closed.undelivered,
+          /* 적힌 것도 같은 행에 — 창이 유입 없이 닫혔어도(시뮬) 이 두 수는 사실이다. */
+          journaledRows: closed.rows,
+          journalFlushes: closed.flushes,
+          /*
+           * 제시가 0 이면 비워 둔다 — 1 로 채우면 「전부 통과」로 읽힌다.
+           * 통과는 **트윈에 닿은** 것만이다: 버려진 것을 빼지 않으면 멈춘 트윈의 창이 100% 로 남는다.
+           */
+          ...(offered > 0
+            ? { acceptedRatio: round4((offered - closed.rejected - closed.undelivered) / offered) }
+            : {})
+        })
+      )
+      .catch(err =>
+        twinWarn(
+          `[twin-ingest-window] "${at.instanceId}" window not persisted (trend will have a gap here):`,
+          err?.message ?? err
+        )
+      )
+  })
+}
+
+/** 0.999 가 1 로 반올림되면 「전부 통과」로 읽힌다 — 자릿수를 넉넉히 준다(메모리 장부와 같은 규칙). */
+const round4 = (v: number) => Math.round(v * 10000) / 10000

package/server/service/twin-ingest-window/twin-ingest-window.ts

@@ -0,0 +1,113 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
+import { ObjectType, Field, ID, Int, Float } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+
+/*
+ * 인제스트 창 하나 — **동기화 추이를 재기동 뒤에도 이어 보기 위한 행.**
+ *
+ * ── 왜 창마다이고 건마다가 아닌가 ───────────────────────────────────────────
+ * 거부마다 행을 쓰면 라이브 계측 규모에서 초당 1만 행이고, 그 부하가 이벤트 루프로 돌아온다. 창마다면
+ * 트윈 1,000개에 하루 14.4만 행(약 14MB)이다. 그래서 **닫힌 창 하나가 영속의 단위**다.
+ *
+ * 건마다 남기는 자리는 이미 따로 있다: 시나리오 경로가 `PayloadLog` 로 dead-letter 를 남긴다(배치성
+ * 유입이라 건수가 감당된다). 이 표는 그것을 대신하지 않고 **추이**를 답한다.
+ *
+ * ── 왜 사유·표본은 여기 없나 ────────────────────────────────────────────────
+ * 사유 문구는 길고 표본에는 **고객의 레코드 원문**이 들어 있다. 그것을 창마다 영속하면 표가 커지고
+ * 고객 데이터가 오래 남는다. 사유와 표본은 메모리 장부가 답하고(최근 6시간), 이 표는 숫자만 든다.
+ *
+ * ── 고치지 않는다 ───────────────────────────────────────────────────────────
+ * 닫힌 창은 지나간 사실이다. 그래서 `updatedAt`·`deletedAt` 을 두지 않는다(저널과 같은 규율).
+ */
+@Entity()
+@Index('ix_twin_ingest_window_0', (e: TwinIngestWindow) => [e.domain, e.instanceId, e.closedAt], { unique: false })
+@ObjectType({
+  description:
+    'One closed ingest window for a twin: how many records were offered, accepted and rejected between two times. Written when a window closes (about every 10 minutes per twin) so the sync trend survives a restart and reaches further back than the in-memory ledger. Reasons and rejected-record samples are deliberately not stored here — they live in the in-memory ledger, which covers roughly the last 6 hours.'
+})
+export class TwinIngestWindow {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the window record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinIngestWindow) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin runtime instance this window belongs to.' })
+  instanceId: string
+
+  @Column()
+  @Field({ description: 'When the window opened.' })
+  openedAt: Date
+
+  @Column()
+  @Field({ description: 'When the window closed. Windows close on the next ingest after the window length elapses, so a feed that stops leaves its last window open and unwritten.' })
+  closedAt: Date
+
+  @Column({ type: 'int' })
+  @Field(type => Int, { description: 'Records offered in this window, whether or not they were accepted.' })
+  offered: number
+
+  @Column({ type: 'int' })
+  @Field(type => Int, { description: 'Records the kernel refused in this window because they did not map — the fix is in the mapping.' })
+  rejected: number
+
+  /*
+   * 거부와 따로 센다 — **처방이 다르다.**
+   *
+   * 트윈이 라이브로 돌지 않으면 커널이 레코드를 버린다. 그것을 거부에 합치면 「매핑을 고쳐라」로 읽히고,
+   * 통과에 합치면 멈춘 트윈이 100% 로 보인다(실제로 그렇게 떴다). 그래서 제3의 수로 남긴다.
+   */
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, {
+    description:
+      'Records that mapped fine but never reached the twin, because the twin was not running live while the feed kept delivering. Distinct from rejected: the fix here is to start the twin or disconnect the feed, not to change the mapping. Offered minus rejected minus undelivered is what actually reached the twin.'
+  })
+  undelivered: number
+
+  /*
+   * 통과율을 **함께 적는다.** 읽는 쪽에서 나누게 하면 소비처마다 반올림이 갈리고(0.999 를 1 로 쓰는
+   * 곳이 생긴다), 제시가 0 인 창에서 0으로 나누는 실수가 각자 생긴다. 제시가 0 이면 **비어 둔다** —
+   * 1 로 채우면 「전부 통과」로 읽힌다.
+   */
+  @Column({ type: 'float', nullable: true })
+  @Field(type => Float, {
+    nullable: true,
+    description:
+      'Share of offered records that reached the twin (0–1), rounded to four places. Null when nothing was offered in this window — an empty window is not a perfect one, and writing 1 there would read as "everything passed".'
+  })
+  acceptedRatio?: number
+
+  /*
+   * ── 적힌 것도 같은 창에 든다 ────────────────────────────────────────────────
+   * 유입과 **다른 축**이다. 시뮬 트윈은 받는 것 없이 자기가 낸 사실을 적으므로 `offered` 가 0 이고
+   * `journaledRows` 는 0 이 아니다. 이 칸이 없으면 도는 트윈 대부분이 시뮬인 서버의 활동이 어느 추이에도
+   * 남지 않는다(계기는 지금만 답하고 재기동에 0 으로 돌아간다).
+   *
+   * 두 수를 따로 세는 이유: 2026-08-20 에 고친 것이 **행당 왕복**이다(델타마다 한 번 → 창당 한 번).
+   * 행만 세면 그 개선도, 되돌아가는 것도 보이지 않는다.
+   */
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, {
+    description:
+      'Journal rows written for this twin during this window. This is a different axis from ingest: a twin driven by a simulator source receives nothing (offered = 0) yet writes what it produces, so without this column its activity appears in no trend at all.'
+  })
+  journaledRows: number
+
+  @Column({ type: 'int', default: 0 })
+  @Field(type => Int, {
+    description:
+      'Number of journal write round-trips (flushes) behind those rows. Counted separately from the rows themselves so that a regression back to per-delta writes — the defect fixed on 2026-08-20, where each kernel delta cost one insert — is visible as rows-per-flush falling back towards 1.'
+  })
+  journalFlushes: number
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'When this record was written.' })
+  createdAt?: Date
+}

package/server/service/twin-instance/twin-instance.ts

@@ -74,7 +74,7 @@ export class TwinInstance {
    * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.
    *
    * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로
-   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **던진다**
+   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **오류를 낸다**
    * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.
    */
   @Column()

package/server/service/twin-journal/twin-journal-query.ts

@@ -1,9 +1,11 @@
+import { twinWarn } from '../../engine/log.js'
 import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'
 import { Arg, Args, Ctx, Float, Int, Query, Resolver } from 'type-graphql'
 
 import { buildNextCursor, cursorSortings, getQueryBuilderFromListParams, getRepository, ListParam, ScalarObject } from '@things-factory/shell'
 
 import { TwinEvent } from '../twin-event/twin-event.js'
+import { JOURNAL_COUNT_CAP } from '../twin-event/journal-count.js'
 import { TwinEventList } from '../twin-event/twin-event-type.js'
 import { TwinEngine } from '../../engine/index.js'
 import { pickAxes } from '../../engine/state-axes.js'
@@ -16,6 +18,12 @@ import { computeTwinKpi, resolveTwinTargets } from '../../engine/kpi-query.js'
  * twinReplay : 내구 저널을 replay 해 상태 재구성(재부팅 복구·시간여행) — untilRevision 으로 임의 과거.
  * (실시간 스트림은 twinState subscription, 명령은 twin-control mutation. 이건 '질의' 표면.)
  */
+/*
+ * 건수 상한은 **저널 세기의 문**에서 온다(`journal-count.ts`) — 값과 규율이 두 곳에 흩어지면 한쪽만
+ * 고쳐진다. 근거(2026-08-22 실측): 상한 1만이면 0.04초, 상한 없이 세면 5.32초(저널 358만 행).
+ */
+const COUNT_CAP = JOURNAL_COUNT_CAP
+
 /**
  * 시각 필터 값을 날짜로 — 배열(between)이면 원소마다.
  *
@@ -52,8 +60,31 @@ export class TwinJournalQuery {
     else if (fromRevision != null) where.revision = MoreThanOrEqual(fromRevision)
     else if (toRevision != null) where.revision = LessThanOrEqual(toRevision)
 
-    /* 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능. */
-    return getRepository(TwinEvent).find({ where, order: { revision: 'DESC' }, take: limit ?? 200 })
+    /*
+     * 최신순(DESC) 기본 — Ledger/recent 뷰. 범위 필터로 시간여행 구간 조회도 가능.
+     *
+     * ── 정렬 축을 **거르는 축과 맞춘다** (2026-08-22 실측) ─────────────────────
+     * `untilTime` 경로는 `eventTime <= T` 로 거르면서 `revision` 으로 정렬했다. 그러면 sqlite 는 조건에
+     * 맞는 행을 **전부 찾아 전부 정렬한 뒤** 상한을 적용한다 — 상한이 정렬 뒤에 걸리므로 200건을 얻는
+     * 데도 전량 정렬을 치른다. 실측(인스턴스 하나가 375만 행):
+     *
+     *   ORDER BY revision DESC              → 33.4초
+     *   ORDER BY eventTime DESC, revision DESC → 0.007초   (4,700배)
+     *
+     * 계획이 그것을 그대로 말한다: 앞은 `USE TEMP B-TREE FOR ORDER BY`(전체 정렬), 뒤는
+     * `... FOR LAST TERM OF ORDER BY` — 시각은 인덱스(`ix_twin_event_1`)에서 순서대로 나오고
+     * **동시각만** 임시 정렬한다.
+     *
+     * **리비전 경로는 그대로 둔다.** 그때는 거르는 축이 `revision` 이고 정렬도 `revision` 이라 이미
+     * 맞아 있다(`ix_twin_event_0`). 축이 어긋난 경로만 고친다 — 맞는 자리를 건드리면 그쪽이 어긋난다.
+     *
+     * 순서의 뜻이 **완전히 같지는 않다**(측정해서 고친 문장): `revision` 순서와 `eventTime` 순서가
+     * 어긋나는 자리가 실재한다(426만 행 중 7건 — 미러는 원본의 시각을 싣고 도착 순서로 리비전을 받는다).
+     * 이 목록은 사람이 이력을 훑는 화면이고 **시각순으로 보는 것이 그 화면의 뜻**이므로, 그 어긋남은
+     * 결함이 아니라 오히려 맞는 순서다. 동시각의 순서를 위해 `revision` 을 둘째 축으로 남긴다.
+     */
+    const order: any = untilTime != null ? { eventTime: 'DESC', revision: 'DESC' } : { revision: 'DESC' }
+    return getRepository(TwinEvent).find({ where, order, take: limit ?? 200 })
   }
 
   /**
@@ -131,13 +162,36 @@ export class TwinJournalQuery {
     /* 대상 범위는 호출자가 필터로 빼먹을 수 있는 값이 아니다 — 계약상 필수라 여기서 강제한다. */
     qb.andWhere(`${qb.alias}.instanceId IN (:...instanceIds)`, { instanceIds })
 
-    const [items, total] = await qb.getManyAndCount()
+    /*
+     * ── 건수는 **상한까지만** 센다 (2026-08-22 실측) ──────────────────────────
+     * 예전에는 `getManyAndCount()` 였다. 그 두 번째 질의가 조건에 맞는 행을 **전부** 세는데, 실측한
+     * 개발 저널에서 트윈 하나가 358만 행이라 **한 번에 5.32초**였다. 이력 화면을 열 때마다 그것을
+     * 물었고, 그 5초 동안 이벤트 루프가 다른 요청을 처리하지 못했다.
+     *
+     * 상한을 두면 같은 답이 **0.04초**다(130배). 상한을 넘으면 정확한 수를 모르는 것이 사실이므로
+     * 목록 규약의 「서버 상한에 부딪힘(total 모름)」 갈래로 낸다 — 화면은 「처음 N 건만」이라고 말하고
+     * 좁히기를 권한다. **조용히 자르지 않는다**: 상한을 넘었다는 사실을 `capped` 로 함께 낸다.
+     *
+     * 왜 하위 질의로 세지 않나: 5개 드라이버에서 같이 도는 형태여야 한다(이 저장소의 절대 규칙).
+     * 그래서 **키 컬럼만 상한까지 읽어 세는** 방식을 쓴다 — 색인만 읽으므로 행 본문을 만들지 않는다.
+     */
+    const items = await qb.getMany()
+    const probe = qb
+      .clone()
+      .orderBy() /* 세는 데 순서는 필요 없다 — 정렬을 남기면 임의 축에서 전체 정렬이 된다. */
+      .skip(0)
+      .take(COUNT_CAP + 1)
+      .select(`${qb.alias}.id`)
+    const counted = await probe.getRawMany()
+    const capped = counted.length > COUNT_CAP
+    /* 상한을 넘었으면 **전체 수를 모른다** — 상한값을 전체로 적으면 화면이 거짓을 말한다. */
+    const total = capped ? undefined : counted.length
 
     /* 다음 커서는 **이번 페이지의 마지막 행**에서 만든다. 페이지가 상한보다 짧으면 뒤가 없다. */
     const axes = cursorSortings(effective.sortings, 'id')
     const nextCursor = items.length === limit ? buildNextCursor(items[items.length - 1], axes) : undefined
 
-    return { items, total, nextCursor }
+    return { items, total, capped, countCap: COUNT_CAP, nextCursor }
   }
 
   /**
@@ -231,7 +285,7 @@ export class TwinJournalQuery {
     const state = await TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)
     const picked = pickAxes(state, axes)
     /* 오타를 조용히 넘기지 않는다 — 화면이 빈 채로 뜨는 이유를 아무도 모르게 되는 것이 가장 나쁘다. */
-    if (picked.unknown.length) console.warn(`[twin] twinReplay: unknown axes ignored for "${instanceId}": ${picked.unknown.join(', ')}`)
+    if (picked.unknown.length) twinWarn(`[twin] twinReplay: unknown axes ignored for "${instanceId}": ${picked.unknown.join(', ')}`)
     if (!attentionLimit || !picked.state?.attentions) return picked.state
     const d = digestAttentions(picked.state.attentions, attentionLimit)
     /* 잘랐다는 사실을 값으로 남긴다 — 개수만 줄어들면 화면은 "괜찮아졌다" 로 읽는다. */

package/server/service/twin-lifecycle/twin-lifecycle-mutation.ts

@@ -1,8 +1,11 @@
 import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
-import { ScalarObject } from '@things-factory/shell'
+import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+/* 정책 읽기는 그 모듈에서 직접 가져온다 — 다른 소비처(`reference-resolver`)와 같은 길이다. */
+import { readRestartPolicy } from '../../engine/restart-policy.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
 
 import type { TwinModelDef } from '@operato/twin-kernel'
 
@@ -61,6 +64,45 @@ export class TwinLifecycleMutation {
     return true
   }
 
+  /**
+   * 이 트윈이 **자기 과거를 어떻게 대할 것인가**를 다시 선언한다 (2026-08-20).
+   *
+   * ── 왜 이 문이 필요한가 ────────────────────────────────────────────────────
+   * `restartPolicy` 는 사람이 하는 선언인데, 만들 때 한 번 정하면 **고칠 길이 없었다.** 그래서 「씨앗
+   * 재현용」으로 세운 트윈이 나중에 사람들이 이력을 보는 트윈이 되어도 선언은 `reset` 으로 남았다.
+   * 선언과 쓰임이 어긋난 채로 두면, 선언대로 구현하는 순간(저널 초기화) 이력을 잃는다.
+   *
+   * ── 지금 도는 것에는 손대지 않는다 ─────────────────────────────────────────
+   * 이 값은 **다음 기동**의 규칙이다. 돌고 있는 런타임의 구동 방식을 바꾸려면 정지·기동이 필요하고,
+   * 그 판단은 사람의 것이다(도는 트윈을 조용히 갈아 끼우면 그 사이의 사실이 어디로 갔는지 알 수 없다).
+   * 그래서 결과에 「지금 도는 것과 다르다」는 사실을 함께 낸다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Re-declare how a twin treats its own past on the next boot: 'resync' (re-read from the source), 'resume' (carry its own journal forward) or 'reset' (reproduce from the seed, journal cleared). The value is read strictly — an unknown or legacy word is refused with the accepted words named, because a silent default would decide whether a twin's history survives. This changes the declaration only: a running runtime keeps the mode it was started with, and the result says so (appliesAtNextStart) rather than swapping it underneath."
+  })
+  async setTwinRestartPolicy(
+    @Arg('instanceId') instanceId: string,
+    @Arg('restartPolicy') restartPolicy: string,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    /* 값은 **엄격히** 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 조용히 결정된다. */
+    const policy = readRestartPolicy(restartPolicy, `twin "${instanceId}"`)
+    const repo = getRepository(TwinInstance)
+    const row = await repo.findOne({ where: { domain: { id: domainId }, instanceId } })
+    if (!row) throw new Error(`unknown twin "${instanceId}" in this domain — nothing was changed`)
+
+    const before = row.restartPolicy
+    if (before === policy) return { instanceId, restartPolicy: policy, changed: false, appliesAtNextStart: false }
+
+    await repo.update({ id: row.id }, { restartPolicy: policy })
+    /* 도는 런타임의 구동 방식은 그대로다 — 그 사실을 숨기지 않는다. */
+    const running = !!TwinEngine.metrics(domainId, instanceId)
+    return { instanceId, restartPolicy: policy, previous: before, changed: true, appliesAtNextStart: running }
+  }
+
   /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Delete a twin instance: stop it, remove the registry entry and purge its event journal.' })
@@ -82,9 +124,41 @@ export class TwinLifecycleMutation {
     return TwinEngine.instanceIdsOfSpace(context.state.domain.id, spaceId)
   }
 
-  @Query(returns => [ScalarObject], { description: 'List provisioned twin instances in the current domain with management metadata.' })
+  @Query(returns => [ScalarObject], {
+    description:
+      'List provisioned twin instances in the current domain with management metadata. Each row also carries `sync`: a one-line answer to "is this twin keeping in step with the floor?" — a verdict (syncing | mapping-blocked | no-traffic | not-connected | not-applicable | unknown), the accepted share of the last closed 10-minute window, and up to 36 closed windows of offered/rejected counts for a sparkline. Reasons and rejected-record samples are deliberately absent here; ask twinIngestHealth for one twin when you need them, because carrying raw records for every row would make this list heavy for no gain. acceptedRatio is null while the first window is still filling — a partially filled window under-counts, and drawing it as zero would read as "nothing passed".'
+  })
   async twinInstanceList(@Ctx() context: ResolverContext): Promise<any[]> {
-    return TwinEngine.list(context.state.domain.id)
+    const domainId = context.state.domain.id
+    const list = await TwinEngine.list(domainId)
+    /*
+     * 동기화 요약을 **같은 응답에 얹는다.** 따로 질의하면 트윈 수만큼 왕복이 생기고(N+1), 그 사이 화면은
+     * 판정 없는 목록을 먼저 그린다 — 사람이 그 순간을 「정상」으로 읽는다.
+     */
+    const brief = new Map(
+      TwinEngine.ingestHealthBrief(
+        domainId,
+        list.map((x: any) => x.instanceId)
+      ).map(b => [b.instanceId, b])
+    )
+    /*
+     * **쓰기 사실도 같은 응답에 얹는다** (2026-08-20).
+     *
+     * 「이 트윈이 사실을 적고 있나」는 운영자가 트윈 화면에서 묻는 질문인데, 그 답은 벤치(슈퍼유저)의
+     * 부하 계기판에만 있었다. 유입(`sync`)과 나란히 두는 이유는 둘이 한 사슬이기 때문이다 — 받은 것이
+     * 있어도 적히지 않으면 저널이 비고, 그러면 성과·시간여행이 함께 빈다.
+     *
+     * 계기는 메모리라 왕복이 없다. **도는 트윈만** 답이 있고, 멈춘 트윈은 `null` 이다(0 이 아니다 —
+     * 「쓰지 않았다」와 「돌지 않는다」는 다른 사실이다).
+     */
+    return list.map((x: any) => {
+      const m = TwinEngine.metrics(domainId, x.instanceId)
+      return {
+        ...x,
+        sync: brief.get(x.instanceId) ?? null,
+        write: m ? { rate: m.journalRate, journaled: m.journaledTotal, backlog: m.backlog } : null
+      }
+    })
   }
 
   /** 단건 상세 — 프로비저닝 에디터용 model(구조+layout) 포함. */

package/server/service/twin-metrics/twin-metrics-query.ts

@@ -3,18 +3,30 @@ import { Arg, Ctx, Directive, Query, Resolver } from 'type-graphql'
 import { In } from 'typeorm'
 
 import { Domain, getRepository, ScalarObject } from '@things-factory/shell'
+import { PrivilegeObject, checkPermission } from '@things-factory/auth-base'
 
 import { TwinEngine } from '../../engine/index.js'
 import { newCpuSampler, sampleCpu } from '../../engine/load-meter.js'
+import { modelGapOf } from '../../engine/model-gap.js'
 
 /*
  * 트윈 처리량 계측(모니터, ④-1) — 라이브 동기 인터페이스 부하를 읽는 일급 지표.
- * 유입률(ingestRate)·방송률(broadcastRate)·저널률(journalRate)·백로그(backlog)·누적. 폴링으로 라이브 관측.
- * (부하가 화면에 안 보인다던 문제의 정공법 — "얼마나 들어오고 얼마나 방송/기록되나"를 수치로.)
+ * 유입률(ingestRate)·브로드캐스팅률(broadcastRate)·저널률(journalRate)·백로그(backlog)·누적. 폴링으로 라이브 관측.
+ * (부하가 화면에 안 보인다던 문제의 정공법 — "얼마나 들어오고 얼마나 브로드캐스팅/기록되나"를 수치로.)
  */
 /* CPU 는 누적값이라 **표본 사이의 차이**로만 점유율이 나온다. 그래서 호출 사이에 상태가 남아야 한다. */
 const CPU_SAMPLER = newCpuSampler()
 
+/**
+ * 거부된 **레코드 원문**을 볼 수 있는 자격.
+ *
+ * 트윈을 고칠 수 있는 사람과 같은 자격으로 둔다 — 매핑을 고치려면 원천이 실제로 보낸 모양을 봐야 하므로
+ * 권한이 그 일과 맞는다. 도메인 소유자·슈퍼유저는 통과한다(프레임워크 규약과 같다).
+ *
+ * 판정·추이·사유는 이 자격과 무관하게 낸다. 「맞춰지고 있나」는 감출 일이 아니다.
+ */
+const RAW_RECORD_PRIVILEGE: PrivilegeObject = { category: 'twin', privilege: 'mutation', owner: true, super: true }
+
 @Resolver()
 export class TwinMetricsQuery {
   @Query(returns => ScalarObject, { nullable: true, description: 'Live throughput metrics of one twin instance (ingest/broadcast/journal rate, backlog). Null if not a live instance or not in the current domain.' })
@@ -23,11 +35,77 @@ export class TwinMetricsQuery {
     return TwinEngine.metrics(context.state.domain.id, instanceId)
   }
 
-  @Query(returns => [ScalarObject], { description: 'Live throughput metrics of all running live twin instances in the current domain (monitor dashboard).' })
+  @Query(returns => [ScalarObject], {
+    description:
+      'Throughput metrics of every running twin instance in the current domain — simulations as well as mirrors (monitor dashboard). Simulations report ingestRate 0 because they receive nothing from a source: they emit their own facts, and that zero is a fact rather than a gap. Until 2026-08-20 simulations carried no meter at all and were silently absent from this list, which made a host full of running simulations look idle.'
+  })
   async twinMetricsAll(@Ctx() context: ResolverContext): Promise<any[]> {
     return TwinEngine.allMetrics(context.state.domain.id) // 도메인 스코프
   }
 
+  /*
+   * ── 동기화 건강 — 「이 트윈이 현장과 맞춰지고 있나」 ──────────────────────────
+   *
+   * `twinMetrics` 는 **통과한** 이벤트의 초당 수를 답한다. 여기서 답하는 것은 **제시된 것 중 얼마가
+   * 통과했나**이고, 통과하지 못한 것의 이유와 실제 모양까지 낸다.
+   *
+   * 왜 따로 있나: 거부된 레코드는 **저널에 없다**(거부의 뜻이 그것이다). 저널을 접어 나오는 것은 통과한
+   * 쪽뿐이라, 거부의 추이는 세는 자리를 따로 두어야 나온다.
+   *
+   * 왜 도메인으로 자르나: 이것은 **테넌트의 데이터**다. 거부 표본에는 그 고객의 레코드 원문이 들어
+   * 있으므로 남의 것을 보여 줄 수 없다(부하 계기판이 프로세스 전체를 내는 것과 반대다 — 그쪽은
+   * 이벤트 루프가 프로세스 공유라서 그렇게 했다).
+   *
+   * ── 수치와 원문은 민감도가 다르다 ───────────────────────────────────────────
+   * 판정·추이·사유는 「맞춰지고 있나」를 알려면 누구나 봐야 한다. 반면 **거부된 레코드 원문**은 그 고객의
+   * 업무 데이터다(품목·수량·거래처가 그대로 들어 있다). 같은 도메인이라는 것만으로 원문까지 열면 필요
+   * 없는 사람에게도 열린다.
+   *
+   * 그래서 원문만 한 겹 뒤에 둔다 — 트윈을 **고칠 수 있는 사람**에게만. 매핑을 고치려면 원천이 실제로
+   * 무엇을 보냈는지 봐야 하므로 권한이 그 일과 맞는다. 감출 때는 **감췄다고 말한다**(`samplesWithheld`);
+   * 빈 배열로 두면 「거부된 것이 없다」로 읽힌다.
+   */
+  @Query(returns => ScalarObject, {
+    description:
+      'Answers one question: is this twin keeping in step with the floor? Returns a verdict — syncing | mapping-blocked | no-traffic | not-connected | not-applicable | unknown — together with the threshold it was judged by, so a screen can say why. `recent` is the last **closed** 10-minute window (null while the first window is still filling: a partially filled window under-counts, so it is not called "recent"), and `trend` carries up to 36 closed windows (6 hours) oldest-first with offered / accepted / rejected per window. Accepted and rejected are reported together because counting only rejections makes "nothing is arriving" and "everything is fine" both look like zero. `reasons` groups rejections by the reason the kernel gave, most frequent first, each with the last time that reason occurred — a reason whose time has stopped is one you already fixed. `samples` holds one rejected record per reason (the raw record, truncated with recordTruncated when long) because a reason alone does not tell you what the source actually sent. Counts that could not be shown are reported rather than dropped: sampleDropped, trendDropped, and reasonsCapped when distinct reasons hit their limit and the rest were folded into "(other reasons)". A twin that has never received anything reports null figures rather than zeros, since never-measured and measured-as-zero are different facts. This ledger lives in memory: it covers roughly the last 6 hours and resets when the process restarts. The verdict, trend and reasons are returned to anyone in the owning domain, but the raw records in `samples` are business data of that tenant, so they require the same privilege as changing the twin (twin/mutation, with domain owner and superuser granted); when the caller lacks it, `samples` comes back empty and `samplesWithheld` says how many were held back — an empty list alone would read as "nothing was rejected". `modelGap` answers a different question from the verdict: the verdict is about the feed (is anything arriving, does it pass), while modelGap is about the model (did we declare what the source knows). The ingest gate deliberately does not reject a record that references an id the master never declared — a source may legitimately report a new place before the structure sync catches up, and rejecting it would lose that measurement. The kernel absorbs it and marks it `origin: "observed"` instead, and modelGap counts those per axis (locations / equipment / persons) with a capped id list plus how many more were left out. It also carries the kernel\'s `unhandled` tally — event kinds the twin could not apply at all — and, for energy twins, how many state reports arrived from equipment the model does not know. `notCovered` names axes this cannot answer yet: meters carry no origin mark in the kernel, so a mistyped meterId silently becomes a new meter whose kW is accumulated into the site demand. Null while the twin is not running: there is nothing to compare against, and never-compared is not the same as none. Null if the instance is not in the current domain.'
+  })
+  async twinIngestHealth(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    const domainId = context.state.domain.id
+    /*
+     * 테넌트 격리 — 다만 `owns` 는 **도는 트윈**만 참이다. 멈춘 트윈의 장부도 볼 수 있어야 하므로
+     * (「고치려고 멈춰 뒀는데 마지막에 뭐가 거부됐나」), 등록 여부로도 판정한다. 도는 트윈이면 DB 를
+     * 묻지 않는다(대부분의 조회가 그쪽이다).
+     */
+    if (!TwinEngine.owns(domainId, instanceId) && !(await TwinEngine.ownsRegistered(domainId, instanceId))) return null
+
+    const view = TwinEngine.ingestHealthOf(domainId, instanceId)
+
+    /*
+     * ── 「원본이 말한 적 없는 것」을 함께 낸다 (2026-08-20) ──────────────────────
+     * 유입 문은 참조 오류를 거부하지 않는다(실측: 모르는 로케이션·bizStep·계량기가 모두 통과). 거부하지
+     * 않는 것이 옳다 — 원천이 모델보다 먼저 새 자리를 말하는 것은 정상이고, 거부하면 그 선행 계측을
+     * 잃는다. 대신 커널이 **흡수하고 표시한다**(`origin: 'observed'`).
+     *
+     * 그 표시를 읽는 곳이 모델 인스펙션 화면 하나였다. 그런데 「이 트윈이 현장과 맞춰지고 있나」를
+     * 보는 사람이 바로 그것을 알아야 한다 — 원천이 우리가 모르는 로케이션만 보내면 트윈은 도는데
+     * 스키매틱은 비어 있고, 그게 우리가 「빈 공장」이라 불러 온 상태다.
+     *
+     * 판정에는 섞지 않는다. 판정은 **피드**를 말하고 이것은 **모델**을 말한다(`model-gap.ts`).
+     */
+    const modelGap = modelGapOf(TwinEngine.snapshot(domainId, instanceId))
+
+    /* 원문을 볼 수 있나 — 못 보면 **몇 건을 감췄는지** 함께 낸다(빈 배열은 「없었다」로 읽힌다). */
+    const maySeeRecords = await checkPermission(
+      RAW_RECORD_PRIVILEGE,
+      context.state.user,
+      context.state.domain
+    )
+    if (maySeeRecords) return { ...view, modelGap }
+
+    const { samples, ...rest } = view
+    return { ...rest, modelGap, samples: [], samplesWithheld: samples.length }
+  }
+
   /*
    * ── 이벤트 루프 부하 — **운영 계기판이다. 테넌트 기능이 아니다.** ─────────────
    *