@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -1,4 +1,5 @@
-import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'
+import { twinError } from '../../engine/log.js'
+import { Arg, Ctx, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
 import { validateScenario } from '@operato/twin-kernel'
 
@@ -9,6 +10,8 @@ import { getRepository } from '@things-factory/shell'
 import { TwinEngine } from '../../engine/index.js'
 import { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'
 import { buildCommandAudit } from '../twin-audit/command-audit.js'
+/* 구동은 원본을 지난다(ADR-0029 §8) — 트윈 런타임을 직접 잡지 않는다. */
+import { routeControl, controlCapabilityOf } from '../reference/control-routing.js'
 
 /*
  * 트윈 Command·Scenario 채널 — 상향 mutation.
@@ -40,7 +43,7 @@ export class TwinControlMutation {
     const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
     /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
-      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
+      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => twinError('twin syncBoardEquipment fail', err))
     }
     /*
      * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
@@ -54,49 +57,94 @@ export class TwinControlMutation {
       const repo = getRepository(TwinAuditEvent)
       await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
     } catch (err) {
-      console.error(`[twin-control] command audit not recorded for "${instanceId}"`, err)
+      twinError(`[twin-control] command audit not recorded for "${instanceId}"`, err)
     }
 
     /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
     return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }
   }
 
-  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
+  /**
+   * 구동 채널 — **원본을 지난다**(ADR-0029 §8).
+   *
+   * ── 무엇이 바뀌었나 (2026-08-19) ──────────────────────────────────────────
+   * 예전에는 이 문이 `TwinEngine.runtime(...).scenario` 를 **직접** 잡았다. 시뮬만 할 수 있는 일(자극·배속·
+   * 정지)이 계약 밖의 지름길로 들어온 셈이고, 실 시스템에는 그 자리가 아예 없었다. 이제 길은 하나다:
+   * 트윈 → 그 트윈의 원본 → 어댑터가 **선언한** `control` 능력. 선언하지 않은 원본에는 문이 열리지 않고,
+   * 그 사실을 사유 코드로 말한다(`not-declared`) — 실 WMS 가 정지되지 않는 것은 결손이 아니다.
+   *
+   * 반환을 Boolean 에서 객체로 바꿨다: 예전에는 거절 사유를 실을 자리가 없어 **로그로만** 남겼다.
+   * 화면은 왜 안 되는지 알 수 없었다.
+   */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })
-  async controlTwinScenario(
+  @Mutation(returns => ScalarObject, {
+    description:
+      "Drive the source behind a twin: stimulus | start | pause | speed | reset. The command goes through the source adapter's declared control capability — a source that does not declare it refuses with code 'not-declared' (a real system is not paused or seeded, and that is a fact rather than a gap). Returns { ok, code?, detail? }."
+  })
+  async controlTwinSource(
     @Arg('instanceId') instanceId: string,
     @Arg('action') action: string,
     @Ctx() context: ResolverContext,
-    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any
-  ): Promise<boolean> {
+    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any,
+    @Arg('speed', { nullable: true }) speed?: number
+  ): Promise<any> {
     const domainId = context.state.domain?.id
-    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */
-    if (!TwinEngine.owns(domainId, instanceId)) return false
-    const runtime = TwinEngine.runtime(domainId, instanceId)
+    if (!domainId) return { ok: false, code: 'no-domain' }
+    const allowed = ['stimulus', 'start', 'pause', 'speed', 'reset']
+    if (!allowed.includes(action)) return { ok: false, code: 'unsupported-action', detail: `one of ${allowed.join(' | ')}` }
     /*
-     * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).
-     * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.
+     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour` 를
+     * 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다). 규칙은 커널이
+     * 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
      */
-    if (!runtime?.scenario) return false
+    if (action === 'stimulus') {
+      const v = validateScenario(scenario)
+      if (v.ok === false) return { ok: false, code: 'invalid', detail: v.errorCode, params: v.errorParams }
+    }
+    if (action === 'speed' && !(Number(speed) > 0)) return { ok: false, code: 'invalid', detail: 'speed must be greater than 0' }
+
     /*
-     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`
-     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).
-     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
+     * **구동도 사람이 한 일이다 — 남긴다** (ADR-0029 §1 결정 C, 2026-08-19).
+     *
+     * 이 문은 감사를 아예 남기지 않았다. 그런데 자극을 바꾸고 배속을 올리고 원본을 멈추는 것은 그 트윈의
+     * 사실을 바꾸는 행위다 — 커맨드 채널은 남기는데 이쪽이 비어 있으면, 나중에 「무엇이 이 공장을
+     * 흔들었나」에 답할 수 없다.
+     *
+     * 결정 C 그대로: 게이트는 여기 남고(위 `@privilege`), **원본의 답을 같은 행에 닫는다.** 답을 못 받으면
+     * `unknown` 이다 — 성공으로 적지 않는다.
      */
-    if (action === 'load') {
-      const v = validateScenario(scenario)
-      if (v.ok === false) {
-        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */
-        console.warn(`[twin] scenario rejected for "${instanceId}": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)
-        return false
-      }
+    let result: { ok: boolean; code?: string; detail?: string }
+    try {
+      result = await routeControl(domainId, instanceId, { action: action as any, scenario, speed: speed != null ? Number(speed) : undefined })
+    } catch (e: any) {
+      result = { ok: false, code: 'failed', detail: e?.message ?? 'control failed' }
     }
-    if (action === 'load' && scenario) runtime.scenario.load(scenario)
-    else if (action === 'start') runtime.scenario.start()
-    else if (action === 'pause') runtime.scenario.pause()
-    else if (action === 'setSpeed' && scenario?.speed != null) runtime.scenario.setSpeed(Number(scenario.speed))
-    else return false
-    return true
+    try {
+      const audit = buildCommandAudit({
+        /* 커맨드 채널과 같은 모양으로 적는다 — 감사를 읽는 쪽이 두 어휘를 배우지 않게. */
+        command: { type: `source.${action}`, origin: 'user', args: { ...(scenario ? { scenario } : {}), ...(speed != null ? { speed } : {}) } },
+        /* 게이트는 통과했다(여기까지 왔다) — 그 사실과 원본의 답은 다른 칸이다. */
+        ack: { accepted: true },
+        source: { answered: typeof result?.ok === 'boolean', ok: result?.ok, code: result?.code },
+        actor: context.state.user,
+        at: new Date()
+      })
+      const repo = getRepository(TwinAuditEvent)
+      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
+    } catch (err) {
+      /* 기록이 실패해도 결과는 돌려준다 — 다만 삼키지 않는다(「기록 없음」과 「일 없음」을 구별해야 한다). */
+      twinError(`[twin-control] source control audit not recorded for "${instanceId}"`, err)
+    }
+    return result
+  }
+
+  /** 이 트윈의 원본이 **무엇을 받을 수 있나** — 화면이 버튼을 열기 전에 묻는 자리. */
+  @Query(returns => ScalarObject, {
+    description: "What the source behind this twin can do: its declared capabilities ('live', 'control'). Empty when the twin has no source or its adapter declares nothing."
+  })
+  async twinSourceCapability(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    const domainId = context.state.domain?.id
+    if (!domainId) return { capabilities: [] }
+    return controlCapabilityOf(domainId, instanceId)
   }
 }

package/server/service/twin-event/journal-count.ts

@@ -0,0 +1,53 @@
+/*
+ * 저널을 **상한까지만 센다** — 세는 것도 읽는 것이다 (2026-08-22).
+ *
+ * ── 왜 (실측) ───────────────────────────────────────────────────────────────
+ * 조건에 맞는 행을 전부 세는 질의는 행을 실어 오지 않아도 비싸다. 개발 저널에서 트윈 하나가 358만
+ * 행이었고 그 한 번이 **5.32초**였다. 색인만 상한까지 읽으면 같은 조건에서 **0.04초**다(130배).
+ *
+ * 그 5초 동안 이벤트 루프는 다른 요청을 처리하지 못한다 — 이력 화면 한 번, 준비도 화면 한 번이
+ * 사용자에게는 「눌렀는데 아무 반응이 없다」로 나타난다. 준비도 화면은 그런 세기를 **넷** 했다.
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * 세는 목적이 둘 중 하나다.
+ *  ① **판정** — 「한 건이라도 있나」. 그때는 하나만 찾으면 끝이다(`anyJournalRow`).
+ *  ② **표시** — 사람에게 수를 보인다. 그때는 상한까지 세고, 넘으면 **모른다고 말한다**(`countUpTo`).
+ *
+ * 상한을 넘었을 때 상한값을 전체로 적으면 화면이 거짓을 말한다. 그래서 `capped` 를 함께 낸다 —
+ * 없는 것과 모르는 것을 가르는 이 프로젝트의 규율이 세기에도 같이 적용된다.
+ */
+import type { ObjectLiteral, Repository } from 'typeorm'
+
+/** 표시용 세기의 기본 상한 — 화면이 한 번에 보여 줄 범위를 훨씬 넘는 값. */
+export const JOURNAL_COUNT_CAP = 10_000
+
+export interface CappedCount {
+  /** 센 수. `capped` 면 상한까지만 센 값이므로 **전체가 아니다**. */
+  count: number
+  /** 상한을 넘었나 — 그때 전체 수는 모르는 것이 사실이다. */
+  capped: boolean
+}
+
+/**
+ * 상한까지만 세기 — 키 컬럼만 읽으므로 행 본문을 만들지 않는다.
+ *
+ * `count()` 를 쓰지 않는 이유: 그것은 상한을 받지 않는다(조건에 맞는 전부를 센다).
+ */
+export async function countUpTo<T extends ObjectLiteral>(
+  repo: Repository<T>,
+  where: any,
+  cap = JOURNAL_COUNT_CAP
+): Promise<CappedCount> {
+  const rows = await repo.find({ where, select: ['id'] as any, take: cap + 1 })
+  return rows.length > cap ? { count: cap, capped: true } : { count: rows.length, capped: false }
+}
+
+/**
+ * 한 건이라도 있나 — **판정에는 수가 필요 없다.**
+ *
+ * 예전에는 전부 센 뒤 `> 0` 을 봤다. 그 답을 얻는 데 358만 행을 세고 있었다.
+ */
+export async function anyJournalRow<T extends ObjectLiteral>(repo: Repository<T>, where: any): Promise<boolean> {
+  const rows = await repo.find({ where, select: ['id'] as any, take: 1 })
+  return rows.length > 0
+}

package/server/service/twin-event/twin-event-keys.ts

@@ -1,3 +1,4 @@
+import { twinWarn } from '../../engine/log.js'
 /*
  * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.
  *
@@ -18,6 +19,7 @@
 
 /** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */
 export interface TwinEventKeys {
+  action?: string
   bizStep?: string
   epc?: string
   orderId?: string
@@ -37,7 +39,7 @@ function clip(v: unknown, field: string): string | undefined {
   const s = String(v)
   if (!s) return undefined
   if (s.length <= MAX_KEY) return s
-  console.warn(
+  twinWarn(
     `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +
       `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`
   )
@@ -90,9 +92,22 @@ export function equipmentIdOf(envelope: any): string | undefined {
   return d.moverId ?? undefined
 }
 
+/**
+ * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).
+ *
+ * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.
+ * 그래서 「이 트윈이 반출을 한 번이라도 접었는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
+ * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.
+ */
+export function actionOf(envelope: any): string | undefined {
+  const a = (envelope?.data ?? envelope ?? {}).action
+  return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined
+}
+
 /** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */
 export function twinEventKeys(envelope: any): TwinEventKeys {
   return {
+    action: actionOf(envelope),
     bizStep: clip(bizStepOf(envelope), 'bizStep'),
     epc: clip(epcOf(envelope), 'epc'),
     orderId: clip(orderOf(envelope), 'orderId'),

package/server/service/twin-event/twin-event-type.ts

@@ -14,8 +14,32 @@ export class TwinEventList {
   @Field(type => [TwinEvent], { description: 'The events on this page, ordered by the requested sorting (revision descending by default).' })
   items: TwinEvent[]
 
-  @Field(type => Int, { description: 'Total number of events matching the filters, ignoring pagination. Lets the caller show an honest "shown of total" count instead of silently truncating.' })
-  total: number
+  /*
+   * 전체 수 — **상한을 넘으면 비운다.**
+   *
+   * 세는 데도 값이 든다(2026-08-22 실측: 저널 358만 행인 트윈에서 전량 세기 5.32초 · 상한 1만까지
+   * 0.04초). 그래서 상한까지만 세고, 넘으면 「모른다」로 둔다. 그때 상한값을 전체로 적으면 화면이
+   * 거짓을 말한다 — 없는 것과 모르는 것을 가르는 것이 이 필드의 규율이다.
+   */
+  @Field(type => Int, {
+    nullable: true,
+    description:
+      'Total number of events matching the filters, ignoring pagination. Lets the caller show an honest "shown of total" count instead of silently truncating. NULL when the server stopped counting at countCap: the exact total is then unknown, and capped says so — do not render the cap as if it were the total.'
+  })
+  total?: number
+
+  @Field({
+    nullable: true,
+    description:
+      'True when there are more matching events than countCap, so total could not be established. The caller should say "first N shown" and offer narrowing rather than implying it received everything.'
+  })
+  capped?: boolean
+
+  @Field(type => Int, {
+    nullable: true,
+    description: 'The counting limit the server applied. Reported so the screen can say how far the count is trustworthy instead of guessing.'
+  })
+  countCap?: number
 
   /*
    * 다음 페이지 커서. 저널은 **머리에 계속 쌓이는 목록**이라 offset 으로 뒤를 읽으면

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

@@ -34,6 +34,8 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 @Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
 /* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
 @Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })
+/* ix_6 — "반출을 한 번이라도 접었나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
+@Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -132,6 +134,11 @@ export class TwinEvent {
   @Field({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' })
   correlationId?: string
 
+  /* 옛 행은 비어 있다 — 승격 전에 기록된 것이라 **모른다**(0 이나 OBSERVE 로 위장하지 않는다). */
+  @Column({ length: 16, nullable: true })
+  @Field({ nullable: true, description: 'EPCIS action (ADD / OBSERVE / DELETE), promoted from the payload. Empty for operational deltas, and for rows journaled before this column existed.' })
+  action?: string
+
   @Column({ length: 255, nullable: true })
   @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })
   bizStep?: string

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

@@ -1,3 +1,4 @@
+import { twinLog } from '../../engine/log.js'
 import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive} from 'type-graphql'
 
 import { getRepository, ScalarObject } from '@things-factory/shell'
@@ -193,7 +194,7 @@ export class TwinForecastQuery {
     const basis = await TwinEngine.modelBasis(domainId, instanceId)
     const stale = !!stored && modelBasisChanged(stored.basis, basis)
     if (stale) {
-      console.log(
+      twinLog(
         `[twin-forecast] "${instanceId}": calibration not applied — model changed since it was learned.` +
           ` learned on: ${describeModelBasis(stored!.basis)} / now: ${describeModelBasis(basis)}`
       )

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

@@ -0,0 +1,7 @@
+import { TwinIngestWindow } from './twin-ingest-window.js'
+import { TwinIngestWindowQuery } from './twin-ingest-window-query.js'
+
+export const entities = [TwinIngestWindow]
+export const resolvers = [TwinIngestWindowQuery]
+
+export { installIngestWindowWriter } from './twin-ingest-window-writer.js'

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
+}