@things-factory/headless-twin 10.0.12 → 10.0.14

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[] = [
@@ -86,6 +86,20 @@ const FIELDS: Isa95Concept[] = [
     surface: 'full',
     note: 'twin.epcis.note.identity'
   },
+  /*
+   * ── 2026-08-24 주장 근거가 달라졌다 ────────────────────────────────────────
+   * 이 줄은 오래 `full` 이었지만 근거가 **우리 선언**이었다. 이제 **정본 원문 대조**다:
+   * CBV Standard Release 2.0(Ratified Jun 2022) §7.2.3 의 처분 38개를 전수 확인했다.
+   *
+   * 그 대조가 실제로 셋을 바꿨다.
+   *   · `expired` — 있는 낱말인데 우리가 쓰지 않고 있었다(기한 경과를 처분으로 말할 수 있게 됐다)
+   *   · `conformant` / `non_conformant` — 검사 판정을 처분으로 남기는 낱말. 함께 `inspecting` bizStep
+   *   · `non_sellable_expired` 는 표준이 **폐기**하고 `expired` 로 대체한 것을 확인
+   *
+   * ★ 그리고 **검증 방법에 함정이 있다**: `ref.gs1.org/cbv/…` 로 URN 을 조회하면 **지어낸 값에도
+   * 똑같은 응답**이 온다. 그것으로 확인했다고 여기면 없는 낱말을 발행한다(한 번 그렇게 했다).
+   * 확인은 정본 문서로만 한다.
+   */
   {
     std: 'bizStep / disposition (CBV)',
     part: 'fields',
@@ -160,6 +174,19 @@ const FIELDS: Isa95Concept[] = [
     surface: 'none',
     note: 'twin.epcis.note.persistentDisposition'
   },
+  /*
+   * ── 2026-08-24 계측이 어디로 들어오는지 확정됐다 ──────────────────────────
+   * 「계측은 EPCIS 센서 필드로 오지 않는다」는 사실이 이제 **자리를 갖는다**: 자리의 상시 관측은
+   * ISA-95 `OperationsEvent` 로 들어오고(커널 `location.measured` 채널), 에너지는 그 위의 누적기가
+   * 받는다. ISA-95 표의 `OperationsEvent` 줄이 그 판정을 든다.
+   *
+   * 왜 EPCIS 가 아닌가: `SensorElement` 는 **개체에 붙는** 관측이고, 냉장실의 온도는 그 안의 물건
+   * 수백 개와 관계되며 그 수백 개는 시간에 따라 바뀐다. 개체마다 붙이면 같은 사실이 수백 벌이 되고,
+   * 물건이 떠나면 그 방의 온도 이력이 함께 사라진다. 주인은 **자리**다.
+   *
+   * 그래서 이 줄은 `behavior: 'none'` 으로 남는다 — 결손이 아니라 **다른 층으로 들어온다는 사실**이다.
+   * 그 구별을 표가 말하지 않으면 「센서를 못 받는 트윈」으로 읽힌다.
+   */
   {
     std: 'sensorElementList',
     part: 'fields',
@@ -179,13 +206,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

@@ -102,9 +102,39 @@ const PART2: Isa95Concept[] = [
   { std: 'PhysicalAsset', part: '2', label: 'twin.isa95.PhysicalAsset', axis: 'assets', structure: 'full', behavior: 'full', surface: 'full' },
   { std: 'MaterialClass', part: '2', label: 'twin.isa95.MaterialClass', axis: 'materialClasses', structure: 'full', behavior: 'partial', surface: 'full' },
   { std: 'MaterialDefinition', part: '2', label: 'twin.isa95.MaterialDefinition', axis: 'materialDefinitions', structure: 'full', behavior: 'full', surface: 'full' },
-  /* 로트·서브로트는 개체 축이 아니라 **관측**으로 존재한다(EPCIS 개체) — 구조는 저널이 갖는다. */
+  /*
+   * 로트·서브로트는 개체 축이 아니라 **관측**으로 존재한다(EPCIS 개체) — 구조는 저널이 갖는다.
+   *
+   * ── 2026-08-24 로트가 시험 결과를 들게 됐다 (커널 0.7.57) ─────────────────
+   * `ItemState.testResults` 로 「이 로트를 쓸 수 있나」의 **근거**가 로트에 실린다. 그전에는 판정
+   * (`disposition`)만 있었고 「왜 그렇게 판정했나」를 되짚을 수 없었다.
+   *
+   * **구조를 `full` 로 올리지 않는다.** `MaterialLotType` 원문(B2MML-Material.xsd)이 드는 것 중
+   * 아직 없는 것이 있다: `MaterialLotProperty`(시험이 아닌 로트 속성 — 원산지·포장 형태) ·
+   * `TestSpecificationID`(로트별 기준 참조 — 품목 정의가 대신 답하므로 두지 않았다) · `Status` ·
+   * `HierarchyScope` · `Version`. 채운 것만 세는 것이 이 표의 규율이다.
+   */
   { std: 'MaterialLot', part: '2', label: 'twin.isa95.MaterialLot', axis: null, structure: 'partial', behavior: 'full', surface: 'partial', note: 'twin.isa95.note.lot' },
-  { std: 'MaterialSublot', part: '2', label: 'twin.isa95.MaterialSublot', axis: null, structure: 'none', behavior: 'none', surface: 'none' },
+  /*
+   * ── 2026-08-24 판정 정정: `none` 이 아니었다 ──────────────────────────────
+   * 이 줄은 셋 다 `none` 이었는데 **표가 코드보다 뒤처져 있었다.** 커널은 서브로트를 든다:
+   *
+   *   `ItemState.subLotId`   표준 `MaterialSubLot.ID` (계약이 그렇게 적고 있다)
+   *   `subLotIdOf(class, location)`  비직렬 로트가 자리마다 나뉠 때 그 부분의 이름을 만든다
+   *   `itemKeyOf(item)`      **개체의 정체성이 이 값이다** — `subLotId ?? epc`
+   *
+   * 기능이 `full` 인 근거: 이 축이 없으면 같은 로트를 rack-1 에 100개·rack-2 에 60개 관측했을 때
+   * **뒤에 온 관측이 앞을 덮어 100개가 조용히 사라진다**(합계 160 → 60). 실제로 그 결함을 이 축으로
+   * 고쳤다. 즉 장식이 아니라 정체성을 지탱한다.
+   *
+   * 구조가 `partial` 인 이유: 서브로트는 로트와 같은 모양이고(위 참조) 그 로트가 `partial` 이다.
+   * 화면이 `partial` 인 이유: 값이 물품의 **이름으로** 나온다(`twin-item` 의 line) — 「이 로트가 자리마다
+   * 나뉘어 있다」를 말하는 자리는 아직 없다.
+   *
+   * 이 부류(코드에 있는데 표가 `none`)는 자동으로 잡히지 않는다 — 표의 가드는 반대 방향만 본다
+   * (축이 사라지면 구조를 내린다). 그래서 축을 늘릴 때 이 표를 함께 보는 것이 규율이다.
+   */
+  { std: 'MaterialSublot', part: '2', label: 'twin.isa95.MaterialSublot', axis: null, structure: 'partial', behavior: 'full', surface: 'partial' },
   { std: 'ProcessSegment', part: '2', label: 'twin.isa95.ProcessSegment', axis: 'operations', structure: 'full', behavior: 'full', surface: 'full' },
   /*
    * 속성은 자원마다 붙는 확장이라 **자기 축이 아니다** — 그래서 `axis` 는 없지만 구조는 완전하다:
@@ -114,7 +144,30 @@ const PART2: Isa95Concept[] = [
    * 기능은 **부분**이다: 호스트의 주행 추정기가 `speed` 를 읽어 이동 시간을 만드는 것이 유일한 소비처다
    * (다른 속성은 아직 아무도 읽지 않는다). 그 사실을 `full` 로 올리면 표가 거짓이 된다.
    */
-  { std: 'Property', part: '2', label: 'twin.isa95.Property', axis: null, structure: 'full', behavior: 'partial', surface: 'full', note: 'twin.isa95.note.property' }
+  { std: 'Property', part: '2', label: 'twin.isa95.Property', axis: null, structure: 'full', behavior: 'partial', surface: 'full', note: 'twin.isa95.note.property' },
+  /*
+   * **자리의 상시 관측** — 2026-08-24 신설(커널 0.7.56). 표에 이 개념이 아예 없었다.
+   *
+   * 왜 이 축이 필요한가: 트윈의 판정 대상은 물건의 상태이고, 물건의 상태는 **조건 없이 정해지지
+   * 않는다.** 「이 로트가 냉장실에 있었다」까지만 아는 트윈은 그 로트가 괜찮았는지 말할 수 없다. 그리고
+   * **이 조인은 트윈만 할 수 있다** — 계측 시스템은 물건의 자리 이력을 모르고, 물류 시스템은 조건
+   * 이력을 모른다.
+   *
+   * 표준 앵커: `OperationsEventType`(B2MML-OperationsEvent.xsd, ISA-95.00.02-2018) +
+   * `OperationsRecordTemplateType`. 우리가 든 것 — `EffectiveTimestamp` · `EffectiveEndDate` ·
+   * `RecordTimestamp` · `HierarchyScope`(자리) · `Source` · 값은 `ValueType` 으로 **좁혔다**
+   * (단위 없는 물리량은 판정의 재료가 못 된다).
+   *
+   * 붙는 자리가 `HierarchyScope.EquipmentID` 인 것이 중요하다 — ISA-95 에서 장소 계층이 곧 설비
+   * 계층이고 냉장실은 `StorageZone` 수준의 설비다. `OperationalLocationType` 에는 이 축이 없다.
+   *
+   * 구조가 `partial`: 봉투 전체(`ID`·`Description`·사건 분류·`OperationsRecord` 구조)가 아니라 관측
+   * 하나를 담는 데 필요한 칸만 든다.
+   * 기능이 `full`: 사건 채널(`location.measured`)이 상태를 만들고, 선언된 기준으로 판정해
+   * `observation-out-of-limit` 신호를 세운다.
+   * 화면이 `none`: 클라이언트에 이 축을 그리는 곳이 없다(실측 0곳).
+   */
+  { std: 'OperationsEvent', part: '2', label: 'twin.isa95.OperationsEvent', axis: null, shownOn: ['locations'], structure: 'partial', behavior: 'full', surface: 'none' }
 ]
 
 /*
@@ -149,10 +202,37 @@ const PART4: Isa95Concept[] = [
    * 그것을 본다 — 만료·불합격이면 그 자격은 성립하지 않는다(실측: 만료된 용접사는 용접 작업 5건 중 한
    * 번도 배정되지 않았다).
    *
-   * `full` 이 아닌 이유는 둘이다: **사람만 판정한다**(설비·자산의 검사 결과는 아직 배정에 쓰지 않는다),
-   * 그리고 결과가 없으면 판정하지 않는다(선언한 것만 제약이 된다 — 그건 결손이 아니라 규율이다).
+   * ── 2026-08-24 위 문장 하나가 낡았다 ─────────────────────────────────────
+   * 「**사람만 판정한다**」고 적혀 있었다. 지금은 아니다 — `capabilityOfResource` 가 설비·사람·자산
+   * **셋 모두**에 `requiredTests` 를 걸고, 그 답이 배정의 가용성 필터로 들어간다. 그리고 판정 대상이
+   * 자원 밖으로 넓어졌다: **자리의 상시 관측**(`OperationsEvent` 줄)과 **로트의 시험 결과**
+   * (`TestResult` 줄)도 같은 기준으로 판정한다.
+   *
+   * 남은 규율은 하나다: **결과가 없으면 판정하지 않는다**(선언한 것만 제약이 된다 — 결손이 아니라 규율).
+   *
+   * 그리고 기준의 **숫자 한계는 우리가 더한 것**이다. 표준 `TestSpecificationCriteria.Expression` 은
+   * 자유 문장(`TextType`)이고, B2MML 일곱 파일에 `Minimum`·`Maximum`·`Tolerance` 가 하나도 없다
+   * (원문 대조). 그것 없이는 판정할 수 없으므로 `limit: {minimum, maximum, uom}` 을 더했고, 발명한
+   * 자리임을 계약에 적었다. 커널은 `Expression` 을 **읽지 않는다** — 문법이 정의되지 않았으므로
+   * 파싱하면 그 순간 방언이다.
    */
   { std: 'TestSpecification', part: '4', label: 'twin.isa95.TestSpecification', axis: 'testSpecifications', structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.test' },
+  /*
+   * **시험 결과** — 2026-08-24 신설(커널 0.7.57). 기준만 있고 결과의 자리가 표에 없었다.
+   *
+   * 표준 `TestResultType`(B2MML-OperationsTest.xsd)에서 우리가 든 것:
+   *   `EvaluationDate`(at) · `Expiration`(expiresAt) · `TestableObjectID` · `PropertyMeasurement`
+   *   · `EvaluatedCriterionResult` → **`result: 'pass'|'fail'` 로 좁혔다**(표준은 열거하지 않는다)
+   * 아직 없는 것: `ID` · `Description` · `HierarchyScope` · `OperationsTestRequirementID` ·
+   * `TestResultChild`. 그래서 구조는 `partial` 이다.
+   *
+   * 기능이 `partial` 인 이유를 정확히 적는다 — **자원에서는 결정을 바꾸고 로트에서는 아직 바꾸지
+   * 않는다.** 만료·불합격 자원에는 작업이 배정되지 않지만, 불합격 로트가 할당에서 빠지거나 주의 신호를
+   * 세우지는 않는다(들고·판정하고·되짚을 수는 있다). 그 자리를 `full` 로 적으면 표가 거짓이 된다.
+   *
+   * 화면은 `none` 이다 — 클라이언트에 이 축을 그리는 곳이 없다(실측: `operato-twin/client` 에 0곳).
+   */
+  { std: 'TestResult', part: '4', label: 'twin.isa95.TestResult', axis: null, shownOn: ['items'], structure: 'partial', behavior: 'partial', surface: 'none' },
   { std: 'WorkMaster', part: '4', label: 'twin.isa95.WorkMaster', axis: 'recipes', structure: 'full', behavior: 'full', surface: 'full' },
   { std: 'WorkDirective', part: '4', label: 'twin.isa95.WorkDirective', axis: null, structure: 'none', behavior: 'none', surface: 'none' }
 ]
@@ -166,20 +246,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
+}

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) {