@things-factory/headless-twin 10.0.11 → 10.0.13

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

@@ -61,19 +61,25 @@ export class TwinInstance {
   kind: string
 
   /*
-   * realityMode — 이 트윈의 현실이 어디서 오는가(runtime-state-model §0·§1 "지속 현실 하나 + 여러 렌즈"의 ① 선언).
-   * 'mirror'         = 현실은 외부 실물 시스템. 트윈=순수 렌즈, 재기동 시 실물서 재동기(startLive).
-   * 'sim-world'      = 트윈이 낳은 타임라인이 곧 진실이며 이어진다 → 재기동 시 저널서 resume(현실 지속).
-   * 'sim-experiment' = seed 재현형. 재기동 = 같은 우주 재실행(저널 reset, revision 0) — 백지 시작이 버그가 아니라 선언된 거동.
+   * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나(ADR-0029 §2).
    *
-   * **비어 있을 수 없다.** 이 값은 재기동 거동을 구분하는 선언이고, 없으면 읽는 쪽마다 각자
-   * 기본값을 고르게 된다 — 같은 트윈이 부르는 자리에 따라 다르게 재기동하는 길이다.
-   * 선언을 생략한 프로비저닝은 `register` 가 `DEFAULT_REALITY_MODE` 로 **각인해서 저장한다**.
-   * 즉 "미선언" 이라는 상태 자체를 저장소에 두지 않는다.
+   *   'resync' = 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다 → startLive).
+   *   'resume' = 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).
+   *   'reset'  = 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험 — 백지 시작이 선언된 거동이다).
+   *
+   * ── 왜 트윈에 남았나 (옛 이름 `realityMode`) ────────────────────────────────
+   * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) —
+   * 트윈은 한 종류이고 언제나 원본을 반영한다. 그런데 코드가 이 축으로 실제로 가른 것은 **재기동 거동
+   * 하나**였고, 그것은 원본의 성질이 아니라 **트윈과 자기 과거의 관계**다: 같은 시뮬레이터 원본을 보는 두
+   * 트윈이 하나는 이어가고 하나는 매번 처음부터 재현할 수 있다. 그래서 축은 남고 이름만 바뀌었다.
+   *
+   * **비어 있을 수 없고, 기본값도 없다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로
+   * 떨어졌다 — 값이 하나 어긋나는 순간 이력을 지우는 길이다. 이제 읽는 쪽이 **오류를 낸다**
+   * (`engine/restart-policy.ts`). 선언은 프로비저닝하는 쪽의 몫이다.
    */
   @Column()
-  @Field({ description: "Reality source declaration: 'mirror' (external system is truth, resync on reboot) | 'sim-world' (generated timeline is truth and persists, resume on reboot) | 'sim-experiment' (seed-reproducible, resets on reboot)." })
-  realityMode: string
+  @Field({ description: "Restart policy: 'resync' (read again from the external source) | 'resume' (continue this twin's own journal) | 'reset' (wipe and replay from the seed). No default — an unspecified policy is refused." })
+  restartPolicy: string
 
   /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
      자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라

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'
 
@@ -14,7 +17,8 @@ import { domainCatalog } from './domain-catalog.js'
  * 트윈 인스턴스 생명주기 채널 — 프로비저닝(상향, ADR-0015).
  * State/Command/Scenario 는 이미 running 인 인스턴스를 다루지만, 이 채널은 인스턴스 자체를 만들고/설정하고/없앤다.
  * 생명주기: provision(save, 미기동) → start → stop → delete. 모두 domain 스코프(context.state.domain.id).
- * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 controlTwinScenario 로.
+ * model(TwinModelDef+layout)=구조, scenario=자극 은 분리 — 여기선 구조만 세운다. 자극은 **원본이 선언하고**
+ * (`TwinReference.connectionConfig.scenario`) 기동이 싣거나, 원본의 구동 능력으로 태운다(ADR-0029 §4·§8).
  */
 @Resolver()
 export class TwinLifecycleMutation {
@@ -60,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.' })
@@ -81,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 }
+  }
+
   /*
    * ── 이벤트 루프 부하 — **운영 계기판이다. 테넌트 기능이 아니다.** ─────────────
    *

package/server/service/twin-model/axis-journal-evidence.ts

@@ -0,0 +1,57 @@
+/*
+ * **저널에 그 축의 사실이 있나** — 「아직 없다」와 「왔는데 상태에 없다」를 가른다 (2026-08-22).
+ *
+ * ── 왜 필요했나 (실측) ──────────────────────────────────────────────────────
+ * 화면이 「작업 — 아직 하나도 없습니다」라고 말하는데, 그 트윈의 저널에는 `task.status` 5,786건이
+ * 있었고 **마지막 상태가 `in-progress`** 였다. 사용자가 「작업 지시 835건인데 작업이 0인 이유」를
+ * 물어 반나절을 조사해 원인을 찾았다: 관측 모드 커널이 관측기의 작업을 스냅샷으로 내보내지 않는다
+ * (커널 자리이고 그 레인에 넘겼다).
+ *
+ * 화면 몫은 다른 것이다. **카드가 단정하면 안 된다.** 「아직 하나도 없습니다」는 「선언은 있고 사실이
+ * 아직 일어나지 않았다」는 뜻인데, 실제로는 「사실이 일어났는데 상태에 오지 못했다」였다 — 그 차이가
+ * 사용자를 반나절 조사로 보낸다.
+ *
+ * 그래서 상태가 빈 축에 대해 **저널을 한 건만 물어본다.** 있으면 화면이 그렇게 말한다.
+ *
+ * ── 어휘의 집 ───────────────────────────────────────────────────────────────
+ * 어느 사건이 어느 축을 채우는지는 **커널이 선언한 낱말**에서 온다(`OP_EVENT`·`ENERGY_EVENT`, 그리고
+ * EPCIS 접두사). 여기서 이름을 새로 만들지 않는다 — 커널이 낱말을 늘리면 이 표에 한 줄이 늘고,
+ * 표에 없는 축은 **아무 말도 하지 않는다**(모르는 것을 지어내지 않는다).
+ */
+import { anyJournalRow } from '../twin-event/journal-count.js'
+
+/**
+ * 상태 축 → 그 축을 채우는 사건 낱말. 표에 없으면 판단하지 않는다.
+ *
+ * 물품은 EPCIS 로 온다(사건 이름이 여러 개다) — 그래서 접두사로 본다.
+ */
+const AXIS_EVENTS: Record<string, { types?: string[]; prefix?: string }> = {
+  tasks: { types: ['task.status'] },
+  orders: { types: ['order.status'] },
+  items: { prefix: 'epcis.' },
+  demandWindows: { types: ['energy.demand.window'] }
+}
+
+/** 이 축의 사실이 저널에 한 건이라도 있나. 판단할 수 없으면 `null`(모른다). */
+export async function axisSeenInJournal(
+  repo: any,
+  where: Record<string, unknown>,
+  axis: string
+): Promise<boolean | null> {
+  const spec = AXIS_EVENTS[axis]
+  if (!spec) return null
+
+  if (spec.types) {
+    for (const t of spec.types) {
+      if (await anyJournalRow(repo, { ...where, eventType: t })) return true
+    }
+    return false
+  }
+  /*
+   * 접두사로 찾는 축(물품) — 한 건만 있으면 된다. `Like` 를 쓰는 대신 **낱말 목록**을 쓰지 않는 이유는
+   * EPCIS 사건 이름이 커널에서 자라기 때문이다(객체·집약·변환·거래…). 이름을 여기 베끼면 커널이
+   * 하나 늘릴 때 이 자리가 조용히 낡는다.
+   */
+  const { Like } = await import('typeorm')
+  return anyJournalRow(repo, { ...where, eventType: Like(`${spec.prefix}%`) })
+}

package/server/service/twin-model/epcis-coverage.ts

@@ -15,7 +15,7 @@
  *
  * ISA-95 표와 같은 규율이다(`isa95-coverage.ts` 머리말): 사람이 판단해 적고, 틀리면 여기를 고친다.
  */
-import type { Isa95Concept, CoverageLevel } from './isa95-coverage.js'
+import { reconcileAxes, type Isa95Concept, type CoverageLevel } from './isa95-coverage.js'
 
 /* Part: EPCIS 2.0 의 사건 종류 — 무엇이 일어났는가. */
 const EVENTS: Isa95Concept[] = [
@@ -179,13 +179,7 @@ export function epcisCoverage(axes: string[]): {
   concepts: (Isa95Concept & { axisMissing?: boolean })[]
   totals: { concepts: number; structure: number; behavior: number; surface: number }
 } {
-  const known = new Set(axes)
-  const concepts = EPCIS_CONCEPTS.map(c => {
-    const axisMissing = !!c.axis && !known.has(c.axis)
-    const shownOn = c.shownOn?.filter(a => known.has(a))
-    const fixed = shownOn && shownOn.length !== c.shownOn?.length ? { ...c, shownOn } : c
-    return axisMissing ? { ...fixed, structure: 'none' as CoverageLevel, axisMissing } : fixed
-  })
+  const concepts = EPCIS_CONCEPTS.map(c => reconcileAxes(c, new Set(axes)))
   const count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
   return {
     model: 'GS1 EPCIS 2.0',

package/server/service/twin-model/iec61850-coverage.ts

@@ -14,7 +14,7 @@
  * ISA-95 표와 같은 규율이다(`isa95-coverage.ts` 머리말): 사람이 판단해 적고, 틀리면 여기를 고친다.
  * 자동으로 알 수 있는 것 하나만 자동으로 한다 — 축 이름이 커널 축 목록에 없으면 구조가 없는 것이다.
  */
-import type { Isa95Concept, CoverageLevel } from './isa95-coverage.js'
+import { reconcileAxes, type Isa95Concept, type CoverageLevel } from './isa95-coverage.js'
 
 /*
  * Part 7-4 — 논리 노드 클래스. 이 프로파일이 쓰는 것만 적는다(표준 전체를 옮기지 않는다):
@@ -100,13 +100,7 @@ export function iec61850Coverage(axes: string[]): {
   concepts: (Isa95Concept & { axisMissing?: boolean })[]
   totals: { concepts: number; structure: number; behavior: number; surface: number }
 } {
-  const known = new Set(axes)
-  const concepts = IEC61850_CONCEPTS.map(c => {
-    const axisMissing = !!c.axis && !known.has(c.axis)
-    const shownOn = c.shownOn?.filter(a => known.has(a))
-    const fixed = shownOn && shownOn.length !== c.shownOn?.length ? { ...c, shownOn } : c
-    return axisMissing ? { ...fixed, structure: 'none' as CoverageLevel, axisMissing } : fixed
-  })
+  const concepts = IEC61850_CONCEPTS.map(c => reconcileAxes(c, new Set(axes)))
   const count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
   return {
     /* 이름에 (vocabulary) 를 달아 둔다 — 프로토콜 적합성으로 읽히지 않게. */

package/server/service/twin-model/isa95-coverage.ts

@@ -166,20 +166,33 @@ export const ISA95_CONCEPTS: Isa95Concept[] = [...PART2, ...PART4]
  * `axis` 를 커널 축 목록과 맞춰 본다: 축이 있다고 적혀 있는데 커널에 없으면 그 선언이 낡은 것이므로
  * **구조 없음으로 낮추고 그 사실을 말한다**(조용히 통과시키면 이 표가 거짓이 된다).
  */
+/**
+ * 선언한 축을 커널의 축 목록과 맞춘다 — **어긋난 것을 조용히 지우지 않는다.**
+ *
+ * 두 자리가 어긋날 수 있다.
+ *  · `axis` — 그 개념 자신의 문. 커널에 없으면 구조를 「없음」으로 낮추고 그 사실을 말한다.
+ *  · `shownOn` — 그 사실을 들고 있는 다른 축. 예전에는 없는 축을 **말없이 걸러 냈다.** 그러면 그 줄은
+ *    「개념 축이 없습니다」로 보이고, 사람은 그것을 **원래 그런 것**으로 읽는다. 실제로 그 일이 있었다:
+ *    EPCIS 표의 일곱 줄이 커널에 없는 축(`items`)에 기대고 있었는데, 경고가 뜬 것은 두 줄뿐이었다.
+ *
+ * 둘 중 하나라도 어긋나면 `axisMissing` 이다 — 표가 스스로 「최신이 아니다」라고 말하게 한다.
+ */
+export function reconcileAxes(c: Isa95Concept, known: Set<string>): Isa95Concept & { axisMissing?: boolean } {
+  const ownMissing = !!c.axis && !known.has(c.axis)
+  const shownOn = c.shownOn?.filter(a => known.has(a))
+  const lostShown = !!c.shownOn && (shownOn?.length ?? 0) !== c.shownOn.length
+  const fixed = lostShown ? { ...c, shownOn } : c
+  if (!ownMissing && !lostShown) return fixed
+  /* 구조를 낮추는 것은 **자기 문이 없어진 경우**다 — 남의 축에서 보이던 것은 구조가 아니라 표시의 문제다. */
+  return ownMissing ? { ...fixed, structure: 'none' as CoverageLevel, axisMissing: true } : { ...fixed, axisMissing: true }
+}
+
 export function isa95Coverage(axes: string[]): {
   model: string
   concepts: (Isa95Concept & { axisMissing?: boolean })[]
   totals: { concepts: number; structure: number; behavior: number; surface: number }
 } {
-  const known = new Set(axes)
-  const concepts = ISA95_CONCEPTS.map(c => {
-    const axisMissing = !!c.axis && !known.has(c.axis)
-    /* 가리키는 곳이 없어진 축은 **가리키지 않는다** — 죽은 문으로 보내면 화면이 거짓말을 한다.
-       `axis` 와 같은 규율이고, 여기가 비면 그 줄은 다시 "축이 없다" 로 정직하게 돌아간다. */
-    const shownOn = c.shownOn?.filter(a => known.has(a))
-    const fixed = shownOn && shownOn.length !== c.shownOn?.length ? { ...c, shownOn } : c
-    return axisMissing ? { ...fixed, structure: 'none' as CoverageLevel, axisMissing } : fixed
-  })
+  const concepts = ISA95_CONCEPTS.map(c => reconcileAxes(c, new Set(axes)))
   /* 채운 수는 `full` 만 센다 — 부분을 채운 것으로 세면 기준이 스스로를 속인다. */
   const count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
   return {

package/server/service/twin-model/item-ref.ts

@@ -0,0 +1,80 @@
+/*
+ * **개체에서 품목으로** — 정체성 모양이 하나가 아니다 (2026-08-23).
+ *
+ * ── 무엇이 조용히 비어 있었나 ───────────────────────────────────────────────
+ * 화면이 「이 개체는 선언된 자재가 아닙니다(라인 내부의 중간 산물일 수 있습니다)」라고 말했는데, 그
+ * 품목은 원본의 선언에 이름까지 있었다(「냉동그린빈스」). 대응 표(`productionSpec.binding`)도 멀쩡했다.
+ *
+ * 원인은 **개체에서 품목을 꺼내는 규칙**이었다. 그 규칙이 GS1 SGTIN URN 하나만 알았다.
+ *
+ *   urn:epc:id:sgtin:0614141.077101.42   →  077101      (알던 모양)
+ *   https://…/class/product-M0000438@M2R0001  →  null    (모르던 모양)
+ *
+ * 웹 URI 로 정체성을 말하는 원본에서는 언제나 `null` 이 나왔고, 그래서 **개체를 자재에 이을 수 없었다.**
+ * 그 결과가 화면 두 곳에서 조용한 빈칸이었다(계보 적합성 · 오더가 무엇을 만드나). 「없으면 붙이지
+ * 않는다」는 규율을 지키기 때문에 아무 오류도 나지 않았다.
+ *
+ * ── 무엇을 돌려주나 ─────────────────────────────────────────────────────────
+ * **그 트윈의 대응 표가 쓰는 것과 같은 모양**이다. 두 세계가 서로 다른 것을 값으로 쓴다.
+ *
+ *   SGTIN 세계   binding 값 = 품목 참조 숫자(`077101`)      → 숫자를 돌려준다
+ *   URI 세계     binding 값 = 클래스 URI(`…/product-M…`)    → 클래스 URI 를 돌려준다
+ *
+ * 그래서 두 세계를 한 함수가 답한다 — 부르는 자리가 원본의 정체성 방식을 알지 않아도 된다.
+ *
+ * ── 무엇을 지어내지 않나 ────────────────────────────────────────────────────
+ * **어느 부호가 개체를 가리키는지 모른다.** 그것은 원본마다 다르고 커널 계약이 정한 적이 없다 — 한
+ * 원본(chef)이 쓰는 `@` 를 규칙으로 굳히면 이 화면이 그 레거시 위에 서게 된다. 자르는 판단은 그 트윈의
+ * **선언**이 하고(§`resolveByDeclaration`), 후보가 둘 이상이면 답하지 않는다. 짐작으로 이으면 남의
+ * 레시피와 견주게 되고, 그것이 「설계와 다르다」는 거짓 진단이 된다.
+ */
+
+/**
+ * 개체 식별자 → **품목 참조**. 대응 표의 값과 견줄 수 있는 모양으로 돌려준다.
+ *
+ * SGTIN 은 표준이 자리를 정해 두었으므로 그 자리에서 품목 참조를 꺼낸다. 그 밖의 모양은 **손대지
+ * 않는다** — 어느 부호가 개체를 가리키는지는 원본마다 다르고, 커널 계약이 그 구분자를 정한 적이 없다.
+ * 앞서 이 자리에 「`@` 뒤는 개체다」를 넣었는데, 그것은 한 원본(chef)의 모양을 규칙으로 굳힌 것이었다.
+ *
+ * 그래서 자르는 일은 여기서 하지 않고, **그 트윈의 선언과 견주어** 판정한다(§`resolveByDeclaration`).
+ * 선언이 답을 주지 못하면 `null` 이다 — 짐작으로 이으면 남의 레시피와 견주게 되고, 그것이 「설계와
+ * 다르다」는 거짓 진단이 된다.
+ */
+export function itemRefOf(epc: unknown): string | null {
+  if (typeof epc !== 'string') return null
+  const s = epc.trim()
+  if (!s) return null
+
+  /* GS1 SGTIN — 회사 접두사와 일련번호 사이의 품목 참조. `idpat` 의 `*` 도 같은 자리에서 걸린다. */
+  const sgtin = /sgtin:[^.]+\.([^.]+)\./.exec(s)
+  if (sgtin) return sgtin[1]
+
+  /* 그 밖의 정체성(웹 URI 등)은 그대로 낸다 — 자르는 판단은 선언이 한다. */
+  return s
+}
+
+/**
+ * 이 식별자가 가리키는 **선언 항목**을 찾는다 — 원본의 정체성 관행을 알지 않고, 구분자도 모른다.
+ *
+ * 세 가지를 차례로 본다. 어느 단계든 **후보가 둘 이상이면 답하지 않는다**(모르는 것이 틀린 답보다 낫다).
+ *
+ *  ① 그대로 같다
+ *  ② 관측된 식별자가 선언을 **확장**한다 — 개체는 자기 클래스로 시작한다(`…/product-M1` + 개체 표시)
+ *  ③ 화면이 **짧게 줄인** 식별자를 건넸다 — 선언이 그것으로 끝난다(`net/class/product-M1`)
+ *
+ * ②③은 부호를 모른다. 그래서 원본이 `@`·`#`·`/` 무엇을 쓰든, 또는 아무것도 쓰지 않든 같은 규칙이 선다.
+ */
+export function resolveByDeclaration<T>(ref: string | null, declared: Map<string, T>): T | undefined {
+  if (!ref) return undefined
+  const exact = declared.get(ref)
+  if (exact !== undefined) return exact
+  let hit: T | undefined
+  let found = 0
+  for (const [id, value] of declared) {
+    if (!(ref.startsWith(id) || id.endsWith(ref))) continue
+    found++
+    if (found > 1) return undefined
+    hit = value
+  }
+  return hit
+}