@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -1,24 +1,81 @@
-import { Arg, Ctx, Query, Resolver } from 'type-graphql'
+import { Arg, Ctx, Directive, Query, Resolver } from 'type-graphql'
 
-import { ScalarObject } from '@things-factory/shell'
+import { In } from 'typeorm'
+
+import { Domain, getRepository, ScalarObject } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { newCpuSampler, sampleCpu } from '../../engine/load-meter.js'
 
 /*
  * 트윈 처리량 계측(모니터, ④-1) — 라이브 동기 인터페이스 부하를 읽는 일급 지표.
  * 유입률(ingestRate)·방송률(broadcastRate)·저널률(journalRate)·백로그(backlog)·누적. 폴링으로 라이브 관측.
  * (부하가 화면에 안 보인다던 문제의 정공법 — "얼마나 들어오고 얼마나 방송/기록되나"를 수치로.)
  */
+/* CPU 는 누적값이라 **표본 사이의 차이**로만 점유율이 나온다. 그래서 호출 사이에 상태가 남아야 한다. */
+const CPU_SAMPLER = newCpuSampler()
+
 @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.' })
   twinMetrics(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): any {
     if (!TwinEngine.owns(context.state.domain.id, instanceId)) return null // 테넌트 격리
-    return TwinEngine.metrics(instanceId)
+    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).' })
   async twinMetricsAll(@Ctx() context: ResolverContext): Promise<any[]> {
     return TwinEngine.allMetrics(context.state.domain.id) // 도메인 스코프
   }
+
+  /*
+   * ── 이벤트 루프 부하 — **운영 계기판이다. 테넌트 기능이 아니다.** ─────────────
+   *
+   * `twinMetrics` 는 "얼마나 들어오고 나가나"(초당 이벤트)를 답한다. 여기서 묻는 것은 "그 일을 하느라
+   * 이벤트 루프를 얼마나 붙잡고 있나" 다. 시뮬 틱은 트윈마다 setInterval 로 **메인 루프에서 동기로**
+   * 돌기 때문에, 한 트윈이 느려지면 HTTP·구독이 함께 느려진다. 실제로 그 상태를 겪었는데 볼 계기판이
+   * 없어서 "포트는 열렸는데 응답이 없다" 로만 보였다.
+   *
+   * ── 왜 도메인으로 자르지 않나 ───────────────────────────────────────────────
+   * 처음에는 호출자의 도메인만 냈다. 테넌트 격리로는 맞아 보이지만 **이벤트 루프는 프로세스 하나가
+   * 공유한다.** 실측으로 드러났다: 한 도메인 트윈 22개가 CPU 를 110% 쓰는 동안, 다른 도메인 화면은
+   * `실행 중 0 · 루프 점유 —` 였다. "내 도메인은 한가한데 왜 느리지" 를 설명할 수 없었다.
+   *
+   * 그렇다고 테넌트에게 남의 부하를 조금 보여 주는 것도 답이 아니다 — 쓸 수 없는 정보이고 봐서도 안 된다.
+   * 층이 잘못이었다: 이것은 **프로세스를 운영하는 사람의 계기판**이다. 그래서 도메인으로 자르지 않고
+   * (전 테넌트 합산) **슈퍼유저에게만** 연다.
+   */
+  @Directive('@privilege(superUserGranted: true)')
+  @Query(returns => ScalarObject, {
+    description:
+      'Event-loop load of every twin in this process, for system operators (superuser only). Deliberately NOT scoped to the caller\'s domain: the event loop is shared by the whole process, so a tenant-scoped view reports an idle domain while the machine is saturated by someone else. Reports how many instances are running (by mode), how many forecast forks have been created, and per instance how long each kind of work takes (kernel tick, state snapshot, broadcast payload, publish, journal write, live ingest, Monte-Carlo forecast, fork trajectory). Each instance reports both `recent` (the last closed sampling window — what it is doing now) and `total` (cumulative since boot), with `busyRatio` telling how much of the window that twin held the loop. `fleetBusyRatio` above 1 means the twins together cannot finish inside one tick interval, which is when HTTP and subscriptions start to stall. Work that has never been measured is reported as null rather than zero, because zero would read as "instant".'
+  })
+  async twinLoad(@Ctx() context: ResolverContext): Promise<any> {
+    const fleet = TwinEngine.fleet() // 프로세스 전체 — 도메인으로 자르지 않는다(위 주석)
+
+    /* 도메인 id 는 UUID 라 사람이 못 읽는다. 읽을 수 있는 이름을 채운다 — **모르면 id 를 그대로 둔다**
+       (지어내지 않는다). 라이브 인스턴스에는 이미 붙어 있고, 시뮬은 여기서 한 번 조회한다. */
+    const ids = [...new Set((fleet.byDomain ?? []).map((d: any) => d.domainId).filter((v: any) => v && v !== '(unknown)'))]
+    if (ids.length) {
+      const found = await getRepository(Domain).find({ where: { id: In(ids as string[]) } })
+      const nameOf = new Map(found.map(d => [d.id, d.subdomain || d.name]))
+      for (const d of fleet.byDomain) if (nameOf.get(d.domainId)) d.label = nameOf.get(d.domainId) as string
+      for (const r of fleet.slowest ?? []) if (r.domainId && nameOf.get(r.domainId)) r.domainLabel = nameOf.get(r.domainId)
+      for (const r of fleet.details ?? []) if (r.domainId && nameOf.get(r.domainId)) r.domainLabel = nameOf.get(r.domainId)
+    }
+
+    /*
+     * 프로세스가 실제로 쓴 CPU — **계기판의 다른 숫자와 뜻이 다르다.**
+     *
+     * 위의 값들은 트윈의 계측된 작업만 잰 것이라, 그 밖의 일(GraphQL·TypeORM·GC·webpack·HTTP)은
+     * 분모에도 분자에도 없다. "루프 점유 <1%" 인데 CPU 는 110% 였던 상태를 실제로 겪었다. 두 숫자를
+     * 나란히 두어야 **트윈이 범인인지** 가릴 수 있다.
+     *
+     * 표본 간 차이라 첫 호출은 `null` 이다 — 0 이 아니다.
+     */
+    const usage = process.cpuUsage()
+    const cpu = sampleCpu(CPU_SAMPLER, usage.user + usage.system, Date.now())
+
+    return { ...fleet, processCpuRatio: cpu?.ratio ?? null, processCpuSpanMs: cpu?.spanMs ?? null }
+  }
 }

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

@@ -0,0 +1,195 @@
+/*
+ * GS1 EPCIS 2.0 적합성 기준 — **물류·제조 트윈이 표준의 어디를 채우고 있나.**
+ *
+ * ── 왜 따로 있나 ────────────────────────────────────────────────────────────
+ * 적합성 패널이 ISA-95 하나만 말하고 있었다. 그런데 창고·야드·공장 트윈에서 「무슨 일이 있었나」와
+ * 「이 번호가 무엇을 가리키나」를 정하는 것은 EPCIS 다. ISA-95 표만 보이면 그 트윈이 기대는 기준의
+ * 절반이 화면에 없다.
+ *
+ * ── 수준은 근거를 보고 적었다 ───────────────────────────────────────────────
+ * 「있다/없다」를 기억으로 적지 않는다. 각 줄의 판단 근거:
+ *  · 타입 선언 — 커널 `epcis.ts`(이벤트·필드의 모양)
+ *  · 실제 사용 — 커널 도메인(`mes-kernel`·`face2-adapter`·`observed-reducer`)과 호스트 인제스트
+ *  · 화면 노출 — 저널·계보·엔티티 360
+ * 모양만 있고 아무도 채우지 않는 필드는 **구조만 있음**으로 적는다(그게 사실이다).
+ *
+ * ISA-95 표와 같은 규율이다(`isa95-coverage.ts` 머리말): 사람이 판단해 적고, 틀리면 여기를 고친다.
+ */
+import type { Isa95Concept, CoverageLevel } from './isa95-coverage.js'
+
+/* Part: EPCIS 2.0 의 사건 종류 — 무엇이 일어났는가. */
+const EVENTS: Isa95Concept[] = [
+  {
+    std: 'ObjectEvent',
+    part: 'events',
+    label: 'twin.epcis.ObjectEvent',
+    axis: 'items',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.epcis.note.ObjectEvent'
+  },
+  {
+    std: 'AggregationEvent',
+    part: 'events',
+    label: 'twin.epcis.AggregationEvent',
+    axis: null,
+    shownOn: ['items'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'partial',
+    note: 'twin.epcis.note.AggregationEvent'
+  },
+  {
+    std: 'TransactionEvent',
+    part: 'events',
+    label: 'twin.epcis.TransactionEvent',
+    axis: 'orders',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'partial',
+    note: 'twin.epcis.note.TransactionEvent'
+  },
+  {
+    std: 'TransformationEvent',
+    part: 'events',
+    label: 'twin.epcis.TransformationEvent',
+    axis: null,
+    shownOn: ['items', 'operations'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.epcis.note.TransformationEvent'
+  },
+  /* EPCIS 2.0 이 더한 사건 — 우리는 타입조차 두지 않았다. 없는 것은 없다고 적는다. */
+  {
+    std: 'AssociationEvent',
+    part: 'events',
+    label: 'twin.epcis.AssociationEvent',
+    axis: null,
+    structure: 'none',
+    behavior: 'none',
+    surface: 'none',
+    note: 'twin.epcis.note.AssociationEvent'
+  }
+]
+
+/* Part: 사건이 답하는 다섯 가지 — 무엇을·어디서·언제·왜, 그리고 어떤 거래로. */
+const FIELDS: Isa95Concept[] = [
+  {
+    std: 'epcList / quantityList',
+    part: 'fields',
+    label: 'twin.epcis.identity',
+    axis: 'items',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.epcis.note.identity'
+  },
+  {
+    std: 'bizStep / disposition (CBV)',
+    part: 'fields',
+    label: 'twin.epcis.cbv',
+    axis: null,
+    shownOn: ['items', 'tasks'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.epcis.note.cbv'
+  },
+  {
+    std: 'readPoint / bizLocation',
+    part: 'fields',
+    label: 'twin.epcis.where',
+    axis: 'locations',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.epcis.note.where'
+  },
+  {
+    std: 'bizTransactionList',
+    part: 'fields',
+    label: 'twin.epcis.bizTransaction',
+    axis: 'orders',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'partial',
+    note: 'twin.epcis.note.bizTransaction'
+  },
+  {
+    std: 'ilmd',
+    part: 'fields',
+    label: 'twin.epcis.ilmd',
+    axis: null,
+    shownOn: ['items'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'partial',
+    note: 'twin.epcis.note.ilmd'
+  },
+  {
+    std: 'errorDeclaration',
+    part: 'fields',
+    label: 'twin.epcis.errorDeclaration',
+    axis: null,
+    shownOn: ['items'],
+    structure: 'full',
+    behavior: 'partial',
+    surface: 'none',
+    note: 'twin.epcis.note.errorDeclaration'
+  },
+  /* 모양만 있고 아무도 채우지 않는 것들 — 구조만 있음. */
+  {
+    std: 'sourceList / destinationList',
+    part: 'fields',
+    label: 'twin.epcis.sourceDestination',
+    axis: null,
+    structure: 'partial',
+    behavior: 'none',
+    surface: 'none',
+    note: 'twin.epcis.note.sourceDestination'
+  },
+  {
+    std: 'persistentDisposition',
+    part: 'fields',
+    label: 'twin.epcis.persistentDisposition',
+    axis: null,
+    structure: 'partial',
+    behavior: 'none',
+    surface: 'none',
+    note: 'twin.epcis.note.persistentDisposition'
+  },
+  {
+    std: 'sensorElementList',
+    part: 'fields',
+    label: 'twin.epcis.sensorElement',
+    axis: null,
+    structure: 'partial',
+    behavior: 'none',
+    surface: 'none',
+    note: 'twin.epcis.note.sensorElement'
+  }
+]
+
+export const EPCIS_CONCEPTS: Isa95Concept[] = [...EVENTS, ...FIELDS]
+
+export function epcisCoverage(axes: string[]): {
+  model: 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 count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
+  return {
+    model: 'GS1 EPCIS 2.0',
+    concepts,
+    totals: { concepts: concepts.length, structure: count('structure'), behavior: count('behavior'), surface: count('surface') }
+  }
+}

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

@@ -0,0 +1,117 @@
+/*
+ * IEC 61850 적합성 기준 — **에너지 트윈이 표준의 어디를 채우고 있나.**
+ *
+ * ── 왜 따로 있나 ────────────────────────────────────────────────────────────
+ * 인스펙션의 적합성 패널은 트윈 종류와 무관하게 ISA-95 하나만 말하고 있었다. 에너지 트윈에서 그것은
+ * 거짓은 아니지만(설비·계층·속성은 에너지에서도 ISA-95 자원이다) **부족하다** — 계량기·차단기·태양광·
+ * 축전지의 어휘를 주는 것은 IEC 61850 이고, 무엇이 비었는지도 그 목록으로만 셀 수 있다.
+ *
+ * ── 주장 수준을 못 박는다 ───────────────────────────────────────────────────
+ * 여기서 재는 것은 **어휘와 모델**이다. 프로토콜(MMS·GOOSE·샘플드값)을 구현했다는 뜻이 아니며,
+ * 그 주장은 적합성 시험이 뒷받침해야 한다. 표 이름을 「IEC 61850 (vocabulary)」로 쓰는 이유다.
+ *
+ * ── 값은 관측이 아니라 선언이다 ─────────────────────────────────────────────
+ * ISA-95 표와 같은 규율이다(`isa95-coverage.ts` 머리말): 사람이 판단해 적고, 틀리면 여기를 고친다.
+ * 자동으로 알 수 있는 것 하나만 자동으로 한다 — 축 이름이 커널 축 목록에 없으면 구조가 없는 것이다.
+ */
+import type { Isa95Concept, CoverageLevel } from './isa95-coverage.js'
+
+/*
+ * Part 7-4 — 논리 노드 클래스. 이 프로파일이 쓰는 것만 적는다(표준 전체를 옮기지 않는다):
+ * 계량·계측·개폐·발전·저장.
+ */
+const LOGICAL_NODES: Isa95Concept[] = [ // vocabulary-guard: allow — IEC 61850 의 「논리 노드(logical node)」는 표준 용어다(우리가 은퇴시킨 node 어휘가 아니다)
+  /*
+   * 계량(적산) — 커넥터가 누적 전력량을 실어 오고 상태가 지점별로 들고 있다. 화면은 계량 컴포넌트가
+   * 지점의 값을 보인다.
+   */
+  {
+    std: 'MMTR',
+    part: '7-4',
+    label: 'twin.iec61850.MMTR',
+    axis: 'equipment',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.iec61850.note.MMTR'
+  },
+  /*
+   * 계측(유효전력·역률) — 표본이 수요 구간으로 접히고, 구간·피크·계약 대비가 그 위에 선다.
+   * 이 프로파일에서 가장 두껍게 채운 자리다.
+   */
+  {
+    std: 'MMXU',
+    part: '7-4',
+    label: 'twin.iec61850.MMXU',
+    axis: 'demandWindows',
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.iec61850.note.MMXU'
+  },
+  /*
+   * ── 셋이 함께 올라갔다 (2026-08-15) ──────────────────────────────────────
+   * 개폐·발전·저장은 오래 「구조만 있음」이었다. 능력이 상태 필드를 선언해 두었는데 **값을 받는 문이
+   * 없었기 때문**이다. 이제 셋 다 실제로 돈다: 설비 상태가 계약에 서고(`EquipmentState`), 커널이
+   * `energy.equipment` 로 받아 그 설비에 적고, 씬 컴포넌트가 그린다.
+   *
+   * 세 층을 함께 올리는 이유: 값이 없는데 화면만 만들면 영원히 「—」인 카드가 되고, 화면이 없는데
+   * 기능만 올리면 아무도 그 값을 보지 못한다. 「값이 먼저, 컴포넌트는 그 다음」의 결과다.
+   */
+  {
+    std: 'XCBR',
+    part: '7-4',
+    label: 'twin.iec61850.XCBR',
+    axis: null,
+    shownOn: ['equipment'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.iec61850.note.XCBR'
+  },
+  {
+    std: 'DPVA',
+    part: '7-4',
+    label: 'twin.iec61850.DPVA',
+    axis: null,
+    shownOn: ['equipment'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.iec61850.note.DPVA'
+  },
+  {
+    std: 'ZBAT',
+    part: '7-4',
+    label: 'twin.iec61850.ZBAT',
+    axis: null,
+    shownOn: ['equipment'],
+    structure: 'full',
+    behavior: 'full',
+    surface: 'full',
+    note: 'twin.iec61850.note.ZBAT'
+  }
+]
+
+export const IEC61850_CONCEPTS: Isa95Concept[] = [...LOGICAL_NODES] // vocabulary-guard: allow — 표준 용어(위 주석)
+
+export function iec61850Coverage(axes: string[]): {
+  model: 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 count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
+  return {
+    /* 이름에 (vocabulary) 를 달아 둔다 — 프로토콜 적합성으로 읽히지 않게. */
+    model: 'IEC 61850 (vocabulary)',
+    concepts,
+    totals: { concepts: concepts.length, structure: count('structure'), behavior: count('behavior'), surface: count('surface') }
+  }
+}

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

@@ -0,0 +1,25 @@
+/*
+ * 트윈 구조 모델 — `TwinInstance.model`(JSON 덩어리) 에서 풀어낸 **표준 엔티티**(ADR-0032).
+ *
+ * 여기 있는 것은 전부 **원본에서 온 캐시**다. 정본은 원본 시스템이고(ADR-0028), 이 행들은
+ * 인제스트가 만들며 언제든 전부 지우고 다시 만들 수 있어야 한다.
+ *
+ * 오늘은 **실제로 채워지는 세 축**만 있다 — 자리·설비·공정. 사람·자산·등급·속성·생산 정의는
+ * 지금 0건이라 만들지 않는다("설계와 착수는 다르다", ADR-0032-H). 모델은 그때 옳게 세운다.
+ */
+export { TwinLocation } from './twin-location.js'
+export { TwinEquipment } from './twin-equipment.js'
+export { TwinOperation } from './twin-operation.js'
+
+import { TwinLocation } from './twin-location.js'
+import { TwinEquipment } from './twin-equipment.js'
+import { TwinOperation } from './twin-operation.js'
+
+import { TwinModelQuery } from './twin-model-query.js'
+import { TwinModelItemQuery } from './twin-model-item-query.js'
+import { TwinModelTreeQuery } from './twin-model-tree-query.js'
+import { TwinModelMutation } from './twin-model-mutation.js'
+import { TwinLineageQuery } from './twin-lineage-query.js'
+
+export const entities = [TwinLocation, TwinEquipment, TwinOperation]
+export const resolvers = [TwinModelQuery, TwinModelItemQuery, TwinModelTreeQuery, TwinModelMutation, TwinLineageQuery]

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

@@ -0,0 +1,190 @@
+/*
+ * ISA-95 적합성 기준 — **표준이 요구하는 것의 목록.**
+ *
+ * ── 왜 이 파일이 필요한가 ──────────────────────────────────────────────────────
+ * 지금까지 화면은 "우리가 가진 축" 만 보였다. 그러면 채운 것은 세어지지만 **빠진 것은 셀 수 없다** —
+ * 없는 것은 화면에 없으므로 아무도 그것을 묻지 않는다. 표준 준수는 "우리 축에 표준 이름을 붙였다"
+ * 가 아니라 **표준의 목록을 기준으로 빠진 것이 없다**는 말이어야 한다. 기준이 코드로 있어야 그
+ * 문장을 검사할 수 있다.
+ *
+ * ── 세 층에서 본다 ────────────────────────────────────────────────────────────
+ * 표준 준수는 한 층의 일이 아니다. 개념마다 셋을 따로 본다:
+ *
+ *  · `structure` — **데이터구조**가 있나(커널 축·호스트 표에 이 개념의 자리가 있나)
+ *  · `behavior`  — **기능**이 그것을 쓰나(커널이 계획·집행·집계에서 실제로 다루나)
+ *  · `surface`   — **UI 노출**이 있나(사용자가 그것을 볼 수 있나)
+ *
+ * 셋을 합치면 "구조는 있는데 아무도 안 쓰는 컬럼" 과 "커널은 쓰는데 화면에 없는 사실" 이 같은
+ * 값으로 보인다. 실제로 이 프로젝트에서 둘 다 나왔다(인력 명세는 구조·기능이 있었지만 화면에
+ * 없었고, `properties` 는 구조만 있다).
+ *
+ * ── 값은 관측이 아니라 선언이다 ────────────────────────────────────────────────
+ * 여기 적힌 것은 **사람이 판단해 적은 사실**이다(자동 판정이 아니다). 그래서 틀릴 수 있고, 틀리면
+ * 여기를 고쳐야 한다 — 화면은 이 선언을 그대로 보이고 지어내지 않는다. 자동으로 알 수 있는 것
+ * 하나는 자동으로 한다: `axis` 가 커널 축 목록에 없으면 그것은 **구조가 없는 것**이다(오타 방지).
+ *
+ * ── 이 표가 커널에 없는 이유 ──────────────────────────────────────────────────
+ * 커널은 **런타임 모델의 SSOT** 다(무엇이 있는가). 이 표는 **참조 모델의 목록**이다(무엇이 있어야
+ * 하는가). 둘은 다른 종류의 사실이고, 후자는 커널을 배포하지 않고도 늘어야 한다.
+ */
+
+/** 한 층의 상태 — 있음 · 부분 · 없음. "부분" 을 두는 이유: 절반 있는 것을 있다고 하면 기준이 죽는다. */
+export type CoverageLevel = 'full' | 'partial' | 'none'
+
+export interface Isa95Concept {
+  /** 표준이 부르는 이름 — 이 표의 키다(우리 어휘가 아니라 표준 어휘). */
+  std: string
+  /** 표준의 어느 부분인가 — Part 2(자원 모델) · Part 4(일정·실적) 등. */
+  part: string
+  /** 사람이 읽는 이름(i18n 키). 화면이 번역한다. */
+  label: string
+  /** 우리 커널 축 — 있으면 데이터구조가 있는 것이다. 없으면 `null`. */
+  axis: string | null
+  /** 세 층의 상태. `structure` 는 `axis` 로도 검증된다. */
+  structure: CoverageLevel
+  behavior: CoverageLevel
+  surface: CoverageLevel
+  /** 왜 그 수준인지 — **모르는 것을 감추지 않기 위해** 한 줄로 적는다(i18n 키). */
+  note?: string
+  /**
+   * 자기 축이 없을 때 **어디서 보이나** — 그 사실을 들고 있는 축들.
+   *
+   * 「어디에」칸이 두 가지를 합쳐고 있었다: *아직 축이 없다(부채)* 와 *축일 수 없다(설계)*. 가용 능력은
+   * 개체가 아니라 자원의 지금 상태이므로 축이 될 수 없는데, 세 층이 다 완전한 줄이 "개념 축이 없습니다"
+   * 라고만 말하면 **표가 스스로 모순된 말을 한다**(다 됐다면서 없다고 한다).
+   *
+   * 그래서 축일 수 없는 것은 갈 곳을 가리킨다. 여기가 비어 있고 축도 없으면 그것은 **진짜 빈칸**이다.
+   */
+  shownOn?: string[]
+}
+
+/*
+ * 가용 능력(2026-08-12, 커널 0.6.8) — **판정과 이유가 상태에 실려 온다**(`capability {available, reason}`).
+ *
+ * 셋 다 완전인 근거: 상태가 판정을 들고 오고(시뮬·미러가 같은 함수로 파생한다), 배정이 같은 판정을
+ * 쓰고, 두 화면이 같은 낱말로 그 이유를 보인다(자원 탭 배지 · 인스펙션 관측 열).
+ *
+ * 왜 축이 없는가 — 가용 능력은 개체가 아니라 **자원의 지금 상태**다. 개념 카드로 세우면 사람·설비와
+ * 나란히 놓여 "능력이 몇 개인가" 를 세게 되는데, 그건 물을 일이 아니다.
+ */
+
+/*
+ * 생산 능력(2026-08-13, 커널 0.6.12) — **구간의 양을 표준 종류로 구분한다.**
+ *
+ * `structure` 완전: 계약이 보고서를 낸다(`operationsCapabilityOf`) — 구간(StartTime·EndTime) · 표준
+ * 열거값(Committed·Available·Unattainable) · 공정별 분해 · 제약하는 축. 낱말은 B2MML 대조 후 표준 것을
+ * 그대로 쓴다(우리 낱말을 만들지 않았다).
+ * `behavior` 완전: 약정은 오더에서, 달성불가는 자원 판정(`capabilityOf`)에서 온다 — 그리고 그 판정은
+ * 배정이 쓰는 것과 같은 한 벌이다. 표준의 `Unattainable` 정의가 그 판정과 겹친다.
+ * `surface` 완전: 두 자리에서 보인다 — 성과 화면이 현장 전체의 "앞으로 더 받을 수 있는 몫" 을, 공정
+ * 상세가 그 공정 하나의 분해(상한·약정·달성불가·가용)와 제약하는 축을 보인다. 두 화면은 **같은 낱말**을
+ * 쓴다(같은 i18n 키) — 같은 사실을 다르게 부르면 어느 쪽이 맞는지 아무도 모른다.
+ *
+ * 남은 것 — 표준은 **게시된(약속된) 능력**도 담는다(계산이 아니라 선언). 값을 실을 소스가 아직
+ * 침묵하므로 빈 축을 먼저 만들지 않는다(상태 쪽 `workCalendar` 를 지운 이유와 같다).
+ *
+ * 과거 분해(Used·Unused)는 이 보고서에 없다 — 그것은 실적이고 이미 두 곳에 있다(설비 OEE 의 가동/유휴,
+ * 성과 화면의 구간 가동률). 표준이 그 둘을 다른 종류로 부르므로 **합치지 않는다.**
+ */
+
+/*
+ * Part 2 — 자원 모델. 네 자원 각각이 **등급/정의 ↔ 개체** 이중구조를 갖는 것이 이 부분의 핵심이고,
+ * 그 이중성이 이 트윈의 뼈대이기도 하다.
+ */
+const PART2: Isa95Concept[] = [
+  { std: 'PersonnelClass', part: '2', label: 'twin.isa95.PersonnelClass', axis: 'personnelClasses', structure: 'full', behavior: 'full', surface: 'full' },
+  { std: 'Person', part: '2', label: 'twin.isa95.Person', axis: 'persons', structure: 'full', behavior: 'full', surface: 'full' },
+  { std: 'PersonnelCapability', part: '2', label: 'twin.isa95.PersonnelCapability', axis: null, shownOn: ['persons'], structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.capability' },
+  { std: 'EquipmentClass', part: '2', label: 'twin.isa95.EquipmentClass', axis: 'equipmentClasses', structure: 'full', behavior: 'full', surface: 'full' },
+  { std: 'Equipment', part: '2', label: 'twin.isa95.Equipment', axis: 'equipment', structure: 'full', behavior: 'full', surface: 'full' },
+  { std: 'EquipmentCapability', part: '2', label: 'twin.isa95.EquipmentCapability', axis: null, shownOn: ['equipment'], structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.capability' },
+  { std: 'PhysicalAssetClass', part: '2', label: 'twin.isa95.PhysicalAssetClass', axis: 'assetClasses', structure: 'full', behavior: 'full', surface: 'full' },
+  { 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 개체) — 구조는 저널이 갖는다. */
+  { 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' },
+  { std: 'ProcessSegment', part: '2', label: 'twin.isa95.ProcessSegment', axis: 'operations', structure: 'full', behavior: 'full', surface: 'full' },
+  /*
+   * 속성은 자원마다 붙는 확장이라 **자기 축이 아니다** — 그래서 `axis` 는 없지만 구조는 완전하다:
+   * 계약(`ResourceProperty`: 값·데이터형·단위·하위·등급속성)이 표준을 그대로 담고, 인제스트·상태·
+   * 화면이 그것을 통과시킨다.
+   *
+   * 기능은 **부분**이다: 호스트의 주행 추정기가 `speed` 를 읽어 이동 시간을 만드는 것이 유일한 소비처다
+   * (다른 속성은 아직 아무도 읽지 않는다). 그 사실을 `full` 로 올리면 표가 거짓이 된다.
+   */
+  { std: 'Property', part: '2', label: 'twin.isa95.Property', axis: null, structure: 'full', behavior: 'partial', surface: 'full', note: 'twin.isa95.note.property' }
+]
+
+/*
+ * Part 4 — 일정과 실적.
+ *
+ * **2026-08-11 이전에는 이 부분이 거의 비어 있었다.** 오더·작업은 런타임과 저널에 실재하는데 조회
+ * 모델의 축이 아니었고, 그래서 "이 트윈이 표준의 어디를 채우나" 라는 질문에 절반만 답했다.
+ *
+ * 커널이 계약을 넓혀(`source: 'state'`) 두 축이 추가되었다 — 이제 요구(`orders`)와 응답(`tasks`)을 개념으로
+ * 가리켜 걸어 들어갈 수 있다. 남은 것은 **과거로 다시 계산하는 길**(저널 커서 페이징)과 능력·검사 명세다.
+ */
+const PART4: Isa95Concept[] = [
+  { std: 'OperationsDefinition', part: '4', label: 'twin.isa95.OperationsDefinition', axis: 'productionSpec', structure: 'full', behavior: 'full', surface: 'partial', note: 'twin.isa95.note.opsdef' },
+  /*
+   * 2026-08-11 — **축이 추가되었다**(커널 0.6.3 · `source: 'state'`). 요구는 `orders`, 응답은 `tasks` 다.
+   *
+   * `structure` 를 `full` 로 올린다: 담을 자리가 계약에 있다(상태 계약 + 축 선언). **테이블 투영이
+   * 없는 것은 결손이 아니다** — 이 축의 정본은 저널이고, 투영하지 않는 것이 결정이다(ADR-0032-D).
+   *
+   * `surface` 도 `full` 이다(같은 날 두 번째 단계): 목록·상세·관계에 더해 **과거로 다시 계산하는 길**이 화면에
+   * 있다 — 시각 커서를 옮기면 그 시점의 사실이 나오고, 무엇을 근거로 답했는지도 화면이 말한다
+   * (라이브=권위 · 저널=파생 · 접은 리비전). 실측: 이른 시각 0건 · 하루 뒤 504건.
+   */
+  { std: 'OperationsSchedule', part: '4', label: 'twin.isa95.OperationsSchedule', axis: 'orders', structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.schedule' },
+  { std: 'OperationsPerformance', part: '4', label: 'twin.isa95.OperationsPerformance', axis: 'tasks', structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.performance' },
+  { std: 'OperationsCapability', part: '4', label: 'twin.isa95.OperationsCapability', axis: null, shownOn: ['operations'], structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.opscapability' },
+  /*
+   * 2026-08-12 — **축이 추가되었다**(커널 0.6.5). 자원 아홉이 가리키던 참조에 대상이 생겼고, 없는 명세를
+   * 가리키면 선 채움이 끊어진 참조로 센다.
+   *
+   * 기능이 **`partial` 로 살아났다**(커널 0.6.6): 결과(`TestResult`)가 계약에 들어오면서 커널이 배정에서
+   * 그것을 본다 — 만료·불합격이면 그 자격은 성립하지 않는다(실측: 만료된 용접사는 용접 작업 5건 중 한
+   * 번도 배정되지 않았다).
+   *
+   * `full` 이 아닌 이유는 둘이다: **사람만 판정한다**(설비·자산의 검사 결과는 아직 배정에 쓰지 않는다),
+   * 그리고 결과가 없으면 판정하지 않는다(선언한 것만 제약이 된다 — 그건 결손이 아니라 규율이다).
+   */
+  { std: 'TestSpecification', part: '4', label: 'twin.isa95.TestSpecification', axis: 'testSpecifications', structure: 'full', behavior: 'full', surface: 'full', note: 'twin.isa95.note.test' },
+  { 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' }
+]
+
+/** 표준이 요구하는 것 전부 — 이 배열이 곧 기준이다. */
+export const ISA95_CONCEPTS: Isa95Concept[] = [...PART2, ...PART4]
+
+/**
+ * 적합성 보고 — **채운 것과 빠진 것을 함께.**
+ *
+ * `axis` 를 커널 축 목록과 맞춰 본다: 축이 있다고 적혀 있는데 커널에 없으면 그 선언이 낡은 것이므로
+ * **구조 없음으로 낮추고 그 사실을 말한다**(조용히 통과시키면 이 표가 거짓이 된다).
+ */
+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
+  })
+  /* 채운 수는 `full` 만 센다 — 부분을 채운 것으로 세면 기준이 스스로를 속인다. */
+  const count = (k: 'structure' | 'behavior' | 'surface') => concepts.filter(c => c[k] === 'full').length
+  return {
+    model: 'ISA-95',
+    concepts,
+    totals: { concepts: concepts.length, structure: count('structure'), behavior: count('behavior'), surface: count('surface') }
+  }
+}