@things-factory/headless-twin 10.0.12 → 10.0.14

package/server/service/reference/reference-assessment.ts

@@ -0,0 +1,250 @@
+import type { IngestWarning, ReferenceMaster } from './reference-master.js'
+
+/*
+ * **원본에서 읽은 뒤의 총평** — 사람이 한 장으로 읽는다.
+ *
+ * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────
+ * 읽기가 끝나면 화면에 남는 것은 경고 열 줄이었고, 그 안에 이유가 문장으로 묻혀 있고 UUID 수백 개가
+ * 붙어 있었다. 그래서 사람이 「가져올 것은 다 들어왔나」·「무엇이 비었나」·「다음에 무엇을 하면
+ * 나아지나」를 스스로 세어야 했다 — 실제로 그 셋을 손으로 세는 대화가 하루를 채웠다.
+ *
+ * 그 셋은 이미 우리가 아는 사실이다. 세어 두었으니 **정리해서 내면 된다.**
+ *
+ * ── 두 층으로 나눈다 ────────────────────────────────────────────────────────
+ * 여기는 **사실 층**이다: 센 것과 그 사유 코드만 담고 문장을 만들지 않는다. 화면이 표로 그리고,
+ * 사람이 더 알고 싶으면 그때 AI 가 이 사실**만** 근거로 서술한다(말 층).
+ *
+ * **AI 는 로드베어링이 아니다.** 호출이 꺼져 있거나 실패해도 이 표가 그대로 화면에 남아야 한다 —
+ * 그래서 사실 층이 스스로 완결이다.
+ *
+ * ── 무엇을 지어내지 않는가 ──────────────────────────────────────────────────
+ * 「없음」의 뜻을 셋으로 구분해 둔다. 뭉치면 조치가 달라지는 것들이 한 칸에 섞인다.
+ *  · `gaps` — 원본에 있는데 우리가 옮기지 못했다. 고칠 대상이 있다(원본의 빈 칸이거나 우리 매핑).
+ *  · `absent` — 이 원본에 그 **개념이 없다.** 빠진 것이 아니므로 고칠 것이 없다.
+ *  · `grounding` — 값이 들어왔지만 **근거가 저장된 값이 아니다**(원본의 계산 규칙에서 왔다).
+ */
+
+/** 센 것 — 화면이 그대로 표로 그린다. */
+export interface AssessmentCounts {
+  locations: number
+  areas: number
+  equipment: number
+  materialDefinitions: number
+  operations: number
+  /** 생산 선언이 없으면 없다 — 0 과 구별한다(선언 자체가 없는 것과 비어 있는 것은 다르다). */
+  materials?: number
+  materialsWithHome?: number
+  routes?: number
+  recipes?: number
+  recipesWithRoute?: number
+  /** 공정을 말하는 투입 / 전체 투입 — 공정별 소요를 아는 정도. */
+  taggedInputs?: number
+  totalInputs?: number
+  /** 시험 명세(점검표)의 수 — 선언되지 않았으면 없다(0 과 구별한다). */
+  testSpecifications?: number
+  /** 그 명세들이 선언한 판정 기준의 수. */
+  criteria?: number
+  /**
+   * 그중 **아무 한계도 말하지 않는** 기준의 수 — 커널의 `criterionSaysNothing` 과 같은 판정이다.
+   *
+   * 이 수가 0 이 아니면 「관리점이 있다」가 「판정된다」를 뜻하지 않는다. 세지 않으면 그 구별이 사라진다.
+   */
+  criteriaWithoutLimit?: number
+}
+
+/** 옮기지 못한 것 한 갈래 — 건수 큰 것부터. */
+export interface AssessmentGap {
+  /** 무엇을 옮기다 못 옮겼나 — 커넥터가 붙인 이름(`material home warehouse`). */
+  what: string
+  count: number
+  /** 못 옮긴 원본 값 몇 개 — 전부가 아니라 표본이다(수백 개가 붙던 자리다). */
+  sample?: string
+  /** 그 자리에 대신 들어간 값. */
+  fallback?: string
+}
+
+export interface ImportAssessment {
+  source: string
+  siteId: string
+  siteName?: string
+  system?: string
+  built: AssessmentCounts
+  /**
+   * **원본이 가지고 있던 수** — 커넥터가 말해 준 경우에만 있다.
+   *
+   * 이름을 `origin` 이라 하지 않는다 — 화면에서 그 낱말이 이미 **트윈의 출처**(`summary.origin`:
+   * 템플릿인가 원본인가)를 뜻한다. 같은 이름을 두 뜻으로 쓰면 읽는 사람이 헷갈린다.
+   *
+   * `built` 와 비교해 「전부 옮겼는가」를 사람이 직접 셀 수 있게 한다. 커넥터가 말하지 않으면 이 자리는
+   * 비어 있고, 화면은 분모 없이 옮긴 수만 보인다 — **분모를 지어내지 않는다.**
+   */
+  originCounts?: Record<string, number>
+  gaps: AssessmentGap[]
+  /** 이 원본에 개념이 없는 자리 — 커널 낱말로 적는다(화면이 번역한다). */
+  absent: string[]
+  /**
+   * 값이 들어왔지만 **근거가 원본의 저장된 값이 아닌 것** — 파생·유추된 값이다.
+   *
+   * 이것을 `gaps` 에 섞으면 안 된다. 빈 자리가 아니라 **채워진 자리**이고, 사람이 물을 것은
+   * 「왜 비었나」가 아니라 「그 값을 믿어도 되나」다. 조치도 다르다 — 원본을 채우는 것이 아니라
+   * 그 규칙이 바뀌면 이 값도 바뀐다는 사실을 아는 것이다.
+   */
+  derived: AssessmentGap[]
+  /** 되물은 횟수·잘린 목록 같은 운영 사실. */
+  notes: IngestWarning[]
+}
+
+/** 이 마스터가 개념을 선언했나 — 「없다」와 「비어 있다」를 구분한다. */
+const declared = (v: unknown): boolean => Array.isArray(v) ? v.length > 0 : v !== undefined && v !== null
+
+/**
+ * 마스터 한 벌 → 총평의 사실 층.
+ *
+ * 경고를 두 갈래로 나눈다: `connector-mapping-fallback` 은 **옮기지 못한 것**이므로 `gaps` 로,
+ * 나머지(파생된 값·되물은 횟수·잘린 목록)는 `notes` 로 그대로 나른다. 판단하지 않는다 — 무엇이
+ * 심각한지는 건수와 그 자리의 뜻이 말하고, 그 해석은 사람이나 말 층의 몫이다.
+ */
+export function assessMaster(master: ReferenceMaster, siteId: string): ImportAssessment {
+  const m: any = master
+  const d = m.productionSpec?.definition
+  const inputs = (d?.recipes ?? []).flatMap((r: any) => r.inputs ?? [])
+
+  const built: AssessmentCounts = {
+    locations: (m.locations ?? []).length,
+    areas: (m.locations ?? []).filter((l: any) => l.role === 'area' || l.role === 'both').length,
+    equipment: (m.equipment ?? []).length,
+    materialDefinitions: (m.materialDefinitions ?? []).length,
+    operations: (m.operations ?? []).length,
+    ...(declared(m.testSpecifications)
+      ? {
+          testSpecifications: m.testSpecifications!.length,
+          criteria: m.testSpecifications!.reduce((n, t) => n + (t.criteria?.length ?? 0), 0),
+          /*
+           * **한계를 말하지 않는 기준** — 커널의 `criterionSaysNothing` 과 같은 판정이다. 기준이
+           * 선언됐다는 사실만 있고 판정할 재료가 없는 자리이고, 그것을 세지 않으면 「관리점이 있다」가
+           * 「판정된다」로 읽힌다.
+           */
+          criteriaWithoutLimit: m.testSpecifications!.reduce(
+            (n, t) => n + (t.criteria ?? []).filter(c => !c.expression && c.limit?.minimum === undefined && c.limit?.maximum === undefined).length,
+            0
+          )
+        }
+      : {}),
+    ...(d
+      ? {
+          materials: (d.materials ?? []).length,
+          materialsWithHome: (d.materials ?? []).filter((x: any) => x.locationType).length,
+          routes: (d.routes ?? []).length,
+          recipes: (d.recipes ?? []).length,
+          recipesWithRoute: (d.recipes ?? []).filter((x: any) => x.route).length,
+          totalInputs: inputs.length,
+          taggedInputs: inputs.filter((i: any) => i.operation).length
+        }
+      : {})
+  }
+
+  /* 원본의 수는 커넥터가 말한 그대로 나른다 — 여기서 고치거나 채우지 않는다. */
+  const originCounts = m.originCounts && Object.keys(m.originCounts).length ? { ...m.originCounts } : undefined
+
+  const gaps: AssessmentGap[] = []
+  const derived: AssessmentGap[] = []
+  const notes: IngestWarning[] = []
+  /*
+   * 커넥터가 「대체」 수집기로 남기는 것 중 일부는 **빈 자리가 아니라 파생된 값**이다(산출량이 원본의
+   * 계산 규칙에서 온 경우처럼). 같은 통로로 오지만 뜻이 달라 구분해 담는다 — 이름에 그 사실이 적혀 있다.
+   */
+  const isDerived = (field: string) => /derived|not a stored field/i.test(field)
+  for (const w of m.warnings ?? []) {
+    if (w?.code === 'connector-mapping-fallback' && w.params?.field) {
+      const values = String(w.params.values ?? '')
+      const bin = isDerived(String(w.params.field)) ? derived : gaps
+      bin.push({
+        what: String(w.params.field),
+        count: Number(w.params.count ?? 0),
+        /* 값은 표본만 — 이 자리에 UUID 수백 개가 붙어 화면을 밀어냈다. 전체는 경고 원문에 남는다. */
+        ...(values ? { sample: values.length > 120 ? `${values.slice(0, 120)}…` : values } : {}),
+        ...(w.params.fallback ? { fallback: String(w.params.fallback) } : {})
+      })
+      continue
+    }
+    notes.push(w)
+  }
+  gaps.sort((a, b) => b.count - a.count)
+  derived.sort((a, b) => b.count - a.count)
+
+  /*
+   * 이 원본에 개념이 없는 자리. **커널 낱말로 적는다** — 화면이 그것으로 번역하고, 개념 지도가 이미
+   * 같은 낱말을 쓴다(두 화면이 다른 말을 하면 사람이 둘을 다른 사실로 읽는다).
+   */
+  const absent: string[] = []
+  if (!declared(m.persons)) absent.push('persons')
+  if (!declared(m.assets)) absent.push('assets')
+  if (!declared(m.testSpecifications)) absent.push('testSpecifications')
+  if (!declared(m.personnelClasses)) absent.push('personnelClasses')
+  if (!declared(m.assetClasses)) absent.push('assetClasses')
+  if (!declared(m.materialClasses)) absent.push('materialClasses')
+  if (!d) absent.push('productionSpec')
+
+  return {
+    source: m.source,
+    siteId,
+    siteName: m.siteName,
+    system: m.system,
+    built,
+    ...(originCounts ? { originCounts } : {}),
+    gaps,
+    derived,
+    absent,
+    notes
+  }
+}
+
+/** 사람이 읽는 줄 — 터미널·로그가 읽는다(화면은 구조를 그대로 그린다). */
+export function formatAssessment(a: ImportAssessment): string {
+  const c = a.built
+  const out: string[] = []
+  /**
+   * 분모가 있으면 함께 적는다 — 「1,261」과 「원본 1,408 중 1,261」은 다른 말이다.
+   * 커넥터가 그 수를 말하지 않았으면 옮긴 수만 적는다(지어내지 않는다).
+   */
+  const n = (key: keyof AssessmentCounts, v?: number) => {
+    if (v === undefined) return '없음'
+    const o = a.originCounts?.[key as string]
+    return o === undefined ? String(v) : o === v ? `${v}(원본 전부)` : `${v} / 원본 ${o}`
+  }
+  out.push(`총평 ${a.siteName ?? a.siteId} (${a.system ?? '?'}) — 원본 ${a.source}`)
+  out.push(
+    `  선 것: 로케이션 ${n('locations', c.locations)}(존 ${c.areas}) · 설비 ${n('equipment', c.equipment)} · ` +
+      `품목 정의 ${n('materialDefinitions', c.materialDefinitions)} · 공정 ${n('operations', c.operations)}`
+  )
+  if (c.materials !== undefined) {
+    out.push(
+      `         자재 ${n('materials', c.materials)}(보관 로케이션 있는 것 ${c.materialsWithHome}) · ` +
+        `경로 ${n('routes', c.routes)} · 레시피 ${n('recipes', c.recipes)}(경로 붙은 것 ${c.recipesWithRoute}) · ` +
+        `투입 ${n('totalInputs', c.totalInputs)}(공정을 말하는 것 ${c.taggedInputs})`
+    )
+  } else {
+    out.push('         생산 선언 없음 — 레시피가 하나도 성립하지 않았다')
+  }
+  if (a.gaps.length) {
+    out.push('  옮기지 못한 것(건수 순):')
+    for (const g of a.gaps) out.push(`    ${String(g.count).padStart(6)}  ${g.what}${g.sample ? ` — ${g.sample}` : ''}`)
+  }
+  if (a.derived.length) {
+    out.push('  파생된 값(저장된 값이 아니다):')
+    for (const g of a.derived) out.push(`    ${g.what}${g.sample ? ` — ${g.sample}` : ''}`)
+  }
+  if (c.testSpecifications) {
+    /*
+     * 관리 기준은 계측이 오는지와 무관하게 값이 있다 — 「관리점이 셋인데 둘은 아무 한계도 말하지
+     * 않는다」를 여기서 볼 수 있어야 판정에 근거가 있는지 사람이 안다.
+     */
+    out.push(
+      `  관리 기준: 점검표 ${n('testSpecifications', c.testSpecifications)} · 기준 ${c.criteria ?? 0}` +
+        (c.criteriaWithoutLimit ? ` (한계를 말하지 않는 것 ${c.criteriaWithoutLimit})` : '')
+    )
+  }
+  if (a.absent.length) out.push(`  이 원본에 개념이 없는 자리: ${a.absent.join(', ')}`)
+  for (const n of a.notes) out.push(`  참고 ${n.code}: ${n.message}`)
+  return out.join('\n')
+}

package/server/service/reference/reference-live.ts

@@ -1,6 +1,7 @@
+import { twinLog, twinWarn, twinError } from '../../engine/log.js'
 import { getRepository } from '@things-factory/shell'
 
-import { getAdapter, type ConnectionConfig, type SiteDescriptor } from './reference-adapter.js'
+import { getAdapter, type ConnectionConfig, type LiveFeedContinuity, type SiteDescriptor } from './reference-adapter.js'
 import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
@@ -25,7 +26,18 @@ export async function startReferenceLiveFeed(
   adapterType: string,
   cfg: ConnectionConfig,
   site: SiteDescriptor,
-  instanceId: string
+  instanceId: string,
+  /**
+   * **어느 레퍼런스에서 읽는 피드인가** — 읽기 커서를 저장할 자리를 가리킨다(§`loadLiveCursor`).
+   *
+   * 부르는 쪽이 `TwinReference` 를 이미 들고 있으므로 그 이름을 넘긴다. 처음에는 `cfg`·`site` 에서
+   * 찾으려 했는데 **둘 다 그 값을 가질 수 없다**: `cfg` 는 사람이 화면에서 입력한 접속 설정이고
+   * (`endpoint`·`token`…), `site` 는 커넥터가 원본에서 발견한 것이다 — **레퍼런스의 이름은 호스트가
+   * 붙이는 것이고 원본은 그것을 모른다.** 커넥터가 채울 수 없는 값을 커넥터에서 읽으려 한 것이 잘못이었다.
+   *
+   * 주지 않으면 커서를 잇지 않고 **그 사실을 말한다**(조용히 창이 미끄러지지 않게).
+   */
+  source?: string
 ): Promise<boolean> {
   const adapter = getAdapter(adapterType)
   if (!adapter?.openLiveFeed) return false
@@ -38,29 +50,149 @@ export async function startReferenceLiveFeed(
   TwinEngine.startLive(instanceId, domainId, det.kind, await TwinEngine.withSpaceTimeBase(det.model, domainId))
 
   stopReferenceLiveFeed(instanceId) // 재기동 시 이전 피드 정리
+  /*
+   * **어디까지 읽었나를 이 층이 들고 건넨다**(§`LiveFeedContinuity`, 2026-08-23).
+   *
+   * 어댑터가 이 값을 자기 사물함에 두면 원본이 늘 때마다 저장 기제가 늘고, 그중 하나가 조용히 다르게
+   * 동작한다. 그리고 커널이 이미 갈라 두었다: 「원천이 애초에 다시 말해 주지 않는 축」은 재기동
+   * 연속성으로 이어받는다(§`hydrateContinuity`) — 읽기 커서가 정확히 그 성질이다.
+   *
+   * 없으면 `undefined` 를 건넨다 — 그것이 「첫 붙음」이라는 사실이고, 그때만 어댑터가 되돌아볼 날수로
+   * 첫 창을 만든다. 빈 객체로 메우지 않는다(그러면 첫 붙음과 이어 붙음이 같아진다).
+   */
+  const continuity = await loadLiveCursor(domainId, instanceId, source)
   const unsubscribe = adapter.openLiveFeed(cfg, site, (records: unknown[]) => {
     if (!TwinEngine.owns(domainId, instanceId)) {
       stopReferenceLiveFeed(instanceId) // 인스턴스 사라지면 자가 정지(안전망)
       return
     }
+    const offered = Array.isArray(records) ? records.length : records ? 1 : 0
     const { accepted, rejected } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
-    if (accepted.length) TwinEngine.ingestLive(domainId, instanceId, accepted)
+    /*
+     * 커널이 **몇 건을 실제로 받았나**를 함께 본다. 트윈이 라이브로 돌지 않으면 `ingestLive` 가 0 을
+     * 돌려주고, 그 차이가 곧 「바닥에 버려진 수」다. 이것을 통과로 세면 멈춘 트윈이 100% 로 보인다.
+     */
+    const applied = accepted.length ? TwinEngine.ingestLive(domainId, instanceId, accepted) : 0
+    const undelivered = accepted.length - applied
     /*
      * **거부한 것을 조용히 버리지 않는다.** 예전에는 `rejected` 를 받지도 않았다 — 커넥터의 매핑이
      * 틀리면 트윈은 「아무 일도 일어나지 않는」 모습이 되고, 로그에도 아무 흔적이 없었다.
      *
-     * 지금은 이유와 함께 남긴다. 화면까지 나르는 것은 다음 일이다(라이브 계측은 초당 여러 건이라
-     * 건마다 방송하면 그 자체가 부하가 된다 — 집계해 낼 자리가 필요하다).
+     * 그다음 자리였던 「화면까지 나르기」를 이제 채운다. 건마다 브로드캐스팅하지 않고 **집계**한다 — 통과분까지
+     * 함께 세는 이유는, 거부만 세면 「유입 없음」과 「정상」이 둘 다 거부 0 으로 같아 보이기 때문이다.
+     * 조회는 `twinIngestHealth`.
      */
+    /*
+     * **읽었다는 것 자체가 사실이다** — 빈 읽기도 성공이므로 단절 기록을 지운다(§`onReadFailure`).
+     * 그 둘을 섞으면 조용한 원본이 끊긴 원본으로 보인다.
+     */
+    TwinEngine.clearIngestReadFailure(domainId, instanceId)
+    TwinEngine.recordIngestResult(domainId, instanceId, offered, rejected, Date.now(), undelivered)
     if (rejected.length) {
       const why = rejected[0]?.errors?.join(' · ') ?? 'unknown'
-      console.warn(`[twin-live] "${instanceId}": ${rejected.length} record(s) rejected — e.g. ${why}`)
+      twinWarn(`[twin-live] "${instanceId}": ${rejected.length}/${offered} record(s) rejected — e.g. ${why}`)
     }
-  })
+    /* 버려진 것은 로그에도 남긴다 — 화면을 보지 않는 사람도 알아야 한다(사실이 사라지는 중이다). */
+    if (undelivered > 0) {
+      twinWarn(
+        `[twin-live] "${instanceId}": ${undelivered}/${offered} record(s) NOT delivered — the twin is not running live; ` +
+          `records are being discarded. Start the twin, or disconnect the feed.`
+      )
+    }
+  }, continuity)
   feeds.set(instanceId, unsubscribe)
   return true
 }
 
+/**
+ * 그 원본의 읽기 커서를 불러오고, 움직이면 저장하는 통로를 만든다.
+ *
+ * 커서는 **원본(`TwinReference`)의 것**이지 인스턴스의 것이 아니다 — 한 원본이 여러 인스턴스를 낳고
+ * (`scopeSpec.produced`) 읽는 것은 한 번이다. 인스턴스마다 커서를 두면 같은 표를 여러 번 읽는다.
+ *
+ * 저장 실패는 **삼키지 않고 말한다.** 조용히 실패하면 다음 재기동에서 창이 다시 미끄러지고, 그 손실은
+ * 오류 없이 사라진다 — 이 컬럼을 만든 이유가 바로 그것이다.
+ */
+async function loadLiveCursor(
+  domainId: string,
+  /** 읽기 실패를 적을 트윈 — 커서는 레퍼런스의 것이지만 **건강은 인스턴스의 것**이다(한 레퍼런스가 여럿을 낳는다). */
+  instanceId: string,
+  source?: string
+): Promise<LiveFeedContinuity | undefined> {
+  if (!source) {
+    /* 원본을 가리킬 수 없으면 저장할 자리도 없다 — 그 사실을 말한다(조용히 커서 없이 돌지 않게). */
+    twinWarn('[twin-live] live cursor not carried — the caller did not say which reference this feed reads from')
+    return undefined
+  }
+  const repo = getRepository(TwinReference)
+  const row = await repo.findOne({ where: { domain: { id: domainId } as any, source } }).catch(() => null)
+  if (!row) {
+    twinWarn(`[twin-live] live cursor not carried — no reference row for source "${source}"`)
+    return undefined
+  }
+  const stored = row.liveCursor
+  if (stored?.firstAttachedAt) {
+    twinLog(`[twin-live] "${source}": resuming from stored cursor — knowledge starts ${stored.firstAttachedAt}`)
+  }
+  return {
+    cursor: stored ?? undefined,
+    /*
+     * **원본에 닿지 못했다** — 어댑터가 알리면 상태에 적는다(§`onReadFailure`).
+     *
+     * 로그로는 어댑터가 이미 말하고 있었다(재시도 경고). 그러나 **로그는 사람이 볼 때만 값이 있다** —
+     * 화면이 말하려면 조회 가능한 상태에 있어야 한다.
+     *
+     * ── `status` 를 건드리지 않는다 (2026-08-23, 되돌린 자리) ────────────────────
+     * 처음에는 레퍼런스 행의 `status` 를 `'error'` 로도 적었다 — 「목록이 「연결됨」이라 말하면서 실제로는
+     * 못 읽는 상태를 없애려고」. **그것이 피드를 영구히 껐다.**
+     *
+     * 부팅 재부착은 `status: 'connected'` 인 레퍼런스만 되살린다(§`resumeReferenceLiveFeeds`). 그래서
+     * 원본이 **잠깐** 끊긴 것이 그 행을 `error` 로 만들고, 다음 재기동에서 그 피드는 아예 붙지 않았다 —
+     * 실측으로 그렇게 났다(09:25 판에 `[twin-live]` 줄이 한 줄도 없었다).
+     *
+     * 두 축을 한 칸에 섞은 것이 원인이다:
+     *   `status`      **연결 설정이 성립하나** — 접속 시험·마스터 동기가 정하는 축(재부착의 자격이다)
+     *   읽기 실패      **지금 닿나** — 오갈 수 있는 사실이고, 유입 장부가 그 축을 갖는다
+     *
+     * 그러니 여기서는 `lastError` 에만 적는다(사람이 목록에서 이유를 볼 수 있게). 「지금 닿나」는
+     * `ingestHealth().readFailure` 가 답하고, 성공한 주기가 그것을 지운다.
+     */
+    onReadFailure: ({ reason, stream }) => {
+      TwinEngine.recordIngestReadFailure(domainId, instanceId, reason, Date.now(), stream)
+      twinWarn(`[twin-live] "${source}": cannot read from the source${stream ? ` (${stream})` : ''} — ${reason}`)
+      repo
+        .update({ id: row.id }, { lastError: `live: ${reason}` } as any)
+        .catch(err => twinWarn(`[twin-live] "${source}": read failure not recorded — ${err?.message ?? err}`))
+    },
+    /**
+     * **읽었는데 창을 넘길 수 없다** — 위와 조치가 반대인 사실이다 (2026-08-24).
+     *
+     * 이 문을 만들기 전에는 이 사실이 `onReadFailure` 로 나갔다. 그래서 화면이 「원본에 닿지 못한다」고
+     * 말했는데 실제로는 원본이 **답한** 상태였고, 그 답의 모양이 커서를 이긴 것이었다. 사람은 원본을
+     * 의심하고 기다리는데 기다림으로는 영원히 풀리지 않는다 — **원인을 반대 방향으로 가리켰다.**
+     *
+     * `status` 를 건드리지 않는 규율은 위와 같다(재부착의 자격이다). `lastError` 에는 적는다 — 목록에서
+     * 이유를 볼 수 있어야 하고, 「닿지 못한다」와 다른 문장이어야 한다.
+     */
+    onCursorStall: ({ reason, stream }) => {
+      TwinEngine.recordIngestCursorStall(domainId, instanceId, reason, Date.now(), stream)
+      twinWarn(
+        `[twin-live] "${source}": read the source but the cursor cannot advance` +
+          `${stream ? ` (${stream})` : ''} — ${reason}. Waiting will not clear this.`
+      )
+      repo
+        .update({ id: row.id }, { lastError: `live cursor stalled: ${reason}` } as any)
+        .catch(err => twinWarn(`[twin-live] "${source}": cursor stall not recorded — ${err?.message ?? err}`))
+    },
+    onCursor: next => {
+      /* 어댑터가 준 모양을 그대로 적는다 — 이 층은 흐름의 뜻을 모른다(열쇠는 어댑터가 정한다). */
+      repo
+        .update({ id: row.id }, { liveCursor: next } as any)
+        .catch(err => twinWarn(`[twin-live] "${source}": live cursor not saved — ${err?.message ?? err}`))
+    }
+  }
+}
+
 /** 라이브 피드 중지(unsubscribe). */
 export function stopReferenceLiveFeed(instanceId: string): boolean {
   const unsub = feeds.get(instanceId)
@@ -151,7 +283,7 @@ export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; f
         }
         attached.set(p.instanceId, ref.source)
         try {
-          const ok = await startReferenceLiveFeed(domainId, ref.adapterType, ref.connectionConfig ?? {}, site, p.instanceId)
+          const ok = await startReferenceLiveFeed(domainId, ref.adapterType, ref.connectionConfig ?? {}, site, p.instanceId, ref.source)
           if (ok) resumed.push(p.instanceId)
           else failed.push({ instanceId: p.instanceId, error: 'adapter has no openLiveFeed' })
         } catch (e: any) {
@@ -160,12 +292,12 @@ export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; f
       }
     }
   } catch (e: any) {
-    console.error('[twin-live] feed resume scan failed', e?.message)
+    twinError('[twin-live] feed resume scan failed', e?.message)
   }
 
-  if (resumed.length) console.log(`[twin-live] reattached ${resumed.length} feed(s): ${resumed.join(', ')}`)
+  if (resumed.length) twinLog(`[twin-live] reattached ${resumed.length} feed(s): ${resumed.join(', ')}`)
   /* **조용히 넘기지 않는다** — 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다. */
-  for (const f of failed) console.warn(`[twin-live] "${f.instanceId}" feed NOT reattached — ${f.error}`)
+  for (const f of failed) twinWarn(`[twin-live] "${f.instanceId}" feed NOT reattached — ${f.error}`)
   return { resumed, failed }
 }
 

package/server/service/reference/reference-master.ts

@@ -7,7 +7,7 @@
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
-import type { DomainSystem, EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel'
+import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/twin-kernel'
 
 export interface RefLocation {
   id: string
@@ -127,6 +127,16 @@ export interface RefTestSpecification {
   /** 표시명 — i18n 키일 수 있다. 읽는 어휘를 하나로 맞추려고 인제스트가 `name` 으로 옮긴다. */
   description?: string
   version?: string
+  /**
+   * 판정 기준들 — 커널 계약의 `TestSpecification.criteria` 를 그대로 나른다.
+   *
+   * **경계에서 어휘를 갈지 않는다.** 커널 타입을 그대로 쓰므로 `limit.{minimum,maximum,uom}` ·
+   * `expression` · `evaluatedPropertyId` 가 원본에서 커널까지 한 이름으로 간다.
+   *
+   * 선언하지 않아도 명세는 성립한다(이름만으로 「무엇으로 검증했나」에 답한다). 선언하면 **판정에
+   * 근거가 있는지**를 물을 수 있게 된다 — 커널의 `criterionSaysNothing` 이 그것을 센다.
+   */
+  criteria?: TestSpecificationCriterion[]
 }
 
 export interface RefEquipment {
@@ -350,7 +360,7 @@ export type MasterOrigin =
    * `source` 는 **레퍼런스 등록 이름**이고 그 참조가 보고하는 사이트 전부에 같다. 그래서 어느 사이트에서
    * 온 트윈인지는 `siteId` 가 있어야 안다 — 없으면 다시 읽기가 사이트를 찾지 못한다(2026-08-18 실측:
    * 사이트가 여러 개인 참조에서 온 트윈은 재동기가 전부 거절됐다. 참조 이름을 사이트별 마스터의
-   * `source`(=인스턴스 id)와 견주고 있었다 — 서로 다른 것을 비교한 것이다).
+   * `source`(=인스턴스 id)와 비교하고 있었다 — 서로 다른 것을 비교한 것이다).
    */
   | { kind: 'reference'; source: string; siteId?: string; spaceId?: string }
   /**
@@ -407,6 +417,21 @@ export interface ReferenceMaster {
    * BOM 을 설명 문서에만 적어 둔 채 키트를 못 만드는 트윈을 만든 원인). 근거는 커널 계약 주석에.
    */
   productionSpec?: unknown
+  /**
+   * **이 원본이 식별자를 만드는 이름공간** — `TwinModelDef.identity` 로 통과한다.
+   *
+   * **선언이 없으면 커널이 거절한다** (0.7.45~). 예전에는 상수 프리픽스로 팔레트·트레일러·문서를
+   * 만들었는데(`0614141` — GS1 이 규격 예제로 쓰다 버린 값이고 `06…` 은 실 배정 대역이다), 그 값은
+   * 저널에 영원히 남으면서 지어낸 것이라고 말해 주는 데가 없었다. 그래서 커널이 만들지 않는다.
+   *
+   * 원본이 자기 도메인을 말하면 그 아래에서 만든다 — 그것이 표준 정합이다(CBV 2.0 §8.2.4·§8.5.5,
+   * 「그 인터넷 도메인 소유자가 배정한다」). GS1 키를 쓰려면 `documentTypes` + `companyPrefix` 이고,
+   * 그때 **자리 수가 맞아야 한다**(SGTIN 은 프리픽스 + 품목참조 = 13자리, GS1 TDS).
+   *
+   * 정체성은 생산과 무관하므로 `productionSpec` 이 아니라 **모델**이 갖는다 — 창고·야드는 아무것도
+   * 생산하지 않으면서 팔레트·트레일러를 식별한다.
+   */
+  identity?: unknown
   /**
    * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 가동되는 공장).
    * 공정이 인원을 요구하는데 사람이 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
@@ -435,6 +460,21 @@ export interface ReferenceMaster {
    * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
    */
   warnings?: IngestWarning[]
+  /**
+   * **원본이 가진 수** — 옮긴 수의 분모다.
+   *
+   * 총평은 도착한 모델만 볼 수 있어서 「레시피 1,261」까지만 말할 수 있었다. 그런데 사람이 묻는 것은
+   * 「그게 전부인가」다 — 원본에 1,408개가 있었고 147개를 옮기지 못했다면 그 사실이 총평의 첫 줄에
+   * 있어야 한다. 실제로 사용자가 품목 2,789 와 자재 1,789 의 차이를 화면에서 읽어 내지 못해 직접
+   * 물었다(2026-08-22).
+   *
+   * 분모를 아는 것은 **커넥터뿐이다.** 그래서 커넥터가 실어 보낸다. 보내지 않으면 총평은 분모 없이
+   * 옮긴 수만 말한다 — **지어내지 않는다.**
+   *
+   * 열쇠는 총평이 세는 이름과 같다(`recipes`·`materials`·`totalInputs`·…). 값은 **원본을 끝까지 읽어서
+   * 센 것**이어야 한다. 잘린 읽기의 수를 여기 담으면 「전부 옮겼다」는 거짓이 된다.
+   */
+  originCounts?: Record<string, number>
 }
 
 export interface IngestedTwin {
@@ -471,7 +511,7 @@ export function utcOffsetOf(timezone?: string, at: Date = new Date()): number |
     const sign = m[1] === '-' ? -1 : 1
     return sign * (Number(m[2]) * 60 + Number(m[3] ?? 0))
   } catch {
-    return undefined // 알 수 없는 이름 — Intl 이 던진다
+    return undefined // 알 수 없는 이름 — Intl 이 오류를 낸다
   }
 }
 
@@ -524,13 +564,37 @@ export const generationWithoutTimeZone = (spaceId: string, equipmentId: string):
     'so the generation peak will not land at local noon. Declare the space time zone (we do not guess one).'
 })
 
-/** 커널 카탈로그가 모르는 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다. */
+/**
+ * 아무도 선언하지 않은 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다.
+ *
+ * **묻는 상대를 고쳤다 (2026-08-20).** 예전에는 내장 카탈로그에게만 물었다. 그런데 원본이 자기
+ * `DomainDefinition.locationTypes` 를 함께 보내면 **그 선언이 정본**이다 — 카탈로그는 우리가 아는
+ * 도메인들의 기본 어휘일 뿐이다. 물을 상대가 틀렸으니, 자기 어휘를 선언한 원본은 정상적인 타입마다
+ * 경고를 받았다(F&B 라인을 붙이면 자리마다 하나씩). 소음이 되면 사람은 경고를 읽지 않게 되고, 그때
+ * 진짜 경고도 함께 죽는다.
+ */
 export const unknownLocationType = (system: string, type: string, id: string): IngestWarning => ({
   code: 'unknown-location-type',
   params: { system, type, id },
-  message: `"${type}" is not a known ${system} location type (${id}) — the kernel may not include this location in the flow`
+  message:
+    `"${type}" is declared nowhere for ${system} (${id}) — neither in the master's own locationTypes nor in the built-in ` +
+    `catalog, so the kernel may not include this location in the flow`
 })
 
+/**
+ * 원본이 함께 보낸 자리 타입 선언 — 있으면 **이것이 정본**이다.
+ *
+ * 커널 계약의 `DomainDefinition.locationTypes` 는 `{ key, label, … }` 목록이다. 읽을 수 없는 모양이면
+ * `undefined` 를 돌려 **카탈로그로 떨어진다** — 빈 배열을 돌려주면 「아무 타입도 선언되지 않았다」가
+ * 되어 모든 자리가 경고를 받는다(없는 것과 못 읽은 것은 다르다).
+ */
+export function declaredLocationTypes(productionSpec: unknown): string[] | undefined {
+  const list = (productionSpec as any)?.definition?.locationTypes
+  if (!Array.isArray(list) || !list.length) return undefined
+  const keys = list.map((t: any) => (typeof t === 'string' ? t : t?.key)).filter((k: any) => typeof k === 'string' && k)
+  return keys.length ? keys : undefined
+}
+
 /** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
 export const unknownTimezone = (timezone: string): IngestWarning => ({
   code: 'unknown-timezone',
@@ -638,7 +702,11 @@ export const siteEquipmentAdopted = (key: string, count: number): IngestWarning
 export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTwin {
   /* 커넥터가 옮기며 알게 된 것을 먼저 싣는다 — 원인이 앞에 오는 편이 읽기 쉽다(대체가 먼저, 그 결과가 뒤). */
   const warnings: IngestWarning[] = [...(master.warnings ?? [])]
-  const known: string[] = catalog?.[master.system]?.locationTypes ?? []
+  /*
+   * 원본이 자기 어휘를 선언했으면 **그것에 대조한다.** 내장 카탈로그는 그 선언이 없을 때의 기본이다 —
+   * 상대를 바꾸지 않으면, 자기 어휘를 선언한 원본이 정상적인 자리마다 경고를 받는다.
+   */
+  const known: string[] = declaredLocationTypes(master.productionSpec) ?? catalog?.[master.system]?.locationTypes ?? []
 
   const locationEntries = master.locations.filter(l => l.role === 'location' || l.role === 'both')
   const areaLocs = master.locations.filter(l => l.role === 'area' || l.role === 'both')
@@ -740,6 +808,8 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
     locations, equipment, layout, spaceId,
     /* 생산 정의도 손대지 않고 통과 — 경계에서 어휘를 갈지 않는다(커널이 그대로 소비한다). */
     ...(master.productionSpec ? { productionSpec: master.productionSpec } : {}),
+    /* 정체성 선언도 그대로 통과한다 — 없으면 만들지 않는다(커널이 레거시 상수로 떨어진다). */
+    ...(master.identity ? { identity: master.identity } : {}),
     ...(materialDefinitions?.length ? { materialDefinitions } : {}),
     ...(materialClasses?.length ? { materialClasses } : {}),
     ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),