@things-factory/headless-twin 10.0.11 → 10.0.13

package/server/service/twin-model/name-index.ts

@@ -0,0 +1,94 @@
+/*
+ * 항목의 **이름**을 붙이는 자리 — 화면이 id 만 보이지 않게. (2026-08-22 공용으로 옮김)
+ *
+ * 이 둘은 항목 질의 안에 사적으로 있었다. 그런데 **전개(BOM 나무) 화면도 같은 이름이 필요하다** —
+ * 사용자가 「각 노드의 식별자가 반복되어서 이해가 어렵다. 식별자와 이름이 보이면」이라고 했다.
+ * 두 벌을 만들면 한쪽만 고쳐지므로 한 곳에 둔다(재발명 금지).
+ */
+/* 커널 런타임 로드 — 어느 축이 있는지는 카탈로그가 선언한다(이 파일은 도메인 모양을 알지 않는다). */
+const { TWIN_AXES, axisSource } = require('@operato/twin-kernel')
+
+/** `productionSpec.definition.recipes` 같은 경로를 문서에서 따라간다. */
+export const at = (o: any, path: string) => path.split('.').reduce((a: any, k: string) => (a == null ? undefined : a[k]), o)
+
+/**
+ * 문서 항목의 **식별자** — 축마다 이름이 다르다(자리는 `id`, 공정은 `key`, 레시피도 `key`).
+ *
+ * 도메인 모양을 코드가 아는 것이 아니라 **식별자 관례**를 아는 것이다. 후보를 순서대로 보고 첫
+ * 값을 쓴다. 하나도 없으면 그 항목은 가리킬 수 없으므로 `null` — 목록에서 빼지 않고 **id 없음**으로
+ * 낸다(조용히 빠지면 건수가 안 맞는다).
+ */
+export const idOf = (o: any, info?: { idField?: string | string[] }): string | null => {
+  if (typeof o === 'string') return o
+  /*
+   * **무엇이 이 항목을 가리키는지는 선언이 말한다**(§`TwinAxisInfo.idField`).
+   *
+   * 예전에는 `id`·`key`·`gtin` 을 짐작했다. 그래서 `id` 가 없는 축(수요 구간 — 정체성이 구간 시작
+   * 시각이다)의 항목이 전부 「식별자 없음 — 참조할 수 없는 항목」으로 보였다. 값은 실재하는데
+   * 가리킬 수 없다고 말한 것이다.
+   */
+  /*
+   * 선언이 **차례**를 말할 수 있다(2026-08-22) — 정체성이 한 칸으로 정해지지 않는 축이 있다. 물품이
+   * 그렇다: 직렬 물품은 `epc` 가 유일하지만 비직렬 로트가 자리마다 나뉘면 `subLotId` 가 개체를
+   * 구별한다(같은 로트의 두 부분은 같은 `epc` 를 갖는다). 앞에서 값이 있는 첫 칸이 이긴다.
+   */
+  for (const f of info?.idField ? (Array.isArray(info.idField) ? info.idField : [info.idField]) : []) {
+    const v = o?.[f]
+    if (v !== undefined && v !== null) return String(v)
+  }
+  return o?.id ?? o?.key ?? o?.gtin ?? null
+}
+
+
+/**
+ * **id → 이름**, 모든 축을 한 표로.
+ *
+ * ── 왜 이 표가 필요한가 ──────────────────────────────────────────────────────
+ * 행은 다른 것을 **id 로** 가리킨다(사람의 `personnelClassIds`, 설비의 `homeLocationId`, 공정의
+ * `locationType`). 그 id 의 이름은 **가리켜진 축의 행**에 있으므로, 화면이 그것을 알려면 축을
+ * 하나씩 더 읽어야 한다 — 그래서 지금까지 표면마다 그냥 id 를 찍었다(`cutter-op`, `cut-station`).
+ * 표면을 하나씩 고치는 것은 끝이 없다: 새 화면은 처음부터 다시 id 를 찍는다.
+ *
+ * 그래서 **서버가 붙인다.** 서버는 이미 모델을 손에 들고 있고, 어느 축이 있는지는 커널 카탈로그가
+ * 선언한다(`TWIN_AXES`) — 도메인이 늘어도 이 함수는 그대로다.
+ *
+ * 값은 그 항목이 **자기 이름이라고 말한 것**이다(`name`·`label`·`description`). 그중 어떤 것은
+ * i18n 키이므로(등급의 `description`) 번역은 화면의 일로 남긴다. 이름이 없으면 표에 넣지 않는다 —
+ * 없는 것을 지어내지 않고, 그 경우 화면은 id 를 그대로 보인다.
+ */
+export function nameIndex(model: any): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const info of TWIN_AXES as any[]) {
+    /* 관측 축(상태·저널)은 문서에 없다 — 경로가 없는 축을 읽으면 모델 루트를 훑는다. */
+    if (axisSource(info.axis) !== 'document') continue
+    const raw = at(model ?? {}, info.path)
+    const list = Array.isArray(raw) ? raw : raw ? [raw] : []
+    for (const o of list) {
+      const id = idOf(o)
+      if (!id || typeof o !== 'object') continue
+      const label = o.name ?? o.label ?? o.description
+      /* 이름이 id 와 같으면 표에 넣지 않는다 — 같은 값을 두 번 보이는 셈이다. */
+      if (typeof label === 'string' && label && label !== id && !out[id]) out[id] = label
+    }
+  }
+  return out
+}
+
+
+/**
+ * 이 응답이 **실제로 가리킨 것만** 골라 낸다.
+ *
+ * 모델 전체 표를 그대로 실으면 자리가 10만인 현장에서 목록 한 페이지에 10만 줄짜리 이름표가
+ * 따라온다. 나온 값에 걸리는 것만 싣는다 — 규모에서 성립하는 유일한 방식이다.
+ */
+export function namesFor(rows: any[], index: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {}
+  const take = (v: any, depth: number): void => {
+    if (v == null || depth > 4) return
+    if (typeof v === 'string') { if (index[v]) out[v] = index[v]; return }
+    if (Array.isArray(v)) { for (const x of v) take(x, depth + 1); return }
+    if (typeof v === 'object') for (const x of Object.values(v)) take(x, depth + 1)
+  }
+  for (const r of rows) { take(r?.fields ?? r, 0); if (typeof r?.id === 'string' && index[r.id]) out[r.id] = index[r.id] }
+  return out
+}

package/server/service/twin-model/project-structure.ts

@@ -43,7 +43,7 @@ export async function projectStructure(domainId: string, instanceId: string, mod
   if (!instance) throw new Error(`cannot project structure: twin instance "${instanceId}" is not registered`)
 
   /*
-   * **같은 id 가 둘이면 그 사실을 말한다** — 제약 위반 문구를 사용자에게 던지지 않는다.
+   * **같은 id 가 둘이면 그 사실을 말한다** — 제약 위반 문구를 사용자에게 보이지 않는다.
    *
    * 실측(2026-08-18): 현장 값을 그 현장의 트윈 전부에 얹다가 한 트윈에서 투영이 터졌다. 올라온 것은
    * `SQLITE_CONSTRAINT: UNIQUE constraint failed: twin_equipment...` 뿐이라 **무엇이 잘못됐는지 아무도

package/server/service/twin-model/status-tally.ts

@@ -0,0 +1,37 @@
+/*
+ * **수 하나가 뜻을 바꾸는 자리** — 상태별로 갈라 센다 (2026-08-23).
+ *
+ * ── 무엇이 있었나 ───────────────────────────────────────────────────────────
+ * 미러가 완료된 작업까지 상태에 들고 있게 되면서(관측 흡수에서 `completed` 를 떨어뜨리지 않게 커널을
+ * 고친 뒤) 개념 지도의 작업 카드가 「0」에서 「2,820」이 되었다. 이 카드는 **상태의 인구조사**이므로
+ * 그 수가 맞다 — 그런데 사람은 그것을 「지금 할 일 2,820건」으로 읽는다.
+ *
+ * 수를 줄여 맞는 척하게 만들지 않는다(그러면 인구조사가 거짓이 된다). 대신 **무엇으로 이루어진
+ * 수인지** 함께 낸다: 「진행 중 28 · 완료 2,792」.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ *  · 낱말은 **커널이 실어 보낸 그대로**다. 여기서 묶거나 고쳐 부르지 않는다(화면이 라벨을 입히고,
+ *    라벨이 없으면 낱말이 그대로 보여 누락이 드러난다).
+ *  · 상태를 말하지 않는 축은 **아무것도 내지 않는다.** 빈 표를 내면 화면이 「상태가 없는 축」과
+ *    「상태를 못 읽은 축」을 구별할 수 없다.
+ *  · 한 번만 훑는다. 카드가 이미 같은 배열의 길이를 세므로 셈이 한 벌 늘지 않는다.
+ */
+
+/** 상태 한 갈래와 그 건수. */
+export interface StatusCount {
+  status: string
+  count: number
+}
+
+/** 이 축의 개체를 상태별로 센다. 상태가 없으면 빈 객체(필드를 만들지 않는다). */
+export function statusTally(bucket: unknown): { statusCounts?: StatusCount[] } {
+  if (!Array.isArray(bucket) || !bucket.length) return {}
+  const tally = new Map<string, number>()
+  for (const e of bucket) {
+    const s = (e as any)?.status
+    if (typeof s !== 'string' || !s) continue
+    tally.set(s, (tally.get(s) ?? 0) + 1)
+  }
+  if (!tally.size) return {}
+  return { statusCounts: [...tally].map(([status, count]) => ({ status, count })).sort((x, y) => y.count - x.count) }
+}

package/server/service/twin-model/twin-lineage-query.ts

@@ -2,6 +2,8 @@ import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
+import { itemRefOf, resolveByDeclaration } from './item-ref.js'
+
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinEvent } from '../twin-event/twin-event.js'
 
@@ -24,11 +26,6 @@ import { TwinEvent } from '../twin-event/twin-event.js'
  * 읽히고, 계보에서 그 오해는 리콜 범위를 좁게 잡는 결과로 이어진다.
  */
 
-/** GS1 SGTIN 의 **품목 참조** — 개체(serial)를 떼고 품목만 남긴다(`…sgtin:0614141.077101.42` → `077101`). */
-function itemRefOf(epc: string): string | null {
-  const m = /sgtin:[^.]+\.([^.]+)\./.exec(epc)
-  return m ? m[1] : null
-}
 
 @Resolver()
 export class TwinLineageQuery {
@@ -110,18 +107,50 @@ export class TwinLineageQuery {
     const spec: any = (inst.model as any)?.productionSpec
     const binding: Record<string, string> = spec?.binding ?? {}
     const refToMaterial = new Map(Object.entries(binding).map(([mat, ref]) => [String(ref), mat]))
-    const materialOf = (e: string) => {
-      const ref = itemRefOf(e)
-      return ref ? refToMaterial.get(ref) ?? null : null
-    }
+    /*
+     * ── **화면은 끝마디로 묻는다** (2026-08-23) ─────────────────────────────────
+     *
+     * 서랍의 포커스 식별자는 클래스의 끝마디다(`net/class/product-M0000438`). 대응 표의 값은 전체
+     * 식별자(`https://…/class/product-M0000438`)이므로 곧바로는 맞지 않고, 그래서 「선언된 자재가
+     * 아닙니다」가 떴다 — 그 품목은 대응 표에 있었다.
+     *
+     * 끝마디로도 찾되 **하나뿐일 때만** 인정한다. 둘 이상이 같은 끝마디를 가지면 어느 것인지 모르므로
+     * 아무 말도 하지 않는다 — 짐작으로 이으면 남의 레시피와 견주게 되고, 그것이 「설계와 다르다」는
+     * 거짓 진단이 된다.
+     */
+    const materialOf = (e: string) => resolveByDeclaration(itemRefOf(e), refToMaterial) ?? null
 
     const myMaterial = materialOf(epc)
     const recipes: any[] = spec?.definition?.recipes ?? []
     const recipe = myMaterial ? recipes.find((r: any) => (r.outputs ?? []).some((o: any) => o.material === myMaterial)) : undefined
 
+    /*
+     * ── 「모르는 개체」와 「대응이 없는 개체」는 다른 사실이다 (2026-08-23) ──────
+     *
+     * 화면이 「이 개체는 선언된 자재가 아닙니다(라인 내부의 중간 산물일 수 있습니다)」라고 말했는데,
+     * 그 품목은 원본의 품목 선언에 **이름까지 있었다**(「냉동그린빈스」). 바인딩 표가 그 품목을 담지
+     * 못한 것이고, 그것은 「중간 산물」과 전혀 다른 이야기다 — 사용자가 할 일도 다르다(원본을 볼 일이
+     * 아니라 대응을 고칠 일이다).
+     *
+     * 그래서 개체가 가리키는 품목이 **모델의 품목 선언에 있는지** 함께 본다. 이름은 그 자리에 있으니
+     * 함께 낸다(화면이 사람에게 무엇을 말하는지 알 수 있게).
+     */
+    const definitions: any[] = (inst.model as any)?.materialDefinitions ?? []
+    const defByRef = new Map(definitions.filter(d => d?.id).map(d => [String(d.id), d]))
+    /* 정의도 같은 문으로 되찾는다 — 규칙 하나, 후보가 둘 이상이면 답하지 않는다. */
+    const myRef = itemRefOf(epc)
+    const myDef = resolveByDeclaration(myRef, defByRef)
+
     let conformance: any = null
     if (!Object.keys(binding).length) {
       conformance = { comparable: false, reason: 'no-binding' }
+    } else if (!myMaterial && myDef) {
+      /* 원본은 이 품목을 안다 — 개체를 자재에 잇는 대응이 없어서 비교하지 못한다. */
+      conformance = {
+        comparable: false,
+        reason: 'item-known-not-bound',
+        ...(typeof myDef.name === 'string' && myDef.name ? { itemName: myDef.name } : {})
+      }
     } else if (!myMaterial) {
       conformance = { comparable: false, reason: 'item-not-bound' }
     } else if (!recipe) {

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

@@ -2,14 +2,19 @@ import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
+import { itemRefOf } from './item-ref.js'
+
 import { TwinEngine } from '../../engine/index.js'
 import { unwrapState } from '../../engine/warm-start.js'
 import { propertyEffectsOf } from '../../engine/property-effects.js'
+/* 축이 사는 자리를 읽는 **한 곳** — 카드(`twin-model-query`)와 같은 규칙을 쓴다. */
+import { axisValueOf } from '@things-factory/headless-twin/dist-shared/axis-read.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinLocation } from './twin-location.js'
 import { TwinEquipment } from './twin-equipment.js'
 import { TwinOperation } from './twin-operation.js'
 import { TwinArea } from '../twin-space/twin-area.js'
+import { at, idOf, nameIndex, namesFor } from './name-index.js'
 
 /* 커널 런타임 로드 — 축·관계·속성 선언의 SSOT. 이 파일은 도메인 모양을 알지 않는다. */
 const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, relationsFrom, relationsTo, propertiesOf } = require('@operato/twin-kernel')
@@ -26,17 +31,6 @@ const ROW_BACKED: Record<string, { entity: any; idColumn: string; order: any }>
   operations: { entity: TwinOperation, idColumn: 'operationKey', order: { seq: 'ASC' } }
 }
 
-/** `productionSpec.definition.recipes` 같은 경로를 문서에서 따라간다. */
-const at = (o: any, path: string) => path.split('.').reduce((a: any, k: string) => (a == null ? undefined : a[k]), o)
-
-/**
- * 문서 항목의 **식별자** — 축마다 이름이 다르다(자리는 `id`, 공정은 `key`, 레시피도 `key`).
- *
- * 도메인 모양을 코드가 아는 것이 아니라 **식별자 관례**를 아는 것이다. 후보를 순서대로 보고 첫
- * 값을 쓴다. 하나도 없으면 그 항목은 가리킬 수 없으므로 `null` — 목록에서 빼지 않고 **id 없음**으로
- * 낸다(조용히 빠지면 건수가 안 맞는다).
- */
-const idOf = (o: any): string | null => (typeof o === 'string' ? o : o?.id ?? o?.key ?? o?.gtin ?? null)
 
 /** 검색 — 항목의 값 어디든 걸리면 맞는 것으로 본다. 축마다 검색 컬럼을 정해 두면 축이 늘 때마다 여기를 고쳐야 한다. */
 function matches(o: any, q: string): boolean {
@@ -142,7 +136,7 @@ export class TwinModelItemQuery {
         truncated: rows.length >= SCAN_MAX,
         ...(() => {
           const items = hit.slice(skip, skip + take).map((r: any) => this.rowItem(axis, r))
-          return { items, names: this.namesFor(items, this.nameIndex(inst.model ?? {})) }
+          return { items, names: namesFor(items, nameIndex(inst.model ?? {})) }
         })()
       }
     }
@@ -188,12 +182,15 @@ export class TwinModelItemQuery {
       if (!snap) {
         return { axis, label: info.label, basis: 'state', total: null, observed: false, offset: skip, items: [] }
       }
-      const bucket = (snap as any)[axis]
+      /* 축이 사는 자리는 **커널 선언이 말한다**(`path`) — 축 이름으로만 읽으면 중첩된 축이 언제나
+         비어 보인다. 카드는 `axisValueOf` 로 읽는데 여기가 그 규칙을 지나지 않아, 「42」를 센 개념의
+         목록이 「0건」으로 나왔다(에너지의 수요 구간). 규칙의 집은 `axisValueOf` 하나다. */
+      const bucket = axisValueOf(snap, info)
       const list: any[] = Array.isArray(bucket) ? bucket : []
       const hitState = q ? list.filter(o => matches(o, q)) : list
       const items = hitState
         .slice(skip, skip + take)
-        .map(o => ({ id: idOf(o), fields: this.withOrderMaterial(axis, inst.model ?? {}, o) }))
+        .map(o => ({ id: idOf(o, info), fields: this.withOrderMaterial(axis, inst.model ?? {}, o) }))
       return {
         axis,
         label: info.label,
@@ -206,7 +203,7 @@ export class TwinModelItemQuery {
         offset: skip,
         resourceClassLabels: this.classLabels(inst.model ?? {}),
         items,
-        names: this.namesFor(items, this.nameIndex(inst.model ?? {}))
+        names: namesFor(items, nameIndex(inst.model ?? {}))
       }
     }
 
@@ -233,7 +230,7 @@ export class TwinModelItemQuery {
         const items = hit
           .slice(skip, skip + take)
           .map(o => ({ id: idOf(o) ?? (singular ? axis : null), fields: this.withBinding(axis, inst.model ?? {}, o) }))
-        return { items, names: this.namesFor(items, this.nameIndex(inst.model ?? {})), singular }
+        return { items, names: namesFor(items, nameIndex(inst.model ?? {})), singular }
       })()
     }
   }
@@ -298,10 +295,9 @@ export class TwinModelItemQuery {
     const binding: Record<string, string> = model?.productionSpec?.binding ?? {}
     const refToMaterial = new Map(Object.entries(binding).map(([mat, r]) => [String(r), mat]))
     /* 단일 품목 작업지시는 `gtin`, 여러 품목이면 라인마다 말한다 — 첫 라인으로 대표하지 않는다. */
-    const refOf = (v: unknown): string | null => {
-      const m = typeof v === 'string' ? /sgtin:[^.]+\.([^.]+)\./.exec(v) : null
-      return m ? m[1] : null
-    }
+    /* 정체성 모양은 하나가 아니다 — 규칙의 집은 `item-ref` 하나다(웹 URI 원본에서 이 자리가 언제나
+       빈칸이었다). */
+    const refOf = itemRefOf
     const mat = refToMaterial.get(String(refOf(fields.gtin) ?? ''))
     if (mat) return { ...fields, material: mat }
     const lineMats = (fields.lines ?? [])
@@ -359,8 +355,9 @@ export class TwinModelItemQuery {
           /* 다시 계산할 것이 없다 — 아래에서 "모른다" 를 낸다(0 으로 메우지 않는다). */
         }
       }
-      const bucket = snap ? (snap as any)[axis] : null
-      const found = Array.isArray(bucket) ? bucket.find((o: any) => idOf(o) === itemId) : undefined
+      /* 같은 규칙 — 축 이름이 아니라 선언된 자리에서 읽는다(§axisValueOf). */
+      const bucket = snap ? axisValueOf(snap, info) : null
+      const found = Array.isArray(bucket) ? bucket.find((o: any) => idOf(o, info) === itemId) : undefined
       if (!snap || !found) {
         return {
           instanceId, axis, label: info.label, itemId,
@@ -373,7 +370,7 @@ export class TwinModelItemQuery {
           names: {}, provenance: { basis: 'state' }
         }
       }
-      const names = this.namesFor([{ id: itemId, fields: found }], this.nameIndex(inst.model ?? {}))
+      const names = namesFor([{ id: itemId, fields: found }], nameIndex(inst.model ?? {}))
       return {
         instanceId, axis, label: info.label, itemId,
         identity: { standardClass: info.standardClass ?? null, typeRole: info.typeRole ?? null, kind: info.kind, gs1Scheme: info.gs1Scheme ?? null },
@@ -509,9 +506,9 @@ export class TwinModelItemQuery {
        * **이웃의 이름도 함께 싣는다.** 관계 그림의 이웃은 대개 *들어오는* 링크(이 자리를 기준 자리로
        * 삼는 설비·사람)라, 이 항목 자신의 필드에는 그 id 가 없다 — 필드만 훑으면 그림이 id 로 채워진다.
        */
-      names: this.namesFor(
+      names: namesFor(
         [{ id: itemId, fields: declared }, { fields: observed }, { fields: links }],
-        { ...this.nameIndex(model), ...areaNames }
+        { ...nameIndex(model), ...areaNames }
       ),
       provenance
     }
@@ -665,14 +662,16 @@ export class TwinModelItemQuery {
         return { absence: 'not-running' as const }
       }
     }
-    const bucket = state ? (state as any)[axis] : null
+    /* 같은 규칙 — 선언된 자리에서 읽는다. 축 이름으로 읽으면 중첩된 축이 언제나 「관측 없음」이 된다. */
+    const bucket = state ? axisValueOf(state, axisInfo(axis) ?? { axis }) : null
     /*
      * **왜 관측이 없는지 말한다.** 예전에는 그냥 `null` 이었고 화면은 그것을 "트윈이 실행 중이지 않아"
      * 로 읽었다 — 실행 중인데도 그렇게 말했다(공정 상세에서 관측됨). 공정·레시피처럼 **관측 축이
      * 아닌 것**은 트윈이 돌든 말든 관측이 없다. 이유가 다르면 화면이 다르게 말해야 한다.
      */
     if (!Array.isArray(bucket)) return { absence: 'not-observed' as const }
-    const value = bucket.find((x: any) => x?.id === itemId)
+    /* 같은 규칙 — 선언이 말하는 자리로 찾는다. `id` 로만 찾으면 수요 구간을 열 수 없다. */
+    const value = bucket.find((x: any) => idOf(x, axisInfo(axis)) === itemId)
     if (!value) return { absence: 'not-observed' as const }
     return { value, basis: live ? 'state' : 'journal', ...(folded != null ? { foldedRevision: folded } : {}) }
   }

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

@@ -1,8 +1,12 @@
+import { axisSeenInJournal } from './axis-journal-evidence.js'
+import { statusTally } from './status-tally.js'
+import { TwinEvent } from '../twin-event/twin-event.js'
 import { Arg, Ctx, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { modelGapOf } from '../../engine/model-gap.js'
 import { readBoardEquipment } from '@operato/twin-kernel'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinSpace } from '../twin-space/twin-space.js'
@@ -98,6 +102,27 @@ function valuesAt(obj: any, field: string): any[] {
 
 const idOf = (o: any): string | null => (typeof o === 'string' ? o : o?.id ?? o?.key ?? o?.gtin ?? null)
 
+/** 상태가 빈 축의 이유 — 저널에 그 사실이 있으면 그렇게 말한다. 판단할 수 없으면 예전 그대로. */
+async function emptyStateReason(domainId: string, instanceId: string, axis: string): Promise<string> {
+  try {
+    const seen = await axisSeenInJournal(getRepository(TwinEvent), { domain: { id: domainId }, instanceId }, axis)
+    /* 판단할 수 없는 축(`null`)은 예전 답을 그대로 쓴다 — 모르는 것을 새 사실로 만들지 않는다. */
+    return seen ? 'observed-not-in-state' : 'none-yet'
+  } catch {
+    /* 저널을 못 읽었다고 카드가 없는 말을 하지는 않는다. */
+    return 'none-yet'
+  }
+}
+
+/**
+ * 되세운 상태를 담아 둔다 — **열쇠에 저널 끝 리비전이 들어 있어** 새 사건이 오면 저절로 낡는다.
+ *
+ * 접기는 저널 전체를 훑는 일이라(리비전 12만에서 2~3초) 모델 화면을 열 때마다 그 값을 낼 수 없다.
+ * 프로세스 안에만 두고 몇 개만 남긴다 — 다시 뜨면 다시 접는다(정확함이 캐시보다 앞선다).
+ */
+const RECALL_CACHE = new Map<string, { snap: any; heardAt: string | null }>()
+const RECALL_CACHE_MAX = 8
+
 @Resolver()
 export class TwinModelQuery {
   /**
@@ -188,6 +213,60 @@ export class TwinModelQuery {
         }
         return { snap, folded, observing }
       })())
+
+    /*
+     * ── **라이브가 잊은 것을 저널이 안다** (2026-08-23) ─────────────────────────
+     *
+     * 미러의 관측은 메모리에만 산다. 재기동하면 빈 채로 시작하고, 원본이 다시 말해 줄 때 채워진다 —
+     * 그런데 읽기 커서가 정직해진 뒤로는 원본이 **지난 것을 다시 말하지 않는다.** 그래서 재고 741건이
+     * 저널에 있는데 화면은 「0」을 보였다. 사용자가 「재고현황이 없다」고 물은 자리가 이것이다.
+     *
+     * 그 0 은 사실이 아니라 **우리가 잊은 것**이다. 저널을 접으면 그대로 되살아난다(실측: 리비전
+     * 97,689 을 2.4초에 접어 물품 741 · 작업 9,145 · 지시 2,856).
+     *
+     * ── 그래서 접는다. 다만 **언제 들은 값인지 함께 낸다** ──────────────────────
+     * 저널을 접는 것은 **원천이 우리에게 말한 것을 다시 세우는 일**이지, 없는 값을 심는 일이 아니다.
+     * 그러나 물품·재고처럼 **절대값인 축**은 우리가 못 듣는 사이 떠났을 수 있다 — 그래서 값과 함께
+     * `heardAt`(그 접기의 시계)을 낸다. 사용자가 신선도를 스스로 판정할 수 있어야 하고, 화면은 그것을
+     * 값 옆에 적는다. 시각 없이 수만 내면 낡은 값을 지금으로 읽는다.
+     *
+     * 접는 조건을 좁게 둔다: **관측 축이 비어 있고, 저널에 그 축의 사실이 있을 때만**(그 판정은 색인
+     * 한 줄이다). 그리고 한 요청에 **한 번만** 접는다 — 위 `stateOnce` 와 같은 규율이다.
+     */
+    let journalPromise: Promise<{ snap: any; heardAt: string | null } | null> | null = null
+    const journalOnce = () =>
+      (journalPromise ??= (async () => {
+        try {
+          const tip = await getRepository(TwinEvent).findOne({
+            where: { domain: { id: domainId } as any, instanceId } as any,
+            order: { revision: 'DESC' } as any
+          })
+          if (!tip?.revision) return null
+          /*
+           * **한 번 접은 것을 다시 접지 않는다.** 접기는 저널 전체를 훑는 일이다(리비전 12만에서 2~3초).
+           * 이 화면은 사람이 여러 번 들어오는 자리이므로 그대로 두면 매번 그 값을 낸다 — 그리고 저널이
+           * 수백만 행이 되면 그 비용이 화면을 못 쓰게 만든다.
+           *
+           * 열쇠에 **저널 끝의 리비전**을 넣는다: 새 사건이 오면 열쇠가 달라지므로 캐시가 저절로 낡는다
+           * (캐시가 사실을 이기지 않는다). 프로세스 안에만 두고 몇 개만 남긴다.
+           */
+          const key = `${domainId}:${instanceId}:${tip.revision}`
+          const hit = RECALL_CACHE.get(key)
+          if (hit) return hit
+          const snap = unwrapState(await TwinEngine.recover(domainId, instanceId, tip.revision))
+          if (!snap) return null
+          /* 그 접기의 시계가 「언제 들은 값인가」다. 없으면 저널 끝의 사건 시각으로 답한다. */
+          const out = { snap, heardAt: (snap as any).nowTime ?? tip.eventTime ?? null }
+          RECALL_CACHE.set(key, out)
+          /* 오래된 열쇠부터 버린다 — 트윈 몇 개를 번갈아 봐도 메모리가 자라지 않게. */
+          while (RECALL_CACHE.size > RECALL_CACHE_MAX) RECALL_CACHE.delete(RECALL_CACHE.keys().next().value as string)
+          return out
+        } catch {
+          /* 접지 못했으면 아무 말도 만들지 않는다 — 라이브가 말한 것을 그대로 둔다. */
+          return null
+        }
+      })())
+
     const concepts = await Promise.all(
       TWIN_AXES.map(async (a: any) => {
         /*
@@ -210,6 +289,17 @@ export class TwinModelQuery {
             count: null,
             notApplicable: true,
             emptyBecause: 'not-applicable',
+            /*
+             * **그 개념의 성질** — 선언인가 관측인가 (2026-08-22).
+             *
+             * `basis` 와 다르다: `basis` 는 「이 값이 어디서 왔나」이고 트윈마다·시점마다 달라진다(같은
+             * 축이 한 트윈에서 `journal`, 다른 트윈에서 `state` 로 온다). 그것으로 묶으면 같은 축이 화면
+             * 마다 다른 묶음에 들어간다. `source` 는 트윈과 무관하게 고정이므로 묶는 축이 된다.
+             *
+             * 화면이 축 이름을 열거하지 않아도 되고, 축이 늘면 자동으로 맞는 묶음에 들어간다 —
+             * 카탈로그가 정본이다.
+             */
+            source: axisSource(a.axis),
             basis: 'declaration'
           }
         }
@@ -243,6 +333,15 @@ export class TwinModelQuery {
          * 0 으로 내면 "작업이 없는 공장" 으로 읽히고, 그건 거짓이다(관측이 없는 것과 0 건은 다르다).
          * 이 화면이 관측 열에서 내내 지켜 온 구분을 카드에서도 지킨다.
          */
+        /*
+         * **「아직 없다」와 「왔는데 상태에 없다」는 다른 사실이다** (2026-08-22).
+         *
+         * 화면이 「작업 — 아직 하나도 없습니다」라고 말했는데 저널에는 `task.status` 5,786건이 있었고
+         * 마지막 상태가 `in-progress` 였다(원인은 커널의 내보내기였고 그 레인에 넘겼다). 카드가 단정한
+         * 탓에 사용자가 그 차이를 직접 조사해야 했다 — 화면이 아는 것을 말하지 않은 자리다.
+         *
+         * 그래서 상태가 빈 축은 저널을 **한 건만** 물어본다(색인 한 줄, `journal-count` 의 문).
+         */
         if (axisSource(a.axis) === 'state') {
           /* 스냅샷은 `{revision, state}` 봉투다 — 벗기지 않으면 축이 한 겹 안에 있어 언제나 `null` 이
              된다(커널은 도는데 카드가 "모름" 으로 보였다). 벗기는 규칙의 집은 `warm-start` 하나다. */
@@ -255,7 +354,25 @@ export class TwinModelQuery {
           const { snap, folded, observing } = await stateOnce()
           /* 축이 사는 자리는 **커널 선언이 말한다**(`path`) — 축 이름으로만 읽으면 중첩된 축이
              언제나 「관측 없음」이 된다(에너지의 수요 구간이 그렇다). 규칙은 `axisValueOf` 한 곳. */
-          const bucket = snap ? axisValueOf(snap, a) ?? null : null
+          let bucket = snap ? axisValueOf(snap, a) ?? null : null
+          let heardAt: string | null = null
+          let fromJournal = false
+          /*
+           * 라이브가 잊은 축은 **저널에서 되세운다**(§`journalOnce`). 그 축의 사실이 저널에 있을 때만
+           * 접고, 값과 함께 「언제 들은 값인가」를 낸다 — 시각 없이 수만 내면 낡은 값을 지금으로 읽는다.
+           */
+          if (!folded && Array.isArray(bucket) && bucket.length === 0) {
+            const seen = await axisSeenInJournal(getRepository(TwinEvent), { domain: { id: domainId }, instanceId }, a.axis).catch(() => null)
+            if (seen) {
+              const j = await journalOnce()
+              const jb = j?.snap ? axisValueOf(j.snap, a) ?? null : null
+              if (Array.isArray(jb) && jb.length) {
+                bucket = jb
+                heardAt = j?.heardAt ?? null
+                fromJournal = true
+              }
+            }
+          }
           return {
             axis: a.axis,
             label: a.label,
@@ -264,13 +381,34 @@ export class TwinModelQuery {
             standardClass: a.standardClass,
             typeRole: a.typeRole ?? null,
             count: Array.isArray(bucket) ? bucket.length : null,
+            /*
+             * **수 하나가 뜻을 바꾸는 자리** (2026-08-23).
+             *
+             * 미러가 완료된 작업까지 상태에 들고 있게 되면서 「작업 2,820」이 되었다. 이 카드는 상태의
+             * 인구조사이므로 그 수가 맞다 — 그런데 사람은 그것을 「지금 할 일 2,820건」으로 읽는다.
+             * 수를 줄여 거짓으로 만드는 대신 **무엇으로 이루어진 수인지** 함께 낸다.
+             *
+             * 낱말은 커널의 것을 그대로 쓴다(`created`·`assigned`·`in-progress`·`completed`). 화면이
+             * 라벨을 입히고, 없으면 낱말이 그대로 보여 누락이 드러난다.
+             */
+            ...statusTally(bucket),
             /*
              * **비었으면 왜 비었는지 말한다.** 0 과 `null` 만 내면 화면은 "없다" 까지만 말하고, 사용자는
              * "안 적어 놨나 · 아직 안 일어났나 · 못 세었나" 를 구별할 수 없다. 이 화면이 관측 열에서
              * 내내 지켜 온 구분(§observedAbsence)을 카드에서도 지킨다.
              */
-            ...(Array.isArray(bucket) ? (bucket.length ? {} : { emptyBecause: 'none-yet' }) : { emptyBecause: 'not-observed' }),
-            basis: folded ? 'journal' : 'state',
+            ...(Array.isArray(bucket)
+              ? bucket.length
+                ? {}
+                : { emptyBecause: await emptyStateReason(domainId, instanceId, a.axis) }
+              : { emptyBecause: 'not-observed' }),
+            source: axisSource(a.axis),
+            basis: folded || fromJournal ? 'journal' : 'state',
+            /*
+             * **언제 들은 값인가** — 저널에서 되세운 축만 갖는다. 라이브가 답한 축은 지금이므로 없다.
+             * 이 값이 없으면 화면이 낡은 수를 지금으로 읽는다(그 구별이 이 카드의 전부다).
+             */
+            ...(fromJournal && heardAt ? { heardAt, recalled: true } : {}),
             observing,
             /* 선언이 아니라 관측인 축 — 화면이 "원본이 침묵했다" 로 읽지 않게 사실로 말한다. */
             observedOnly: true,
@@ -301,6 +439,7 @@ export class TwinModelQuery {
                   entity && inDocument > 0 ? 'not-projected' : raw == null ? 'not-declared' : 'declared-empty'
               }),
           /* 'rows' = DB 가 셌다(질의 가능) · 'document' = 문서를 세었다(아직 이주 전). */
+          source: axisSource(a.axis),
           basis: entity ? 'rows' : 'document',
           ...(entity ? { documentCount: inDocument, stale } : {}),
           /* 표준 투영이 없는 축은 **숨기지 않고** 그 사실을 낸다(ADR-0031). */
@@ -321,12 +460,24 @@ export class TwinModelQuery {
      * 트윈이 안 실행 중이면 비교할 상대가 없다 — 그때는 `null` 이다(0 이 아니다. 없는 것과
      * 세어 보지 못한 것은 다르다).
      */
+    /*
+     * 도출은 **한 벌**이다(`engine/model-gap.ts`). 예전에는 이 자리에 인라인으로 있었는데, 같은 사실을
+     * 「현장과 맞춰지고 있나」 화면도 물어야 해서 두 곳이 다른 수를 말할 위험이 생겼다.
+     *
+     * 이 화면은 **전체 목록**이 필요하다(인스펙션이니까). 그래서 상한 없는 원본을 여기서 만들고,
+     * 상한이 걸린 요약은 `modelGapOf` 가 답한다 — 같은 판정(`origin === 'observed'`)을 쓴다.
+     */
     const snap = TwinEngine.snapshot(domainId, instanceId)
+    const gap = modelGapOf(snap)
     const observedOnly = snap
       ? {
           equipment: (snap.equipment ?? []).filter((e: any) => e?.origin === 'observed').map((e: any) => e.id),
           locations: (snap.locations ?? []).filter((l: any) => l?.origin === 'observed').map((l: any) => l.id),
-          persons: (snap.persons ?? []).filter((p: any) => p?.origin === 'observed').map((p: any) => p.id)
+          persons: (snap.persons ?? []).filter((p: any) => p?.origin === 'observed').map((p: any) => p.id),
+          /* 커널이 담을 줄 몰라 세어 둔 사건·모르는 설비 보고 — 인스펙션이 이미 물을 자리다. */
+          unhandled: gap?.unhandled ?? [],
+          unknownEquipmentReports: gap?.unknownEquipmentReports ?? null,
+          notCovered: gap?.notCovered ?? []
         }
       : null
 
@@ -374,7 +525,7 @@ export class TwinModelQuery {
       })(),
       description: inst.description ?? null,
       kind: inst.kind,
-      realityMode: inst.realityMode,
+      restartPolicy: inst.restartPolicy,
       source: ref
         ? { referenceId: ref.source, adapterType: ref.adapterType, status: ref.status, lastSyncedAt: ref.lastSyncedAt }
         : null,

package/server/service/twin-model/twin-model-tree-query.ts

@@ -1,3 +1,4 @@
+import { nameIndex, namesFor } from './name-index.js'
 import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
@@ -171,6 +172,12 @@ export class TwinModelTreeQuery {
       items,
       edges,
       /* 수량을 하나라도 모르면 아래 합계가 성립하지 않는다는 사실을 그대로 낸다. */
+      /*
+       * **이름을 함께 낸다** (2026-08-22). 나무의 줄이 id 만 보이면 사용자는 그 노드가 무엇인지 알 수
+       * 없다 — 사용자의 말: 「각 노드의 식별자가 반복되어서 이해가 어렵다. 식별자와 이름이 보이면.」
+       * 목록·항목 화면이 쓰는 것과 **같은 표**를 쓴다(`name-index`) — 두 벌이면 한쪽만 고쳐진다.
+       */
+      names: namesFor(items, nameIndex(inst.model ?? {})),
       qtyIncomplete: edges.some(e => e.step == null),
       cycles: [...new Set(cycles)],
       truncated: { depth: depthTruncated, items: itemTruncated, depthCap, itemCap },

package/server/service/twin-readiness/index.ts

@@ -0,0 +1,3 @@
+import { TwinReadinessQuery } from './twin-readiness-query.js'
+
+export const resolvers = [TwinReadinessQuery]